diff --git a/.github/workflows/openapi-lint.yml b/.github/workflows/openapi-lint.yml
index affbe288e..4a556efb3 100644
--- a/.github/workflows/openapi-lint.yml
+++ b/.github/workflows/openapi-lint.yml
@@ -1,9 +1,11 @@
 name: Lint OpenAPI specs
 
 # Quality gate for the public API reference. Fails on undocumented schema
-# properties, epoch time fields without Unix/timestamp wording, string enums
-# whose values are not explained in the description, and operations without
-# request/response examples. See scripts/lint_openapi.py for the rules.
+# properties, epoch time fields without Unix/timestamp wording, enums whose
+# values are not explained in the description, `required` entries that name
+# undeclared properties, operations without examples or a 403 response,
+# examples that do not match their schema, and over-long operation
+# descriptions. See scripts/lint_openapi.py for the rules.
 
 on:
   pull_request:
diff --git a/api-reference/monitors.openapi.en.json b/api-reference/monitors.openapi.en.json
index c64821fe2..de1407dba 100644
--- a/api-reference/monitors.openapi.en.json
+++ b/api-reference/monitors.openapi.en.json
@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Flashduty Open API",
-    "description": "Public HTTP API for the Flashduty incident management platform — incidents, notification templates, channels, schedules, monitors, RUM, and platform administration. Every operation is authenticated with an `app_key` query parameter issued from the Flashduty console under Account → APP Keys. Responses follow a uniform envelope: `{ request_id, data }` on success, `{ request_id, error }` on failure.",
+    "description": "Public HTTP API for the Flashduty incident management platform — incidents, notification templates, channels, schedules, monitors, RUM, and platform administration. Every operation is authenticated with an `app_key` query parameter created in the Flashduty console under My → APP Key (or sent in the `Fd-App-Key` header). Responses follow a uniform envelope: `{ request_id, data }` on success, `{ request_id, error }` on failure.",
     "version": "1.0.0"
   },
   "servers": [
@@ -52,7 +52,7 @@
           "Monitors/Alert rules"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Alerting Rules Read** (`monit`) |\n\n## Usage\n\n- Each item is a historical snapshot: `num` is the total rule count at the given `clock` (Unix epoch seconds).",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Monits Overview Read** (`monit`) |\n\n## Usage\n\n- Each item is a historical snapshot: `num` is the total number of alert rules in the account (enabled and disabled) at `clock` (Unix timestamp in seconds).\n- A snapshot is recorded roughly every 12 hours (an hourly job adds one when none exists in the last 12 hours). All snapshots are returned oldest first; the array is empty until the first snapshot is recorded.",
           "href": "/en/api-reference/monitors/alert-rules/monit-rule-read-counter-total",
           "metadata": {
             "sidebarTitle": "Get rule counter time series"
@@ -83,7 +83,13 @@
                   "data": [
                     {
                       "id": 1,
-                      "account_id": 10023,
+                      "account_id": 888,
+                      "num": 48,
+                      "clock": 1711956000
+                    },
+                    {
+                      "id": 2,
+                      "account_id": 888,
                       "num": 50,
                       "clock": 1712000000
                     }
@@ -98,6 +104,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -122,12 +131,12 @@
       "post": {
         "operationId": "monit-datasource-write-create",
         "summary": "Create datasource",
-        "description": "Create a new monitoring data source. The `payload` must include the type-specific configuration block. Supports diagnostic types redis_node, redis_sentinel, mongodb_mongod, mongodb_mongos and kafka; enabled and alerting_enabled are independent.",
+        "description": "Create a monitoring datasource of one of 15 supported types and bind it to a Monitors edge cluster.",
         "tags": [
           "Monitors/Data sources"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Datasources Manage** (`monit`) |\n\n## Usage\n\n- `type_ident` must be one of: `prometheus`, `loki`, `mysql`, `oracle`, `postgres`, `clickhouse`, `elasticsearch`, `sls`, `tencent_cls`, `victorialogs`, `redis_node`, `redis_sentinel`, `mongodb_mongod`, `mongodb_mongos`, `kafka`.\n- `edge_cluster_name` specifies which Monitors edge cluster evaluates rules using this datasource.\n- For `elasticsearch`, set `payload.elasticsearch.deployment` to `cloud` or `self-managed`.\n- Every call is recorded in the account audit log. Use credential fields only for connection credentials.\n\nSee the request/response schemas for all supported types and credential handling. Diagnostic-only types cannot enable alerting. On create omitted enabled defaults to true; on update omission preserves the current value. Explicit null for enabled or alerting_enabled is invalid. Diagnostic passwords and Kafka private keys are omitted from responses unless they are environment references; omit these secrets on update to preserve them, or send an empty string to clear. Other datasource credentials may be returned and must be handled as sensitive.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Datasources Manage** (`monit`) |\n\n## Usage\n\n- `type_ident` must be one of: `prometheus`, `loki`, `mysql`, `oracle`, `postgres`, `clickhouse`, `elasticsearch`, `sls`, `tencent_cls`, `victorialogs`, `redis_node`, `redis_sentinel`, `mongodb_mongod`, `mongodb_mongos`, `kafka`. The last five (`redis_node`, `redis_sentinel`, `mongodb_mongod`, `mongodb_mongos`, `kafka`) are diagnostic-only: they cannot evaluate alerts, so `alerting_enabled` must not be `true`.\n- `name` must be unique within the account across all types; a duplicate fails with `InvalidParameter`.\n- `edge_cluster_name` must be an existing Monitors edge cluster of the account; that cluster evaluates rules and runs queries for the datasource.\n- Put the type-specific settings in `payload.<type_ident>`. For `elasticsearch`, `payload.elasticsearch.deployment` is required (`cloud` or `self-managed`). `tencent_cls` requires every edge instance in the cluster to run Monitors edge v0.66.0 or later.\n- Omitted `enabled` defaults to `true`; omitted `alerting_enabled` defaults to `true` for alerting types and `false` for diagnostic-only types. Explicit `null` for either is rejected.\n- `manage_team_id` and `readonly_team_ids` restrict who can manage or query the datasource; omit both to leave it open to every member.\n- Responses return credentials of non-diagnostic types (for example Prometheus Basic Auth passwords) as stored. Diagnostic passwords and Kafka private keys are returned only when they are `${env:NAME}` references. Treat responses as sensitive.\n- Every call is recorded in the account audit log.",
           "href": "/en/api-reference/monitors/data-sources/monit-datasource-write-create",
           "metadata": {
             "sidebarTitle": "Create datasource"
@@ -157,12 +166,26 @@
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "id": 10,
+                    "account_id": 10023,
                     "type_ident": "prometheus",
                     "name": "Prometheus Prod",
                     "enabled": true,
+                    "note": "Production Prometheus",
+                    "address": "http://prometheus.example.com:9090",
+                    "payload": {
+                      "prometheus": {
+                        "basic_auth_enabled": false,
+                        "basic_auth_username": "",
+                        "basic_auth_password": "",
+                        "tls_skip_verify": false
+                      }
+                    },
                     "edge_cluster_name": "default",
                     "updated_at": 1712000000,
-                    "alerting_enabled": true
+                    "alerting_enabled": true,
+                    "manage_team_id": null,
+                    "readonly_team_ids": null,
+                    "creator_id": 20001
                   }
                 }
               }
@@ -174,6 +197,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -209,12 +235,12 @@
       "post": {
         "operationId": "monit-datasource-write-update",
         "summary": "Update datasource",
-        "description": "Update an existing data source. Supply `id` plus the fields to change. Supports diagnostic types redis_node, redis_sentinel, mongodb_mongod, mongodb_mongos and kafka; enabled and alerting_enabled are independent.",
+        "description": "Update a datasource by ID, replacing its name, note, address, payload and edge cluster.",
         "tags": [
           "Monitors/Data sources"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Datasources Manage** (`monit`) |\n\n## Usage\n\n- Every call is recorded in the account audit log. Use credential fields only for connection credentials.\n\nSee the request/response schemas for all supported types and credential handling. Diagnostic-only types cannot enable alerting. On create omitted enabled defaults to true; on update omission preserves the current value. Explicit null for enabled or alerting_enabled is invalid. Diagnostic passwords and Kafka private keys are omitted from responses unless they are environment references; omit these secrets on update to preserve them, or send an empty string to clear. Other datasource credentials may be returned and must be handled as sensitive.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Datasources Manage** (`monit`) |\n\n## Usage\n\n- This is a full replace, not a patch: send `type_ident`, `name`, `edge_cluster_name`, `payload` and (except for Elasticsearch `cloud`) `address` on every call. `note`, `address` and `payload` overwrite the stored values, so an omitted `note` is cleared.\n- Omitting `enabled`, `alerting_enabled`, `manage_team_id` or `readonly_team_ids` keeps the current value. `null` for `enabled` or `alerting_enabled` is rejected; `null` for the two team fields clears them.\n- Secrets: for the diagnostic types, omit the password (and the Kafka `tls_key`) to keep the stored value or send an empty string to clear it. For `tencent_cls`, an omitted or empty `secret_key` keeps the stored key. Other types need their credentials resent.\n- Setting `enabled` or `alerting_enabled` to `false`, or changing `type_ident` or `edge_cluster_name`, closes open alerts of the rules that use this datasource. Renaming it closes open alerts of rules whose `ds_list` name pattern no longer matches the new name.\n- Turning `alerting_enabled` off fails with HTTP 409 `UndonedOrderExist` while an enabled alert rule still selects the datasource.\n- Only the account owner, Admin members, the creator and members of the managing team can update a datasource (anyone with the permission when no managing team is set); others get `AccessDenied`. An unknown ID, or one in another account, returns `ResourceNotFound`.\n- Every call is recorded in the account audit log.",
           "href": "/en/api-reference/monitors/data-sources/monit-datasource-write-update",
           "metadata": {
             "sidebarTitle": "Update datasource"
@@ -244,12 +270,26 @@
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "id": 10,
+                    "account_id": 10023,
                     "type_ident": "prometheus",
                     "name": "Prometheus Prod v2",
                     "enabled": true,
+                    "note": "Updated",
+                    "address": "http://prometheus-v2.example.com:9090",
+                    "payload": {
+                      "prometheus": {
+                        "basic_auth_enabled": false,
+                        "basic_auth_username": "",
+                        "basic_auth_password": "",
+                        "tls_skip_verify": false
+                      }
+                    },
                     "edge_cluster_name": "default",
                     "updated_at": 1712100000,
-                    "alerting_enabled": true
+                    "alerting_enabled": true,
+                    "manage_team_id": null,
+                    "readonly_team_ids": null,
+                    "creator_id": 20001
                   }
                 }
               }
@@ -261,6 +301,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -302,7 +345,7 @@
           "Monitors/Alert rules"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Alerting Rules Manage** (`monit`) |\n\n## Usage\n\n- Rules whose names already exist in the destination folder are skipped. Inspect each result's `message` to identify conflicts.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Alerting Rules Manage** (`monit`) |\n\n## Usage\n\n- `dest_folder_id` must be an existing folder that the caller must be able to manage the folder (account owner or admin, creator of the folder or one of its ancestors, or member of the team bound to the folder or an ancestor); otherwise the whole call fails with `AccessDenied` and nothing is moved.\n- The result has one entry per requested ID, in request order. A moved rule's `message` is a localized success text (`Move successfully` / `移动成功`); a rule that is not moved stays in its folder and its `message` carries the error.\n- A rule is not moved when a rule with the same name already exists in the destination folder, when the caller cannot manage its current folder, or when the ID does not exist (its `name` is then `id: <id>`).\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/monitors/alert-rules/monit-rule-write-move",
           "metadata": {
             "sidebarTitle": "Move alert rules to folder"
@@ -333,7 +376,11 @@
                   "data": [
                     {
                       "name": "CPU High",
-                      "message": ""
+                      "message": "Move successfully"
+                    },
+                    {
+                      "name": "Disk High",
+                      "message": "alert rule name already exists in this folder"
                     }
                   ]
                 }
@@ -346,6 +393,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -376,12 +426,12 @@
       "post": {
         "operationId": "monit-rule-read-audit-detail",
         "summary": "Get rule audit snapshot",
-        "description": "Return the audit record (including the `content` field, a JSON string of the rule snapshot at that point in time).",
+        "description": "Return one audit record of an alert rule, including the rule snapshot stored in `content`.",
         "tags": [
           "Monitors/Alert rules"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Alerting Rules Read** (`monit`) |\n\n## Usage\n\n- Pass the audit record `id` (not the rule `id`) from `POST /monit/rule/audits`.\n- `content` is a JSON string — parse it to get the full rule snapshot.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Pass the audit record `id` (not the rule `id`) from `POST /monit/rule/audits`. An unknown ID returns `InvalidParameter` (`alert rule audit not found`).\n- `content` is a JSON string — parse it to get the rule snapshot; its shape depends on the operation that wrote the record (see `content` below).\n- To read a record, the caller must be able to manage the rule's folder (account owner or admin, creator of the folder or one of its ancestors, or member of the team bound to the folder or an ancestor); otherwise the call returns `AccessDenied`. Records of a deleted rule can no longer be read: the call returns `InvalidParameter` (`alert rule not found`).",
           "href": "/en/api-reference/monitors/alert-rules/monit-rule-read-audit-detail",
           "metadata": {
             "sidebarTitle": "Get rule audit snapshot"
@@ -411,13 +461,13 @@
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "id": 9001,
-                    "account_id": 10023,
+                    "account_id": 888,
                     "alert_rule_id": 50001,
                     "action": "update",
-                    "content": "{\"id\":50001,\"name\":\"CPU High\"}",
-                    "creator_id": 80011,
-                    "creator_name": "Alice",
-                    "created_at": 1712000000
+                    "content": "{\"id\":50001,\"account_id\":888,\"folder_id\":100,\"name\":\"CPU High\",\"enabled\":true,\"updated_at\":1712003600}",
+                    "creator_id": 66,
+                    "creator_name": "zhangsan",
+                    "created_at": 1712003600
                   }
                 }
               }
@@ -429,6 +479,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -455,12 +508,12 @@
       "post": {
         "operationId": "monit-datasource-write-delete",
         "summary": "Delete datasource",
-        "description": "Delete a data source by ID. Alert rules referencing this datasource are not blocked: the datasource is removed from their monitoring scope and their open alerts on it are closed automatically.",
+        "description": "Delete a datasource by ID; alert rules that reference it are not blocked.",
         "tags": [
           "Monitors/Data sources"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Datasources Manage** (`monit`) |\n\n## Usage\n\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Datasources Manage** (`monit`) |\n\n## Usage\n\n- Alert rules that reference the datasource are not blocked or edited; their open alerts on it are closed automatically.\n- Deleting an ID that does not exist succeeds as a no-op; an ID in another account returns `ResourceNotFound`.\n- Only the account owner, Admin members, the creator and members of the managing team can delete a datasource (anyone with the permission when no managing team is set); others get `AccessDenied`.\n- Every call is recorded in the account audit log.",
           "href": "/en/api-reference/monitors/data-sources/monit-datasource-write-delete",
           "metadata": {
             "sidebarTitle": "Delete datasource"
@@ -499,6 +552,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -530,7 +586,7 @@
           "Monitors/Alert rules"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **30 requests/minute**; **5 requests/second** per account |\n| Permissions | **Alerting Rules Manage** (`monit`) |\n\n## Usage\n\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **100 requests/minute**; **5 requests/second** per account |\n| Permissions | **Alerting Rules Manage** (`monit`) |\n\n## Usage\n\n- IDs are processed in order and the call stops at the first error; rules deleted before the error stay deleted, so fix the cause and re-send the remaining IDs.\n- IDs that do not exist are skipped without error. Each deleted rule's active alerts are cleared.\n- `ids` must contain at least one ID. For every rule, the caller must be able to manage its folder (account owner or admin, creator of the folder or one of its ancestors, or member of the team bound to the folder or an ancestor); otherwise the call returns `AccessDenied`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/monitors/alert-rules/monit-rule-write-delete-batch",
           "metadata": {
             "sidebarTitle": "Batch delete alert rules"
@@ -569,6 +625,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -603,7 +662,7 @@
           "Monitors/Data sources"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Datasources Read** (`monit`) |\n\n## Usage\n\n- The datasource identified by `id` must be of type `sls`.\n- Use `query` to filter projects by name prefix. Use `offset` and `size` for pagination.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Datasources Read** (`monit`) |\n\n## Usage\n\n- The datasource identified by `id` must be of type `sls`; other types fail with `InvalidParameter`.\n- Use `query` to filter the project list and `offset` and `size` to paginate; `count` is the number of projects in the page and `total` the number matching the filter.\n- The request is relayed to the Monitors edge cluster of the datasource, which calls Alibaba Cloud with the stored credentials; it times out after 30 seconds. Fails with `InvalidParameter` when no edge instance of that cluster is online, and with HTTP 503 `ServiceUnavailable` when the edge version does not support metadata discovery.",
           "href": "/en/api-reference/monitors/data-sources/monit-datasource-read-sls-projects",
           "metadata": {
             "sidebarTitle": "List SLS projects"
@@ -665,6 +724,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -699,7 +761,7 @@
           "Monitors/Data sources"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Datasources Read** (`monit`) |\n\n## Usage\n\n- The datasource identified by `id` must be of type `sls`.\n- Supply `project` to select the SLS project whose logstores to list.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Datasources Read** (`monit`) |\n\n## Usage\n\n- The datasource identified by `id` must be of type `sls`; other types fail with `InvalidParameter`.\n- Supply `project` to select the SLS project whose logstores to list; use `offset` and `size` to paginate. The response is a plain array of logstore names.\n- The request is relayed to the Monitors edge cluster of the datasource, which calls Alibaba Cloud with the stored credentials; it times out after 30 seconds. Fails with `InvalidParameter` when no edge instance of that cluster is online, and with HTTP 503 `ServiceUnavailable` when the edge version does not support metadata discovery.",
           "href": "/en/api-reference/monitors/data-sources/monit-datasource-read-sls-logstores",
           "metadata": {
             "sidebarTitle": "List SLS logstores"
@@ -741,6 +803,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -770,12 +835,12 @@
       "post": {
         "operationId": "monit-datasource-read-info",
         "summary": "Get datasource detail",
-        "description": "Retrieve full details of a single data source by its ID, including the `payload` configuration with its configured connection and authentication settings; treat the response as sensitive and avoid logging or forwarding it. Supports diagnostic types redis_node, redis_sentinel, mongodb_mongod, mongodb_mongos and kafka; enabled and alerting_enabled are independent.",
+        "description": "Return one datasource by ID, including its full `payload` configuration.",
         "tags": [
           "Monitors/Data sources"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Datasources Read** (`monit`) |\n\nSee the request/response schemas for all supported types and credential handling. Diagnostic-only types cannot enable alerting. On create omitted enabled defaults to true; on update omission preserves the current value. Explicit null for enabled or alerting_enabled is invalid. Diagnostic passwords and Kafka private keys are omitted from responses unless they are environment references; omit these secrets on update to preserve them, or send an empty string to clear. Other datasource credentials may be returned and must be handled as sensitive.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Datasources Read** (`monit`) |\n\n## Usage\n\n- Requires manage access to the datasource (see `manage_team_id`); members who can only query it get `AccessDenied`. Use `/monit/datasource/list` for the datasources you can query.\n- The response is sensitive: `payload` holds connection settings, and credentials of non-diagnostic types are returned as stored. Diagnostic passwords and Kafka private keys are returned only when they are `${env:NAME}` references; `tencent_cls` `secret_key` is returned as an empty string unless it is a `${env:NAME}` reference.\n- An unknown ID, or one in another account, returns `ResourceNotFound`.",
           "href": "/en/api-reference/monitors/data-sources/monit-datasource-read-info",
           "metadata": {
             "sidebarTitle": "Get datasource detail"
@@ -821,7 +886,10 @@
                     },
                     "edge_cluster_name": "default",
                     "updated_at": 1712000000,
-                    "alerting_enabled": true
+                    "alerting_enabled": true,
+                    "manage_team_id": null,
+                    "readonly_team_ids": null,
+                    "creator_id": 20001
                   }
                 }
               }
@@ -833,6 +901,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -864,7 +935,7 @@
           "Monitors/Alert rules"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Alerting Rules Read** (`monit`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Records are ordered newest first and omit `content`; read one snapshot with `POST /monit/rule/audit/detail`.\n- A record is written on every create, full update, field update and move. Deleting a rule writes no record, and the history of a deleted rule can no longer be listed: the call returns `InvalidParameter` (`alert rule not found`).\n- The caller must be able to manage the rule's folder (account owner or admin, creator of the folder or one of its ancestors, or member of the team bound to the folder or an ancestor); otherwise the call returns `AccessDenied`.",
           "href": "/en/api-reference/monitors/alert-rules/monit-rule-read-audits",
           "metadata": {
             "sidebarTitle": "List rule change history"
@@ -895,11 +966,20 @@
                   "data": [
                     {
                       "id": 9001,
-                      "account_id": 10023,
+                      "account_id": 888,
                       "alert_rule_id": 50001,
                       "action": "update",
-                      "creator_id": 80011,
-                      "creator_name": "Alice",
+                      "creator_id": 66,
+                      "creator_name": "zhangsan",
+                      "created_at": 1712003600
+                    },
+                    {
+                      "id": 8990,
+                      "account_id": 888,
+                      "alert_rule_id": 50001,
+                      "action": "create",
+                      "creator_id": 66,
+                      "creator_name": "zhangsan",
                       "created_at": 1712000000
                     }
                   ]
@@ -913,6 +993,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -944,7 +1027,7 @@
           "Monitors/Alert rules"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Alerting Rules Manage** (`monit`) |\n\n## Usage\n\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Alerting Rules Manage** (`monit`) |\n\n## Usage\n\n- The rule's active alerts are cleared as part of the deletion.\n- Deleting an ID that does not exist succeeds with an empty `data`, so retries are safe.\n- The caller must be able to manage the rule's folder (account owner or admin, creator of the folder or one of its ancestors, or member of the team bound to the folder or an ancestor); otherwise the call returns `AccessDenied`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/monitors/alert-rules/monit-rule-write-delete",
           "metadata": {
             "sidebarTitle": "Delete alert rule"
@@ -983,6 +1066,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -1009,12 +1095,12 @@
       "post": {
         "operationId": "monit-rule-read-list",
         "summary": "List alert rules",
-        "description": "Return the basic information of all alert rules in a folder. For full rule details, call `POST /monit/rule/v2/info`.",
+        "description": "Return basic information for the alert rules in a folder; call `POST /monit/rule/v2/info` for full details.",
         "tags": [
           "Monitors/Alert rules"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Alerting Rules Read** (`monit`) |\n\n## Usage\n\n- Set `folder_id` to `0` to list all rules across all folders visible to the current user.\n- The `triggered` field indicates whether the rule has any currently active alerts.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Alerting Rules Read** or **Alerting Rules Manage** (`monit`) |\n\n## Usage\n\n- `folder_id` must be an existing folder: `0` or an unknown ID returns `InvalidParameter`, and a folder the caller cannot manage (account owner or admin, creator of the folder or an ancestor, or member of the team bound to it or an ancestor) returns `AccessDenied`. There is no account-wide listing.\n- By default only the rules directly in the folder are returned, sorted by name, with `active_alert_count` and `runtime_state` filled.\n- With `include_descendants: true` the call searches the folder and all its descendant folders and returns at most `limit` rules sorted by name; only `id`, `folder_id` and `name` are filled and the other fields carry zero values (`labels` is `null`, `runtime_state` is omitted).\n- `triggered` is `true` exactly when `active_alert_count > 0`.",
           "href": "/en/api-reference/monitors/alert-rules/monit-rule-read-list",
           "metadata": {
             "sidebarTitle": "List alert rules"
@@ -1045,12 +1131,25 @@
                   "data": [
                     {
                       "id": 50001,
+                      "account_id": 888,
                       "folder_id": 100,
                       "name": "CPU High",
+                      "labels": {
+                        "team": "sre"
+                      },
                       "ds_type": "prometheus",
                       "enabled": true,
-                      "triggered": true,
+                      "debug_log_enabled": false,
+                      "cron_pattern": "0 * * * * *",
+                      "timezone": "Asia/Shanghai",
+                      "delay_seconds": 0,
+                      "creator_id": 66,
+                      "creator_name": "zhangsan",
+                      "updater_id": 66,
+                      "updater_name": "zhangsan",
                       "created_at": 1710000000,
+                      "updated_at": 1712000000,
+                      "triggered": true,
                       "active_alert_count": 2,
                       "runtime_state": "normal"
                     }
@@ -1065,6 +1164,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -1091,12 +1193,12 @@
       "post": {
         "operationId": "monit-datasource-read-list",
         "summary": "List datasources",
-        "description": "Return all data sources for the current account. Optionally filter by `type_ident`. Supports diagnostic types redis_node, redis_sentinel, mongodb_mongod, mongodb_mongos and kafka; enabled and alerting_enabled are independent.",
+        "description": "List the account's datasources that the caller can query, optionally filtered by type or exact name.",
         "tags": [
           "Monitors/Data sources"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Datasources Read** (`monit`) |\n\n## Usage\n\n- Omit `type_ident` to return all types.\n- Sensitive credential fields (passwords, keys) are not returned in the list response.\n\nSee the request/response schemas for all supported types and credential handling. Diagnostic-only types cannot enable alerting. On create omitted enabled defaults to true; on update omission preserves the current value. Explicit null for enabled or alerting_enabled is invalid. Diagnostic passwords and Kafka private keys are omitted from responses unless they are environment references; omit these secrets on update to preserve them, or send an empty string to clear. Other datasource credentials may be returned and must be handled as sensitive.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Datasources Read** (`monit`) |\n\n## Usage\n\n- Omit `type` and `name` to return every datasource you can query; `type` and `name` are exact-match filters. An unrecognized `type` returns an empty array. The result is not paginated.\n- Only datasources the caller can query are returned (see `readonly_team_ids`); each item carries `my_perm` (`manage` or `readonly`).\n- `payload` is always `null` in list items. Use `/monit/datasource/info` to read the configuration of a datasource you can manage.",
           "href": "/en/api-reference/monitors/data-sources/monit-datasource-read-list",
           "metadata": {
             "sidebarTitle": "List datasources"
@@ -1133,10 +1235,14 @@
                       "enabled": true,
                       "note": "Production Prometheus",
                       "address": "http://prometheus.example.com:9090",
+                      "payload": null,
                       "edge_cluster_name": "default",
                       "updated_at": 1712000000,
-                      "payload": null,
-                      "alerting_enabled": true
+                      "alerting_enabled": true,
+                      "manage_team_id": null,
+                      "readonly_team_ids": null,
+                      "creator_id": 20001,
+                      "my_perm": "manage"
                     }
                   ]
                 }
@@ -1149,6 +1255,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -1175,12 +1284,12 @@
       "post": {
         "operationId": "monit-rule-write-fields-update",
         "summary": "Batch update rule fields",
-        "description": "Update specific fields across multiple alert rules at once. Only the fields listed in `fields` are applied.",
+        "description": "Update the fields listed in `fields` on multiple alert rules in one call.",
         "tags": [
           "Monitors/Alert rules"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Alerting Rules Manage** (`monit`) |\n\n## Usage\n\n- Include the field names you want to update in the `fields` array, e.g. `[\"enabled\", \"channel_ids\"]`.\n- Only the specified fields are updated; others are left unchanged.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Alerting Rules Manage** (`monit`) |\n\n## Usage\n\n- Each listed field takes the value of the same-named request field; a listed field whose value is omitted is set to its zero value (for example, listing `labels` without `labels` or `labels_patch` removes all labels). Unlisted fields keep their current values.\n- An unknown name in `fields`, a `labels_patch` / `annotations_patch` whose field is not listed in `fields`, or sending `labels` together with `labels_patch` (or `annotations` with `annotations_patch`) fails the whole call with `InvalidParameter`.\n- Rules are updated one by one and the result has one entry per ID: `message` is empty on success, otherwise it carries that rule's error (validation failure, no access to its folder, or an unknown ID, whose `name` is then `id: <id>`).\n- Setting `enabled` to `false` clears the rules' active alerts. Unless the call only disables rules (`fields` is exactly `[\"enabled\"]` with `enabled: false`), it fails with `AccessDenied` when the account exceeds its alert rule license limit, and non-admin callers need read-only access to every datasource each rule selects.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/monitors/alert-rules/monit-rule-write-fields-update",
           "metadata": {
             "sidebarTitle": "Batch update rule fields"
@@ -1228,6 +1337,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -1261,12 +1373,12 @@
       "post": {
         "operationId": "monit-rule-read-counter-channel",
         "summary": "Get rule counts by channel",
-        "description": "Return an object mapping channel name to the number of rules routing alerts to that channel. If a channel name cannot be resolved, the channel ID (as a string) is used as the key.",
+        "description": "Return how many alert rules route alerts to each collaboration space, keyed by space name.",
         "tags": [
           "Monitors/Alert rules"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Alerting Rules Read** (`monit`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Monits Overview Read** (`monit`) |\n\n## Usage\n\n- Only rules with a non-empty `channel_ids` are counted; a rule routed to several spaces is counted once under each of them.\n- When a space ID cannot be resolved to a name, the ID (as a string) is used as the key. Spaces that share the same name are merged into one key.\n- Returns an empty object `{}` when no rule routes to a space.",
           "href": "/en/api-reference/monitors/alert-rules/monit-rule-read-counter-channel",
           "metadata": {
             "sidebarTitle": "Get rule counts by channel"
@@ -1307,6 +1419,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -1336,7 +1451,7 @@
           "Monitors/Alert rules"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Alerting Rules Read** (`monit`) |\n\n## Usage\n\n- `id` is required and must not be `0`; otherwise the call returns `InvalidParameter`.\n- A missing rule returns `InvalidParameter` (`alert rule not found`).",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Alerting Rules Read** or **Alerting Rules Manage** (`monit`) |\n\n## Usage\n\n- `id` is required and must not be `0`; otherwise the call returns `InvalidParameter`.\n- A missing rule, or a rule of another account, returns `InvalidParameter` (`alert rule not found`).\n- No folder-level check applies: any caller with the permission above can read every rule in the account.",
           "href": "/en/api-reference/monitors/alert-rules/monit-rule-read-info-v2",
           "metadata": {
             "sidebarTitle": "Get alert rule detail (V2)"
@@ -1378,6 +1493,7 @@
                     "enabled": true,
                     "debug_log_enabled": false,
                     "rule_configs": {
+                      "relate_queries": [],
                       "queries": [
                         {
                           "name": "A",
@@ -1438,6 +1554,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -1469,7 +1588,7 @@
           "Monitors/Alert rules"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Alerting Rules Manage** (`monit`) |\n\n## Usage\n\n- `name`, `ds_type`, `enabled`, `cron_pattern`, and `rule_configs.queries` are required; either `ds_list` (supports wildcards) or `ds_ids` must be non-empty.\n- `enabled` must be passed explicitly (including `false`); omitting it returns `InvalidParameter`.\n- `id`, `account_id`, `creator_*`, `updater_*`, `created_at`, and `updated_at` are assigned by the server; client-supplied values are ignored.\n- `name` must be unique within `folder_id`; a duplicate returns `InvalidParameter`.\n- `channel_ids` can be empty; alerts will then route through the global integration.\n- The request body tolerates additional unknown fields (forward compatibility); they are ignored.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Alerting Rules Manage** (`monit`) |\n\n## Usage\n\n- `folder_id`, `name`, `ds_type`, `enabled`, `cron_pattern` and `rule_configs.queries` are required, and at least one of `ds_list` (wildcards supported) or `ds_ids` must be non-empty.\n- `enabled` must be passed explicitly (including `false`); omitting it returns `InvalidParameter`.\n- `folder_id` must be an existing folder (otherwise `InvalidParameter`) and the caller must be able to manage the folder (account owner or admin, creator of the folder or one of its ancestors, or member of the team bound to the folder or an ancestor) (otherwise `AccessDenied`).\n- `name` must be unique within `folder_id`; a duplicate returns `InvalidParameter`.\n- When `enabled` is `true`, `ds_type` must be a datasource type that supports alerting and every ID in `ds_ids` must be an enabled datasource with alerting turned on; otherwise the call returns `InvalidParameter`.\n- Callers other than the account owner or admins need read-only access to every datasource listed in `ds_ids` or currently matched by `ds_list`; otherwise the call returns `AccessDenied` (`no permission to reference datasource \"<name>\"`).\n- The call fails with `AccessDenied` when creating the rule would exceed the account's alert rule license limit.\n- `id`, `account_id`, `creator_*`, `updater_*`, `created_at`, and `updated_at` are assigned by the server; client-supplied values are ignored.\n- `channel_ids` can be empty; alerts will then route through the global integration.\n- The request body may not exceed 1 MiB; a larger body returns HTTP 413 (`EntityTooLarge`). Additional unknown fields are ignored (forward compatibility).\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/monitors/alert-rules/monit-rule-write-create-v2",
           "metadata": {
             "sidebarTitle": "Create alert rule (V2)"
@@ -1511,6 +1630,7 @@
                     "enabled": true,
                     "debug_log_enabled": false,
                     "rule_configs": {
+                      "relate_queries": [],
                       "queries": [
                         {
                           "name": "A",
@@ -1571,6 +1691,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -1629,7 +1752,7 @@
           "Monitors/Alert rules"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Alerting Rules Manage** (`monit`) |\n\n## Usage\n\n- `id` is required and the rule must already exist; otherwise the call returns `InvalidParameter`.\n- This is a full-field replacement: except for the cases below, fields you omit are stored as zero values. Fetch the full configuration via `/monit/rule/v2/info` before modifying it.\n- `enabled` must be passed explicitly (including `false`); omitting it returns `InvalidParameter`. Setting it to `false` clears the rule's active alerts.\n- `investigation_targets` is the exception: omit it to keep the current value, pass `[]` to clear, or pass a value to replace it entirely.\n- `folder_id` cannot be changed through this operation; use `/monit/rule/move` to move the rule to another folder.\n- `account_id`, `creator_*`, `updater_*`, `created_at`, and `updated_at` are maintained by the server; client-supplied values are ignored.\n- `name` must be unique within `folder_id`; a duplicate returns `InvalidParameter`.\n- The request body tolerates additional unknown fields (forward compatibility); they are ignored.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Alerting Rules Manage** (`monit`) |\n\n## Usage\n\n- `id` is required and the rule must already exist; otherwise the call returns `InvalidParameter`.\n- This is a full-field replacement: except for the cases below, fields you omit are stored as zero values (then normalized, e.g. `repeat_interval` becomes 3600). Fetch the full configuration via `/monit/rule/v2/info` before modifying it.\n- `enabled` must be passed explicitly (including `false`); omitting it returns `InvalidParameter`. Setting it to `false` clears the rule's active alerts.\n- `investigation_targets` is the exception: omit it to keep the current value, pass `[]` to clear, or pass a value to replace it entirely.\n- `folder_id` cannot be changed through this operation; use `/monit/rule/move` to move the rule to another folder.\n- The caller must be able to manage the rule's folder (account owner or admin, creator of the folder or one of its ancestors, or member of the team bound to the folder or an ancestor); otherwise the call returns `AccessDenied`.\n- `name` must be unique within the rule's folder; a duplicate returns `InvalidParameter`.\n- When `enabled` is `true`, `ds_type` must be a datasource type that supports alerting and every ID in `ds_ids` must be an enabled datasource with alerting turned on; otherwise the call returns `InvalidParameter`.\n- Callers other than the account owner or admins need read-only access to every datasource listed in `ds_ids` or currently matched by `ds_list`; otherwise the call returns `AccessDenied` (`no permission to reference datasource \"<name>\"`).\n- The call fails with `AccessDenied` when the account already exceeds its alert rule license limit.\n- If the rule is modified by another request while this one is processed, the call returns HTTP 409 (`UndonedOrderExist`, `alert rule was modified; reload and retry`); fetch the rule again and retry.\n- `account_id`, `creator_*`, `updater_*`, `created_at`, and `updated_at` are maintained by the server; client-supplied values are ignored.\n- The request body may not exceed 1 MiB; a larger body returns HTTP 413 (`EntityTooLarge`). Additional unknown fields are ignored (forward compatibility).\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/monitors/alert-rules/monit-rule-write-update-v2",
           "metadata": {
             "sidebarTitle": "Update alert rule (V2)"
@@ -1671,6 +1794,7 @@
                     "enabled": true,
                     "debug_log_enabled": false,
                     "rule_configs": {
+                      "relate_queries": [],
                       "queries": [
                         {
                           "name": "A",
@@ -1731,6 +1855,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -1785,12 +1912,12 @@
       "post": {
         "operationId": "monit-read-query-data",
         "summary": "Query structured data",
-        "description": "Run a synchronous ad-hoc query against a configured data source and return a stable `query_result.v1` result whose natural shape is frames, records, or samples. This public API requires monit-edge v0.65.0 or later.",
+        "description": "Run a synchronous ad-hoc query against a data source and return a `query_result.v1` result as frames, records, or samples.",
         "tags": [
           "Monitors/Diagnostics"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **100 requests/minute**; **5 requests/second** per account |\n| Permissions | Any valid `app_key` (read-only; not gated by a specific permission class) |\n| Edge requirement | Supported deployments require **monit-edge v0.65.0 or later** |\n\n## Usage\n\n- Treat **monit-edge v0.65.0** as the minimum supported Edge version for this public API. WebAPI retains migration adapters for older Edge versions: query.v2 results may still preserve frames, records, or samples, while legacy rows can expose only the information they retained. These adapters do not change the support floor; older protocols lack query.v3 cancellation and error-lifecycle semantics, and data already lost by legacy rows cannot be recovered.\n- The public response format is always `query_result.v1` and is independent of the internal Edge query protocol. Dispatch on `result.kind` (`frames`, `records`, or `samples`); do not infer the result shape from `ds_type` or the Edge version.\n- A `frames` result may contain multiple table or time-series frames. Field values are columnar and all fields in one frame have the same length.\n- A `records` result may contain nested JSON and null records. Integer literals outside JavaScript's safe integer range are returned as decimal strings.\n- A `samples` result contains label sets and instant values. A value may be a number or one of the strings `NaN`, `+Inf`, and `-Inf`.\n- The final success response is limited to 8 MiB and query results are limited to 1,000 rows. Narrow the time range, reduce fields, or aggregate at the source when a request exceeds a limit.\n- Query failures use non-2xx HTTP status codes and the standard error envelope. Do not transparently fall back to the deprecated `/monit/query/rows` endpoint.\n- Query execution may take up to 35 seconds across WebAPI forwarding and Edge execution. Configure client timeouts to at least 40 seconds and propagate cancellation when the caller abandons a query.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **100 requests/minute**; **5 requests/second** per account |\n| Permissions | Any valid `app_key` (read-only; not gated by a specific permission class) |\n| Edge requirement | Supported deployments require **monit-edge v0.65.0 or later** |\n\n## Usage\n\n- The data source is identified by `ds_type` plus `ds_name`, not by ID. It must belong to the account and be enabled. When the data source restricts querying to certain teams, only members of those teams, its managing team, and account owners or admins can query it; others get `AccessDenied`.\n- Treat **monit-edge v0.65.0** as the minimum supported Edge version for this public API. WebAPI retains migration adapters for older Edge versions: query.v2 results may still preserve frames, records, or samples, while legacy rows can expose only the information they retained. These adapters do not change the support floor; older protocols lack query.v3 cancellation and error-lifecycle semantics, and data already lost by legacy rows cannot be recovered.\n- The public response format is always `query_result.v1` and is independent of the internal Edge query protocol. Dispatch on `result.kind` (`frames`, `records`, or `samples`); do not infer the result shape from `ds_type` or the Edge version.\n- A `frames` result may contain multiple table or time-series frames. Field values are columnar and all fields in one frame have the same length.\n- A `records` result may contain nested JSON and null records. Integer literals outside JavaScript's safe integer range are returned as decimal strings.\n- A `samples` result contains label sets and instant values. A value may be a number or one of the strings `NaN`, `+Inf`, and `-Inf`.\n- Prometheus expressions are syntax-checked before the query is dispatched; an invalid expression returns HTTP 400.\n- The request body is limited to 256 KiB and the complete success response to 10 MiB; either limit returns HTTP 413. A result with more than 1,000 rows fails with HTTP 400. Narrow the time range, reduce fields, or aggregate at the source.\n- Query failures use non-2xx HTTP status codes and the standard error envelope.\n- Query execution may take up to 35 seconds across WebAPI forwarding and Edge execution. Configure client timeouts to at least 40 seconds and propagate cancellation when the caller abandons a query.",
           "href": "/en/api-reference/monitors/diagnostics/monit-read-query-data",
           "metadata": {
             "sidebarTitle": "Query structured data"
@@ -1987,7 +2114,7 @@
                               {
                                 "labels": {
                                   "__name__": "up",
-                                  "instance": "10.101.214.50:7070"
+                                  "instance": "203.0.113.10:9090"
                                 },
                                 "value": 1
                               }
@@ -2111,7 +2238,7 @@
           "Monitors/Data sources"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **2,000 requests/minute**; **32 requests/second** per account |\n| Permissions | **Datasources Read** (`monit`) |\n\nUse datasource IDs from `/monit/datasource/list`. Disabled datasources return `datasource_disabled`; `alerting_enabled=false` does not block tools. Errors use non-2xx HTTP status and `error.code`, `error.message`, `error.reason`. `tool_not_supported` indicates the selected executor does not provide this tool; it is not a vendor permission error. Never retry through another Edge or the legacy diagnose endpoint automatically.\n\n## Usage\n\n- Two tool families share this entry: diagnostic tools defined by the executing Edge (e.g. `mysql.overview`, `prometheus.metric_trends`) and query tools named `<type>.query`. The tool prefix must match the datasource type.\n- Query tools require the Edge cluster to support Explore queries (protocol milestone v0.68.0); diagnostic tools require the v0.71.0 base invoke protocol. Unsupported clusters fail with `edge_upgrade_required`, `mixed_edge_versions`, or `edge_version_unknown`; never fall back to `/monit/query/data` or another endpoint automatically.\n- For query tools, `params` follows the per-datasource schema named in the `tool` field description. `expr` and `execution` are always required. `limit`/`direction` only bound raw-log retrieval, never SQL rows or scanned data. Unknown extension fields are tolerated but never executed or forwarded.\n- Query `data` is the complete Explore result: `format` is `explore_result.v1` and `result.kind` is `samples`, `frames`, or `logs`; log results keep `applied_limit` and `has_more`. Query results never synthesize `summary` or `truncated`.\n- Request body limit 128 KiB; complete success response limit 10 MiB for both families; diagnostic tool timeout at most 25 seconds.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **2,000 requests/minute**; **32 requests/second** per account |\n| Permissions | **Datasources Read** (`monit`) |\n\nUse datasource IDs from `/monit/datasource/list`. Disabled datasources return `datasource_disabled`; `alerting_enabled=false` does not block tools. Errors use non-2xx HTTP status and `error.code`, `error.message`, `error.reason`. `tool_not_supported` indicates the selected executor does not provide this tool; it is not a vendor permission error. Never retry through another Edge or the legacy diagnose endpoint automatically.\n\n## Usage\n\n- The caller needs query access to the datasource (see `readonly_team_ids` on the datasource); without it the call fails with 403 `access_denied`. A datasource in another account returns 404 `datasource_not_found`.\n- Diagnostic tools exist only for datasource types `mysql`, `postgres`, `redis_node`, `redis_sentinel`, `mongodb_mongod`, `mongodb_mongos`, `kafka`, `elasticsearch`, `prometheus`, `loki` and `victorialogs`; `oracle`, `clickhouse`, `sls` and `tencent_cls` support only their `<type>.query` tool. Other combinations fail with `invalid_request`.\n- Two tool families share this entry: diagnostic tools defined by the executing Edge (e.g. `mysql.overview`, `prometheus.metric_trends`) and query tools named `<type>.query`. The tool prefix must match the datasource type.\n- Query tools require the Edge cluster to support Explore queries (protocol milestone v0.68.0); diagnostic tools require the v0.71.0 base invoke protocol. Unsupported clusters fail with `edge_upgrade_required`, `mixed_edge_versions`, or `edge_version_unknown`; never fall back to `/monit/query/data` or another endpoint automatically.\n- For query tools, `params` follows the per-datasource schema named in the `tool` field description. `expr` and `execution` are always required. `limit`/`direction` only bound raw-log retrieval, never SQL rows or scanned data. Unknown extension fields are tolerated but never executed or forwarded.\n- Query `data` is the complete Explore result: `format` is `explore_result.v1` and `result.kind` is `samples`, `frames`, or `logs`; log results keep `applied_limit` and `has_more`. Query results never synthesize `summary` or `truncated`.\n- Request body limit 128 KiB; complete success response limit 10 MiB for both families; diagnostic tool timeout at most 25 seconds.",
           "href": "/en/api-reference/monitors/data-sources/monit-datasource-tools-invoke",
           "metadata": {
             "sidebarTitle": "Invoke datasource tool"
@@ -2208,7 +2335,7 @@
             }
           },
           "400": {
-            "description": "Standard HTTP error; error.reason: invalid_request.",
+            "description": "Standard HTTP error. `error.reason` is `invalid_request` for malformed or out-of-range parameters, a disabled data source, an unsupported data source type, or a data source without an Edge cluster. A data source ID that does not exist returns code `ResourceNotFound` without a `reason`.",
             "content": {
               "application/json": {
                 "schema": {
@@ -2221,17 +2348,7 @@
             "$ref": "#/components/responses/Unauthorized"
           },
           "403": {
-            "description": "Standard HTTP error; error.reason: access_denied.",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/ErrorResponse"
-                }
-              }
-            }
-          },
-          "404": {
-            "description": "Standard HTTP error; error.reason: datasource_not_found.",
+            "description": "The caller is not allowed to query this data source. `error.code` is `AccessDenied`; there is no `error.reason`.",
             "content": {
               "application/json": {
                 "schema": {
@@ -2241,7 +2358,7 @@
             }
           },
           "413": {
-            "description": "Standard HTTP error; error.reason: source_too_large, result_too_large.",
+            "description": "Standard HTTP error. `error.reason`: `too_many_rows`, `source_too_large`, or `result_too_large`. A request body above 256 KiB also returns 413, without a `reason`.",
             "content": {
               "application/json": {
                 "schema": {
@@ -2281,7 +2398,7 @@
             }
           },
           "503": {
-            "description": "Standard HTTP error; error.reason: no_active_edge, edge_upgrade_required, mixed_edge_versions, edge_unavailable.",
+            "description": "Standard HTTP error. `error.reason`: `no_active_edge`, `edge_version_unknown`, `edge_upgrade_required`, `mixed_edge_versions`, or `edge_unavailable`.",
             "content": {
               "application/json": {
                 "schema": {
@@ -2306,7 +2423,7 @@
           "Monitors/Diagnostics"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **100 requests/minute**; **16 requests/second** per account |\n| Permissions | **Datasources Read** (`monit`) |\n| Edge requirement | Supported deployments require **monit-edge v0.68.0 or later** |\n\n## Usage\n\n- Use this endpoint when you need the data source's native result shape; `/monit/query/data` returns the stable `query_result.v1` contract instead. Dispatch on `data.result.kind` (`frames`, `samples`, or `logs`) here.\n- `execution.kind` decides which companion fields are accepted: `instant` needs only `to_ms`, `range` requires `from_ms`, `to_ms`, and `max_data_points`, and `window` takes `from_ms` and `to_ms`. `step_seconds` is not accepted; the step is derived from `max_data_points` and `min_step_seconds`.\n- `args` carries macro substitutions such as Grafana-style variables; every value is a string.\n- A `logs` result is capped at 1,000 entries and reports `applied_limit` plus `has_more`. Time-series and sample results are capped at 1,000 items each and the whole success response at 8 MiB.\n- Query execution may take up to 35 seconds across WebAPI forwarding and Edge execution. Configure client timeouts to at least 40 seconds.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **100 requests/minute**; **16 requests/second** per account |\n| Permissions | **Datasources Read** (`monit`) |\n| Edge requirement | Supported deployments require **monit-edge v0.68.0 or later** |\n\n## Usage\n\n- Use this endpoint when you need the data source's native result shape; `/monit/query/data` returns the stable `query_result.v1` contract instead. Dispatch on `data.result.kind` (`frames`, `samples`, or `logs`) here.\n- The data source is identified by `datasource_id`. It must belong to the account, be enabled, have an Edge cluster, and be one of `prometheus`, `elasticsearch`, `loki`, `clickhouse`, `mysql`, `oracle`, `postgres`, `sls`, `victorialogs`, or `tencent_cls`. When the data source restricts querying to certain teams, only members of those teams, its managing team, and account owners or admins can query it.\n- `execution.kind` decides which companion fields are accepted: `instant` needs `to_ms` (`from_ms` is optional), `range` requires `from_ms`, `to_ms`, and `max_data_points`, and `window` requires `from_ms` and `to_ms`. When both times are given, `from_ms` must be less than `to_ms`. `step_seconds` is not accepted; the step is derived from `max_data_points` and `min_step_seconds`.\n- `args` is required (send `{}` when unused) and carries macro substitutions such as Grafana-style variables; every value is a string. Unknown or duplicate JSON keys are rejected.\n- A `logs` result is capped at 1,000 entries (100 for `sls`) and reports `applied_limit` plus `has_more`. A `frames` result holds at most 1,000 frames, 1,000 table rows in total, and 100,000 values in total; a `samples` result holds at most 1,000 samples. The request body is limited to 256 KiB and the whole success response to 10 MiB.\n- Failures use the standard error envelope. `error.reason` is a stable machine-readable value; a data source ID that does not exist returns HTTP 400 with code `ResourceNotFound` and no `reason`.\n- Query execution may take up to 35 seconds across WebAPI forwarding and Edge execution. Configure client timeouts to at least 40 seconds.",
           "href": "/en/api-reference/monitors/diagnostics/monit-read-query-explore",
           "metadata": {
             "sidebarTitle": "Run Explore query"
@@ -2331,11 +2448,11 @@
           {
             "name": "X-DSID",
             "in": "header",
-            "required": true,
+            "required": false,
             "schema": {
               "type": "string"
             },
-            "description": "Data source ID to query. Must reference a Prometheus-compatible data source owned by the authenticated account."
+            "description": "Data source ID to query, as a decimal string. Must reference a Prometheus data source owned by the authenticated account. When omitted, the request is served by the platform's own Prometheus instead of one of your data sources."
           }
         ],
         "responses": {
@@ -2358,7 +2475,7 @@
             }
           },
           "400": {
-            "description": "The `X-DSID` header is missing or invalid, the data source does not exist, or it is not a Prometheus data source. Returned as `text/plain`.",
+            "description": "The `X-DSID` header is not a number, the data source is not a Prometheus data source, or no monit-edge is registered for the data source's cluster. Returned as `text/plain`.",
             "content": {
               "text/plain": {
                 "schema": {
@@ -2370,18 +2487,14 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
-          "500": {
-            "description": "The data source lookup or the proxied request failed. Returned as `text/plain`.",
-            "content": {
-              "text/plain": {
-                "schema": {
-                  "type": "string"
-                }
-              }
-            }
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
           },
-          "503": {
-            "description": "No monit-edge in the data source's cluster supports the data source resource proxy. Returned as `text/plain`; upgrade monit-edge.",
+          "429": {
+            "$ref": "#/components/responses/TooManyRequests"
+          },
+          "500": {
+            "description": "The data source does not exist or belongs to another account (message `data source not found`), or the data source lookup or proxied request failed. Returned as `text/plain`.",
             "content": {
               "text/plain": {
                 "schema": {
@@ -2396,7 +2509,7 @@
           "Monitors/Data sources"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | Any valid `app_key` (read-only; not gated by a specific permission class) |\n| Edge requirement | Supported deployments require **monit-edge v0.35.0 or later** |\n\n## Usage\n\n- Pass the target data source in the `X-DSID` header. It must be a Prometheus-compatible data source owned by the authenticated account; use `/monit/datasource/list` to obtain its ID.\n- The 200 body is the data source's native Prometheus HTTP API payload, **not** the standard `{ request_id, data }` envelope. Failures raised before the data source is reached are returned as `text/plain` with the matching 4xx or 5xx status.\n- When `X-DSID` is omitted, the request falls back to the platform's own Prometheus proxy. Send the header to query a specific data source.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | Any valid `app_key` (read-only; not gated by a specific permission class) |\n| Edge requirement | Querying a specific data source requires **monit-edge v0.35.0 or later** |\n\n## Usage\n\n- Pass the target data source ID in the `X-DSID` header. It must belong to the authenticated account and be a Prometheus data source; use `/monit/datasource/list` to obtain its ID.\n- The 200 body is the data source's native Prometheus HTTP API payload, **not** the standard `{ request_id, data }` envelope. Query-string parameters are forwarded unchanged, so Prometheus's own parameters such as `match[]`, `start`, and `end` work.\n- When `X-DSID` is omitted, or any monit-edge of the data source's cluster is older than v0.35.0, the request is answered by the platform's own Prometheus instead of your data source. Send the header and keep monit-edge up to date to get your data source's values.\n- Failures raised before the data source is reached are returned as `text/plain` with the matching 4xx or 5xx status. A status of 400 or above returned by the data source itself is passed through with its own body.",
           "href": "/en/api-reference/monitors/data-sources/monit-prometheus-read-label-values",
           "metadata": {
             "sidebarTitle": "List Prometheus label values"
@@ -2413,7 +2526,7 @@
           "Monitors/Dashboards"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Dashboards Manage** (`monit`) |\n\n## Usage\n\n- The caller supplies `dashboard_id`, so a retried request after a timeout fails with `DashboardIDConflict` instead of creating a second dashboard.\n- `definition` is bounded at 1 MiB and the request body at 2 MiB.\n- Audit-logged.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Dashboards Manage** (`monit`) |\n\n## Usage\n\n- The caller generates `dashboard_id` (a lowercase canonical UUIDv7). Retrying after a timeout with the same ID fails with `DashboardIDConflict` (HTTP 409) instead of creating a second dashboard.\n- `folder_id` must be one of the folders the `app_key` owner can access: folders they created or that belong to one of their teams, plus all subfolders of those; the account owner and admins can access every folder; otherwise the call fails with `FolderNotFound` (HTTP 404).\n- A new dashboard starts at `revision` 1; send it as `expected_revision` on the next update, move or delete.\n- An invalid `definition` returns `InvalidParameter` (HTTP 400) whose message lists each violation as `<JSON pointer>: <reason>`. A definition over 1 MiB or over a count limit such as sections per tab, panels, queries or variables, or a request body over 2 MiB, returns `EntityTooLarge` (HTTP 413); a `schema_version` other than `dashboard.v1` returns `UnsupportedSchemaVersion` (HTTP 422).\n- Audit-logged.",
           "href": "/en/api-reference/monitors/dashboards/monit-dashboard-write-create",
           "metadata": {
             "sidebarTitle": "Create dashboard"
@@ -2518,7 +2631,7 @@
                                       "legend_alias": "{{env}} requests",
                                       "query": {
                                         "mode": "range",
-                                        "expr": "sum(rate(http_requests_total{env=\"{{env}}\"}[5m]))",
+                                        "expr": "sum(rate(http_requests_total{env=\"${env}\"}[5m]))",
                                         "args": {},
                                         "min_step_seconds": 30
                                       }
@@ -2652,7 +2765,7 @@
                                   "legend_alias": "{{env}} requests",
                                   "query": {
                                     "mode": "range",
-                                    "expr": "sum(rate(http_requests_total{env=\"{{env}}\"}[5m]))",
+                                    "expr": "sum(rate(http_requests_total{env=\"${env}\"}[5m]))",
                                     "args": {},
                                     "min_step_seconds": 30
                                   }
@@ -2691,7 +2804,7 @@
           "Monitors/Dashboards"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | any valid `app_key`; the result is limited to folders its owner can read |\n\n## Usage\n\n- A dashboard in the trash returns `DashboardDeleted` rather than the definition.\n- This read is not permission-gated beyond folder readability: an `app_key` only sees dashboards in folders its owner can read.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Only dashboards in folders the `app_key` owner can access: folders they created or that belong to one of their teams, plus all subfolders of those; the account owner and admins can access every folder are visible; any other dashboard returns `DashboardNotFound` (HTTP 404).\n- A dashboard in the trash returns `DashboardDeleted` (HTTP 410) instead of its definition; find it with `POST /monit/dashboard/trash/list` and bring it back with `POST /monit/dashboard/restore`.\n- Send the returned `revision` as `expected_revision` on the next update, move or delete.",
           "href": "/en/api-reference/monitors/dashboards/monit-dashboard-read-get",
           "metadata": {
             "sidebarTitle": "Get dashboard detail"
@@ -2796,7 +2909,7 @@
                                       "legend_alias": "{{env}} requests",
                                       "query": {
                                         "mode": "range",
-                                        "expr": "sum(rate(http_requests_total{env=\"{{env}}\"}[5m]))",
+                                        "expr": "sum(rate(http_requests_total{env=\"${env}\"}[5m]))",
                                         "args": {},
                                         "min_step_seconds": 30
                                       }
@@ -2878,7 +2991,7 @@
           "Monitors/Dashboards"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Dashboards Manage** (`monit`) |\n\n## Usage\n\n- The whole definition is sent — this is not a partial update.\n- `expected_revision` must equal the stored revision or the call fails with `DashboardRevisionConflict`.\n- A byte-identical definition sets `changed` to false and does not create a revision.\n- The response `resource` is `null` only if the caller lost read access to the folder during the call.\n- Audit-logged.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Dashboards Manage** (`monit`) |\n\n## Usage\n\n- Send the whole definition; anything left out is removed, not kept from the stored version.\n- `expected_revision` must equal the stored revision, otherwise the call fails with `DashboardRevisionConflict` (HTTP 409); re-read the dashboard and retry.\n- On success `revision` goes up by 1 and a revision entry carrying `message` is recorded. When the normalized definition and `schema_version` equal the stored ones, `changed` is false, `revision` stays the same and no revision entry is recorded.\n- Titles and descriptions are trimmed and an omitted numeric `unit` is stored as `unitless`, so the returned `definition` can differ slightly from the request.\n- A dashboard in the trash returns `DashboardDeleted` (HTTP 410); a dashboard whose folder the caller cannot access returns `AccessDenied`. Validation and size errors are the same as for `POST /monit/dashboard/create`.\n- Audit-logged.",
           "href": "/en/api-reference/monitors/dashboards/monit-dashboard-write-update",
           "metadata": {
             "sidebarTitle": "Update dashboard"
@@ -2985,7 +3098,7 @@
                                         "legend_alias": "{{env}} requests",
                                         "query": {
                                           "mode": "range",
-                                          "expr": "sum(rate(http_requests_total{env=\"{{env}}\"}[5m]))",
+                                          "expr": "sum(rate(http_requests_total{env=\"${env}\"}[5m]))",
                                           "args": {},
                                           "min_step_seconds": 30
                                         }
@@ -3120,7 +3233,7 @@
                                   "legend_alias": "{{env}} requests",
                                   "query": {
                                     "mode": "range",
-                                    "expr": "sum(rate(http_requests_total{env=\"{{env}}\"}[5m]))",
+                                    "expr": "sum(rate(http_requests_total{env=\"${env}\"}[5m]))",
                                     "args": {},
                                     "min_step_seconds": 30
                                   }
@@ -3160,7 +3273,7 @@
           "Monitors/Dashboards"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Dashboards Manage** (`monit`) |\n\n## Usage\n\n- Both the source and the destination folder must be writable.\n- The definition is untouched, so `changed` is false only when the dashboard already sits in `folder_id`.\n- Audit-logged.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Dashboards Manage** (`monit`) |\n\n## Usage\n\n- The caller must be able to access both the current folder and the destination (folders they created or that belong to one of their teams, plus subfolders; the account owner and admins can access every folder). An inaccessible current folder returns `AccessDenied`; a missing or inaccessible destination returns `FolderNotFound` (HTTP 404).\n- The definition is not touched, but a real move still increments `revision` and records a revision entry. If the dashboard is already in `folder_id`, `changed` is false and nothing is written.\n- `expected_revision` must equal the stored revision, otherwise `DashboardRevisionConflict` (HTTP 409); a dashboard in the trash returns `DashboardDeleted` (HTTP 410).\n- Audit-logged.",
           "href": "/en/api-reference/monitors/dashboards/monit-dashboard-write-move",
           "metadata": {
             "sidebarTitle": "Move dashboard"
@@ -3267,7 +3380,7 @@
                                         "legend_alias": "{{env}} requests",
                                         "query": {
                                           "mode": "range",
-                                          "expr": "sum(rate(http_requests_total{env=\"{{env}}\"}[5m]))",
+                                          "expr": "sum(rate(http_requests_total{env=\"${env}\"}[5m]))",
                                           "args": {},
                                           "min_step_seconds": 30
                                         }
@@ -3344,12 +3457,12 @@
       "post": {
         "operationId": "monit-dashboard-write-delete",
         "summary": "Delete dashboard",
-        "description": "Move a dashboard to the trash.",
+        "description": "Move a dashboard to the trash, where it can be restored for 30 days.",
         "tags": [
           "Monitors/Dashboards"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Dashboards Manage** (`monit`) |\n\n## Usage\n\n- The delete is soft: the definition is retained for 30 days and can be brought back with `POST /monit/dashboard/restore`.\n- The returned `revision` is the one recorded for the deletion.\n- Audit-logged.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Dashboards Manage** (`monit`) |\n\n## Usage\n\n- The delete is soft: the dashboard moves to the trash and is permanently removed, with all its revisions, 30 days after deletion. Restore it before then with `POST /monit/dashboard/restore`.\n- Deleting increments `revision`; the returned `revision` is the value to send as `expected_revision` when restoring.\n- `expected_revision` must equal the stored revision, otherwise `DashboardRevisionConflict` (HTTP 409); deleting a dashboard that is already in the trash returns `DashboardDeleted` (HTTP 410).\n- Audit-logged.",
           "href": "/en/api-reference/monitors/dashboards/monit-dashboard-write-delete",
           "metadata": {
             "sidebarTitle": "Delete dashboard"
@@ -3426,7 +3539,7 @@
           "Monitors/Dashboards"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Dashboards Manage** (`monit`) |\n\n## Usage\n\n- Omit `folder_id` to restore into the original folder; if that folder is no longer writable the call fails with `RestoreFolderRequired` and you must name a destination.\n- Restoring a dashboard that is not in the trash fails with `DashboardNotFound`.\n- Audit-logged.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Dashboards Manage** (`monit`) |\n\n## Usage\n\n- Only dashboards in the trash can be restored; any other dashboard returns `DashboardNotFound` (HTTP 404).\n- `expected_revision` must equal the trashed dashboard's current revision (the `revision` returned by delete and shown in the trash listing), otherwise `DashboardRevisionConflict` (HTTP 409).\n- Omit `folder_id` to restore into the original folder. If that folder no longer exists, the account owner and admins get `RestoreFolderRequired` (HTTP 409) and must pass a destination; other members can only restore dashboards whose original folder they can still access and get `DashboardNotFound` otherwise.\n- A missing or inaccessible destination folder returns `FolderNotFound` (HTTP 404). Restoring increments `revision`.\n- Audit-logged.",
           "href": "/en/api-reference/monitors/dashboards/monit-dashboard-write-restore",
           "metadata": {
             "sidebarTitle": "Restore dashboard"
@@ -3531,7 +3644,7 @@
                                       "legend_alias": "{{env}} requests",
                                       "query": {
                                         "mode": "range",
-                                        "expr": "sum(rate(http_requests_total{env=\"{{env}}\"}[5m]))",
+                                        "expr": "sum(rate(http_requests_total{env=\"${env}\"}[5m]))",
                                         "args": {},
                                         "min_step_seconds": 30
                                       }
@@ -3607,12 +3720,12 @@
       "post": {
         "operationId": "monit-dashboard-read-list",
         "summary": "List dashboards",
-        "description": "List the dashboards in one folder.",
+        "description": "List the dashboards stored directly in one folder, with word search and paging.",
         "tags": [
           "Monitors/Dashboards"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | any valid `app_key`; the result is limited to folders its owner can read |\n\n## Usage\n\n- `folder_id` is required; the listing always includes descendant folders.\n- `query` is split on whitespace and matched against title and description.\n- Sort keys are limited to `title` and `updated_at` here, at most two, and default to `updated_at` descending.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Only dashboards stored directly in `folder_id` are returned; dashboards in its subfolders are not included. Use `POST /monit/dashboard/search` to look across folders.\n- `folder_id` must be one of the folders the `app_key` owner can access: folders they created or that belong to one of their teams, plus all subfolders of those; the account owner and admins can access every folder; otherwise the call fails with `FolderNotFound` (HTTP 404). Trashed dashboards are never listed.\n- `query` is split on whitespace; a dashboard matches when every word appears as a substring of its title or description.\n- Sort keys are `title` and `updated_at`, at most two and each used once; the default is `updated_at` descending, and ties are ordered by `dashboard_id`.",
           "href": "/en/api-reference/monitors/dashboards/monit-dashboard-read-list",
           "metadata": {
             "sidebarTitle": "List dashboards"
@@ -3717,7 +3830,7 @@
           "Monitors/Dashboards"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | any valid `app_key`; the result is limited to folders its owner can read |\n\n## Usage\n\n- `query` must contain at least one word; an empty query fails with `InvalidParameter`.\n- Scope is limited to the folders the `app_key` owner can read — this endpoint never widens access.\n- Sort keys are limited to `title` and `updated_at`.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- `query` must contain at least one word; an empty or whitespace-only query fails with `InvalidParameter`. A dashboard matches when every word appears as a substring of its title or description.\n- Results cover only folders the `app_key` owner can access: folders they created or that belong to one of their teams, plus all subfolders of those; the account owner and admins can access every folder. Trashed dashboards are never returned.\n- Sort keys are `title` and `updated_at`, at most two and each used once; the default is `updated_at` descending.",
           "href": "/en/api-reference/monitors/dashboards/monit-dashboard-read-search",
           "metadata": {
             "sidebarTitle": "Search dashboards"
@@ -3821,7 +3934,7 @@
           "Monitors/Dashboards"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Dashboards Manage** (`monit`) |\n\n## Usage\n\n- Sort keys are limited to `title` and `deleted_at` and default to `deleted_at` descending.\n- Unlike the read endpoints this one is gated by Dashboards Manage.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Dashboards Manage** (`monit`) |\n\n## Usage\n\n- Lists trashed dashboards in folders the `app_key` owner can access: folders they created or that belong to one of their teams, plus all subfolders of those; the account owner and admins can access every folder. Each entry is purged permanently 30 days after deletion.\n- Sort keys are `title` and `deleted_at`, at most two and each used once; the default is `deleted_at` descending.\n- Unlike the other dashboard read endpoints, this one requires the Dashboards Manage permission.",
           "href": "/en/api-reference/monitors/dashboards/monit-dashboard-trash-read-list",
           "metadata": {
             "sidebarTitle": "List trashed dashboards"
@@ -3921,7 +4034,7 @@
           "Monitors/Dashboards"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | any valid `app_key`; the result is limited to folders its owner can read |\n\n## Usage\n\n- At most 20 revisions are retained, including the current one; older ones are dropped as new revisions land.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Returns at most the 20 most recent revisions, newest first. Create, every update that changes the definition, move, delete and restore each record a revision; older ones are pruned.\n- `message` is present only on revisions written by `POST /monit/dashboard/update` with a message.\n- Only dashboards in folders the `app_key` owner can access: folders they created or that belong to one of their teams, plus all subfolders of those; the account owner and admins can access every folder are visible, others return `DashboardNotFound` (HTTP 404); a dashboard in the trash returns `DashboardDeleted` (HTTP 410).",
           "href": "/en/api-reference/monitors/dashboards/monit-dashboard-revision-read-list",
           "metadata": {
             "sidebarTitle": "List dashboard revisions"
@@ -4011,7 +4124,7 @@
           "Monitors/Dashboards"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | any valid `app_key`; the result is limited to folders its owner can read |\n\n## Usage\n\n- Revision numbers are per dashboard and start at 1.\n- A revision that has aged out of the 20-entry window returns `DashboardNotFound`.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Revision numbers are per dashboard and start at 1 (the create). Revisions older than the latest 20 are pruned and return `DashboardNotFound` (HTTP 404).\n- Only dashboards in folders the `app_key` owner can access: folders they created or that belong to one of their teams, plus all subfolders of those; the account owner and admins can access every folder are visible; a dashboard in the trash returns `DashboardDeleted` (HTTP 410), so restore it before reading its history.",
           "href": "/en/api-reference/monitors/dashboards/monit-dashboard-revision-read-get",
           "metadata": {
             "sidebarTitle": "Get dashboard revision"
@@ -4112,7 +4225,7 @@
                                       "legend_alias": "{{env}} requests",
                                       "query": {
                                         "mode": "range",
-                                        "expr": "sum(rate(http_requests_total{env=\"{{env}}\"}[5m]))",
+                                        "expr": "sum(rate(http_requests_total{env=\"${env}\"}[5m]))",
                                         "args": {},
                                         "min_step_seconds": 30
                                       }
@@ -4191,7 +4304,7 @@
           "Monitors/Dashboards"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | any valid `app_key`; the result is limited to folders its owner can read |\n\n## Usage\n\n- Use this to render navigation or let an agent find a panel ID before running it — it avoids paying for the full definition.\n- With `target_id` set, only the branch containing that tab, section or panel is returned; an unknown ID fails with `TargetNotFound`.\n- Panel entries carry only the visualization `kind` and the datasource type, never the panel's queries.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Use it to render navigation or to find a panel ID before calling `POST /monit/dashboard/panel/run`, without downloading queries.\n- With `target_id` set to a tab ID the whole tab is returned; a section ID returns that tab with only that section and no top panels; a panel ID returns only that panel inside its tab or section. An unknown ID fails with `TargetNotFound` (HTTP 404).\n- Panel entries carry only the visualization `kind` and the datasource type, never queries. Datasource variables always report `selection` as `single` without `all`.\n- Only dashboards in folders the `app_key` owner can access: folders they created or that belong to one of their teams, plus all subfolders of those; the account owner and admins can access every folder are visible; a dashboard in the trash returns `DashboardDeleted` (HTTP 410).",
           "href": "/en/api-reference/monitors/dashboards/monit-dashboard-read-outline",
           "metadata": {
             "sidebarTitle": "Get dashboard outline"
@@ -4334,7 +4447,7 @@
           "Monitors/Dashboards"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **16 requests/second** (no per-minute cap) per account |\n| Permissions | **Datasources Read** (`monit`) |\n\n## Usage\n\n- A variable that cannot be resolved does not fail the call: its entry carries an `error` and is left out of `selections`.\n- An explicitly empty `values` selection means unresolved — the resolver will not fall back to the stored default.\n- Selections are bounded at 20 variables; names must match `^[A-Za-z_][A-Za-z0-9_]{0,63}$`.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **16 requests/second** per account (no per-minute limit) |\n| Permissions | **Datasources Read** (`monit`) |\n\n## Usage\n\n- Resolves the variables of the current revision of a stored dashboard. `variables` holds the caller's current selections; a variable without an entry falls back to its stored default (`default` for `custom` and `query` variables; for `datasource` variables the `default_datasource_id` if it is still a candidate, otherwise the first candidate ordered by name).\n- A variable that cannot be resolved does not fail the call: its entry carries an `error` and is left out of `selections`. Typical causes are no selection and no default, a selection that is not among the candidates, an unresolved dependency, or an unreachable datasource.\n- An explicitly empty `values` selection means unresolved (`variable_invalid`); the resolver does not fall back to the stored default.\n- Variables are resolved in dependency order, so a variable that depends on a failed variable also reports an error. A name in `variables` that the dashboard does not define fails the call with HTTP 400.\n- Each variable returns at most 1000 candidates, and all candidates together must fit in 8 MiB, otherwise the call fails with `EntityTooLarge` (HTTP 413). `query` variables can only run against Prometheus, MySQL and Loki datasources.\n- The caller must be able to see the dashboard's folder; otherwise the call returns `DashboardNotFound` (HTTP 404). The call has a 35-second overall deadline; exceeding it returns `RuntimeTimeout` (HTTP 504).",
           "href": "/en/api-reference/monitors/dashboards/monit-dashboard-variable-read-resolve",
           "metadata": {
             "sidebarTitle": "Resolve dashboard variables"
@@ -4455,7 +4568,7 @@
           "Monitors/Dashboards"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **16 requests/second** (no per-minute cap) per account |\n| Permissions | **Datasources Read** (`monit`) |\n\n## Usage\n\n- `context` is `new` for a folder that has no dashboard yet, and `existing` for an already stored dashboard; mixing the two fields fails validation.\n- Nothing is persisted, so the response has no `dashboard_id` or `revision`.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **16 requests/second** per account (no per-minute limit) |\n| Permissions | **Datasources Read** (`monit`) |\n\n## Usage\n\n- Resolves a draft variable list that is not stored in a dashboard, so an editor can test variables before saving. Nothing is persisted, so the response has no `dashboard_id` or `revision`.\n- `context.kind` is `existing` with `dashboard_id` when the draft belongs to a stored dashboard, or `new` with `folder_id` when the dashboard does not exist yet; sending the other kind's field fails validation (HTTP 400). The caller needs access to that dashboard's folder or to that folder (otherwise 403/404).\n- The draft `variables` are validated like a stored definition (names, dependencies, option limits, at most 20 variables, 1 MiB); a violation fails the call with HTTP 400, or HTTP 413 when a size limit is exceeded.\n- Resolution behaves like variable resolve: a variable that fails carries an `error` and is absent from `selections`, and an empty `values` selection is unresolved.\n- The call has a 35-second overall deadline; exceeding it returns `RuntimeTimeout` (HTTP 504).",
           "href": "/en/api-reference/monitors/dashboards/monit-dashboard-variable-read-preview",
           "metadata": {
             "sidebarTitle": "Preview draft variables"
@@ -4604,7 +4717,7 @@
           "Monitors/Dashboards"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **16 requests/second** (no per-minute cap) per account |\n| Permissions | **Datasources Read** (`monit`) |\n\n## Usage\n\n- Use this to show which datasource a panel will hit, and with which expression, before spending a query.\n- `panel_ids` accepts 1–100 unique IDs; a panel missing from the dashboard yields a `state: \"error\"` entry instead of failing the whole call.\n- A panel whose queries only partly resolve reports `state: \"partial\"`.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **16 requests/second** per account (no per-minute limit) |\n| Permissions | **Datasources Read** (`monit`) |\n\n## Usage\n\n- Use this to show which datasource a panel will hit, and with which expression, before running it. Nothing is executed.\n- `panel_ids` accepts 1–100 unique IDs, answered in request order. A panel that is not in the dashboard yields `state: \"error\"` with reason `panel_missing` instead of failing the call; a text panel yields `state: \"error\"` with reason `invalid_request`.\n- `state` is `success` when every query of the panel resolved, `partial` when only some did, and `error` when none did. `queries` lists the queries that resolved; `error` reports only the first failure.\n- Built-in time variables (such as the step and the time range) are rendered from `time` and `max_data_points`, unless `preserve_builtin_variables` is `true`, which leaves them verbatim for a caller that renders them with its own window. User variables are always resolved.\n- Panel queries can only be bound to Prometheus, MySQL and Loki datasources. The call has a 35-second overall deadline; exceeding it returns `RuntimeTimeout` (HTTP 504).",
           "href": "/en/api-reference/monitors/dashboards/monit-dashboard-query-read-resolve",
           "metadata": {
             "sidebarTitle": "Resolve panel queries"
@@ -4730,7 +4843,7 @@
           "Monitors/Dashboards"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **16 requests/second** (no per-minute cap) per account |\n| Permissions | **Datasources Read** (`monit`) |\n\n## Usage\n\n- Omitting `revision` runs whatever is current; sending it makes the call reject a stale read instead of returning overwritten data.\n- `run_state` aggregates the per-query states — `partial` when some refs succeeded, `incompatible` when the datasource accepted the call but the query does not fit its type.\n- Each ref's `execution` payload is datasource-specific and passed through unmodified; `child_request_id` traces the underlying datasource call.\n- `max_data_points` defaults to 100 and is bounded at 2–5000. The whole response is capped at 8 MiB.\n- Queries inside one panel run with a concurrency of at most 6.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **32 requests/second** per account (no per-minute limit) |\n| Permissions | **Datasources Read** (`monit`) |\n\n## Usage\n\n- Executes every query of one panel of the current stored dashboard against its datasource. The call returns HTTP 200 even when every query failed; read `run_state` and each ref's `state` and `error`.\n- Omitting `revision` (or sending 0) runs the current revision. Sending it makes the call fail with `DashboardRevisionConflict` (HTTP 409) when the dashboard has changed, instead of returning data for a stale definition.\n- `run_state` summarizes the refs: `success` when all succeeded, `partial` when at least one succeeded and at least one did not, and otherwise `cancelled`, `incompatible` or `error`. A ref is `incompatible` when its query ran but the result does not fit the panel's visualization, for example a configured value field is missing or not numeric.\n- Each ref's `execution` is datasource-specific and passed through unmodified; `child_request_id` identifies the underlying datasource call. Text panels cannot be run (HTTP 400), and an unknown `panel_id` returns `TargetNotFound` (HTTP 404).\n- `max_data_points` defaults to 100 and is bounded at 2–5000. At most 6 queries of one panel run at the same time. A response larger than 8 MiB is rejected with `EntityTooLarge` (HTTP 413) instead of being truncated. The call has a 35-second overall deadline; exceeding it returns `RuntimeTimeout` (HTTP 504).",
           "href": "/en/api-reference/monitors/dashboards/monit-dashboard-panel-read-run",
           "metadata": {
             "sidebarTitle": "Run dashboard panel"
@@ -4891,7 +5004,7 @@
           "Monitors/Dashboards"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **16 requests/second** (no per-minute cap) per account |\n| Permissions | **Datasources Read** (`monit`) |\n\n## Usage\n\n- Use this to validate a panel while the user is still editing it — nothing is written and no revision is created.\n- The draft is still held to the same limits as a saved dashboard: grid overlap, query counts per visualization kind, and the 1 MiB definition ceiling.\n- The response mirrors a panel run minus `dashboard_id`.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **32 requests/second** per account (no per-minute limit) |\n| Permissions | **Datasources Read** (`monit`) |\n\n## Usage\n\n- Use this to check a panel while the user is still editing it: the draft panel and its variables are executed inline, and nothing is written and no revision is created.\n- `context` ties the draft to a stored dashboard (`existing` with `dashboard_id`) or to a folder that has no dashboard yet (`new` with `folder_id`). The caller needs access to that dashboard's folder or to that folder.\n- The draft `panel` and `variables` are validated like a stored definition (grid, query counts per visualization kind, variable references) and must stay within 1 MiB; a violation fails the call with HTTP 400, or HTTP 413 when a size limit is exceeded. Text panels cannot be previewed.\n- The response has the same shape as a panel run, without `dashboard_id` and `revision`. It returns HTTP 200 even when every query failed; read `run_state` and each ref's `state` and `error`.\n- `max_data_points` defaults to 100 and is bounded at 2–5000. At most 6 queries run at the same time. A response larger than 8 MiB is rejected with `EntityTooLarge` (HTTP 413). The call has a 35-second overall deadline; exceeding it returns `RuntimeTimeout` (HTTP 504).",
           "href": "/en/api-reference/monitors/dashboards/monit-dashboard-panel-read-preview",
           "metadata": {
             "sidebarTitle": "Preview draft panel"
@@ -5043,7 +5156,7 @@
                       "legend_alias": "{{env}} requests",
                       "query": {
                         "mode": "range",
-                        "expr": "sum(rate(http_requests_total{env=\"{{env}}\"}[5m]))",
+                        "expr": "sum(rate(http_requests_total{env=\"${env}\"}[5m]))",
                         "args": {},
                         "min_step_seconds": 30
                       }
@@ -5116,7 +5229,7 @@
           "Monitors/Rule folders"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Alerting Rules Read** or **Node Permissions Read** (`monit`) |\n\n## Usage\n\n- The response is a flat list of every readable folder, not a tree: rebuild the hierarchy from `parent_id` and `parent_path`, and search client-side.\n- Dashboards and alert rules both live in this folder tree, so the same IDs appear as `folder_id` on dashboard payloads.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Alerting Rules Read**, **Alerting Rules Manage**, **Node Permissions Read**, or **Node Permissions Manage** (`monit`) |\n\n## Usage\n\n- The response is a flat list of the visible folders, not a tree: rebuild the hierarchy from `parent_id` and `parent_path`, and search client-side. An account with no visible folder gets `[]`.\n- Account owners and admins see every folder. Other members see the folders they created, the folders that belong to one of their teams, everything below those folders, and the ancestor folders needed to reach them.\n- Dashboards and alert rules both live in this folder tree, so the same IDs appear as `folder_id` on dashboard payloads and alert rules.",
           "href": "/en/api-reference/monitors/rule-folders/monit-folder-read-list",
           "metadata": {
             "sidebarTitle": "List monitor folders"
@@ -5174,6 +5287,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -5187,12 +5303,12 @@
       "post": {
         "operationId": "monit-folder-read-health",
         "summary": "Get monitor folder health",
-        "description": "Get health summaries for visible folders, including issues in their descendants.",
+        "description": "Get issue flags for the visible monitor folders, including issues in their descendants.",
         "tags": [
           "Monitors/Rule folders"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **30 requests/minute**; **2 requests/second** per account |\n| Permissions | **Alerting Rules Read**, **Alerting Rules Manage**, **Node Permissions Read**, or **Node Permissions Manage** (`monit`) |\n\n## Usage\n\n- Issues include active alerts and alert-rule runtime problems; issues propagate to visible ancestors.\n- This operation scans folder rules and runtime state. Avoid frequent polling.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **30 requests/minute**; **2 requests/second** per account |\n| Permissions | **Alerting Rules Read**, **Alerting Rules Manage**, **Node Permissions Read**, or **Node Permissions Manage** (`monit`) |\n\n## Usage\n\n- `items` has one entry per folder visible to the caller (the same set as `/monit/folder/list`), sorted by `id`.\n- `has_issue` is true when a rule in the folder or in any of its descendants has an active alert or a runtime problem. The issue then also shows on every visible ancestor folder. Only rules in folders the caller can read are counted.\n- This operation scans folder rules and runtime state. Avoid frequent polling.",
           "href": "/en/api-reference/monitors/rule-folders/monit-folder-read-health",
           "metadata": {
             "sidebarTitle": "Get monitor folder health"
@@ -5238,6 +5354,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -5251,12 +5370,12 @@
       "post": {
         "operationId": "monit-folder-write-create",
         "summary": "Create monitor folder",
-        "description": "Create a monitor folder at the root or under an accessible parent folder.",
+        "description": "Create a monitor folder at the root or under a parent folder the caller may modify.",
         "tags": [
           "Monitors/Rule folders"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Alerting Rules Manage** or **Node Permissions Manage** (`monit`) |\n\n## Usage\n\n- Use `parent_id: 0` or omit it to create a root folder. The parent must be accessible.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Alerting Rules Manage** or **Node Permissions Manage** (`monit`) |\n\n## Usage\n\n- Use `parent_id: 0` or omit it to create a root folder. To create under a parent, the caller must be allowed to modify it: an account owner or admin, the creator of the parent or of one of its ancestors, or a member of the team assigned to the parent or one of its ancestors. A parent that does not exist returns `InvalidParameter`; a parent you may not modify returns `AccessDenied`.\n- The response is the created folder.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/monitors/rule-folders/monit-folder-write-create",
           "metadata": {
             "sidebarTitle": "Create monitor folder"
@@ -5309,6 +5428,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -5338,12 +5460,12 @@
       "post": {
         "operationId": "monit-folder-write-update",
         "summary": "Update monitor folder",
-        "description": "Replace the name, note, and team assignment of an accessible monitor folder.",
+        "description": "Replace the name, note, and team assignment of a monitor folder the caller may modify.",
         "tags": [
           "Monitors/Rule folders"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Alerting Rules Manage** or **Node Permissions Manage** (`monit`) |\n\n## Usage\n\n- Send both `id` and `name`. This is a replacement of editable fields: omitting `note` clears it, and omitting `team_id` resets it to 0.\n- Use the move operation to change the parent folder.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Alerting Rules Manage** or **Node Permissions Manage** (`monit`) |\n\n## Usage\n\n- Send both `id` and `name`. This is a replacement of editable fields: omitting `note` clears it, and omitting `team_id` resets it to 0.\n- The caller must be allowed to modify the folder: an account owner or admin, the folder's creator or the creator of one of its ancestors, or a member of the team assigned to the folder or one of its ancestors. A missing folder returns `InvalidParameter`; a folder you may not modify returns `AccessDenied`.\n- Use the move operation to change the parent folder. The response is the updated folder.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/monitors/rule-folders/monit-folder-write-update",
           "metadata": {
             "sidebarTitle": "Update monitor folder"
@@ -5396,6 +5518,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -5430,7 +5555,7 @@
           "Monitors/Rule folders"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Alerting Rules Manage** or **Node Permissions Manage** (`monit`) |\n\n## Usage\n\n- You must have access to both the source and destination folders.\n- `dest_parent_id` is required; send 0 explicitly to move to the root. Moving under the folder itself or a descendant is rejected.\n- Descendant paths are updated in the same transaction.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Alerting Rules Manage** or **Node Permissions Manage** (`monit`) |\n\n## Usage\n\n- The caller must be allowed to modify the source folder and, unless `dest_parent_id` is 0, the destination folder.\n- `dest_parent_id` is required; send 0 explicitly to move to the root. It must differ from `id`, and moving under the folder itself or a descendant is rejected with `InvalidParameter`. Moving a folder to its current parent succeeds without changes.\n- Descendant paths are updated in the same transaction, and the folder and all its descendants record the caller as last updater.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/monitors/rule-folders/monit-folder-write-move",
           "metadata": {
             "sidebarTitle": "Move monitor folder"
@@ -5470,6 +5595,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -5497,12 +5625,12 @@
       "post": {
         "operationId": "monit-folder-write-delete",
         "summary": "Delete monitor folder",
-        "description": "Delete an accessible monitor folder after removing its children, rules, and dashboards.",
+        "description": "Delete an empty monitor folder that the caller may modify.",
         "tags": [
           "Monitors/Rule folders"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Alerting Rules Manage** or **Node Permissions Manage** (`monit`) |\n\n## Usage\n\n- Only empty folders can be deleted. Child folders, alert rules, and dashboards block deletion with HTTP 409 and error code `FolderNotEmpty`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Alerting Rules Manage** or **Node Permissions Manage** (`monit`) |\n\n## Usage\n\n- Only empty folders can be deleted; nothing inside is removed for you. Child folders, alert rules, and dashboards block deletion with HTTP 409 and error code `FolderNotEmpty`.\n- The caller must be allowed to modify the folder. A missing folder returns `InvalidParameter`; a folder you may not modify returns `AccessDenied`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/monitors/rule-folders/monit-folder-write-delete",
           "metadata": {
             "sidebarTitle": "Delete monitor folder"
@@ -5542,6 +5670,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -5619,7 +5750,7 @@
         "type": "apiKey",
         "in": "query",
         "name": "app_key",
-        "description": "App key issued from the Flashduty console under Account → APP Keys. Required on every public API call. Keep it secret — it grants the same access as the owning account."
+        "description": "APP Key created in the Flashduty console under My → APP Key. Send it as the `app_key` query parameter or in the `Fd-App-Key` request header. Its effective access is the intersection of the key's permission scope and the creator's current role permissions. Keep it secret."
       }
     },
     "responses": {
@@ -5666,7 +5797,7 @@
         }
       },
       "Forbidden": {
-        "description": "The app_key is valid but lacks permission for this operation.",
+        "description": "The app_key is valid, but its permission scope or the creator's role does not allow this operation or object.",
         "content": {
           "application/json": {
             "schema": {
@@ -5708,7 +5839,7 @@
         }
       },
       "TooManyRequests": {
-        "description": "Rate limit hit. Either the global API limit, a per-account limit, or a per-integration limit.",
+        "description": "Rate limit hit (per-account limit or the operation's platform-wide limit). Wait for the number of seconds in `Flashcat-Request-Rate-Limit-Delay`, then retry.",
         "content": {
           "application/json": {
             "schema": {
@@ -5726,6 +5857,15 @@
               }
             }
           }
+        },
+        "headers": {
+          "Flashcat-Request-Rate-Limit-Delay": {
+            "description": "Seconds until the current rate-limit window resets. Absent when the request was rejected by the gateway's global protection limit.",
+            "schema": {
+              "type": "integer",
+              "minimum": 0
+            }
+          }
         }
       },
       "ServerError": {
@@ -5998,7 +6138,7 @@
           },
           "content": {
             "type": "string",
-            "description": "JSON string of the full rule snapshot at audit time. Populated on `/monit/rule/audit/detail`, omitted on list responses."
+            "description": "JSON string of the full rule right after the change. Populated on `/monit/rule/audit/detail`, omitted on list responses. Records written by `/monit/rule/v2/create` and `/monit/rule/v2/update` use the `AlertRuleV2` shape; records written by `/monit/rule/update/fields` and `/monit/rule/move` use the stored rule shape, whose checker configs carry legacy recovery settings instead of `recovery_mode` / `end_mode`."
           },
           "creator_id": {
             "type": "integer",
@@ -6018,7 +6158,7 @@
       },
       "AlertRuleBasic": {
         "type": "object",
-        "description": "Basic alert rule information for list views.",
+        "description": "Basic alert rule information for list views. In `include_descendants: true` listings only `id`, `folder_id` and `name` are filled; the other fields carry zero values.",
         "required": [
           "id",
           "account_id",
@@ -6049,27 +6189,30 @@
           "account_id": {
             "type": "integer",
             "format": "uint64",
-            "description": "Account ID."
+            "description": "ID of the account that owns the rule; `0` in `include_descendants: true` listings."
           },
           "folder_id": {
             "type": "integer",
             "format": "uint64",
-            "description": "Folder ID."
+            "description": "ID of the folder that directly contains the rule; in `include_descendants: true` listings it can be a descendant of the requested folder."
           },
           "name": {
             "type": "string",
-            "description": "Rule name."
+            "description": "Rule name, unique within its folder (at most 128 characters)."
           },
           "labels": {
-            "type": "object",
+            "type": [
+              "object",
+              "null"
+            ],
             "additionalProperties": {
               "type": "string"
             },
-            "description": "Custom labels."
+            "description": "Custom labels the rule adds to its alert events; `null` in `include_descendants: true` listings."
           },
           "ds_type": {
             "type": "string",
-            "description": "Data source type, e.g. `prometheus`."
+            "description": "Datasource type the rule queries. Types that support alerting: `prometheus`, `elasticsearch`, `loki`, `clickhouse`, `mysql`, `oracle`, `postgres`, `sls`, `tencent_cls`, `victorialogs`. Only enabled rules are checked against this list, so a disabled rule may carry another value; empty in `include_descendants: true` listings."
           },
           "enabled": {
             "type": "boolean",
@@ -6077,7 +6220,7 @@
           },
           "debug_log_enabled": {
             "type": "boolean",
-            "description": "Whether debug logging is enabled."
+            "description": "Whether debug logging is on; when `true` the edge writes detailed evaluation logs for this rule."
           },
           "cron_pattern": {
             "type": "string",
@@ -6090,7 +6233,7 @@
           },
           "delay_seconds": {
             "type": "integer",
-            "description": "Evaluation delay in seconds."
+            "description": "Seconds the evaluation query window is shifted back to allow for data ingestion latency."
           },
           "creator_id": {
             "type": "integer",
@@ -6375,7 +6518,7 @@
               "cloud",
               "self-managed"
             ],
-            "description": "Deployment type. `cloud` uses Elastic Cloud; `self-managed` uses a self-hosted cluster."
+            "description": "Deployment type; required. `cloud` uses Elastic Cloud (`address` is not needed); `self-managed` uses a self-hosted cluster (`address` is required)."
           },
           "timeout_mills": {
             "type": "integer",
@@ -6592,31 +6735,40 @@
         "description": "Type-specific datasource configuration. Include only the block matching `type_ident`.",
         "properties": {
           "prometheus": {
-            "$ref": "#/components/schemas/DSPrometheusConfig"
+            "$ref": "#/components/schemas/DSPrometheusConfig",
+            "description": "Settings for `type_ident` `prometheus`."
           },
           "loki": {
-            "$ref": "#/components/schemas/DSLokiConfig"
+            "$ref": "#/components/schemas/DSLokiConfig",
+            "description": "Settings for `type_ident` `loki`."
           },
           "mysql": {
-            "$ref": "#/components/schemas/DSMySQLConfig"
+            "$ref": "#/components/schemas/DSMySQLConfig",
+            "description": "Settings for `type_ident` `mysql`."
           },
           "oracle": {
-            "$ref": "#/components/schemas/DSOracleConfig"
+            "$ref": "#/components/schemas/DSOracleConfig",
+            "description": "Settings for `type_ident` `oracle`."
           },
           "postgres": {
-            "$ref": "#/components/schemas/DSPostgresConfig"
+            "$ref": "#/components/schemas/DSPostgresConfig",
+            "description": "Settings for `type_ident` `postgres`."
           },
           "clickhouse": {
-            "$ref": "#/components/schemas/DSClickHouseConfig"
+            "$ref": "#/components/schemas/DSClickHouseConfig",
+            "description": "Settings for `type_ident` `clickhouse`."
           },
           "elasticsearch": {
-            "$ref": "#/components/schemas/DSElasticSearchConfig"
+            "$ref": "#/components/schemas/DSElasticSearchConfig",
+            "description": "Settings for `type_ident` `elasticsearch`."
           },
           "sls": {
-            "$ref": "#/components/schemas/DSSLSConfig"
+            "$ref": "#/components/schemas/DSSLSConfig",
+            "description": "Settings for `type_ident` `sls`."
           },
           "victorialogs": {
-            "$ref": "#/components/schemas/DSVictoriaLogsConfig"
+            "$ref": "#/components/schemas/DSVictoriaLogsConfig",
+            "description": "Settings for `type_ident` `victorialogs`."
           },
           "tencent_cls": {
             "$ref": "#/components/schemas/DSTencentCLSConfig",
@@ -6624,23 +6776,28 @@
           },
           "kafka": {
             "$ref": "#/components/schemas/DSKafkaConfig",
-            "x-flashduty-preserve-absence": true
+            "x-flashduty-preserve-absence": true,
+            "description": "Settings for `type_ident` `kafka` (diagnostic-only)."
           },
           "mongodb_mongod": {
             "$ref": "#/components/schemas/DSMongoDBConfig",
-            "x-flashduty-preserve-absence": true
+            "x-flashduty-preserve-absence": true,
+            "description": "Settings for `type_ident` `mongodb_mongod` (diagnostic-only); same fields as `mongodb_mongos`."
           },
           "mongodb_mongos": {
             "$ref": "#/components/schemas/DSMongoDBConfig",
-            "x-flashduty-preserve-absence": true
+            "x-flashduty-preserve-absence": true,
+            "description": "Settings for `type_ident` `mongodb_mongos` (diagnostic-only); same fields as `mongodb_mongod`."
           },
           "redis_node": {
             "$ref": "#/components/schemas/DSRedisNodeConfig",
-            "x-flashduty-preserve-absence": true
+            "x-flashduty-preserve-absence": true,
+            "description": "Settings for `type_ident` `redis_node` (diagnostic-only)."
           },
           "redis_sentinel": {
             "$ref": "#/components/schemas/DSRedisSentinelConfig",
-            "x-flashduty-preserve-absence": true
+            "x-flashduty-preserve-absence": true,
+            "description": "Settings for `type_ident` `redis_sentinel` (diagnostic-only)."
           }
         }
       },
@@ -6708,11 +6865,11 @@
           },
           "basic_auth_username": {
             "type": "string",
-            "description": "Basic auth username."
+            "description": "Basic Auth username, effective when `basic_auth_enabled` is `true`."
           },
           "basic_auth_password": {
             "type": "string",
-            "description": "Basic auth password."
+            "description": "Basic Auth password, effective when `basic_auth_enabled` is `true`. Returned as stored in create, update and info responses."
           },
           "headers": {
             "type": "array",
@@ -6853,26 +7010,46 @@
           "edge_cluster_name",
           "updated_at",
           "payload",
-          "alerting_enabled"
+          "alerting_enabled",
+          "manage_team_id",
+          "readonly_team_ids",
+          "creator_id"
         ],
         "properties": {
           "id": {
             "type": "integer",
             "format": "uint64",
-            "description": "Unique datasource ID."
+            "description": "Unique datasource ID. Pass it as `id` to update, delete and info, and as `datasource_id` to tool invocation."
           },
           "account_id": {
             "type": "integer",
             "format": "uint64",
-            "description": "Account ID."
+            "description": "ID of the account that owns the datasource; always the caller's account."
           },
           "type_ident": {
             "type": "string",
-            "description": "Datasource type identifier. Allowed: `prometheus`, `loki`, `mysql`, `oracle`, `postgres`, `clickhouse`, `elasticsearch`, `sls`, `tencent_cls`, `victorialogs`, `redis_node`, `redis_sentinel`, `mongodb_mongod`, `mongodb_mongos`, `kafka`。"
+            "enum": [
+              "prometheus",
+              "loki",
+              "mysql",
+              "oracle",
+              "postgres",
+              "clickhouse",
+              "elasticsearch",
+              "sls",
+              "tencent_cls",
+              "victorialogs",
+              "redis_node",
+              "redis_sentinel",
+              "mongodb_mongod",
+              "mongodb_mongos",
+              "kafka"
+            ],
+            "description": "Datasource type.\n\nAlerting types (can evaluate alert rules):\n- `prometheus`: Prometheus-compatible metrics.\n- `loki`: Grafana Loki logs.\n- `mysql`: MySQL.\n- `oracle`: Oracle Database.\n- `postgres`: PostgreSQL.\n- `clickhouse`: ClickHouse.\n- `elasticsearch`: Elasticsearch.\n- `sls`: Alibaba Cloud Simple Log Service.\n- `tencent_cls`: Tencent Cloud Log Service (CLS).\n- `victorialogs`: VictoriaLogs.\n\nDiagnostic-only types (cannot evaluate alerts, `alerting_enabled` is always `false`):\n- `redis_node`: a single Redis node.\n- `redis_sentinel`: Redis Sentinel.\n- `mongodb_mongod`: a MongoDB mongod instance.\n- `mongodb_mongos`: a MongoDB mongos router.\n- `kafka`: a Kafka cluster.\n\nThe `payload` key that holds the type-specific settings has the same name as the type."
           },
           "name": {
             "type": "string",
-            "description": "Datasource display name."
+            "description": "Datasource name, unique within the account across all types."
           },
           "enabled": {
             "type": "boolean",
@@ -6880,11 +7057,11 @@
           },
           "note": {
             "type": "string",
-            "description": "Optional description."
+            "description": "Free-text note; an empty string when not set."
           },
           "address": {
             "type": "string",
-            "description": "Connection address. For Prometheus/Loki/VictoriaLogs: HTTP URL. For MySQL/Oracle/Postgres/ClickHouse: `host:port`. For SLS: endpoint without http/https prefix. Redis/MongoDB diagnostic types: one host:port, bracket IPv6; no URI, userinfo or query. Kafka: 1–32 unique comma-separated host:port bootstrap addresses; payload has no broker list. At most 4096 characters after normalization.",
+            "description": "Connection address as stored, after normalization. The format depends on `type_ident`; see the `address` field of the create request for each type. At most 4096 characters.",
             "maxLength": 4096
           },
           "payload": {
@@ -6910,6 +7087,41 @@
           "alerting_enabled": {
             "description": "Whether alert evaluation is allowed. Alerting also requires enabled=true and an alerting-capable type. Always false for diagnostic-only types; false does not block non-alerting queries or tools.",
             "type": "boolean"
+          },
+          "manage_team_id": {
+            "type": [
+              "integer",
+              "null"
+            ],
+            "format": "uint64",
+            "description": "ID of the managing team. Its members can edit, delete, enable or disable the datasource and view its full configuration. `null` means no managing team: any caller with the Datasources Manage permission can manage it. The creator, the account owner and Admin members can always manage."
+          },
+          "readonly_team_ids": {
+            "type": [
+              "array",
+              "null"
+            ],
+            "items": {
+              "type": "integer",
+              "format": "uint64"
+            },
+            "description": "IDs of the teams allowed to query and reference the datasource, in addition to the managing team, the creator, the account owner and Admin members. `null` or an empty array means every member of the account can query it."
+          },
+          "creator_id": {
+            "type": [
+              "integer",
+              "null"
+            ],
+            "format": "uint64",
+            "description": "ID of the member who created the datasource; `null` when not recorded. The creator can always manage the datasource."
+          },
+          "my_perm": {
+            "type": "string",
+            "enum": [
+              "manage",
+              "readonly"
+            ],
+            "description": "The caller's access level on this datasource. Only present in list responses.\n- `manage`: can edit, delete, enable or disable the datasource, view its configuration and query it.\n- `readonly`: can query and reference the datasource but not change it or read its configuration."
           }
         }
       },
@@ -6919,20 +7131,41 @@
         "properties": {
           "type": {
             "type": "string",
-            "description": "Datasource type identifier. Omit to return all types. Allowed: `prometheus`, `loki`, `mysql`, `oracle`, `postgres`, `clickhouse`, `elasticsearch`, `sls`, `tencent_cls`, `victorialogs`, `redis_node`, `redis_sentinel`, `mongodb_mongod`, `mongodb_mongos`, `kafka`。"
+            "description": "Return only datasources of this type; omit or leave empty to return all types. An unrecognized value matches nothing and returns an empty array.\n\nAlerting types (can evaluate alert rules):\n- `prometheus`: Prometheus-compatible metrics.\n- `loki`: Grafana Loki logs.\n- `mysql`: MySQL.\n- `oracle`: Oracle Database.\n- `postgres`: PostgreSQL.\n- `clickhouse`: ClickHouse.\n- `elasticsearch`: Elasticsearch.\n- `sls`: Alibaba Cloud Simple Log Service.\n- `tencent_cls`: Tencent Cloud Log Service (CLS).\n- `victorialogs`: VictoriaLogs.\n\nDiagnostic-only types (cannot evaluate alerts, `alerting_enabled` is always `false`):\n- `redis_node`: a single Redis node.\n- `redis_sentinel`: Redis Sentinel.\n- `mongodb_mongod`: a MongoDB mongod instance.\n- `mongodb_mongos`: a MongoDB mongos router.\n- `kafka`: a Kafka cluster.",
+            "enum": [
+              "prometheus",
+              "loki",
+              "mysql",
+              "oracle",
+              "postgres",
+              "clickhouse",
+              "elasticsearch",
+              "sls",
+              "tencent_cls",
+              "victorialogs",
+              "redis_node",
+              "redis_sentinel",
+              "mongodb_mongod",
+              "mongodb_mongos",
+              "kafka"
+            ]
+          },
+          "name": {
+            "type": "string",
+            "description": "Return only the datasource whose name equals this value exactly (names are unique within the account, so at most one item). Omit or leave empty for no name filter."
           }
         }
       },
       "DataSourceListResponse": {
         "type": "array",
-        "description": "List of datasources. The `payload` column is not read by this endpoint, so `payload` is `null` in every item.",
+        "description": "Datasources of the account that the caller can query, sorted by name; an empty array when nothing matches. `payload` is `null` in every item because the list does not read it; each item also carries `my_perm`.",
         "items": {
           "$ref": "#/components/schemas/DataSourceItem"
         }
       },
       "DataSourceUpsertRequest": {
         "type": "object",
-        "description": "Request body for creating or updating a datasource. `id` is required only for update. `address` is required for all types except Elasticsearch with `deployment=cloud`.",
+        "description": "Request body for creating or updating a datasource. `id` is required for update and ignored on create. An update replaces `type_ident`, `name`, `note`, `address`, `payload` and `edge_cluster_name` with the values sent, so resend them all; only `enabled`, `alerting_enabled`, `manage_team_id` and `readonly_team_ids` keep their current value when omitted. `address` is required for all types except Elasticsearch with `deployment=cloud`.",
         "required": [
           "type_ident",
           "name",
@@ -6943,32 +7176,49 @@
           "id": {
             "type": "integer",
             "format": "uint64",
-            "description": "Datasource ID. Required for update; omit for create."
+            "description": "Datasource ID. Required for update (an unknown ID, or one in another account, fails with `ResourceNotFound`); ignored on create."
           },
           "type_ident": {
             "type": "string",
-            "description": "Datasource type identifier. Allowed: `prometheus`, `loki`, `mysql`, `oracle`, `postgres`, `clickhouse`, `elasticsearch`, `sls`, `tencent_cls`, `victorialogs`, `redis_node`, `redis_sentinel`, `mongodb_mongod`, `mongodb_mongos`, `kafka`。"
+            "enum": [
+              "prometheus",
+              "loki",
+              "mysql",
+              "oracle",
+              "postgres",
+              "clickhouse",
+              "elasticsearch",
+              "sls",
+              "tencent_cls",
+              "victorialogs",
+              "redis_node",
+              "redis_sentinel",
+              "mongodb_mongod",
+              "mongodb_mongos",
+              "kafka"
+            ],
+            "description": "Datasource type.\n\nAlerting types (can evaluate alert rules):\n- `prometheus`: Prometheus-compatible metrics.\n- `loki`: Grafana Loki logs.\n- `mysql`: MySQL.\n- `oracle`: Oracle Database.\n- `postgres`: PostgreSQL.\n- `clickhouse`: ClickHouse.\n- `elasticsearch`: Elasticsearch.\n- `sls`: Alibaba Cloud Simple Log Service.\n- `tencent_cls`: Tencent Cloud Log Service (CLS).\n- `victorialogs`: VictoriaLogs.\n\nDiagnostic-only types (cannot evaluate alerts, `alerting_enabled` is always `false`):\n- `redis_node`: a single Redis node.\n- `redis_sentinel`: Redis Sentinel.\n- `mongodb_mongod`: a MongoDB mongod instance.\n- `mongodb_mongos`: a MongoDB mongos router.\n- `kafka`: a Kafka cluster.\n\nThe `payload` key that holds the type-specific settings has the same name as the type."
           },
           "name": {
             "type": "string",
-            "description": "Datasource display name. This is the name referenced as `ds_name` in query APIs."
+            "description": "Datasource name; required and unique within the account across all types. This is the name referenced as `ds_name` in query APIs. Duplicates fail with `InvalidParameter`."
           },
           "note": {
             "type": "string",
-            "description": "Optional description."
+            "description": "Free-text note. On update, an omitted or empty value clears the stored note."
           },
           "address": {
             "type": "string",
-            "description": "Connection address. Required for every type except `elasticsearch` with `deployment: cloud`. Prometheus/Loki/VictoriaLogs: HTTP URL; MySQL/Oracle/Postgres/ClickHouse: `host:port`; SLS: endpoint without the `http(s)://` prefix; `tencent_cls`: must be `cls.tencentcloudapi.com` or `cls.internal.tencentcloudapi.com` (requires Monitors edge >= v0.66.0). Redis/MongoDB diagnostic types: one host:port, bracket IPv6; no URI, userinfo or query. Kafka: 1–32 unique comma-separated host:port bootstrap addresses; payload has no broker list. At most 4096 characters after normalization.",
+            "description": "Connection address, required for every type except `elasticsearch` with `deployment: cloud`. At most 4096 characters after normalization. Format by type:\n- `prometheus`, `loki`, `victorialogs`: HTTP URL; `http://` is prepended when the value does not start with `http`.\n- `mysql`, `oracle`, `postgres`: `host:port`.\n- `clickhouse`: one or more comma-separated `host:port` endpoints; duplicates are rejected.\n- `elasticsearch` with `self-managed`: one or more comma-separated HTTP(S) URLs (scheme defaults to `http://`) that share identical query parameters; duplicates are rejected. Not needed for `cloud`.\n- `sls`: endpoint without the `http://` or `https://` prefix.\n- `tencent_cls`: exactly `cls.tencentcloudapi.com` or `cls.internal.tencentcloudapi.com` (requires Monitors edge >= v0.66.0).\n- `redis_node`, `redis_sentinel`, `mongodb_mongod`, `mongodb_mongos`: a single `host:port` (bracket IPv6) with no URI, userinfo or query.\n- `kafka`: 1-32 unique comma-separated `host:port` bootstrap addresses (the payload has no broker list).",
             "maxLength": 4096
           },
           "payload": {
             "$ref": "#/components/schemas/DSPayload",
-            "description": "Type-specific configuration block. Must include the key matching `type_ident`. For diagnostic types, password and Kafka tls_key are omitted from responses unless they are ${env:...} references. On update, omit those fields to preserve stored secrets; explicitly send an empty string to clear. Other configuration fields retain their existing behavior."
+            "description": "Type-specific configuration block; must include the key named by `type_ident`. An update replaces the whole payload, so resend every setting you want to keep (including credentials of non-diagnostic types, which the info endpoint returns). Exceptions: for the diagnostic types, omit the password (and the Kafka `tls_key`) to keep the stored value or send an empty string to clear it; for `tencent_cls`, an omitted or empty `secret_key` keeps the stored key. Stored secrets are not carried over when `type_ident` changes."
           },
           "edge_cluster_name": {
             "type": "string",
-            "description": "Monitors edge cluster name responsible for evaluating rules using this datasource."
+            "description": "Name of the Monitors edge cluster that evaluates rules and runs queries for this datasource. It must be an existing edge cluster of the account, otherwise the call fails with `InvalidParameter`. Changing it on update closes open alerts of rules that use this datasource."
           },
           "enabled": {
             "type": "boolean",
@@ -6979,6 +7229,27 @@
             "description": "Whether this datasource may evaluate alerts. Omitted on create: true for alerting types, false for diagnostic-only types; omitted on update: preserve current value. null is invalid. redis_node, redis_sentinel, mongodb_mongod, mongodb_mongos and kafka reject true. Disabling is rejected with conflict when enabled rules reference the datasource.",
             "type": "boolean",
             "x-flashduty-preserve-absence": true
+          },
+          "manage_team_id": {
+            "type": [
+              "integer",
+              "null"
+            ],
+            "format": "uint64",
+            "description": "ID of the managing team (see the response field of the same name). On create, omitted means no managing team. On update, omitted keeps the current value, while `null` or `0` clears it. Required whenever `readonly_team_ids` is non-empty.",
+            "x-flashduty-preserve-absence": true
+          },
+          "readonly_team_ids": {
+            "type": [
+              "array",
+              "null"
+            ],
+            "items": {
+              "type": "integer",
+              "format": "uint64"
+            },
+            "description": "IDs of the teams allowed to query and reference the datasource (see the response field of the same name). On create, omitted means unrestricted. On update, omitted keeps the current value, while `null` or an empty array clears it (everyone can query). Duplicates and `0` are dropped. Requires `manage_team_id`: a non-empty list without a managing team fails with `InvalidParameter`.",
+            "x-flashduty-preserve-absence": true
           }
         }
       },
@@ -6991,7 +7262,7 @@
           },
           "message": {
             "type": "string",
-            "description": "Human-readable error message, localized by the caller's Accept-Language. May contain field names, IDs, or other context from the failing request.",
+            "description": "Human-readable error message in the response language (`locale` / `lang` query parameter or `Accept-Language` header). May name the offending field; do not parse it.",
             "example": "The specified parameter template_id is not valid."
           },
           "reason": {
@@ -7007,7 +7278,7 @@
       },
       "EmptyResponse": {
         "type": "object",
-        "description": "Empty response body. The server returns `data: null` on success.",
+        "description": "No payload. Depending on the operation, `data` is `{}` or omitted from the envelope; rely only on the HTTP 200 status and the absence of `error`.",
         "properties": {}
       },
       "EnabledTime": {
@@ -7019,21 +7290,21 @@
             "items": {
               "type": "integer"
             },
-            "description": "Days of week, 0 = Sunday."
+            "description": "Days of week the window applies to, `0` = Sunday through `6` = Saturday; non-empty, no duplicates."
           },
           "stime": {
             "type": "string",
-            "description": "Start time, e.g. `09:00`."
+            "description": "Start time in 24-hour `HH:MM` format, e.g. `09:00`."
           },
           "etime": {
             "type": "string",
-            "description": "End time, e.g. `18:00`."
+            "description": "End time in 24-hour `HH:MM` format, e.g. `18:00`."
           }
         }
       },
       "ErrorCode": {
         "type": "string",
-        "description": "Flashduty error code enum. Every failed API response sets `error.code` to one of these stable wire strings. HTTP status is informational — the authoritative signal is the enum value.\n\n| Code | HTTP | Meaning |\n|---|---|---|\n| `OK` | 200 | Reserved — not returned on real errors. |\n| `InvalidParameter` | 400 | A required parameter is missing or failed validation. |\n| `BadRequest` | 400 | Generic 400 used when no more specific code fits. |\n| `InvalidContentType` | 400 | The `Content-Type` header is not `application/json`. |\n| `ResourceNotFound` | 400 | The referenced resource does not exist. Note: returned as HTTP 400, not 404 (historical choice). |\n| `NoLicense` | 400 | The feature is license-gated and no active license was found. |\n| `ReferenceExist` | 400 | Deletion blocked — other entities still reference this resource. |\n| `Unauthorized` | 401 | `app_key` is missing, invalid, or expired. |\n| `BalanceNotEnough` | 402 | Billing-gated operation with insufficient account balance. |\n| `AccessDenied` | 403 | Authenticated but lacking the permission required for this operation. |\n| `RouteNotFound` | 404 | The request URL path is not a known route. |\n| `MethodNotAllowed` | 405 | The HTTP method is not allowed on this otherwise-known path. |\n| `UndonedOrderExist` | 409 | An outstanding billing order blocks this new one. Wait and retry. |\n| `RequestLocked` | 423 | Operation temporarily locked due to repeated failures. |\n| `EntityTooLarge` | 413 | Request body exceeds the configured max size. |\n| `RequestTooFrequently` | 429 | Rate limit hit — API-global, per-account, or per-integration. |\n| `RequestVerifyRequired` | 428 | Second-factor verification required but not supplied. |\n| `DangerousOperation` | 428 | High-risk operation requires MFA verification. |\n| `InternalError` | 500 | Unhandled server-side error. Include `request_id` in the bug report. |\n| `ServiceUnavailable` | 503 | A backend dependency is unavailable. Try again later. |",
+        "description": "Error code. Every failed response sets `error.code` to one of these stable strings; branch on it rather than on the HTTP status.\n\n| Code | HTTP | Meaning |\n|---|---|---|\n| `OK` | 200 | Reserved; never returned on a failed request. |\n| `InvalidParameter` | 400 | A parameter is missing, has the wrong type, or failed validation; `message` usually names the field. |\n| `BadRequest` | 400 | The request breaks a business rule or conflicts with the current state of an object; `message` says which. |\n| `InvalidContentType` | 400 | The body is not sent as `application/json`. |\n| `ResourceNotFound` | 400 | The referenced object does not exist in this account or was deleted. Returned as HTTP 400, not 404. |\n| `NoLicense` | 400 | The account's plan does not include the feature, a plan quota is used up, the plan has expired, or credits are insufficient. |\n| `ReferenceExist` | 400 | The object is still referenced by other objects, so it cannot be deleted. |\n| `Unauthorized` | 401 | The APP Key is missing, invalid, or deleted. |\n| `BalanceNotEnough` | 402 | Console-only (billing); not returned by Open API operations. |\n| `AccessDenied` | 403 | The APP Key's permission scope or the creator's role does not allow this operation or object. |\n| `RouteNotFound` | 404 | No operation matches the HTTP method and path. |\n| `MethodNotAllowed` | 405 | The path exists but not for this HTTP method. |\n| `UndonedOrderExist` | 409 | Console-only (billing); not returned by Open API operations. |\n| `EntityTooLarge` | 413 | The request body exceeds the size limit. |\n| `RequestLocked` | 423 | Console-only (sign-in protection); not returned by Open API operations. |\n| `RequestVerifyRequired` | 428 | Console-only (verification code); not returned by Open API operations. |\n| `DangerousOperation` | 428 | Console-only (MFA for high-risk actions); not returned by Open API operations. |\n| `RequestTooFrequently` | 429 | A rate limit was hit; wait for the `Flashcat-Request-Rate-Limit-Delay` response header (seconds) before retrying. |\n| `InternalError` | 500 | Unexpected server error; retry with backoff and include `request_id` when reporting. |\n| `ServiceUnavailable` | 503 | A backend dependency is overloaded or unavailable; retry with backoff. |",
         "enum": [
           "OK",
           "InvalidParameter",
@@ -7048,35 +7319,35 @@
           "RouteNotFound",
           "MethodNotAllowed",
           "UndonedOrderExist",
-          "RequestLocked",
           "EntityTooLarge",
-          "RequestTooFrequently",
+          "RequestLocked",
           "RequestVerifyRequired",
           "DangerousOperation",
+          "RequestTooFrequently",
           "InternalError",
           "ServiceUnavailable"
         ],
         "x-enumDescriptions": {
-          "OK": "Reserved — not returned on real errors.",
-          "InvalidParameter": "A required parameter is missing or failed validation.",
-          "BadRequest": "Generic 400 used when no more specific code fits.",
-          "InvalidContentType": "The `Content-Type` header is not `application/json`.",
-          "ResourceNotFound": "The referenced resource does not exist. Note: returned as HTTP 400, not 404 (historical choice).",
-          "NoLicense": "The feature is license-gated and no active license was found.",
-          "ReferenceExist": "Deletion blocked — other entities still reference this resource.",
-          "Unauthorized": "`app_key` is missing, invalid, or expired.",
-          "BalanceNotEnough": "Billing-gated operation with insufficient account balance.",
-          "AccessDenied": "Authenticated but lacking the permission required for this operation.",
-          "RouteNotFound": "The request URL path is not a known route.",
-          "MethodNotAllowed": "The HTTP method is not allowed on this otherwise-known path.",
-          "UndonedOrderExist": "An outstanding billing order blocks this new one. Wait and retry.",
-          "RequestLocked": "Operation temporarily locked due to repeated failures.",
-          "EntityTooLarge": "Request body exceeds the configured max size.",
-          "RequestTooFrequently": "Rate limit hit — API-global, per-account, or per-integration.",
-          "RequestVerifyRequired": "Second-factor verification required but not supplied.",
-          "DangerousOperation": "High-risk operation requires MFA verification.",
-          "InternalError": "Unhandled server-side error. Include `request_id` in the bug report.",
-          "ServiceUnavailable": "A backend dependency is unavailable. Try again later."
+          "OK": "Reserved; never returned on a failed request.",
+          "InvalidParameter": "A parameter is missing, has the wrong type, or failed validation; `message` usually names the field.",
+          "BadRequest": "The request breaks a business rule or conflicts with the current state of an object; `message` says which.",
+          "InvalidContentType": "The body is not sent as `application/json`.",
+          "ResourceNotFound": "The referenced object does not exist in this account or was deleted. Returned as HTTP 400, not 404.",
+          "NoLicense": "The account's plan does not include the feature, a plan quota is used up, the plan has expired, or credits are insufficient.",
+          "ReferenceExist": "The object is still referenced by other objects, so it cannot be deleted.",
+          "Unauthorized": "The APP Key is missing, invalid, or deleted.",
+          "BalanceNotEnough": "Console-only (billing); not returned by Open API operations.",
+          "AccessDenied": "The APP Key's permission scope or the creator's role does not allow this operation or object.",
+          "RouteNotFound": "No operation matches the HTTP method and path.",
+          "MethodNotAllowed": "The path exists but not for this HTTP method.",
+          "UndonedOrderExist": "Console-only (billing); not returned by Open API operations.",
+          "EntityTooLarge": "The request body exceeds the size limit.",
+          "RequestLocked": "Console-only (sign-in protection); not returned by Open API operations.",
+          "RequestVerifyRequired": "Console-only (verification code); not returned by Open API operations.",
+          "DangerousOperation": "Console-only (MFA for high-risk actions); not returned by Open API operations.",
+          "RequestTooFrequently": "A rate limit was hit; wait for the `Flashcat-Request-Rate-Limit-Delay` response header (seconds) before retrying.",
+          "InternalError": "Unexpected server error; retry with backoff and include `request_id` when reporting.",
+          "ServiceUnavailable": "A backend dependency is overloaded or unavailable; retry with backoff."
         },
         "example": "InvalidParameter"
       },
@@ -7122,11 +7393,11 @@
         "properties": {
           "name": {
             "type": "string",
-            "description": "Rule name."
+            "description": "Name of the rule this result belongs to; `id: <id>` when the rule ID does not exist."
           },
           "message": {
             "type": "string",
-            "description": "Empty on success, error message on failure."
+            "description": "Outcome for this rule. On success it is empty for `/monit/rule/update/fields` and a localized success text (`Move successfully` / `移动成功`) for `/monit/rule/move`; on failure it carries the error message."
           }
         }
       },
@@ -7424,7 +7695,7 @@
               "type": "integer",
               "format": "uint64"
             },
-            "description": "Rule IDs to update."
+            "description": "IDs of the rules to update; must contain at least one ID."
           },
           "fields": {
             "type": "array",
@@ -7448,18 +7719,18 @@
                 "repeat_total"
               ]
             },
-            "description": "Field names to update. Only listed fields are updated, taking new values from the same-named request fields; values for unlisted fields are silently ignored."
+            "description": "Names of the fields to update. Each listed field takes the value of the same-named request field, and is set to its zero value when that value is omitted; values sent for unlisted fields are ignored. An unknown name fails the whole call with `InvalidParameter`."
           },
           "labels": {
             "type": "object",
             "additionalProperties": {
               "type": "string"
             },
-            "description": "Custom label key-value pairs; replaces existing labels as a whole. Effective only when `fields` includes `labels`."
+            "description": "Custom label key-value pairs; replaces existing labels as a whole. Effective only when `fields` includes `labels`; cannot be sent together with `labels_patch`."
           },
           "ds_type": {
             "type": "string",
-            "description": "Datasource type identifier. Effective only when `fields` includes `ds_type`."
+            "description": "Datasource type identifier. Enabled rules must use a type that supports alerting: `prometheus`, `elasticsearch`, `loki`, `clickhouse`, `mysql`, `oracle`, `postgres`, `sls`, `tencent_cls`, `victorialogs`. Effective only when `fields` includes `ds_type`."
           },
           "ds_list": {
             "type": "array",
@@ -7490,7 +7761,7 @@
           },
           "timezone": {
             "type": "string",
-            "description": "Timezone in which the rule executes. IANA timezone name; defaults to `Asia/Shanghai`.",
+            "description": "Timezone the rule runs in, as an IANA name (e.g. `Asia/Shanghai`, `UTC`); empty falls back to `Asia/Shanghai`. Effective only when `fields` includes `timezone`.",
             "default": "Asia/Shanghai"
           },
           "delay_seconds": {
@@ -7509,11 +7780,11 @@
             "additionalProperties": {
               "type": "string"
             },
-            "description": "Annotation key-value pairs delivered with alert events; keys must not start with `$` (reserved for query fields). Effective only when `fields` includes `annotations`."
+            "description": "Annotation key-value pairs delivered with alert events; replaces existing annotations as a whole, and keys must not start with `$` (reserved for query fields). Effective only when `fields` includes `annotations`; cannot be sent together with `annotations_patch`."
           },
           "description": {
             "type": "string",
-            "description": "Rule description (Markdown). Effective only when `fields` includes `description`."
+            "description": "Rule description, rendered according to the rule's existing `description_type` (which this endpoint cannot change). Effective only when `fields` includes `description`."
           },
           "channel_ids": {
             "type": "array",
@@ -7526,20 +7797,20 @@
           "repeat_interval": {
             "type": "integer",
             "format": "int64",
-            "description": "Interval in seconds between repeated alert notifications. Effective only when `fields` includes `repeat_interval`."
+            "description": "Interval in seconds between repeated alert notifications; values below 1 fall back to 3600, maximum 2147483647. Effective only when `fields` includes `repeat_interval`."
           },
           "repeat_total": {
             "type": "integer",
             "format": "int64",
-            "description": "Maximum number of repeated notifications. Effective only when `fields` includes `repeat_total`."
+            "description": "Maximum number of repeated notifications; values below 1 fall back to 3, maximum 2147483647. Effective only when `fields` includes `repeat_total`."
           },
           "labels_patch": {
             "$ref": "#/components/schemas/StringMapPatch",
-            "description": "Partial label update. Effective only when `fields` includes `labels`; takes precedence over `labels` when both are sent."
+            "description": "Partial label update that keeps unmentioned labels. Requires `labels` in `fields` and cannot be sent together with `labels`; otherwise the call returns `InvalidParameter`."
           },
           "annotations_patch": {
             "$ref": "#/components/schemas/StringMapPatch",
-            "description": "Partial annotation update. Effective only when `fields` includes `annotations`; takes precedence over `annotations` when both are sent."
+            "description": "Partial annotation update that keeps unmentioned annotations. Requires `annotations` in `fields` and cannot be sent together with `annotations`; otherwise the call returns `InvalidParameter`."
           }
         }
       },
@@ -7565,7 +7836,7 @@
           "id": {
             "type": "integer",
             "format": "uint64",
-            "description": "Audit record ID — the `id` of an audit row returned by `POST /monit/rule/audits`, NOT the rule ID. Passing a rule ID returns HTTP 400."
+            "description": "Audit record ID — the `id` of a row returned by `POST /monit/rule/audits`, not the rule ID. A rule ID is looked up as an audit record ID, which usually returns `InvalidParameter` (`alert rule audit not found`) or an unrelated record."
           }
         }
       },
@@ -7581,7 +7852,7 @@
               "type": "integer",
               "format": "uint64"
             },
-            "description": "Rule IDs."
+            "description": "IDs of the alert rules to delete; must contain at least one ID. Get them from `POST /monit/rule/list/basic`."
           }
         }
       },
@@ -7606,15 +7877,15 @@
           "folder_id": {
             "type": "integer",
             "format": "uint64",
-            "description": "Folder ID. Must be an existing folder; `0` is rejected with a `folder_not_found` error."
+            "description": "ID of the folder to list. Must be an existing folder the caller can manage; `0` or an unknown ID returns `InvalidParameter`."
           },
           "include_descendants": {
             "type": "boolean",
-            "description": "Also include rules from all descendant folders. When `true`, each returned item carries only `id`, `folder_id` and `name`; combine with `query` / `limit` for rule-picker scenarios."
+            "description": "Also search all descendant folders. When `true`, results are sorted by name, capped by `limit`, and each item fills only `id`, `folder_id` and `name` (other fields carry zero values); combine with `query` for rule-picker scenarios."
           },
           "query": {
             "type": "string",
-            "description": "Rule name fuzzy filter; only effective when `include_descendants` is `true`."
+            "description": "Filter by rule name substring; a numeric value also matches the rule with that ID. Only effective when `include_descendants` is `true`."
           },
           "limit": {
             "type": "integer",
@@ -7637,12 +7908,12 @@
               "type": "integer",
               "format": "uint64"
             },
-            "description": "Rule IDs to move."
+            "description": "IDs of the rules to move; must contain at least one ID."
           },
           "dest_folder_id": {
             "type": "integer",
             "format": "uint64",
-            "description": "Destination folder ID. Obtainable via `POST /monit/folder/list`."
+            "description": "Destination folder ID, from `POST /monit/folder/list`. Must be non-zero; a folder that does not exist or that the caller cannot manage fails the whole call with `AccessDenied`."
           }
         }
       },
@@ -7748,16 +8019,15 @@
             "example": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
           },
           "data": {
-            "description": "Endpoint-specific payload. See each operation's 200 response schema."
+            "description": "Operation-specific payload, documented in each operation's 200 response. Operations without a payload return `{}` or omit `data` entirely."
           }
         },
         "required": [
-          "request_id",
-          "data"
+          "request_id"
         ]
       },
       "QueryDataRequest": {
-        "description": "Request for the stable structured query endpoint. It accepts the same query fields as the retired rows endpoint.",
+        "description": "Request body of the structured query endpoint.",
         "allOf": [
           {
             "$ref": "#/components/schemas/QueryRowsRequest"
@@ -7999,33 +8269,49 @@
           "account_id": {
             "type": "integer",
             "format": "int64",
-            "description": "Optional consistency check. Must equal the authenticated account when supplied; mismatched values are rejected. Business execution always uses the authenticated account."
+            "description": "Optional consistency check. When supplied it must equal the authenticated account, otherwise the request fails with `AccessDenied`. The query always runs as the authenticated account."
           },
           "ds_type": {
             "type": "string",
-            "description": "Data source type; must match a configured data source under the tenant. Examples: `prometheus`, `loki`, `victorialogs`, `sls`, `elasticsearch`, `mysql`, `postgres`, `oracle`, `clickhouse`."
+            "description": "Data source type. Together with `ds_name` it must match an enabled data source of the account.\n\n- `prometheus`: Prometheus-compatible data source; `expr` is PromQL.\n- `loki`: Grafana Loki; `expr` is LogQL.\n- `victorialogs`: VictoriaLogs.\n- `sls`: Alibaba Cloud Log Service (SLS).\n- `tencent_cls`: Tencent Cloud Log Service (CLS); requires monit-edge v0.66.0 or later.\n- `elasticsearch`: Elasticsearch.\n- `mysql`: MySQL; `expr` is SQL.\n- `postgres`: PostgreSQL; `expr` is SQL.\n- `oracle`: Oracle Database; `expr` is SQL.\n- `clickhouse`: ClickHouse; `expr` is SQL.\n\nOther data source types (for example MongoDB, Redis, or Kafka) are rejected.",
+            "enum": [
+              "clickhouse",
+              "elasticsearch",
+              "loki",
+              "mysql",
+              "oracle",
+              "postgres",
+              "prometheus",
+              "sls",
+              "tencent_cls",
+              "victorialogs"
+            ]
           },
           "ds_name": {
             "type": "string",
-            "description": "Data source name; must match a configured data source under the tenant."
+            "description": "Data source name, as returned by `/monit/datasource/list`. The data source must be enabled; a name that matches no data source of the account returns HTTP 400."
           },
           "expr": {
             "type": "string",
-            "description": "Query expression. Syntax depends on `ds_type` and is interpreted by the corresponding monit-edge client (PromQL for Prometheus, LogQL for Loki, SQL for SQL sources, etc.)."
+            "description": "Query expression in the language of `ds_type` (PromQL for `prometheus`, LogQL for `loki`, SQL for SQL sources, and so on). Required, at most 64 KiB (12 KiB for `tencent_cls`). Loki's `$__auto` is not supported here; use a fixed duration such as `[5m]`. Prometheus expressions are syntax-checked before dispatch.",
+            "minLength": 1
           },
           "delay_seconds": {
             "type": "integer",
-            "description": "Look-back offset in seconds applied to point-in-time queries (Prometheus, Loki stats, VictoriaLogs stats). Ignored for raw / detail queries.",
-            "default": 0
+            "description": "Look-back offset in seconds, from 0 to 86400. Applied to point-in-time queries (Prometheus, Loki stats, VictoriaLogs stats); ignored for raw and detail queries. When `args` carries an absolute `<source>.time` and the Edge is v0.74.0 or later, the absolute time takes precedence and this offset is not applied.",
+            "default": 0,
+            "minimum": 0,
+            "maximum": 86400
           },
           "args": {
             "type": "object",
-            "description": "Polymorphic key/value extension parameters forwarded verbatim to monit-edge. All values must be strings, and keys are always namespaced by source (e.g. `sls.project`, `loki.type`). Validation depends on `ds_type`: SLS requires `sls.project` + `sls.logstore`. Elasticsearch accepts `es.type` of `sql`, or omitted — any other value is rejected. Loki and VictoriaLogs accept `<source>.type` of `stats`, `raw`, or omitted; `raw` additionally requires a time range, either `<source>.start` + `<source>.end` or `<source>.timespan.value` + `<source>.timespan.unit` (unit one of `s`, `m`, `h`, `d`). Prometheus and the remaining SQL sources ignore `args` entirely.",
+            "description": "Extra query parameters as string key/value pairs; keys are namespaced by data source (for example `sls.project`, `loki.type`). At most 128 entries, keys up to 256 bytes, values up to 64 KiB, and 128 KiB in total. What is accepted depends on `ds_type`:\n\n- `prometheus`: optional `prometheus.time`, the evaluation time as Unix seconds, not in the future.\n- `loki`, `victorialogs`: `<source>.type` is `stats` (default) or `raw`. `stats` accepts an optional `<source>.time` (Unix seconds, not in the future). `raw` requires a time range, either `<source>.start` + `<source>.end` (Unix seconds) or `<source>.timespan.value` + `<source>.timespan.unit` (`s`, `m`, `h`, or `d`), spanning at most 6 hours, and accepts `<source>.limit` from 1 to 1001.\n- `sls`: `sls.project` and `sls.logstore` are required. Optional: `sls.lines` (1 to 100), `sls.offset` (0 or more), and a time range of at most 6 hours given as `sls.from` + `sls.to` (Unix seconds) or `sls.timespan.value` + `sls.timespan.unit`.\n- `tencent_cls`: `tencent_cls.region`, `tencent_cls.topic_id`, `tencent_cls.query_mode` (`raw` or `analysis`), and `tencent_cls.syntax` (`cql` or `lucene`) are required. Optional: `tencent_cls.limit` (1 to 100, `raw` mode only, needs monit-edge v0.67.0 or later) and a time range given as `tencent_cls.from` + `tencent_cls.to` (Unix seconds) or `tencent_cls.timespan.value` + `tencent_cls.timespan.unit`, at most 6 hours in `raw` mode and 24 hours in `analysis` mode. Any other key is rejected.\n- `elasticsearch`: `es.type` may be `sql` or omitted; any other value is rejected.\n- `mysql`, `postgres`, `oracle`, `clickhouse`: no arguments are defined.\n\nAn absolute `<source>.time` is only valid for its own data source type. Edges older than v0.74.0 approximate it with a look-back offset and accept only times within the last 86,400 seconds.",
             "additionalProperties": {
               "type": "string"
             }
           }
-        }
+        },
+        "description": "Query to run. `ds_type` and `ds_name` together select the data source; `expr` and `args` are interpreted by that data source type."
       },
       "DSTencentCLSConfig": {
         "type": "object",
@@ -8101,7 +8387,7 @@
       },
       "StringMapPatch": {
         "type": "object",
-        "description": "Partial update for a map field: keys in `set` are inserted or replaced, keys in `delete` are removed, all other keys are preserved.",
+        "description": "Partial update for a map field: keys in `set` are inserted or replaced, keys in `delete` are removed, all other keys are preserved. At least one of `set` / `delete` must be non-empty, keys must not be blank, and a key may not appear in both or twice in `delete`.",
         "properties": {
           "set": {
             "type": "object",
@@ -8123,7 +8409,7 @@
         "description": "Diagnostic datasource connection configuration.",
         "properties": {
           "password": {
-            "description": "Authentication password; supports ${env:NAME}. Omit on update to preserve; explicitly send an empty string to clear. Literal passwords are omitted from responses.",
+            "description": "Authentication password; supports ${env:NAME}. Required with `username` for SASL authentication and must be empty when `sasl_mechanism` is `none`. On update, omit to keep the stored password; explicitly send an empty string to clear. Literal passwords are omitted from responses.",
             "type": "string",
             "x-flashduty-preserve-absence": true
           },
@@ -8155,7 +8441,7 @@
           },
           "tls_enabled": {
             "default": false,
-            "description": "Whether TLS is enabled; defaults to false.",
+            "description": "Whether TLS is enabled; defaults to false. When false, all `tls_*` fields are cleared on save.",
             "type": "boolean"
           },
           "tls_key": {
@@ -8180,7 +8466,7 @@
             "type": "boolean"
           },
           "username": {
-            "description": "Authentication username; an ${env:NAME} reference is supported.",
+            "description": "Authentication username; an ${env:NAME} reference is supported. Required when `sasl_mechanism` is `plain`, `scram-sha-256` or `scram-sha-512`; must be empty when it is `none`.",
             "type": "string"
           }
         },
@@ -8212,7 +8498,7 @@
           },
           "tls_enabled": {
             "default": false,
-            "description": "Whether TLS is enabled; defaults to false.",
+            "description": "Whether TLS is enabled; defaults to false. When false, all `tls_*` fields are cleared on save.",
             "type": "boolean"
           },
           "tls_max_version": {
@@ -8232,7 +8518,7 @@
             "type": "boolean"
           },
           "username": {
-            "description": "Authentication username; an ${env:NAME} reference is supported.",
+            "description": "Authentication username; an ${env:NAME} reference is supported. Must be configured together with `password`.",
             "type": "string"
           }
         },
@@ -8260,7 +8546,7 @@
             "type": "integer"
           },
           "username": {
-            "description": "Authentication username; an ${env:NAME} reference is supported.",
+            "description": "Authentication username; an ${env:NAME} reference is supported. When set, `password` is required (on update, omit `password` to keep the stored one).",
             "type": "string"
           }
         },
@@ -8282,7 +8568,7 @@
             "type": "integer"
           },
           "username": {
-            "description": "Authentication username; an ${env:NAME} reference is supported.",
+            "description": "Authentication username; an ${env:NAME} reference is supported. When set, `password` is required (on update, omit `password` to keep the stored one).",
             "type": "string"
           }
         },
@@ -8608,7 +8894,7 @@
             "type": "integer"
           },
           "datasource_id": {
-            "description": "Datasource ID from /monit/datasource/list.",
+            "description": "ID of the datasource to run the tool against, from `/monit/datasource/list`. The caller needs query access to it. For query tools (`<type>.query`) the ID must not exceed 9007199254740991.",
             "format": "uint64",
             "minimum": 1,
             "type": "integer"
@@ -8671,7 +8957,7 @@
       "DatasourceToolTruncation": {
         "properties": {
           "reason": {
-            "description": "Why the result was truncated. Presence of this object indicates truncation.",
+            "description": "Why the result was truncated, as reported by the executing Edge; treat it as an opaque string. The object is present only when the result was truncated.",
             "type": "string"
           }
         },
@@ -8695,12 +8981,12 @@
             "format": "int64",
             "minimum": 1,
             "maximum": 9007199254740991,
-            "description": "Data source ID from `/monit/datasource/list`. Must be a positive JavaScript-safe integer and belong to the authenticated account."
+            "description": "Data source ID from `/monit/datasource/list`. Must be a positive JavaScript-safe integer for an enabled data source of the authenticated account that the caller may query."
           },
           "expr": {
             "type": "string",
             "minLength": 1,
-            "description": "Query expression in the data source's native language (PromQL, LogsQL, SQL, and so on). Non-empty UTF-8 of at most 64 KiB; some data source types enforce a lower limit."
+            "description": "Query expression in the data source's native language (PromQL, LogsQL, SQL, and so on). Non-empty UTF-8 of at most 64 KiB; `mysql` allows at most 16 KiB and `tencent_cls` at most 12 KiB."
           },
           "args": {
             "type": "object",
@@ -8717,7 +9003,7 @@
       },
       "QueryExploreExecution": {
         "type": "object",
-        "description": "Time semantics of the query. The accepted companion fields depend on `kind`: `instant` takes only `to_ms` (plus optional `from_ms`), `range` requires `from_ms`, `to_ms`, and `max_data_points`, and `window` takes only `from_ms` and `to_ms`. `step_seconds` is never accepted over HTTP.",
+        "description": "Time semantics of the query. The accepted companion fields depend on `kind`: `instant` takes `to_ms` (and optionally `from_ms`), `range` requires `from_ms`, `to_ms`, and `max_data_points`, and `window` takes only `from_ms` and `to_ms`. When both times are present, `from_ms` must be less than `to_ms`. `step_seconds` is never accepted over HTTP.",
         "required": [
           "kind"
         ],
@@ -8729,17 +9015,19 @@
               "range",
               "window"
             ],
-            "description": "Execution kind. `instant` evaluates at a single point in time, `range` evaluates a series over a range, and `window` returns raw rows inside a time window."
+            "description": "Execution kind.\n\n- `instant`: evaluate at a single point in time.\n- `range`: evaluate a series over `from_ms` to `to_ms`, with a step derived from `max_data_points` and `min_step_seconds`.\n- `window`: query the interval from `from_ms` to `to_ms` with no step."
           },
           "from_ms": {
             "type": "integer",
             "format": "int64",
-            "description": "Unix timestamp in milliseconds for the start of the range. Required for `range` and `window`; optional for `instant`."
+            "description": "Start of the interval as a Unix timestamp in milliseconds; non-negative and less than `to_ms`. Required for `range` and `window`; optional for `instant`.",
+            "minimum": 0
           },
           "to_ms": {
             "type": "integer",
             "format": "int64",
-            "description": "Unix timestamp in milliseconds for the end of the range. Required for every execution kind."
+            "description": "End of the interval (or the evaluation time for `instant`) as a Unix timestamp in milliseconds; non-negative. Required for every execution kind.",
+            "minimum": 0
           },
           "max_data_points": {
             "type": "integer",
@@ -8800,7 +9088,7 @@
             "items": {
               "$ref": "#/components/schemas/ExploreFrame"
             },
-            "description": "Columnar frames. Present when `kind` is `frames`; at most 1,000 frames."
+            "description": "Columnar frames. Present when `kind` is `frames`; at most 1,000 frames, 1,000 table rows in total, and 100,000 values in total."
           },
           "samples": {
             "type": "array",
@@ -8818,7 +9106,7 @@
           },
           "applied_limit": {
             "type": "integer",
-            "description": "Entry limit applied to a logs result; at most 1000."
+            "description": "Entry limit applied to a logs result: 1 to 1000 (1 to 100 for `sls` data sources). Present only when `kind` is `logs`."
           },
           "has_more": {
             "type": "boolean",
@@ -8840,7 +9128,7 @@
               "table",
               "time_series"
             ],
-            "description": "Frame shape. `table` is an unlabeled table, while `time_series` carries exactly one time field and one float field."
+            "description": "Frame shape. `table` is an unlabeled table. `time_series` carries exactly one time field and one float field; its time values are strictly increasing and never null."
           },
           "fields": {
             "type": "array",
@@ -8883,6 +9171,17 @@
           "values": {
             "type": "array",
             "items": {
+              "oneOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "number"
+                },
+                {
+                  "type": "null"
+                }
+              ],
               "description": "One cell. `time` cells are UTC RFC3339Nano strings; `float` cells may be the strings `NaN`, `+Inf`, and `-Inf`; any cell may be null except a time value inside a `time_series` frame."
             },
             "description": "Column values in row order."
@@ -8905,6 +9204,14 @@
             "description": "Label set of the sample. May be empty but never null."
           },
           "value": {
+            "oneOf": [
+              {
+                "type": "number"
+              },
+              {
+                "type": "string"
+              }
+            ],
             "description": "Sample value: a number, or one of the strings `NaN`, `+Inf`, and `-Inf`. Never null."
           }
         }
@@ -9011,11 +9318,11 @@
             "additionalProperties": {
               "type": "string"
             },
-            "description": "Custom labels."
+            "description": "Custom labels added to every alert event of the rule. Keys are trimmed, must not be empty and must not start with `__alert_rule_` (reserved); values containing `{{` are rendered as templates when events are delivered; `job` and `instance` values are limited to 255 characters. The serialized object may not exceed 1024 characters."
           },
           "ds_type": {
             "type": "string",
-            "description": "Datasource type identifier (e.g. `prometheus`, `elasticsearch`)."
+            "description": "Datasource type the rule queries. When the rule is enabled it must be a type that supports alerting: `prometheus`, `elasticsearch`, `loki`, `clickhouse`, `mysql`, `oracle`, `postgres`, `sls`, `tencent_cls`, `victorialogs`."
           },
           "ds_list": {
             "type": "array",
@@ -9046,7 +9353,7 @@
           },
           "cron_pattern": {
             "type": "string",
-            "description": "Schedule expression: a 6-field cron (with seconds) or an `@every 30s` interval. Must not start with `CRON_TZ=` or `TZ=`; set the timezone in the `timezone` field instead."
+            "description": "Schedule expression: a 6-field cron with seconds (e.g. `0 * * * * *`), a descriptor such as `@hourly`, or `@every <duration>` with a whole number of seconds of at least `1s` (e.g. `@every 30s`). Must not start with `CRON_TZ=` or `TZ=`; set the timezone in the `timezone` field instead."
           },
           "timezone": {
             "type": "string",
@@ -9083,15 +9390,15 @@
                   "items": {
                     "type": "integer"
                   },
-                  "description": "Days of week (0=Sunday)."
+                  "description": "Days of week the window applies to, `0` = Sunday through `6` = Saturday; non-empty, no duplicates."
                 },
                 "stime": {
                   "type": "string",
-                  "description": "Start time, e.g. `09:00`."
+                  "description": "Start time in 24-hour `HH:MM` format, e.g. `09:00`."
                 },
                 "etime": {
                   "type": "string",
-                  "description": "End time, e.g. `18:00`."
+                  "description": "End time in 24-hour `HH:MM` format, e.g. `18:00`."
                 }
               }
             }
@@ -9114,7 +9421,7 @@
           },
           "description": {
             "type": "string",
-            "description": "Rule description, Markdown format."
+            "description": "Rule description; rendered as plain text or Markdown according to `description_type`."
           },
           "channel_ids": {
             "type": "array",
@@ -9127,12 +9434,12 @@
           "repeat_interval": {
             "type": "integer",
             "format": "int64",
-            "description": "Notification repeat interval in seconds. Values below 1 fall back to the default 3600."
+            "description": "Notification repeat interval in seconds. Values below 1 fall back to the default 3600; maximum 2147483647."
           },
           "repeat_total": {
             "type": "integer",
             "format": "int64",
-            "description": "Maximum number of repeat notifications. Values below 1 fall back to the default 3."
+            "description": "Maximum number of repeat notifications. Values below 1 fall back to the default 3; maximum 2147483647."
           },
           "investigation_targets": {
             "type": "array",
@@ -9140,7 +9447,7 @@
               "$ref": "#/components/schemas/InvestigationTarget"
             },
             "maxItems": 20,
-            "description": "Drill-down entries linked from the alert event detail page; at most 20 items, duplicates rejected. On update the field is presence-based: omit it to keep the current value, pass `[]` to clear.",
+            "description": "Drill-down entries linked from the alert event detail page; at most 20 items, duplicates rejected, and at most 32 KiB once serialized. On update the field is presence-based: omit it to keep the current value, pass `[]` to clear; `null` is rejected.",
             "x-flashduty-preserve-absence": true
           },
           "creator_id": {
@@ -9225,7 +9532,7 @@
           },
           "relate_queries": {
             "type": "array",
-            "description": "Optional auxiliary queries whose results attach to alert events as context. Each entry needs a unique `name` (not colliding with any query name) and a non-empty `expr`.",
+            "description": "Optional auxiliary queries whose results attach to alert events as context. Each entry needs a unique `name` (not colliding with any query name) and a non-empty `expr`. Always returned, as `[]` when there are none.",
             "items": {
               "type": "object",
               "properties": {
@@ -9544,7 +9851,7 @@
       },
       "DashboardQuery": {
         "type": "object",
-        "description": "Query payload shared by dashboards and drill-down entries.",
+        "description": "Query payload shared by dashboard panels and alert rule drill-down entries. Template syntax differs by context: dashboard panels use dashboard variables (`${name}`), drill-down entries use event labels (`{{ }}`).",
         "properties": {
           "mode": {
             "type": "string",
@@ -9553,18 +9860,18 @@
               "range",
               "window"
             ],
-            "description": "Evaluation mode: `instant` evaluates at a single timestamp, `range` evaluates a stepped series, `window` returns raw rows inside a time window."
+            "description": "Evaluation mode: `instant` = evaluate at a single timestamp; `range` = evaluate a stepped series over the time range; `window` = return raw rows inside the time range. Dashboard panels on Prometheus and Loki accept `instant` or `range` (Loki `logs` panels need `range`); MySQL panels need `window`."
           },
           "expr": {
             "type": "string",
-            "description": "Query expression in the target data source's language. May reference event labels through `{{ }}` templates."
+            "description": "Query expression in the datasource's language. In dashboard panels it may reference variables as `${name}`, `${name:raw}` (one value inserted as is) or `${name:regex}` (values joined as a regex alternation), or as `$name` in Prometheus and Loki; write `$${...}` for a literal. Without a formatter, multi-value or `all` variables and values inside `=~`/`!~` are inserted in regex form, so they cannot be used with `=` or `!=`. MySQL queries do not support variables. In drill-down entries the expression may reference event labels through `{{ }}` templates."
           },
           "args": {
             "type": "object",
             "additionalProperties": {
               "type": "string"
             },
-            "description": "Named query arguments; defaults to an empty object. Values are passed through verbatim and must not contain `{{ }}` templates."
+            "description": "Named query arguments; defaults to an empty object. In dashboard panels values may use `${name}` templates except for Loki and MySQL datasources. In drill-down entries keys and values must not contain `{{ }}` templates."
           },
           "min_step_seconds": {
             "type": [
@@ -9574,7 +9881,7 @@
             "format": "int64",
             "minimum": 1,
             "maximum": 9007199254740,
-            "description": "Minimum step, in seconds. Only accepted when `mode` is `range`, and must be greater than zero; omit or pass null to let the server decide."
+            "description": "Minimum step, in seconds; must be greater than zero. In drill-down entries it is only accepted when `mode` is `range`. Omit or pass null to let the server decide."
           }
         },
         "required": [
@@ -9585,7 +9892,7 @@
       },
       "DashboardDefinition": {
         "type": "object",
-        "description": "Complete dashboard payload stored as a portable `dashboard.v1` document. Unknown keys, duplicate keys, NaN/Inf, over-range numbers and trailing values are rejected; the serialized form must stay within 1 MiB.",
+        "description": "Complete dashboard payload stored as a portable `dashboard.v1` document. Unknown keys, duplicate keys, trailing values and nesting deeper than 32 levels are rejected, and the serialized form must stay within 1 MiB. Limits: 10 tabs, 10 sections per tab, 30 panels and 100 queries per tab, 100 panels and 300 queries per dashboard, 20 variables.",
         "properties": {
           "title": {
             "type": "string",
@@ -9617,7 +9924,7 @@
               "$ref": "#/components/schemas/DashboardVariable"
             },
             "maxItems": 20,
-            "description": "Dashboard variables, at most 20. Names must be unique within the definition and match the variable-name pattern."
+            "description": "Dashboard variables, at most 20, with unique names. Variables may reference other variables but not in a cycle."
           },
           "tabs": {
             "type": "array",
@@ -9626,7 +9933,7 @@
             },
             "minItems": 1,
             "maxItems": 10,
-            "description": "Tabs, 1–10. Every tab title is unique and every tab or section ID must be a canonical UUIDv7 used only once across the definition."
+            "description": "Tabs, 1–10. Every tab, section and panel `id` must be a canonical UUIDv7 used only once across the definition. Tab titles do not need to be unique."
           }
         },
         "required": [
@@ -9681,7 +9988,7 @@
             "type": "string",
             "minLength": 1,
             "maxLength": 189,
-            "description": "Tab title, 1–189 Unicode code points. Unique among tabs."
+            "description": "Tab title, 1–189 Unicode code points after trimming."
           },
           "description": {
             "type": "string",
@@ -9694,7 +10001,7 @@
               "$ref": "#/components/schemas/DashboardPanel"
             },
             "maxItems": 30,
-            "description": "Panels placed directly on the tab, at most 30."
+            "description": "Panels placed directly on the tab. A tab holds at most 30 panels in total, counting top panels and section panels, and at most 100 queries."
           },
           "sections": {
             "type": "array",
@@ -9742,7 +10049,7 @@
               "$ref": "#/components/schemas/DashboardPanel"
             },
             "maxItems": 30,
-            "description": "Panels in the section, at most 30."
+            "description": "Panels in the section; they count toward the tab's 30-panel limit."
           }
         },
         "required": [
@@ -9754,7 +10061,7 @@
       },
       "DashboardPanel": {
         "type": "object",
-        "description": "A single visualization. Panels must not overlap inside the same container; the 24-column grid is validated on save.",
+        "description": "A single visualization. `datasource_ref` is required for every kind except `text`, where it is forbidden. Panels must not overlap inside the same container; the 24-column grid is validated on save.",
         "properties": {
           "id": {
             "type": "string",
@@ -9849,17 +10156,18 @@
             "type": "integer",
             "format": "uint64",
             "minimum": 1,
-            "description": "Datasource ID. Required when `kind` is `fixed`, forbidden when `kind` is `variable`."
+            "description": "Datasource ID. Required when `kind` is `fixed`, forbidden when `kind` is `variable`.",
+            "maximum": 9007199254740991
           },
           "name": {
             "type": "string",
             "pattern": "^[A-Za-z_][A-Za-z0-9_]{0,63}$",
-            "description": "Datasource variable name. Required when `kind` is `variable`, forbidden when `kind` is `fixed`."
+            "description": "Name of a `datasource` variable in the same definition. Required when `kind` is `variable`, forbidden when `kind` is `fixed`."
           },
           "datasource_type": {
             "type": "string",
             "pattern": "^[a-z][a-z0-9_]{0,63}$",
-            "description": "Datasource type identifier, e.g. `prometheus` or `victorialogs`."
+            "description": "Datasource type identifier: lowercase letters, digits and underscores, starting with a letter. The set is open, so saving accepts any such value, but the dashboard runtime only runs `prometheus`, `mysql` and `loki` datasources; panels on other types fail when run. With `kind` = `variable` it must equal the referenced datasource variable's `datasource_type`."
           }
         },
         "required": [
@@ -9882,7 +10190,7 @@
           "legend_alias": {
             "type": "string",
             "maxLength": 1024,
-            "description": "Optional legend label; supports the same variable templates as `expr`."
+            "description": "Optional legend label, at most 1024 Unicode code points. The console replaces `{{label}}` with that series label's value (for example `{{env}} requests`); dashboard variables are not substituted here."
           }
         },
         "required": [
@@ -9926,7 +10234,7 @@
           "name": {
             "type": "string",
             "pattern": "^[A-Za-z_][A-Za-z0-9_]{0,63}$",
-            "description": "Variable name used in `{{ }}` templates, at most 64 characters. Names starting with `__` are reserved for built-in time variables."
+            "description": "Variable name, unique within the definition. Queries reference it as `${name}` (or `$name` inside Prometheus and Loki expressions). Names starting with `__` are reserved for the built-in variables `__interval`, `__rate_interval`, `__range` and `__auto`."
           },
           "label": {
             "type": "string",
@@ -9936,7 +10244,7 @@
           "datasource_type": {
             "type": "string",
             "pattern": "^[a-z][a-z0-9_]{0,63}$",
-            "description": "Datasource type the candidates are drawn from."
+            "description": "Type of datasource offered as candidates; candidates are the account's enabled datasources of this type. The set is open, so saving accepts any such value, but the dashboard runtime only runs `prometheus`, `mysql` and `loki` datasources; panels on other types fail when run. "
           },
           "name_patterns": {
             "type": "array",
@@ -9951,7 +10259,8 @@
           "default_datasource_id": {
             "type": "integer",
             "format": "uint64",
-            "description": "Default datasource ID. Without a usable default the runtime picks the first candidate by name, then ID."
+            "description": "Default datasource ID. Without a usable default the runtime picks the first candidate by name, then ID.",
+            "maximum": 9007199254740991
           }
         },
         "required": [
@@ -9974,7 +10283,7 @@
           "name": {
             "type": "string",
             "pattern": "^[A-Za-z_][A-Za-z0-9_]{0,63}$",
-            "description": "Variable name used in `{{ }}` templates, at most 64 characters. Names starting with `__` are reserved for built-in time variables."
+            "description": "Variable name, unique within the definition. Queries reference it as `${name}` (or `$name` inside Prometheus and Loki expressions). Names starting with `__` are reserved for the built-in variables `__interval`, `__rate_interval`, `__range` and `__auto`."
           },
           "label": {
             "type": "string",
@@ -10018,7 +10327,7 @@
           "name": {
             "type": "string",
             "pattern": "^[A-Za-z_][A-Za-z0-9_]{0,63}$",
-            "description": "Variable name used in `{{ }}` templates, at most 64 characters. Names starting with `__` are reserved for built-in time variables."
+            "description": "Variable name, unique within the definition. Queries reference it as `${name}` (or `$name` inside Prometheus and Loki expressions). Names starting with `__` are reserved for the built-in variables `__interval`, `__rate_interval`, `__range` and `__auto`."
           },
           "label": {
             "type": "string",
@@ -10079,7 +10388,7 @@
       },
       "DashboardSelection": {
         "type": "object",
-        "description": "A concrete selection of variable values. An empty `values` array is valid wire input and means unresolved — the server never substitutes a default for it.",
+        "description": "A concrete selection of variable values. As a saved variable `default`, `values` must be non-empty and hold exactly one value in `single` mode. In runtime requests an empty `values` array is valid and means unresolved — the server never substitutes a default for it.",
         "properties": {
           "kind": {
             "type": "string",
@@ -10166,7 +10475,7 @@
           },
           "metric": {
             "type": "string",
-            "description": "Optional metric used to restrict the series considered."
+            "description": "Optional metric selector that restricts the series considered; may reference other variables as `${name}` or `$name`."
           },
           "label_filters": {
             "type": "array",
@@ -10188,7 +10497,7 @@
           "label": {
             "type": "string",
             "pattern": "^[A-Za-z_][A-Za-z0-9_:.\\-]{0,189}$",
-            "description": "Label name."
+            "description": "Prometheus label name to match, e.g. `job`; letters, digits, `_`, `:`, `.` and `-`, starting with a letter or `_`."
           },
           "op": {
             "type": "string",
@@ -10203,7 +10512,7 @@
           "value": {
             "type": "string",
             "minLength": 1,
-            "description": "Matcher value; may reference other variables through `{{ }}`."
+            "description": "Matcher value; may reference other variables as `${name}`. A multi-value or `all` variable needs `=~` or `!~`."
           }
         },
         "required": [
@@ -10225,7 +10534,7 @@
           },
           "expr": {
             "type": "string",
-            "description": "SQL statement; may reference other variables through `{{ }}`."
+            "description": "SQL statement whose result supplies the candidates. SQL variable queries run only on MySQL datasources, and MySQL queries do not support variable references."
           },
           "args": {
             "type": "object",
@@ -10264,7 +10573,7 @@
           },
           "expr": {
             "type": "string",
-            "description": "Logs query expression; may reference other variables through `{{ }}`. May be empty for a Loki datasource, which then lists the field's values across all streams."
+            "description": "Logs query expression; may reference other variables as `${name}`. Logs variable queries run only on Loki datasources, where `expr` may be empty to list the field's values across all streams."
           },
           "args": {
             "type": "object",
@@ -10287,7 +10596,7 @@
         ]
       },
       "DashboardVizConfig": {
-        "description": "Visualization configuration. `kind` selects the arm and therefore which sibling config object is required; `time_series` also carries the shared numeric options.",
+        "description": "Visualization configuration. `kind` selects the arm and therefore which sibling fields are allowed; `time_series`, `stat`, `bar` and `gauge` also carry the shared numeric fields `unit`, `decimals` and `threshold`. Fields of another kind are rejected.",
         "oneOf": [
           {
             "$ref": "#/components/schemas/DashboardTimeSeriesViz"
@@ -10354,7 +10663,7 @@
               "bytes_per_second",
               "bits_per_second"
             ],
-            "description": "Display unit for the panel's numeric values: `unitless` = raw number; `ratio` = fraction of 1; `percent` = percentage; `milliseconds` = duration in milliseconds; `seconds` = duration in seconds; `bytes` = size in bytes; `bits` = size in bits; `count_per_second` = per-second count; `bytes_per_second` = bytes per second; `bits_per_second` = bits per second."
+            "description": "Display unit for the panel's numeric values: `unitless` = raw number; `ratio` = fraction of 1; `percent` = percentage; `milliseconds` = duration in milliseconds; `seconds` = duration in seconds; `bytes` = size in bytes; `bits` = size in bits; `count_per_second` = per-second count; `bytes_per_second` = bytes per second; `bits_per_second` = bits per second. Defaults to `unitless` when omitted."
           },
           "decimals": {
             "type": [
@@ -10362,7 +10671,8 @@
               "null"
             ],
             "minimum": 0,
-            "description": "Fixed decimal places; omit or send null to let the renderer decide."
+            "description": "Fixed number of decimal places, 0–15; omit or send null to let the console decide.",
+            "maximum": 15
           },
           "threshold": {
             "$ref": "#/components/schemas/DashboardThreshold"
@@ -10394,15 +10704,14 @@
             "additionalProperties": {
               "$ref": "#/components/schemas/DashboardColumnOption"
             },
-            "description": "Per-column display overrides keyed by field name, at most 100 entries."
+            "description": "Per-column display overrides keyed by result field name, at most 100 entries. Keys must be non-empty, at most 1024 Unicode code points and not `frame_index` or `field_index`."
           },
           "sort": {
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/DashboardFieldSort"
             },
-            "maxItems": 2,
-            "description": "Initial sort keys; fields must be unique."
+            "description": "Initial sort keys, applied in order; each field may appear once."
           },
           "link_columns": {
             "type": "array",
@@ -10448,7 +10757,7 @@
               "bytes_per_second",
               "bits_per_second"
             ],
-            "description": "Display unit for the panel's numeric values: `unitless` = raw number; `ratio` = fraction of 1; `percent` = percentage; `milliseconds` = duration in milliseconds; `seconds` = duration in seconds; `bytes` = size in bytes; `bits` = size in bits; `count_per_second` = per-second count; `bytes_per_second` = bytes per second; `bits_per_second` = bits per second."
+            "description": "Display unit for the panel's numeric values: `unitless` = raw number; `ratio` = fraction of 1; `percent` = percentage; `milliseconds` = duration in milliseconds; `seconds` = duration in seconds; `bytes` = size in bytes; `bits` = size in bits; `count_per_second` = per-second count; `bytes_per_second` = bytes per second; `bits_per_second` = bits per second. Defaults to `unitless` when omitted."
           },
           "decimals": {
             "type": [
@@ -10456,7 +10765,8 @@
               "null"
             ],
             "minimum": 0,
-            "description": "Fixed decimal places; omit or send null to let the renderer decide."
+            "description": "Fixed number of decimal places, 0–15; omit or send null to let the console decide.",
+            "maximum": 15
           },
           "threshold": {
             "$ref": "#/components/schemas/DashboardThreshold"
@@ -10466,7 +10776,9 @@
             "items": {
               "type": "string"
             },
-            "description": "Fields reduced to the displayed values."
+            "description": "Result fields reduced to the displayed values; at least one, each listed once. Names are matched exactly and must not be `frame_index` or `field_index`.",
+            "minItems": 1,
+            "uniqueItems": true
           },
           "reducer": {
             "type": "string",
@@ -10517,7 +10829,7 @@
               "bytes_per_second",
               "bits_per_second"
             ],
-            "description": "Display unit for the panel's numeric values: `unitless` = raw number; `ratio` = fraction of 1; `percent` = percentage; `milliseconds` = duration in milliseconds; `seconds` = duration in seconds; `bytes` = size in bytes; `bits` = size in bits; `count_per_second` = per-second count; `bytes_per_second` = bytes per second; `bits_per_second` = bits per second."
+            "description": "Display unit for the panel's numeric values: `unitless` = raw number; `ratio` = fraction of 1; `percent` = percentage; `milliseconds` = duration in milliseconds; `seconds` = duration in seconds; `bytes` = size in bytes; `bits` = size in bits; `count_per_second` = per-second count; `bytes_per_second` = bytes per second; `bits_per_second` = bits per second. Defaults to `unitless` when omitted."
           },
           "decimals": {
             "type": [
@@ -10525,21 +10837,25 @@
               "null"
             ],
             "minimum": 0,
-            "description": "Fixed decimal places; omit or send null to let the renderer decide."
+            "description": "Fixed number of decimal places, 0–15; omit or send null to let the console decide.",
+            "maximum": 15
           },
           "threshold": {
             "$ref": "#/components/schemas/DashboardThreshold"
           },
           "category_field": {
             "type": "string",
-            "description": "Field supplying the category axis."
+            "description": "Result field supplying the category axis; required, at most 1024 Unicode code points, not `frame_index` or `field_index`.",
+            "minLength": 1
           },
           "value_fields": {
             "type": "array",
             "items": {
               "type": "string"
             },
-            "description": "Fields supplying the bar values."
+            "description": "Result fields supplying the bar values; at least one, each listed once. Names must not be `frame_index` or `field_index`.",
+            "minItems": 1,
+            "uniqueItems": true
           },
           "data_link": {
             "$ref": "#/components/schemas/DashboardDataLink"
@@ -10582,7 +10898,7 @@
               "bytes_per_second",
               "bits_per_second"
             ],
-            "description": "Display unit for the panel's numeric values: `unitless` = raw number; `ratio` = fraction of 1; `percent` = percentage; `milliseconds` = duration in milliseconds; `seconds` = duration in seconds; `bytes` = size in bytes; `bits` = size in bits; `count_per_second` = per-second count; `bytes_per_second` = bytes per second; `bits_per_second` = bits per second."
+            "description": "Display unit for the panel's numeric values: `unitless` = raw number; `ratio` = fraction of 1; `percent` = percentage; `milliseconds` = duration in milliseconds; `seconds` = duration in seconds; `bytes` = size in bytes; `bits` = size in bits; `count_per_second` = per-second count; `bytes_per_second` = bytes per second; `bits_per_second` = bits per second. Defaults to `unitless` when omitted."
           },
           "decimals": {
             "type": [
@@ -10590,7 +10906,8 @@
               "null"
             ],
             "minimum": 0,
-            "description": "Fixed decimal places; omit or send null to let the renderer decide."
+            "description": "Fixed number of decimal places, 0–15; omit or send null to let the console decide.",
+            "maximum": 15
           },
           "threshold": {
             "$ref": "#/components/schemas/DashboardThreshold"
@@ -10600,7 +10917,9 @@
             "items": {
               "type": "string"
             },
-            "description": "Fields reduced to the gauge value."
+            "description": "Result fields reduced to the gauge value; at least one, each listed once. Names are matched exactly and must not be `frame_index` or `field_index`.",
+            "minItems": 1,
+            "uniqueItems": true
           },
           "reducer": {
             "type": "string",
@@ -10683,7 +11002,7 @@
           "markdown": {
             "type": "string",
             "maxLength": 65536,
-            "description": "Markdown body, at most 64 KiB. Only a restricted node set (headings, lists, tables, links, code) survives validation."
+            "description": "Markdown body, at most 64 KiB. Allowed: paragraphs, headings, lists, block quotes, code blocks and spans, emphasis, tables, horizontal rules and links. Links must be `https://` URLs or site-relative paths starting with `/`. Images, raw HTML and `${` templates are rejected with `InvalidParameter`, not stripped."
           }
         },
         "required": [
@@ -10761,7 +11080,7 @@
               "bytes_per_second",
               "bits_per_second"
             ],
-            "description": "Unit override for the column: `unitless` = raw number; `ratio` = fraction of 1; `percent` = percentage; `milliseconds` = duration in milliseconds; `seconds` = duration in seconds; `bytes` = size in bytes; `bits` = size in bits; `count_per_second` = per-second count; `bytes_per_second` = bytes per second; `bits_per_second` = bits per second."
+            "description": "Unit override for the column: `unitless` = raw number; `ratio` = fraction of 1; `percent` = percentage; `milliseconds` = duration in milliseconds; `seconds` = duration in seconds; `bytes` = size in bytes; `bits` = size in bits; `count_per_second` = per-second count; `bytes_per_second` = bytes per second; `bits_per_second` = bits per second. Defaults to `unitless` when omitted."
           },
           "threshold": {
             "$ref": "#/components/schemas/DashboardThreshold"
@@ -10786,7 +11105,7 @@
           "field": {
             "type": "string",
             "minLength": 1,
-            "description": "Field name to sort by."
+            "description": "Result field name to sort by; at most 1024 Unicode code points, not `frame_index` or `field_index`."
           },
           "direction": {
             "type": "string",
@@ -10804,12 +11123,12 @@
       },
       "DashboardDataLink": {
         "type": "object",
-        "description": "Drill-down link from a table column or bar panel into another dashboard. The target dashboard must exist and the mapping sources must match the source panel's shape.",
+        "description": "Drill-down link from a table or bar panel into another dashboard. Only the ID format is checked on save; a link to a dashboard that does not exist is accepted. The mapping sources allowed depend on the source panel kind.",
         "properties": {
           "dashboard_id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "Target dashboard ID."
+            "description": "ID of the dashboard to open; must be a canonical UUIDv7."
           },
           "target_id": {
             "type": "string",
@@ -10825,7 +11144,7 @@
             "additionalProperties": {
               "$ref": "#/components/schemas/DashboardLinkMapping"
             },
-            "description": "Maps target variable names to a source value such as a column or a source variable."
+            "description": "Values to set in the target dashboard, keyed by target variable name (must match `^[A-Za-z_][A-Za-z0-9_]{0,63}$`); each entry says where the value comes from. Send `{}` for none."
           }
         },
         "required": [
@@ -10847,15 +11166,15 @@
               "series",
               "value"
             ],
-            "description": "Where the value comes from: `variable` = a dashboard variable; `row_column` = a table column (requires `column`); `category` = the bar category; `series` = the series name; `value` = the value itself. `category`, `series` and `value` are only valid for bar panels."
+            "description": "Where the value comes from: `variable` = the current value of a variable of the source dashboard (requires `name`), allowed on table and bar panels; `row_column` = the clicked row's value in a table column (requires `column`), table panels only; `category` = the clicked bar's category, `series` = its series name, `value` = its value — these three are bar panels only and take no extra fields."
           },
           "column": {
             "type": "string",
-            "description": "Source column name; required when `source` is `row_column`."
+            "description": "Table column (result field) to read; required when `source` is `row_column` and forbidden otherwise."
           },
           "name": {
             "type": "string",
-            "description": "Source dashboard variable name; required when `source` is `variable`."
+            "description": "Variable of the source dashboard to read; required when `source` is `variable` and must exist in the same definition; forbidden for other sources."
           }
         },
         "required": [
@@ -10869,11 +11188,11 @@
           "id": {
             "type": "integer",
             "format": "uint64",
-            "description": "Member ID."
+            "description": "Member ID of the person who performed the action."
           },
           "name": {
             "type": "string",
-            "description": "Member display name."
+            "description": "Member display name, recorded at the time of the action."
           }
         },
         "required": [
@@ -10956,13 +11275,13 @@
           "dashboard_id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "Dashboard ID."
+            "description": "Dashboard ID; pass it to `POST /monit/dashboard/get` for the full definition."
           },
           "folder_id": {
             "type": "integer",
             "format": "uint64",
             "minimum": 1,
-            "description": "Folder ID."
+            "description": "ID of the folder the dashboard is stored in."
           },
           "folder_breadcrumb": {
             "type": "array",
@@ -10977,7 +11296,7 @@
           },
           "description": {
             "type": "string",
-            "description": "Dashboard description; empty when unset."
+            "description": "Dashboard description; omitted when unset."
           },
           "revision": {
             "type": "integer",
@@ -11033,7 +11352,7 @@
           "dashboard_id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "Dashboard ID."
+            "description": "ID of the trashed dashboard; pass it to `POST /monit/dashboard/restore`."
           },
           "folder_id": {
             "type": "integer",
@@ -11054,13 +11373,13 @@
           },
           "description": {
             "type": "string",
-            "description": "Dashboard description; empty when unset."
+            "description": "Dashboard description; omitted when unset."
           },
           "revision": {
             "type": "integer",
             "format": "uint64",
             "minimum": 1,
-            "description": "Revision the dashboard had when deleted."
+            "description": "Current revision of the trashed dashboard (the deletion bumped it); send it as `expected_revision` to restore."
           },
           "deleted_by": {
             "$ref": "#/components/schemas/DashboardActor"
@@ -11095,7 +11414,7 @@
           "total": {
             "type": "integer",
             "format": "int64",
-            "description": "Total number of deleted dashboards."
+            "description": "Total number of trashed dashboards visible to the caller, across all pages."
           }
         },
         "required": [
@@ -11105,11 +11424,11 @@
       },
       "DashboardUpdateOutput": {
         "type": "object",
-        "description": "Result of an update or move. `changed` is false when the write was a no-op — the canonical serialized definition matched the stored one byte for byte, in which case `resource` still describes the unchanged dashboard.",
+        "description": "Result of an update or move. `changed` is false when nothing was written — for update, the normalized definition and `schema_version` equal the stored ones; for move, the dashboard is already in the target folder. `revision` then stays the same and `resource` describes the unchanged dashboard.",
         "properties": {
           "changed": {
             "type": "boolean",
-            "description": "Whether the stored dashboard actually changed."
+            "description": "Whether the dashboard was written and its `revision` incremented."
           },
           "resource": {
             "$ref": "#/components/schemas/DashboardResource"
@@ -11127,13 +11446,13 @@
           "dashboard_id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "Dashboard ID."
+            "description": "ID of the dashboard moved to the trash."
           },
           "revision": {
             "type": "integer",
             "format": "uint64",
             "minimum": 1,
-            "description": "Revision recorded for the deletion."
+            "description": "Revision after the deletion; send it as `expected_revision` to restore."
           }
         },
         "required": [
@@ -11148,7 +11467,7 @@
           "dashboard_id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "Dashboard ID."
+            "description": "ID of the dashboard this revision belongs to."
           },
           "revision": {
             "type": "integer",
@@ -11165,7 +11484,7 @@
           "message": {
             "type": "string",
             "maxLength": 1024,
-            "description": "Optional commit message; at most 1024 Unicode code points."
+            "description": "Message passed to `POST /monit/dashboard/update`; omitted when none was given and on revisions written by create, move, delete and restore."
           },
           "actor": {
             "$ref": "#/components/schemas/DashboardActor"
@@ -11207,7 +11526,7 @@
           "dashboard_id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "Dashboard ID."
+            "description": "ID of the dashboard this revision belongs to."
           },
           "schema_version": {
             "type": "string",
@@ -11234,7 +11553,7 @@
           "message": {
             "type": "string",
             "maxLength": 1024,
-            "description": "Optional commit message."
+            "description": "Message passed to `POST /monit/dashboard/update`; omitted when none was given."
           },
           "actor": {
             "$ref": "#/components/schemas/DashboardActor"
@@ -11294,7 +11613,7 @@
           "dashboard_id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "Dashboard ID."
+            "description": "Dashboard ID, as passed in the request."
           },
           "title": {
             "type": "string",
@@ -11302,7 +11621,7 @@
           },
           "description": {
             "type": "string",
-            "description": "Dashboard description; empty when unset."
+            "description": "Dashboard description; omitted when unset."
           },
           "revision": {
             "type": "integer",
@@ -11331,7 +11650,7 @@
             "type": "integer",
             "format": "uint64",
             "minimum": 1,
-            "description": "Folder ID."
+            "description": "ID of the folder the dashboard is stored in."
           },
           "breadcrumb": {
             "type": "array",
@@ -11357,7 +11676,7 @@
           },
           "label": {
             "type": "string",
-            "description": "Display label; empty when unset."
+            "description": "Display label; omitted when unset."
           },
           "kind": {
             "type": "string",
@@ -11384,15 +11703,15 @@
           "id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "Tab ID."
+            "description": "Tab ID; pass it as `target_id` to narrow the outline to this tab."
           },
           "title": {
             "type": "string",
-            "description": "Tab title."
+            "description": "Tab title as stored in the definition."
           },
           "description": {
             "type": "string",
-            "description": "Tab description; empty when unset."
+            "description": "Tab description; omitted when unset."
           },
           "breadcrumb": {
             "type": "array",
@@ -11431,7 +11750,7 @@
           "id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "Section ID."
+            "description": "Section ID; pass it as `target_id` to narrow the outline to this section."
           },
           "title": {
             "type": "string",
@@ -11439,7 +11758,7 @@
           },
           "description": {
             "type": "string",
-            "description": "Section description; empty when unset."
+            "description": "Section description; omitted when unset."
           },
           "breadcrumb": {
             "type": "array",
@@ -11470,7 +11789,7 @@
           "id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "Panel ID."
+            "description": "Panel ID; use it as `panel_id` for `POST /monit/dashboard/panel/run` or as `target_id` here."
           },
           "title": {
             "type": "string",
@@ -11478,7 +11797,7 @@
           },
           "description": {
             "type": "string",
-            "description": "Panel description; empty when unset."
+            "description": "Panel description; omitted when unset."
           },
           "breadcrumb": {
             "type": "array",
@@ -11492,7 +11811,7 @@
           },
           "datasource_type": {
             "type": "string",
-            "description": "Datasource type the panel queries; empty when the panel has no datasource (text panels)."
+            "description": "Datasource type from the panel's `datasource_ref`, such as `prometheus`, `mysql` or `loki`; omitted for text panels, which have no datasource. The set is open: it echoes whatever type was saved."
           }
         },
         "required": [
@@ -11558,7 +11877,7 @@
           "dashboard_id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "Canonical UUIDv7 of the dashboard."
+            "description": "Lowercase canonical UUIDv7 generated by the caller; it becomes the dashboard's permanent ID."
           },
           "schema_version": {
             "type": "string",
@@ -11571,7 +11890,7 @@
             "type": "integer",
             "format": "uint64",
             "minimum": 1,
-            "description": "Folder the dashboard is created in. Must be a folder the caller can write."
+            "description": "Folder to create the dashboard in; must exist and be accessible to the `app_key` owner, otherwise `FolderNotFound`."
           },
           "definition": {
             "$ref": "#/components/schemas/DashboardDefinition"
@@ -11674,7 +11993,7 @@
             "type": "integer",
             "format": "uint64",
             "minimum": 1,
-            "description": "Destination folder ID."
+            "description": "Destination folder ID; must exist and be accessible to the caller, otherwise `FolderNotFound`."
           }
         },
         "required": [
@@ -11685,7 +12004,7 @@
       },
       "DashboardDeleteRequest": {
         "type": "object",
-        "description": "Move a dashboard to the trash. The definition is retained for 30 days so the delete can be undone with the restore endpoint.",
+        "description": "Move a dashboard to the trash. It is purged permanently 30 days after deletion; until then the restore endpoint can undo the delete.",
         "properties": {
           "dashboard_id": {
             "type": "string",
@@ -11717,7 +12036,7 @@
             "type": "integer",
             "format": "uint64",
             "minimum": 1,
-            "description": "Revision the caller last read. The write fails with `DashboardRevisionConflict` unless it still matches the stored revision."
+            "description": "Current revision of the trashed dashboard, as returned by the delete call or listed in the trash. The restore fails with `DashboardRevisionConflict` if it does not match."
           },
           "folder_id": {
             "type": [
@@ -11726,7 +12045,7 @@
             ],
             "format": "uint64",
             "minimum": 1,
-            "description": "Destination folder. Omit to restore to the original folder; when the original folder is no longer writable the call fails with `RestoreFolderRequired` and you must pass one."
+            "description": "Destination folder. Omit or send null to restore into the original folder; if that folder no longer exists the call fails with `RestoreFolderRequired` and a destination must be passed."
           }
         },
         "required": [
@@ -11763,12 +12082,12 @@
             "type": "integer",
             "format": "uint64",
             "minimum": 1,
-            "description": "Folder whose dashboards are listed."
+            "description": "Folder whose directly contained dashboards are listed; subfolders are not included."
           },
           "query": {
             "type": "string",
             "maxLength": 128,
-            "description": "Optional space-separated search words matched against title and description; at most 128 Unicode code points."
+            "description": "Optional search words separated by whitespace, at most 128 Unicode code points. A dashboard matches when every word appears in its title or description."
           },
           "sort": {
             "type": "array",
@@ -11802,7 +12121,7 @@
             "type": "string",
             "minLength": 1,
             "maxLength": 128,
-            "description": "Space-separated search words; at least one word and at most 128 Unicode code points."
+            "description": "Search words separated by whitespace; at least one word and at most 128 Unicode code points. A dashboard matches when every word appears in its title or description."
           },
           "sort": {
             "type": "array",
@@ -11861,13 +12180,15 @@
             "type": "integer",
             "format": "int64",
             "minimum": 0,
-            "description": "Unix timestamp in milliseconds."
+            "description": "Start of the window as a Unix timestamp in milliseconds. Must be 0 or greater and less than `to_ms`.",
+            "maximum": 9007199254740991
           },
           "to_ms": {
             "type": "integer",
             "format": "int64",
             "minimum": 1,
-            "description": "Unix timestamp in milliseconds."
+            "description": "End of the window as a Unix timestamp in milliseconds. Must be greater than `from_ms`; `instant` queries are evaluated at this time.",
+            "maximum": 9007199254740991
           }
         },
         "required": [
@@ -11877,15 +12198,15 @@
       },
       "DashboardRuntimeError": {
         "type": "object",
-        "description": "Per-variable or per-query failure. A failed arm does not fail the whole call.",
+        "description": "Failure of one variable or one query. A failed variable or query does not fail the whole call.",
         "properties": {
           "reason": {
             "type": "string",
-            "description": "Machine-readable failure reason. Observed values include `invalid_request`, `variable_invalid`, `panel_missing`, `field_missing`, `datasource_permission_denied`, `timeout`, `panel_deadline`, `panel_canceled`, `canceled`, `overloaded`, `source_too_large`, `edge_unavailable`, `edge_upgrade_required`, `edge_version_unknown`, `mixed_edge_versions` and `internal`."
+            "description": "Machine-readable failure reason. The set is open; current values:\n- `invalid_request`: the query or datasource setup is rejected (unsupported datasource type or query mode, non-empty `args` where none are allowed, a malformed argument).\n- `variable_invalid`: a variable could not be used (no selection and no default, a selection outside the candidates, an unresolved dependency, a bad substitution, or an unusable candidate list).\n- `panel_missing`: the panel is not in the dashboard (queries resolve only).\n- `datasource_permission_denied`: the datasource is missing, disabled, not accessible to the caller, or no accessible datasource matches the variable.\n- `field_missing`, `value_not_scalar`, `empty_field_name`, `duplicate_field_name`, `field_type_changed`: the result does not fit the panel's visualization, or a SQL variable query returned unusable columns.\n- `timeout`: the datasource call timed out; `panel_deadline`: the run hit the overall 35-second deadline.\n- `canceled`, `panel_canceled`: the call was cancelled.\n- `overloaded`: the datasource side is rate limiting.\n- `too_many_rows`, `result_too_large`, `source_too_large`: a row, size or candidate-count limit was exceeded.\n- `edge_unavailable`, `no_active_edge`, `edge_upgrade_required`, `edge_version_unknown`, `mixed_edge_versions`: the Edge cluster of the datasource is not connected, too old, of unknown version, or mixed.\n- `internal`: an unexpected server-side error."
           },
           "message": {
             "type": "string",
-            "description": "Human-readable detail for the failure."
+            "description": "Human-readable detail for display or troubleshooting; its wording is not stable, so do not parse it."
           }
         },
         "required": [
@@ -11895,18 +12216,18 @@
       },
       "DashboardRuntimeDatasource": {
         "type": "object",
-        "description": "The datasource a runtime query was bound to.",
+        "description": "The datasource a runtime variable or query was bound to.",
         "properties": {
           "id": {
             "type": "integer",
             "format": "uint64",
             "minimum": 1,
-            "description": "Datasource ID."
+            "description": "Datasource ID, as listed by the datasource list endpoint."
           },
           "type": {
             "type": "string",
             "pattern": "^[a-z][a-z0-9_]{0,63}$",
-            "description": "Datasource type identifier."
+            "description": "Datasource type identifier. Resolved queries and `query` variables only use `prometheus`, `mysql` or `loki`; the datasource chosen by a `datasource` variable can be any type identifier the variable was configured with."
           },
           "name": {
             "type": "string",
@@ -11921,12 +12242,12 @@
       },
       "DashboardResolvedVariable": {
         "type": "object",
-        "description": "One resolved variable. An unreachable datasource, a bad expression or an empty result leaves `candidates` incomplete and fills `error` instead of failing the request.",
+        "description": "One resolved variable. A failure (no selection and no default, a selection outside the candidates, an unresolved dependency, an unreachable datasource, an unusable query result) fills `error` and leaves `selection` out instead of failing the request.",
         "properties": {
           "name": {
             "type": "string",
             "pattern": "^[A-Za-z_][A-Za-z0-9_]{0,63}$",
-            "description": "Variable name."
+            "description": "Variable name, as defined in the dashboard or draft."
           },
           "kind": {
             "type": "string",
@@ -11942,7 +12263,7 @@
             "items": {
               "$ref": "#/components/schemas/DashboardCandidate"
             },
-            "description": "Resolved candidates, at most 1000."
+            "description": "Selectable options, at most 1000; an empty array when there are none or resolution failed. Order: `custom` keeps the definition order, `datasource` is sorted by name then ID, `query` is sorted by value."
           },
           "selection": {
             "$ref": "#/components/schemas/DashboardSelection"
@@ -11977,13 +12298,13 @@
             "additionalProperties": {
               "$ref": "#/components/schemas/DashboardSelection"
             },
-            "description": "Selections already made, keyed by variable name, at most 20 entries. Variables omitted here fall back to their stored defaults."
+            "description": "Selections already made, keyed by variable name, at most 20 entries. Variables without an entry fall back to their stored defaults; a name the dashboard does not define fails the call with HTTP 400.",
+            "maxProperties": 20
           }
         },
         "required": [
           "dashboard_id",
-          "time",
-          "variables"
+          "time"
         ]
       },
       "DashboardVariablesResolveResponse": {
@@ -11993,7 +12314,7 @@
           "dashboard_id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "Dashboard ID."
+            "description": "ID of the dashboard the variables were resolved for, echoing the request."
           },
           "revision": {
             "type": "integer",
@@ -12030,7 +12351,7 @@
           "ref_id": {
             "type": "string",
             "pattern": "^[A-Z]$",
-            "description": "Panel-local query reference."
+            "description": "Query reference within the panel: a single letter `A`–`Z`."
           },
           "datasource": {
             "$ref": "#/components/schemas/DashboardRuntimeDatasource"
@@ -12042,27 +12363,24 @@
               "instant",
               "window"
             ],
-            "description": "Evaluation mode: `range` = a stepped time series; `instant` = a single point in time; `window` = raw rows inside a bounded time window."
+            "description": "Evaluation mode: `range` = a stepped time series; `instant` = a single point in time; `window` = rows inside a bounded time window. Prometheus and Loki queries use `range` or `instant`; MySQL queries use `window`."
           },
           "expr": {
             "type": "string",
-            "description": "Expression with variable templates substituted."
+            "description": "Expression with variable templates substituted. Built-in time variables stay verbatim when the request set `preserve_builtin_variables` to `true`."
           },
           "args": {
             "type": "object",
             "additionalProperties": {
               "type": "string"
             },
-            "description": "Query arguments; empty object when none."
+            "description": "Query arguments; an empty object when none. Only Loki queries carry arguments: `loki.limit` (a decimal integer from 1 to 1000, the maximum number of log entries) and `loki.direction` (`latest` or `earliest`)."
           },
           "min_step_seconds": {
-            "type": [
-              "integer",
-              "null"
-            ],
+            "type": "integer",
             "format": "int64",
             "minimum": 1,
-            "description": "Minimum step in seconds; null when unset."
+            "description": "Minimum step in seconds from the panel query; omitted when unset."
           }
         },
         "required": [
@@ -12075,12 +12393,12 @@
       },
       "DashboardResolvedPanelQueries": {
         "type": "object",
-        "description": "Per-panel resolution result. `state` is `success` when every query resolved, `partial` when some did and `error` when none did.",
+        "description": "Per-panel resolution result. `state` is `success` when every query resolved, `partial` when some did and `error` when none did. `error` describes only the first failure.",
         "properties": {
           "panel_id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "Panel ID."
+            "description": "ID of the panel, echoing an entry of `panel_ids`."
           },
           "state": {
             "type": "string",
@@ -12089,14 +12407,14 @@
               "partial",
               "error"
             ],
-            "description": "Aggregate state of the panel's queries: `success` = every query resolved; `partial` = some resolved; `error` = none resolved."
+            "description": "Resolution state of the panel's queries: `success` = every query resolved; `partial` = some resolved and some failed; `error` = none resolved, including a panel that does not exist."
           },
           "queries": {
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/DashboardResolvedQuery"
             },
-            "description": "Successfully resolved queries."
+            "description": "Queries that resolved successfully, in the panel's query order. Queries that failed are left out; empty array when none resolved."
           },
           "error": {
             "$ref": "#/components/schemas/DashboardRuntimeError"
@@ -12135,7 +12453,8 @@
             "additionalProperties": {
               "$ref": "#/components/schemas/DashboardSelection"
             },
-            "description": "Selections keyed by variable name, at most 20 entries."
+            "description": "Selections keyed by variable name, at most 20 entries. Variables without an entry fall back to their stored defaults; a name the dashboard does not define fails the call with HTTP 400.",
+            "maxProperties": 20
           },
           "max_data_points": {
             "type": [
@@ -12144,7 +12463,7 @@
             ],
             "minimum": 2,
             "maximum": 5000,
-            "description": "Downsampling target used to compute the step and render the built-in time variables, 2–5000 points; omit or send null for the server default of 100."
+            "description": "Target maximum number of points per series, used to compute the step and render the built-in time variables. 2–5000; omit or send null for the default of 100."
           },
           "preserve_builtin_variables": {
             "type": "boolean",
@@ -12154,18 +12473,17 @@
         "required": [
           "dashboard_id",
           "panel_ids",
-          "time",
-          "variables"
+          "time"
         ]
       },
       "DashboardQueriesResolveResponse": {
         "type": "object",
-        "description": "One entry per requested panel, in request order.",
+        "description": "Resolved queries of the requested panels, plus the effective variable selections they were resolved with. Nothing is executed.",
         "properties": {
           "dashboard_id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "Dashboard ID."
+            "description": "ID of the dashboard the queries were resolved against, echoing the request."
           },
           "revision": {
             "type": "integer",
@@ -12181,14 +12499,14 @@
             "additionalProperties": {
               "$ref": "#/components/schemas/DashboardSelection"
             },
-            "description": "Selections that resolved successfully."
+            "description": "Effective selections of the variables that resolved successfully, keyed by variable name; variables that failed to resolve are left out."
           },
           "panels": {
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/DashboardResolvedPanelQueries"
             },
-            "description": "Per-panel results."
+            "description": "One entry per requested panel, in request order."
           }
         },
         "required": [
@@ -12206,12 +12524,12 @@
           "max_concurrency": {
             "type": "integer",
             "minimum": 1,
-            "description": "Concurrency cap applied to the panel's queries."
+            "description": "Maximum number of the panel's queries executed at the same time; fixed at 6."
           },
           "execution_count": {
             "type": "integer",
             "minimum": 0,
-            "description": "Number of queries launched."
+            "description": "Number of queries that resolved successfully and were dispatched for execution; queries that failed to resolve are not counted."
           }
         },
         "required": [
@@ -12221,12 +12539,12 @@
       },
       "DashboardPanelRunRef": {
         "type": "object",
-        "description": "Result of one query inside a panel run. The raw execution payload differs per datasource type and is passed through unmodified, so it is not schema-constrained here.",
+        "description": "Result of one query inside a panel run or preview. The raw execution payload differs per datasource type and is passed through unmodified, so it is not schema-constrained here.",
         "properties": {
           "ref_id": {
             "type": "string",
             "pattern": "^[A-Z]$",
-            "description": "Panel-local query reference."
+            "description": "Query reference within the panel: a single letter `A`–`Z`, as set in the panel's `queries`."
           },
           "state": {
             "type": "string",
@@ -12235,16 +12553,16 @@
               "error",
               "incompatible"
             ],
-            "description": "Per-query execution state: `success` = the query executed; `error` = the query failed; `incompatible` = the datasource accepted the call but the query mode or field selection does not fit the datasource type."
+            "description": "Per-query state: `success` = the query ran and `execution` is present; `error` = the query could not be resolved or executed, or the run was cancelled or timed out, and `error` explains why; `incompatible` = the query ran, but its result does not fit the panel's visualization (for example a configured field is missing or not numeric), so `execution` is still present and `error` explains the mismatch."
           },
           "child_request_id": {
             "type": "string",
-            "description": "Request ID of the underlying datasource execution; use it when tracing a single query."
+            "description": "Request ID of the underlying datasource execution; use it when tracing a single query. Absent when the query never reached the datasource."
           },
           "execution": {
             "type": "object",
             "additionalProperties": true,
-            "description": "Datasource-specific execution payload, passed through unmodified."
+            "description": "Datasource-specific execution result, passed through unmodified. Present when `state` is `success` or `incompatible`; absent when `state` is `error`."
           },
           "error": {
             "$ref": "#/components/schemas/DashboardRuntimeError"
@@ -12257,7 +12575,7 @@
       },
       "DashboardPanelRunRequest": {
         "type": "object",
-        "description": "Execute one panel against the stored dashboard. Omit `revision` to run the current revision; send it to have stale responses rejected.",
+        "description": "Execute one panel of a stored dashboard. Omit `revision` (or send 0) to run the current revision; send it to have a stale call rejected. Text panels cannot be run.",
         "properties": {
           "dashboard_id": {
             "type": "string",
@@ -12267,13 +12585,12 @@
           "panel_id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "Panel to execute."
+            "description": "ID of the panel to execute. It must belong to the dashboard, otherwise the call returns `TargetNotFound` (HTTP 404)."
           },
           "revision": {
             "type": "integer",
             "format": "uint64",
-            "minimum": 1,
-            "description": "Revision guard; when set it must equal the current revision."
+            "description": "Revision guard. When set (non-zero) it must equal the dashboard's current revision, otherwise the call fails with `DashboardRevisionConflict` (HTTP 409). Omit or send 0 to skip the check."
           },
           "time": {
             "$ref": "#/components/schemas/DashboardAbsoluteTimeRange"
@@ -12283,7 +12600,8 @@
             "additionalProperties": {
               "$ref": "#/components/schemas/DashboardSelection"
             },
-            "description": "Selections keyed by variable name, at most 20 entries."
+            "description": "Selections keyed by variable name, at most 20 entries. Variables without an entry fall back to their stored defaults; a name the dashboard does not define fails the call with HTTP 400.",
+            "maxProperties": 20
           },
           "max_data_points": {
             "type": [
@@ -12292,29 +12610,28 @@
             ],
             "minimum": 2,
             "maximum": 5000,
-            "description": "Downsampling target, 2–5000 points; omit or send null for the server default of 100."
+            "description": "Target maximum number of points per series for `range` queries; the server derives the query step from it. 2–5000; omit or send null for the default of 100."
           }
         },
         "required": [
           "dashboard_id",
           "panel_id",
-          "time",
-          "variables"
+          "time"
         ]
       },
       "DashboardPanelRunResponse": {
         "type": "object",
-        "description": "Panel execution result. `run_state` aggregates the per-query states: `success` when all succeeded, `partial` when some did, otherwise `incompatible`, `cancelled` or `error`. The total response is capped at 8 MiB.",
+        "description": "Panel execution result. HTTP 200 is returned even when every query failed; read `run_state` and each ref's `state` and `error`. A response larger than 8 MiB is rejected with `EntityTooLarge` (HTTP 413) instead of being truncated.",
         "properties": {
           "dashboard_id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "Dashboard ID."
+            "description": "ID of the dashboard that was run, echoing the request."
           },
           "panel_id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "Panel ID."
+            "description": "ID of the panel that was run, echoing the request."
           },
           "revision": {
             "type": "integer",
@@ -12331,7 +12648,7 @@
               "cancelled",
               "error"
             ],
-            "description": "Aggregate state of the run: `success` = all queries succeeded; `partial` = some succeeded; `incompatible` = at least one query is incompatible with its datasource; `cancelled` = the run was cancelled; `error` = all queries failed."
+            "description": "Aggregate state of the run: `success` = every query succeeded; `partial` = at least one query succeeded and at least one did not; `cancelled` = no query succeeded and the client cancelled the request; `incompatible` = no query succeeded and at least one query ran but returned a result that does not fit the panel's visualization; `error` = no query succeeded and none is `incompatible` (also when the panel has no queries)."
           },
           "time": {
             "$ref": "#/components/schemas/DashboardAbsoluteTimeRange"
@@ -12341,14 +12658,14 @@
             "additionalProperties": {
               "$ref": "#/components/schemas/DashboardSelection"
             },
-            "description": "Selections that resolved successfully."
+            "description": "Effective selections of the variables that resolved successfully, keyed by variable name; variables that failed to resolve are left out."
           },
           "refs": {
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/DashboardPanelRunRef"
             },
-            "description": "One entry per query in the panel."
+            "description": "One entry per query of the panel, in the panel's query order. A query that failed to resolve appears with `state` `error`."
           },
           "display": {
             "$ref": "#/components/schemas/DashboardVizConfig"
@@ -12384,13 +12701,13 @@
           "dashboard_id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "Required for `existing`, forbidden for `new`."
+            "description": "Required for `existing`, forbidden for `new`. The caller must have access to the dashboard's folder."
           },
           "folder_id": {
             "type": "integer",
             "format": "uint64",
             "minimum": 1,
-            "description": "Required for `new`, forbidden for `existing`."
+            "description": "Required for `new`, forbidden for `existing`. Must be a folder the caller can access, otherwise the call returns `FolderNotFound` (HTTP 404)."
           }
         },
         "required": [
@@ -12410,14 +12727,15 @@
               "$ref": "#/components/schemas/DashboardVariable"
             },
             "maxItems": 20,
-            "description": "Draft variables, at most 20."
+            "description": "Draft variables, at most 20. They are validated like a stored definition (names, dependencies, option limits) and must stay within 1 MiB."
           },
           "selections": {
             "type": "object",
             "additionalProperties": {
               "$ref": "#/components/schemas/DashboardSelection"
             },
-            "description": "Selections keyed by variable name, at most 20 entries."
+            "description": "Selections keyed by variable name, at most 20 entries. Variables without an entry fall back to their draft default; a name that is not in `variables` fails the call with HTTP 400.",
+            "maxProperties": 20
           },
           "time": {
             "$ref": "#/components/schemas/DashboardAbsoluteTimeRange"
@@ -12426,7 +12744,6 @@
         "required": [
           "context",
           "variables",
-          "selections",
           "time"
         ]
       },
@@ -12439,14 +12756,14 @@
             "items": {
               "$ref": "#/components/schemas/DashboardResolvedVariable"
             },
-            "description": "Resolved variables."
+            "description": "Resolved variables, in the order of the draft `variables`."
           },
           "selections": {
             "type": "object",
             "additionalProperties": {
               "$ref": "#/components/schemas/DashboardSelection"
             },
-            "description": "Effective selections keyed by variable name."
+            "description": "Effective selections keyed by variable name; only variables that resolved successfully appear."
           }
         },
         "required": [
@@ -12456,7 +12773,7 @@
       },
       "DashboardPanelPreviewRequest": {
         "type": "object",
-        "description": "Execute a draft panel inline, without saving a dashboard revision. Subject to the same 1 MiB definition-size ceiling.",
+        "description": "Execute a draft panel inline, without saving a dashboard revision. The draft `panel` and `variables` together must stay within 1 MiB, and the request body within 2 MiB.",
         "properties": {
           "context": {
             "$ref": "#/components/schemas/DashboardDraftContext"
@@ -12470,14 +12787,15 @@
               "$ref": "#/components/schemas/DashboardVariable"
             },
             "maxItems": 20,
-            "description": "Draft variables the panel may reference."
+            "description": "Draft variables the panel may reference, at most 20. Required; the panel's queries can only use variables listed here."
           },
           "selections": {
             "type": "object",
             "additionalProperties": {
               "$ref": "#/components/schemas/DashboardSelection"
             },
-            "description": "Selections keyed by variable name."
+            "description": "Selections keyed by variable name, at most 20 entries. Variables without an entry fall back to their draft default.",
+            "maxProperties": 20
           },
           "time": {
             "$ref": "#/components/schemas/DashboardAbsoluteTimeRange"
@@ -12489,25 +12807,24 @@
             ],
             "minimum": 2,
             "maximum": 5000,
-            "description": "Downsampling target, 2–5000 points."
+            "description": "Target maximum number of points per series for `range` queries; the server derives the query step from it. 2–5000; omit or send null for the default of 100."
           }
         },
         "required": [
           "context",
           "panel",
           "variables",
-          "selections",
           "time"
         ]
       },
       "DashboardPanelPreviewResponse": {
         "type": "object",
-        "description": "Draft panel execution result. Same shape as a stored panel run, minus the dashboard identity.",
+        "description": "Draft panel execution result. Same shape as a stored panel run, minus `dashboard_id` and `revision`. HTTP 200 is returned even when every query failed; a response larger than 8 MiB is rejected with `EntityTooLarge` (HTTP 413).",
         "properties": {
           "panel_id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "Panel ID."
+            "description": "ID of the draft panel, echoing `panel.id` from the request."
           },
           "run_state": {
             "type": "string",
@@ -12518,7 +12835,7 @@
               "cancelled",
               "error"
             ],
-            "description": "Aggregate state of the run: `success` = all queries succeeded; `partial` = some succeeded; `incompatible` = at least one query is incompatible with its datasource; `cancelled` = the run was cancelled; `error` = all queries failed."
+            "description": "Aggregate state of the run: `success` = every query succeeded; `partial` = at least one query succeeded and at least one did not; `cancelled` = no query succeeded and the client cancelled the request; `incompatible` = no query succeeded and at least one query ran but returned a result that does not fit the panel's visualization; `error` = no query succeeded and none is `incompatible` (also when the panel has no queries)."
           },
           "time": {
             "$ref": "#/components/schemas/DashboardAbsoluteTimeRange"
@@ -12528,14 +12845,14 @@
             "additionalProperties": {
               "$ref": "#/components/schemas/DashboardSelection"
             },
-            "description": "Selections that resolved successfully."
+            "description": "Effective selections of the variables that resolved successfully, keyed by variable name; variables that failed to resolve are left out."
           },
           "refs": {
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/DashboardPanelRunRef"
             },
-            "description": "One entry per query in the panel."
+            "description": "One entry per query of the panel, in the panel's query order. A query that failed to resolve appears with `state` `error`."
           },
           "display": {
             "$ref": "#/components/schemas/DashboardVizConfig"
@@ -12556,12 +12873,12 @@
       },
       "FolderItem": {
         "type": "object",
-        "description": "A monitor folder (监控节点). Folders form a tree; `parent_path` is the comma-separated ancestor ID list, so the caller can rebuild the tree and search it client-side.",
+        "description": "A monitor folder. Folders form a tree; `parent_path` is the comma-separated ancestor ID list, so the caller can rebuild the tree and search it client-side.",
         "properties": {
           "id": {
             "type": "integer",
             "format": "uint64",
-            "description": "Folder ID."
+            "description": "Folder ID. Pass it as `id` to update, move, or delete the folder, as `parent_id` or `dest_parent_id` to nest folders under it, and as `folder_id` on alert rules and dashboards."
           },
           "account_id": {
             "type": "integer",
@@ -12580,7 +12897,7 @@
           "team_id": {
             "type": "integer",
             "format": "uint64",
-            "description": "Team the folder is scoped to; 0 when account-wide."
+            "description": "ID of the team the folder belongs to; 0 when it has no team. Members of the team can see and modify the folder."
           },
           "name": {
             "type": "string",
@@ -12593,7 +12910,7 @@
           "creator_id": {
             "type": "integer",
             "format": "uint64",
-            "description": "Member ID of the creator."
+            "description": "Member ID of the creator; the creator can always see and modify the folder."
           },
           "creator_name": {
             "type": "string",
@@ -12602,7 +12919,7 @@
           "updater_id": {
             "type": "integer",
             "format": "uint64",
-            "description": "Member ID of the last updater."
+            "description": "Member ID of the last updater. Updates and moves both set it."
           },
           "updater_name": {
             "type": "string",
@@ -12611,12 +12928,12 @@
           "created_at": {
             "type": "integer",
             "format": "int64",
-            "description": "Unix timestamp in seconds."
+            "description": "Creation time as a Unix timestamp in seconds."
           },
           "updated_at": {
             "type": "integer",
             "format": "int64",
-            "description": "Unix timestamp in seconds."
+            "description": "Time of the last update or move as a Unix timestamp in seconds."
           }
         },
         "required": [
@@ -12637,26 +12954,26 @@
       },
       "FolderCreateRequest": {
         "type": "object",
-        "description": "Monitor folder request.",
+        "description": "Request to create a monitor folder.",
         "properties": {
           "name": {
             "type": "string",
-            "description": "Folder name; cannot contain a period, slash, or comma.",
+            "description": "Folder name; required, and must not contain a period (`.`), slash (`/`), or comma (`,`).",
             "minLength": 1
           },
           "note": {
             "type": "string",
-            "description": "Free-form note; omitted or empty clears the note on update."
+            "description": "Free-form note. Empty when omitted."
           },
           "parent_id": {
             "type": "integer",
-            "description": "Parent folder ID; 0 or omitted creates a root folder.",
+            "description": "ID of the parent folder; 0 or omitted creates a root folder. The caller must be allowed to modify the parent.",
             "format": "uint64",
             "minimum": 0
           },
           "team_id": {
             "type": "integer",
-            "description": "Team ID; 0 means account-wide. Omitted on update resets to 0.",
+            "description": "ID of the team the folder belongs to; 0 or omitted means no team. Members of the team can see and modify the folder and everything below it.",
             "format": "uint64",
             "minimum": 0
           }
@@ -12667,26 +12984,26 @@
       },
       "FolderUpdateRequest": {
         "type": "object",
-        "description": "Monitor folder request.",
+        "description": "Request to update a monitor folder. Editable fields are replaced as a whole.",
         "properties": {
           "id": {
             "type": "integer",
-            "description": "Folder ID.",
+            "description": "ID of the folder to update, from `/monit/folder/list` or the create response.",
             "format": "uint64",
             "minimum": 1
           },
           "name": {
             "type": "string",
-            "description": "Folder name; cannot contain a period, slash, or comma.",
+            "description": "New folder name; required, and must not contain a period (`.`), slash (`/`), or comma (`,`).",
             "minLength": 1
           },
           "note": {
             "type": "string",
-            "description": "Free-form note; omitted or empty clears the note on update."
+            "description": "New note. Omitted or empty clears the note."
           },
           "team_id": {
             "type": "integer",
-            "description": "Team ID; 0 means account-wide. Omitted on update resets to 0.",
+            "description": "New team ID; 0 or omitted removes the team assignment.",
             "format": "uint64",
             "minimum": 0
           }
@@ -12698,17 +13015,17 @@
       },
       "FolderMoveRequest": {
         "type": "object",
-        "description": "Monitor folder request.",
+        "description": "Request to move a monitor folder and its descendants.",
         "properties": {
           "id": {
             "type": "integer",
-            "description": "Folder ID.",
+            "description": "ID of the folder to move, from `/monit/folder/list`.",
             "format": "uint64",
             "minimum": 1
           },
           "dest_parent_id": {
             "type": "integer",
-            "description": "Destination parent folder ID; required even when 0 to move to the root.",
+            "description": "ID of the new parent folder; send 0 to move to the root. The field cannot be omitted. Must differ from `id` and must not be a descendant of the folder.",
             "format": "uint64",
             "minimum": 0
           }
@@ -12720,11 +13037,11 @@
       },
       "FolderDeleteRequest": {
         "type": "object",
-        "description": "Monitor folder request.",
+        "description": "Request to delete a monitor folder.",
         "properties": {
           "id": {
             "type": "integer",
-            "description": "Folder ID.",
+            "description": "ID of the folder to delete, from `/monit/folder/list`. The folder must be empty.",
             "format": "uint64",
             "minimum": 1
           }
@@ -12739,13 +13056,13 @@
         "properties": {
           "folder_id": {
             "type": "integer",
-            "description": "Folder ID.",
+            "description": "ID of the folder this entry describes; matches `id` in `/monit/folder/list`.",
             "format": "uint64",
             "minimum": 0
           },
           "has_issue": {
             "type": "boolean",
-            "description": "Whether this folder or a visible descendant has active alerts or rule runtime issues."
+            "description": "`true` when a rule in this folder or in any descendant has an active alert or a runtime problem (`runtime_state` of `offline`, `abnormal`, `stale`, or `no_datasource`). Rules in folders the caller cannot read are not counted."
           }
         },
         "required": [
@@ -12759,7 +13076,7 @@
         "properties": {
           "items": {
             "type": "array",
-            "description": "Folder health summaries.",
+            "description": "One health entry per folder visible to the caller, sorted by `folder_id`.",
             "items": {
               "$ref": "#/components/schemas/FolderHealthItem"
             }
diff --git a/api-reference/monitors.openapi.zh.json b/api-reference/monitors.openapi.zh.json
index e51b3412b..283a28247 100644
--- a/api-reference/monitors.openapi.zh.json
+++ b/api-reference/monitors.openapi.zh.json
@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Flashduty 开放 API",
-    "description": "Flashduty 事件管理平台的公开 HTTP API —— 覆盖故障、通知模板、协作空间、值班排班、监控、RUM、以及平台管理。每次调用都需在 query 中携带 `app_key`，该 key 在 Flashduty 控制台 账户 → APP Key 中签发。所有响应使用统一结构：成功时为 `{ request_id, data }`，失败时为 `{ request_id, error }`。",
+    "description": "Flashduty 事件管理平台的公开 HTTP API —— 覆盖故障、通知模板、协作空间、值班排班、监控、RUM、以及平台管理。每次调用都需在 query 中携带 `app_key`，该 key 在 Flashduty 控制台 我的 → APP Key 中创建（也可放在请求头 `Fd-App-Key` 中）。所有响应使用统一结构：成功时为 `{ request_id, data }`，失败时为 `{ request_id, error }`。",
     "version": "1.0.0"
   },
   "servers": [
@@ -52,7 +52,7 @@
           "Monitors/告警规则"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **告警规则查看**（`monit`） |\n\n## 使用说明\n\n- 每一项为一次历史快照：`num` 为 `clock`（Unix 时间戳，秒）时刻的规则总数。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **概览查看**（`monit`） |\n\n## 使用说明\n\n- 每一项为一次历史快照：`num` 为 `clock`（Unix 时间戳，秒）时刻账户下告警规则的总数（含启用与禁用的规则）。\n- 大约每 12 小时记录一次快照（每小时运行的任务在最近 12 小时内没有快照时补记一条）。返回全部快照，按时间从早到晚排列；尚未记录任何快照时返回空数组。",
           "href": "/zh/api-reference/monitors/alert-rules/monit-rule-read-counter-total",
           "metadata": {
             "sidebarTitle": "查看规则数量时序"
@@ -83,7 +83,13 @@
                   "data": [
                     {
                       "id": 1,
-                      "account_id": 10023,
+                      "account_id": 888,
+                      "num": 48,
+                      "clock": 1711956000
+                    },
+                    {
+                      "id": 2,
+                      "account_id": 888,
                       "num": 50,
                       "clock": 1712000000
                     }
@@ -98,6 +104,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -122,12 +131,12 @@
       "post": {
         "operationId": "monit-datasource-write-create",
         "summary": "创建数据源",
-        "description": "创建新的监控数据源，`payload` 中须包含对应类型的配置块。 支持诊断类型 redis_node、redis_sentinel、mongodb_mongod、mongodb_mongos 和 kafka；enabled 与 alerting_enabled 相互独立。",
+        "description": "创建一个监控数据源（支持 15 种类型），并将其绑定到某个 Monitors edge 集群。",
         "tags": [
           "Monitors/告警数据源"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **数据源管理**（`monit`） |\n\n## 使用说明\n\n- `type_ident` 必须为以下之一：`prometheus`、`loki`、`mysql`、`oracle`、`postgres`、`clickhouse`、`elasticsearch`、`sls`、`tencent_cls`、`victorialogs`、`redis_node`、`redis_sentinel`、`mongodb_mongod`、`mongodb_mongos`、`kafka`。\n- `edge_cluster_name` 指定使用该数据源进行规则评估的 Monitors Edge 集群。\n- 对于 `elasticsearch`，`payload.elasticsearch.deployment` 须设为 `cloud` 或 `self-managed`。\n- 每次调用都会记录到账户审计日志，仅通过凭据字段配置连接凭据。\n\n完整支持类型与凭据行为见请求/响应 Schema。仅诊断类型不能启用告警。创建时省略 enabled 默认为 true，更新时省略保留当前值；enabled 或 alerting_enabled 的显式 null 非法。诊断密码及 Kafka 私钥在响应中省略，环境变量引用除外；更新时省略秘密字段保留原值，空字符串清除。其他数据源凭据可能返回，应作为敏感数据处理。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **数据源管理**（`monit`） |\n\n## 使用说明\n\n- `type_ident` 必须为以下之一：`prometheus`, `loki`, `mysql`, `oracle`, `postgres`, `clickhouse`, `elasticsearch`, `sls`, `tencent_cls`, `victorialogs`, `redis_node`, `redis_sentinel`, `mongodb_mongod`, `mongodb_mongos`, `kafka`。后五种（`redis_node`、`redis_sentinel`、`mongodb_mongod`、`mongodb_mongos`、`kafka`）仅用于诊断，不能评估告警，因此 `alerting_enabled` 不能为 `true`。\n- `name` 在账户内唯一（不区分类型），重名时返回 `InvalidParameter`。\n- `edge_cluster_name` 必须是账户下已存在的 Monitors edge 集群；该集群负责评估规则并执行该数据源的查询。\n- 类型专属配置放在 `payload.<type_ident>` 中。`elasticsearch` 必须设置 `payload.elasticsearch.deployment`（`cloud` 或 `self-managed`）。`tencent_cls` 要求集群内所有 edge 实例均为 Monitors edge v0.66.0 或更高版本。\n- 省略 `enabled` 时默认为 `true`；省略 `alerting_enabled` 时，告警类默认 `true`，仅诊断类默认 `false`。两者显式传 `null` 都会被拒绝。\n- `manage_team_id` 和 `readonly_team_ids` 用于限制谁能管理或查询该数据源；两者都省略则对所有成员开放。\n- 响应会原样返回非诊断类型的凭据（例如 Prometheus 的 Basic Auth 密码）；诊断类型的密码和 Kafka 私钥仅在它们是 `${env:NAME}` 引用时才返回。请将响应视为敏感信息。\n- 每次调用都会记录到账户审计日志。",
           "href": "/zh/api-reference/monitors/data-sources/monit-datasource-write-create",
           "metadata": {
             "sidebarTitle": "创建数据源"
@@ -157,12 +166,26 @@
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "id": 10,
+                    "account_id": 10023,
                     "type_ident": "prometheus",
                     "name": "Prometheus Prod",
                     "enabled": true,
+                    "note": "Production Prometheus",
+                    "address": "http://prometheus.example.com:9090",
+                    "payload": {
+                      "prometheus": {
+                        "basic_auth_enabled": false,
+                        "basic_auth_username": "",
+                        "basic_auth_password": "",
+                        "tls_skip_verify": false
+                      }
+                    },
                     "edge_cluster_name": "default",
                     "updated_at": 1712000000,
-                    "alerting_enabled": true
+                    "alerting_enabled": true,
+                    "manage_team_id": null,
+                    "readonly_team_ids": null,
+                    "creator_id": 20001
                   }
                 }
               }
@@ -174,6 +197,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -209,12 +235,12 @@
       "post": {
         "operationId": "monit-datasource-write-update",
         "summary": "更新数据源",
-        "description": "更新已有数据源，需提供 `id` 及待修改的字段。 支持诊断类型 redis_node、redis_sentinel、mongodb_mongod、mongodb_mongos 和 kafka；enabled 与 alerting_enabled 相互独立。",
+        "description": "按 ID 更新数据源，整体替换其名称、备注、地址、payload 和 edge 集群。",
         "tags": [
           "Monitors/告警数据源"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **数据源管理**（`monit`） |\n\n## 使用说明\n\n- 每次调用都会记录到账户审计日志，仅通过凭据字段配置连接凭据。\n\n完整支持类型与凭据行为见请求/响应 Schema。仅诊断类型不能启用告警。创建时省略 enabled 默认为 true，更新时省略保留当前值；enabled 或 alerting_enabled 的显式 null 非法。诊断密码及 Kafka 私钥在响应中省略，环境变量引用除外；更新时省略秘密字段保留原值，空字符串清除。其他数据源凭据可能返回，应作为敏感数据处理。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **数据源管理**（`monit`） |\n\n## 使用说明\n\n- 这是整体替换而非局部更新：每次调用都要发送 `type_ident`、`name`、`edge_cluster_name`、`payload`，以及 `address`（`cloud` 部署的 Elasticsearch 除外）。`note`、`address`、`payload` 会覆盖已保存的值，因此省略 `note` 会将其清空。\n- 省略 `enabled`、`alerting_enabled`、`manage_team_id`、`readonly_team_ids` 时保持原值。`enabled` 或 `alerting_enabled` 传 `null` 会被拒绝；两个团队字段传 `null` 表示清除。\n- 密钥：诊断类型省略密码（以及 Kafka 的 `tls_key`）表示保留已保存的值，传空字符串表示清除；`tencent_cls` 省略或传空的 `secret_key` 表示保留已保存的密钥；其他类型需要重新发送凭据。\n- 将 `enabled` 或 `alerting_enabled` 设为 `false`，或修改 `type_ident`、`edge_cluster_name`，会关闭使用该数据源的规则上的未恢复告警；重命名时，会关闭 `ds_list` 名称模式不再匹配新名称的规则上的未恢复告警。\n- 只要仍有已启用的告警规则选中该数据源，关闭 `alerting_enabled` 会返回 HTTP 409 `UndonedOrderExist`。\n- 只有账户所有者、管理员、创建者和负责团队成员可以更新数据源（未设置负责团队时，拥有该权限的调用方均可）；其他人返回 `AccessDenied`。ID 不存在或属于其他账户时返回 `ResourceNotFound`。\n- 每次调用都会记录到账户审计日志。",
           "href": "/zh/api-reference/monitors/data-sources/monit-datasource-write-update",
           "metadata": {
             "sidebarTitle": "更新数据源"
@@ -244,12 +270,26 @@
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "id": 10,
+                    "account_id": 10023,
                     "type_ident": "prometheus",
                     "name": "Prometheus Prod v2",
                     "enabled": true,
+                    "note": "Updated",
+                    "address": "http://prometheus-v2.example.com:9090",
+                    "payload": {
+                      "prometheus": {
+                        "basic_auth_enabled": false,
+                        "basic_auth_username": "",
+                        "basic_auth_password": "",
+                        "tls_skip_verify": false
+                      }
+                    },
                     "edge_cluster_name": "default",
                     "updated_at": 1712100000,
-                    "alerting_enabled": true
+                    "alerting_enabled": true,
+                    "manage_team_id": null,
+                    "readonly_team_ids": null,
+                    "creator_id": 20001
                   }
                 }
               }
@@ -261,6 +301,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -302,7 +345,7 @@
           "Monitors/告警规则"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **告警规则管理**（`monit`） |\n\n## 使用说明\n\n- 如果目标文件夹中已存在同名规则，该规则会被跳过；请检查每条结果的 `message` 以识别冲突。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **告警规则管理**（`monit`） |\n\n## 使用说明\n\n- `dest_folder_id` 必须是已存在的文件夹，且调用者须对该文件夹有管理权限（账户所有者或管理员、该文件夹或其上级文件夹的创建者，或绑定到该文件夹或其上级文件夹的团队成员）；否则整个调用返回 `AccessDenied`，不会移动任何规则。\n- 结果按请求顺序为每个 ID 返回一项。移动成功的规则 `message` 为本地化的成功文案（`Move successfully` / `移动成功`）；未移动的规则保留在原文件夹，`message` 为错误信息。\n- 目标文件夹已有同名规则、调用者对规则当前所在文件夹无管理权限，或 ID 不存在（此时 `name` 为 `id: <id>`）时，该规则不会被移动。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/monitors/alert-rules/monit-rule-write-move",
           "metadata": {
             "sidebarTitle": "移动告警规则到文件夹"
@@ -333,7 +376,11 @@
                   "data": [
                     {
                       "name": "CPU High",
-                      "message": ""
+                      "message": "移动成功"
+                    },
+                    {
+                      "name": "Disk High",
+                      "message": "alert rule name already exists in this folder"
                     }
                   ]
                 }
@@ -346,6 +393,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -376,12 +426,12 @@
       "post": {
         "operationId": "monit-rule-read-audit-detail",
         "summary": "查看规则审计快照",
-        "description": "返回审计记录（包含 `content` 字段，即该时间点规则配置的 JSON 字符串快照）。",
+        "description": "返回告警规则的一条审计记录，包含保存在 `content` 中的规则快照。",
         "tags": [
           "Monitors/告警规则"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **告警规则查看**（`monit`） |\n\n## 使用说明\n\n- 传入来自 `POST /monit/rule/audits` 的审计记录 `id`（非规则 `id`）。\n- `content` 为 JSON 字符串，解析后可获得完整的规则快照。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 任意有效 `app_key` 均可调用 |\n\n## 使用说明\n\n- 传入来自 `POST /monit/rule/audits` 的审计记录 `id`（非规则 `id`）。ID 不存在时返回 `InvalidParameter`（`alert rule audit not found`）。\n- `content` 为 JSON 字符串，解析后可获得规则快照；其结构取决于写入该记录的操作（见下方 `content` 字段说明）。\n- 调用者须对规则所在文件夹有管理权限（账户所有者或管理员、该文件夹或其上级文件夹的创建者，或绑定到该文件夹或其上级文件夹的团队成员），否则返回 `AccessDenied`。规则被删除后其审计记录无法再读取，调用返回 `InvalidParameter`（`alert rule not found`）。",
           "href": "/zh/api-reference/monitors/alert-rules/monit-rule-read-audit-detail",
           "metadata": {
             "sidebarTitle": "查看规则审计快照"
@@ -411,13 +461,13 @@
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "id": 9001,
-                    "account_id": 10023,
+                    "account_id": 888,
                     "alert_rule_id": 50001,
                     "action": "update",
-                    "content": "{\"id\":50001,\"name\":\"CPU High\"}",
-                    "creator_id": 80011,
-                    "creator_name": "Alice",
-                    "created_at": 1712000000
+                    "content": "{\"id\":50001,\"account_id\":888,\"folder_id\":100,\"name\":\"CPU High\",\"enabled\":true,\"updated_at\":1712003600}",
+                    "creator_id": 66,
+                    "creator_name": "zhangsan",
+                    "created_at": 1712003600
                   }
                 }
               }
@@ -429,6 +479,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -455,12 +508,12 @@
       "post": {
         "operationId": "monit-datasource-write-delete",
         "summary": "删除数据源",
-        "description": "通过 ID 删除数据源。引用该数据源的告警规则不会被阻塞：该数据源会从规则的监控范围中移除，规则上相关的未恢复告警会自动关闭。",
+        "description": "按 ID 删除数据源；引用它的告警规则不会被阻止。",
         "tags": [
           "Monitors/告警数据源"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **数据源管理**（`monit`） |\n\n## 使用说明\n\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **数据源管理**（`monit`） |\n\n## 使用说明\n\n- 引用该数据源的告警规则不会被阻止，也不会被修改；规则上该数据源的未恢复告警会自动关闭。\n- 删除不存在的 ID 会直接成功（无任何操作）；属于其他账户的 ID 返回 `ResourceNotFound`。\n- 只有账户所有者、管理员、创建者和负责团队成员可以删除数据源（未设置负责团队时，拥有该权限的调用方均可）；其他人返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志。",
           "href": "/zh/api-reference/monitors/data-sources/monit-datasource-write-delete",
           "metadata": {
             "sidebarTitle": "删除数据源"
@@ -499,6 +552,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -530,7 +586,7 @@
           "Monitors/告警规则"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **30 次/分钟**；**5 次/秒** |\n| 权限要求 | **告警规则管理**（`monit`） |\n\n## 使用说明\n\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **100 次/分钟**；**5 次/秒** |\n| 权限要求 | **告警规则管理**（`monit`） |\n\n## 使用说明\n\n- 按顺序逐个处理 ID，遇到第一个错误即停止；错误前已删除的规则不会恢复，请排除原因后重新提交剩余 ID。\n- 不存在的 ID 会被跳过，不报错。每条被删除规则的活跃告警会被清理。\n- `ids` 至少包含一个 ID。调用者须对每条规则所在的文件夹有管理权限（账户所有者或管理员、该文件夹或其上级文件夹的创建者，或绑定到该文件夹或其上级文件夹的团队成员），否则返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/monitors/alert-rules/monit-rule-write-delete-batch",
           "metadata": {
             "sidebarTitle": "批量删除告警规则"
@@ -569,6 +625,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -603,7 +662,7 @@
           "Monitors/告警数据源"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **数据源查看**（`monit`） |\n\n## 使用说明\n\n- `id` 指定的数据源类型必须为 `sls`。\n- 使用 `query` 按名称前缀过滤项目，使用 `offset` 和 `size` 分页。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **数据源查看**（`monit`） |\n\n## 使用说明\n\n- `id` 指定的数据源类型必须为 `sls`，其他类型返回 `InvalidParameter`。\n- 使用 `query` 过滤项目列表，使用 `offset` 和 `size` 分页；`count` 为当前页项目数，`total` 为满足过滤条件的项目总数。\n- 请求会转发给该数据源所属的 Monitors edge 集群，由 edge 使用已保存的凭据调用阿里云，30 秒超时。该集群没有在线的 edge 实例时返回 `InvalidParameter`；edge 版本不支持元数据发现时返回 HTTP 503 `ServiceUnavailable`。",
           "href": "/zh/api-reference/monitors/data-sources/monit-datasource-read-sls-projects",
           "metadata": {
             "sidebarTitle": "查询 SLS 项目列表"
@@ -665,6 +724,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -699,7 +761,7 @@
           "Monitors/告警数据源"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **数据源查看**（`monit`） |\n\n## 使用说明\n\n- `id` 指定的数据源类型必须为 `sls`。\n- 通过 `project` 指定要列出日志库的 SLS 项目。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **数据源查看**（`monit`） |\n\n## 使用说明\n\n- `id` 指定的数据源类型必须为 `sls`，其他类型返回 `InvalidParameter`。\n- 通过 `project` 指定要列出日志库的 SLS 项目；使用 `offset` 和 `size` 分页。响应是日志库名称组成的数组。\n- 请求会转发给该数据源所属的 Monitors edge 集群，由 edge 使用已保存的凭据调用阿里云，30 秒超时。该集群没有在线的 edge 实例时返回 `InvalidParameter`；edge 版本不支持元数据发现时返回 HTTP 503 `ServiceUnavailable`。",
           "href": "/zh/api-reference/monitors/data-sources/monit-datasource-read-sls-logstores",
           "metadata": {
             "sidebarTitle": "查询 SLS 日志库列表"
@@ -741,6 +803,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -770,12 +835,12 @@
       "post": {
         "operationId": "monit-datasource-read-info",
         "summary": "查看数据源详情",
-        "description": "通过 ID 获取单个数据源的完整信息，包括 `payload` 配置及其中配置的连接与鉴权信息；请将该响应视为敏感信息，避免记录或转发。 支持诊断类型 redis_node、redis_sentinel、mongodb_mongod、mongodb_mongos 和 kafka；enabled 与 alerting_enabled 相互独立。",
+        "description": "按 ID 返回单个数据源，包含完整的 `payload` 配置。",
         "tags": [
           "Monitors/告警数据源"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **数据源查看**（`monit`） |\n\n完整支持类型与凭据行为见请求/响应 Schema。仅诊断类型不能启用告警。创建时省略 enabled 默认为 true，更新时省略保留当前值；enabled 或 alerting_enabled 的显式 null 非法。诊断密码及 Kafka 私钥在响应中省略，环境变量引用除外；更新时省略秘密字段保留原值，空字符串清除。其他数据源凭据可能返回，应作为敏感数据处理。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **数据源查看**（`monit`） |\n\n## 使用说明\n\n- 需要该数据源的管理权限（见 `manage_team_id`）；只有查询权限的成员返回 `AccessDenied`。需要查看自己可查询的数据源时请使用 `/monit/datasource/list`。\n- 响应属于敏感信息：`payload` 包含连接配置，非诊断类型的凭据会原样返回；诊断类型的密码和 Kafka 私钥仅在是 `${env:NAME}` 引用时才返回；`tencent_cls` 的 `secret_key` 返回空字符串，除非它是 `${env:NAME}` 引用。\n- ID 不存在或属于其他账户时返回 `ResourceNotFound`。",
           "href": "/zh/api-reference/monitors/data-sources/monit-datasource-read-info",
           "metadata": {
             "sidebarTitle": "查看数据源详情"
@@ -821,7 +886,10 @@
                     },
                     "edge_cluster_name": "default",
                     "updated_at": 1712000000,
-                    "alerting_enabled": true
+                    "alerting_enabled": true,
+                    "manage_team_id": null,
+                    "readonly_team_ids": null,
+                    "creator_id": 20001
                   }
                 }
               }
@@ -833,6 +901,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -864,7 +935,7 @@
           "Monitors/告警规则"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **告警规则查看**（`monit`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 任意有效 `app_key` 均可调用 |\n\n## 使用说明\n\n- 记录按时间倒序排列，不含 `content`；如需查看快照，请调用 `POST /monit/rule/audit/detail`。\n- 每次创建、整体更新、字段批量更新和移动都会写入一条记录。删除规则不会写入记录，且规则删除后无法再列出其历史，调用返回 `InvalidParameter`（`alert rule not found`）。\n- 调用者须对规则所在文件夹有管理权限（账户所有者或管理员、该文件夹或其上级文件夹的创建者，或绑定到该文件夹或其上级文件夹的团队成员），否则返回 `AccessDenied`。",
           "href": "/zh/api-reference/monitors/alert-rules/monit-rule-read-audits",
           "metadata": {
             "sidebarTitle": "查询规则变更历史"
@@ -895,11 +966,20 @@
                   "data": [
                     {
                       "id": 9001,
-                      "account_id": 10023,
+                      "account_id": 888,
                       "alert_rule_id": 50001,
                       "action": "update",
-                      "creator_id": 80011,
-                      "creator_name": "Alice",
+                      "creator_id": 66,
+                      "creator_name": "zhangsan",
+                      "created_at": 1712003600
+                    },
+                    {
+                      "id": 8990,
+                      "account_id": 888,
+                      "alert_rule_id": 50001,
+                      "action": "create",
+                      "creator_id": 66,
+                      "creator_name": "zhangsan",
                       "created_at": 1712000000
                     }
                   ]
@@ -913,6 +993,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -944,7 +1027,7 @@
           "Monitors/告警规则"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **告警规则管理**（`monit`） |\n\n## 使用说明\n\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **告警规则管理**（`monit`） |\n\n## 使用说明\n\n- 删除规则时会同时清理该规则的活跃告警。\n- 删除不存在的 ID 也会成功并返回空 `data`，因此可以安全重试。\n- 调用者须对规则所在文件夹有管理权限（账户所有者或管理员、该文件夹或其上级文件夹的创建者，或绑定到该文件夹或其上级文件夹的团队成员），否则返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/monitors/alert-rules/monit-rule-write-delete",
           "metadata": {
             "sidebarTitle": "删除告警规则"
@@ -983,6 +1066,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -1009,12 +1095,12 @@
       "post": {
         "operationId": "monit-rule-read-list",
         "summary": "查询告警规则列表",
-        "description": "返回指定文件夹下所有告警规则的基础信息。如需完整规则详情，请调用 `POST /monit/rule/v2/info`。",
+        "description": "返回指定文件夹下告警规则的基础信息；如需完整配置，请调用 `POST /monit/rule/v2/info`。",
         "tags": [
           "Monitors/告警规则"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **告警规则查看**（`monit`） |\n\n## 使用说明\n\n- 将 `folder_id` 设为 `0` 可列出当前用户有权查看的所有文件夹下的规则。\n- `triggered` 字段表示该规则当前是否有活跃告警。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **告警规则查看**或**告警规则管理**（`monit`） |\n\n## 使用说明\n\n- `folder_id` 必须是已存在的文件夹：传 `0` 或不存在的 ID 返回 `InvalidParameter`；调用者对该文件夹无管理权限（账户所有者或管理员、该文件夹或其上级文件夹的创建者，或绑定到该文件夹或其上级文件夹的团队成员）时返回 `AccessDenied`。不支持跨文件夹列出整个账户的规则。\n- 默认只返回直接位于该文件夹下的规则，按名称排序，并填充 `active_alert_count` 与 `runtime_state`。\n- `include_descendants` 为 `true` 时会搜索该文件夹及其所有子孙文件夹，按名称排序最多返回 `limit` 条；此时只填充 `id`、`folder_id`、`name`，其余字段为零值（`labels` 为 `null`，不返回 `runtime_state`）。\n- 当且仅当 `active_alert_count > 0` 时 `triggered` 为 `true`。",
           "href": "/zh/api-reference/monitors/alert-rules/monit-rule-read-list",
           "metadata": {
             "sidebarTitle": "查询告警规则列表"
@@ -1045,12 +1131,25 @@
                   "data": [
                     {
                       "id": 50001,
+                      "account_id": 888,
                       "folder_id": 100,
                       "name": "CPU High",
+                      "labels": {
+                        "team": "sre"
+                      },
                       "ds_type": "prometheus",
                       "enabled": true,
-                      "triggered": true,
+                      "debug_log_enabled": false,
+                      "cron_pattern": "0 * * * * *",
+                      "timezone": "Asia/Shanghai",
+                      "delay_seconds": 0,
+                      "creator_id": 66,
+                      "creator_name": "zhangsan",
+                      "updater_id": 66,
+                      "updater_name": "zhangsan",
                       "created_at": 1710000000,
+                      "updated_at": 1712000000,
+                      "triggered": true,
                       "active_alert_count": 2,
                       "runtime_state": "normal"
                     }
@@ -1065,6 +1164,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -1091,12 +1193,12 @@
       "post": {
         "operationId": "monit-datasource-read-list",
         "summary": "查询数据源列表",
-        "description": "返回当前账户下的所有数据源，可通过 `type_ident` 过滤类型。 支持诊断类型 redis_node、redis_sentinel、mongodb_mongod、mongodb_mongos 和 kafka；enabled 与 alerting_enabled 相互独立。",
+        "description": "列出账户下调用方有权查询的数据源，可按类型或名称精确过滤。",
         "tags": [
           "Monitors/告警数据源"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **数据源查看**（`monit`） |\n\n## 使用说明\n\n- 省略 `type_ident` 可返回所有类型的数据源。\n- 列表响应中不返回敏感凭证字段（密码、密钥）。\n\n完整支持类型与凭据行为见请求/响应 Schema。仅诊断类型不能启用告警。创建时省略 enabled 默认为 true，更新时省略保留当前值；enabled 或 alerting_enabled 的显式 null 非法。诊断密码及 Kafka 私钥在响应中省略，环境变量引用除外；更新时省略秘密字段保留原值，空字符串清除。其他数据源凭据可能返回，应作为敏感数据处理。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **数据源查看**（`monit`） |\n\n## 使用说明\n\n- 省略 `type` 和 `name` 时返回你有权查询的所有数据源；`type`、`name` 均为精确匹配。无法识别的 `type` 返回空数组。结果不分页。\n- 只返回调用方有权查询的数据源（见 `readonly_team_ids`）；每项带有 `my_perm`（`manage` 或 `readonly`）。\n- 列表项中的 `payload` 恒为 `null`。如需读取自己可管理的数据源的配置，请使用 `/monit/datasource/info`。",
           "href": "/zh/api-reference/monitors/data-sources/monit-datasource-read-list",
           "metadata": {
             "sidebarTitle": "查询数据源列表"
@@ -1133,10 +1235,14 @@
                       "enabled": true,
                       "note": "Production Prometheus",
                       "address": "http://prometheus.example.com:9090",
+                      "payload": null,
                       "edge_cluster_name": "default",
                       "updated_at": 1712000000,
-                      "payload": null,
-                      "alerting_enabled": true
+                      "alerting_enabled": true,
+                      "manage_team_id": null,
+                      "readonly_team_ids": null,
+                      "creator_id": 20001,
+                      "my_perm": "manage"
                     }
                   ]
                 }
@@ -1149,6 +1255,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -1175,12 +1284,12 @@
       "post": {
         "operationId": "monit-rule-write-fields-update",
         "summary": "批量更新规则字段",
-        "description": "一次性更新多条告警规则的特定字段，仅应用 `fields` 列表中指定的字段。",
+        "description": "在一次调用中为多条告警规则更新 `fields` 中列出的字段。",
         "tags": [
           "Monitors/告警规则"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **告警规则管理**（`monit`） |\n\n## 使用说明\n\n- 在 `fields` 数组中指定要更新的字段名，如 `[\"enabled\", \"channel_ids\"]`。\n- 仅更新指定字段，其他字段保持不变。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **告警规则管理**（`monit`） |\n\n## 使用说明\n\n- 每个列出的字段取同名请求字段的值；列出但未传值的字段会被设为零值（例如 `fields` 包含 `labels` 却既不传 `labels` 也不传 `labels_patch`，会清空全部标签）。未列出的字段保持原值。\n- `fields` 中出现未知字段名、传入 `labels_patch` / `annotations_patch` 但 `fields` 未包含对应字段，或同时传入 `labels` 与 `labels_patch`（`annotations` 与 `annotations_patch` 同理）时，整个调用返回 `InvalidParameter`。\n- 规则逐条更新，结果为每个 ID 返回一项：成功时 `message` 为空，否则为该规则的错误信息（校验失败、对其所在文件夹无权限，或 ID 不存在，此时 `name` 为 `id: <id>`）。\n- 将 `enabled` 设为 `false` 会清理这些规则的活跃告警。除非本次调用只是停用规则（`fields` 恰好为 `[\"enabled\"]` 且 `enabled: false`），否则账户规则数超出告警规则 License 上限时返回 `AccessDenied`，且非管理员调用者须对每条规则选中的所有数据源具备只读权限。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/monitors/alert-rules/monit-rule-write-fields-update",
           "metadata": {
             "sidebarTitle": "批量更新规则字段"
@@ -1228,6 +1337,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -1261,12 +1373,12 @@
       "post": {
         "operationId": "monit-rule-read-counter-channel",
         "summary": "按协作空间查询规则统计",
-        "description": "返回一个对象，key 为协作空间名称，value 为将告警路由到该协作空间的规则数量。若协作空间名称无法解析，则以协作空间 ID（字符串形式）作为 key。",
+        "description": "按协作空间名称返回将告警路由到各协作空间的告警规则数量。",
         "tags": [
           "Monitors/告警规则"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **告警规则查看**（`monit`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **概览查看**（`monit`） |\n\n## 使用说明\n\n- 仅统计 `channel_ids` 非空的规则；一条规则路由到多个协作空间时，会在每个协作空间下各计一次。\n- 协作空间 ID 无法解析为名称时，以该 ID 的字符串形式作为 key；同名的协作空间会合并到同一个 key。\n- 没有任何规则路由到协作空间时返回空对象 `{}`。",
           "href": "/zh/api-reference/monitors/alert-rules/monit-rule-read-counter-channel",
           "metadata": {
             "sidebarTitle": "按协作空间查询规则统计"
@@ -1307,6 +1419,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -1336,7 +1451,7 @@
           "Monitors/告警规则"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **告警规则查看**（`monit`） |\n\n## 使用说明\n\n- `id` 必填且不能为 `0`，否则返回 `InvalidParameter`。\n- 规则不存在时返回 `InvalidParameter`（`alert rule not found`）。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **告警规则查看**或**告警规则管理**（`monit`） |\n\n## 使用说明\n\n- `id` 必填且不能为 `0`，否则返回 `InvalidParameter`。\n- 规则不存在或属于其他账户时返回 `InvalidParameter`（`alert rule not found`）。\n- 不做文件夹级权限校验：具备上述权限的调用者可读取账户内的任意规则。",
           "href": "/zh/api-reference/monitors/alert-rules/monit-rule-read-info-v2",
           "metadata": {
             "sidebarTitle": "获取告警规则详情 V2"
@@ -1378,6 +1493,7 @@
                     "enabled": true,
                     "debug_log_enabled": false,
                     "rule_configs": {
+                      "relate_queries": [],
                       "queries": [
                         {
                           "name": "A",
@@ -1438,6 +1554,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -1469,7 +1588,7 @@
           "Monitors/告警规则"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **告警规则管理**（`monit`） |\n\n## 使用说明\n\n- `name`、`ds_type`、`enabled`、`cron_pattern` 和 `rule_configs.queries` 为必填项；`ds_list`（支持通配符）或 `ds_ids` 必须有一个非空。\n- `enabled` 必须显式传入（包括 `false`），缺失时返回 `InvalidParameter`。\n- `id`、`account_id`、`creator_*`、`updater_*`、`created_at`、`updated_at` 由服务端赋值，客户端传入将被忽略。\n- `name` 在 `folder_id` 内必须唯一；重名会返回 `InvalidParameter`。\n- `channel_ids` 可为空，告警将通过全局集成路由。\n- 请求体容忍额外的未知字段（向前兼容），未知字段会被忽略。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **告警规则管理**（`monit`） |\n\n## 使用说明\n\n- `folder_id`、`name`、`ds_type`、`enabled`、`cron_pattern` 和 `rule_configs.queries` 为必填项；`ds_list`（支持通配符）与 `ds_ids` 至少一个非空。\n- `enabled` 必须显式传入（包括 `false`），缺失时返回 `InvalidParameter`。\n- `folder_id` 必须是已存在的文件夹（否则返回 `InvalidParameter`），且调用者须对该文件夹有管理权限（账户所有者或管理员、该文件夹或其上级文件夹的创建者，或绑定到该文件夹或其上级文件夹的团队成员）（否则返回 `AccessDenied`）。\n- `name` 在 `folder_id` 内必须唯一；重名会返回 `InvalidParameter`。\n- `enabled` 为 `true` 时，`ds_type` 必须是支持告警的数据源类型，且 `ds_ids` 中的每个 ID 都必须是已启用并开启告警的数据源，否则返回 `InvalidParameter`。\n- 账户所有者和管理员以外的调用者，须对 `ds_ids` 中列出的、以及 `ds_list` 当前匹配到的每个数据源具备只读权限，否则返回 `AccessDenied`（`no permission to reference datasource \"<name>\"`）。\n- 创建后若超出账户的告警规则 License 上限，调用返回 `AccessDenied`。\n- `id`、`account_id`、`creator_*`、`updater_*`、`created_at`、`updated_at` 由服务端赋值，客户端传入将被忽略。\n- `channel_ids` 可为空，告警将通过全局集成路由。\n- 请求体不得超过 1 MiB，超出时返回 HTTP 413（`EntityTooLarge`）。请求体中额外的未知字段会被忽略（向前兼容）。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/monitors/alert-rules/monit-rule-write-create-v2",
           "metadata": {
             "sidebarTitle": "创建告警规则 V2"
@@ -1511,6 +1630,7 @@
                     "enabled": true,
                     "debug_log_enabled": false,
                     "rule_configs": {
+                      "relate_queries": [],
                       "queries": [
                         {
                           "name": "A",
@@ -1571,6 +1691,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -1629,7 +1752,7 @@
           "Monitors/告警规则"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **告警规则管理**（`monit`） |\n\n## 使用说明\n\n- `id` 必填且对应规则必须已存在，否则返回 `InvalidParameter`。\n- 本接口为全量字段替换语义：除下列例外外，未传入的字段按零值保存，建议先调用 `/monit/rule/v2/info` 获取完整配置后再修改。\n- `enabled` 必须显式传入（包括 `false`），缺失时返回 `InvalidParameter`；更新为 `false` 时服务端会清理该规则的活跃告警。\n- `investigation_targets` 为例外：省略时保留原配置，传 `[]` 清空，传值则整体替换。\n- `folder_id` 不可通过本接口修改，调整文件夹请使用 `/monit/rule/move`。\n- `account_id`、`creator_*`、`updater_*`、`created_at`、`updated_at` 由服务端维护，传入将被忽略。\n- `name` 在 `folder_id` 内必须唯一；重名会返回 `InvalidParameter`。\n- 请求体容忍额外的未知字段（向前兼容），未知字段会被忽略。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **告警规则管理**（`monit`） |\n\n## 使用说明\n\n- `id` 必填且对应规则必须已存在，否则返回 `InvalidParameter`。\n- 本接口为全量字段替换语义：除下列例外外，未传入的字段按零值保存（随后按默认规则归一，例如 `repeat_interval` 变为 3600），建议先调用 `/monit/rule/v2/info` 获取完整配置后再修改。\n- `enabled` 必须显式传入（包括 `false`），缺失时返回 `InvalidParameter`；更新为 `false` 时服务端会清理该规则的活跃告警。\n- `investigation_targets` 为例外：省略时保留原配置，传 `[]` 清空，传值则整体替换。\n- `folder_id` 不可通过本接口修改，调整文件夹请使用 `/monit/rule/move`。\n- 调用者须对规则所在文件夹有管理权限（账户所有者或管理员、该文件夹或其上级文件夹的创建者，或绑定到该文件夹或其上级文件夹的团队成员），否则返回 `AccessDenied`。\n- `name` 在规则所在文件夹内必须唯一；重名会返回 `InvalidParameter`。\n- `enabled` 为 `true` 时，`ds_type` 必须是支持告警的数据源类型，且 `ds_ids` 中的每个 ID 都必须是已启用并开启告警的数据源，否则返回 `InvalidParameter`。\n- 账户所有者和管理员以外的调用者，须对 `ds_ids` 中列出的、以及 `ds_list` 当前匹配到的每个数据源具备只读权限，否则返回 `AccessDenied`（`no permission to reference datasource \"<name>\"`）。\n- 账户规则数已超出告警规则 License 上限时，调用返回 `AccessDenied`。\n- 处理期间规则被其他请求修改时，返回 HTTP 409（`UndonedOrderExist`，`alert rule was modified; reload and retry`），请重新获取规则后重试。\n- `account_id`、`creator_*`、`updater_*`、`created_at`、`updated_at` 由服务端维护，传入将被忽略。\n- 请求体不得超过 1 MiB，超出时返回 HTTP 413（`EntityTooLarge`）。请求体中额外的未知字段会被忽略（向前兼容）。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/monitors/alert-rules/monit-rule-write-update-v2",
           "metadata": {
             "sidebarTitle": "更新告警规则 V2"
@@ -1671,6 +1794,7 @@
                     "enabled": true,
                     "debug_log_enabled": false,
                     "rule_configs": {
+                      "relate_queries": [],
                       "queries": [
                         {
                           "name": "A",
@@ -1731,6 +1855,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -1785,12 +1912,12 @@
       "post": {
         "operationId": "monit-read-query-data",
         "summary": "查询结构化数据",
-        "description": "对已配置的数据源执行同步即席查询，并返回稳定的 `query_result.v1` 结果；结果会按自然语义呈现为 frames、records 或 samples。此公开接口要求 monit-edge v0.65.0 或更高版本。",
+        "description": "对数据源执行同步即席查询，返回 `query_result.v1` 结果，形态为 frames、records 或 samples。",
         "tags": [
           "Monitors/诊断分析"
         ],
         "x-mint": {
-          "content": "## 调用限制\n\n| 项 | 值 |\n| ------ | ----- |\n| 速率限制 | 每账户 **100 次/分钟**、**5 次/秒** |\n| 权限 | 任意有效的 `app_key`（只读，不受特定权限分类限制） |\n| Edge 版本要求 | 受支持的部署要求 **monit-edge v0.65.0 或更高版本** |\n\n## 使用说明\n\n- 此公开接口以 **monit-edge v0.65.0** 为最低受支持版本。迁移期间，WebAPI 仍保留旧版 Edge 适配器：query.v2 结果仍可能保留 frames、records 或 samples，而 legacy rows 只能提供其已保留的信息。这些适配器不会改变最低支持版本；旧协议缺少 query.v3 的取消和错误生命周期语义，legacy rows 已丢失的数据也无法恢复。\n- 公开响应格式固定为 `query_result.v1`，与 Edge 内部查询协议版本无关。必须根据 `result.kind`（`frames`、`records` 或 `samples`）分发结果，不要根据 `ds_type` 或 Edge 版本猜测结果形态。\n- `frames` 结果可以包含多个表格或时序 Frame。字段值按列组织，同一 Frame 中所有字段的值数量一致。\n- `records` 结果可以包含嵌套 JSON 和 null record。超出 JavaScript 安全整数范围的整数字面量会以十进制字符串返回。\n- `samples` 结果包含标签集合和瞬时值。值可以是数字，也可以是字符串 `NaN`、`+Inf` 或 `-Inf`。\n- 最终成功响应上限为 8 MiB，查询结果上限为 1,000 行。超限时请缩短时间范围、减少字段或在数据源侧聚合。\n- 查询失败使用非 2xx HTTP 状态码和标准错误 envelope。不要透明回退到已弃用的 `/monit/query/rows` 接口。\n- WebAPI 跨实例转发和 Edge 执行合计可能耗时 35 秒。客户端超时建议至少设为 40 秒，并在调用方放弃查询时向下传播取消信号。",
+          "content": "## 调用限制\n\n| 项 | 值 |\n| ------ | ----- |\n| 速率限制 | 每账户 **100 次/分钟**、**5 次/秒** |\n| 权限 | 任意有效的 `app_key`（只读，不受特定权限分类限制） |\n| Edge 版本要求 | 受支持的部署要求 **monit-edge v0.65.0 或更高版本** |\n\n## 使用说明\n\n- 数据源由 `ds_type` 加 `ds_name` 指定，而不是数据源 ID。数据源必须属于当前账户且已启用。若数据源限制了可查询的团队，只有这些团队的成员、其管理团队以及账户所有者或管理员可以查询，其他人会收到 `AccessDenied`。\n- 此公开接口以 **monit-edge v0.65.0** 为最低受支持版本。迁移期间，WebAPI 仍保留旧版 Edge 适配器：query.v2 结果仍可能保留 frames、records 或 samples，而 legacy rows 只能提供其已保留的信息。这些适配器不会改变最低支持版本；旧协议缺少 query.v3 的取消和错误生命周期语义，legacy rows 已丢失的数据也无法恢复。\n- 公开响应格式固定为 `query_result.v1`，与 Edge 内部查询协议版本无关。必须根据 `result.kind`（`frames`、`records` 或 `samples`）分发结果，不要根据 `ds_type` 或 Edge 版本猜测结果形态。\n- `frames` 结果可以包含多个表格或时序 Frame。字段值按列组织，同一 Frame 中所有字段的值数量一致。\n- `records` 结果可以包含嵌套 JSON 和 null record。超出 JavaScript 安全整数范围的整数字面量会以十进制字符串返回。\n- `samples` 结果包含标签集合和瞬时值。值可以是数字，也可以是字符串 `NaN`、`+Inf` 或 `-Inf`。\n- Prometheus 表达式在下发查询前会做语法检查，表达式非法时返回 HTTP 400。\n- 请求体上限为 256 KiB，完整成功响应上限为 10 MiB，超限均返回 HTTP 413。结果超过 1,000 行时返回 HTTP 400。请缩短时间范围、减少字段或在数据源侧聚合。\n- 查询失败使用非 2xx HTTP 状态码和标准错误 envelope。\n- WebAPI 跨实例转发和 Edge 执行合计可能耗时 35 秒。客户端超时建议至少设为 40 秒，并在调用方放弃查询时向下传播取消信号。",
           "href": "/zh/api-reference/monitors/diagnostics/monit-read-query-data",
           "metadata": {
             "sidebarTitle": "查询结构化数据"
@@ -1987,7 +2114,7 @@
                               {
                                 "labels": {
                                   "__name__": "up",
-                                  "instance": "10.101.214.50:7070"
+                                  "instance": "203.0.113.10:9090"
                                 },
                                 "value": 1
                               }
@@ -2111,7 +2238,7 @@
           "Monitors/告警数据源"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **2,000 次/分钟**；**32 次/秒** |\n| 权限要求 | **数据源查看**（`monit`） |\n\n通过 `/monit/datasource/list` 获取数据源 ID。停用数据源返回 `datasource_disabled`，`alerting_enabled=false` 不阻断工具。错误使用非 2xx HTTP 状态和 `error.code`、`error.message`、`error.reason`。`tool_not_supported` 表示选中的执行端未提供该工具，不表示厂商权限不足。禁止自动切换 Edge 或回退旧 diagnose 重试。\n\n## 使用说明\n\n- 本入口共用两类工具：由执行端 Edge 定义的诊断工具（如 `mysql.overview`、`prometheus.metric_trends`）和命名为 `<type>.query` 的查询工具。工具前缀必须与数据源类型一致。\n- 查询工具要求 Edge 集群支持 Explore 查询（协议里程碑 v0.68.0）；诊断工具要求 v0.71.0 基础 invoke 协议。不支持的集群返回 `edge_upgrade_required`、`mixed_edge_versions` 或 `edge_version_unknown`；禁止自动回退 `/monit/query/data` 或其他接口。\n- 查询工具的 `params` 遵循 `tool` 字段描述中按数据源列出的专属 Schema。`expr` 和 `execution` 必填。`limit`/`direction` 只约束原始日志条数与检索方向，不代表 SQL 行数或扫描量。未知扩展字段被容忍，但不参与执行也不透传。\n- 查询结果的 `data` 是完整 Explore 结果：`format` 为 `explore_result.v1`，`result.kind` 为 `samples`、`frames` 或 `logs`；日志结果保留 `applied_limit` 和 `has_more`。查询结果不合成 `summary` 或 `truncated`。\n- 请求体上限 128 KiB；两类工具的完整成功响应上限均为 10 MiB；诊断工具超时最多 25 秒。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **2,000 次/分钟**；**32 次/秒** |\n| 权限要求 | **数据源查看**（`monit`） |\n\n通过 `/monit/datasource/list` 获取数据源 ID。停用数据源返回 `datasource_disabled`，`alerting_enabled=false` 不阻断工具。错误使用非 2xx HTTP 状态和 `error.code`、`error.message`、`error.reason`。`tool_not_supported` 表示选中的执行端未提供该工具，不表示厂商权限不足。禁止自动切换 Edge 或回退旧 diagnose 重试。\n\n## 使用说明\n\n- 调用方需要拥有该数据源的查询权限（见数据源的 `readonly_team_ids`），否则返回 403 `access_denied`；其他账户的数据源返回 404 `datasource_not_found`。\n- 诊断工具仅支持数据源类型 `mysql`、`postgres`、`redis_node`、`redis_sentinel`、`mongodb_mongod`、`mongodb_mongos`、`kafka`、`elasticsearch`、`prometheus`、`loki` 和 `victorialogs`；`oracle`、`clickhouse`、`sls`、`tencent_cls` 只支持各自的 `<type>.query` 工具。其他组合返回 `invalid_request`。\n- 本入口共用两类工具：由执行端 Edge 定义的诊断工具（如 `mysql.overview`、`prometheus.metric_trends`）和命名为 `<type>.query` 的查询工具。工具前缀必须与数据源类型一致。\n- 查询工具要求 Edge 集群支持 Explore 查询（协议里程碑 v0.68.0）；诊断工具要求 v0.71.0 基础 invoke 协议。不支持的集群返回 `edge_upgrade_required`、`mixed_edge_versions` 或 `edge_version_unknown`；禁止自动回退 `/monit/query/data` 或其他接口。\n- 查询工具的 `params` 遵循 `tool` 字段描述中按数据源列出的专属 Schema。`expr` 和 `execution` 必填。`limit`/`direction` 只约束原始日志条数与检索方向，不代表 SQL 行数或扫描量。未知扩展字段被容忍，但不参与执行也不透传。\n- 查询结果的 `data` 是完整 Explore 结果：`format` 为 `explore_result.v1`，`result.kind` 为 `samples`、`frames` 或 `logs`；日志结果保留 `applied_limit` 和 `has_more`。查询结果不合成 `summary` 或 `truncated`。\n- 请求体上限 128 KiB；两类工具的完整成功响应上限均为 10 MiB；诊断工具超时最多 25 秒。",
           "href": "/zh/api-reference/monitors/data-sources/monit-datasource-tools-invoke",
           "metadata": {
             "sidebarTitle": "调用数据源工具"
@@ -2208,7 +2335,7 @@
             }
           },
           "400": {
-            "description": "标准 HTTP 错误；error.reason：invalid_request。",
+            "description": "标准 HTTP 错误。参数格式错误或超出范围、数据源已禁用、数据源类型不受支持或数据源未绑定 Edge 集群时，`error.reason` 为 `invalid_request`。数据源 ID 不存在时返回错误码 `ResourceNotFound`，且不带 `reason`。",
             "content": {
               "application/json": {
                 "schema": {
@@ -2221,17 +2348,7 @@
             "$ref": "#/components/responses/Unauthorized"
           },
           "403": {
-            "description": "标准 HTTP 错误；error.reason：access_denied。",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/ErrorResponse"
-                }
-              }
-            }
-          },
-          "404": {
-            "description": "标准 HTTP 错误；error.reason：datasource_not_found。",
+            "description": "调用方无权查询该数据源。`error.code` 为 `AccessDenied`，不带 `error.reason`。",
             "content": {
               "application/json": {
                 "schema": {
@@ -2241,7 +2358,7 @@
             }
           },
           "413": {
-            "description": "标准 HTTP 错误；error.reason：source_too_large、result_too_large。",
+            "description": "标准 HTTP 错误。`error.reason`：`too_many_rows`、`source_too_large` 或 `result_too_large`。请求体超过 256 KiB 时同样返回 413，不带 `reason`。",
             "content": {
               "application/json": {
                 "schema": {
@@ -2281,7 +2398,7 @@
             }
           },
           "503": {
-            "description": "标准 HTTP 错误；error.reason：no_active_edge、edge_upgrade_required、mixed_edge_versions、edge_unavailable。",
+            "description": "标准 HTTP 错误。`error.reason`：`no_active_edge`、`edge_version_unknown`、`edge_upgrade_required`、`mixed_edge_versions` 或 `edge_unavailable`。",
             "content": {
               "application/json": {
                 "schema": {
@@ -2306,7 +2423,7 @@
           "Monitors/诊断分析"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **100 次/分钟**；**16 次/秒** |\n| 权限要求 | **数据源查看**（`monit`） |\n| Edge 版本要求 | 受支持的部署要求 **monit-edge v0.68.0 或更高版本** |\n\n## 使用说明\n\n- 需要数据源原生结果形态时使用本接口；`/monit/query/data` 返回稳定的 `query_result.v1` 契约。本接口根据 `data.result.kind`（`frames`、`samples` 或 `logs`）分发结果。\n- `execution.kind` 决定可接受的配套字段：`instant` 只需 `to_ms`，`range` 需要 `from_ms`、`to_ms` 和 `max_data_points`，`window` 需要 `from_ms` 和 `to_ms`。不接受 `step_seconds`，步长由 `max_data_points` 与 `min_step_seconds` 推导。\n- `args` 用于宏替换（例如 Grafana 风格变量），取值均为字符串。\n- `logs` 结果最多返回 1,000 条，并通过 `applied_limit` 与 `has_more` 说明截断情况。时序与采样结果各最多 1,000 条，成功响应整体上限 8 MiB。\n- WebAPI 跨实例转发与 Edge 执行合计可能耗时 35 秒，客户端超时建议至少 40 秒。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **100 次/分钟**；**16 次/秒** |\n| 权限要求 | **数据源查看**（`monit`） |\n| Edge 版本要求 | 受支持的部署要求 **monit-edge v0.68.0 或更高版本** |\n\n## 使用说明\n\n- 需要数据源原生结果形态时使用本接口；`/monit/query/data` 返回稳定的 `query_result.v1` 契约。本接口根据 `data.result.kind`（`frames`、`samples` 或 `logs`）分发结果。\n- 数据源由 `datasource_id` 指定。数据源必须属于当前账户、已启用、已绑定 Edge 集群，且类型为 `prometheus`、`elasticsearch`、`loki`、`clickhouse`、`mysql`、`oracle`、`postgres`、`sls`、`victorialogs` 或 `tencent_cls` 之一。若数据源限制了可查询的团队，只有这些团队的成员、其管理团队以及账户所有者或管理员可以查询。\n- `execution.kind` 决定可接受的配套字段：`instant` 需要 `to_ms`（`from_ms` 可选），`range` 需要 `from_ms`、`to_ms` 和 `max_data_points`，`window` 需要 `from_ms` 和 `to_ms`。同时给出两个时间时，`from_ms` 必须小于 `to_ms`。不接受 `step_seconds`，步长由 `max_data_points` 与 `min_step_seconds` 推导。\n- `args` 为必填（无参数时传 `{}`），用于宏替换（例如 Grafana 风格变量），取值均为字符串。未知或重复的 JSON 键会被拒绝。\n- `logs` 结果最多返回 1,000 条（`sls` 为 100 条），并通过 `applied_limit` 与 `has_more` 说明截断情况。`frames` 结果最多 1,000 个 frame，表格行合计最多 1,000 行，值合计最多 100,000 个；`samples` 结果最多 1,000 条。请求体上限 256 KiB，成功响应整体上限 10 MiB。\n- 失败使用标准错误 envelope。`error.reason` 是稳定的机器可读取值；数据源 ID 不存在时返回 HTTP 400，错误码为 `ResourceNotFound`，且不带 `reason`。\n- WebAPI 跨实例转发与 Edge 执行合计可能耗时 35 秒，客户端超时建议至少 40 秒。",
           "href": "/zh/api-reference/monitors/diagnostics/monit-read-query-explore",
           "metadata": {
             "sidebarTitle": "执行探索查询"
@@ -2331,11 +2448,11 @@
           {
             "name": "X-DSID",
             "in": "header",
-            "required": true,
+            "required": false,
             "schema": {
               "type": "string"
             },
-            "description": "要查询的数据源 ID，必须是当前账户下 Prometheus 兼容类型的数据源。"
+            "description": "要查询的数据源 ID，十进制字符串。必须是当前账户下的 Prometheus 类型数据源。省略时由平台自有的 Prometheus 响应，而不是您的数据源。"
           }
         ],
         "responses": {
@@ -2358,7 +2475,7 @@
             }
           },
           "400": {
-            "description": "`X-DSID` 请求头缺失或非法、数据源不存在，或该数据源不是 Prometheus 类型。以 `text/plain` 返回。",
+            "description": "`X-DSID` 请求头不是数字、数据源不是 Prometheus 类型，或数据源所在集群没有已注册的 monit-edge。以 `text/plain` 返回。",
             "content": {
               "text/plain": {
                 "schema": {
@@ -2370,18 +2487,14 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
-          "500": {
-            "description": "数据源查询或代理请求失败。以 `text/plain` 返回。",
-            "content": {
-              "text/plain": {
-                "schema": {
-                  "type": "string"
-                }
-              }
-            }
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
           },
-          "503": {
-            "description": "数据源所在集群中没有支持数据源资源代理的 monit-edge。以 `text/plain` 返回，请升级 monit-edge。",
+          "429": {
+            "$ref": "#/components/responses/TooManyRequests"
+          },
+          "500": {
+            "description": "数据源不存在或属于其他账户（消息为 `data source not found`），或数据源查询、代理请求失败。以 `text/plain` 返回。",
             "content": {
               "text/plain": {
                 "schema": {
@@ -2396,7 +2509,7 @@
           "Monitors/告警数据源"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 任意有效的 `app_key`（只读，不受特定权限分类限制） |\n| Edge 版本要求 | 受支持的部署要求 **monit-edge v0.35.0 或更高版本** |\n\n## 使用说明\n\n- 通过 `X-DSID` 请求头指定目标数据源，必须是当前账户下 Prometheus 兼容类型的数据源；可用 `/monit/datasource/list` 获取 ID。\n- 200 响应体是数据源原生的 Prometheus HTTP API 结构，**不是**统一的 `{ request_id, data }` envelope。未到达数据源前发生的失败以 `text/plain` 返回，并携带对应的 4xx/5xx 状态码。\n- 省略 `X-DSID` 时会回退到平台自有的 Prometheus 代理；需要查询指定数据源时必须携带该请求头。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 任意有效的 `app_key`（只读，不受特定权限分类限制） |\n| Edge 版本要求 | 查询指定数据源要求 **monit-edge v0.35.0 或更高版本** |\n\n## 使用说明\n\n- 通过 `X-DSID` 请求头传入目标数据源 ID。数据源必须属于当前账户且为 Prometheus 类型；可用 `/monit/datasource/list` 获取 ID。\n- 200 响应体是数据源原生的 Prometheus HTTP API 结构，**不是**统一的 `{ request_id, data }` envelope。查询字符串参数会原样转发，因此 Prometheus 自身的 `match[]`、`start`、`end` 等参数都可使用。\n- 省略 `X-DSID`，或数据源所在集群中有任意 monit-edge 低于 v0.35.0 时，请求会由平台自有的 Prometheus 响应，而不是您的数据源。请携带该请求头并保持 monit-edge 为较新版本，才能获得数据源自身的取值。\n- 到达数据源之前发生的失败以 `text/plain` 返回，并携带对应的 4xx/5xx 状态码。数据源自身返回的 400 及以上状态码会连同其响应体一并透传。",
           "href": "/zh/api-reference/monitors/data-sources/monit-prometheus-read-label-values",
           "metadata": {
             "sidebarTitle": "查询 Prometheus 标签值列表"
@@ -2413,7 +2526,7 @@
           "Monitors/仪表盘"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | **300 requests/minute**; **20 requests/second** per account |\n| 权限要求 | **仪表盘管理**（`monit`） |\n\n## 使用说明\n\n- `dashboard_id` 由调用方提供，因此超时后重试会以 `DashboardIDConflict` 失败，而不会创建第二个仪表盘。\n- `definition` 上限 1 MiB，请求体上限 2 MiB。\n- 会记录审计日志。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **仪表盘管理**（`monit`） |\n\n## 使用说明\n\n- `dashboard_id` 由调用方生成（小写的 canonical UUIDv7）。超时后用同一 ID 重试会以 `DashboardIDConflict`（HTTP 409）失败，而不会创建第二个仪表盘。\n- `folder_id` 必须是`app_key` 所属成员可访问的目录：其本人创建或归属其所在团队的目录及这些目录的全部子目录；账户所有者与管理员可访问全部目录之一，否则以 `FolderNotFound`（HTTP 404）失败。\n- 新仪表盘的 `revision` 从 1 开始；下次更新、移动或删除时把它作为 `expected_revision` 传入。\n- `definition` 不合法时返回 `InvalidParameter`（HTTP 400），错误信息按 `<JSON 指针>: <原因>` 逐条列出违规项。定义超过 1 MiB 或超出数量上限（如每个 tab 的 section 数、面板数、查询数或变量数），或请求体超过 2 MiB，返回 `EntityTooLarge`（HTTP 413）；`schema_version` 不是 `dashboard.v1` 时返回 `UnsupportedSchemaVersion`（HTTP 422）。\n- 会记录审计日志。",
           "href": "/zh/api-reference/monitors/dashboards/monit-dashboard-write-create",
           "metadata": {
             "sidebarTitle": "创建仪表盘"
@@ -2518,7 +2631,7 @@
                                       "legend_alias": "{{env}} requests",
                                       "query": {
                                         "mode": "range",
-                                        "expr": "sum(rate(http_requests_total{env=\"{{env}}\"}[5m]))",
+                                        "expr": "sum(rate(http_requests_total{env=\"${env}\"}[5m]))",
                                         "args": {},
                                         "min_step_seconds": 30
                                       }
@@ -2652,7 +2765,7 @@
                                   "legend_alias": "{{env}} requests",
                                   "query": {
                                     "mode": "range",
-                                    "expr": "sum(rate(http_requests_total{env=\"{{env}}\"}[5m]))",
+                                    "expr": "sum(rate(http_requests_total{env=\"${env}\"}[5m]))",
                                     "args": {},
                                     "min_step_seconds": 30
                                   }
@@ -2691,7 +2804,7 @@
           "Monitors/仪表盘"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | **1,000 requests/minute**; **50 requests/second** per account |\n| 权限要求 | 任意有效 `app_key`；结果限于其所属成员可读的目录 |\n\n## 使用说明\n\n- 位于回收站的仪表盘返回 `DashboardDeleted`，不返回定义。\n- 该读接口除目录可读性外无额外权限点：`app_key` 只能看到其所属成员可读目录下的仪表盘。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 只能看到位于`app_key` 所属成员可访问的目录：其本人创建或归属其所在团队的目录及这些目录的全部子目录；账户所有者与管理员可访问全部目录中的仪表盘；其他仪表盘返回 `DashboardNotFound`（HTTP 404）。\n- 位于回收站的仪表盘返回 `DashboardDeleted`（HTTP 410），不返回定义；可用 `POST /monit/dashboard/trash/list` 找到它，再用 `POST /monit/dashboard/restore` 恢复。\n- 下次更新、移动或删除时，把返回的 `revision` 作为 `expected_revision` 传入。",
           "href": "/zh/api-reference/monitors/dashboards/monit-dashboard-read-get",
           "metadata": {
             "sidebarTitle": "查看仪表盘详情"
@@ -2796,7 +2909,7 @@
                                       "legend_alias": "{{env}} requests",
                                       "query": {
                                         "mode": "range",
-                                        "expr": "sum(rate(http_requests_total{env=\"{{env}}\"}[5m]))",
+                                        "expr": "sum(rate(http_requests_total{env=\"${env}\"}[5m]))",
                                         "args": {},
                                         "min_step_seconds": 30
                                       }
@@ -2878,7 +2991,7 @@
           "Monitors/仪表盘"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | **300 requests/minute**; **20 requests/second** per account |\n| 权限要求 | **仪表盘管理**（`monit`） |\n\n## 使用说明\n\n- 发送的是完整定义——这不是部分更新。\n- `expected_revision` 必须等于已存版本号，否则返回 `DashboardRevisionConflict`。\n- 定义逐字节相同时 `changed` 为 false，且不会产生新版本。\n- 仅当调用过程中调用方失去该目录的读权限时，响应中的 `resource` 才为 null。\n- 会记录审计日志。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **仪表盘管理**（`monit`） |\n\n## 使用说明\n\n- 需要发送完整定义；未包含的内容会被删除，不会沿用已存版本。\n- `expected_revision` 必须等于已存版本号，否则以 `DashboardRevisionConflict`（HTTP 409）失败；请重新读取仪表盘后重试。\n- 成功后 `revision` 加 1，并记录一条带 `message` 的版本。规范化后的定义与 `schema_version` 都与已存内容相同时，`changed` 为 false，`revision` 不变，也不会记录版本。\n- 标题与描述会去除首尾空白，未填写的数值 `unit` 会存为 `unitless`，因此返回的 `definition` 可能与请求略有不同。\n- 位于回收站的仪表盘返回 `DashboardDeleted`（HTTP 410）；调用方无权访问其所在目录时返回 `AccessDenied`。校验与大小错误与 `POST /monit/dashboard/create` 相同。\n- 会记录审计日志。",
           "href": "/zh/api-reference/monitors/dashboards/monit-dashboard-write-update",
           "metadata": {
             "sidebarTitle": "更新仪表盘"
@@ -2985,7 +3098,7 @@
                                         "legend_alias": "{{env}} requests",
                                         "query": {
                                           "mode": "range",
-                                          "expr": "sum(rate(http_requests_total{env=\"{{env}}\"}[5m]))",
+                                          "expr": "sum(rate(http_requests_total{env=\"${env}\"}[5m]))",
                                           "args": {},
                                           "min_step_seconds": 30
                                         }
@@ -3120,7 +3233,7 @@
                                   "legend_alias": "{{env}} requests",
                                   "query": {
                                     "mode": "range",
-                                    "expr": "sum(rate(http_requests_total{env=\"{{env}}\"}[5m]))",
+                                    "expr": "sum(rate(http_requests_total{env=\"${env}\"}[5m]))",
                                     "args": {},
                                     "min_step_seconds": 30
                                   }
@@ -3160,7 +3273,7 @@
           "Monitors/仪表盘"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | **300 requests/minute**; **20 requests/second** per account |\n| 权限要求 | **仪表盘管理**（`monit`） |\n\n## 使用说明\n\n- 源目录与目标目录都必须可写。\n- 定义不变，因此仅当仪表盘已在 `folder_id` 中时 `changed` 才为 false。\n- 会记录审计日志。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **仪表盘管理**（`monit`） |\n\n## 使用说明\n\n- 调用方必须同时能访问当前目录与目标目录（本人创建或归属其团队的目录及其子目录；账户所有者与管理员可访问全部目录）。无权访问当前目录返回 `AccessDenied`；目标目录不存在或无权访问返回 `FolderNotFound`（HTTP 404）。\n- 定义不会改动，但真正移动时 `revision` 仍会加 1 并记录一条版本。若仪表盘已在 `folder_id` 中，`changed` 为 false，且不做任何写入。\n- `expected_revision` 必须等于已存版本号，否则返回 `DashboardRevisionConflict`（HTTP 409）；位于回收站的仪表盘返回 `DashboardDeleted`（HTTP 410）。\n- 会记录审计日志。",
           "href": "/zh/api-reference/monitors/dashboards/monit-dashboard-write-move",
           "metadata": {
             "sidebarTitle": "移动仪表盘"
@@ -3267,7 +3380,7 @@
                                         "legend_alias": "{{env}} requests",
                                         "query": {
                                           "mode": "range",
-                                          "expr": "sum(rate(http_requests_total{env=\"{{env}}\"}[5m]))",
+                                          "expr": "sum(rate(http_requests_total{env=\"${env}\"}[5m]))",
                                           "args": {},
                                           "min_step_seconds": 30
                                         }
@@ -3344,12 +3457,12 @@
       "post": {
         "operationId": "monit-dashboard-write-delete",
         "summary": "删除仪表盘",
-        "description": "把仪表盘移入回收站。",
+        "description": "把仪表盘移入回收站，30 天内可恢复。",
         "tags": [
           "Monitors/仪表盘"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | **300 requests/minute**; **20 requests/second** per account |\n| 权限要求 | **仪表盘管理**（`monit`） |\n\n## 使用说明\n\n- 这是软删除：定义保留 30 天，可用 `POST /monit/dashboard/restore` 恢复。\n- 返回的 `revision` 是本次删除记录的版本号。\n- 会记录审计日志。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **仪表盘管理**（`monit`） |\n\n## 使用说明\n\n- 这是软删除：仪表盘进入回收站，删除 30 天后连同全部版本被永久清除。在此之前可用 `POST /monit/dashboard/restore` 恢复。\n- 删除会使 `revision` 加 1；返回的 `revision` 就是恢复时要传入的 `expected_revision`。\n- `expected_revision` 必须等于已存版本号，否则返回 `DashboardRevisionConflict`（HTTP 409）；删除已在回收站中的仪表盘返回 `DashboardDeleted`（HTTP 410）。\n- 会记录审计日志。",
           "href": "/zh/api-reference/monitors/dashboards/monit-dashboard-write-delete",
           "metadata": {
             "sidebarTitle": "删除仪表盘"
@@ -3426,7 +3539,7 @@
           "Monitors/仪表盘"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | **300 requests/minute**; **20 requests/second** per account |\n| 权限要求 | **仪表盘管理**（`monit`） |\n\n## 使用说明\n\n- 省略 `folder_id` 表示恢复到原目录；若原目录已不可写，调用会以 `RestoreFolderRequired` 失败，此时必须指定目标目录。\n- 恢复一个不在回收站中的仪表盘会以 `DashboardNotFound` 失败。\n- 会记录审计日志。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **仪表盘管理**（`monit`） |\n\n## 使用说明\n\n- 只能恢复回收站中的仪表盘；其他仪表盘返回 `DashboardNotFound`（HTTP 404）。\n- `expected_revision` 必须等于该仪表盘在回收站中的当前版本号（即删除接口返回、回收站列表中显示的 `revision`），否则返回 `DashboardRevisionConflict`（HTTP 409）。\n- 省略 `folder_id` 表示恢复到原目录。若原目录已不存在，账户所有者与管理员会收到 `RestoreFolderRequired`（HTTP 409），需指定目标目录；其他成员只能恢复原目录仍可访问的仪表盘，否则返回 `DashboardNotFound`。\n- 目标目录不存在或无权访问时返回 `FolderNotFound`（HTTP 404）。恢复会使 `revision` 加 1。\n- 会记录审计日志。",
           "href": "/zh/api-reference/monitors/dashboards/monit-dashboard-write-restore",
           "metadata": {
             "sidebarTitle": "恢复仪表盘"
@@ -3531,7 +3644,7 @@
                                       "legend_alias": "{{env}} requests",
                                       "query": {
                                         "mode": "range",
-                                        "expr": "sum(rate(http_requests_total{env=\"{{env}}\"}[5m]))",
+                                        "expr": "sum(rate(http_requests_total{env=\"${env}\"}[5m]))",
                                         "args": {},
                                         "min_step_seconds": 30
                                       }
@@ -3607,12 +3720,12 @@
       "post": {
         "operationId": "monit-dashboard-read-list",
         "summary": "查询仪表盘列表",
-        "description": "列出某个目录下的仪表盘。",
+        "description": "列出某个目录下直接存放的仪表盘，支持关键词搜索与分页。",
         "tags": [
           "Monitors/仪表盘"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | **1,000 requests/minute**; **50 requests/second** per account |\n| 权限要求 | 任意有效 `app_key`；结果限于其所属成员可读的目录 |\n\n## 使用说明\n\n- `folder_id` 必填；列表始终包含子目录。\n- `query` 按空白拆分后匹配标题与描述。\n- 此处排序键仅限 `title` 与 `updated_at`，最多两个，默认按 `updated_at` 倒序。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 只返回直接存放在 `folder_id` 中的仪表盘，不包含其子目录中的仪表盘。跨目录查找请用 `POST /monit/dashboard/search`。\n- `folder_id` 必须是`app_key` 所属成员可访问的目录：其本人创建或归属其所在团队的目录及这些目录的全部子目录；账户所有者与管理员可访问全部目录之一，否则以 `FolderNotFound`（HTTP 404）失败。回收站中的仪表盘不会被列出。\n- `query` 按空白拆分为多个词；标题或描述中包含每一个词（子串匹配）的仪表盘才会命中。\n- 排序键为 `title` 与 `updated_at`，最多两个且不可重复；默认按 `updated_at` 倒序，相同值再按 `dashboard_id` 排序。",
           "href": "/zh/api-reference/monitors/dashboards/monit-dashboard-read-list",
           "metadata": {
             "sidebarTitle": "查询仪表盘列表"
@@ -3717,7 +3830,7 @@
           "Monitors/仪表盘"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | **1,000 requests/minute**; **50 requests/second** per account |\n| 权限要求 | 任意有效 `app_key`；结果限于其所属成员可读的目录 |\n\n## 使用说明\n\n- `query` 至少需要一个单词；空查询会以 `InvalidParameter` 失败。\n- 范围限于 `app_key` 所属成员可读的目录——该接口不会扩大访问范围。\n- 排序键仅限 `title` 与 `updated_at`。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- `query` 至少需要一个词；为空或只含空白时以 `InvalidParameter` 失败。标题或描述中包含每一个词（子串匹配）的仪表盘才会命中。\n- 结果只包含`app_key` 所属成员可访问的目录：其本人创建或归属其所在团队的目录及这些目录的全部子目录；账户所有者与管理员可访问全部目录中的仪表盘。回收站中的仪表盘不会返回。\n- 排序键为 `title` 与 `updated_at`，最多两个且不可重复；默认按 `updated_at` 倒序。",
           "href": "/zh/api-reference/monitors/dashboards/monit-dashboard-read-search",
           "metadata": {
             "sidebarTitle": "搜索仪表盘"
@@ -3821,7 +3934,7 @@
           "Monitors/仪表盘"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | **1,000 requests/minute**; **50 requests/second** per account |\n| 权限要求 | **仪表盘管理**（`monit`） |\n\n## 使用说明\n\n- 排序键仅限 `title` 与 `deleted_at`，默认按 `deleted_at` 倒序。\n- 与读接口不同，该接口受「仪表盘管理」权限点管控。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **仪表盘管理**（`monit`） |\n\n## 使用说明\n\n- 列出位于`app_key` 所属成员可访问的目录：其本人创建或归属其所在团队的目录及这些目录的全部子目录；账户所有者与管理员可访问全部目录中的已删除仪表盘。每条记录在删除 30 天后被永久清除。\n- 排序键为 `title` 与 `deleted_at`，最多两个且不可重复；默认按 `deleted_at` 倒序。\n- 与其他仪表盘读接口不同，该接口需要「仪表盘管理」权限。",
           "href": "/zh/api-reference/monitors/dashboards/monit-dashboard-trash-read-list",
           "metadata": {
             "sidebarTitle": "查询回收站仪表盘"
@@ -3921,7 +4034,7 @@
           "Monitors/仪表盘"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | **1,000 requests/minute**; **50 requests/second** per account |\n| 权限要求 | 任意有效 `app_key`；结果限于其所属成员可读的目录 |\n\n## 使用说明\n\n- 最多保留 20 个版本（含当前版本）；产生新版本时更早的会被丢弃。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 按最新在前最多返回最近 20 个版本。创建、每次改变定义的更新、移动、删除与恢复都会记录一个版本；更早的版本会被清理。\n- 只有通过 `POST /monit/dashboard/update` 并附带说明写入的版本才有 `message`。\n- 只能看到位于`app_key` 所属成员可访问的目录：其本人创建或归属其所在团队的目录及这些目录的全部子目录；账户所有者与管理员可访问全部目录中的仪表盘，其他返回 `DashboardNotFound`（HTTP 404）；位于回收站的仪表盘返回 `DashboardDeleted`（HTTP 410）。",
           "href": "/zh/api-reference/monitors/dashboards/monit-dashboard-revision-read-list",
           "metadata": {
             "sidebarTitle": "查询仪表盘版本列表"
@@ -4011,7 +4124,7 @@
           "Monitors/仪表盘"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | **1,000 requests/minute**; **50 requests/second** per account |\n| 权限要求 | 任意有效 `app_key`；结果限于其所属成员可读的目录 |\n\n## 使用说明\n\n- 版本号按仪表盘独立编号，从 1 开始。\n- 已滚动出 20 条窗口的版本会返回 `DashboardNotFound`。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 版本号按仪表盘独立编号，从 1（创建）开始。早于最近 20 个的版本已被清理，返回 `DashboardNotFound`（HTTP 404）。\n- 只能看到位于`app_key` 所属成员可访问的目录：其本人创建或归属其所在团队的目录及这些目录的全部子目录；账户所有者与管理员可访问全部目录中的仪表盘；位于回收站的仪表盘返回 `DashboardDeleted`（HTTP 410），需先恢复才能读取历史。",
           "href": "/zh/api-reference/monitors/dashboards/monit-dashboard-revision-read-get",
           "metadata": {
             "sidebarTitle": "查看仪表盘版本详情"
@@ -4112,7 +4225,7 @@
                                       "legend_alias": "{{env}} requests",
                                       "query": {
                                         "mode": "range",
-                                        "expr": "sum(rate(http_requests_total{env=\"{{env}}\"}[5m]))",
+                                        "expr": "sum(rate(http_requests_total{env=\"${env}\"}[5m]))",
                                         "args": {},
                                         "min_step_seconds": 30
                                       }
@@ -4191,7 +4304,7 @@
           "Monitors/仪表盘"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | **1,000 requests/minute**; **50 requests/second** per account |\n| 权限要求 | 任意有效 `app_key`；结果限于其所属成员可读的目录 |\n\n## 使用说明\n\n- 用于渲染导航，或让 Agent 在执行前定位面板 ID——可避免拉取完整定义。\n- 设置 `target_id` 时只返回包含该 tab/section/panel 的分支；ID 不存在会以 `TargetNotFound` 失败。\n- 面板条目只含可视化 `kind` 与数据源类型，不包含面板查询。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 可用于渲染导航，或在调用 `POST /monit/dashboard/panel/run` 前定位面板 ID，而无需下载查询。\n- `target_id` 为 tab ID 时返回整个 tab；为 section ID 时返回该 tab，但只含该 section 且不含顶层面板；为面板 ID 时只返回该面板及其所在 tab/section。ID 不存在时以 `TargetNotFound`（HTTP 404）失败。\n- 面板条目只含可视化 `kind` 与数据源类型，不含查询。数据源变量的 `selection` 固定为 `single` 且不含 `all`。\n- 只能看到位于`app_key` 所属成员可访问的目录：其本人创建或归属其所在团队的目录及这些目录的全部子目录；账户所有者与管理员可访问全部目录中的仪表盘；位于回收站的仪表盘返回 `DashboardDeleted`（HTTP 410）。",
           "href": "/zh/api-reference/monitors/dashboards/monit-dashboard-read-outline",
           "metadata": {
             "sidebarTitle": "获取仪表盘大纲"
@@ -4334,7 +4447,7 @@
           "Monitors/仪表盘"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | **16 requests/second** (no per-minute cap) per account |\n| 权限要求 | **数据源查看**（`monit`） |\n\n## 使用说明\n\n- 无法解析的变量不会导致调用失败：其条目会带上 `error`，并且不出现在 `selections` 中。\n- 显式传入空的 `values` 表示未解析——解析器不会回退到存储的默认值。\n- 选择最多 20 个变量；变量名需匹配 `^[A-Za-z_][A-Za-z0-9_]{0,63}$`。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **16 次/秒**（无每分钟上限） |\n| 权限要求 | **数据源查看**（`monit`） |\n\n## 使用说明\n\n- 解析已存仪表盘当前版本的变量。`variables` 是调用方当前的选择；未给出的变量回退到存储的默认值（`custom`、`query` 变量用 `default`；`datasource` 变量用 `default_datasource_id`，若它已不在候选项中，则取按名称排序的第一个候选项）。\n- 无法解析的变量不会导致调用失败：其条目会带上 `error`，并且不出现在 `selections` 中。常见原因：既无选择也无默认值、所选值不在候选项中、依赖项未解析、数据源不可达。\n- 显式传入空的 `values` 表示未解析（`variable_invalid`），解析器不会回退到存储的默认值。\n- 变量按依赖顺序解析，依赖了失败变量的变量也会报错。`variables` 中出现仪表盘未定义的变量名时，调用以 HTTP 400 失败。\n- 每个变量最多返回 1000 个候选项，所有候选项合计须在 8 MiB 以内，否则以 `EntityTooLarge`（HTTP 413）失败。`query` 变量只能对 Prometheus、MySQL、Loki 数据源执行。\n- 调用方须能看到该仪表盘所在的目录，否则返回 `DashboardNotFound`（HTTP 404）。整个调用有 35 秒的总时限，超时返回 `RuntimeTimeout`（HTTP 504）。",
           "href": "/zh/api-reference/monitors/dashboards/monit-dashboard-variable-read-resolve",
           "metadata": {
             "sidebarTitle": "解析仪表盘变量"
@@ -4455,7 +4568,7 @@
           "Monitors/仪表盘"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | **16 requests/second** (no per-minute cap) per account |\n| 权限要求 | **数据源查看**（`monit`） |\n\n## 使用说明\n\n- `context` 为 `new` 时指向尚无仪表盘的目录，为 `existing` 时指向已存仪表盘；两者字段混用会校验失败。\n- 不落库，因此响应中没有 `dashboard_id` 或 `revision`。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **16 次/秒**（无每分钟上限） |\n| 权限要求 | **数据源查看**（`monit`） |\n\n## 使用说明\n\n- 解析尚未存入仪表盘的草稿变量列表，便于编辑器在保存前测试变量。不落库，因此响应中没有 `dashboard_id` 或 `revision`。\n- 草稿属于已存仪表盘时，`context.kind` 为 `existing` 并带 `dashboard_id`；仪表盘尚不存在时为 `new` 并带 `folder_id`；混用另一种类型的字段会校验失败（HTTP 400）。调用方需要能访问该仪表盘所在目录或该目录（否则返回 403/404）。\n- 草稿 `variables` 按与已存定义相同的规则校验（名称、依赖、选项上限、最多 20 个变量、1 MiB）；违规时以 HTTP 400 失败，超出大小限制时为 HTTP 413。\n- 解析行为与「解析仪表盘变量」一致：失败的变量带 `error` 且不出现在 `selections` 中，空的 `values` 选择视为未解析。\n- 整个调用有 35 秒的总时限，超时返回 `RuntimeTimeout`（HTTP 504）。",
           "href": "/zh/api-reference/monitors/dashboards/monit-dashboard-variable-read-preview",
           "metadata": {
             "sidebarTitle": "预览草稿变量"
@@ -4604,7 +4717,7 @@
           "Monitors/仪表盘"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | **16 requests/second** (no per-minute cap) per account |\n| 权限要求 | **数据源查看**（`monit`） |\n\n## 使用说明\n\n- 用于在真正执行前展示面板将命中哪个数据源、使用什么表达式。\n- `panel_ids` 接受 1～100 个唯一 ID；面板在仪表盘中不存在时产生 `state: \"error\"` 条目，而不会使整个调用失败。\n- 只有部分查询解析成功的面板返回 `state: \"partial\"`。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **16 次/秒**（无每分钟上限） |\n| 权限要求 | **数据源查看**（`monit`） |\n\n## 使用说明\n\n- 用于在运行之前展示面板将命中哪个数据源、使用什么表达式。不会执行任何查询。\n- `panel_ids` 接受 1～100 个唯一 ID，按请求顺序返回。面板不在该仪表盘中时，返回 `state: \"error\"`、原因 `panel_missing`，而不会使整个调用失败；文本面板返回 `state: \"error\"`、原因 `invalid_request`。\n- 面板的全部查询解析成功时 `state` 为 `success`，只有部分成功为 `partial`，全部失败为 `error`。`queries` 列出解析成功的查询；`error` 只报告第一个失败。\n- 内置时间变量（如步长、时间范围）根据 `time` 和 `max_data_points` 渲染；`preserve_builtin_variables` 为 `true` 时原样保留，供调用方用自己的窗口渲染。用户变量始终会被解析。\n- 面板查询只能绑定到 Prometheus、MySQL、Loki 数据源。整个调用有 35 秒的总时限，超时返回 `RuntimeTimeout`（HTTP 504）。",
           "href": "/zh/api-reference/monitors/dashboards/monit-dashboard-query-read-resolve",
           "metadata": {
             "sidebarTitle": "解析面板查询"
@@ -4730,7 +4843,7 @@
           "Monitors/仪表盘"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | **16 requests/second** (no per-minute cap) per account |\n| 权限要求 | **数据源查看**（`monit`） |\n\n## 使用说明\n\n- 省略 `revision` 表示按当前版本运行；传入它可让调用返回过期错误，而不是返回已被覆盖的数据。\n- `run_state` 汇总各查询状态——部分 ref 成功为 `partial`；数据源接受了调用但查询不匹配其类型时为 `incompatible`。\n- 每个 ref 的 `execution` 载荷随数据源而异且原样透传；`child_request_id` 可用于追踪底层数据源调用。\n- `max_data_points` 默认 100，取值 2～5000。整个响应上限 8 MiB。\n- 单个面板内查询的并发上限为 6。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **32 次/秒**（无每分钟上限） |\n| 权限要求 | **数据源查看**（`monit`） |\n\n## 使用说明\n\n- 对已存仪表盘当前版本的单个面板，把其全部查询发往对应数据源执行。即使所有查询都失败，调用仍返回 HTTP 200，请查看 `run_state` 以及各 ref 的 `state`、`error`。\n- 省略 `revision`（或传 0）表示按当前版本运行。传入它时，若仪表盘已被修改，调用以 `DashboardRevisionConflict`（HTTP 409）失败，而不是返回基于过期定义的数据。\n- `run_state` 汇总各 ref：全部成功为 `success`，至少一个成功且至少一个未成功为 `partial`，否则为 `cancelled`、`incompatible` 或 `error`。查询已执行但结果与面板可视化不匹配（例如配置的值字段缺失或不是数值）时，该 ref 为 `incompatible`。\n- 每个 ref 的 `execution` 随数据源而异且原样透传；`child_request_id` 标识底层数据源调用。文本面板不能运行（HTTP 400），`panel_id` 不存在时返回 `TargetNotFound`（HTTP 404）。\n- `max_data_points` 默认 100，取值 2～5000。单个面板内最多同时运行 6 个查询。响应超过 8 MiB 时以 `EntityTooLarge`（HTTP 413）拒绝，而不会截断。整个调用有 35 秒的总时限，超时返回 `RuntimeTimeout`（HTTP 504）。",
           "href": "/zh/api-reference/monitors/dashboards/monit-dashboard-panel-read-run",
           "metadata": {
             "sidebarTitle": "运行仪表盘面板"
@@ -4891,7 +5004,7 @@
           "Monitors/仪表盘"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | **16 requests/second** (no per-minute cap) per account |\n| 权限要求 | **数据源查看**（`monit`） |\n\n## 使用说明\n\n- 用于在用户仍在编辑时校验面板——不会写入任何内容，也不会产生版本。\n- 草稿同样受已存仪表盘的全部限制：网格重叠、各可视化类型的查询数量，以及 1 MiB 定义上限。\n- 响应结构与面板运行一致，只是不含 `dashboard_id`。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **32 次/秒**（无每分钟上限） |\n| 权限要求 | **数据源查看**（`monit`） |\n\n## 使用说明\n\n- 用于在用户仍在编辑面板时检查它：草稿面板及其变量被内联执行，不会写入任何内容，也不会产生版本。\n- `context` 把草稿关联到已存仪表盘（`existing` 并带 `dashboard_id`）或尚无仪表盘的目录（`new` 并带 `folder_id`）。调用方需要能访问该仪表盘所在目录或该目录。\n- 草稿 `panel` 与 `variables` 按与已存定义相同的规则校验（网格、各可视化类型的查询数量、变量引用），且不得超过 1 MiB；违规时以 HTTP 400 失败，超出大小限制时为 HTTP 413。文本面板不能预览。\n- 响应结构与面板运行一致，只是不含 `dashboard_id` 和 `revision`。即使所有查询都失败，也返回 HTTP 200，请查看 `run_state` 以及各 ref 的 `state`、`error`。\n- `max_data_points` 默认 100，取值 2～5000。同时最多运行 6 个查询。响应超过 8 MiB 时以 `EntityTooLarge`（HTTP 413）拒绝。整个调用有 35 秒的总时限，超时返回 `RuntimeTimeout`（HTTP 504）。",
           "href": "/zh/api-reference/monitors/dashboards/monit-dashboard-panel-read-preview",
           "metadata": {
             "sidebarTitle": "预览草稿面板"
@@ -5043,7 +5156,7 @@
                       "legend_alias": "{{env}} requests",
                       "query": {
                         "mode": "range",
-                        "expr": "sum(rate(http_requests_total{env=\"{{env}}\"}[5m]))",
+                        "expr": "sum(rate(http_requests_total{env=\"${env}\"}[5m]))",
                         "args": {},
                         "min_step_seconds": 30
                       }
@@ -5110,16 +5223,16 @@
     "/monit/folder/list": {
       "post": {
         "operationId": "monit-folder-read-list",
-        "summary": "查询监控节点列表",
+        "summary": "查询监控目录列表",
         "description": "列出调用方可读的全部监控节点。",
         "tags": [
           "Monitors/规则分组"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | **1,000 requests/minute**; **50 requests/second** per account |\n| 权限要求 | **告警规则查看** 或 **节点权限查看**（`monit`） |\n\n## 使用说明\n\n- 响应是可读目录的扁平列表而非树：请用 `parent_id` 与 `parent_path` 重建层级，并在客户端自行搜索。\n- 仪表盘与告警规则共用这棵目录树，因此同一批 ID 会作为仪表盘载荷中的 `folder_id` 出现。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **告警规则查看**、**告警规则管理**、**节点权限查看**或**节点权限管理**（`monit`） |\n\n## 使用说明\n\n- 响应是可见文件夹的扁平列表而非树：请用 `parent_id` 与 `parent_path` 重建层级，并在客户端自行搜索。账户下没有可见文件夹时返回 `[]`。\n- 账户所有者和管理员可看到全部文件夹。其他成员可看到自己创建的文件夹、归属于自己所在团队的文件夹、这些文件夹下的全部子文件夹，以及到达它们所需经过的祖先文件夹。\n- 仪表盘与告警规则共用这棵文件夹树，因此同一批 ID 会作为仪表盘载荷和告警规则中的 `folder_id` 出现。",
           "href": "/zh/api-reference/monitors/rule-folders/monit-folder-read-list",
           "metadata": {
-            "sidebarTitle": "查询监控节点列表"
+            "sidebarTitle": "查询监控目录列表"
           }
         },
         "responses": {
@@ -5174,6 +5287,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -5187,12 +5303,12 @@
       "post": {
         "operationId": "monit-folder-read-health",
         "summary": "获取监控目录健康摘要",
-        "description": "获取可见目录的健康摘要，包含后代目录中的问题。",
+        "description": "获取可见监控文件夹的问题标记，包含后代文件夹中的问题。",
         "tags": [
           "Monitors/规则分组"
         ],
         "x-mint": {
-          "content": "## 限制\n\n| 项目 | 值 |\n| ------ | ----- |\n| 频率限制 | 每账户 **30 次/分钟**；**2 次/秒** |\n| 权限 | **告警规则查看**、**告警规则管理**、**节点权限查看**或**节点权限管理**（`monit`） |\n\n## 使用说明\n\n- 问题包括活跃告警和告警规则运行问题，并向可见祖先目录汇总。\n- 此操作扫描目录规则和运行状态，请避免频繁轮询。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **30 次/分钟**；**2 次/秒** |\n| 权限要求 | **告警规则查看**、**告警规则管理**、**节点权限查看**或**节点权限管理**（`monit`） |\n\n## 使用说明\n\n- `items` 对调用方可见的每个文件夹返回一项（与 `/monit/folder/list` 的范围相同），按 `id` 升序排列。\n- 当文件夹自身或其任一后代文件夹中的规则存在活跃告警或运行问题时，`has_issue` 为 true，且该问题也会显示在每一级可见的祖先文件夹上。只统计调用方可读文件夹中的规则。\n- 此操作会扫描文件夹中的规则和运行状态，请避免频繁轮询。",
           "href": "/zh/api-reference/monitors/rule-folders/monit-folder-read-health",
           "metadata": {
             "sidebarTitle": "获取监控目录健康摘要"
@@ -5238,6 +5354,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -5251,12 +5370,12 @@
       "post": {
         "operationId": "monit-folder-write-create",
         "summary": "创建监控目录",
-        "description": "在顶层或有权访问的父目录下创建监控目录。",
+        "description": "在根级别或调用方有权修改的父文件夹下创建监控文件夹。",
         "tags": [
           "Monitors/规则分组"
         ],
         "x-mint": {
-          "content": "## 限制\n\n| 项目 | 值 |\n| ------ | ----- |\n| 频率限制 | 每账户 **300 次/分钟**；**20 次/秒** |\n| 权限 | **告警规则管理**或**节点权限管理**（`monit`） |\n\n## 使用说明\n\n- 传入 `parent_id: 0` 或省略该字段以创建顶层目录。您必须有权访问父目录。\n- 每次调用均记录账户审计日志。请勿在请求字段中传入密钥。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **告警规则管理**或**节点权限管理**（`monit`） |\n\n## 使用说明\n\n- 传入 `parent_id: 0` 或省略该字段以创建根文件夹。要在某个父文件夹下创建，调用方必须有权修改它：账户所有者或管理员、该父文件夹或其任一祖先的创建者，或者被分配到该父文件夹或其任一祖先的团队成员。父文件夹不存在时返回 `InvalidParameter`，无权修改父文件夹时返回 `AccessDenied`。\n- 响应为新创建的文件夹。\n- 每次调用均记录账户审计日志。请勿在请求字段中传入密钥。",
           "href": "/zh/api-reference/monitors/rule-folders/monit-folder-write-create",
           "metadata": {
             "sidebarTitle": "创建监控目录"
@@ -5309,6 +5428,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -5338,12 +5460,12 @@
       "post": {
         "operationId": "monit-folder-write-update",
         "summary": "更新监控目录",
-        "description": "替换有权访问的监控目录的名称、备注和团队归属。",
+        "description": "替换调用方有权修改的监控文件夹的名称、备注和团队归属。",
         "tags": [
           "Monitors/规则分组"
         ],
         "x-mint": {
-          "content": "## 限制\n\n| 项目 | 值 |\n| ------ | ----- |\n| 频率限制 | 每账户 **300 次/分钟**；**20 次/秒** |\n| 权限 | **告警规则管理**或**节点权限管理**（`monit`） |\n\n## 使用说明\n\n- 必须传入 `id` 和 `name`。此操作替换可编辑字段：省略 `note` 会清空备注，省略 `team_id` 会重置为 0。\n- 请使用移动接口更改父目录。\n- 每次调用均记录账户审计日志。请勿在请求字段中传入密钥。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **告警规则管理**或**节点权限管理**（`monit`） |\n\n## 使用说明\n\n- 必须传入 `id` 和 `name`。此操作替换可编辑字段：省略 `note` 会清空备注，省略 `team_id` 会重置为 0。\n- 调用方必须有权修改该文件夹：账户所有者或管理员、该文件夹的创建者或其任一祖先的创建者，或者被分配到该文件夹或其任一祖先的团队成员。文件夹不存在时返回 `InvalidParameter`，无权修改时返回 `AccessDenied`。\n- 请使用移动接口更改父文件夹。响应为更新后的文件夹。\n- 每次调用均记录账户审计日志。请勿在请求字段中传入密钥。",
           "href": "/zh/api-reference/monitors/rule-folders/monit-folder-write-update",
           "metadata": {
             "sidebarTitle": "更新监控目录"
@@ -5396,6 +5518,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -5430,7 +5555,7 @@
           "Monitors/规则分组"
         ],
         "x-mint": {
-          "content": "## 限制\n\n| 项目 | 值 |\n| ------ | ----- |\n| 频率限制 | 每账户 **300 次/分钟**；**20 次/秒** |\n| 权限 | **告警规则管理**或**节点权限管理**（`monit`） |\n\n## 使用说明\n\n- 您必须有权访问源目录和目标目录。\n- 必须传入 `dest_parent_id`；移至顶层时显式传 0。不能移至自身或后代目录下。\n- 后代目录路径在同一事务中更新。\n- 每次调用均记录账户审计日志。请勿在请求字段中传入密钥。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **告警规则管理**或**节点权限管理**（`monit`） |\n\n## 使用说明\n\n- 调用方必须有权修改源文件夹；除非 `dest_parent_id` 为 0，还必须有权修改目标文件夹。\n- 必须传入 `dest_parent_id`；移至根级别时显式传 0。它不能等于 `id`，不能移至自身或后代文件夹下，否则返回 `InvalidParameter`。移动到当前父文件夹时请求成功，但不产生任何变化。\n- 后代文件夹的路径在同一事务中更新，该文件夹及其全部后代的最后更新人都会记为调用方。\n- 每次调用均记录账户审计日志。请勿在请求字段中传入密钥。",
           "href": "/zh/api-reference/monitors/rule-folders/monit-folder-write-move",
           "metadata": {
             "sidebarTitle": "移动监控目录"
@@ -5470,6 +5595,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -5497,12 +5625,12 @@
       "post": {
         "operationId": "monit-folder-write-delete",
         "summary": "删除监控目录",
-        "description": "移除子目录、规则和仪表盘后，删除有权访问的监控目录。",
+        "description": "删除调用方有权修改的空监控文件夹。",
         "tags": [
           "Monitors/规则分组"
         ],
         "x-mint": {
-          "content": "## 限制\n\n| 项目 | 值 |\n| ------ | ----- |\n| 频率限制 | 每账户 **300 次/分钟**；**20 次/秒** |\n| 权限 | **告警规则管理**或**节点权限管理**（`monit`） |\n\n## 使用说明\n\n- 只能删除空目录。存在子目录、告警规则或仪表盘时，返回 HTTP 409，错误码为 `FolderNotEmpty`。\n- 每次调用均记录账户审计日志。请勿在请求字段中传入密钥。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **告警规则管理**或**节点权限管理**（`monit`） |\n\n## 使用说明\n\n- 只能删除空文件夹，不会替您删除其中的内容。存在子文件夹、告警规则或仪表盘时，返回 HTTP 409，错误码为 `FolderNotEmpty`。\n- 调用方必须有权修改该文件夹。文件夹不存在时返回 `InvalidParameter`，无权修改时返回 `AccessDenied`。\n- 每次调用均记录账户审计日志。请勿在请求字段中传入密钥。",
           "href": "/zh/api-reference/monitors/rule-folders/monit-folder-write-delete",
           "metadata": {
             "sidebarTitle": "删除监控目录"
@@ -5542,6 +5670,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -5619,7 +5750,7 @@
         "type": "apiKey",
         "in": "query",
         "name": "app_key",
-        "description": "在 Flashduty 控制台 账户 → APP Key 中签发的 app_key。调用任何公开 API 时都必须携带。它等同于所属账户的身份凭证，请妥善保管。"
+        "description": "在 Flashduty 控制台 我的 → APP Key 中创建的 APP Key。可通过 query 参数 `app_key` 或请求头 `Fd-App-Key` 传入。实际可访问范围是该 APP Key 的权限范围与创建者当前角色权限的交集，请妥善保管。"
       }
     },
     "responses": {
@@ -5666,7 +5797,7 @@
         }
       },
       "Forbidden": {
-        "description": "app_key 有效但没有执行该操作的权限。",
+        "description": "app_key 有效，但其权限范围或创建者角色不允许该操作或该对象。",
         "content": {
           "application/json": {
             "schema": {
@@ -5708,7 +5839,7 @@
         }
       },
       "TooManyRequests": {
-        "description": "命中限流。可能是全局 API 限流、账户级限流或集成级限流。限流按账户聚合。",
+        "description": "触发频率限制（账户级限制或该接口的平台级上限）。请等待响应头 `Flashcat-Request-Rate-Limit-Delay` 给出的秒数后重试。",
         "content": {
           "application/json": {
             "schema": {
@@ -5726,6 +5857,15 @@
               }
             }
           }
+        },
+        "headers": {
+          "Flashcat-Request-Rate-Limit-Delay": {
+            "description": "距当前限流窗口重置的秒数。请求被网关全局保护限流拒绝时不返回该响应头。",
+            "schema": {
+              "type": "integer",
+              "minimum": 0
+            }
+          }
         }
       },
       "ServerError": {
@@ -5998,7 +6138,7 @@
           },
           "content": {
             "type": "string",
-            "description": "审计时刻规则完整配置的 JSON 字符串，仅在 `/monit/rule/audit/detail` 返回，列表接口中省略。"
+            "description": "变更完成后规则完整配置的 JSON 字符串，仅在 `/monit/rule/audit/detail` 返回，列表接口中省略。由 `/monit/rule/v2/create` 和 `/monit/rule/v2/update` 写入的记录采用 `AlertRuleV2` 结构；由 `/monit/rule/update/fields` 和 `/monit/rule/move` 写入的记录采用规则的存储结构，其检查器配置使用旧版恢复设置，而不是 `recovery_mode` / `end_mode`。"
           },
           "creator_id": {
             "type": "integer",
@@ -6018,7 +6158,7 @@
       },
       "AlertRuleBasic": {
         "type": "object",
-        "description": "列表视图用的告警规则基础信息。",
+        "description": "列表视图用的告警规则基础信息。`include_descendants` 为 `true` 的列表中只填充 `id`、`folder_id`、`name`，其余字段为零值。",
         "required": [
           "id",
           "account_id",
@@ -6049,27 +6189,30 @@
           "account_id": {
             "type": "integer",
             "format": "uint64",
-            "description": "账户 ID。"
+            "description": "规则所属账户 ID；在 `include_descendants` 为 `true` 的列表中为 `0`。"
           },
           "folder_id": {
             "type": "integer",
             "format": "uint64",
-            "description": "文件夹 ID。"
+            "description": "直接包含该规则的文件夹 ID；在 `include_descendants` 为 `true` 的列表中可能是所请求文件夹的子孙文件夹。"
           },
           "name": {
             "type": "string",
-            "description": "规则名称。"
+            "description": "规则名称，在所属文件夹内唯一（最长 128 个字符）。"
           },
           "labels": {
-            "type": "object",
+            "type": [
+              "object",
+              "null"
+            ],
             "additionalProperties": {
               "type": "string"
             },
-            "description": "自定义标签。"
+            "description": "规则附加到其告警事件上的自定义标签；在 `include_descendants` 为 `true` 的列表中为 `null`。"
           },
           "ds_type": {
             "type": "string",
-            "description": "数据源类型，如 `prometheus`。"
+            "description": "规则查询的数据源类型。支持告警的类型：`prometheus`、`elasticsearch`、`loki`、`clickhouse`、`mysql`、`oracle`、`postgres`、`sls`、`tencent_cls`、`victorialogs`。只有启用的规则会按此列表校验，因此禁用的规则可能是其他值；在 `include_descendants` 为 `true` 的列表中为空。"
           },
           "enabled": {
             "type": "boolean",
@@ -6077,7 +6220,7 @@
           },
           "debug_log_enabled": {
             "type": "boolean",
-            "description": "是否启用调试日志。"
+            "description": "是否开启调试日志；为 `true` 时 edge 会为该规则输出详细的评估日志。"
           },
           "cron_pattern": {
             "type": "string",
@@ -6090,7 +6233,7 @@
           },
           "delay_seconds": {
             "type": "integer",
-            "description": "评估延迟（秒）。"
+            "description": "评估时查询窗口向前偏移的秒数，用于补偿数据摄入延迟。"
           },
           "creator_id": {
             "type": "integer",
@@ -6375,7 +6518,7 @@
               "cloud",
               "self-managed"
             ],
-            "description": "部署类型。`cloud` 使用 Elastic Cloud；`self-managed` 使用自托管集群。"
+            "description": "部署类型，必填。`cloud` 使用 Elastic Cloud（无需 `address`）；`self-managed` 使用自建集群（`address` 必填）。"
           },
           "timeout_mills": {
             "type": "integer",
@@ -6592,31 +6735,40 @@
         "description": "与类型相关的数据源配置，仅包含与 `type_ident` 匹配的配置块。",
         "properties": {
           "prometheus": {
-            "$ref": "#/components/schemas/DSPrometheusConfig"
+            "$ref": "#/components/schemas/DSPrometheusConfig",
+            "description": "`type_ident` 为 `prometheus` 时的配置。"
           },
           "loki": {
-            "$ref": "#/components/schemas/DSLokiConfig"
+            "$ref": "#/components/schemas/DSLokiConfig",
+            "description": "`type_ident` 为 `loki` 时的配置。"
           },
           "mysql": {
-            "$ref": "#/components/schemas/DSMySQLConfig"
+            "$ref": "#/components/schemas/DSMySQLConfig",
+            "description": "`type_ident` 为 `mysql` 时的配置。"
           },
           "oracle": {
-            "$ref": "#/components/schemas/DSOracleConfig"
+            "$ref": "#/components/schemas/DSOracleConfig",
+            "description": "`type_ident` 为 `oracle` 时的配置。"
           },
           "postgres": {
-            "$ref": "#/components/schemas/DSPostgresConfig"
+            "$ref": "#/components/schemas/DSPostgresConfig",
+            "description": "`type_ident` 为 `postgres` 时的配置。"
           },
           "clickhouse": {
-            "$ref": "#/components/schemas/DSClickHouseConfig"
+            "$ref": "#/components/schemas/DSClickHouseConfig",
+            "description": "`type_ident` 为 `clickhouse` 时的配置。"
           },
           "elasticsearch": {
-            "$ref": "#/components/schemas/DSElasticSearchConfig"
+            "$ref": "#/components/schemas/DSElasticSearchConfig",
+            "description": "`type_ident` 为 `elasticsearch` 时的配置。"
           },
           "sls": {
-            "$ref": "#/components/schemas/DSSLSConfig"
+            "$ref": "#/components/schemas/DSSLSConfig",
+            "description": "`type_ident` 为 `sls` 时的配置。"
           },
           "victorialogs": {
-            "$ref": "#/components/schemas/DSVictoriaLogsConfig"
+            "$ref": "#/components/schemas/DSVictoriaLogsConfig",
+            "description": "`type_ident` 为 `victorialogs` 时的配置。"
           },
           "tencent_cls": {
             "$ref": "#/components/schemas/DSTencentCLSConfig",
@@ -6624,23 +6776,28 @@
           },
           "kafka": {
             "$ref": "#/components/schemas/DSKafkaConfig",
-            "x-flashduty-preserve-absence": true
+            "x-flashduty-preserve-absence": true,
+            "description": "`type_ident` 为 `kafka`（仅诊断）时的配置。"
           },
           "mongodb_mongod": {
             "$ref": "#/components/schemas/DSMongoDBConfig",
-            "x-flashduty-preserve-absence": true
+            "x-flashduty-preserve-absence": true,
+            "description": "`type_ident` 为 `mongodb_mongod`（仅诊断）时的配置，字段与 `mongodb_mongos` 相同。"
           },
           "mongodb_mongos": {
             "$ref": "#/components/schemas/DSMongoDBConfig",
-            "x-flashduty-preserve-absence": true
+            "x-flashduty-preserve-absence": true,
+            "description": "`type_ident` 为 `mongodb_mongos`（仅诊断）时的配置，字段与 `mongodb_mongod` 相同。"
           },
           "redis_node": {
             "$ref": "#/components/schemas/DSRedisNodeConfig",
-            "x-flashduty-preserve-absence": true
+            "x-flashduty-preserve-absence": true,
+            "description": "`type_ident` 为 `redis_node`（仅诊断）时的配置。"
           },
           "redis_sentinel": {
             "$ref": "#/components/schemas/DSRedisSentinelConfig",
-            "x-flashduty-preserve-absence": true
+            "x-flashduty-preserve-absence": true,
+            "description": "`type_ident` 为 `redis_sentinel`（仅诊断）时的配置。"
           }
         }
       },
@@ -6708,11 +6865,11 @@
           },
           "basic_auth_username": {
             "type": "string",
-            "description": "Basic 认证用户名。"
+            "description": "Basic Auth 用户名，`basic_auth_enabled` 为 `true` 时生效。"
           },
           "basic_auth_password": {
             "type": "string",
-            "description": "Basic 认证密码。"
+            "description": "Basic Auth 密码，`basic_auth_enabled` 为 `true` 时生效。创建、更新和详情响应会原样返回。"
           },
           "headers": {
             "type": "array",
@@ -6853,26 +7010,46 @@
           "edge_cluster_name",
           "updated_at",
           "payload",
-          "alerting_enabled"
+          "alerting_enabled",
+          "manage_team_id",
+          "readonly_team_ids",
+          "creator_id"
         ],
         "properties": {
           "id": {
             "type": "integer",
             "format": "uint64",
-            "description": "唯一数据源 ID。"
+            "description": "数据源唯一 ID。用作更新、删除、详情接口的 `id`，以及工具调用接口的 `datasource_id`。"
           },
           "account_id": {
             "type": "integer",
             "format": "uint64",
-            "description": "账户 ID。"
+            "description": "数据源所属账户的 ID，恒为调用方所在账户。"
           },
           "type_ident": {
             "type": "string",
-            "description": "数据源类型标识。支持：`prometheus`, `loki`, `mysql`, `oracle`, `postgres`, `clickhouse`, `elasticsearch`, `sls`, `tencent_cls`, `victorialogs`, `redis_node`, `redis_sentinel`, `mongodb_mongod`, `mongodb_mongos`, `kafka`。"
+            "enum": [
+              "prometheus",
+              "loki",
+              "mysql",
+              "oracle",
+              "postgres",
+              "clickhouse",
+              "elasticsearch",
+              "sls",
+              "tencent_cls",
+              "victorialogs",
+              "redis_node",
+              "redis_sentinel",
+              "mongodb_mongod",
+              "mongodb_mongos",
+              "kafka"
+            ],
+            "description": "数据源类型。\n\n告警类（可用于告警规则评估）：\n- `prometheus`：兼容 Prometheus 的指标数据源。\n- `loki`：Grafana Loki 日志。\n- `mysql`：MySQL。\n- `oracle`：Oracle 数据库。\n- `postgres`：PostgreSQL。\n- `clickhouse`：ClickHouse。\n- `elasticsearch`：Elasticsearch。\n- `sls`：阿里云日志服务（SLS）。\n- `tencent_cls`：腾讯云日志服务（CLS）。\n- `victorialogs`：VictoriaLogs。\n\n仅诊断类（不能用于告警评估，`alerting_enabled` 恒为 `false`）：\n- `redis_node`：单个 Redis 节点。\n- `redis_sentinel`：Redis Sentinel。\n- `mongodb_mongod`：MongoDB mongod 实例。\n- `mongodb_mongos`：MongoDB mongos 路由。\n- `kafka`：Kafka 集群。\n\n存放类型专属配置的 `payload` 键与类型同名。"
           },
           "name": {
             "type": "string",
-            "description": "数据源显示名称。"
+            "description": "数据源名称，在账户内唯一（不区分类型）。"
           },
           "enabled": {
             "type": "boolean",
@@ -6880,11 +7057,11 @@
           },
           "note": {
             "type": "string",
-            "description": "可选描述。"
+            "description": "自由文本备注；未设置时为空字符串。"
           },
           "address": {
             "type": "string",
-            "description": "连接地址。Prometheus/Loki/VictoriaLogs 为 HTTP URL；MySQL/Oracle/Postgres/ClickHouse 为 `host:port`；SLS 为不含 http/https 前缀的 endpoint。 Redis/MongoDB 诊断类型使用单个 host:port（IPv6 加方括号），不接受 URI、userinfo 或查询参数。Kafka 使用 1–32 个不重复、逗号分隔的 host:port 引导地址；payload 不含 broker 列表。规范化后最多 4096 个字符。",
+            "description": "已保存的连接地址（已规范化）。格式取决于 `type_ident`，各类型格式见创建请求中的 `address` 字段。最长 4096 个字符。",
             "maxLength": 4096
           },
           "payload": {
@@ -6910,6 +7087,41 @@
           "alerting_enabled": {
             "description": "是否允许告警评估。告警同时要求 enabled=true 且类型支持告警。仅诊断类型固定为 false；false 不阻断非告警查询或工具。",
             "type": "boolean"
+          },
+          "manage_team_id": {
+            "type": [
+              "integer",
+              "null"
+            ],
+            "format": "uint64",
+            "description": "负责团队 ID。该团队成员可以编辑、删除、启停该数据源并查看其完整配置。`null` 表示未指定负责团队：任何拥有“数据源管理”权限的调用方都可管理。创建者、账户所有者和管理员始终可管理。"
+          },
+          "readonly_team_ids": {
+            "type": [
+              "array",
+              "null"
+            ],
+            "items": {
+              "type": "integer",
+              "format": "uint64"
+            },
+            "description": "允许查询和引用该数据源的团队 ID 列表（负责团队、创建者、账户所有者和管理员始终可查询）。`null` 或空数组表示账户内所有成员都可查询。"
+          },
+          "creator_id": {
+            "type": [
+              "integer",
+              "null"
+            ],
+            "format": "uint64",
+            "description": "创建该数据源的成员 ID；未记录时为 `null`。创建者始终可管理该数据源。"
+          },
+          "my_perm": {
+            "type": "string",
+            "enum": [
+              "manage",
+              "readonly"
+            ],
+            "description": "调用方对该数据源的权限级别，仅出现在列表响应中。\n- `manage`：可编辑、删除、启停、查看配置并查询。\n- `readonly`：只能查询和引用，不能修改或查看配置。"
           }
         }
       },
@@ -6919,20 +7131,41 @@
         "properties": {
           "type": {
             "type": "string",
-            "description": "数据源类型标识。省略时返回全部类型。支持：`prometheus`, `loki`, `mysql`, `oracle`, `postgres`, `clickhouse`, `elasticsearch`, `sls`, `tencent_cls`, `victorialogs`, `redis_node`, `redis_sentinel`, `mongodb_mongod`, `mongodb_mongos`, `kafka`。"
+            "description": "仅返回该类型的数据源；省略或留空返回所有类型。无法识别的值不匹配任何数据源，返回空数组。\n\n告警类（可用于告警规则评估）：\n- `prometheus`：兼容 Prometheus 的指标数据源。\n- `loki`：Grafana Loki 日志。\n- `mysql`：MySQL。\n- `oracle`：Oracle 数据库。\n- `postgres`：PostgreSQL。\n- `clickhouse`：ClickHouse。\n- `elasticsearch`：Elasticsearch。\n- `sls`：阿里云日志服务（SLS）。\n- `tencent_cls`：腾讯云日志服务（CLS）。\n- `victorialogs`：VictoriaLogs。\n\n仅诊断类（不能用于告警评估，`alerting_enabled` 恒为 `false`）：\n- `redis_node`：单个 Redis 节点。\n- `redis_sentinel`：Redis Sentinel。\n- `mongodb_mongod`：MongoDB mongod 实例。\n- `mongodb_mongos`：MongoDB mongos 路由。\n- `kafka`：Kafka 集群。",
+            "enum": [
+              "prometheus",
+              "loki",
+              "mysql",
+              "oracle",
+              "postgres",
+              "clickhouse",
+              "elasticsearch",
+              "sls",
+              "tencent_cls",
+              "victorialogs",
+              "redis_node",
+              "redis_sentinel",
+              "mongodb_mongod",
+              "mongodb_mongos",
+              "kafka"
+            ]
+          },
+          "name": {
+            "type": "string",
+            "description": "仅返回名称与该值完全相等的数据源（名称在账户内唯一，因此最多一条）。省略或留空表示不按名称过滤。"
           }
         }
       },
       "DataSourceListResponse": {
         "type": "array",
-        "description": "数据源列表。本接口不读取 payload 列，因此每项的 `payload` 均为 `null`。",
+        "description": "账户下调用方有权查询的数据源，按名称排序；没有匹配项时为空数组。列表不读取 `payload`，因此每项的 `payload` 均为 `null`；每项另带 `my_perm`。",
         "items": {
           "$ref": "#/components/schemas/DataSourceItem"
         }
       },
       "DataSourceUpsertRequest": {
         "type": "object",
-        "description": "创建或更新数据源的请求体。`id` 仅在更新时必填。`address` 除 Elasticsearch `deployment=cloud` 外均为必填。",
+        "description": "创建或更新数据源的请求体。`id` 仅更新时必填，创建时忽略。更新会用请求中的值整体替换 `type_ident`、`name`、`note`、`address`、`payload` 和 `edge_cluster_name`，因此必须全部重新发送；仅 `enabled`、`alerting_enabled`、`manage_team_id`、`readonly_team_ids` 在省略时保持原值。除 `deployment=cloud` 的 Elasticsearch 外，`address` 对所有类型必填。",
         "required": [
           "type_ident",
           "name",
@@ -6943,32 +7176,49 @@
           "id": {
             "type": "integer",
             "format": "uint64",
-            "description": "数据源 ID。更新时必填，创建时省略。"
+            "description": "数据源 ID。更新时必填（ID 不存在或属于其他账户时返回 `ResourceNotFound`）；创建时忽略。"
           },
           "type_ident": {
             "type": "string",
-            "description": "数据源类型标识。支持：`prometheus`, `loki`, `mysql`, `oracle`, `postgres`, `clickhouse`, `elasticsearch`, `sls`, `tencent_cls`, `victorialogs`, `redis_node`, `redis_sentinel`, `mongodb_mongod`, `mongodb_mongos`, `kafka`。"
+            "enum": [
+              "prometheus",
+              "loki",
+              "mysql",
+              "oracle",
+              "postgres",
+              "clickhouse",
+              "elasticsearch",
+              "sls",
+              "tencent_cls",
+              "victorialogs",
+              "redis_node",
+              "redis_sentinel",
+              "mongodb_mongod",
+              "mongodb_mongos",
+              "kafka"
+            ],
+            "description": "数据源类型。\n\n告警类（可用于告警规则评估）：\n- `prometheus`：兼容 Prometheus 的指标数据源。\n- `loki`：Grafana Loki 日志。\n- `mysql`：MySQL。\n- `oracle`：Oracle 数据库。\n- `postgres`：PostgreSQL。\n- `clickhouse`：ClickHouse。\n- `elasticsearch`：Elasticsearch。\n- `sls`：阿里云日志服务（SLS）。\n- `tencent_cls`：腾讯云日志服务（CLS）。\n- `victorialogs`：VictoriaLogs。\n\n仅诊断类（不能用于告警评估，`alerting_enabled` 恒为 `false`）：\n- `redis_node`：单个 Redis 节点。\n- `redis_sentinel`：Redis Sentinel。\n- `mongodb_mongod`：MongoDB mongod 实例。\n- `mongodb_mongos`：MongoDB mongos 路由。\n- `kafka`：Kafka 集群。\n\n存放类型专属配置的 `payload` 键与类型同名。"
           },
           "name": {
             "type": "string",
-            "description": "数据源显示名称，查询与诊断接口中的 `ds_name` 引用的就是这个名称。"
+            "description": "数据源名称；必填，在账户内唯一（不区分类型），即查询接口中的 `ds_name`。重名时返回 `InvalidParameter`。"
           },
           "note": {
             "type": "string",
-            "description": "可选描述。"
+            "description": "自由文本备注。更新时省略或传空字符串会清空已保存的备注。"
           },
           "address": {
             "type": "string",
-            "description": "连接地址。除 `elasticsearch` 的 `deployment: cloud` 部署外均为必填。Prometheus/Loki/VictoriaLogs 为 HTTP URL；MySQL/Oracle/Postgres/ClickHouse 为 `host:port`；SLS 为不含 `http(s)://` 前缀的 endpoint；`tencent_cls` 必须为 `cls.tencentcloudapi.com` 或 `cls.internal.tencentcloudapi.com`（要求 Monitors edge >= v0.66.0）。 Redis/MongoDB 诊断类型使用单个 host:port（IPv6 加方括号），不接受 URI、userinfo 或查询参数。Kafka 使用 1–32 个不重复、逗号分隔的 host:port 引导地址；payload 不含 broker 列表。规范化后最多 4096 个字符。",
+            "description": "连接地址；除 `deployment: cloud` 的 `elasticsearch` 外，所有类型都必填。规范化后最长 4096 个字符。各类型格式：\n- `prometheus`、`loki`、`victorialogs`：HTTP URL；不以 `http` 开头时自动补 `http://`。\n- `mysql`、`oracle`、`postgres`：`host:port`。\n- `clickhouse`：一个或多个以逗号分隔的 `host:port`，重复地址会被拒绝。\n- `self-managed` 的 `elasticsearch`：一个或多个以逗号分隔的 HTTP(S) URL（缺省协议为 `http://`），各 URL 的查询参数必须一致，重复地址会被拒绝；`cloud` 部署无需填写。\n- `sls`：不带 `http://` 或 `https://` 前缀的 endpoint。\n- `tencent_cls`：只能是 `cls.tencentcloudapi.com` 或 `cls.internal.tencentcloudapi.com`（要求 Monitors edge >= v0.66.0）。\n- `redis_node`、`redis_sentinel`、`mongodb_mongod`、`mongodb_mongos`：单个 `host:port`（IPv6 须加方括号），不能含 URI、用户信息或查询串。\n- `kafka`：1-32 个互不重复、以逗号分隔的 `host:port` 引导地址（payload 中没有 broker 列表）。",
             "maxLength": 4096
           },
           "payload": {
             "$ref": "#/components/schemas/DSPayload",
-            "description": "类型相关配置块，必须包含与 `type_ident` 匹配的键。 诊断类型的 password 和 Kafka tls_key 在响应中省略，${env:...} 引用除外；更新时省略保留已保存的秘密，显式空字符串清除。其他配置字段保持原有行为。"
+            "description": "类型专属配置块，必须包含与 `type_ident` 同名的键。更新会整体替换 payload，需要保留的配置（包括非诊断类型的凭据，可通过详情接口读取）都要重新发送。例外：诊断类型省略密码（以及 Kafka 的 `tls_key`）表示保留已保存的值，传空字符串表示清除；`tencent_cls` 省略或传空的 `secret_key` 表示保留已保存的密钥。修改 `type_ident` 时不会沿用已保存的密钥。"
           },
           "edge_cluster_name": {
             "type": "string",
-            "description": "负责使用该数据源评估规则的 Monitors Edge 集群名称。"
+            "description": "负责评估规则和执行查询的 Monitors edge 集群名称，必须是账户下已存在的 edge 集群，否则返回 `InvalidParameter`。更新时修改该值会关闭使用此数据源的规则上的未恢复告警。"
           },
           "enabled": {
             "type": "boolean",
@@ -6979,6 +7229,27 @@
             "description": "是否允许数据源用于告警。创建时省略：支持告警的类型默认为 true，仅诊断类型默认为 false；更新时省略保留当前值。null 非法。redis_node、redis_sentinel、mongodb_mongod、mongodb_mongos 和 kafka 不允许 true。有启用规则引用时，关闭用途返回冲突。",
             "type": "boolean",
             "x-flashduty-preserve-absence": true
+          },
+          "manage_team_id": {
+            "type": [
+              "integer",
+              "null"
+            ],
+            "format": "uint64",
+            "description": "负责团队 ID（含义见响应中的同名字段）。创建时省略表示不指定负责团队；更新时省略保持原值，传 `null` 或 `0` 表示清除。`readonly_team_ids` 非空时必须填写。",
+            "x-flashduty-preserve-absence": true
+          },
+          "readonly_team_ids": {
+            "type": [
+              "array",
+              "null"
+            ],
+            "items": {
+              "type": "integer",
+              "format": "uint64"
+            },
+            "description": "允许查询和引用该数据源的团队 ID 列表（含义见响应中的同名字段）。创建时省略表示不限制；更新时省略保持原值，传 `null` 或空数组表示清除（所有人可查询）。重复值和 `0` 会被去掉。依赖 `manage_team_id`：列表非空而未指定负责团队时返回 `InvalidParameter`。",
+            "x-flashduty-preserve-absence": true
           }
         }
       },
@@ -6991,7 +7262,7 @@
           },
           "message": {
             "type": "string",
-            "description": "用户可读的错误描述，语言会跟随调用方的 Accept-Language。可能包含字段名、ID 等请求上下文。",
+            "description": "按响应语言（query 参数 `locale` / `lang` 或请求头 `Accept-Language`）返回的错误描述，可能包含出错的字段名，请不要解析它。",
             "example": "The specified parameter template_id is not valid."
           },
           "reason": {
@@ -7007,7 +7278,7 @@
       },
       "EmptyResponse": {
         "type": "object",
-        "description": "空响应体。成功时服务端返回 `data: null`。",
+        "description": "无返回数据。不同接口的 `data` 可能是 `{}`，也可能不出现在响应中；请只根据 HTTP 200 且没有 `error` 判断成功。",
         "properties": {}
       },
       "EnabledTime": {
@@ -7019,21 +7290,21 @@
             "items": {
               "type": "integer"
             },
-            "description": "星期几，0 = 周日。"
+            "description": "时间窗口适用的星期，`0` = 周日至 `6` = 周六；不能为空，不能重复。"
           },
           "stime": {
             "type": "string",
-            "description": "起始时间，如 `09:00`。"
+            "description": "开始时间，24 小时制 `HH:MM` 格式，如 `09:00`。"
           },
           "etime": {
             "type": "string",
-            "description": "结束时间，如 `18:00`。"
+            "description": "结束时间，24 小时制 `HH:MM` 格式，如 `18:00`。"
           }
         }
       },
       "ErrorCode": {
         "type": "string",
-        "description": "Flashduty 错误码枚举。每个失败响应的 `error.code` 都是下列稳定值之一，HTTP 状态码仅作参考。\n\n| 错误码 | HTTP | 含义 |\n|---|---|---|\n| `OK` | 200 | 保留值，正常错误响应不会返回。 |\n| `InvalidParameter` | 400 | 必填参数缺失或未通过校验。 |\n| `BadRequest` | 400 | 通用的 400 错误，通常是请求本身不合法。 |\n| `InvalidContentType` | 400 | 请求头 `Content-Type` 不是 `application/json`。 |\n| `ResourceNotFound` | 400 | 目标资源不存在。注意 HTTP 状态码是 400 而非 404（历史设计）。 |\n| `NoLicense` | 400 | 功能需要有效授权，但未找到可用的 license。 |\n| `ReferenceExist` | 400 | 该资源仍被其他实体引用，无法删除。 |\n| `Unauthorized` | 401 | `app_key` 缺失、无效或已过期。 |\n| `BalanceNotEnough` | 402 | 账户余额不足，无法执行需要计费的操作。 |\n| `AccessDenied` | 403 | 身份认证通过，但 RBAC 权限不足以执行该操作。 |\n| `RouteNotFound` | 404 | 请求的 URL 路径不是已知路由。 |\n| `MethodNotAllowed` | 405 | 当前路径不接受所使用的 HTTP 方法。 |\n| `UndonedOrderExist` | 409 | 账户存在未完成的订单，请稍后重试。 |\n| `RequestLocked` | 423 | 因连续失败被临时锁定。 |\n| `EntityTooLarge` | 413 | 请求体超过允许的最大长度。 |\n| `RequestTooFrequently` | 429 | 命中限流（全局、账户级或集成级）。 |\n| `RequestVerifyRequired` | 428 | 操作需要二次验证码，但未提供。 |\n| `DangerousOperation` | 428 | 危险操作，需要进行 MFA 验证。 |\n| `InternalError` | 500 | 服务端未预期错误。反馈问题请附上 `request_id`。 |\n| `ServiceUnavailable` | 503 | 后端依赖不可用，请稍后重试。 |",
+        "description": "错误码。所有失败响应都会把 `error.code` 设为下列稳定字符串之一，请以它而不是 HTTP 状态码做判断。\n\n| 错误码 | HTTP | 含义 |\n|---|---|---|\n| `OK` | 200 | 保留值，失败的请求不会返回。 |\n| `InvalidParameter` | 400 | 参数缺失、类型错误或未通过校验，`message` 通常会指出字段名。 |\n| `BadRequest` | 400 | 请求违反业务规则或与对象当前状态冲突，`message` 会说明原因。 |\n| `InvalidContentType` | 400 | 请求体没有以 `application/json` 发送。 |\n| `ResourceNotFound` | 400 | 引用的对象在本账户中不存在或已删除。注意 HTTP 状态码是 400 而不是 404。 |\n| `NoLicense` | 400 | 账户套餐不包含该功能、套餐配额已用完、套餐已过期或额度不足。 |\n| `ReferenceExist` | 400 | 对象仍被其他对象引用，无法删除。 |\n| `Unauthorized` | 401 | APP Key 缺失、无效或已删除。 |\n| `BalanceNotEnough` | 402 | 仅用于控制台计费流程，Open API 接口不会返回。 |\n| `AccessDenied` | 403 | APP Key 的权限范围或创建者角色不允许该操作或该对象。 |\n| `RouteNotFound` | 404 | 没有与该 HTTP 方法和路径匹配的接口。 |\n| `MethodNotAllowed` | 405 | 路径存在，但不支持该 HTTP 方法。 |\n| `UndonedOrderExist` | 409 | 仅用于控制台计费流程，Open API 接口不会返回。 |\n| `EntityTooLarge` | 413 | 请求体超出大小限制。 |\n| `RequestLocked` | 423 | 仅用于控制台登录保护，Open API 接口不会返回。 |\n| `RequestVerifyRequired` | 428 | 仅用于控制台验证码流程，Open API 接口不会返回。 |\n| `DangerousOperation` | 428 | 仅用于控制台高风险操作的 MFA 校验，Open API 接口不会返回。 |\n| `RequestTooFrequently` | 429 | 触发频率限制；请等待响应头 `Flashcat-Request-Rate-Limit-Delay` 给出的秒数后再重试。 |\n| `InternalError` | 500 | 服务端意外错误；请退避后重试，反馈问题时附上 `request_id`。 |\n| `ServiceUnavailable` | 503 | 后端依赖过载或不可用，请退避后重试。 |",
         "enum": [
           "OK",
           "InvalidParameter",
@@ -7048,35 +7319,35 @@
           "RouteNotFound",
           "MethodNotAllowed",
           "UndonedOrderExist",
-          "RequestLocked",
           "EntityTooLarge",
-          "RequestTooFrequently",
+          "RequestLocked",
           "RequestVerifyRequired",
           "DangerousOperation",
+          "RequestTooFrequently",
           "InternalError",
           "ServiceUnavailable"
         ],
         "x-enumDescriptions": {
-          "OK": "保留值，正常错误响应不会返回。",
-          "InvalidParameter": "必填参数缺失或未通过校验。",
-          "BadRequest": "通用的 400 错误，通常是请求本身不合法。",
-          "InvalidContentType": "请求头 `Content-Type` 不是 `application/json`。",
-          "ResourceNotFound": "目标资源不存在。注意 HTTP 状态码是 400 而非 404（历史设计）。",
-          "NoLicense": "功能需要有效授权，但未找到可用的 license。",
-          "ReferenceExist": "该资源仍被其他实体引用，无法删除。",
-          "Unauthorized": "`app_key` 缺失、无效或已过期。",
-          "BalanceNotEnough": "账户余额不足，无法执行需要计费的操作。",
-          "AccessDenied": "身份认证通过，但 RBAC 权限不足以执行该操作。",
-          "RouteNotFound": "请求的 URL 路径不是已知路由。",
-          "MethodNotAllowed": "当前路径不接受所使用的 HTTP 方法。",
-          "UndonedOrderExist": "账户存在未完成的订单，请稍后重试。",
-          "RequestLocked": "因连续失败被临时锁定。",
-          "EntityTooLarge": "请求体超过允许的最大长度。",
-          "RequestTooFrequently": "命中限流（全局、账户级或集成级）。",
-          "RequestVerifyRequired": "操作需要二次验证码，但未提供。",
-          "DangerousOperation": "危险操作，需要进行 MFA 验证。",
-          "InternalError": "服务端未预期错误。反馈问题请附上 `request_id`。",
-          "ServiceUnavailable": "后端依赖不可用，请稍后重试。"
+          "OK": "保留值，失败的请求不会返回。",
+          "InvalidParameter": "参数缺失、类型错误或未通过校验，`message` 通常会指出字段名。",
+          "BadRequest": "请求违反业务规则或与对象当前状态冲突，`message` 会说明原因。",
+          "InvalidContentType": "请求体没有以 `application/json` 发送。",
+          "ResourceNotFound": "引用的对象在本账户中不存在或已删除。注意 HTTP 状态码是 400 而不是 404。",
+          "NoLicense": "账户套餐不包含该功能、套餐配额已用完、套餐已过期或额度不足。",
+          "ReferenceExist": "对象仍被其他对象引用，无法删除。",
+          "Unauthorized": "APP Key 缺失、无效或已删除。",
+          "BalanceNotEnough": "仅用于控制台计费流程，Open API 接口不会返回。",
+          "AccessDenied": "APP Key 的权限范围或创建者角色不允许该操作或该对象。",
+          "RouteNotFound": "没有与该 HTTP 方法和路径匹配的接口。",
+          "MethodNotAllowed": "路径存在，但不支持该 HTTP 方法。",
+          "UndonedOrderExist": "仅用于控制台计费流程，Open API 接口不会返回。",
+          "EntityTooLarge": "请求体超出大小限制。",
+          "RequestLocked": "仅用于控制台登录保护，Open API 接口不会返回。",
+          "RequestVerifyRequired": "仅用于控制台验证码流程，Open API 接口不会返回。",
+          "DangerousOperation": "仅用于控制台高风险操作的 MFA 校验，Open API 接口不会返回。",
+          "RequestTooFrequently": "触发频率限制；请等待响应头 `Flashcat-Request-Rate-Limit-Delay` 给出的秒数后再重试。",
+          "InternalError": "服务端意外错误；请退避后重试，反馈问题时附上 `request_id`。",
+          "ServiceUnavailable": "后端依赖过载或不可用，请退避后重试。"
         },
         "example": "InvalidParameter"
       },
@@ -7122,11 +7393,11 @@
         "properties": {
           "name": {
             "type": "string",
-            "description": "规则名称。"
+            "description": "该结果对应的规则名称；规则 ID 不存在时为 `id: <id>`。"
           },
           "message": {
             "type": "string",
-            "description": "成功时为空，失败时为错误信息。"
+            "description": "该规则的处理结果。成功时，`/monit/rule/update/fields` 返回空字符串，`/monit/rule/move` 返回本地化的成功文案（`Move successfully` / `移动成功`）；失败时为错误信息。"
           }
         }
       },
@@ -7424,7 +7695,7 @@
               "type": "integer",
               "format": "uint64"
             },
-            "description": "要更新的规则 ID 列表。"
+            "description": "要更新的规则 ID 列表，至少包含一个 ID。"
           },
           "fields": {
             "type": "array",
@@ -7448,18 +7719,18 @@
                 "repeat_total"
               ]
             },
-            "description": "要更新的字段名列表。只有列出的字段会被更新，新值从同名请求字段读取；未列出的字段即使传值也会被忽略。"
+            "description": "要更新的字段名列表。每个列出的字段取同名请求字段的值，未传值时设为零值；未列出的字段即使传值也会被忽略。出现未知字段名时整个调用返回 `InvalidParameter`。"
           },
           "labels": {
             "type": "object",
             "additionalProperties": {
               "type": "string"
             },
-            "description": "自定义标签键值对，整体替换现有标签。仅当 `fields` 包含 `labels` 时生效。"
+            "description": "自定义标签键值对，整体替换现有标签。仅当 `fields` 包含 `labels` 时生效；不能与 `labels_patch` 同时传入。"
           },
           "ds_type": {
             "type": "string",
-            "description": "数据源类型标识。仅当 `fields` 包含 `ds_type` 时生效。"
+            "description": "数据源类型标识。启用的规则必须使用支持告警的类型：`prometheus`、`elasticsearch`、`loki`、`clickhouse`、`mysql`、`oracle`、`postgres`、`sls`、`tencent_cls`、`victorialogs`。仅当 `fields` 包含 `ds_type` 时生效。"
           },
           "ds_list": {
             "type": "array",
@@ -7490,7 +7761,7 @@
           },
           "timezone": {
             "type": "string",
-            "description": "告警规则执行时区，IANA 时区名，默认 `Asia/Shanghai`。",
+            "description": "规则执行时区，取 IANA 时区名（如 `Asia/Shanghai`、`UTC`）；为空时按 `Asia/Shanghai` 处理。仅当 `fields` 包含 `timezone` 时生效。",
             "default": "Asia/Shanghai"
           },
           "delay_seconds": {
@@ -7509,11 +7780,11 @@
             "additionalProperties": {
               "type": "string"
             },
-            "description": "附加注解键值对，随告警事件下发；键不允许以 `$` 开头（该前缀保留给查询字段）。仅当 `fields` 包含 `annotations` 时生效。"
+            "description": "随告警事件下发的注解键值对，整体替换现有注解，键不允许以 `$` 开头（该前缀保留给查询字段）。仅当 `fields` 包含 `annotations` 时生效；不能与 `annotations_patch` 同时传入。"
           },
           "description": {
             "type": "string",
-            "description": "规则描述（Markdown）。仅当 `fields` 包含 `description` 时生效。"
+            "description": "规则描述，按规则现有的 `description_type` 渲染（本接口无法修改该格式）。仅当 `fields` 包含 `description` 时生效。"
           },
           "channel_ids": {
             "type": "array",
@@ -7526,20 +7797,20 @@
           "repeat_interval": {
             "type": "integer",
             "format": "int64",
-            "description": "告警通知重复间隔（秒）。仅当 `fields` 包含 `repeat_interval` 时生效。"
+            "description": "告警通知重复间隔（秒）；小于 1 时按 3600 处理，最大 2147483647。仅当 `fields` 包含 `repeat_interval` 时生效。"
           },
           "repeat_total": {
             "type": "integer",
             "format": "int64",
-            "description": "最大重复通知次数。仅当 `fields` 包含 `repeat_total` 时生效。"
+            "description": "最大重复通知次数；小于 1 时按 3 处理，最大 2147483647。仅当 `fields` 包含 `repeat_total` 时生效。"
           },
           "labels_patch": {
             "$ref": "#/components/schemas/StringMapPatch",
-            "description": "标签的增量更新，仅在 `fields` 包含 `labels` 时生效；与 `labels` 同时发送时优先使用本字段。"
+            "description": "标签的增量更新，未提及的标签保持不变。要求 `fields` 包含 `labels`，且不能与 `labels` 同时传入，否则返回 `InvalidParameter`。"
           },
           "annotations_patch": {
             "$ref": "#/components/schemas/StringMapPatch",
-            "description": "注解的增量更新，仅在 `fields` 包含 `annotations` 时生效；与 `annotations` 同时发送时优先使用本字段。"
+            "description": "注解的增量更新，未提及的注解保持不变。要求 `fields` 包含 `annotations`，且不能与 `annotations` 同时传入，否则返回 `InvalidParameter`。"
           }
         }
       },
@@ -7565,7 +7836,7 @@
           "id": {
             "type": "integer",
             "format": "uint64",
-            "description": "审计记录 ID——来自 `POST /monit/rule/audits` 返回行的 `id`，不是规则 ID。传规则 ID 会返回 HTTP 400。"
+            "description": "审计记录 ID——来自 `POST /monit/rule/audits` 返回行的 `id`，不是规则 ID。传入规则 ID 时会被当作审计记录 ID 查询，通常返回 `InvalidParameter`（`alert rule audit not found`）或一条不相关的记录。"
           }
         }
       },
@@ -7581,7 +7852,7 @@
               "type": "integer",
               "format": "uint64"
             },
-            "description": "规则 ID 列表。"
+            "description": "要删除的告警规则 ID 列表，至少包含一个 ID，可通过 `POST /monit/rule/list/basic` 获取。"
           }
         }
       },
@@ -7606,15 +7877,15 @@
           "folder_id": {
             "type": "integer",
             "format": "uint64",
-            "description": "文件夹 ID，必须是已存在的文件夹；传 `0` 会返回 `folder_not_found` 错误。"
+            "description": "要列出的文件夹 ID，必须是调用者有管理权限的已存在文件夹；传 `0` 或不存在的 ID 返回 `InvalidParameter`。"
           },
           "include_descendants": {
             "type": "boolean",
-            "description": "是否同时包含所有子孙文件夹中的规则。为 `true` 时返回的每项仅包含 `id`、`folder_id`、`name` 三个字段；配合 `query` / `limit` 用于规则选择器场景。"
+            "description": "是否同时搜索所有子孙文件夹。为 `true` 时结果按名称排序、受 `limit` 限制，且每项只填充 `id`、`folder_id`、`name`（其余字段为零值）；可配合 `query` 用于规则选择器场景。"
           },
           "query": {
             "type": "string",
-            "description": "规则名模糊过滤，仅在 `include_descendants` 为 `true` 时生效。"
+            "description": "按规则名称子串过滤；纯数字时还会匹配该 ID 的规则。仅在 `include_descendants` 为 `true` 时生效。"
           },
           "limit": {
             "type": "integer",
@@ -7637,12 +7908,12 @@
               "type": "integer",
               "format": "uint64"
             },
-            "description": "要移动的规则 ID 列表。"
+            "description": "要移动的规则 ID 列表，至少包含一个 ID。"
           },
           "dest_folder_id": {
             "type": "integer",
             "format": "uint64",
-            "description": "目标文件夹 ID，可通过 `POST /monit/folder/list` 获取。"
+            "description": "目标文件夹 ID，可通过 `POST /monit/folder/list` 获取。不能为 0；文件夹不存在或调用者对其无管理权限时，整个调用返回 `AccessDenied`。"
           }
         }
       },
@@ -7748,16 +8019,15 @@
             "example": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
           },
           "data": {
-            "description": "每个接口自己的业务 payload，详见各接口的 200 响应 schema。"
+            "description": "接口返回的数据，格式见各接口的 200 响应。没有返回数据的接口会返回 `{}` 或完全不带 `data`。"
           }
         },
         "required": [
-          "request_id",
-          "data"
+          "request_id"
         ]
       },
       "QueryDataRequest": {
-        "description": "稳定结构化查询接口的请求。字段与已下线的 rows 接口一致。",
+        "description": "结构化查询接口的请求体。",
         "allOf": [
           {
             "$ref": "#/components/schemas/QueryRowsRequest"
@@ -7999,33 +8269,49 @@
           "account_id": {
             "type": "integer",
             "format": "int64",
-            "description": "可选的一致性校验。若提供,必须等于已认证账户;不一致将被拒绝。业务执行始终使用已认证账户。"
+            "description": "可选的一致性校验。若提供，必须等于已认证账户，否则请求以 `AccessDenied` 失败。查询始终以已认证账户执行。"
           },
           "ds_type": {
             "type": "string",
-            "description": "数据源类型;必须匹配租户下已配置的数据源。示例:`prometheus`、`loki`、`victorialogs`、`sls`、`elasticsearch`、`mysql`、`postgres`、`oracle`、`clickhouse`。"
+            "description": "数据源类型，需要与 `ds_name` 一起匹配账户下一个已启用的数据源。\n\n- `prometheus`：Prometheus 兼容数据源，`expr` 为 PromQL。\n- `loki`：Grafana Loki，`expr` 为 LogQL。\n- `victorialogs`：VictoriaLogs。\n- `sls`：阿里云日志服务（SLS）。\n- `tencent_cls`：腾讯云日志服务（CLS），需要 monit-edge v0.66.0 或更高版本。\n- `elasticsearch`：Elasticsearch。\n- `mysql`：MySQL，`expr` 为 SQL。\n- `postgres`：PostgreSQL，`expr` 为 SQL。\n- `oracle`：Oracle 数据库，`expr` 为 SQL。\n- `clickhouse`：ClickHouse，`expr` 为 SQL。\n\n其他数据源类型（例如 MongoDB、Redis、Kafka）会被拒绝。",
+            "enum": [
+              "clickhouse",
+              "elasticsearch",
+              "loki",
+              "mysql",
+              "oracle",
+              "postgres",
+              "prometheus",
+              "sls",
+              "tencent_cls",
+              "victorialogs"
+            ]
           },
           "ds_name": {
             "type": "string",
-            "description": "数据源名称;必须匹配租户下已配置的数据源。"
+            "description": "数据源名称，可从 `/monit/datasource/list` 获取。数据源必须已启用；账户下不存在该名称的数据源时返回 HTTP 400。"
           },
           "expr": {
             "type": "string",
-            "description": "查询表达式。语法取决于 `ds_type`,由对应的 monit-edge 客户端解释(Prometheus 用 PromQL,Loki 用 LogQL,SQL 类数据源用 SQL,等等)。"
+            "description": "使用 `ds_type` 对应查询语言的表达式（`prometheus` 为 PromQL，`loki` 为 LogQL，SQL 类数据源为 SQL，等等）。必填，最大 64 KiB（`tencent_cls` 为 12 KiB）。此接口不支持 Loki 的 `$__auto`，请使用固定时长，例如 `[5m]`。Prometheus 表达式在下发前会做语法检查。",
+            "minLength": 1
           },
           "delay_seconds": {
             "type": "integer",
-            "description": "应用于点查询(Prometheus、Loki stats、VictoriaLogs stats)的回看偏移,单位秒。明细 / raw 查询忽略该字段。",
-            "default": 0
+            "description": "回看偏移，单位秒，取值 0 到 86400。应用于点查询（Prometheus、Loki stats、VictoriaLogs stats）；明细 / raw 查询忽略该字段。当 `args` 带有绝对时间 `<source>.time` 且 Edge 为 v0.74.0 或更高版本时，以绝对时间为准，不再应用此偏移。",
+            "default": 0,
+            "minimum": 0,
+            "maximum": 86400
           },
           "args": {
             "type": "object",
-            "description": "透传给 monit-edge 的多态键值扩展参数。所有值必须是字符串，键一律按数据源加前缀（如 `sls.project`、`loki.type`）。校验规则取决于 `ds_type`：SLS 必须提供 `sls.project` 与 `sls.logstore`；Elasticsearch 的 `es.type` 只接受 `sql` 或不传，其他值一律拒绝；Loki 与 VictoriaLogs 的 `<source>.type` 接受 `stats`、`raw` 或不传，其中 `raw` 还必须给出时间范围——`<source>.start` + `<source>.end`，或 `<source>.timespan.value` + `<source>.timespan.unit`（单位取 `s`/`m`/`h`/`d`）。Prometheus 及其余 SQL 类数据源完全忽略 `args`。",
+            "description": "额外的查询参数，字符串键值对；键按数据源加前缀（例如 `sls.project`、`loki.type`）。最多 128 项，键最长 256 字节，值最长 64 KiB，总计不超过 128 KiB。可接受的参数取决于 `ds_type`：\n\n- `prometheus`：可选 `prometheus.time`，评估时间，Unix 秒，不能晚于当前时间。\n- `loki`、`victorialogs`：`<source>.type` 取 `stats`（默认）或 `raw`。`stats` 可带 `<source>.time`（Unix 秒，不能晚于当前时间）。`raw` 必须给出时间范围，可用 `<source>.start` + `<source>.end`（Unix 秒），或 `<source>.timespan.value` + `<source>.timespan.unit`（`s`、`m`、`h` 或 `d`），跨度不超过 6 小时，并可带 `<source>.limit`，取值 1 到 1001。\n- `sls`：必须提供 `sls.project` 和 `sls.logstore`。可选 `sls.lines`（1 到 100）、`sls.offset`（0 或更大），以及不超过 6 小时的时间范围，可用 `sls.from` + `sls.to`（Unix 秒）或 `sls.timespan.value` + `sls.timespan.unit` 给出。\n- `tencent_cls`：必须提供 `tencent_cls.region`、`tencent_cls.topic_id`、`tencent_cls.query_mode`（`raw` 或 `analysis`）和 `tencent_cls.syntax`（`cql` 或 `lucene`）。可选 `tencent_cls.limit`（1 到 100，仅 `raw` 模式，需要 monit-edge v0.67.0 或更高版本），以及时间范围，可用 `tencent_cls.from` + `tencent_cls.to`（Unix 秒）或 `tencent_cls.timespan.value` + `tencent_cls.timespan.unit` 给出，`raw` 模式不超过 6 小时，`analysis` 模式不超过 24 小时。其他任何键都会被拒绝。\n- `elasticsearch`：`es.type` 只能为 `sql` 或不传，其他值会被拒绝。\n- `mysql`、`postgres`、`oracle`、`clickhouse`：未定义任何参数。\n\n绝对时间 `<source>.time` 只对其对应的数据源类型有效。v0.74.0 之前的 Edge 通过回看偏移近似实现，且只接受最近 86,400 秒内的时间。",
             "additionalProperties": {
               "type": "string"
             }
           }
-        }
+        },
+        "description": "要执行的查询。`ds_type` 与 `ds_name` 共同选定数据源；`expr` 与 `args` 由该类型的数据源解释。"
       },
       "DSTencentCLSConfig": {
         "type": "object",
@@ -8101,7 +8387,7 @@
       },
       "StringMapPatch": {
         "type": "object",
-        "description": "map 字段的增量更新：`set` 中的键会被插入或覆盖，`delete` 中的键会被删除，其余键保持不变。",
+        "description": "map 字段的增量更新：`set` 中的键会被插入或覆盖，`delete` 中的键会被删除，其余键保持不变。`set` / `delete` 至少一个非空，键不能为空白，同一个键不能同时出现在两者中，也不能在 `delete` 中重复。",
         "properties": {
           "set": {
             "type": "object",
@@ -8123,7 +8409,7 @@
         "description": "诊断数据源连接配置。",
         "properties": {
           "password": {
-            "description": "认证密码，支持 ${env:NAME}。更新时省略保留；显式空字符串清除。响应中省略字面密码。",
+            "description": "认证密码，支持 ${env:NAME}。使用 SASL 认证时须与 `username` 一起提供，`sasl_mechanism` 为 `none` 时必须为空。更新时省略表示保留已保存的密码，显式传空字符串表示清除。响应中不返回明文密码。",
             "type": "string",
             "x-flashduty-preserve-absence": true
           },
@@ -8155,7 +8441,7 @@
           },
           "tls_enabled": {
             "default": false,
-            "description": "是否启用 TLS，默认为 false。",
+            "description": "是否启用 TLS，默认 false。为 false 时保存时会清空所有 `tls_*` 字段。",
             "type": "boolean"
           },
           "tls_key": {
@@ -8180,7 +8466,7 @@
             "type": "boolean"
           },
           "username": {
-            "description": "认证用户名，支持 ${env:NAME} 引用。",
+            "description": "认证用户名，支持 ${env:NAME} 引用。`sasl_mechanism` 为 `plain`、`scram-sha-256` 或 `scram-sha-512` 时必填，为 `none` 时必须为空。",
             "type": "string"
           }
         },
@@ -8212,7 +8498,7 @@
           },
           "tls_enabled": {
             "default": false,
-            "description": "是否启用 TLS，默认为 false。",
+            "description": "是否启用 TLS，默认 false。为 false 时保存时会清空所有 `tls_*` 字段。",
             "type": "boolean"
           },
           "tls_max_version": {
@@ -8232,7 +8518,7 @@
             "type": "boolean"
           },
           "username": {
-            "description": "认证用户名，支持 ${env:NAME} 引用。",
+            "description": "认证用户名，支持 ${env:NAME} 引用。须与 `password` 一起提供。",
             "type": "string"
           }
         },
@@ -8260,7 +8546,7 @@
             "type": "integer"
           },
           "username": {
-            "description": "认证用户名，支持 ${env:NAME} 引用。",
+            "description": "认证用户名，支持 ${env:NAME} 引用。设置后必须同时提供 `password`（更新时省略 `password` 表示保留已保存的密码）。",
             "type": "string"
           }
         },
@@ -8282,7 +8568,7 @@
             "type": "integer"
           },
           "username": {
-            "description": "认证用户名，支持 ${env:NAME} 引用。",
+            "description": "认证用户名，支持 ${env:NAME} 引用。设置后必须同时提供 `password`（更新时省略 `password` 表示保留已保存的密码）。",
             "type": "string"
           }
         },
@@ -8608,7 +8894,7 @@
             "type": "integer"
           },
           "datasource_id": {
-            "description": "通过 /monit/datasource/list 获取的数据源 ID。",
+            "description": "要执行工具的数据源 ID，可从 `/monit/datasource/list` 获取。调用方需要拥有该数据源的查询权限。查询工具（`<type>.query`）的 ID 不能超过 9007199254740991。",
             "format": "uint64",
             "minimum": 1,
             "type": "integer"
@@ -8671,7 +8957,7 @@
       "DatasourceToolTruncation": {
         "properties": {
           "reason": {
-            "description": "结果截断原因；该对象存在即表示发生截断。",
+            "description": "结果被截断的原因，由执行端 Edge 给出，请当作不透明字符串处理。仅当结果被截断时才返回该对象。",
             "type": "string"
           }
         },
@@ -8695,12 +8981,12 @@
             "format": "int64",
             "minimum": 1,
             "maximum": 9007199254740991,
-            "description": "数据源 ID，来自 `/monit/datasource/list`。必须是正数且不超过 JavaScript 安全整数范围，且属于当前账户。"
+            "description": "来自 `/monit/datasource/list` 的数据源 ID。必须是正的 JavaScript 安全整数，对应已认证账户下已启用、且调用方有权查询的数据源。"
           },
           "expr": {
             "type": "string",
             "minLength": 1,
-            "description": "使用数据源原生语言的查询表达式（如 PromQL、LogsQL、SQL 等）。非空 UTF-8 字符串，最长 64 KiB；部分数据源类型限制更小。"
+            "description": "使用数据源原生语言的查询表达式（PromQL、LogsQL、SQL 等）。非空 UTF-8，最大 64 KiB；`mysql` 最大 16 KiB，`tencent_cls` 最大 12 KiB。"
           },
           "args": {
             "type": "object",
@@ -8717,7 +9003,7 @@
       },
       "QueryExploreExecution": {
         "type": "object",
-        "description": "查询的时间语义。可接受的配套字段取决于 `kind`：`instant` 只需 `to_ms`（`from_ms` 可选），`range` 需要 `from_ms`、`to_ms` 和 `max_data_points`，`window` 需要 `from_ms` 和 `to_ms`。HTTP 接口不接受 `step_seconds`。",
+        "description": "查询的时间语义。可接受的配套字段取决于 `kind`：`instant` 使用 `to_ms`（可选 `from_ms`），`range` 需要 `from_ms`、`to_ms` 和 `max_data_points`，`window` 只使用 `from_ms` 与 `to_ms`。同时给出两个时间时，`from_ms` 必须小于 `to_ms`。HTTP 接口不接受 `step_seconds`。",
         "required": [
           "kind"
         ],
@@ -8729,17 +9015,19 @@
               "range",
               "window"
             ],
-            "description": "执行类型。`instant` 在单个时间点取值，`range` 在时间范围内取序列，`window` 返回时间窗口内的原始行。"
+            "description": "执行类型。\n\n- `instant`：在单个时间点上求值。\n- `range`：在 `from_ms` 到 `to_ms` 范围内求时间序列，步长由 `max_data_points` 与 `min_step_seconds` 推导。\n- `window`：查询 `from_ms` 到 `to_ms` 之间的区间，不带步长。"
           },
           "from_ms": {
             "type": "integer",
             "format": "int64",
-            "description": "范围起点的 Unix 毫秒时间戳。`range` 和 `window` 必填，`instant` 可选。"
+            "description": "区间起点，Unix 时间戳，单位毫秒；非负且小于 `to_ms`。`range` 与 `window` 必填，`instant` 可选。",
+            "minimum": 0
           },
           "to_ms": {
             "type": "integer",
             "format": "int64",
-            "description": "范围终点的 Unix 毫秒时间戳。所有执行类型均必填。"
+            "description": "区间终点（`instant` 时为求值时间），Unix 时间戳，单位毫秒；非负。所有执行类型都必填。",
+            "minimum": 0
           },
           "max_data_points": {
             "type": "integer",
@@ -8800,7 +9088,7 @@
             "items": {
               "$ref": "#/components/schemas/ExploreFrame"
             },
-            "description": "列式 Frame 列表，`kind` 为 `frames` 时出现，最多 1,000 个。"
+            "description": "列式 frame。`kind` 为 `frames` 时返回；最多 1,000 个 frame，表格行合计最多 1,000 行，值合计最多 100,000 个。"
           },
           "samples": {
             "type": "array",
@@ -8818,7 +9106,7 @@
           },
           "applied_limit": {
             "type": "integer",
-            "description": "日志结果实际生效的条数上限，最大 1000。"
+            "description": "logs 结果实际应用的条数上限：1 到 1000（`sls` 数据源为 1 到 100）。仅在 `kind` 为 `logs` 时返回。"
           },
           "has_more": {
             "type": "boolean",
@@ -8840,7 +9128,7 @@
               "table",
               "time_series"
             ],
-            "description": "Frame 形态。`table` 为无标签表格，`time_series` 恰好包含一个时间字段和一个 float 字段。"
+            "description": "Frame 形态。`table` 是不带标签的表格。`time_series` 恰好包含一个时间字段和一个 float 字段，时间值严格递增且不为 null。"
           },
           "fields": {
             "type": "array",
@@ -8883,7 +9171,18 @@
           "values": {
             "type": "array",
             "items": {
-              "description": "单个单元格。`time` 为 UTC RFC3339Nano 字符串，`float` 可以是字符串 `NaN`、`+Inf`、`-Inf`，除 `time_series` 中的时间值外均可以为 null。"
+              "oneOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "number"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "单元格取值。`time` 单元格为 UTC RFC3339Nano 字符串；`float` 单元格可以是字符串 `NaN`、`+Inf`、`-Inf`；除 `time_series` frame 中的时间值外，任何单元格都可以为 null。"
             },
             "description": "按行顺序排列的列取值。"
           }
@@ -8905,7 +9204,15 @@
             "description": "采样的标签集合。可以为空，但不能为 null。"
           },
           "value": {
-            "description": "采样值：数字，或字符串 `NaN`、`+Inf`、`-Inf`。不能为 null。"
+            "oneOf": [
+              {
+                "type": "number"
+              },
+              {
+                "type": "string"
+              }
+            ],
+            "description": "采样值：数字，或字符串 `NaN`、`+Inf`、`-Inf` 之一。不会为 null。"
           }
         }
       },
@@ -9011,11 +9318,11 @@
             "additionalProperties": {
               "type": "string"
             },
-            "description": "自定义标签。"
+            "description": "附加到该规则每个告警事件上的自定义标签。键会去除首尾空白，不能为空，且不能以 `__alert_rule_` 开头（保留前缀）；包含 `{{` 的值会在事件投递时按模板渲染；`job` 与 `instance` 的值最长 255 个字符。序列化后的对象不得超过 1024 个字符。"
           },
           "ds_type": {
             "type": "string",
-            "description": "数据源类型标识（如 `prometheus`、`elasticsearch`）。"
+            "description": "规则查询的数据源类型。规则启用时必须是支持告警的类型：`prometheus`、`elasticsearch`、`loki`、`clickhouse`、`mysql`、`oracle`、`postgres`、`sls`、`tencent_cls`、`victorialogs`。"
           },
           "ds_list": {
             "type": "array",
@@ -9046,7 +9353,7 @@
           },
           "cron_pattern": {
             "type": "string",
-            "description": "调度表达式：6 段（含秒）cron 表达式或 `@every 30s` 间隔描述。不允许以 `CRON_TZ=` 或 `TZ=` 开头，时区请填写到 `timezone` 字段。"
+            "description": "调度表达式：6 段（含秒）cron 表达式（如 `0 * * * * *`）、`@hourly` 等描述符，或 `@every <时长>`（须为整数秒且不小于 `1s`，如 `@every 30s`）。不允许以 `CRON_TZ=` 或 `TZ=` 开头，时区请填写到 `timezone` 字段。"
           },
           "timezone": {
             "type": "string",
@@ -9083,15 +9390,15 @@
                   "items": {
                     "type": "integer"
                   },
-                  "description": "星期几（0=周日）。"
+                  "description": "时间窗口适用的星期，`0` = 周日至 `6` = 周六；不能为空，不能重复。"
                 },
                 "stime": {
                   "type": "string",
-                  "description": "开始时间，如 `09:00`。"
+                  "description": "开始时间，24 小时制 `HH:MM` 格式，如 `09:00`。"
                 },
                 "etime": {
                   "type": "string",
-                  "description": "结束时间，如 `18:00`。"
+                  "description": "结束时间，24 小时制 `HH:MM` 格式，如 `18:00`。"
                 }
               }
             }
@@ -9114,7 +9421,7 @@
           },
           "description": {
             "type": "string",
-            "description": "规则描述，Markdown 格式。"
+            "description": "规则描述，按 `description_type` 以纯文本或 Markdown 渲染。"
           },
           "channel_ids": {
             "type": "array",
@@ -9127,12 +9434,12 @@
           "repeat_interval": {
             "type": "integer",
             "format": "int64",
-            "description": "通知重复间隔（秒）。小于 1 时按默认值 3600 处理。"
+            "description": "通知重复间隔（秒）。小于 1 时按默认值 3600 处理，最大 2147483647。"
           },
           "repeat_total": {
             "type": "integer",
             "format": "int64",
-            "description": "最大重复通知次数。小于 1 时按默认值 3 处理。"
+            "description": "最大重复通知次数。小于 1 时按默认值 3 处理，最大 2147483647。"
           },
           "investigation_targets": {
             "type": "array",
@@ -9140,7 +9447,7 @@
               "$ref": "#/components/schemas/InvestigationTarget"
             },
             "maxItems": 20,
-            "description": "告警事件详情页关联的排障入口列表，最多 20 项，不允许重复。更新接口中该字段按 presence 处理：省略时保留原配置，传 `[]` 清空。",
+            "description": "告警事件详情页关联的排障入口列表，最多 20 项，不允许重复，序列化后不超过 32 KiB。更新接口中该字段按 presence 处理：省略时保留原配置，传 `[]` 清空；传 `null` 会被拒绝。",
             "x-flashduty-preserve-absence": true
           },
           "creator_id": {
@@ -9225,7 +9532,7 @@
           },
           "relate_queries": {
             "type": "array",
-            "description": "可选的辅助查询，其结果作为上下文附加到告警事件中。每项须有唯一的 `name`（不与任何 query 名称重复）且 `expr` 非空。",
+            "description": "可选的辅助查询，其结果作为上下文附加到告警事件中。每项须有唯一的 `name`（不与任何 query 名称重复）且 `expr` 非空。响应中始终返回，没有时为 `[]`。",
             "items": {
               "type": "object",
               "properties": {
@@ -9544,7 +9851,7 @@
       },
       "DashboardQuery": {
         "type": "object",
-        "description": "仪表盘与排障入口共用的查询内容。",
+        "description": "仪表盘面板与告警规则排障入口共用的查询内容。两种场景的模板语法不同：仪表盘面板引用仪表盘变量（`${name}`），排障入口引用事件标签（`{{ }}`）。",
         "properties": {
           "mode": {
             "type": "string",
@@ -9553,18 +9860,18 @@
               "range",
               "window"
             ],
-            "description": "求值模式：`instant` 在单个时间点求值，`range` 求值一条按步长采样的曲线，`window` 返回时间窗口内的原始数据。"
+            "description": "求值模式：`instant` = 在单个时间点求值；`range` = 在时间范围内按步长求值得到曲线；`window` = 返回时间范围内的原始数据行。Prometheus 与 Loki 面板接受 `instant` 或 `range`（Loki 的 `logs` 面板需要 `range`）；MySQL 面板需要 `window`。"
           },
           "expr": {
             "type": "string",
-            "description": "目标数据源语法下的查询表达式，可通过 `{{ }}` 模板引用事件标签。"
+            "description": "数据源语法下的查询表达式。在仪表盘面板中可以 `${name}`、`${name:raw}`（原样插入单个值）或 `${name:regex}`（多个值拼成正则多选）引用变量，在 Prometheus 与 Loki 中也可写 `$name`；需要字面量时写 `$${...}`。不带格式化符时，多选或 `all` 变量以及 `=~`/`!~` 中的值会以正则形式插入，因此不能用在 `=` 或 `!=` 之后。MySQL 查询不支持变量。在排障入口中，表达式可通过 `{{ }}` 模板引用事件标签。"
           },
           "args": {
             "type": "object",
             "additionalProperties": {
               "type": "string"
             },
-            "description": "命名查询参数，默认空对象。值按原样透传，不允许包含 `{{ }}` 模板。"
+            "description": "命名查询参数，默认空对象。在仪表盘面板中，除 Loki 与 MySQL 数据源外，值可使用 `${name}` 模板。在排障入口中，键和值都不允许包含 `{{ }}` 模板。"
           },
           "min_step_seconds": {
             "type": [
@@ -9574,7 +9881,7 @@
             "format": "int64",
             "minimum": 1,
             "maximum": 9007199254740,
-            "description": "最小步长（秒）。仅在 `mode` 为 `range` 时可用，且必须大于 0；省略或传 null 由服务端决定。"
+            "description": "最小步长（秒），必须大于 0。在排障入口中仅当 `mode` 为 `range` 时可用。省略或传 null 由服务端决定。"
           }
         },
         "required": [
@@ -9585,7 +9892,7 @@
       },
       "DashboardDefinition": {
         "type": "object",
-        "description": "以可移植 `dashboard.v1` 文档形式存储的完整仪表盘内容。未知字段、重复字段、NaN/Inf、超范围数字与尾随值都会被拒绝；序列化后不得超过 1 MiB。",
+        "description": "以可移植 `dashboard.v1` 文档形式存储的完整仪表盘内容。未知字段、重复字段、尾随值以及超过 32 层的嵌套都会被拒绝，序列化后不得超过 1 MiB。上限：10 个 tab，每个 tab 10 个 section、30 个面板、100 条查询，每个仪表盘 100 个面板、300 条查询，20 个变量。",
         "properties": {
           "title": {
             "type": "string",
@@ -9617,7 +9924,7 @@
               "$ref": "#/components/schemas/DashboardVariable"
             },
             "maxItems": 20,
-            "description": "仪表盘变量，最多 20 个。名称在定义内必须唯一且符合变量名正则。"
+            "description": "仪表盘变量，最多 20 个，名称唯一。变量之间可以相互引用，但不能形成循环。"
           },
           "tabs": {
             "type": "array",
@@ -9626,7 +9933,7 @@
             },
             "minItems": 1,
             "maxItems": 10,
-            "description": "Tab，1～10 个。标题唯一，且所有 tab/section ID 必须是整份定义内唯一的 canonical UUIDv7。"
+            "description": "Tab，1～10 个。所有 tab、section 与面板的 `id` 必须是整份定义内只出现一次的 canonical UUIDv7。Tab 标题无需唯一。"
           }
         },
         "required": [
@@ -9681,7 +9988,7 @@
             "type": "string",
             "minLength": 1,
             "maxLength": 189,
-            "description": "Tab 标题，1～189 个 Unicode 字符，在 tab 之间唯一。"
+            "description": "Tab 标题，去除首尾空白后 1～189 个 Unicode 字符。"
           },
           "description": {
             "type": "string",
@@ -9694,7 +10001,7 @@
               "$ref": "#/components/schemas/DashboardPanel"
             },
             "maxItems": 30,
-            "description": "直接放在该 tab 上的面板，最多 30 个。"
+            "description": "直接放在该 tab 上的面板。一个 tab 内顶层面板与各 section 面板合计最多 30 个，查询最多 100 条。"
           },
           "sections": {
             "type": "array",
@@ -9742,7 +10049,7 @@
               "$ref": "#/components/schemas/DashboardPanel"
             },
             "maxItems": 30,
-            "description": "该 section 内的面板，最多 30 个。"
+            "description": "该 section 内的面板；计入所在 tab 合计 30 个面板的上限。"
           }
         },
         "required": [
@@ -9754,7 +10061,7 @@
       },
       "DashboardPanel": {
         "type": "object",
-        "description": "单个可视化面板。同一容器内的面板不得重叠；24 列网格在保存时校验。",
+        "description": "单个可视化面板。除 `text` 外所有类型都必须填写 `datasource_ref`，`text` 面板不允许填写。同一容器内的面板不得重叠；24 列网格在保存时校验。",
         "properties": {
           "id": {
             "type": "string",
@@ -9849,17 +10156,18 @@
             "type": "integer",
             "format": "uint64",
             "minimum": 1,
-            "description": "数据源 ID。`kind` 为 `fixed` 时必填，为 `variable` 时禁止设置。"
+            "description": "数据源 ID。`kind` 为 `fixed` 时必填，为 `variable` 时禁止设置。",
+            "maximum": 9007199254740991
           },
           "name": {
             "type": "string",
             "pattern": "^[A-Za-z_][A-Za-z0-9_]{0,63}$",
-            "description": "数据源变量名。`kind` 为 `variable` 时必填，为 `fixed` 时禁止设置。"
+            "description": "同一份定义中某个 `datasource` 类型变量的名称。`kind` 为 `variable` 时必填，为 `fixed` 时不允许填写。"
           },
           "datasource_type": {
             "type": "string",
             "pattern": "^[a-z][a-z0-9_]{0,63}$",
-            "description": "数据源类型标识，例如 `prometheus`、`victorialogs`。"
+            "description": "数据源类型标识：以小写字母开头，由小写字母、数字和下划线组成。取值集合是开放的，保存时接受任何符合格式的值，但仪表盘运行时只支持 `prometheus`、`mysql`、`loki` 数据源；其他类型的面板在运行时会失败。`kind` 为 `variable` 时必须与所引用数据源变量的 `datasource_type` 一致。"
           }
         },
         "required": [
@@ -9882,7 +10190,7 @@
           "legend_alias": {
             "type": "string",
             "maxLength": 1024,
-            "description": "可选图例名；支持与 `expr` 相同的变量模板。"
+            "description": "可选图例名，最多 1024 个 Unicode 字符。控制台会把 `{{label}}` 替换为该序列对应标签的值（如 `{{env}} requests`）；这里不会替换仪表盘变量。"
           }
         },
         "required": [
@@ -9926,7 +10234,7 @@
           "name": {
             "type": "string",
             "pattern": "^[A-Za-z_][A-Za-z0-9_]{0,63}$",
-            "description": "在 `{{ }}` 模板中引用的变量名，最多 64 个字符。以 `__` 开头的名称保留给内置时间变量。"
+            "description": "变量名，在定义内唯一。查询中以 `${name}` 引用（在 Prometheus 与 Loki 表达式中也可写 `$name`）。以 `__` 开头的名称保留给内置变量 `__interval`、`__rate_interval`、`__range`、`__auto`。"
           },
           "label": {
             "type": "string",
@@ -9936,7 +10244,7 @@
           "datasource_type": {
             "type": "string",
             "pattern": "^[a-z][a-z0-9_]{0,63}$",
-            "description": "候选项来自的数据源类型。"
+            "description": "作为候选项的数据源类型；候选项为账户下该类型的已启用数据源。取值集合是开放的，保存时接受任何符合格式的值，但仪表盘运行时只支持 `prometheus`、`mysql`、`loki` 数据源；其他类型的面板在运行时会失败。"
           },
           "name_patterns": {
             "type": "array",
@@ -9951,7 +10259,8 @@
           "default_datasource_id": {
             "type": "integer",
             "format": "uint64",
-            "description": "默认数据源 ID。若默认值不可用，运行时按名称、再按 ID 取第一个候选项。"
+            "description": "默认数据源 ID。若默认值不可用，运行时按名称、再按 ID 取第一个候选项。",
+            "maximum": 9007199254740991
           }
         },
         "required": [
@@ -9974,7 +10283,7 @@
           "name": {
             "type": "string",
             "pattern": "^[A-Za-z_][A-Za-z0-9_]{0,63}$",
-            "description": "在 `{{ }}` 模板中引用的变量名，最多 64 个字符。以 `__` 开头的名称保留给内置时间变量。"
+            "description": "变量名，在定义内唯一。查询中以 `${name}` 引用（在 Prometheus 与 Loki 表达式中也可写 `$name`）。以 `__` 开头的名称保留给内置变量 `__interval`、`__rate_interval`、`__range`、`__auto`。"
           },
           "label": {
             "type": "string",
@@ -10018,7 +10327,7 @@
           "name": {
             "type": "string",
             "pattern": "^[A-Za-z_][A-Za-z0-9_]{0,63}$",
-            "description": "在 `{{ }}` 模板中引用的变量名，最多 64 个字符。以 `__` 开头的名称保留给内置时间变量。"
+            "description": "变量名，在定义内唯一。查询中以 `${name}` 引用（在 Prometheus 与 Loki 表达式中也可写 `$name`）。以 `__` 开头的名称保留给内置变量 `__interval`、`__rate_interval`、`__range`、`__auto`。"
           },
           "label": {
             "type": "string",
@@ -10079,7 +10388,7 @@
       },
       "DashboardSelection": {
         "type": "object",
-        "description": "变量取值的具体选择。空的 `values` 数组是合法输入，表示未解析——服务端不会为其回退到默认值。",
+        "description": "变量取值的具体选择。作为已保存变量的 `default` 时，`values` 不能为空，`single` 模式下必须恰好一个值。在运行时请求中，空的 `values` 数组是合法输入，表示未解析——服务端不会为其回退到默认值。",
         "properties": {
           "kind": {
             "type": "string",
@@ -10166,7 +10475,7 @@
           },
           "metric": {
             "type": "string",
-            "description": "可选指标名，用于限定参与计算的序列。"
+            "description": "可选的指标选择器，用于限定参与计算的序列；可通过 `${name}` 或 `$name` 引用其他变量。"
           },
           "label_filters": {
             "type": "array",
@@ -10188,7 +10497,7 @@
           "label": {
             "type": "string",
             "pattern": "^[A-Za-z_][A-Za-z0-9_:.\\-]{0,189}$",
-            "description": "标签名。"
+            "description": "要匹配的 Prometheus 标签名，如 `job`；由字母、数字、`_`、`:`、`.`、`-` 组成，以字母或 `_` 开头。"
           },
           "op": {
             "type": "string",
@@ -10203,7 +10512,7 @@
           "value": {
             "type": "string",
             "minLength": 1,
-            "description": "匹配值；可通过 `{{ }}` 引用其他变量。"
+            "description": "匹配值；可通过 `${name}` 引用其他变量。多选或含 `all` 的变量需搭配 `=~` 或 `!~`。"
           }
         },
         "required": [
@@ -10225,7 +10534,7 @@
           },
           "expr": {
             "type": "string",
-            "description": "SQL 语句；可通过 `{{ }}` 引用其他变量。"
+            "description": "其结果作为候选项的 SQL 语句。SQL 变量查询只在 MySQL 数据源上运行，而 MySQL 查询不支持引用变量。"
           },
           "args": {
             "type": "object",
@@ -10264,7 +10573,7 @@
           },
           "expr": {
             "type": "string",
-            "description": "日志查询表达式；可通过 `{{ }}` 引用其他变量。数据源为 Loki 时可为空，此时会列出该字段在所有流中的取值。"
+            "description": "日志查询表达式；可通过 `${name}` 引用其他变量。日志变量查询只在 Loki 数据源上运行，此时 `expr` 可为空，表示列出该字段在所有流中的取值。"
           },
           "args": {
             "type": "object",
@@ -10287,7 +10596,7 @@
         ]
       },
       "DashboardVizConfig": {
-        "description": "可视化配置。`kind` 决定使用哪个分支以及哪个同级的配置对象必需；`time_series` 还携带通用的数值配置。",
+        "description": "可视化配置。`kind` 决定使用哪个分支，从而决定允许哪些同级字段；`time_series`、`stat`、`bar`、`gauge` 还带有通用数值字段 `unit`、`decimals`、`threshold`。出现其他类型的字段会被拒绝。",
         "oneOf": [
           {
             "$ref": "#/components/schemas/DashboardTimeSeriesViz"
@@ -10354,7 +10663,7 @@
               "bytes_per_second",
               "bits_per_second"
             ],
-            "description": "面板数值的展示单位：`unitless` = 原始数值；`ratio` = 占比（0–1 的小数）；`percent` = 百分比；`milliseconds` = 毫秒；`seconds` = 秒；`bytes` = 字节；`bits` = 比特；`count_per_second` = 每秒计数；`bytes_per_second` = 每秒字节数；`bits_per_second` = 每秒比特数。"
+            "description": "面板数值的展示单位：`unitless` = 原始数值；`ratio` = 占比（0–1 的小数）；`percent` = 百分比；`milliseconds` = 毫秒；`seconds` = 秒；`bytes` = 字节；`bits` = 比特；`count_per_second` = 每秒计数；`bytes_per_second` = 每秒字节数；`bits_per_second` = 每秒比特数。省略时默认为 `unitless`。"
           },
           "decimals": {
             "type": [
@@ -10362,7 +10671,8 @@
               "null"
             ],
             "minimum": 0,
-            "description": "固定小数位；省略或传 null 由前端决定。"
+            "description": "固定小数位数，0～15；省略或传 null 由控制台决定。",
+            "maximum": 15
           },
           "threshold": {
             "$ref": "#/components/schemas/DashboardThreshold"
@@ -10394,15 +10704,14 @@
             "additionalProperties": {
               "$ref": "#/components/schemas/DashboardColumnOption"
             },
-            "description": "按字段名索引的列展示覆盖配置，最多 100 项。"
+            "description": "按结果字段名设置的列展示覆盖项，最多 100 项。键名不能为空，最多 1024 个 Unicode 字符，且不能是 `frame_index` 或 `field_index`。"
           },
           "sort": {
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/DashboardFieldSort"
             },
-            "maxItems": 2,
-            "description": "初始排序键；字段需唯一。"
+            "description": "初始排序键，按顺序生效；每个字段只能出现一次。"
           },
           "link_columns": {
             "type": "array",
@@ -10448,7 +10757,7 @@
               "bytes_per_second",
               "bits_per_second"
             ],
-            "description": "面板数值的展示单位：`unitless` = 原始数值；`ratio` = 占比（0–1 的小数）；`percent` = 百分比；`milliseconds` = 毫秒；`seconds` = 秒；`bytes` = 字节；`bits` = 比特；`count_per_second` = 每秒计数；`bytes_per_second` = 每秒字节数；`bits_per_second` = 每秒比特数。"
+            "description": "面板数值的展示单位：`unitless` = 原始数值；`ratio` = 占比（0–1 的小数）；`percent` = 百分比；`milliseconds` = 毫秒；`seconds` = 秒；`bytes` = 字节；`bits` = 比特；`count_per_second` = 每秒计数；`bytes_per_second` = 每秒字节数；`bits_per_second` = 每秒比特数。省略时默认为 `unitless`。"
           },
           "decimals": {
             "type": [
@@ -10456,7 +10765,8 @@
               "null"
             ],
             "minimum": 0,
-            "description": "固定小数位；省略或传 null 由前端决定。"
+            "description": "固定小数位数，0～15；省略或传 null 由控制台决定。",
+            "maximum": 15
           },
           "threshold": {
             "$ref": "#/components/schemas/DashboardThreshold"
@@ -10466,7 +10776,9 @@
             "items": {
               "type": "string"
             },
-            "description": "被归约为展示取值的字段。"
+            "description": "归约为展示值的结果字段；至少一个且不可重复。按名称精确匹配，不能是 `frame_index` 或 `field_index`。",
+            "minItems": 1,
+            "uniqueItems": true
           },
           "reducer": {
             "type": "string",
@@ -10517,7 +10829,7 @@
               "bytes_per_second",
               "bits_per_second"
             ],
-            "description": "面板数值的展示单位：`unitless` = 原始数值；`ratio` = 占比（0–1 的小数）；`percent` = 百分比；`milliseconds` = 毫秒；`seconds` = 秒；`bytes` = 字节；`bits` = 比特；`count_per_second` = 每秒计数；`bytes_per_second` = 每秒字节数；`bits_per_second` = 每秒比特数。"
+            "description": "面板数值的展示单位：`unitless` = 原始数值；`ratio` = 占比（0–1 的小数）；`percent` = 百分比；`milliseconds` = 毫秒；`seconds` = 秒；`bytes` = 字节；`bits` = 比特；`count_per_second` = 每秒计数；`bytes_per_second` = 每秒字节数；`bits_per_second` = 每秒比特数。省略时默认为 `unitless`。"
           },
           "decimals": {
             "type": [
@@ -10525,21 +10837,25 @@
               "null"
             ],
             "minimum": 0,
-            "description": "固定小数位；省略或传 null 由前端决定。"
+            "description": "固定小数位数，0～15；省略或传 null 由控制台决定。",
+            "maximum": 15
           },
           "threshold": {
             "$ref": "#/components/schemas/DashboardThreshold"
           },
           "category_field": {
             "type": "string",
-            "description": "提供类目轴的字段。"
+            "description": "提供类目轴的结果字段；必填，最多 1024 个 Unicode 字符，不能是 `frame_index` 或 `field_index`。",
+            "minLength": 1
           },
           "value_fields": {
             "type": "array",
             "items": {
               "type": "string"
             },
-            "description": "提供柱值的字段。"
+            "description": "提供柱值的结果字段；至少一个且不可重复。名称不能是 `frame_index` 或 `field_index`。",
+            "minItems": 1,
+            "uniqueItems": true
           },
           "data_link": {
             "$ref": "#/components/schemas/DashboardDataLink"
@@ -10582,7 +10898,7 @@
               "bytes_per_second",
               "bits_per_second"
             ],
-            "description": "面板数值的展示单位：`unitless` = 原始数值；`ratio` = 占比（0–1 的小数）；`percent` = 百分比；`milliseconds` = 毫秒；`seconds` = 秒；`bytes` = 字节；`bits` = 比特；`count_per_second` = 每秒计数；`bytes_per_second` = 每秒字节数；`bits_per_second` = 每秒比特数。"
+            "description": "面板数值的展示单位：`unitless` = 原始数值；`ratio` = 占比（0–1 的小数）；`percent` = 百分比；`milliseconds` = 毫秒；`seconds` = 秒；`bytes` = 字节；`bits` = 比特；`count_per_second` = 每秒计数；`bytes_per_second` = 每秒字节数；`bits_per_second` = 每秒比特数。省略时默认为 `unitless`。"
           },
           "decimals": {
             "type": [
@@ -10590,7 +10906,8 @@
               "null"
             ],
             "minimum": 0,
-            "description": "固定小数位；省略或传 null 由前端决定。"
+            "description": "固定小数位数，0～15；省略或传 null 由控制台决定。",
+            "maximum": 15
           },
           "threshold": {
             "$ref": "#/components/schemas/DashboardThreshold"
@@ -10600,7 +10917,9 @@
             "items": {
               "type": "string"
             },
-            "description": "被归约为仪表值的字段。"
+            "description": "归约为仪表值的结果字段；至少一个且不可重复。按名称精确匹配，不能是 `frame_index` 或 `field_index`。",
+            "minItems": 1,
+            "uniqueItems": true
           },
           "reducer": {
             "type": "string",
@@ -10683,7 +11002,7 @@
           "markdown": {
             "type": "string",
             "maxLength": 65536,
-            "description": "Markdown 正文，最多 64 KiB。仅限白名单节点（标题、列表、表格、链接、代码）可通过校验。"
+            "description": "Markdown 正文，最多 64 KiB。允许段落、标题、列表、引用、代码块与行内代码、强调、表格、分隔线与链接。链接必须是 `https://` 地址或以 `/` 开头的站内相对路径。图片、原始 HTML 与 `${` 模板会以 `InvalidParameter` 拒绝，而不是被过滤掉。"
           }
         },
         "required": [
@@ -10761,7 +11080,7 @@
               "bytes_per_second",
               "bits_per_second"
             ],
-            "description": "列展示单位覆盖：`unitless` = 原始数值；`ratio` = 占比（0–1 的小数）；`percent` = 百分比；`milliseconds` = 毫秒；`seconds` = 秒；`bytes` = 字节；`bits` = 比特；`count_per_second` = 每秒计数；`bytes_per_second` = 每秒字节数；`bits_per_second` = 每秒比特数。"
+            "description": "列展示单位覆盖：`unitless` = 原始数值；`ratio` = 占比（0–1 的小数）；`percent` = 百分比；`milliseconds` = 毫秒；`seconds` = 秒；`bytes` = 字节；`bits` = 比特；`count_per_second` = 每秒计数；`bytes_per_second` = 每秒字节数；`bits_per_second` = 每秒比特数。省略时默认为 `unitless`。"
           },
           "threshold": {
             "$ref": "#/components/schemas/DashboardThreshold"
@@ -10786,7 +11105,7 @@
           "field": {
             "type": "string",
             "minLength": 1,
-            "description": "排序字段名。"
+            "description": "排序依据的结果字段名；最多 1024 个 Unicode 字符，不能是 `frame_index` 或 `field_index`。"
           },
           "direction": {
             "type": "string",
@@ -10804,12 +11123,12 @@
       },
       "DashboardDataLink": {
         "type": "object",
-        "description": "从表格列或柱状图面板下钻到另一个仪表盘的链接。目标仪表盘必须存在，且映射来源需与源面板的结构匹配。",
+        "description": "从表格或柱状图面板下钻到另一个仪表盘的链接。保存时只校验 ID 格式，指向不存在仪表盘的链接也会被接受。允许的映射来源取决于源面板类型。",
         "properties": {
           "dashboard_id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "目标仪表盘 ID。"
+            "description": "要打开的仪表盘 ID；必须是 canonical UUIDv7。"
           },
           "target_id": {
             "type": "string",
@@ -10825,7 +11144,7 @@
             "additionalProperties": {
               "$ref": "#/components/schemas/DashboardLinkMapping"
             },
-            "description": "把目标变量名映射到某个来源值，例如表格列或源变量。"
+            "description": "要在目标仪表盘中设置的变量值，键为目标变量名（需符合 `^[A-Za-z_][A-Za-z0-9_]{0,63}$`）；每项说明取值来源。无映射时传 `{}`。"
           }
         },
         "required": [
@@ -10847,15 +11166,15 @@
               "series",
               "value"
             ],
-            "description": "取值来源：`variable` = 仪表盘变量；`row_column` = 表格列（必须同时给出 `column`）；`category` = 柱状图的类目；`series` = 序列名；`value` = 数值本身。`category`、`series`、`value` 仅对柱状图面板有效。"
+            "description": "取值来源：`variable` = 源仪表盘某个变量的当前值（需填 `name`），表格与柱状图面板可用；`row_column` = 被点击行在某表格列的值（需填 `column`），仅表格面板；`category` = 被点击柱的类目，`series` = 其序列名，`value` = 其数值——这三种仅柱状图面板可用，且不带额外字段。"
           },
           "column": {
             "type": "string",
-            "description": "来源列名；`source` 为 `row_column` 时必填。"
+            "description": "要读取的表格列（结果字段）；`source` 为 `row_column` 时必填，否则不允许填写。"
           },
           "name": {
             "type": "string",
-            "description": "来源仪表盘变量名；`source` 为 `variable` 时必填。"
+            "description": "要读取的源仪表盘变量；`source` 为 `variable` 时必填，且必须存在于同一份定义中；其他来源不允许填写。"
           }
         },
         "required": [
@@ -10869,11 +11188,11 @@
           "id": {
             "type": "integer",
             "format": "uint64",
-            "description": "成员 ID。"
+            "description": "执行该操作的成员 ID。"
           },
           "name": {
             "type": "string",
-            "description": "成员展示名。"
+            "description": "成员展示名，记录于操作发生时。"
           }
         },
         "required": [
@@ -10956,13 +11275,13 @@
           "dashboard_id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "仪表盘 ID。"
+            "description": "仪表盘 ID；传给 `POST /monit/dashboard/get` 可获取完整定义。"
           },
           "folder_id": {
             "type": "integer",
             "format": "uint64",
             "minimum": 1,
-            "description": "目录 ID。"
+            "description": "仪表盘所在目录的 ID。"
           },
           "folder_breadcrumb": {
             "type": "array",
@@ -10977,7 +11296,7 @@
           },
           "description": {
             "type": "string",
-            "description": "仪表盘描述；未设置时为空串。"
+            "description": "仪表盘描述；未设置时省略。"
           },
           "revision": {
             "type": "integer",
@@ -11033,7 +11352,7 @@
           "dashboard_id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "仪表盘 ID。"
+            "description": "回收站中仪表盘的 ID；可传给 `POST /monit/dashboard/restore`。"
           },
           "folder_id": {
             "type": "integer",
@@ -11054,13 +11373,13 @@
           },
           "description": {
             "type": "string",
-            "description": "仪表盘描述；未设置时为空串。"
+            "description": "仪表盘描述；未设置时省略。"
           },
           "revision": {
             "type": "integer",
             "format": "uint64",
             "minimum": 1,
-            "description": "删除时的版本号。"
+            "description": "回收站中该仪表盘的当前版本号（删除时已加 1）；恢复时作为 `expected_revision` 传入。"
           },
           "deleted_by": {
             "$ref": "#/components/schemas/DashboardActor"
@@ -11095,7 +11414,7 @@
           "total": {
             "type": "integer",
             "format": "int64",
-            "description": "已删除仪表盘总数。"
+            "description": "调用方可见的已删除仪表盘总数（跨所有分页）。"
           }
         },
         "required": [
@@ -11105,11 +11424,11 @@
       },
       "DashboardUpdateOutput": {
         "type": "object",
-        "description": "更新或移动的结果。`changed` 为 false 表示本次写入是空操作——规范化后的序列化定义与已存内容逐字节相同，此时 `resource` 仍描述该未变化的仪表盘。",
+        "description": "更新或移动的结果。`changed` 为 false 表示未做任何写入——更新时规范化后的定义与 `schema_version` 均与已存内容相同；移动时仪表盘已在目标目录中。此时 `revision` 不变，`resource` 描述未变化的仪表盘。",
         "properties": {
           "changed": {
             "type": "boolean",
-            "description": "已存储的仪表盘是否真的发生了变化。"
+            "description": "是否发生了写入并使 `revision` 加 1。"
           },
           "resource": {
             "$ref": "#/components/schemas/DashboardResource"
@@ -11127,13 +11446,13 @@
           "dashboard_id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "仪表盘 ID。"
+            "description": "已移入回收站的仪表盘 ID。"
           },
           "revision": {
             "type": "integer",
             "format": "uint64",
             "minimum": 1,
-            "description": "本次删除记录的版本号。"
+            "description": "删除后的版本号；恢复时作为 `expected_revision` 传入。"
           }
         },
         "required": [
@@ -11148,7 +11467,7 @@
           "dashboard_id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "仪表盘 ID。"
+            "description": "该版本所属的仪表盘 ID。"
           },
           "revision": {
             "type": "integer",
@@ -11165,7 +11484,7 @@
           "message": {
             "type": "string",
             "maxLength": 1024,
-            "description": "可选提交说明；最多 1024 个 Unicode 字符。"
+            "description": "调用 `POST /monit/dashboard/update` 时传入的说明；未提供时，以及创建、移动、删除、恢复产生的版本上，此字段省略。"
           },
           "actor": {
             "$ref": "#/components/schemas/DashboardActor"
@@ -11207,7 +11526,7 @@
           "dashboard_id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "仪表盘 ID。"
+            "description": "该版本所属的仪表盘 ID。"
           },
           "schema_version": {
             "type": "string",
@@ -11234,7 +11553,7 @@
           "message": {
             "type": "string",
             "maxLength": 1024,
-            "description": "可选提交说明。"
+            "description": "调用 `POST /monit/dashboard/update` 时传入的说明；未提供时省略。"
           },
           "actor": {
             "$ref": "#/components/schemas/DashboardActor"
@@ -11294,7 +11613,7 @@
           "dashboard_id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "仪表盘 ID。"
+            "description": "仪表盘 ID，与请求中传入的一致。"
           },
           "title": {
             "type": "string",
@@ -11302,7 +11621,7 @@
           },
           "description": {
             "type": "string",
-            "description": "仪表盘描述；未设置时为空串。"
+            "description": "仪表盘描述；未设置时省略。"
           },
           "revision": {
             "type": "integer",
@@ -11331,7 +11650,7 @@
             "type": "integer",
             "format": "uint64",
             "minimum": 1,
-            "description": "目录 ID。"
+            "description": "仪表盘所在目录的 ID。"
           },
           "breadcrumb": {
             "type": "array",
@@ -11357,7 +11676,7 @@
           },
           "label": {
             "type": "string",
-            "description": "展示名；未设置时为空串。"
+            "description": "展示名；未设置时省略。"
           },
           "kind": {
             "type": "string",
@@ -11384,15 +11703,15 @@
           "id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "Tab ID。"
+            "description": "Tab ID；作为 `target_id` 传入可把大纲收窄到该 tab。"
           },
           "title": {
             "type": "string",
-            "description": "Tab 标题。"
+            "description": "定义中保存的 tab 标题。"
           },
           "description": {
             "type": "string",
-            "description": "Tab 描述；未设置时为空串。"
+            "description": "Tab 描述；未设置时省略。"
           },
           "breadcrumb": {
             "type": "array",
@@ -11431,7 +11750,7 @@
           "id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "Section ID。"
+            "description": "Section ID；作为 `target_id` 传入可把大纲收窄到该 section。"
           },
           "title": {
             "type": "string",
@@ -11439,7 +11758,7 @@
           },
           "description": {
             "type": "string",
-            "description": "Section 描述；未设置时为空串。"
+            "description": "Section 描述；未设置时省略。"
           },
           "breadcrumb": {
             "type": "array",
@@ -11470,7 +11789,7 @@
           "id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "面板 ID。"
+            "description": "面板 ID；可作为 `POST /monit/dashboard/panel/run` 的 `panel_id`，或在此作为 `target_id`。"
           },
           "title": {
             "type": "string",
@@ -11478,7 +11797,7 @@
           },
           "description": {
             "type": "string",
-            "description": "面板描述；未设置时为空串。"
+            "description": "面板描述；未设置时省略。"
           },
           "breadcrumb": {
             "type": "array",
@@ -11492,7 +11811,7 @@
           },
           "datasource_type": {
             "type": "string",
-            "description": "面板查询的数据源类型；面板无数据源（text 面板）时为空串。"
+            "description": "面板 `datasource_ref` 中的数据源类型，如 `prometheus`、`mysql`、`loki`；text 面板没有数据源，此字段省略。取值集合是开放的，原样返回保存时的类型。"
           }
         },
         "required": [
@@ -11558,7 +11877,7 @@
           "dashboard_id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "仪表盘的 canonical UUIDv7。"
+            "description": "由调用方生成的小写 canonical UUIDv7，作为仪表盘的永久 ID。"
           },
           "schema_version": {
             "type": "string",
@@ -11571,7 +11890,7 @@
             "type": "integer",
             "format": "uint64",
             "minimum": 1,
-            "description": "创建到哪个目录。必须是调用方有写权限的目录。"
+            "description": "创建到哪个目录；该目录必须存在且 `app_key` 所属成员可访问，否则返回 `FolderNotFound`。"
           },
           "definition": {
             "$ref": "#/components/schemas/DashboardDefinition"
@@ -11674,7 +11993,7 @@
             "type": "integer",
             "format": "uint64",
             "minimum": 1,
-            "description": "目标目录 ID。"
+            "description": "目标目录 ID；该目录必须存在且调用方可访问，否则返回 `FolderNotFound`。"
           }
         },
         "required": [
@@ -11685,7 +12004,7 @@
       },
       "DashboardDeleteRequest": {
         "type": "object",
-        "description": "把仪表盘移入回收站。定义会保留 30 天，因此可用恢复接口撤销删除。",
+        "description": "把仪表盘移入回收站。删除 30 天后被永久清除；在此之前可用恢复接口撤销删除。",
         "properties": {
           "dashboard_id": {
             "type": "string",
@@ -11717,7 +12036,7 @@
             "type": "integer",
             "format": "uint64",
             "minimum": 1,
-            "description": "调用方最后读到的版本号。若与已存版本不一致，写入会以 `DashboardRevisionConflict` 失败。"
+            "description": "回收站中该仪表盘的当前版本号，即删除接口返回或回收站列表中显示的值。不一致时以 `DashboardRevisionConflict` 失败。"
           },
           "folder_id": {
             "type": [
@@ -11726,7 +12045,7 @@
             ],
             "format": "uint64",
             "minimum": 1,
-            "description": "目标目录。省略则恢复到原目录；当原目录已不可写时调用会以 `RestoreFolderRequired` 失败，此时必须显式指定。"
+            "description": "目标目录。省略或传 null 表示恢复到原目录；若原目录已不存在，调用会以 `RestoreFolderRequired` 失败，此时必须指定目标目录。"
           }
         },
         "required": [
@@ -11763,12 +12082,12 @@
             "type": "integer",
             "format": "uint64",
             "minimum": 1,
-            "description": "要列出仪表盘的目录。"
+            "description": "要列出其直接包含的仪表盘的目录；不包含子目录。"
           },
           "query": {
             "type": "string",
             "maxLength": 128,
-            "description": "可选空格分隔的搜索词，匹配标题与描述；最多 128 个 Unicode 字符。"
+            "description": "可选的搜索词，以空白分隔，最多 128 个 Unicode 字符。标题或描述中包含每一个词的仪表盘才会命中。"
           },
           "sort": {
             "type": "array",
@@ -11802,7 +12121,7 @@
             "type": "string",
             "minLength": 1,
             "maxLength": 128,
-            "description": "空格分隔的搜索词；至少一个单词，最多 128 个 Unicode 字符。"
+            "description": "以空白分隔的搜索词；至少一个词，最多 128 个 Unicode 字符。标题或描述中包含每一个词的仪表盘才会命中。"
           },
           "sort": {
             "type": "array",
@@ -11861,13 +12180,15 @@
             "type": "integer",
             "format": "int64",
             "minimum": 0,
-            "description": "Unix 时间戳（毫秒）。"
+            "description": "窗口起点，Unix 毫秒时间戳。须不小于 0 且小于 `to_ms`。",
+            "maximum": 9007199254740991
           },
           "to_ms": {
             "type": "integer",
             "format": "int64",
             "minimum": 1,
-            "description": "Unix 时间戳（毫秒）。"
+            "description": "窗口终点，Unix 毫秒时间戳。须大于 `from_ms`；`instant` 查询在该时间点求值。",
+            "maximum": 9007199254740991
           }
         },
         "required": [
@@ -11877,15 +12198,15 @@
       },
       "DashboardRuntimeError": {
         "type": "object",
-        "description": "变量级或查询级的失败。单个分支失败不会导致整个调用失败。",
+        "description": "单个变量或单条查询的失败。单个变量或查询失败不会导致整个调用失败。",
         "properties": {
           "reason": {
             "type": "string",
-            "description": "机器可读的失败原因。已观察到的取值包括 `invalid_request`、`variable_invalid`、`panel_missing`、`field_missing`、`datasource_permission_denied`、`timeout`、`panel_deadline`、`panel_canceled`、`canceled`、`overloaded`、`source_too_large`、`edge_unavailable`、`edge_upgrade_required`、`edge_version_unknown`、`mixed_edge_versions`、`internal`。"
+            "description": "机器可读的失败原因。取值集合是开放的，当前有：\n- `invalid_request`：查询或数据源配置被拒绝（数据源类型或查询模式不受支持、不允许 `args` 的地方传了参数、参数格式错误）。\n- `variable_invalid`：变量无法使用（既无选择也无默认值、所选值不在候选项中、依赖项未解析、替换出错、候选项列表不可用）。\n- `panel_missing`：面板不在该仪表盘中（仅出现在查询解析接口）。\n- `datasource_permission_denied`：数据源不存在、已停用、调用方无权访问，或没有可访问的数据源匹配该变量。\n- `field_missing`、`value_not_scalar`、`empty_field_name`、`duplicate_field_name`、`field_type_changed`：结果与面板可视化不匹配，或 SQL 变量查询返回了不可用的列。\n- `timeout`：数据源调用超时；`panel_deadline`：运行触达 35 秒总时限。\n- `canceled`、`panel_canceled`：调用被取消。\n- `overloaded`：数据源一侧正在限流。\n- `too_many_rows`、`result_too_large`、`source_too_large`：超出行数、大小或候选项数量上限。\n- `edge_unavailable`、`no_active_edge`、`edge_upgrade_required`、`edge_version_unknown`、`mixed_edge_versions`：数据源所属的 Edge 集群未连接、版本过旧、版本未知或版本混用。\n- `internal`：服务端意外错误。"
           },
           "message": {
             "type": "string",
-            "description": "失败的可读详情。"
+            "description": "面向展示和排查的可读详情；措辞不保证稳定，请勿据此解析。"
           }
         },
         "required": [
@@ -11895,18 +12216,18 @@
       },
       "DashboardRuntimeDatasource": {
         "type": "object",
-        "description": "运行时查询实际绑定的数据源。",
+        "description": "运行时变量或查询实际绑定的数据源。",
         "properties": {
           "id": {
             "type": "integer",
             "format": "uint64",
             "minimum": 1,
-            "description": "数据源 ID。"
+            "description": "数据源 ID，与数据源列表接口返回的一致。"
           },
           "type": {
             "type": "string",
             "pattern": "^[a-z][a-z0-9_]{0,63}$",
-            "description": "数据源类型标识。"
+            "description": "数据源类型标识。已解析的查询和 `query` 变量只会是 `prometheus`、`mysql` 或 `loki`；`datasource` 变量选中的数据源可以是该变量所配置的任意类型标识。"
           },
           "name": {
             "type": "string",
@@ -11921,12 +12242,12 @@
       },
       "DashboardResolvedVariable": {
         "type": "object",
-        "description": "单个已解析变量。数据源不可达、表达式错误或结果为空时，`candidates` 会不完整并填充 `error`，而不是让请求整体失败。",
+        "description": "单个已解析变量。出现失败（既无选择也无默认值、所选值不在候选项中、依赖项未解析、数据源不可达、查询结果不可用）时，会填充 `error` 并省略 `selection`，而不是让请求整体失败。",
         "properties": {
           "name": {
             "type": "string",
             "pattern": "^[A-Za-z_][A-Za-z0-9_]{0,63}$",
-            "description": "变量名。"
+            "description": "变量名，与仪表盘或草稿中的定义一致。"
           },
           "kind": {
             "type": "string",
@@ -11942,7 +12263,7 @@
             "items": {
               "$ref": "#/components/schemas/DashboardCandidate"
             },
-            "description": "解析出的候选项，最多 1000 个。"
+            "description": "可选项，最多 1000 个；没有候选项或解析失败时为空数组。顺序：`custom` 保持定义顺序，`datasource` 按名称再按 ID 排序，`query` 按值排序。"
           },
           "selection": {
             "$ref": "#/components/schemas/DashboardSelection"
@@ -11977,13 +12298,13 @@
             "additionalProperties": {
               "$ref": "#/components/schemas/DashboardSelection"
             },
-            "description": "已做出的选择，按变量名索引，最多 20 项。未在此给出的变量回退到其存储的默认值。"
+            "description": "已做出的选择，按变量名索引，最多 20 项。未给出的变量回退到其存储的默认值；出现仪表盘未定义的变量名时，调用以 HTTP 400 失败。",
+            "maxProperties": 20
           }
         },
         "required": [
           "dashboard_id",
-          "time",
-          "variables"
+          "time"
         ]
       },
       "DashboardVariablesResolveResponse": {
@@ -11993,7 +12314,7 @@
           "dashboard_id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "仪表盘 ID。"
+            "description": "变量所属的仪表盘 ID，与请求一致。"
           },
           "revision": {
             "type": "integer",
@@ -12030,7 +12351,7 @@
           "ref_id": {
             "type": "string",
             "pattern": "^[A-Z]$",
-            "description": "面板内的查询引用名。"
+            "description": "面板内的查询引用名：单个字母 `A`–`Z`。"
           },
           "datasource": {
             "$ref": "#/components/schemas/DashboardRuntimeDatasource"
@@ -12042,27 +12363,24 @@
               "instant",
               "window"
             ],
-            "description": "求值模式：`range` = 按步长采样的时序；`instant` = 单个时间点；`window` = 有界时间窗口内的原始行。"
+            "description": "求值模式：`range` = 按步长采样的时序；`instant` = 单个时间点；`window` = 有界时间窗口内的行。Prometheus、Loki 查询使用 `range` 或 `instant`；MySQL 查询使用 `window`。"
           },
           "expr": {
             "type": "string",
-            "description": "已完成变量替换的表达式。"
+            "description": "已完成变量替换的表达式。请求中 `preserve_builtin_variables` 为 `true` 时，内置时间变量原样保留。"
           },
           "args": {
             "type": "object",
             "additionalProperties": {
               "type": "string"
             },
-            "description": "查询参数；无参数时为空对象。"
+            "description": "查询参数；无参数时为空对象。只有 Loki 查询带参数：`loki.limit`（1～1000 的十进制整数，日志条数上限）和 `loki.direction`（`latest` 或 `earliest`）。"
           },
           "min_step_seconds": {
-            "type": [
-              "integer",
-              "null"
-            ],
+            "type": "integer",
             "format": "int64",
             "minimum": 1,
-            "description": "最小步长（秒）；未设置时为 null。"
+            "description": "面板查询设置的最小步长（秒）；未设置时不返回。"
           }
         },
         "required": [
@@ -12075,12 +12393,12 @@
       },
       "DashboardResolvedPanelQueries": {
         "type": "object",
-        "description": "单个面板的解析结果。所有查询都成功时 `state` 为 `success`，部分成功为 `partial`，全部失败为 `error`。",
+        "description": "单个面板的解析结果。所有查询都成功时 `state` 为 `success`，部分成功为 `partial`，全部失败为 `error`。`error` 只描述第一个失败。",
         "properties": {
           "panel_id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "面板 ID。"
+            "description": "面板 ID，与 `panel_ids` 中的某一项一致。"
           },
           "state": {
             "type": "string",
@@ -12089,14 +12407,14 @@
               "partial",
               "error"
             ],
-            "description": "该面板查询的整体状态：`success` = 全部查询解析成功；`partial` = 部分成功；`error` = 全部失败。"
+            "description": "该面板查询的解析状态：`success` = 全部查询解析成功；`partial` = 部分成功、部分失败；`error` = 全部失败，包括面板不存在的情况。"
           },
           "queries": {
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/DashboardResolvedQuery"
             },
-            "description": "解析成功的查询。"
+            "description": "解析成功的查询，顺序与面板中的查询一致。失败的查询不出现；全部失败时为空数组。"
           },
           "error": {
             "$ref": "#/components/schemas/DashboardRuntimeError"
@@ -12135,7 +12453,8 @@
             "additionalProperties": {
               "$ref": "#/components/schemas/DashboardSelection"
             },
-            "description": "按变量名索引的选择，最多 20 项。"
+            "description": "按变量名索引的选择，最多 20 项。未给出的变量回退到存储的默认值；出现仪表盘未定义的变量名时，调用以 HTTP 400 失败。",
+            "maxProperties": 20
           },
           "max_data_points": {
             "type": [
@@ -12144,7 +12463,7 @@
             ],
             "minimum": 2,
             "maximum": 5000,
-            "description": "用于计算 step 并渲染内置时间变量的降采样目标，2～5000 个点；省略或传 null 时服务端默认 100。"
+            "description": "每条序列的目标最大点数，用于计算步长并渲染内置时间变量。取值 2～5000；省略或传 null 时默认 100。"
           },
           "preserve_builtin_variables": {
             "type": "boolean",
@@ -12154,18 +12473,17 @@
         "required": [
           "dashboard_id",
           "panel_ids",
-          "time",
-          "variables"
+          "time"
         ]
       },
       "DashboardQueriesResolveResponse": {
         "type": "object",
-        "description": "每个请求的面板对应一个条目，顺序与请求一致。",
+        "description": "所请求面板的已解析查询，以及解析时采用的生效变量选择。不会执行任何查询。",
         "properties": {
           "dashboard_id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "仪表盘 ID。"
+            "description": "查询所依据的仪表盘 ID，与请求一致。"
           },
           "revision": {
             "type": "integer",
@@ -12181,14 +12499,14 @@
             "additionalProperties": {
               "$ref": "#/components/schemas/DashboardSelection"
             },
-            "description": "解析成功的变量选择。"
+            "description": "解析成功的变量的生效选择，按变量名索引；解析失败的变量不出现。"
           },
           "panels": {
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/DashboardResolvedPanelQueries"
             },
-            "description": "每个面板的结果。"
+            "description": "每个请求的面板对应一个条目，顺序与请求一致。"
           }
         },
         "required": [
@@ -12206,12 +12524,12 @@
           "max_concurrency": {
             "type": "integer",
             "minimum": 1,
-            "description": "该面板查询的并发上限。"
+            "description": "该面板同时执行的查询数上限；固定为 6。"
           },
           "execution_count": {
             "type": "integer",
             "minimum": 0,
-            "description": "发起的查询数量。"
+            "description": "解析成功并被派发执行的查询数量；解析失败的查询不计入。"
           }
         },
         "required": [
@@ -12221,12 +12539,12 @@
       },
       "DashboardPanelRunRef": {
         "type": "object",
-        "description": "面板运行中单条查询的结果。原始执行载荷随数据源类型而异且原样透传，因此此处不做 schema 约束。",
+        "description": "面板运行或预览中单条查询的结果。原始执行载荷随数据源类型而异且原样透传，因此此处不做 schema 约束。",
         "properties": {
           "ref_id": {
             "type": "string",
             "pattern": "^[A-Z]$",
-            "description": "面板内的查询引用名。"
+            "description": "面板内的查询引用名：单个字母 `A`–`Z`，与面板 `queries` 中的设置一致。"
           },
           "state": {
             "type": "string",
@@ -12235,16 +12553,16 @@
               "error",
               "incompatible"
             ],
-            "description": "单条查询的执行状态：`success` = 查询执行成功；`error` = 查询执行失败；`incompatible` = 数据源接受了调用，但查询模式或字段选择与该数据源类型不匹配。"
+            "description": "单条查询的状态：`success` = 查询已执行，且带有 `execution`；`error` = 查询无法解析或执行，或运行被取消、超时，原因见 `error`；`incompatible` = 查询已执行，但结果与面板可视化不匹配（例如配置的字段缺失或不是数值），此时仍带有 `execution`，`error` 说明不匹配的原因。"
           },
           "child_request_id": {
             "type": "string",
-            "description": "底层数据源执行的请求 ID；排查单条查询时可用。"
+            "description": "底层数据源执行的请求 ID；排查单条查询时可用。查询没有到达数据源时不返回。"
           },
           "execution": {
             "type": "object",
             "additionalProperties": true,
-            "description": "数据源专属的执行载荷，原样透传。"
+            "description": "数据源专属的执行结果，原样透传。`state` 为 `success` 或 `incompatible` 时存在，`error` 时不返回。"
           },
           "error": {
             "$ref": "#/components/schemas/DashboardRuntimeError"
@@ -12257,7 +12575,7 @@
       },
       "DashboardPanelRunRequest": {
         "type": "object",
-        "description": "对已存仪表盘执行某个面板。省略 `revision` 表示按当前版本运行；传入它可拒绝过期响应。",
+        "description": "执行已存仪表盘的某个面板。省略 `revision`（或传 0）表示按当前版本运行；传入它可让过期调用被拒绝。文本面板不能运行。",
         "properties": {
           "dashboard_id": {
             "type": "string",
@@ -12267,13 +12585,12 @@
           "panel_id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "要执行的面板。"
+            "description": "要执行的面板 ID。必须属于该仪表盘，否则返回 `TargetNotFound`（HTTP 404）。"
           },
           "revision": {
             "type": "integer",
             "format": "uint64",
-            "minimum": 1,
-            "description": "版本护栏；设置时必须等于当前版本号。"
+            "description": "版本护栏。设置（非 0）时必须等于仪表盘当前版本号，否则以 `DashboardRevisionConflict`（HTTP 409）失败。省略或传 0 表示不校验。"
           },
           "time": {
             "$ref": "#/components/schemas/DashboardAbsoluteTimeRange"
@@ -12283,7 +12600,8 @@
             "additionalProperties": {
               "$ref": "#/components/schemas/DashboardSelection"
             },
-            "description": "按变量名索引的选择，最多 20 项。"
+            "description": "按变量名索引的选择，最多 20 项。未给出的变量回退到存储的默认值；出现仪表盘未定义的变量名时，调用以 HTTP 400 失败。",
+            "maxProperties": 20
           },
           "max_data_points": {
             "type": [
@@ -12292,29 +12610,28 @@
             ],
             "minimum": 2,
             "maximum": 5000,
-            "description": "降采样目标，2～5000 个点；省略或传 null 时服务端默认 100。"
+            "description": "`range` 查询每条序列的目标最大点数，服务端据此推算查询步长。取值 2～5000；省略或传 null 时默认 100。"
           }
         },
         "required": [
           "dashboard_id",
           "panel_id",
-          "time",
-          "variables"
+          "time"
         ]
       },
       "DashboardPanelRunResponse": {
         "type": "object",
-        "description": "面板执行结果。`run_state` 汇总各查询状态：全部成功为 `success`，部分成功为 `partial`，否则为 `incompatible`、`cancelled` 或 `error`。整个响应上限 8 MiB。",
+        "description": "面板执行结果。即使所有查询都失败也返回 HTTP 200，请查看 `run_state` 以及各 ref 的 `state`、`error`。响应超过 8 MiB 时以 `EntityTooLarge`（HTTP 413）拒绝，而不会截断。",
         "properties": {
           "dashboard_id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "仪表盘 ID。"
+            "description": "被运行的仪表盘 ID，与请求一致。"
           },
           "panel_id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "面板 ID。"
+            "description": "被运行的面板 ID，与请求一致。"
           },
           "revision": {
             "type": "integer",
@@ -12331,7 +12648,7 @@
               "cancelled",
               "error"
             ],
-            "description": "本次运行的整体状态：`success` = 全部查询成功；`partial` = 部分成功；`incompatible` = 至少一条查询与其数据源类型不兼容；`cancelled` = 运行被取消；`error` = 全部查询失败。"
+            "description": "本次运行的整体状态：`success` = 全部查询成功；`partial` = 至少一个查询成功且至少一个未成功；`cancelled` = 没有查询成功，且客户端取消了请求；`incompatible` = 没有查询成功，且至少一个查询已执行但结果与面板可视化不匹配；`error` = 没有查询成功且没有 `incompatible`（面板没有查询时也是 `error`）。"
           },
           "time": {
             "$ref": "#/components/schemas/DashboardAbsoluteTimeRange"
@@ -12341,14 +12658,14 @@
             "additionalProperties": {
               "$ref": "#/components/schemas/DashboardSelection"
             },
-            "description": "解析成功的变量选择。"
+            "description": "解析成功的变量的生效选择，按变量名索引；解析失败的变量不出现。"
           },
           "refs": {
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/DashboardPanelRunRef"
             },
-            "description": "面板中每条查询对应一个条目。"
+            "description": "面板中每条查询对应一个条目，顺序与面板中的查询一致。解析失败的查询以 `state` 为 `error` 出现。"
           },
           "display": {
             "$ref": "#/components/schemas/DashboardVizConfig"
@@ -12384,13 +12701,13 @@
           "dashboard_id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "`existing` 时必填，`new` 时禁止设置。"
+            "description": "`existing` 时必填，`new` 时禁止设置。调用方须能访问该仪表盘所在目录。"
           },
           "folder_id": {
             "type": "integer",
             "format": "uint64",
             "minimum": 1,
-            "description": "`new` 时必填，`existing` 时禁止设置。"
+            "description": "`new` 时必填，`existing` 时禁止设置。须是调用方可访问的目录，否则返回 `FolderNotFound`（HTTP 404）。"
           }
         },
         "required": [
@@ -12410,14 +12727,15 @@
               "$ref": "#/components/schemas/DashboardVariable"
             },
             "maxItems": 20,
-            "description": "草稿变量，最多 20 个。"
+            "description": "草稿变量，最多 20 个。按与已存定义相同的规则校验（名称、依赖、选项上限），且不得超过 1 MiB。"
           },
           "selections": {
             "type": "object",
             "additionalProperties": {
               "$ref": "#/components/schemas/DashboardSelection"
             },
-            "description": "按变量名索引的选择，最多 20 项。"
+            "description": "按变量名索引的选择，最多 20 项。未给出的变量回退到其草稿默认值；出现不在 `variables` 中的变量名时，调用以 HTTP 400 失败。",
+            "maxProperties": 20
           },
           "time": {
             "$ref": "#/components/schemas/DashboardAbsoluteTimeRange"
@@ -12426,7 +12744,6 @@
         "required": [
           "context",
           "variables",
-          "selections",
           "time"
         ]
       },
@@ -12439,14 +12756,14 @@
             "items": {
               "$ref": "#/components/schemas/DashboardResolvedVariable"
             },
-            "description": "已解析的变量。"
+            "description": "已解析的变量，顺序与草稿 `variables` 一致。"
           },
           "selections": {
             "type": "object",
             "additionalProperties": {
               "$ref": "#/components/schemas/DashboardSelection"
             },
-            "description": "按变量名索引的生效选择。"
+            "description": "按变量名索引的生效选择；只包含解析成功的变量。"
           }
         },
         "required": [
@@ -12456,7 +12773,7 @@
       },
       "DashboardPanelPreviewRequest": {
         "type": "object",
-        "description": "内联执行一个草稿面板，不会产生仪表盘新版本。同样受 1 MiB 定义体积上限约束。",
+        "description": "内联执行一个草稿面板，不会产生仪表盘新版本。草稿 `panel` 与 `variables` 合计不得超过 1 MiB，请求体不得超过 2 MiB。",
         "properties": {
           "context": {
             "$ref": "#/components/schemas/DashboardDraftContext"
@@ -12470,14 +12787,15 @@
               "$ref": "#/components/schemas/DashboardVariable"
             },
             "maxItems": 20,
-            "description": "该面板可能引用的草稿变量。"
+            "description": "该面板可引用的草稿变量，最多 20 个。必填；面板查询只能使用此处列出的变量。"
           },
           "selections": {
             "type": "object",
             "additionalProperties": {
               "$ref": "#/components/schemas/DashboardSelection"
             },
-            "description": "按变量名索引的选择。"
+            "description": "按变量名索引的选择，最多 20 项。未给出的变量回退到其草稿中的默认值。",
+            "maxProperties": 20
           },
           "time": {
             "$ref": "#/components/schemas/DashboardAbsoluteTimeRange"
@@ -12489,25 +12807,24 @@
             ],
             "minimum": 2,
             "maximum": 5000,
-            "description": "降采样目标，2～5000 个点。"
+            "description": "`range` 查询每条序列的目标最大点数，服务端据此推算查询步长。取值 2～5000；省略或传 null 时默认 100。"
           }
         },
         "required": [
           "context",
           "panel",
           "variables",
-          "selections",
           "time"
         ]
       },
       "DashboardPanelPreviewResponse": {
         "type": "object",
-        "description": "草稿面板执行结果。与已存面板运行结构相同，只是不含仪表盘标识。",
+        "description": "草稿面板执行结果。与已存面板运行结构相同，只是不含 `dashboard_id` 和 `revision`。即使所有查询都失败也返回 HTTP 200；响应超过 8 MiB 时以 `EntityTooLarge`（HTTP 413）拒绝。",
         "properties": {
           "panel_id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "面板 ID。"
+            "description": "草稿面板的 ID，与请求中的 `panel.id` 相同。"
           },
           "run_state": {
             "type": "string",
@@ -12518,7 +12835,7 @@
               "cancelled",
               "error"
             ],
-            "description": "本次运行的整体状态：`success` = 全部查询成功；`partial` = 部分成功；`incompatible` = 至少一条查询与其数据源类型不兼容；`cancelled` = 运行被取消；`error` = 全部查询失败。"
+            "description": "本次运行的整体状态：`success` = 全部查询成功；`partial` = 至少一个查询成功且至少一个未成功；`cancelled` = 没有查询成功，且客户端取消了请求；`incompatible` = 没有查询成功，且至少一个查询已执行但结果与面板可视化不匹配；`error` = 没有查询成功且没有 `incompatible`（面板没有查询时也是 `error`）。"
           },
           "time": {
             "$ref": "#/components/schemas/DashboardAbsoluteTimeRange"
@@ -12528,14 +12845,14 @@
             "additionalProperties": {
               "$ref": "#/components/schemas/DashboardSelection"
             },
-            "description": "解析成功的变量选择。"
+            "description": "解析成功的变量的生效选择，按变量名索引；解析失败的变量不出现。"
           },
           "refs": {
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/DashboardPanelRunRef"
             },
-            "description": "面板中每条查询对应一个条目。"
+            "description": "面板中每条查询对应一个条目，顺序与面板中的查询一致。解析失败的查询以 `state` 为 `error` 出现。"
           },
           "display": {
             "$ref": "#/components/schemas/DashboardVizConfig"
@@ -12556,12 +12873,12 @@
       },
       "FolderItem": {
         "type": "object",
-        "description": "监控节点（目录）。目录构成树；`parent_path` 是以逗号分隔的祖先 ID 列表，调用方可据此在客户端重建树并自行搜索。",
+        "description": "监控文件夹。文件夹构成一棵树；`parent_path` 是以逗号分隔的祖先 ID 列表，调用方可据此重建树并在客户端搜索。",
         "properties": {
           "id": {
             "type": "integer",
             "format": "uint64",
-            "description": "目录 ID。"
+            "description": "文件夹 ID。更新、移动、删除该文件夹时作为 `id` 传入；在其下嵌套文件夹时作为 `parent_id` 或 `dest_parent_id`；告警规则和仪表盘上的 `folder_id` 也使用该值。"
           },
           "account_id": {
             "type": "integer",
@@ -12580,7 +12897,7 @@
           "team_id": {
             "type": "integer",
             "format": "uint64",
-            "description": "目录归属的团队；账户级时为 0。"
+            "description": "文件夹所属团队的 ID；未归属任何团队时为 0。团队成员可以查看和修改该文件夹。"
           },
           "name": {
             "type": "string",
@@ -12593,7 +12910,7 @@
           "creator_id": {
             "type": "integer",
             "format": "uint64",
-            "description": "创建者成员 ID。"
+            "description": "创建者的成员 ID；创建者始终可以查看和修改该文件夹。"
           },
           "creator_name": {
             "type": "string",
@@ -12602,7 +12919,7 @@
           "updater_id": {
             "type": "integer",
             "format": "uint64",
-            "description": "最后更新者成员 ID。"
+            "description": "最后更新人的成员 ID。更新和移动都会写入该值。"
           },
           "updater_name": {
             "type": "string",
@@ -12611,12 +12928,12 @@
           "created_at": {
             "type": "integer",
             "format": "int64",
-            "description": "Unix 时间戳（秒）。"
+            "description": "创建时间，Unix 时间戳，单位秒。"
           },
           "updated_at": {
             "type": "integer",
             "format": "int64",
-            "description": "Unix 时间戳（秒）。"
+            "description": "最后一次更新或移动的时间，Unix 时间戳，单位秒。"
           }
         },
         "required": [
@@ -12637,26 +12954,26 @@
       },
       "FolderCreateRequest": {
         "type": "object",
-        "description": "监控目录请求。",
+        "description": "创建监控文件夹的请求。",
         "properties": {
           "name": {
             "type": "string",
-            "description": "目录名称；不能包含句点、斜杠或逗号。",
+            "description": "文件夹名称；必填，不能包含句点（`.`）、斜杠（`/`）或逗号（`,`）。",
             "minLength": 1
           },
           "note": {
             "type": "string",
-            "description": "备注；更新时省略或传空字符串会清空备注。"
+            "description": "自由格式的备注。省略时为空。"
           },
           "parent_id": {
             "type": "integer",
-            "description": "父目录 ID；0 或省略时创建顶层目录。",
+            "description": "父文件夹 ID；为 0 或省略时创建根文件夹。调用方必须有权修改该父文件夹。",
             "format": "uint64",
             "minimum": 0
           },
           "team_id": {
             "type": "integer",
-            "description": "团队 ID；0 表示账户范围。更新时省略会重置为 0。",
+            "description": "文件夹所属团队的 ID；为 0 或省略表示不归属任何团队。团队成员可以查看和修改该文件夹及其下的全部内容。",
             "format": "uint64",
             "minimum": 0
           }
@@ -12667,26 +12984,26 @@
       },
       "FolderUpdateRequest": {
         "type": "object",
-        "description": "监控目录请求。",
+        "description": "更新监控文件夹的请求。可编辑字段会整体替换。",
         "properties": {
           "id": {
             "type": "integer",
-            "description": "目录 ID。",
+            "description": "要更新的文件夹 ID，来自 `/monit/folder/list` 或创建响应。",
             "format": "uint64",
             "minimum": 1
           },
           "name": {
             "type": "string",
-            "description": "目录名称；不能包含句点、斜杠或逗号。",
+            "description": "新的文件夹名称；必填，不能包含句点（`.`）、斜杠（`/`）或逗号（`,`）。",
             "minLength": 1
           },
           "note": {
             "type": "string",
-            "description": "备注；更新时省略或传空字符串会清空备注。"
+            "description": "新的备注。省略或为空会清空备注。"
           },
           "team_id": {
             "type": "integer",
-            "description": "团队 ID；0 表示账户范围。更新时省略会重置为 0。",
+            "description": "新的团队 ID；为 0 或省略会移除团队归属。",
             "format": "uint64",
             "minimum": 0
           }
@@ -12698,17 +13015,17 @@
       },
       "FolderMoveRequest": {
         "type": "object",
-        "description": "监控目录请求。",
+        "description": "移动监控文件夹及其后代的请求。",
         "properties": {
           "id": {
             "type": "integer",
-            "description": "目录 ID。",
+            "description": "要移动的文件夹 ID，来自 `/monit/folder/list`。",
             "format": "uint64",
             "minimum": 1
           },
           "dest_parent_id": {
             "type": "integer",
-            "description": "目标父目录 ID；移至顶层时必须显式传 0。",
+            "description": "新的父文件夹 ID；传 0 表示移至根级别。该字段不能省略。不能等于 `id`，也不能是该文件夹的后代。",
             "format": "uint64",
             "minimum": 0
           }
@@ -12720,11 +13037,11 @@
       },
       "FolderDeleteRequest": {
         "type": "object",
-        "description": "监控目录请求。",
+        "description": "删除监控文件夹的请求。",
         "properties": {
           "id": {
             "type": "integer",
-            "description": "目录 ID。",
+            "description": "要删除的文件夹 ID，来自 `/monit/folder/list`。该文件夹必须为空。",
             "format": "uint64",
             "minimum": 1
           }
@@ -12739,13 +13056,13 @@
         "properties": {
           "folder_id": {
             "type": "integer",
-            "description": "目录 ID。",
+            "description": "该项所描述的文件夹 ID，与 `/monit/folder/list` 中的 `id` 对应。",
             "format": "uint64",
             "minimum": 0
           },
           "has_issue": {
             "type": "boolean",
-            "description": "本目录或可见后代目录是否存在活跃告警或规则运行问题。"
+            "description": "文件夹自身或任一后代文件夹中的规则存在活跃告警或运行问题（`runtime_state` 为 `offline`、`abnormal`、`stale` 或 `no_datasource`）时为 `true`。调用方不可读文件夹中的规则不计入。"
           }
         },
         "required": [
@@ -12759,7 +13076,7 @@
         "properties": {
           "items": {
             "type": "array",
-            "description": "目录摘要列表。",
+            "description": "调用方可见的每个文件夹对应一项健康摘要，按 `folder_id` 升序排列。",
             "items": {
               "$ref": "#/components/schemas/FolderHealthItem"
             }
diff --git a/api-reference/on-call.openapi.en.json b/api-reference/on-call.openapi.en.json
index 3f68fcbff..bd1132a3d 100644
--- a/api-reference/on-call.openapi.en.json
+++ b/api-reference/on-call.openapi.en.json
@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Flashduty Open API",
-    "description": "Public HTTP API for the Flashduty incident management platform — incidents, notification templates, channels, schedules, monitors, RUM, and platform administration. Every operation is authenticated with an `app_key` query parameter issued from the Flashduty console under Account → APP Keys. Responses follow a uniform envelope: `{ request_id, data }` on success, `{ request_id, error }` on failure.",
+    "description": "Public HTTP API for the Flashduty incident management platform — incidents, notification templates, channels, schedules, monitors, RUM, and platform administration. Every operation is authenticated with an `app_key` query parameter created in the Flashduty console under My → APP Key (or sent in the `Fd-App-Key` header). Responses follow a uniform envelope: `{ request_id, data }` on success, `{ request_id, error }` on failure.",
     "version": "1.0.0"
   },
   "servers": [
@@ -75,12 +75,12 @@
       "post": {
         "operationId": "channelInhibitRuleDelete",
         "summary": "Delete inhibit rule",
-        "description": "Delete an inhibit rule. Only a `disabled` rule can be deleted.",
+        "description": "Delete a disabled inhibit rule so it no longer appears in the channel's rule list.",
         "tags": [
           "On-call/Channels"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |\n\n## Usage\n\n- Only a `disabled` rule can be deleted; any other status returns `InvalidParameter`.\n- An unknown `channel_id` or `rule_id` returns `InvalidParameter`.\n- The caller must also be able to edit the channel: the account owner or an admin, the channel creator, or a member of its managing teams (of its owning team when `managing_team_ids` is empty). Otherwise the call returns `AccessDenied`.\n- Every call is recorded in the account audit log.",
           "href": "/en/api-reference/on-call/channels/channel-inhibit-rule-delete",
           "metadata": {
             "sidebarTitle": "Delete inhibit rule"
@@ -119,6 +119,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -151,7 +154,7 @@
           "On-call/Integrations"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Integrations Read** (`on-call`) |\n\n## Usage\n\n- When `orderby` is omitted, types come back in console ranking order and `p`/`limit` still apply.\n- `supports_api_create` tells you which types `POST /integration/create` accepts.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Integrations Read** (`on-call`) |\n\n## Usage\n\n- When `orderby` is omitted, types come back in console ranking order and `p`/`limit` still apply.\n- `supports_api_create` tells you which types `POST /integration/create` accepts.\n- `category` values are not validated; an unknown value returns an empty list.",
           "href": "/en/api-reference/on-call/integrations/integration-api-read-type-list",
           "metadata": {
             "sidebarTitle": "List integration types"
@@ -212,6 +215,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -245,7 +251,7 @@
           "On-call/Integrations"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Integrations Read** (`on-call`) |\n\n## Usage\n\n- `orderby` defaults to `created_at`; `plugin_type` is sorted by the underlying plugin.\n- `plugin_type`, `status` and `category` accept comma-separated values; `ref_ids` values must start with `c_`, `a_` or `w_`; a `c_` filter is syntactically accepted but does not return channel-owned integrations.\n- With `is_my_team` set, results are limited to your teams and `team_ids` narrows that set further.\n- These APIs manage public (account-level) integrations only, not channel-owned dedicated integrations.\n- Items include `settings`, `integration_key`, `plugin_id`, `account_id`, and the legacy `data_source_id` alias. Saved secret values in `settings` are returned as `******`; `integration_key` is returned as is.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Integrations Read** (`on-call`) |\n\n## Usage\n\n- `orderby` defaults to `created_at`; `plugin_type` sorts by the underlying plugin. Rows are ordered by `ref_id` first, so `orderby` applies within each `ref_id` group.\n- `plugin_type`, `status` and `category` accept comma-separated values; `ref_ids` values must start with `c_`, `a_` or `w_`; a `c_` filter is syntactically accepted but does not return channel-owned integrations.\n- With `is_my_team` set, results are limited to your teams and `team_ids` narrows that set further; when you belong to no team, or `team_ids` shares no team with yours, the list is empty.\n- These APIs manage public (account-level) integrations only, not channel-owned dedicated integrations.\n- Items include `settings`, `integration_key`, `plugin_id`, `account_id`, and the legacy `data_source_id` alias. Saved secret values in `settings` are returned as `******`; `integration_key` is returned as is.",
           "href": "/en/api-reference/on-call/integrations/integration-api-read-list",
           "metadata": {
             "sidebarTitle": "List integrations"
@@ -317,6 +323,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -350,7 +359,7 @@
           "On-call/Integrations"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Integrations Read** (`on-call`) |\n\n## Usage\n\n- These APIs manage public (account-level) integrations only, not channel-owned dedicated integrations.\n- Saved secret values in `settings` are returned as `******`, and unset ones stay empty. The integration key is returned as is.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Integrations Read** (`on-call`) |\n\n## Usage\n\n- These APIs manage public (account-level) integrations only, not channel-owned dedicated integrations.\n- Saved secret values in `settings` are returned as `******`, and unset ones stay empty. The integration key is returned as is.\n- An unknown ID, or the ID of a channel-owned integration, returns `ResourceNotFound`.",
           "href": "/en/api-reference/on-call/integrations/integration-api-read-info",
           "metadata": {
             "sidebarTitle": "Get integration detail"
@@ -412,6 +421,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -443,7 +455,7 @@
           "On-call/Integrations"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Integrations Manage** (`on-call`) |\n\n## Usage\n\n- `plugin_type` must be one of the types listed by `POST /integration/type/list` with `supports_api_create: true`; anything else returns `InvalidParameter`.\n- These APIs manage public (account-level) integrations only, not channel-owned dedicated integrations.\n- An omitted `integration_key` is generated automatically; a supplied key must satisfy the length, account suffix, and uniqueness checks.\n- With `is_test: true`, inspect `test.success`; an HTTP 200 response alone does not establish that the plugin test succeeded.\n- Every call is recorded in the account audit log.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Integrations Manage** (`on-call`) |\n\n## Usage\n\n- `plugin_type` must be one of the types listed by `POST /integration/type/list` with `supports_api_create: true`; anything else returns `InvalidParameter`.\n- A type whose `status` is `disabled` returns `InvalidParameter`; a type not included in the account's plan returns `NoLicense`.\n- These APIs manage public (account-level) integrations only, not channel-owned dedicated integrations.\n- An omitted `integration_key` is generated automatically; a supplied key must satisfy the length, account suffix, and uniqueness checks.\n- With `is_test: true`, inspect `test.success`; an HTTP 200 response alone does not establish that the plugin test succeeded.\n- Every call is recorded in the account audit log.",
           "href": "/en/api-reference/on-call/integrations/integration-api-write-create",
           "metadata": {
             "sidebarTitle": "Create integration"
@@ -489,6 +501,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -528,7 +543,7 @@
           "On-call/Integrations"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Integrations Manage** (`on-call`) |\n\n## Usage\n\n- Only the fields you send are changed; omitted fields keep their current value.\n- Submitting `settings` replaces the configuration; known sensitive fields omitted or sent as `******` retain their value. Keeping a stored secret while changing where it is sent (such as `endpoint`, `url`, a database host or port, or an IM API base URL) is rejected, so send the secrets again with the new destination; `******` on a field with no stored value is rejected too. Send `headers: {}` to clear headers; use the integration type’s explicit empty value to clear a body.\n- Submit `settings` together with `is_test: true` to receive a plugin test result; secrets in the returned settings are masked the same way.\n- These APIs manage public (account-level) integrations only, not channel-owned dedicated integrations.\n- Write access also requires object permission: the account owner, an administrator, the creator, or a member of the assigned team; with no team, members with Integrations Manage may operate. Read-only integrations cannot be changed.\n- Every call is recorded in the account audit log.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Integrations Manage** (`on-call`) |\n\n## Usage\n\n- Only the fields you send are changed; omitted fields keep their current value.\n- Submitting `settings` replaces the configuration; known sensitive fields omitted or sent as `******` retain their value. Keeping a stored secret while changing where it is sent (such as `endpoint`, `url`, a database host or port, or an IM API base URL) is rejected, so send the secrets again with the new destination; `******` on a field with no stored value is rejected too. Send `headers: {}` to clear headers; use the integration type’s explicit empty value to clear a body.\n- Submit `settings` together with `is_test: true` to receive a plugin test result; secrets in the returned settings are masked the same way.\n- If another request changes the same integration's settings while this one is being processed, the call returns `RequestLocked`; retry it. A type no longer included in the account's plan returns `NoLicense`.\n- These APIs manage public (account-level) integrations only, not channel-owned dedicated integrations.\n- Write access also requires object permission: the account owner, an administrator, the creator, or a member of the assigned team; with no team, members with Integrations Manage may operate. Read-only integrations cannot be changed.\n- Every call is recorded in the account audit log.",
           "href": "/en/api-reference/on-call/integrations/integration-api-write-update",
           "metadata": {
             "sidebarTitle": "Update integration"
@@ -594,6 +609,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -671,6 +689,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -702,7 +723,7 @@
           "On-call/Integrations"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Integrations Manage** (`on-call`) |\n\n## Usage\n\n- Enabling an integration resumes its scheduled pull task and heartbeat, and requires the integration type to be available on the current plan.\n- Every call is recorded in the account audit log.\n- These APIs manage public (account-level) integrations only, not channel-owned dedicated integrations.\n- Write access also requires object permission: the account owner, an administrator, the creator, or a member of the assigned team; with no team, members with Integrations Manage may operate. Read-only integrations cannot be changed.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Integrations Manage** (`on-call`) |\n\n## Usage\n\n- Enabling an integration resumes its scheduled pull task and heartbeat, and requires the integration type to be available on the current plan.\n- Enabling an integration that is already enabled succeeds without change; the same holds for disabling a disabled one.\n- Every call is recorded in the account audit log.\n- These APIs manage public (account-level) integrations only, not channel-owned dedicated integrations.\n- Write access also requires object permission: the account owner, an administrator, the creator, or a member of the assigned team; with no team, members with Integrations Manage may operate. Read-only integrations cannot be changed.",
           "href": "/en/api-reference/on-call/integrations/integration-api-write-enable",
           "metadata": {
             "sidebarTitle": "Enable integration"
@@ -741,6 +762,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -772,7 +796,7 @@
           "On-call/Integrations"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Integrations Manage** (`on-call`) |\n\n## Usage\n\n- Disabling stops event ingestion and pauses the scheduled pull task; settings are kept so the integration can be enabled again.\n- Every call is recorded in the account audit log.\n- These APIs manage public (account-level) integrations only, not channel-owned dedicated integrations.\n- Write access also requires object permission: the account owner, an administrator, the creator, or a member of the assigned team; with no team, members with Integrations Manage may operate. Read-only integrations cannot be changed.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Integrations Manage** (`on-call`) |\n\n## Usage\n\n- Disabling stops event ingestion and pauses the scheduled pull task; settings are kept so the integration can be enabled again.\n- Enabling an integration that is already enabled succeeds without change; the same holds for disabling a disabled one.\n- Every call is recorded in the account audit log.\n- These APIs manage public (account-level) integrations only, not channel-owned dedicated integrations.\n- Write access also requires object permission: the account owner, an administrator, the creator, or a member of the assigned team; with no team, members with Integrations Manage may operate. Read-only integrations cannot be changed.",
           "href": "/en/api-reference/on-call/integrations/integration-api-write-disable",
           "metadata": {
             "sidebarTitle": "Disable integration"
@@ -811,6 +835,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -883,6 +910,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -914,7 +944,7 @@
           "On-call/Alert enrichment"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Mappings Manage** (`on-call`) |\n\n## Usage\n\n- This is an irreversible bulk-delete operation.\n- High-risk operation. Console JWT callers must pass a second-factor code; `app_key` callers bypass the MFA prompt but remain audited — treat the key as a secret.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Mappings Manage** (`on-call`) |\n\n## Usage\n\n- Permanently deletes every data row of the schema; the schema itself is kept.\n- The schema must exist and not be deleted; otherwise `InvalidParameter`.\n- Only an account admin, the schema creator, or a member of the schema's owning team may call this; others get `AccessDenied`.\n- Data writes to one schema (upsert, delete, truncate, CSV upload) run one at a time; a call made while another is running returns `RequestTooFrequently`.",
           "href": "/en/api-reference/on-call/alert-enrichment/mapping-data-write-truncate",
           "metadata": {
             "sidebarTitle": "Truncate mapping data"
@@ -953,6 +983,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -984,7 +1017,7 @@
           "On-call/Alert enrichment"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Returns `null` if the API does not exist.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Returns `data: null` when no mapping API with this ID exists in the account.\n- A soft-deleted mapping API is still returned, with `status` = `deleted`.\n- There is no team check: any caller in the account can read any mapping API, including its `headers` in plain text.",
           "href": "/en/api-reference/on-call/alert-enrichment/mapping-api-read-info",
           "metadata": {
             "sidebarTitle": "Get mapping API detail"
@@ -1015,12 +1048,18 @@
                   "data": {
                     "api_id": "665f1a2b3c4d5e6f7a8b9c02",
                     "api_name": "CMDB API",
+                    "description": "Query CMDB for host metadata",
                     "url": "https://cmdb.example.com/api/lookup",
+                    "headers": {
+                      "X-Token": "example-token"
+                    },
                     "timeout": 2,
                     "retry_count": 1,
                     "insecure_skip_verify": false,
                     "status": "enabled",
+                    "team_id": 0,
                     "creator_id": 80011,
+                    "updated_by": 80011,
                     "created_at": 1710000000,
                     "updated_at": 1710000000
                   }
@@ -1034,6 +1073,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -1065,7 +1107,7 @@
           "On-call/Status pages"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Poll until `status` is no longer `running`; `progress.completed_steps` out of `progress.total_steps` shows how far the job is.\n- Job state is kept for 24 hours after its last update; after that the call returns `ResourceNotFound`.\n- A `job_id` that belongs to another account returns `AccessDenied`.",
           "href": "/en/api-reference/on-call/status-pages/status-page-migration-status",
           "metadata": {
             "sidebarTitle": "Get migration status"
@@ -1124,6 +1166,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -1148,12 +1193,12 @@
       "post": {
         "operationId": "channelEscalateRuleInfo",
         "summary": "Get escalation rule detail",
-        "description": "Retrieve detailed information for a specific escalation rule.",
+        "description": "Return one escalation rule of a channel, including its levels, time windows and filters.",
         "tags": [
           "On-call/Channels"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Read** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Read** (`on-call`) or **Channels Manage** (`on-call`) or **Incidents Read** (`on-call`) or **Incidents Manage** (`on-call`) |\n\n## Usage\n\n- A deleted rule is still returned, with `status` `deleted`.\n- An unknown `channel_id` or `rule_id` returns `InvalidParameter`.",
           "href": "/en/api-reference/on-call/channels/channel-escalate-rule-info",
           "metadata": {
             "sidebarTitle": "Get escalation rule detail"
@@ -1224,6 +1269,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -1256,7 +1304,7 @@
           "On-call/Alert enrichment"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Integrations Read** (`on-call`) or **Integrations Manage** (`on-call`) or **Mappings Read** (`on-call`) or **Mappings Manage** (`on-call`) |\n\n## Usage\n\n- If `query` is provided, all source labels must be specified — partial source label queries are rejected.\n- Pagination uses cursor-based (`search_after_ctx`) or page-based (`p`, `limit`) navigation. `limit` defaults to 20, max 100.\n- The `search_after_ctx` token from a response can be passed back to retrieve the next page.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Integrations Read** (`on-call`) or **Integrations Manage** (`on-call`) or **Mappings Read** (`on-call`) or **Mappings Manage** (`on-call`) |\n\n## Usage\n\n- The schema must exist and not be deleted; otherwise `InvalidParameter`.\n- `query` filters by exact source label values. Keys that are not source labels are dropped; if any key remains, every source label must be given, otherwise `InvalidParameter`.\n- Page-based navigation (`p`, `limit`) reaches at most 10,000 rows (`p * limit <= 10000`); go further with `search_after_ctx`.\n- `total` counts at most 1,000 matching rows; `used_cnt` is the schema's full row count.",
           "href": "/en/api-reference/on-call/alert-enrichment/mapping-data-read-list",
           "metadata": {
             "sidebarTitle": "List mapping data"
@@ -1287,7 +1335,7 @@
                   "data": {
                     "items": [
                       {
-                        "key": "server01",
+                        "key": "02b8754747905747f7f76d802202d214",
                         "fields": {
                           "host": "server01",
                           "owner": "alice",
@@ -1299,7 +1347,8 @@
                       }
                     ],
                     "total": 1,
-                    "has_next_page": false
+                    "has_next_page": false,
+                    "used_cnt": 1
                   }
                 }
               }
@@ -1311,6 +1360,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -1341,12 +1393,12 @@
       "post": {
         "operationId": "incidentPastList",
         "summary": "List past incidents",
-        "description": "List historical incidents related to the current incident for reference during triage.",
+        "description": "List closed incidents in the same channel that resemble a given incident, to reuse past root causes and resolutions.",
         "tags": [
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **100 requests/minute**; **20 requests/second** per account |\n| Permissions | **Incidents Read** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **100 requests/minute**; **5 requests/second** per account |\n| Permissions | **Incidents Read** or **Incidents Manage** or **Channels Read** or **Channels Manage** (`on-call`) |\n\n## Usage\n\n- Requires the Professional edition or higher; otherwise the call fails with `NoLicense`.\n- Candidates are closed incidents in the same channel that started within the 30 days before the reference incident started and whose semantic similarity exceeds the channel's similarity threshold.\n- Results list incidents with longer `root_cause` plus `resolution` text first, then higher `score`, then more recent `start_time`.\n- `limit` defaults to 5 when omitted or `0`.\n- An empty `items` array means no similar incident was found, or the reference incident has not been indexed for similarity search yet.\n- The reference incident must belong to a channel; otherwise the call fails with `InvalidParameter`.",
           "href": "/en/api-reference/on-call/incidents/incident-past-list",
           "metadata": {
             "sidebarTitle": "List past incidents"
@@ -1387,6 +1439,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -1414,12 +1469,12 @@
       "post": {
         "operationId": "incidentSnooze",
         "summary": "Snooze incident",
-        "description": "Temporarily snooze notifications for an incident until a specified time.",
+        "description": "Pause notifications for acknowledged incidents for a given number of minutes.",
         "tags": [
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Incidents Manage** or **Channels Manage** (`on-call`) |\n\n## Usage\n\n- Only incidents in `Processing` progress can be snoozed; any other progress fails the whole call with `InvalidParameter`.\n- Notifications resume automatically after `minutes` elapse, or earlier through `POST /incident/wake`. The snooze end time is stored in the incident's `snoozed_before` (Unix seconds).\n- The snooze is also cleared when the incident is reassigned or returns to `Triggered`.",
           "href": "/en/api-reference/on-call/incidents/incident-snooze",
           "metadata": {
             "sidebarTitle": "Snooze incident"
@@ -1458,6 +1513,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -1487,12 +1545,12 @@
       "post": {
         "operationId": "statusPageSubscriberExport",
         "summary": "Export subscribers",
-        "description": "Export subscribers list for a status page as a CSV attachment. The response is a `text/csv` file with columns: Method, Recipient, Components, Subscribe All, Locale.",
+        "description": "Export the subscribers of a status page as a CSV file.",
         "tags": [
           "On-call/Status pages"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **100 requests/day**; **20 requests/minute**; **10 requests/second** per account |\n| Permissions | **Status Pages Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **100 requests/day**; **20 requests/minute**; **10 requests/second** per account |\n| Permissions | **Status Pages Manage** (`on-call`) |\n\n## Usage\n\n- Requires the On-call Standard plan or higher; other accounts get `AccessDenied`.\n- The response is a `text/csv` attachment, not a JSON envelope, with the columns Method, Recipient, Components, Subscribe All (`Yes`/`No`), and Locale.\n- Components lists component names joined by `, `; a component inside a section is written as `Section › Component`.\n- Public pages export email subscribers and internal pages export IM subscribers; filtering by `component_ids` also includes subscribers of all components.",
           "href": "/en/api-reference/on-call/status-pages/status-page-subscriber-export",
           "metadata": {
             "sidebarTitle": "Export subscribers"
@@ -1516,6 +1574,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -1542,12 +1603,12 @@
       "post": {
         "operationId": "insightByTeam",
         "summary": "Get team insight",
-        "description": "Return insight metrics aggregated by team.",
+        "description": "Return incident and alert metrics grouped by team, one row per team per time bucket.",
         "tags": [
           "On-call/Analytics"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Analytics Read** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Analytics Read** (`on-call`) |\n\n## Usage\n\n- One row per team per time bucket. Incidents without a team are aggregated into a row that has no `team_id`. `responder_ids` and `incident_ids` are ignored.\n- Incidents are counted by creation time. Rows are sorted by `ts` from newest to oldest, and a bucket (or dimension value) with no incidents produces no row — missing rows mean zero. `split_hours: true` returns up to three rows per bucket, one per `hours` value.\n- `total_alert_cnt`, `total_alert_event_cnt` and `noise_reduction_pct` honor only the time range, team, channel and severity filters; `query`, `labels`, `fields` and the duration filters apply to incident metrics only.\n- Members who are neither the account owner nor an admin only get data from channels they can access; other channels are silently excluded.\n- With `is_my_team: true`, `team_ids` is narrowed to the caller's teams; a caller who belongs to no team gets an empty result.",
           "href": "/en/api-reference/on-call/analytics/insight-by-team",
           "metadata": {
             "sidebarTitle": "Get team insight"
@@ -1615,6 +1676,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -1646,12 +1710,12 @@
       "post": {
         "operationId": "insightChannelExport",
         "summary": "Export channel insight",
-        "description": "Export channel insight metrics as a CSV file — one row per channel (and per time/hour bucket when `aggregate_unit`/`split_hours` is used). The response is a CSV stream delivered with `Content-Disposition: attachment` — it is not a JSON envelope. `time_zone` defaults to UTC. Rows without a valid channel ID are skipped. Valid `export_fields` keys: channel_id, channel_name, total_incident_cnt, total_incidents_acknowledged, total_incidents_closed, total_incidents_auto_closed, total_incidents_manually_closed, total_incidents_timeout_closed, total_incidents_escalated, total_incidents_manually_escalated, total_incidents_timeout_escalated, total_incidents_reassigned, total_interruptions, total_notifications, total_engaged_seconds, mean_seconds_to_ack, mean_seconds_to_close, noise_reduction_pct, acknowledgement_pct, total_alert_cnt, total_alert_event_cnt, hours. The `hours` column is included by default only when `split_hours` is true. For compatibility, incident-export column keys are also accepted but produce empty columns.",
+        "description": "Export channel insight metrics as a CSV file with the same rows as `/insight/channel`.",
         "tags": [
           "On-call/Analytics"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **100 requests/day**; **20 requests/minute**; **10 requests/second** per account |\n| Permissions | **Analytics Read** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **100 requests/day**; **20 requests/minute**; **10 requests/second** per account |\n| Permissions | **Analytics Read** (`on-call`) |\n\n## Usage\n\n- The response is a CSV file (`Content-Type: application/octet-stream`), not a JSON envelope. Validation errors are returned as JSON before any CSV bytes are written.\n- Takes the same filters as `/insight/channel`. Rows without a channel ID are skipped. The file has no time-bucket column, so with `aggregate_unit` the rows of different buckets cannot be told apart; export one bucket per request if you need the split.\n- `export_fields` sets the columns and their order: channel_id, channel_name, total_incident_cnt, total_incidents_acknowledged, total_incidents_closed, total_incidents_auto_closed, total_incidents_manually_closed, total_incidents_timeout_closed, total_incidents_escalated, total_incidents_manually_escalated, total_incidents_timeout_escalated, total_incidents_reassigned, total_interruptions, total_notifications, total_engaged_seconds, mean_seconds_to_ack, mean_seconds_to_close, noise_reduction_pct, acknowledgement_pct, total_alert_cnt, total_alert_event_cnt, hours. Unknown or duplicate keys are rejected. When it is omitted, all columns are exported, and `hours` is included only when `split_hours` is true.\n- The incident-snapshot keys (progress, assigned_to, raw_assigned_to, escalate_rule_name, responders, raw_responders, ackers, owner_id, owner_name, creator_id, creator_name, closer_id, closer_name, snooze_status, snoozed_before, ever_muted, frequency, is_rare, alert_cnt, active_alert_cnt, alert_event_cnt, description, labels, fields) are also accepted for compatibility and produce empty columns.\n- Column headers are localized (request locale, then the member's, then the account's). Time buckets follow `time_zone` (UTC when omitted).",
           "href": "/en/api-reference/on-call/analytics/insight-channel-export",
           "metadata": {
             "sidebarTitle": "Export channel insight"
@@ -1665,7 +1729,7 @@
                 "schema": {
                   "type": "string",
                   "format": "binary",
-                  "description": "CSV file stream (`Content-Type: application/octet-stream`, `Content-Disposition: attachment; filename=channel_export_yyyyMMdd_HHmmss.csv`). The first row holds localized column headers. Columns default to the full field set, or the keys given in `export_fields`."
+                  "description": "CSV file (`Content-Type: application/octet-stream`, `Content-Disposition: attachment; filename*=UTF-8''channel_export_yyyyMMdd_HHmmss.csv`). The first row holds localized column headers."
                 },
                 "example": "channel_id,channel_name,total_incident_cnt,total_incidents_closed\n4321322010131,Production Alerts,12,10\n"
               }
@@ -1677,6 +1741,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -1716,7 +1783,7 @@
           "On-call/Alerts"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Integrations Manage** (`on-call`) |\n\n## Usage\n\n- Maximum 50 rules per pipeline.\n- Each rule has a `kind` (one of `title_reset`, `description_reset`, `severity_reset`, `alert_drop`, `alert_inhibit`), an optional `if` filter, and `settings` specific to the kind.\n- The `alert_inhibit` kind requires the Standard license or higher.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) or **Integrations Manage** (`on-call`) |\n\n## Usage\n\n- Replaces the integration's whole rule list with `rules`; an empty array removes every rule. At most 50 rules.\n- Rules run in array order on each incoming event of the integration before it becomes an alert; `alert_drop`, or an `alert_inhibit` that matches, discards the event and stops processing.\n- `integration_id` may be an account-level or a channel-owned integration; an ID not in the account returns `InvalidParameter`.\n- Write access also requires object permission: the account owner, an administrator, the integration creator, or a member of its team (for a channel-owned integration, a member of the channel's team); with no team, any caller with the API permission may write.\n- An `alert_inhibit` rule requires the Standard plan or higher; otherwise the call returns `NoLicense`.\n- On success the response carries only `request_id`; the `data` field is omitted.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/on-call/alerts/alert-write-pipeline-upsert",
           "metadata": {
             "sidebarTitle": "Create or update alert pipeline"
@@ -1743,8 +1810,7 @@
                   ]
                 },
                 "example": {
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
-                  "data": null
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
             }
@@ -1755,6 +1821,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -1810,7 +1879,7 @@
           "On-call/Status pages"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Returns every affected component, including hidden ones; component names, sections, and order reflect the page's current configuration.\n- Returns `ResourceNotFound` when the page or the event does not exist.",
           "href": "/en/api-reference/on-call/status-pages/status-page-change-info",
           "metadata": {
             "sidebarTitle": "Get status page event detail"
@@ -1897,6 +1966,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -1932,12 +2004,12 @@
       "post": {
         "operationId": "incidentResolve",
         "summary": "Resolve incident",
-        "description": "Mark an incident as resolved.",
+        "description": "Close one or more incidents, optionally recording root cause, resolution, and resolution form values.",
         "tags": [
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |\n\n## Usage\n\n- When a resolution form applies, `custom_fields`, `summary`, and `images` must match its visible elements and required rules.\n- For a batch, form values are accepted only when every selected incident resolves to the same form; otherwise resolve incidents individually.\n- The legacy `values` and `custom_values` properties are rejected; use `custom_fields`.\n- Audited — changes are recorded in the audit log.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Incidents Manage** or **Channels Manage** (`on-call`) |\n\n## Usage\n\n- When a resolution form applies, `custom_fields`, `summary`, and `images` must match its visible elements and required rules.\n- For a batch, form values are accepted only when every selected incident resolves to the same form; otherwise resolve incidents individually.\n- The legacy `values` and `custom_values` properties are rejected; use `custom_fields`.\n- Incidents that are already closed are skipped without error; an unknown ID fails the whole call with `InvalidParameter`.\n- Resolving a `Triggered` incident first acknowledges it on behalf of the caller.\n- After closing, unfinished action items of the incident are converted to follow-ups, and later events no longer merge into the incident's existing alerts.\n- Returns `RequestTooFrequently` while another resolve, reopen, merge, comment, or delete is running in the same account; retry after a short delay.",
           "href": "/en/api-reference/on-call/incidents/incident-resolve",
           "metadata": {
             "sidebarTitle": "Resolve incident"
@@ -1976,6 +2048,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -2006,12 +2081,12 @@
       "post": {
         "operationId": "incidentWarRoomList",
         "summary": "List war rooms",
-        "description": "List all war rooms associated with an incident.",
+        "description": "List the IM war room groups linked to an incident.",
         "tags": [
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Read** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Read** or **Incidents Manage** or **Channels Read** or **Channels Manage** (`on-call`) |\n\n## Usage\n\n- War rooms whose IM integration is disabled or deleted are still returned, with `integration_unavailable` set to `true`.\n- Use `chat_id` and `integration_id` with `POST /incident/war-room/detail` to read the group's current name and join link.",
           "href": "/en/api-reference/on-call/incidents/incident-war-room-list",
           "metadata": {
             "sidebarTitle": "List war rooms"
@@ -2040,7 +2115,19 @@
                 "example": {
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
-                    "items": []
+                    "items": [
+                      {
+                        "account_id": 2451002751131,
+                        "integration_id": 2490562293131,
+                        "created_by": 2476444212131,
+                        "chat_id": "oc_a0553eda9014c2de1b3a8f75b4e0c000",
+                        "incident_id": "69da451ef77b1b51f40e83ee",
+                        "status": "enabled",
+                        "created_at": 1775972300,
+                        "plugin_type": "feishu_app",
+                        "chat_name": "Incident #0E83EE war room"
+                      }
+                    ]
                   }
                 }
               }
@@ -2052,6 +2139,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -2083,7 +2173,7 @@
           "On-call/Alerts"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Read** (`on-call`) |\n\n## Usage\n\n- Both `start_time` and `end_time` are required Unix epoch seconds. Maximum span is 31 days.\n- Use `search_after_ctx` from the previous response to fetch the next page.\n- Results are filtered by the caller's channel data-access permissions.\n- Set `is_active` to `true` to retrieve only active (firing) alerts; `false` to retrieve resolved alerts.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Read** (`on-call`) or **Channels Manage** (`on-call`) or **Incidents Read** (`on-call`) or **Incidents Manage** (`on-call`) or **Integrations Read** (`on-call`) or **Integrations Manage** (`on-call`) |\n\n## Usage\n\n- `start_time` and `end_time` are required Unix seconds and filter on the alert's `start_time`; the span must not exceed 31 days.\n- With `by_updated_at: true`, an `updated_at` window with the same bounds is added on top of the `start_time` filter, and the span must not exceed 7 days.\n- A `start_time` earlier than the account's data retention period is moved up to the retention start; an `end_time` before that start returns `InvalidParameter`.\n- Pass `search_after_ctx` from the previous response for the next page; without it, `p`/`limit` page numbers apply and `p * limit` must stay within 10,000.\n- `total` is capped at 1,000. In page-number mode `has_next_page` is computed from that capped total, so it turns `false` once you reach 1,000 alerts even when more match. Every non-empty page returns `search_after_ctx` for its last alert; to read past 1,000, pass it back and continue in cursor mode, where `has_next_page` is exact.\n- Results are filtered by the caller's channel data-access permissions.\n- Set `is_active` to `true` to retrieve only active (firing) alerts; `false` to retrieve resolved alerts.",
           "href": "/en/api-reference/on-call/alerts/alert-read-list",
           "metadata": {
             "sidebarTitle": "List alerts"
@@ -2137,7 +2227,8 @@
                         "channel_name": "Production",
                         "event_cnt": 3
                       }
-                    ]
+                    ],
+                    "search_after_ctx": "663a1b2c3d4e5f6789abcdef"
                   }
                 }
               }
@@ -2149,6 +2240,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -2178,12 +2272,12 @@
       "post": {
         "operationId": "statusPageChangeUpdate",
         "summary": "Update status page event",
-        "description": "Update an existing status page event.",
+        "description": "Update the title, responders, or linked events of a status page event.",
         "tags": [
           "On-call/Status pages"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Status Pages Events Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Status Pages Events Manage** (`on-call`) |\n\n## Usage\n\n- Status, description, and component impact cannot be changed here; post a timeline entry with `POST /status-page/change/timeline/create` instead.\n- An omitted or empty `responders` or `linked_changes` keeps the current list, so these lists cannot be cleared through this endpoint.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/on-call/status-pages/status-page-change-update",
           "metadata": {
             "sidebarTitle": "Update status page event"
@@ -2222,6 +2316,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -2255,7 +2352,7 @@
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Read** (`on-call`) |\n\n## Usage\n\n- Set `include_events=true` only when you need a preview of each alert's raw events.\n- Event previews are capped at the 20 newest events per alert. Use `POST /alert/event/list` for a full paginated event history.\n- `event_cnt` still reports the total number of raw events merged into each alert.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Read** or **Incidents Manage** or **Channels Read** or **Channels Manage** (`on-call`) |\n\n## Usage\n\n- Set `include_events=true` only when you need a preview of each alert's raw events.\n- Event previews are capped at the 20 newest events per alert. Use `POST /alert/event/list` for a full paginated event history.\n- `event_cnt` still reports the total number of raw events merged into each alert.\n- `p` defaults to 1; `limit` omitted or `0` returns up to 1,000 alerts per page.",
           "href": "/en/api-reference/on-call/incidents/incident-alert-list",
           "metadata": {
             "sidebarTitle": "List alerts of incident"
@@ -2351,6 +2448,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -2381,12 +2481,12 @@
       "post": {
         "operationId": "channelEscalateRuleUpdate",
         "summary": "Update escalation rule",
-        "description": "Update an existing escalation rule configuration.",
+        "description": "Replace the configuration of an existing escalation rule.",
         "tags": [
           "On-call/Channels"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |\n\n## Usage\n\n- Full replacement: omitted `description`, `aggr_window`, `time_filters` and `filters` are reset to empty or `0`. Only `priority` keeps its current value when omitted.\n- Validation is the same as for create. The rule's `status` is not changed; use the enable and disable endpoints.\n- An unknown `channel_id` or `rule_id` returns `InvalidParameter`.\n- The caller must also be able to edit the channel: the account owner or an admin, the channel creator, or a member of its managing teams (of its owning team when `managing_team_ids` is empty). Otherwise the call returns `AccessDenied`.\n- Every call is recorded in the account audit log.",
           "href": "/en/api-reference/on-call/channels/channel-escalate-rule-update",
           "metadata": {
             "sidebarTitle": "Update escalation rule"
@@ -2425,6 +2525,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -2471,12 +2574,12 @@
       "post": {
         "operationId": "calEventUpsert",
         "summary": "Upsert calendar event",
-        "description": "Create or update an event the calendar owns (a day off or a working-day override) over the days [start_at, end_at). Omit event_id to create a new event; a given event_id must be an existing event of this calendar. The write clears the calendar's other own events off the same days: an event fully inside the range is deleted, one partly inside is shortened, and one spanning the range is split in two, so the latest write decides those days. end_at must be later than start_at.",
+        "description": "Create or update one of a personal calendar's own events: a day off or a working-day override.",
         "tags": [
           "On-call/Calendars"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Calendars Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Calendars Manage** (`on-call`) |\n\n## Usage\n\n- The event covers the days [`start_at`, `end_at`), dates in `YYYY-MM-DD`; `end_at` must be later than `start_at`.\n- Omit `event_id` to create an event; a given `event_id` must be an existing event of this calendar.\n- The write clears the calendar's other own events off the same days: an event fully inside the range is deleted, one partly inside is shortened, and one spanning the range is split in two, so the latest write decides those days.\n- Only personal calendars can be changed, and only by the account owner, an administrator, the calendar creator, or a member of the calendar's team; other callers get `AccessDenied`.\n- Every call is recorded in the account audit log.",
           "href": "/en/api-reference/on-call/calendars/cal-event-upsert",
           "metadata": {
             "sidebarTitle": "Upsert calendar event"
@@ -2519,6 +2622,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -2550,12 +2656,12 @@
       "post": {
         "operationId": "statusPageChangeDelete",
         "summary": "Delete status page event",
-        "description": "Delete a status page event.",
+        "description": "Delete an incident or maintenance event from a status page.",
         "tags": [
           "On-call/Status pages"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Status Pages Events Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Status Pages Events Manage** (`on-call`) |\n\n## Usage\n\n- Deleting an event that does not exist returns success.\n- Subscriptions to this event are removed, and the scheduled transitions of an auto-updating maintenance are cancelled.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/on-call/status-pages/status-page-change-delete",
           "metadata": {
             "sidebarTitle": "Delete status page event"
@@ -2594,6 +2700,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -2621,12 +2730,12 @@
       "post": {
         "operationId": "incidentWarRoomDetail",
         "summary": "Get war room detail",
-        "description": "Retrieve the war room configuration and members for an incident.",
+        "description": "Fetch the current name and join link of a war room group from the IM platform.",
         "tags": [
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Read** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Read** or **Incidents Manage** or **Channels Read** (`on-call`) |\n\n## Usage\n\n- Supported for Feishu, DingTalk, WeCom, and Slack IM integrations; other integrations fail with `InvalidParameter`.\n- If the IM platform lookup fails (for example, the group was dissolved outside Flashduty), the call still succeeds and every field is an empty string.",
           "href": "/en/api-reference/on-call/incidents/incident-war-room-detail",
           "metadata": {
             "sidebarTitle": "Get war room detail"
@@ -2669,6 +2778,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -2696,12 +2808,12 @@
       "post": {
         "operationId": "calendarDelete",
         "summary": "Delete calendar",
-        "description": "Delete a personal service calendar. The call fails when referenced by escalation or silence rules.",
+        "description": "Delete a personal service calendar and its events when no rule references it.",
         "tags": [
           "On-call/Calendars"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Calendars Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Calendars Manage** (`on-call`) |\n\n## Usage\n\n- If escalation rules or silence rules still use the calendar, the call returns HTTP 400 with `error.code` = `ReferenceExist` and `data.refs` listing them.\n- The calendar's own events are deleted together with it.\n- Only personal calendars can be changed, and only by the account owner, an administrator, the calendar creator, or a member of the calendar's team; other callers get `AccessDenied`.\n- Every call is recorded in the account audit log.",
           "href": "/en/api-reference/on-call/calendars/calendar-delete",
           "metadata": {
             "sidebarTitle": "Delete calendar"
@@ -2740,6 +2852,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -2771,7 +2886,7 @@
           "On-call/Alerts"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Read** (`on-call`) |\n\n## Usage\n\n- Results are newest-first by default. Set `asc=true` to read events oldest-first.\n- Use `limit` with `search_after_ctx` from the previous response to fetch the next page.\n- Classic page-number pagination is also supported with `p`, but `p * limit` must stay within 10,000 records.\n- Each alert can accumulate a large raw event history; prefer cursor pagination for hot alerts.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Read** (`on-call`) or **Channels Manage** (`on-call`) or **Incidents Read** (`on-call`) or **Incidents Manage** (`on-call`) |\n\n## Usage\n\n- Results are newest-first by default. Set `asc=true` to read events oldest-first.\n- Use `limit` with `search_after_ctx` from the previous response to fetch the next page.\n- Classic page-number pagination is also supported with `p`, but `p * limit` must stay within 10,000 records.\n- An `alert_id` not found in the account returns `InvalidParameter`.",
           "href": "/en/api-reference/on-call/alerts/alert-read-event-list",
           "metadata": {
             "sidebarTitle": "List events for an alert"
@@ -2827,6 +2942,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -2859,7 +2977,7 @@
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Incidents Manage** or **Channels Manage** (`on-call`) |\n\n## Usage\n\n- All alerts of the source incidents move to the target incident, and the target gains the sources' integrations.\n- Source incidents that are still open are closed. With `remove_source_incidents: true` they are then permanently deleted; otherwise they stay closed with an `i_merge` timeline entry that points to the target.\n- The target's progress, responders, and assignment do not change; `title`, when set, replaces the target's title.\n- Returns `RequestTooFrequently` while another resolve, reopen, merge, comment, or delete is running in the same account; retry after a short delay.",
           "href": "/en/api-reference/on-call/incidents/incident-merge",
           "metadata": {
             "sidebarTitle": "Merge incidents"
@@ -2898,6 +3016,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -2934,7 +3055,7 @@
           "On-call/Alert enrichment"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Mappings Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Mappings Manage** (`on-call`) |\n\n## Usage\n\n- `keys` are the row `key` values returned by `/enrichment/mapping/data/list` or `/enrichment/mapping/data/upsert`; keys that match no row are ignored.\n- The schema must exist and not be deleted; otherwise `InvalidParameter`.\n- Only an account admin, the schema creator, or a member of the schema's owning team may call this; others get `AccessDenied`.\n- Data writes to one schema (upsert, delete, truncate, CSV upload) run one at a time; a call made while another is running returns `RequestTooFrequently`.",
           "href": "/en/api-reference/on-call/alert-enrichment/mapping-data-write-delete",
           "metadata": {
             "sidebarTitle": "Delete mapping data rows"
@@ -2973,6 +3094,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -3003,12 +3127,12 @@
       "post": {
         "operationId": "incidentPostMortemDelete",
         "summary": "Delete post-mortem",
-        "description": "Delete a post-mortem report.",
+        "description": "Permanently delete a post-mortem report together with its uploaded media.",
         "tags": [
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Requires the Professional edition or higher; otherwise the call fails with `NoLicense`.\n- The caller must be an account owner or admin, or a member of the post-mortem's team; otherwise the call fails with `AccessDenied`.\n- Linked incidents are unlinked, so their `post_mortem_id` becomes empty.\n- An unknown `post_mortem_id` returns `ResourceNotFound`.\n- On success the response has no `data` field.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/on-call/incidents/incident-post-mortem-delete",
           "metadata": {
             "sidebarTitle": "Delete post-mortem"
@@ -3035,8 +3159,7 @@
                   ]
                 },
                 "example": {
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
-                  "data": {}
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
             }
@@ -3047,6 +3170,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -3073,12 +3199,12 @@
       "post": {
         "operationId": "calendarUpdate",
         "summary": "Update calendar",
-        "description": "Update a personal service calendar. Only non-null fields are updated.",
+        "description": "Update a personal service calendar; only the fields you send are changed.",
         "tags": [
           "On-call/Calendars"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Calendars Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Calendars Manage** (`on-call`) |\n\n## Usage\n\n- Send at least one field besides `cal_id`; otherwise the call returns `InvalidParameter`.\n- `workdays` and `extra_cal_ids` replace the stored lists when sent (an empty array clears them); `team_id: 0` removes the team.\n- `cal_name` must stay unique within the account.\n- Only personal calendars can be changed, and only by the account owner, an administrator, the calendar creator, or a member of the calendar's team; other callers get `AccessDenied`.\n- On success the response carries only `request_id`; the `data` field is omitted.\n- Every call is recorded in the account audit log.",
           "href": "/en/api-reference/on-call/calendars/calendar-update",
           "metadata": {
             "sidebarTitle": "Update calendar"
@@ -3105,8 +3231,7 @@
                   ]
                 },
                 "example": {
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
-                  "data": {}
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
             }
@@ -3117,6 +3242,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -3152,12 +3280,12 @@
       "post": {
         "operationId": "incidentWarRoomDelete",
         "summary": "Delete war room",
-        "description": "Delete an incident war room.",
+        "description": "Dissolve an incident's war room group on the IM platform and unlink it from the incident.",
         "tags": [
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Incidents Manage** or **Channels Manage** (`on-call`) |\n\n## Usage\n\n- The war room record is removed first; a failure to dissolve the group on the IM side (for example, it was already dissolved) is ignored.\n- Succeeds without changes when the incident has no war room on that integration.\n- To only unlink a war room whose IM integration is disabled or deleted, set `unlink_only: true` and pass its `chat_id`. This mode is limited to account owners and admins, fails with `InvalidParameter` while the integration is enabled, and does not dissolve the group.\n- On success the response has no `data` field.",
           "href": "/en/api-reference/on-call/incidents/incident-war-room-delete",
           "metadata": {
             "sidebarTitle": "Delete war room"
@@ -3184,8 +3312,7 @@
                   ]
                 },
                 "example": {
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
-                  "data": {}
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
             }
@@ -3196,6 +3323,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -3223,12 +3353,12 @@
       "post": {
         "operationId": "incidentRemove",
         "summary": "Delete an incident",
-        "description": "Permanently delete an incident and all associated data.",
+        "description": "Permanently delete incidents together with their alerts, raw events, and timelines.",
         "tags": [
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Incidents Manage** or **Channels Manage** (`on-call`) |\n\n## Usage\n\n- Deletion cannot be undone. Analytics statistics of the deleted incidents are removed in the background.\n- Fails with `InvalidParameter` if any incident belongs to a channel the caller cannot access.\n- IDs that do not match an incident are ignored.\n- Returns `RequestTooFrequently` while another resolve, reopen, merge, comment, or delete is running in the same account; retry after a short delay.",
           "href": "/en/api-reference/on-call/incidents/incident-remove",
           "metadata": {
             "sidebarTitle": "Delete an incident"
@@ -3267,6 +3397,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -3295,12 +3428,12 @@
       "post": {
         "operationId": "channelUnsubscribeRuleEnable",
         "summary": "Enable drop rule",
-        "description": "Enable a disabled drop rule. Only a `disabled` rule can be enabled.",
+        "description": "Enable a disabled drop rule so it discards matching alert events again.",
         "tags": [
           "On-call/Channels"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Only a `disabled` rule can be enabled; any other status returns `InvalidParameter`.\n- An unknown `channel_id` or `rule_id` returns `InvalidParameter`.\n- The caller must also be able to edit the channel: the account owner or an admin, the channel creator, or a member of its managing teams (of its owning team when `managing_team_ids` is empty). Otherwise the call returns `AccessDenied`.\n- Every call is recorded in the account audit log.",
           "href": "/en/api-reference/on-call/channels/channel-unsubscribe-rule-enable",
           "metadata": {
             "sidebarTitle": "Enable drop rule"
@@ -3339,6 +3472,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -3371,7 +3507,7 @@
           "On-call/Analytics"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Analytics Read** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Analytics Read** (`on-call`) |\n\n## Usage\n\n- Sorted by incident creation time, newest first by default (`asc: true` for oldest first).\n- Page with `p` + `limit` (at most 10,000 records reachable) or, for deeper reads, pass the previous page's `search_after_ctx` back. When `search_after_ctx` is sent, `total` counts only the incidents after the cursor.\n- `responder_ids` keeps incidents in which any of the given members was a responder.\n- Members who are neither the account owner nor an admin only get data from channels they can access; other channels are silently excluded.\n- With `is_my_team: true`, `team_ids` is narrowed to the caller's teams; a caller who belongs to no team gets an empty result.",
           "href": "/en/api-reference/on-call/analytics/insight-incident-list",
           "metadata": {
             "sidebarTitle": "List insight incidents"
@@ -3465,6 +3601,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -3502,7 +3641,7 @@
           "On-call/Status pages"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Status Pages Events Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Status Pages Events Manage** (`on-call`) |\n\n## Usage\n\n- `status` and every component status in `updates` must be valid for `type`, and every `component_id` must exist on the page.\n- `updates` must be in non-decreasing `at_seconds` order. If `status` is `resolved` or `completed`, every affected component must end as `operational`.\n- With `notify_subscribers: true`, subscribers are notified once, about the last entry in `updates`.\n- For a maintenance with `auto_update_by_schedule: true`, the server moves it from `scheduled` to `ongoing` at `start_at_seconds` and from `ongoing` to `completed` at `close_at_seconds`, setting affected components back to `operational`.\n- Pass `draft_id` to publish a draft stored by `POST /status-page/draft/create`; the draft must target the same page and `type` and can be published only once.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/on-call/status-pages/status-page-change-create",
           "metadata": {
             "sidebarTitle": "Create status page event"
@@ -3544,6 +3683,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -3593,7 +3735,7 @@
           "On-call/Schedules"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **60 requests/minute**; **10 requests/second** per account |\n| Permissions | **Schedules Read** (`on-call`) or **Schedules Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **100 requests/minute**; **5 requests/second** per account |\n| Permissions | **Schedules Read** (`on-call`) or **Schedules Manage** (`on-call`) |\n\n## Usage\n\n- Nothing is saved. The body takes the same fields as `/schedule/create`, plus the required `start`/`end` window. `start` and `end` are 10-digit Unix timestamps in seconds; `end` must be after `start` and at most 45 days later.\n- Pass `time_zone` to preview in the time zone the schedule will be created with; without it, wall-clock values are evaluated in `Asia/Shanghai`.\n- Fields that only exist on saved schedules (`id`, `name`, `group_id`, `disabled`, `status`) are echoed from the request and are usually `null`.\n- `cur_oncall` is the shift in progress now and `next_oncall` the next shift with someone on duty; each is `null` when there is none within 45 days of now, independent of the requested window.",
           "href": "/en/api-reference/on-call/schedules/schedule-preview",
           "metadata": {
             "sidebarTitle": "Preview schedule"
@@ -3626,6 +3768,7 @@
                     "name": null,
                     "account_id": 0,
                     "group_id": null,
+                    "time_zone": "",
                     "disabled": null,
                     "create_at": 0,
                     "create_by": 0,
@@ -3794,6 +3937,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -3873,7 +4019,7 @@
           "On-call/Integrations"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Integrations Read** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- `start_time` and `end_time` are Unix milliseconds.\n- Each record is one delivery of one event to one endpoint; `attempt` counts the HTTP tries, which are retried only on connection errors.\n- Stored request and response headers and bodies are truncated.\n- Pass `search_after_ctx` from the previous response for the next page; it is an empty string on the last page.\n- Returns `InvalidParameter` when delivery history recording is turned off for the deployment.",
           "href": "/en/api-reference/on-call/integrations/webhook-history-list",
           "metadata": {
             "sidebarTitle": "List webhook delivery history"
@@ -3931,6 +4077,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -3961,12 +4110,12 @@
       "post": {
         "operationId": "incidentWake",
         "summary": "Wake incident",
-        "description": "Cancel the snooze on an incident and resume notifications.",
+        "description": "End the snooze on incidents so that their notifications resume immediately.",
         "tags": [
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Incidents Manage** or **Channels Manage** (`on-call`) |\n\n## Usage\n\n- Incidents whose snooze has already ended are skipped; a closed incident fails the whole call with `InvalidParameter`.",
           "href": "/en/api-reference/on-call/incidents/incident-wake",
           "metadata": {
             "sidebarTitle": "Wake incident"
@@ -4005,6 +4154,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -4033,12 +4185,12 @@
       "post": {
         "operationId": "channelSilenceRuleEnable",
         "summary": "Enable silence rule",
-        "description": "Enable a disabled silence rule. Only a `disabled` rule can be enabled.",
+        "description": "Enable a disabled silence rule so it silences matching alert events again.",
         "tags": [
           "On-call/Channels"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |\n\n## Usage\n\n- Only a `disabled` rule can be enabled; any other status returns `InvalidParameter`.\n- An unknown `channel_id` or `rule_id` returns `InvalidParameter`.\n- The caller must also be able to edit the channel: the account owner or an admin, the channel creator, or a member of its managing teams (of its owning team when `managing_team_ids` is empty). Otherwise the call returns `AccessDenied`.\n- Every call is recorded in the account audit log.",
           "href": "/en/api-reference/on-call/channels/channel-silence-rule-enable",
           "metadata": {
             "sidebarTitle": "Enable silence rule"
@@ -4077,6 +4229,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -4104,12 +4259,12 @@
       "post": {
         "operationId": "channelSilenceRuleUpdate",
         "summary": "Update silence rule",
-        "description": "Update an existing silence rule configuration.",
+        "description": "Replace the configuration of an existing silence rule.",
         "tags": [
           "On-call/Channels"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |\n\n## Usage\n\n- The same time window and `filters` requirements as create apply. Switching between `time_filter` and `time_filters` clears the other one.\n- `description`, `is_directly_discard` and `is_auto_delete` are always overwritten, so omitting them resets them to empty or `false`. `from_incident_id` cannot be changed.\n- An unknown `channel_id` or `rule_id` returns `InvalidParameter`.\n- The caller must also be able to edit the channel: the account owner or an admin, the channel creator, or a member of its managing teams (of its owning team when `managing_team_ids` is empty). Otherwise the call returns `AccessDenied`.\n- Every call is recorded in the account audit log.",
           "href": "/en/api-reference/on-call/channels/channel-silence-rule-update",
           "metadata": {
             "sidebarTitle": "Update silence rule"
@@ -4148,6 +4303,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -4191,12 +4349,12 @@
       "post": {
         "operationId": "incidentFeed",
         "summary": "Get incident timeline",
-        "description": "Retrieve the timeline feed for a specific incident, including state changes, comments and system events.",
+        "description": "List an incident's timeline entries, such as state changes, assignments, notifications, comments, and work item events.",
         "tags": [
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Read** (`on-call`) |\n\n## Usage\n\n- For `i_comm` entries, `detail.comment_type` is resolved from the current account-level comment type definition at read time, so it reflects the type's latest name and color.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Read** or **Incidents Manage** or **Channels Read** or **Channels Manage** (`on-call`) |\n\n## Usage\n\n- For `i_comm` entries, `detail.comment_type` is resolved from the current account-level comment type definition at read time, so it reflects the type's latest name and color.\n- Only entries recorded on the incident itself are returned; alert-level entries are read through the alert endpoints.\n- Entries are ordered by creation time, newest first unless `asc` is `true`. Paginate with `p` and `limit`; `has_next_page` tells whether another page exists, and no total count is returned.\n- For `i_notify` entries, `failed_reason` is a localized message describing a delivery failure, filled in at read time.",
           "href": "/en/api-reference/on-call/incidents/incident-feed",
           "metadata": {
             "sidebarTitle": "Get incident timeline"
@@ -4291,6 +4449,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -4319,12 +4480,12 @@
       "post": {
         "operationId": "channelInhibitRuleCreate",
         "summary": "Create inhibit rule",
-        "description": "Create an inhibit rule to suppress lower-priority alerts when higher-priority ones are firing.",
+        "description": "Create an inhibit rule that mutes alert events while a related source alert is still active.",
         "tags": [
           "On-call/Channels"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |\n\n## Usage\n\n- Requires the Standard license or higher; otherwise the call returns `NoLicense`.\n- An incoming event is inhibited when it matches `target_filters` and the same channel has an active (not recovered) alert with a different `alert_key` that matches `source_filters`, started within the 10 minutes before the event, and has the same value for every key in `equals`.\n- The rule never fires when `equals` or `source_filters` is empty, or when the incoming event has no value for a label listed in `equals`.\n- Inhibit rules are checked after drop and silence rules; the first matching inhibit rule is applied.\n- An unknown `channel_id` returns `InvalidParameter`.\n- The caller must also be able to edit the channel: the account owner or an admin, the channel creator, or a member of its managing teams (of its owning team when `managing_team_ids` is empty). Otherwise the call returns `AccessDenied`.\n- Every call is recorded in the account audit log.",
           "href": "/en/api-reference/on-call/channels/channel-inhibit-rule-create",
           "metadata": {
             "sidebarTitle": "Create inhibit rule"
@@ -4354,7 +4515,7 @@
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "rule_id": "69db2f69a0fe7db6448b1504",
-                    "rule_name": "Test inhibit rule"
+                    "rule_name": "Suppress Info when Critical fires"
                   }
                 }
               }
@@ -4366,6 +4527,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -4421,12 +4585,12 @@
       "post": {
         "operationId": "channelInhibitRuleEnable",
         "summary": "Enable inhibit rule",
-        "description": "Enable a disabled inhibit rule. Only a `disabled` rule can be enabled.",
+        "description": "Enable a disabled inhibit rule so it mutes matching alert events again.",
         "tags": [
           "On-call/Channels"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |\n\n## Usage\n\n- Requires the Standard license or higher; otherwise the call returns `NoLicense`.\n- Only a `disabled` rule can be enabled; any other status returns `InvalidParameter`.\n- An unknown `channel_id` or `rule_id` returns `InvalidParameter`.\n- The caller must also be able to edit the channel: the account owner or an admin, the channel creator, or a member of its managing teams (of its owning team when `managing_team_ids` is empty). Otherwise the call returns `AccessDenied`.\n- Every call is recorded in the account audit log.",
           "href": "/en/api-reference/on-call/channels/channel-inhibit-rule-enable",
           "metadata": {
             "sidebarTitle": "Enable inhibit rule"
@@ -4465,6 +4629,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -4492,12 +4659,12 @@
       "post": {
         "operationId": "mapping-schema-read-list",
         "summary": "List mapping schemas",
-        "description": "Return all mapping schemas for the account, sorted by creation time ascending.",
+        "description": "Return all mapping schemas of the account, newest first.",
         "tags": [
           "On-call/Alert enrichment"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Read** (`on-call`) or **Channels Manage** (`on-call`) or **Integrations Read** (`on-call`) or **Integrations Manage** (`on-call`) or **Mappings Read** (`on-call`) or **Mappings Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Read** (`on-call`) or **Channels Manage** (`on-call`) or **Integrations Read** (`on-call`) or **Integrations Manage** (`on-call`) or **Mappings Read** (`on-call`) or **Mappings Manage** (`on-call`) |\n\n## Usage\n\n- Returns every non-deleted schema of the account in one response, without pagination; `total` is the number of items.\n- Schemas of all teams are returned; there is no team filter.",
           "href": "/en/api-reference/on-call/alert-enrichment/mapping-schema-read-list",
           "metadata": {
             "sidebarTitle": "List mapping schemas"
@@ -4543,6 +4710,7 @@
                         "status": "enabled",
                         "team_id": 0,
                         "creator_id": 80011,
+                        "updated_by": 80011,
                         "created_at": 1710000000,
                         "updated_at": 1710000000
                       }
@@ -4558,6 +4726,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -4582,12 +4753,12 @@
       "post": {
         "operationId": "channelUnsubscribeRuleDelete",
         "summary": "Delete drop rule",
-        "description": "Delete a drop rule. Only a `disabled` rule can be deleted.",
+        "description": "Delete a disabled drop rule so it no longer appears in the channel's rule list.",
         "tags": [
           "On-call/Channels"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Only a `disabled` rule can be deleted; any other status returns `InvalidParameter`.\n- An unknown `channel_id` or `rule_id` returns `InvalidParameter`.\n- The caller must also be able to edit the channel: the account owner or an admin, the channel creator, or a member of its managing teams (of its owning team when `managing_team_ids` is empty). Otherwise the call returns `AccessDenied`.\n- Every call is recorded in the account audit log.",
           "href": "/en/api-reference/on-call/channels/channel-unsubscribe-rule-delete",
           "metadata": {
             "sidebarTitle": "Delete drop rule"
@@ -4626,6 +4797,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -4658,7 +4832,7 @@
           "On-call/Alerts"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Integrations Read** (`on-call`) |\n\n## Usage\n\n- Returns `null` data if no pipeline has been configured for the given integration.\n- Requires the caller to have access to the integration.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Read** (`on-call`) or **Channels Manage** (`on-call`) or **Integrations Read** (`on-call`) or **Integrations Manage** (`on-call`) |\n\n## Usage\n\n- When the integration has no pipeline, the response carries only `request_id` and the `data` field is omitted.\n- `integration_id` may be any account-level or channel-owned integration of the account; an unknown ID returns `InvalidParameter`.",
           "href": "/en/api-reference/on-call/alerts/alert-read-pipeline-info",
           "metadata": {
             "sidebarTitle": "Get alert pipeline"
@@ -4728,6 +4902,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -4754,12 +4931,12 @@
       "post": {
         "operationId": "mapping-schema-write-delete",
         "summary": "Delete mapping schema",
-        "description": "Delete a mapping schema and all its associated data. Deletion is blocked if the schema is referenced by any enrichment rule or webhook.",
+        "description": "Delete a mapping schema and all of its data rows; refused while an enrichment rule or robot webhook uses it.",
         "tags": [
           "On-call/Alert enrichment"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Mappings Manage** (`on-call`) |\n\n## Usage\n\n- If the schema is still referenced, the response returns HTTP 400 with a `refs` list of blocking references.\n- Only the schema creator, account admin, or team member can delete the schema.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.\n- High-risk operation. Console JWT callers must pass a second-factor code; `app_key` callers bypass the MFA prompt but remain audited — treat the key as a secret.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Mappings Manage** (`on-call`) |\n\n## Usage\n\n- The schema is soft-deleted (`status` becomes `deleted`) and all of its data rows are removed permanently.\n- If an integration's enrichment rule, or a Feishu, WeCom or Zoom robot webhook in an escalation rule, references the schema, the call returns HTTP 400 `ReferenceExist` with `data.refs` (each item has `kind` = `integration` or `escalate_rule`, `name`, `href`); at most 20 integrations are listed.\n- An unknown `schema_id` returns `InvalidParameter`.\n- Only an account admin, the schema creator, or a member of the schema's owning team may call this; others get `AccessDenied`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/on-call/alert-enrichment/mapping-schema-write-delete",
           "metadata": {
             "sidebarTitle": "Delete mapping schema"
@@ -4798,6 +4975,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -4824,12 +5004,12 @@
       "post": {
         "operationId": "insightByAccount",
         "summary": "Get account-level insight",
-        "description": "Return aggregated incident insight metrics for the entire account.",
+        "description": "Return incident and alert metrics for the whole account, one row per time bucket.",
         "tags": [
           "On-call/Analytics"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Analytics Read** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Analytics Read** (`on-call`) |\n\n## Usage\n\n- One row per time bucket for the whole account. `responder_ids` and `incident_ids` are ignored; use `/insight/responder` or `/insight/incident/list` for those.\n- Incidents are counted by creation time. Rows are sorted by `ts` from newest to oldest, and a bucket (or dimension value) with no incidents produces no row — missing rows mean zero. `split_hours: true` returns up to three rows per bucket, one per `hours` value.\n- `total_alert_cnt`, `total_alert_event_cnt` and `noise_reduction_pct` honor only the time range, team, channel and severity filters; `query`, `labels`, `fields` and the duration filters apply to incident metrics only.\n- Members who are neither the account owner nor an admin only get data from channels they can access; other channels are silently excluded.\n- With `is_my_team: true`, `team_ids` is narrowed to the caller's teams; a caller who belongs to no team gets an empty result.",
           "href": "/en/api-reference/on-call/analytics/insight-by-account",
           "metadata": {
             "sidebarTitle": "Get account-level insight"
@@ -4895,6 +5075,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -4927,12 +5110,12 @@
       "post": {
         "operationId": "insightIncidentExport",
         "summary": "Export insight incidents",
-        "description": "Export the filtered incident analytics list as a CSV file. The response is a CSV stream delivered with `Content-Disposition: attachment` — it is not a JSON envelope. CSV headers and formatted values use the request locale, falling back to the member locale and then the account locale. `time_zone` defaults to the account time zone, then `Asia/Shanghai`. Export stops after at most 100,000 rows. Valid `export_fields` keys: incident_id, title, severity, progress, channel_id, channel_name, team_id, team_name, created_at, alert_cnt, active_alert_cnt, alert_event_cnt, seconds_to_ack, seconds_to_close, closed_by, owner_id, owner_name, creator_id, creator_name, closer_id, closer_name, engaged_seconds, hours, notifications, interruptions, acknowledgements, ackers, assignments, reassignments, escalations, manual_escalations, timeout_escalations, assigned_to, raw_assigned_to, escalate_rule_name, responders, raw_responders, snooze_status, snoozed_before, ever_muted, frequency, is_rare, description, labels, fields. When `export_fields` is omitted, all columns are exported.",
+        "description": "Export the incidents matched by the analytics filters as a CSV file, one row per incident.",
         "tags": [
           "On-call/Analytics"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **100 requests/day**; **20 requests/minute**; **10 requests/second** per account |\n| Permissions | **Analytics Read** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **100 requests/day**; **20 requests/minute**; **10 requests/second** per account |\n| Permissions | **Analytics Read** (`on-call`) |\n\n## Usage\n\n- The response is a CSV file (`Content-Type: application/octet-stream`), not a JSON envelope. Validation errors are returned as JSON before any CSV bytes are written.\n- Takes the same filters and sort order as `/insight/incident/list`. Export stops once more than 100,000 rows have been written.\n- `start_time` is moved forward to the earliest date kept by the account's data retention; a range that ends before that date is rejected.\n- `export_fields` sets the columns and their order: incident_id, title, severity, progress, channel_id, channel_name, team_id, team_name, created_at, alert_cnt, active_alert_cnt, alert_event_cnt, seconds_to_ack, seconds_to_close, closed_by, owner_id, owner_name, creator_id, creator_name, closer_id, closer_name, engaged_seconds, hours, notifications, interruptions, acknowledgements, ackers, assignments, reassignments, escalations, manual_escalations, timeout_escalations, assigned_to, raw_assigned_to, escalate_rule_name, responders, raw_responders, snooze_status, snoozed_before, ever_muted, frequency, is_rare, description, labels, fields. Unknown or duplicate keys are rejected; when omitted, every column except the aliases `owner_id`, `creator_id`, `closer_id`, `snoozed_before` and `is_rare` is exported.\n- `description_html_to_text: true` strips HTML from the `description` column.\n- Headers and formatted values use the request locale, then the member's, then the account's. Times are rendered in `time_zone`, falling back to the account time zone and then `Asia/Shanghai`.",
           "href": "/en/api-reference/on-call/analytics/insight-incident-export",
           "metadata": {
             "sidebarTitle": "Export insight incidents"
@@ -4946,7 +5129,7 @@
                 "schema": {
                   "type": "string",
                   "format": "binary",
-                  "description": "CSV file stream (`Content-Type: application/octet-stream`, `Content-Disposition: attachment; filename=incident_export_yyyyMMdd_HHmmss.csv`). The first row holds localized column headers. Columns default to the full incident field set, or the keys given in `export_fields`."
+                  "description": "CSV file (`Content-Type: application/octet-stream`, `Content-Disposition: attachment; filename*=UTF-8''incident_export_yyyyMMdd_HHmmss.csv`). The first row holds localized column headers."
                 },
                 "example": "incident_id,title,severity,created_at\n6a86b5d6f72de50ae1ce2ffb,CPU usage above 90%,Critical,2026-01-01 10:00:00 +0800 CST\n"
               }
@@ -4958,6 +5141,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -4997,12 +5183,12 @@
       "post": {
         "operationId": "scheduleInfo",
         "summary": "Get schedule info",
-        "description": "Return details of an on-call schedule including the computed schedule layers for the requested time window (max 45 days).",
+        "description": "Return one on-call schedule with its layers and the shifts computed for a time window of up to 45 days.",
         "tags": [
           "On-call/Schedules"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Schedules Read** (`on-call`) or **Schedules Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Schedules Read** (`on-call`) or **Schedules Manage** (`on-call`) |\n\n## Usage\n\n- `start` and `end` are 10-digit Unix timestamps in seconds; `end` must be after `start` and at most 45 days later.\n- `schedule_layers` (and its alias `layer_schedules`) holds each visible layer's shifts in the window; `final_schedule` merges all layers, and a shift whose `group` is `null` is a gap with nobody on call.\n- The first computed shift may start before `start`: a shift already in progress at `start` is returned with its real start time.\n- `cur_oncall` is the shift in progress now and `next_oncall` the next shift with someone on duty; each is `null` when there is none within 45 days of now, independent of the requested window.\n- An unknown `schedule_id` returns `400`.",
           "href": "/en/api-reference/on-call/schedules/schedule-info",
           "metadata": {
             "sidebarTitle": "Get schedule info"
@@ -5035,6 +5221,7 @@
                     "name": "test-000001",
                     "account_id": 2451002751131,
                     "group_id": 4291079133131,
+                    "time_zone": "Asia/Shanghai",
                     "disabled": 0,
                     "create_at": 1766110836,
                     "create_by": 2476123212131,
@@ -5292,6 +5479,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -5307,9 +5497,9 @@
                 "$ref": "#/components/schemas/ScheduleInfoRequest"
               },
               "example": {
-                "schedule_id": 2001,
-                "start": 1712000000,
-                "end": 1712086400
+                "schedule_id": 5789640530410,
+                "start": 1776009600,
+                "end": 1776268800
               }
             }
           }
@@ -5320,12 +5510,12 @@
       "post": {
         "operationId": "template-write-update",
         "summary": "Update a template",
-        "description": "Update an existing template. Only the fields present in the request are written: a channel you omit keeps its current content, and an explicit empty string clears it.",
+        "description": "Update a notification template; only the fields present in the request are written.",
         "tags": [
           "On-call/Notification templates"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Templates Manage** (`on-call`) |\n\n## Usage\n\n- Only the fields present in the request are written. A channel you omit keeps its current content; send it as an empty string to clear it.\n- The caller needs data-permission on the template's team; otherwise the response is `AccessDenied`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Templates Manage** (`on-call`) |\n\n## Usage\n\n- `template_name` is required on every call and always written. Other fields left out keep their current values; a channel sent as an empty string is cleared, and notifications on that channel then use the built-in preset content.\n- Every non-empty channel source in the request is test-rendered against a mock incident; a template error fails the whole request with `InvalidParameter`. While `wecom_markdown_v2_enabled` is `true`, the rendered `wecom` content must be at most 4,096 bytes.\n- `incident_card_hidden_fields` and `incident_card_closed_action_apps`, when sent, replace the stored value as a whole.\n- An unknown `template_id` returns `InvalidParameter`; a new `template_name` must not be used by another template.\n- Only an account admin, the template creator, or a member of the template's owning team may call this; others get `AccessDenied`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/on-call/notification-templates/template-write-update",
           "metadata": {
             "sidebarTitle": "Update a template"
@@ -5385,8 +5575,8 @@
                 "template_id": "6605a1b2c3d4e5f6a7b8c9d0",
                 "template_name": "Prod incident default",
                 "description": "Updated description.",
-                "email": "Incident {{ .IncidentName }} on {{ .Severity }}",
-                "sms": "[Flashduty] {{ .IncidentName }} — {{ .Severity }}"
+                "email": "Incident {{.Title}} is {{.IncidentSeverity}}",
+                "sms": "[Flashduty] {{.Title}} - {{.IncidentSeverity}}"
               }
             }
           }
@@ -5397,12 +5587,12 @@
       "post": {
         "operationId": "channelInfos",
         "summary": "Batch get channels",
-        "description": "Retrieve multiple channels by their IDs.",
+        "description": "Return the ID, name and status of up to 1,000 channels in one call.",
         "tags": [
           "On-call/Channels"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- IDs that do not exist are skipped. Deleted channels are included, with `status` `deleted`.\n- Items are ordered by channel creation, not by the order of `channel_ids`.\n- Private channels are included regardless of the caller's team membership.",
           "href": "/en/api-reference/on-call/channels/channel-infos",
           "metadata": {
             "sidebarTitle": "Batch get channels"
@@ -5449,6 +5639,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -5478,12 +5671,12 @@
       "post": {
         "operationId": "scheduleInfos",
         "summary": "Batch get schedules",
-        "description": "Return details of multiple on-call schedules by their IDs.",
+        "description": "Return the basic configuration of several on-call schedules by ID, without layers or computed shifts.",
         "tags": [
           "On-call/Schedules"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Schedules Read** (`on-call`) or **Schedules Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Schedules Read** (`on-call`) or **Schedules Manage** (`on-call`) |\n\n## Usage\n\n- Returns stored configuration only: `layers`, `schedule_layers`, `layer_schedules`, `cur_oncall` and `next_oncall` are always `null`, and `final_schedule` is empty. Use `/schedule/info` for layers and shifts.\n- IDs that do not exist are skipped without error; disabled schedules are included.",
           "href": "/en/api-reference/on-call/schedules/schedule-infos",
           "metadata": {
             "sidebarTitle": "Batch get schedules"
@@ -5518,6 +5711,7 @@
                         "name": "test-000001",
                         "account_id": 2451002751131,
                         "group_id": 4291079133131,
+                        "time_zone": "Asia/Shanghai",
                         "disabled": 0,
                         "create_at": 1766110836,
                         "create_by": 2476123212131,
@@ -5577,6 +5771,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -5593,9 +5790,8 @@
               },
               "example": {
                 "schedule_ids": [
-                  2001,
-                  2002,
-                  2003
+                  5789640530410,
+                  5432326025106
                 ]
               }
             }
@@ -5612,7 +5808,7 @@
           "On-call/Notification templates"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Templates Read** (`on-call`) |\n\n## Usage\n\n- Pass `000000000000000000000001` as `template_id` to retrieve the built-in preset template for the caller's account locale.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Templates Read** (`on-call`) or **Templates Manage** (`on-call`) |\n\n## Usage\n\n- Pass `6321aad26c12104586a88916` as `template_id` to get the built-in preset template: its channel contents are in the account language, its name and description in the caller's language.\n- An unknown `template_id` returns `InvalidParameter`. A soft-deleted template is still returned, with `status` = `deleted`.",
           "href": "/en/api-reference/on-call/notification-templates/template-read-info",
           "metadata": {
             "sidebarTitle": "Get template detail"
@@ -5646,8 +5842,8 @@
                     "template_id": "6605a1b2c3d4e5f6a7b8c9d0",
                     "template_name": "Prod incident default",
                     "description": "Default template for production incidents.",
-                    "email": "Incident {{ .IncidentName }} on {{ .Severity }}",
-                    "sms": "[Flashduty] {{ .IncidentName }} — {{ .Severity }}",
+                    "email": "Incident {{.Title}} is {{.IncidentSeverity}}",
+                    "sms": "[Flashduty] {{.Title}} - {{.IncidentSeverity}}",
                     "voice": "",
                     "dingtalk": "",
                     "wecom": "",
@@ -5660,6 +5856,14 @@
                     "telegram": "",
                     "slack": "",
                     "zoom": "",
+                    "wecom_markdown_v2_enabled": false,
+                    "feishu_app_card_v2_table_enabled": false,
+                    "feishu_app_card_v2_preserve_blank_lines": false,
+                    "feishu_app_war_room_enabled": false,
+                    "dingtalk_app_war_room_enabled": false,
+                    "slack_app_war_room_enabled": false,
+                    "incident_card_closed_action_apps": [],
+                    "incident_card_hidden_fields": {},
                     "status": "enabled",
                     "creator_id": 80011,
                     "updated_by": 80011,
@@ -5676,6 +5880,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -5702,12 +5909,12 @@
       "post": {
         "operationId": "channelEscalateRuleDisable",
         "summary": "Disable escalation rule",
-        "description": "Disable an escalation rule without deleting it. Only an `enabled` rule can be disabled.",
+        "description": "Disable an escalation rule without deleting it.",
         "tags": [
           "On-call/Channels"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |\n\n## Usage\n\n- Only an `enabled` rule can be disabled; any other status returns `InvalidParameter`.\n- A disabled rule takes no new incidents, and incidents already assigned through it stop receiving its notifications and escalations.\n- An unknown `channel_id` or `rule_id` returns `InvalidParameter`.\n- The caller must also be able to edit the channel: the account owner or an admin, the channel creator, or a member of its managing teams (of its owning team when `managing_team_ids` is empty). Otherwise the call returns `AccessDenied`.\n- Every call is recorded in the account audit log.",
           "href": "/en/api-reference/on-call/channels/channel-escalate-rule-disable",
           "metadata": {
             "sidebarTitle": "Disable escalation rule"
@@ -5746,6 +5953,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -5773,12 +5983,12 @@
       "post": {
         "operationId": "incidentReset",
         "summary": "Update incident fields",
-        "description": "Update one or more editable fields of an incident in a single call, including title, description, impact, root cause, resolution, and severity. At least one field must be provided.",
+        "description": "Update an incident's title, description, impact, root cause, resolution, or severity in one call.",
         "tags": [
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Incidents Manage** or **Channels Manage** (`on-call`) |\n\n## Usage\n\n- At least one field must be provided. Omitted fields and empty strings keep their current values, so this endpoint cannot clear a field.\n- Values equal to the current ones are skipped. Each changed field adds its own timeline entry (`i_r_title`, `i_r_desc`, `i_r_impact`, `i_r_rc`, `i_r_rsltn`, or `i_r_severity`).\n- Changing `title`, `description`, or `incident_severity` adds that field to `manual_overrides`; after that, alerts merged into the incident no longer overwrite it.\n- Closed incidents can be updated as well.",
           "href": "/en/api-reference/on-call/incidents/incident-reset",
           "metadata": {
             "sidebarTitle": "Update incident fields"
@@ -5817,6 +6027,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -5845,12 +6058,12 @@
       "post": {
         "operationId": "channelDisable",
         "summary": "Disable channel",
-        "description": "Disable a channel to stop incident routing without deleting it; a disabled channel discards incoming events. Only an `enabled` channel can be disabled.",
+        "description": "Disable a channel; while disabled it discards all incoming alert events.",
         "tags": [
           "On-call/Channels"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |\n\n## Usage\n\n- Only an `enabled` channel can be disabled; any other status returns `InvalidParameter`.\n- Rules and integrations are kept. Alert processing may take up to about one minute to see the new status.\n- An unknown `channel_id` returns `InvalidParameter`.\n- The caller must also be able to edit the channel: the account owner or an admin, the channel creator, or a member of its managing teams (of its owning team when `managing_team_ids` is empty). Otherwise the call returns `AccessDenied`.\n- Every call is recorded in the account audit log.",
           "href": "/en/api-reference/on-call/channels/channel-disable",
           "metadata": {
             "sidebarTitle": "Disable channel"
@@ -5889,6 +6102,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -5920,7 +6136,7 @@
           "On-call/Integrations"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Integrations Read** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Take `event_id` and `integration_id` from a record of `POST /webhook/history/list`; `event_id` starts with the delivery date (`YYYYMMDD`), which the lookup relies on.\n- When no record matches, `data` is an empty object.\n- Returns `InvalidParameter` when delivery history recording is turned off for the deployment.",
           "href": "/en/api-reference/on-call/integrations/webhook-history-detail",
           "metadata": {
             "sidebarTitle": "Get webhook delivery detail"
@@ -5978,6 +6194,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -6005,12 +6224,12 @@
       "post": {
         "operationId": "scheduleList",
         "summary": "List schedules",
-        "description": "Return a paginated list of on-call schedules. When both start and end are provided (max 45 days apart), computed layer schedules are included.",
+        "description": "List on-call schedules with filters and pagination; pass `start` and `end` to also compute shifts.",
         "tags": [
           "On-call/Schedules"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Sorted by creation time, newest first. `query` matches the schedule name or description as a substring.\n- `is_my_team: true` keeps schedules owned by the caller's teams. `is_my_manage: true` keeps schedules owned by the caller's teams or created by the caller. The two cannot both be true. `team_ids` is intersected with either filter.\n- Without `start`/`end`, items carry stored configuration only (`layers`, `schedule_layers`, `cur_oncall`, `next_oncall` are `null`). With both set, `layers`, `schedule_layers`, `final_schedule`, `cur_oncall` and `next_oncall` are computed; `layer_schedules` stays `null` here.\n- `start` and `end` are 10-digit Unix timestamps in seconds; `end` must be after `start` and at most 45 days later. Sending `end` without `start` is rejected.",
           "href": "/en/api-reference/on-call/schedules/schedule-list",
           "metadata": {
             "sidebarTitle": "List schedules"
@@ -6045,6 +6264,7 @@
                         "name": "test-000001",
                         "account_id": 2451002751131,
                         "group_id": 4291079133131,
+                        "time_zone": "Asia/Shanghai",
                         "disabled": 0,
                         "create_at": 1766110836,
                         "create_by": 2476123212131,
@@ -6097,6 +6317,7 @@
                         "name": "test-2509300001",
                         "account_id": 2451002751131,
                         "group_id": 2477033058131,
+                        "time_zone": "",
                         "disabled": 0,
                         "create_at": 1759132037,
                         "create_by": 2476123212131,
@@ -6141,6 +6362,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -6170,12 +6394,12 @@
       "post": {
         "operationId": "mapping-schema-write-create",
         "summary": "Create mapping schema",
-        "description": "Create a new mapping schema defining source lookup labels and the result labels to populate. Requires a Pro plan.",
+        "description": "Create a mapping schema that defines the lookup labels and the result labels to fill.",
         "tags": [
           "On-call/Alert enrichment"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Mappings Manage** (`on-call`) |\n\n## Usage\n\n- Schema names must be unique within an account.\n- `source_labels` (1–3 labels) are used as lookup keys; `result_labels` (1–10 labels) are the labels written on match.\n- Label names must match `^[a-zA-Z_][a-zA-Z0-9_]*$` and be unique within each list.\n- `source_labels` and `result_labels` must not overlap.\n- An account can have at most 20 mapping schemas.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Mappings Manage** (`on-call`) |\n\n## Usage\n\n- Requires the Pro plan or higher; otherwise `NoLicense`.\n- `schema_name` must be unique among the account's non-deleted schemas.\n- `source_labels` (1–3) form the lookup key; `result_labels` (1–10) are written to alerts on a match. Label names must match `^[a-zA-Z_][a-zA-Z0-9_]*$`, be unique within each list, and not appear in both lists. Neither list can be changed later.\n- An account holds at most 20 non-deleted mapping schemas by default (some accounts have a higher limit); exceeding it returns `InvalidParameter`.\n- Concurrent create calls in one account return `RequestTooFrequently`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/on-call/alert-enrichment/mapping-schema-write-create",
           "metadata": {
             "sidebarTitle": "Create mapping schema"
@@ -6217,6 +6441,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -6257,7 +6484,7 @@
           "On-call/Alert enrichment"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Mappings Manage** (`on-call`) |\n\n## Usage\n\n- Only the API creator, account admin, or team member can update the API.\n- All updatable fields are optional — only provided fields are changed.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Mappings Manage** (`on-call`) |\n\n## Usage\n\n- Fields left out keep their current values. `headers`, when sent, replaces the whole header map; send `{}` to remove all headers. `team_id` `0` removes the team.\n- The fields you send are validated as on create (`url` scheme and internal-address check, header rules, `timeout` 1–3, `retry_count` 0–1); `description` is cut to 500 characters.\n- An unknown `api_id` returns `InvalidParameter`; a new `api_name` must not be used by another mapping API.\n- Only an account admin, the mapping API creator, or a member of the mapping API's owning team may call this; others get `AccessDenied`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/on-call/alert-enrichment/mapping-api-write-update",
           "metadata": {
             "sidebarTitle": "Update mapping API"
@@ -6296,6 +6523,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -6329,7 +6559,7 @@
           "On-call/Calendars"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Without `kind`, personal calendars are returned. `region.official.holiday` returns public holiday calendars, filtered to the caller's locale unless `no_locale` is `true`; use their `cal_id` in `extra_cal_ids`.\n- The list is not paginated; `total` equals the number of items.",
           "href": "/en/api-reference/on-call/calendars/calendar-list",
           "metadata": {
             "sidebarTitle": "List calendars"
@@ -6412,6 +6642,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -6438,12 +6671,12 @@
       "post": {
         "operationId": "incidentResponderAdd",
         "summary": "Add incident responder",
-        "description": "Add a responder to an existing incident.",
+        "description": "Add members as responders to an open incident and notify them.",
         "tags": [
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Incidents Manage** or **Channels Manage** (`on-call`) |\n\n## Usage\n\n- Existing responders are kept, and IDs that are already responders are skipped. To replace the responder set, use `POST /incident/assign`.\n- Closed incidents are rejected with `InvalidParameter`.\n- Member IDs that do not exist in the account are ignored.\n- New responders are notified according to `notify`; by default each follows their personal notification preference.",
           "href": "/en/api-reference/on-call/incidents/incident-responder-add",
           "metadata": {
             "sidebarTitle": "Add incident responder"
@@ -6482,6 +6715,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -6512,12 +6748,12 @@
       "post": {
         "operationId": "insightTeamExport",
         "summary": "Export team insight",
-        "description": "Export team insight metrics as a CSV file — one row per team (and per time/hour bucket when `aggregate_unit`/`split_hours` is used). The response is a CSV stream delivered with `Content-Disposition: attachment` — it is not a JSON envelope. `time_zone` defaults to UTC. Rows without a valid team ID are skipped. Valid `export_fields` keys: team_id, team_name, total_incident_cnt, total_incidents_acknowledged, total_incidents_closed, total_incidents_auto_closed, total_incidents_manually_closed, total_incidents_timeout_closed, total_incidents_escalated, total_incidents_manually_escalated, total_incidents_timeout_escalated, total_incidents_reassigned, total_interruptions, total_notifications, total_engaged_seconds, mean_seconds_to_ack, mean_seconds_to_close, noise_reduction_pct, acknowledgement_pct, total_alert_cnt, total_alert_event_cnt, hours. The `hours` column is included by default only when `split_hours` is true. For compatibility, incident-export column keys are also accepted but produce empty columns.",
+        "description": "Export team insight metrics as a CSV file with the same rows as `/insight/team`.",
         "tags": [
           "On-call/Analytics"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **100 requests/day**; **20 requests/minute**; **10 requests/second** per account |\n| Permissions | **Analytics Read** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **100 requests/day**; **20 requests/minute**; **10 requests/second** per account |\n| Permissions | **Analytics Read** (`on-call`) |\n\n## Usage\n\n- The response is a CSV file (`Content-Type: application/octet-stream`), not a JSON envelope. Validation errors are returned as JSON before any CSV bytes are written.\n- Takes the same filters as `/insight/team`. Rows without a team ID (incidents without a team) are skipped. The file has no time-bucket column, so with `aggregate_unit` the rows of different buckets cannot be told apart; export one bucket per request if you need the split.\n- `export_fields` sets the columns and their order: team_id, team_name, total_incident_cnt, total_incidents_acknowledged, total_incidents_closed, total_incidents_auto_closed, total_incidents_manually_closed, total_incidents_timeout_closed, total_incidents_escalated, total_incidents_manually_escalated, total_incidents_timeout_escalated, total_incidents_reassigned, total_interruptions, total_notifications, total_engaged_seconds, mean_seconds_to_ack, mean_seconds_to_close, noise_reduction_pct, acknowledgement_pct, total_alert_cnt, total_alert_event_cnt, hours. Unknown or duplicate keys are rejected. When it is omitted, all columns are exported, and `hours` is included only when `split_hours` is true.\n- The incident-snapshot keys (progress, assigned_to, raw_assigned_to, escalate_rule_name, responders, raw_responders, ackers, owner_id, owner_name, creator_id, creator_name, closer_id, closer_name, snooze_status, snoozed_before, ever_muted, frequency, is_rare, alert_cnt, active_alert_cnt, alert_event_cnt, description, labels, fields) are also accepted for compatibility and produce empty columns.\n- Column headers are localized (request locale, then the member's, then the account's). Time buckets follow `time_zone` (UTC when omitted).",
           "href": "/en/api-reference/on-call/analytics/insight-team-export",
           "metadata": {
             "sidebarTitle": "Export team insight"
@@ -6531,7 +6767,7 @@
                 "schema": {
                   "type": "string",
                   "format": "binary",
-                  "description": "CSV file stream (`Content-Type: application/octet-stream`, `Content-Disposition: attachment; filename=team_export_yyyyMMdd_HHmmss.csv`). The first row holds localized column headers. Columns default to the full field set, or the keys given in `export_fields`."
+                  "description": "CSV file (`Content-Type: application/octet-stream`, `Content-Disposition: attachment; filename*=UTF-8''team_export_yyyyMMdd_HHmmss.csv`). The first row holds localized column headers."
                 },
                 "example": "team_id,team_name,total_incident_cnt,total_incidents_closed\n4295771902131,SRE Team,12,10\n"
               }
@@ -6543,6 +6779,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -6577,12 +6816,12 @@
       "post": {
         "operationId": "scheduleDelete",
         "summary": "Delete schedules",
-        "description": "Delete one or more on-call schedules by ID.",
+        "description": "Delete one or more on-call schedules by ID, together with their layers.",
         "tags": [
           "On-call/Schedules"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Schedules Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Schedules Manage** (`on-call`) |\n\n## Usage\n\n- A schedule still referenced by an escalation rule cannot be deleted: the call fails with HTTP 400 `ReferenceExist`, nothing is deleted, and `data.refs` lists the referencing rules (`kind`, `name`, `href`).\n- IDs that do not exist are ignored. The deletion of all listed schedules happens in one transaction.\n- Every call is recorded in the account audit log.",
           "href": "/en/api-reference/on-call/schedules/schedule-delete",
           "metadata": {
             "sidebarTitle": "Delete schedules"
@@ -6621,6 +6860,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -6637,7 +6879,7 @@
               },
               "example": {
                 "schedule_ids": [
-                  2001
+                  5789640530410
                 ]
               }
             }
@@ -6654,7 +6896,7 @@
           "On-call/Status pages"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Status Pages Events Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Status Pages Events Manage** (`on-call`) |\n\n## Usage\n\n- The latest timeline entry cannot be deleted; trying returns `InvalidParameter`.\n- After deletion, the event's status, description, close time, and affected components are recomputed from the remaining entries.\n- Returns success when the event does not exist, and `ResourceNotFound` when the event exists but `update_id` does not.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/on-call/status-pages/status-page-change-timeline-delete",
           "metadata": {
             "sidebarTitle": "Delete event timeline entry"
@@ -6693,6 +6935,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -6721,12 +6966,12 @@
       "post": {
         "operationId": "incidentWarRoomCreate",
         "summary": "Create war room",
-        "description": "Create a war room channel for collaborative incident response.",
+        "description": "Create an IM group chat as the war room for an incident and invite members into it.",
         "tags": [
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Incidents Manage** or **Channels Manage** (`on-call`) |\n\n## Usage\n\n- Requires the Professional edition or higher; otherwise the call fails with `NoLicense`.\n- The IM integration must be enabled with war room turned on. Feishu, DingTalk, WeCom (self-built app only), and Slack are supported.\n- An incident can have only one war room. Calling again with the same `integration_id` returns the existing group (with an empty `share_link`); a different `integration_id` fails with `InvalidParameter`.\n- A concurrent creation for the same incident returns `RequestTooFrequently`.\n- A successful creation adds an `i_wr_create` timeline entry.",
           "href": "/en/api-reference/on-call/incidents/incident-war-room-create",
           "metadata": {
             "sidebarTitle": "Create war room"
@@ -6769,6 +7014,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -6797,12 +7045,12 @@
       "post": {
         "operationId": "channelUnsubscribeRuleUpdate",
         "summary": "Update drop rule",
-        "description": "Update an existing drop rule configuration.",
+        "description": "Replace the name, description and conditions of an existing drop rule.",
         "tags": [
           "On-call/Channels"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Full replacement: an omitted `description` becomes empty, and an omitted `filters` clears all conditions so the rule matches nothing.\n- An unknown `channel_id` or `rule_id` returns `InvalidParameter`.\n- The caller must also be able to edit the channel: the account owner or an admin, the channel creator, or a member of its managing teams (of its owning team when `managing_team_ids` is empty). Otherwise the call returns `AccessDenied`.\n- Every call is recorded in the account audit log.",
           "href": "/en/api-reference/on-call/channels/channel-unsubscribe-rule-update",
           "metadata": {
             "sidebarTitle": "Update drop rule"
@@ -6841,6 +7089,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -6880,12 +7131,12 @@
       "post": {
         "operationId": "routeUpsert",
         "summary": "Upsert routing rule",
-        "description": "Create or update routing rules for an integration to direct alerts to specific channels. At least one of `cases` or `default` must be provided.",
+        "description": "Create or replace the routing rule that sends a shared integration's alerts to channels.",
         "tags": [
           "On-call/Channels"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Integrations Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Integrations Manage** (`on-call`) |\n\n## Usage\n\n- The whole rule is replaced: `cases`, `sections` or `default` missing from the request are removed. `version` increases on every call and the previous version is kept in the route history.\n- At least one of `cases` or `default` is required; a `default` with empty `channel_ids` counts as absent.\n- Only shared integrations have routing rules: a channel-exclusive or unknown `integration_id`, or a channel ID that does not exist, returns `InvalidParameter`.\n- When the integration belongs to a team, the caller must be the account owner or an admin, the integration's creator, or a member of that team; otherwise `AccessDenied`.\n- A successful response carries only `request_id`, with no `data` field.\n- Every call is recorded in the account audit log.",
           "href": "/en/api-reference/on-call/channels/route-upsert",
           "metadata": {
             "sidebarTitle": "Upsert routing rule"
@@ -6912,8 +7163,7 @@
                   ]
                 },
                 "example": {
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
-                  "data": {}
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
             }
@@ -6924,6 +7174,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -6973,12 +7226,12 @@
       "post": {
         "operationId": "calendarCreate",
         "summary": "Create calendar",
-        "description": "Create a personal service calendar. Each account is limited to 5 calendars unless the Flashcat-Break-Cal-Limit header is set.",
+        "description": "Create a personal service calendar with its weekly workdays and linked holiday calendars.",
         "tags": [
           "On-call/Calendars"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Calendars Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Calendars Manage** (`on-call`) |\n\n## Usage\n\n- A limit of 5 calendars is checked only when the caller is the account owner: once the account holds 5 calendars, the owner's create call returns `InvalidParameter`. Calls made by other members are not counted against this limit.\n- `cal_name` must be unique within the account, `timezone` must be a valid IANA name, and a nonzero `team_id` must be a team of the account; otherwise the call returns `InvalidParameter`.\n- Every call is recorded in the account audit log.",
           "href": "/en/api-reference/on-call/calendars/calendar-create",
           "metadata": {
             "sidebarTitle": "Create calendar"
@@ -7020,6 +7273,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -7060,7 +7316,7 @@
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |\n\n## Usage\n\n- When an acknowledgement form applies, `custom_fields`, `summary`, and `images` must match its visible elements and required rules.\n- For a batch, form values are accepted only when every selected incident resolves to the same form; otherwise acknowledge incidents individually.\n- The legacy `values` and `custom_values` properties are rejected; use `custom_fields`.\n- Audited — changes are recorded in the audit log.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Incidents Manage** or **Channels Manage** (`on-call`) |\n\n## Usage\n\n- When an acknowledgement form applies, `custom_fields`, `summary`, and `images` must match its visible elements and required rules.\n- For a batch, form values are accepted only when every selected incident resolves to the same form; otherwise acknowledge incidents individually.\n- The legacy `values` and `custom_values` properties are rejected; use `custom_fields`.\n- The calling member becomes a responder if not already one, and the incident moves to `Processing`. Acknowledging an incident you have already acknowledged changes nothing.\n- A closed incident or an unknown ID fails the whole call with `InvalidParameter`.",
           "href": "/en/api-reference/on-call/incidents/incident-ack",
           "metadata": {
             "sidebarTitle": "Acknowledge incident"
@@ -7099,6 +7355,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -7127,12 +7386,12 @@
       "post": {
         "operationId": "channelEscalateRuleList",
         "summary": "List escalation rules",
-        "description": "List all escalation rules for a channel.",
+        "description": "List a channel's escalation rules in the order they are evaluated.",
         "tags": [
           "On-call/Channels"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Read** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Read** (`on-call`) or **Channels Manage** (`on-call`) or **Incidents Read** (`on-call`) or **Incidents Manage** (`on-call`) |\n\n## Usage\n\n- An unknown `channel_id` returns `InvalidParameter`.",
           "href": "/en/api-reference/on-call/channels/channel-escalate-rule-list",
           "metadata": {
             "sidebarTitle": "List escalation rules"
@@ -7207,6 +7466,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -7233,12 +7495,12 @@
       "post": {
         "operationId": "channelCreate",
         "summary": "Create channel",
-        "description": "Create a new channel for incident management.",
+        "description": "Create a channel, optionally with a default escalation rule and channel-exclusive integrations.",
         "tags": [
           "On-call/Channels"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |\n\n## Usage\n\n- `channel_name` must be unique within the account; a duplicate returns `InvalidParameter`.\n- `group.method` `p` requires the Standard license or higher and `i` requires the Pro license. Creating a channel beyond the plan's channel quota also returns `NoLicense`.\n- When `escalate_rule` is set, an enabled escalation rule named `Default` is created with one level that notifies `escalate_rule.target` once.\n- Each ID in `plugin_ids` creates one channel-exclusive integration of that integration type, named after the type.\n- When `is_external_report_enabled` is `true`, the response also carries `external_report_token`.\n- Every call is recorded in the account audit log.",
           "href": "/en/api-reference/on-call/channels/channel-create",
           "metadata": {
             "sidebarTitle": "Create channel"
@@ -7268,7 +7530,7 @@
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "channel_id": 6294542005131,
-                    "channel_name": "API Test Channel"
+                    "channel_name": "Production Alerts"
                   }
                 }
               }
@@ -7280,6 +7542,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -7300,6 +7565,11 @@
                 "description": "Handles all production environment alerts",
                 "group": {
                   "method": "p",
+                  "equals": [
+                    [
+                      "labels.service"
+                    ]
+                  ],
                   "time_window": 10,
                   "window_type": "tumbling"
                 },
@@ -7320,7 +7590,7 @@
           "On-call/Status pages"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Public pages list email subscribers and internal pages list IM subscribers.\n- Filtering by `component_ids` also returns subscribers who subscribed to all components.\n- Each item merges all subscriptions of one recipient; subscriptions to individual events are not shown.",
           "href": "/en/api-reference/on-call/status-pages/status-page-subscriber-list",
           "metadata": {
             "sidebarTitle": "List status page subscribers"
@@ -7378,6 +7648,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -7437,12 +7710,12 @@
       "post": {
         "operationId": "incidentInfo",
         "summary": "Get incident detail",
-        "description": "Retrieve detailed information for a single incident including timeline, alerts, responders and custom fields.",
+        "description": "Get one incident by ID or short number, with responders, assignment, custom fields, and alert counts.",
         "tags": [
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Read** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Read** or **Incidents Manage** or **Channels Read** or **Channels Manage** (`on-call`) |\n\n## Usage\n\n- `num` is not unique; when several incidents share it, the most recent one is returned. Prefer `incident_id`.\n- This endpoint does not fill `alerts` or the `account_*` fields. Use `POST /incident/alert/list` for alerts and `POST /incident/feed` for the timeline.\n- Image tokens starting with `img_` in `images` are replaced with download URLs.\n- An unknown incident returns `InvalidParameter`.",
           "href": "/en/api-reference/on-call/incidents/incident-info",
           "metadata": {
             "sidebarTitle": "Get incident detail"
@@ -7508,6 +7781,7 @@
                     "snoozed_before": 0,
                     "group_method": "n",
                     "ever_muted": false,
+                    "has_unfinished_work_item": false,
                     "labels": {
                       "check": "cpu_usage_high",
                       "resource": "web-server-01",
@@ -7559,6 +7833,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -7590,7 +7867,7 @@
           "On-call/Alert enrichment"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Integrations Read** (`on-call`) or **Integrations Manage** (`on-call`) or **Mappings Read** (`on-call`) or **Mappings Manage** (`on-call`) |\n\n## Usage\n\n- Returns `null` if the schema does not exist.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Integrations Read** (`on-call`) or **Integrations Manage** (`on-call`) or **Mappings Read** (`on-call`) or **Mappings Manage** (`on-call`) |\n\n## Usage\n\n- Returns `data: null` when no schema with this ID exists in the account.\n- A soft-deleted schema is still returned, with `status` = `deleted`.",
           "href": "/en/api-reference/on-call/alert-enrichment/mapping-schema-read-info",
           "metadata": {
             "sidebarTitle": "Get mapping schema detail"
@@ -7633,6 +7910,7 @@
                     "status": "enabled",
                     "team_id": 0,
                     "creator_id": 80011,
+                    "updated_by": 80011,
                     "created_at": 1710000000,
                     "updated_at": 1710000000
                   }
@@ -7646,6 +7924,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -7672,12 +7953,12 @@
       "post": {
         "operationId": "statusPageSubscriberImport",
         "summary": "Import subscribers",
-        "description": "Bulk import subscribers for a status page. The account must be allowlisted for subscriber import; otherwise the call is rejected with an access-denied error.",
+        "description": "Bulk import subscribers into a status page without sending confirmation emails.",
         "tags": [
           "On-call/Status pages"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **20 requests/minute**; **2 requests/second** per account |\n| Permissions | **Status Pages Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **60 requests/minute**; **3 requests/second** per account |\n| Permissions | **Status Pages Manage** (`on-call`) |\n\n## Usage\n\n- Requires the On-call Professional plan, and the account must also be allowlisted for subscriber import; otherwise the call returns `AccessDenied`.\n- `method` must match the page: `email` for a public page with email subscription enabled, `im` for an internal page with IM subscription enabled.\n- Each imported recipient's existing subscriptions on this page are replaced by the imported ones.\n- Every `component_ids` and `change_ids` entry must exist on the page; one invalid ID rejects the whole request.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/on-call/status-pages/status-page-subscriber-import",
           "metadata": {
             "sidebarTitle": "Import subscribers"
@@ -7716,6 +7997,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -7763,7 +8047,7 @@
           "On-call/Alerts"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Read** (`on-call`) |\n\n## Usage\n\n- Both `start_time` and `end_time` are required Unix epoch seconds. `start_time` must be less than `end_time`; the span must not exceed 31 days.\n- Results are filtered by the caller's channel data-access permissions.\n- `severities` is a comma-separated string, e.g. `\"Critical,Warning\"`.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Both `start_time` and `end_time` are required Unix epoch seconds. `start_time` must be less than `end_time`; the span must not exceed 31 days.\n- Results are filtered by the caller's channel data-access permissions.\n- `severities` is a comma-separated list matched against `event_severity`, e.g. `\"Critical,Warning\"`. Values are not validated, so an unknown value (or `Ok`) matches nothing.\n- Pass `search_after_ctx` from the previous response for the next page; without it, `p`/`limit` page numbers apply and `p * limit` must stay within 10,000.",
           "href": "/en/api-reference/on-call/alerts/alert-event-read-list",
           "metadata": {
             "sidebarTitle": "List raw alert events"
@@ -7802,7 +8086,8 @@
                         "event_severity": "Critical",
                         "event_time": 1712650000
                       }
-                    ]
+                    ],
+                    "search_after_ctx": "663a1b2c3d4e5f6789abc001"
                   }
                 }
               }
@@ -7814,6 +8099,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -7843,12 +8131,12 @@
       "post": {
         "operationId": "calEventDelete",
         "summary": "Delete calendar event",
-        "description": "Delete one event of a personal calendar by event_id, or clear the calendar's own events off the days [start_at, end_at). Pass either event_id or both start_at and end_at. Cleared days fall back to the linked holiday calendars and the weekly workdays.",
+        "description": "Delete one personal-calendar event by ID, or clear the calendar's own events from a date range.",
         "tags": [
           "On-call/Calendars"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Calendars Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Calendars Manage** (`on-call`) |\n\n## Usage\n\n- Pass either `event_id`, or both `start_at` and `end_at` (dates in `YYYY-MM-DD`, covering [`start_at`, `end_at`)); any other combination returns `InvalidParameter`.\n- Cleared days fall back to the linked holiday calendars and the weekly workdays.\n- Only personal calendars can be changed, and only by the account owner, an administrator, the calendar creator, or a member of the calendar's team; other callers get `AccessDenied`.\n- Every call is recorded in the account audit log.",
           "href": "/en/api-reference/on-call/calendars/cal-event-delete",
           "metadata": {
             "sidebarTitle": "Delete calendar event"
@@ -7887,6 +8175,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -7919,7 +8210,7 @@
           "On-call/Alerts"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Integrations Read** (`on-call`) |\n\n## Usage\n\n- All `integration_ids` must be accessible to the caller.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Integrations Read** (`on-call`) or **Integrations Manage** (`on-call`) |\n\n## Usage\n\n- Every `integration_ids` entry must be an integration of the account; one unknown ID fails the whole request with `InvalidParameter`.\n- `items` holds one entry per integration that has a pipeline; integrations without one are absent.",
           "href": "/en/api-reference/on-call/alerts/alert-read-pipeline-list",
           "metadata": {
             "sidebarTitle": "List alert pipelines"
@@ -7965,11 +8256,11 @@
                             ],
                             "settings": {
                               "equals": [
-                                "service"
+                                "labels.service"
                               ],
                               "source_filters": [
                                 {
-                                  "key": "alert_severity",
+                                  "key": "severity",
                                   "oper": "IN",
                                   "vals": [
                                     "Critical"
@@ -7997,6 +8288,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -8026,12 +8320,12 @@
       "get": {
         "operationId": "incidentPostMortemInfo",
         "summary": "Get post-mortem",
-        "description": "Retrieve a post-mortem report by its `post_mortem_id`. List reports via `/incident/post-mortem/list` first — each row carries the incident it covers — then fetch the full report here by that id.",
+        "description": "Get the full content and auto-aggregated basics of a post-mortem report by its ID.",
         "tags": [
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Read** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Get `post_mortem_id` from `POST /incident/post-mortem/list`, or from an incident's `post_mortem_id`.\n- Private post-mortems can be read only by account owners, admins, and members of the post-mortem's team; others get `AccessDenied`.\n- An unknown `post_mortem_id` returns `ResourceNotFound`.",
           "href": "/en/api-reference/on-call/incidents/incident-post-mortem-info",
           "metadata": {
             "sidebarTitle": "Get post-mortem"
@@ -8076,6 +8370,8 @@
                       "team_id": 2477033058131,
                       "channel_id": 3047621227131,
                       "is_private": false,
+                      "generation": 0,
+                      "revision": 12,
                       "channel_name": "Ops Channel",
                       "created_at_seconds": 1773900354,
                       "updated_at_seconds": 1773909012
@@ -8096,7 +8392,8 @@
                     "content": {
                       "content": "{\"type\":\"doc\",\"content\":[]}"
                     },
-                    "follow_ups": ""
+                    "follow_ups": "",
+                    "has_active_incident": false
                   }
                 }
               }
@@ -8108,6 +8405,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -8123,7 +8423,7 @@
             "schema": {
               "type": "string"
             },
-            "description": "Post-mortem ID. Deterministic hash derived from account ID and the set of linked incident IDs."
+            "description": "Post-mortem ID: a 32-character hex string derived from the account ID and the linked incident IDs."
           }
         ]
       }
@@ -8132,12 +8432,12 @@
       "post": {
         "operationId": "calEventList",
         "summary": "List calendar events",
-        "description": "Return events for a personal calendar within a year/month/day scope. When month and day are both omitted the whole year is returned. The response also carries days, the resolved state of every day in the scope.",
+        "description": "Return a personal calendar's events for a year, month or day, plus the resolved state of each day.",
         "tags": [
           "On-call/Calendars"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- `year` defaults to the current year; without `month` the whole year is returned, and `day` requires `month`.\n- `items` merges the calendar's own events (`cale.*` IDs), one generated `non_work.YYYYMMDD` entry per non-working weekday when `workdays` is set, and the events of the linked holiday calendars; `total` counts all of them.\n- `days` gives the resolved state of every day in the scope.\n- Only personal calendars (`cal_id` starting with `cal.`) are supported; other IDs return `InvalidParameter`.",
           "href": "/en/api-reference/on-call/calendars/cal-event-list",
           "metadata": {
             "sidebarTitle": "List calendar events"
@@ -8226,6 +8526,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -8259,7 +8562,7 @@
           "On-call/Status pages"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Status Pages Events Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Status Pages Events Manage** (`on-call`) |\n\n## Usage\n\n- `at_seconds` must not be earlier than the event's latest timeline entry.\n- Component changes whose status equals the component's current status are dropped from the stored entry.\n- Moving to `resolved` or `completed` requires every affected component to be `operational`; posting a non-terminal status on a closed event reopens it.\n- The event description is set to this entry's description. If the event has `notify_subscribers` enabled, subscribers are notified about this entry.\n- Manually moving an auto-updating maintenance to `ongoing` or `completed` cancels the matching scheduled transition.\n- Pass `draft_id` to publish a stored draft whose `change_id` is this event; a draft can be published only once.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/on-call/status-pages/status-page-change-timeline-create",
           "metadata": {
             "sidebarTitle": "Create event timeline entry"
@@ -8300,6 +8603,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -8336,12 +8642,12 @@
       "post": {
         "operationId": "incidentDisableMerge",
         "summary": "Disable incident merge",
-        "description": "Disable automatic merging for a specific incident.",
+        "description": "Stop new alerts and events from being merged into the given incidents.",
         "tags": [
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Later events no longer merge into the incidents' existing alerts, and alert grouping no longer adds new alerts to these incidents.\n- IDs that do not match an incident are ignored.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/on-call/incidents/incident-disable-merge",
           "metadata": {
             "sidebarTitle": "Disable incident merge"
@@ -8380,6 +8686,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -8408,12 +8717,12 @@
       "post": {
         "operationId": "statusPageMigrationCancel",
         "summary": "Cancel status page migration",
-        "description": "Cancel an in-progress status page migration job. Only jobs currently in the `running` state can be cancelled.",
+        "description": "Cancel a running Atlassian Statuspage migration job.",
         "tags": [
           "On-call/Status pages"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Status Pages Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Only a job whose `status` is `running` can be cancelled; otherwise the call returns `InvalidParameter`.\n- The job is marked `cancelled` at once and the account can start a new migration; data already imported is kept.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/on-call/status-pages/status-page-migration-cancel",
           "metadata": {
             "sidebarTitle": "Cancel status page migration"
@@ -8452,6 +8761,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -8478,12 +8790,12 @@
       "post": {
         "operationId": "enrichment-write-upsert",
         "summary": "Upsert enrichment rules",
-        "description": "Create or fully replace the enrichment rule set for an integration. The entire `rules` array is replaced atomically.",
+        "description": "Create or replace the whole enrichment rule set of an integration.",
         "tags": [
           "On-call/Alert enrichment"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) or **Integrations Manage** (`on-call`) |\n\n## Usage\n\n- Enrichment rules are evaluated in order.\n- Each rule has a `kind`: `extraction` (regex/gjson extraction), `composition` (template-based label composition), `mapping` (lookup via mapping schema or API), or `drop` (remove labels).\n- The optional `if` field is an `AndFilters` condition: if it does not match, the rule is skipped.\n- For `kind: extraction`: `source_field` must be `title`, `description`, or a `labels.*` key; specify exactly one of `pattern` (RE2 regex — its capture groups are joined with a space and written to `result_label`) or `g_json` (GJson path).\n- For `kind: composition`: `template` is a Go text/template rendered against the event struct, e.g. `{{.Title}}`, `{{.Description}}`, `{{.Labels.key}}`.\n- For `kind: mapping`: `mapping_type` is `schema` (default) or `api`; provide `schema_id` or `api_id` accordingly.\n- For `kind: drop`: `drop_labels` lists the label keys to remove.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) or **Integrations Manage** (`on-call`) |\n\n## Usage\n\n- `rules` replaces the stored rule set as a whole; send `[]` to remove all rules.\n- The integration must exist (`InvalidParameter` otherwise) and the caller must be allowed to edit it: an account admin, the integration's creator, someone who can edit its channel (for an integration inside a channel), or a member of its owning team. Integrations with no team and no channel can be edited by any member. Others get `AccessDenied`.\n- Rules run in array order on every incoming alert and change event, and each rule sees the labels written by the rules before it. A rule whose `if` conditions do not all match is skipped; a rule that fails at run time (no regex match, lookup miss, API error) is skipped without affecting the event.\n- Condition keys in `if` must be alert or change event keys (for example `title`, `description`, `labels.<name>`); other keys return `InvalidParameter`.\n- `schema_id` and `api_id` are not checked on save; a rule pointing at a missing or deleted schema or API does nothing at run time. `mapping` rules with `mapping_type` = `api` run for alert events only.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/on-call/alert-enrichment/enrichment-write-upsert",
           "metadata": {
             "sidebarTitle": "Upsert enrichment rules"
@@ -8522,6 +8834,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -8567,12 +8882,12 @@
       "post": {
         "operationId": "alert-read-list-by-ids",
         "summary": "List alerts by IDs",
-        "description": "Return the details of multiple alerts by their IDs in a single request. Note: this endpoint does not paginate — `total` and `has_next_page` are always `0`/`false` and `search_after_ctx` is never set.",
+        "description": "Return the details of several alerts by ID in one request, without pagination.",
         "tags": [
           "On-call/Alerts"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Read** (`on-call`) |\n\n## Usage\n\n- All provided `alert_ids` must belong to the caller's account; any invalid ID causes the entire request to fail.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Read** (`on-call`) or **Channels Manage** (`on-call`) or **Incidents Read** (`on-call`) or **Incidents Manage** (`on-call`) |\n\n## Usage\n\n- A malformed ID fails the request with `InvalidParameter`; well-formed IDs not found in the account are left out of `items`.\n- The response is not paginated: `total` is always `0`, `has_next_page` is always `false`, and `search_after_ctx` is omitted.",
           "href": "/en/api-reference/on-call/alerts/alert-read-list-by-ids",
           "metadata": {
             "sidebarTitle": "List alerts by IDs"
@@ -8620,6 +8935,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -8648,12 +8966,12 @@
       "post": {
         "operationId": "channelEscalateRuleEnable",
         "summary": "Enable escalation rule",
-        "description": "Enable a disabled escalation rule. Only a `disabled` rule can be enabled.",
+        "description": "Enable a disabled escalation rule so it can take new incidents again.",
         "tags": [
           "On-call/Channels"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |\n\n## Usage\n\n- Only a `disabled` rule can be enabled; any other status returns `InvalidParameter`.\n- An unknown `channel_id` or `rule_id` returns `InvalidParameter`.\n- The caller must also be able to edit the channel: the account owner or an admin, the channel creator, or a member of its managing teams (of its owning team when `managing_team_ids` is empty). Otherwise the call returns `AccessDenied`.\n- Every call is recorded in the account audit log.",
           "href": "/en/api-reference/on-call/channels/channel-escalate-rule-enable",
           "metadata": {
             "sidebarTitle": "Enable escalation rule"
@@ -8692,6 +9010,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -8724,7 +9045,7 @@
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Read** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Read** or **Incidents Manage** or **Channels Read** or **Channels Manage** or **Templates Read** or **Templates Manage** (`on-call`) |\n\n## Usage\n\n- Only incidents in channels the caller can access are returned.\n- `start_time` and `end_time` filter on incident start time and may span at most 31 days. A `start_time` earlier than the account's data retention period is moved up to the retention boundary; an `end_time` before that boundary fails with `InvalidParameter`.\n- Results are sorted by `start_time`, newest first unless `asc` is `true`.\n- Paginate with `p` and `limit`, or pass the previous response's `search_after_ctx`, in which case `p` is ignored.\n- `total` is capped at 1,000. With `p`/`limit` paging, `has_next_page` turns `false` once `p` × `limit` reaches 1,000 even if more incidents match. To read further, pass the `search_after_ctx` returned with every non-empty page; in cursor mode `has_next_page` reflects whether more rows really exist.\n- Without `progress`, incidents in every progress state are returned.",
           "href": "/en/api-reference/on-call/incidents/incident-list",
           "metadata": {
             "sidebarTitle": "List incidents"
@@ -8795,6 +9116,7 @@
                         "snoozed_before": 0,
                         "group_method": "n",
                         "ever_muted": false,
+                        "has_unfinished_work_item": false,
                         "labels": {
                           "check": "cpu_usage_high",
                           "resource": "web-server-01",
@@ -8848,6 +9170,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -8887,7 +9212,7 @@
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Read** (`on-call`) |\n\n## Usage\n\n- Use this endpoint to inspect synchronization mappings between ServiceDeskPlus requests and Flashduty incidents, including the external request link and sync status.\n- When `incident_id` is not provided, `start_time` and `end_time` are required Unix-second timestamps; the time window cannot exceed 30 days.\n- `status` accepts only `success` and `failed`, representing successful and failed synchronization records.\n- Results are sorted by the internal record ID. Set `asc` to `true` for ascending order; otherwise records are returned descending. Pass the returned `search_after_ctx` to continue pagination.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Read** or **Incidents Manage** or **Channels Read** or **Channels Manage** (`on-call`) |\n\n## Usage\n\n- Use this endpoint to inspect synchronization mappings between ServiceDeskPlus requests and Flashduty incidents, including the external request link and sync status.\n- When `incident_id` is not provided, `start_time` and `end_time` are required Unix-second timestamps; the time window cannot exceed 30 days.\n- `status` accepts only `success` and `failed`, representing successful and failed synchronization records.\n- Results are sorted by the internal record ID. Set `asc` to `true` for ascending order; otherwise records are returned descending.\n- Pagination uses only `search_after_ctx`: pass the value returned by the previous response; `p` is ignored.",
           "href": "/en/api-reference/on-call/incidents/incident-service-desk-plus-request-read-list",
           "metadata": {
             "sidebarTitle": "Get ServiceDeskPlus linked incidents"
@@ -8943,6 +9268,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -8980,7 +9308,7 @@
           "On-call/Analytics"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Analytics Read** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Analytics Read** (`on-call`) |\n\n## Usage\n\n- Only the time range, `team_ids`, `channel_ids`, `severities`, `is_my_team` and `split_hours` filter the result; other filter fields and `aggregate_unit` are ignored.\n- Alerts are counted in hourly buckets, so the effective range is aligned to whole hours.\n- With `split_hours: true`, the top `k` is computed separately for each of `work`, `sleep` and `off`, so up to 3 × `k` rows come back.\n- Members who are neither the account owner nor an admin only get data from channels they can access; other channels are silently excluded.",
           "href": "/en/api-reference/on-call/analytics/insight-topk-alerts-by-label",
           "metadata": {
             "sidebarTitle": "Get top-K alerts grouped by check or resource"
@@ -9037,6 +9365,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -9072,7 +9403,7 @@
           "On-call/Alert enrichment"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Integrations Read** (`on-call`) or **Integrations Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Integrations Read** (`on-call`) or **Integrations Manage** (`on-call`) |\n\n## Usage\n\n- Every ID must be an existing integration of the account; otherwise `InvalidParameter`.\n- Integrations that have no rule set are left out of `items`.",
           "href": "/en/api-reference/on-call/alert-enrichment/enrichment-read-list",
           "metadata": {
             "sidebarTitle": "List enrichment rules"
@@ -9123,6 +9454,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -9152,12 +9486,12 @@
       "post": {
         "operationId": "channelSilenceRuleDisable",
         "summary": "Disable silence rule",
-        "description": "Disable a silence rule without deleting it. Only an `enabled` rule can be disabled.",
+        "description": "Disable a silence rule without deleting it.",
         "tags": [
           "On-call/Channels"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |\n\n## Usage\n\n- Only an `enabled` rule can be disabled; any other status returns `InvalidParameter`.\n- An unknown `channel_id` or `rule_id` returns `InvalidParameter`.\n- The caller must also be able to edit the channel: the account owner or an admin, the channel creator, or a member of its managing teams (of its owning team when `managing_team_ids` is empty). Otherwise the call returns `AccessDenied`.\n- Every call is recorded in the account audit log.",
           "href": "/en/api-reference/on-call/channels/channel-silence-rule-disable",
           "metadata": {
             "sidebarTitle": "Disable silence rule"
@@ -9196,6 +9530,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -9228,7 +9565,7 @@
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Incidents Manage** or **Channels Manage** (`on-call`) |\n\n## Usage\n\n- The integration must be an enabled custom action integration whose channels include the incident's channel; otherwise the call fails with `InvalidParameter`.\n- The server posts the incident payload to the action's URL with a 2-second timeout. If that request fails, the call still returns HTTP 200 with the error in `data.message`; on success `data` is `null`.\n- A successful run adds an `i_custom` timeline entry.",
           "href": "/en/api-reference/on-call/incidents/incident-custom-action-do",
           "metadata": {
             "sidebarTitle": "Execute custom action"
@@ -9256,9 +9593,7 @@
                 },
                 "example": {
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
-                  "data": {
-                    "message": ""
-                  }
+                  "data": null
                 }
               }
             }
@@ -9269,6 +9604,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -9301,7 +9639,7 @@
           "On-call/Alerts"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Read** (`on-call`) |\n\n## Usage\n\n- Use `p` (page number, starting at 1) and `limit` (max 100, default 20) for pagination.\n- Set `asc` to `true` for chronological order.\n- Use `types` to filter by specific feed types (e.g. `a_comm`, `a_merge`).",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Use `p` (page number, starting at 1) and `limit` (max 100, default 20) for pagination.\n- Set `asc` to `true` for chronological order.\n- Use `types` to filter by specific feed types (e.g. `a_comm`, `a_merge`).\n- An `alert_id` not found in the account returns `InvalidParameter`.",
           "href": "/en/api-reference/on-call/alerts/alert-read-feed",
           "metadata": {
             "sidebarTitle": "List alert activity feed"
@@ -9338,8 +9676,10 @@
                         "detail": {
                           "comment": "Investigating now."
                         },
+                        "account_id": 10023,
                         "creator_id": 80011,
-                        "created_at": 1712651000
+                        "created_at": 1712651000000,
+                        "updated_at": 1712651000000
                       }
                     ]
                   }
@@ -9353,6 +9693,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -9381,12 +9724,12 @@
       "post": {
         "operationId": "insightResponderExport",
         "summary": "Export responder insight",
-        "description": "Export responder insight metrics as a CSV file — one row per responder (and per time/hour bucket when `aggregate_unit`/`split_hours` is used). The response is a CSV stream delivered with `Content-Disposition: attachment` — it is not a JSON envelope. `time_zone` defaults to UTC. Rows without a valid responder ID are skipped. Valid `export_fields` keys: responder_id, responder_name, total_incident_cnt, total_incidents_acknowledged, total_incidents_reassigned, total_incidents_escalated, total_incidents_manually_escalated, total_incidents_timeout_escalated, total_interruptions, total_notifications, total_engaged_seconds, mean_seconds_to_ack, acknowledgement_pct, hours. The `hours` column is included by default only when `split_hours` is true. For compatibility, incident-export column keys are also accepted but produce empty columns.",
+        "description": "Export responder insight metrics as a CSV file with the same rows as `/insight/responder`.",
         "tags": [
           "On-call/Analytics"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **100 requests/day**; **20 requests/minute**; **10 requests/second** per account |\n| Permissions | **Analytics Read** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **100 requests/day**; **20 requests/minute**; **10 requests/second** per account |\n| Permissions | **Analytics Read** (`on-call`) |\n\n## Usage\n\n- The response is a CSV file (`Content-Type: application/octet-stream`), not a JSON envelope. Validation errors are returned as JSON before any CSV bytes are written.\n- Takes the same filters as `/insight/responder`. Rows without a responder ID are skipped. The file has no time-bucket column, so with `aggregate_unit` the rows of different buckets cannot be told apart; export one bucket per request if you need the split.\n- `export_fields` sets the columns and their order: responder_id, responder_name, total_incident_cnt, total_incidents_acknowledged, total_incidents_reassigned, total_incidents_escalated, total_incidents_manually_escalated, total_incidents_timeout_escalated, total_interruptions, total_notifications, total_engaged_seconds, mean_seconds_to_ack, acknowledgement_pct, hours. Unknown or duplicate keys are rejected. When it is omitted, all columns are exported, and `hours` is included only when `split_hours` is true.\n- The incident-snapshot keys (progress, assigned_to, raw_assigned_to, escalate_rule_name, responders, raw_responders, ackers, owner_id, owner_name, creator_id, creator_name, closer_id, closer_name, snooze_status, snoozed_before, ever_muted, frequency, is_rare, alert_cnt, active_alert_cnt, alert_event_cnt, description, labels, fields) are also accepted for compatibility and produce empty columns.\n- Column headers are localized (request locale, then the member's, then the account's). Time buckets follow `time_zone` (UTC when omitted).",
           "href": "/en/api-reference/on-call/analytics/insight-responder-export",
           "metadata": {
             "sidebarTitle": "Export responder insight"
@@ -9400,7 +9743,7 @@
                 "schema": {
                   "type": "string",
                   "format": "binary",
-                  "description": "CSV file stream (`Content-Type: application/octet-stream`, `Content-Disposition: attachment; filename=responder_export_yyyyMMdd_HHmmss.csv`). The first row holds localized column headers. Columns default to the full field set, or the keys given in `export_fields`."
+                  "description": "CSV file (`Content-Type: application/octet-stream`, `Content-Disposition: attachment; filename*=UTF-8''responder_export_yyyyMMdd_HHmmss.csv`). The first row holds localized column headers."
                 },
                 "example": "responder_id,responder_name,total_incident_cnt,total_incidents_acknowledged\n3790925372131,alice,5,4\n"
               }
@@ -9412,6 +9755,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -9451,7 +9797,7 @@
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Read** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Read** or **Incidents Manage** or **Channels Read** (`on-call`) |\n\n## Usage\n\n- IDs that do not match an incident are omitted; `total` is the number of incidents found and `has_next_page` is always `false`.\n- Results are sorted by `start_time`, newest first.\n- This endpoint does not fill `integration_type` or `assigned_to.escalate_rule_name`.",
           "href": "/en/api-reference/on-call/incidents/incident-list-by-ids",
           "metadata": {
             "sidebarTitle": "List incidents by IDs"
@@ -9480,7 +9826,7 @@
                 "example": {
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
-                    "total": 2,
+                    "total": 1,
                     "has_next_page": false,
                     "items": [
                       {
@@ -9521,6 +9867,7 @@
                         "snoozed_before": 0,
                         "group_method": "n",
                         "ever_muted": false,
+                        "has_unfinished_work_item": false,
                         "labels": {},
                         "fields": {},
                         "assigned_to": {
@@ -9559,6 +9906,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -9588,12 +9938,12 @@
       "post": {
         "operationId": "incidentPostMortemList",
         "summary": "List post-mortems",
-        "description": "List post-mortem reports with optional filters.",
+        "description": "List post-mortem reports, optionally filtered by status, team, channel, and creation time.",
         "tags": [
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Read** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Account owners and admins see all post-mortems; other members see public ones plus private ones that belong to their own teams.\n- Results are sorted by `order_by` (default `created_at_seconds`), descending unless `asc` is `true`.\n- Items carry metadata only; fetch the full report with `GET /incident/post-mortem/info`.",
           "href": "/en/api-reference/on-call/incidents/incident-post-mortem-list",
           "metadata": {
             "sidebarTitle": "List post-mortems"
@@ -9641,6 +9991,8 @@
                         "team_id": 2477033058131,
                         "channel_id": 3047621227131,
                         "is_private": false,
+                        "generation": 0,
+                        "revision": 12,
                         "channel_name": "Ops Channel",
                         "created_at_seconds": 1773900354,
                         "updated_at_seconds": 1773909012
@@ -9657,6 +10009,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -9685,12 +10040,12 @@
       "post": {
         "operationId": "mapping-api-read-list",
         "summary": "List mapping APIs",
-        "description": "Return all mapping APIs configured for the account.",
+        "description": "Return all mapping APIs of the account, newest first.",
         "tags": [
           "On-call/Alert enrichment"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Mappings Read** (`on-call`) or **Mappings Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Mappings Read** (`on-call`) or **Mappings Manage** (`on-call`) |\n\n## Usage\n\n- Returns every non-deleted mapping API in one response, without pagination; `total` is the number of items.\n- Mapping APIs of all teams are returned, with their `headers` in plain text.",
           "href": "/en/api-reference/on-call/alert-enrichment/mapping-api-read-list",
           "metadata": {
             "sidebarTitle": "List mapping APIs"
@@ -9727,7 +10082,7 @@
                         "description": "Query CMDB for host metadata",
                         "url": "https://cmdb.example.com/api/lookup",
                         "headers": {
-                          "Authorization": "Bearer eyJhbGciOiJIUzI1NiJ9.example-token"
+                          "X-Token": "example-token"
                         },
                         "timeout": 2,
                         "retry_count": 1,
@@ -9735,6 +10090,7 @@
                         "status": "enabled",
                         "team_id": 0,
                         "creator_id": 80011,
+                        "updated_by": 80011,
                         "created_at": 1710000000,
                         "updated_at": 1710000000
                       }
@@ -9750,6 +10106,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -9774,12 +10133,12 @@
       "post": {
         "operationId": "incidentUnack",
         "summary": "Unacknowledge incident",
-        "description": "Remove the acknowledge status from an incident.",
+        "description": "Withdraw the calling member's acknowledgement of one or more incidents.",
         "tags": [
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Incidents Manage** or **Channels Manage** (`on-call`) |\n\n## Usage\n\n- Only the calling member's acknowledgement is removed. The incident returns to `Triggered`, and any snooze is cleared, only when no other responder still has it acknowledged.\n- Every incident must be in `Processing`; a `Triggered` or `Closed` incident fails the whole call with `InvalidParameter`.",
           "href": "/en/api-reference/on-call/incidents/incident-unack",
           "metadata": {
             "sidebarTitle": "Unacknowledge incident"
@@ -9818,6 +10177,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -9851,7 +10213,7 @@
           "On-call/Alert enrichment"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Mappings Manage** (`on-call`) |\n\n## Usage\n\n- Only the schema creator, account admin, or team member can update the schema.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Mappings Manage** (`on-call`) |\n\n## Usage\n\n- Fields left out keep their current values; `team_id` `0` removes the team.\n- An unknown `schema_id` returns `InvalidParameter`; a new `schema_name` must not be used by another schema.\n- Only an account admin, the schema creator, or a member of the schema's owning team may call this; others get `AccessDenied`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/on-call/alert-enrichment/mapping-schema-write-update",
           "metadata": {
             "sidebarTitle": "Update mapping schema"
@@ -9890,6 +10252,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -9918,12 +10283,12 @@
       "post": {
         "operationId": "scheduleCreate",
         "summary": "Create schedule",
-        "description": "Create a new on-call schedule (escalation rule schedule).",
+        "description": "Create an on-call schedule with its rotation layers and shift notification settings.",
         "tags": [
           "On-call/Schedules"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Schedules Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Schedules Manage** (`on-call`) |\n\n## Usage\n\n- `schedule_name` (or the legacy `name`) is required, at most 40 characters, and must be unique in the account. `description` is at most 500 characters.\n- `time_zone` anchors every wall-clock rule of the schedule (handoff time, restriction windows, weekdays, fixed-time notifications) and cannot be changed later. When omitted, the schedule is evaluated in `Asia/Shanghai` and `time_zone` reads back as an empty string.\n- Layer times can be sent either as numbers (`layer_start`, `handoff_time`, `restrict_periods`, …) or as wall-clock strings (`starts_at`, `ends_at`, `handoff`, `restricts_wall`); wall-clock fields win and are converted in the schedule's time zone.\n- Creating more schedules than the account's plan allows is rejected with `NoLicense`.\n- Use `/schedule/preview` to check the resulting shifts before saving.\n- Every call is recorded in the account audit log.",
           "href": "/en/api-reference/on-call/schedules/schedule-create",
           "metadata": {
             "sidebarTitle": "Create schedule"
@@ -9964,6 +10329,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -9982,6 +10350,7 @@
                 "schedule_name": "Production On-Call",
                 "description": "Primary on-call rotation for the production team",
                 "team_id": 4291079133131,
+                "time_zone": "Asia/Shanghai",
                 "layers": [
                   {
                     "layer_name": "Layer 1",
@@ -10061,12 +10430,12 @@
       "post": {
         "operationId": "insightByChannel",
         "summary": "Get channel insight",
-        "description": "Return insight metrics aggregated by channel.",
+        "description": "Return incident and alert metrics grouped by channel, one row per channel per time bucket.",
         "tags": [
           "On-call/Analytics"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Analytics Read** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Analytics Read** (`on-call`) |\n\n## Usage\n\n- One row per channel per time bucket. `responder_ids` and `incident_ids` are ignored.\n- Incidents are counted by creation time. Rows are sorted by `ts` from newest to oldest, and a bucket (or dimension value) with no incidents produces no row — missing rows mean zero. `split_hours: true` returns up to three rows per bucket, one per `hours` value.\n- `total_alert_cnt`, `total_alert_event_cnt` and `noise_reduction_pct` honor only the time range, team, channel and severity filters; `query`, `labels`, `fields` and the duration filters apply to incident metrics only.\n- Members who are neither the account owner nor an admin only get data from channels they can access; other channels are silently excluded.\n- With `is_my_team: true`, `team_ids` is narrowed to the caller's teams; a caller who belongs to no team gets an empty result.",
           "href": "/en/api-reference/on-call/analytics/insight-by-channel",
           "metadata": {
             "sidebarTitle": "Get channel insight"
@@ -10134,6 +10503,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -10165,12 +10537,12 @@
       "post": {
         "operationId": "channelDelete",
         "summary": "Delete channel",
-        "description": "Delete a channel. Only a `disabled` channel can be deleted; all of its escalation, silence, drop and inhibit rules are deleted with it. The call fails when an integration route still references the channel.",
+        "description": "Delete a disabled channel together with its rules and channel-exclusive integrations.",
         "tags": [
           "On-call/Channels"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |\n\n## Usage\n\n- Only a `disabled` channel can be deleted; any other status returns `InvalidParameter`.\n- If a shared integration's routing rule still targets the channel (in a case or the default branch), the call returns HTTP 400 with `error.code` `ReferenceExist` and the referencing integrations in `data.refs`. Remove the channel from those routes with `POST /route/upsert` first.\n- All escalation, silence, drop, inhibit and subscribe rules of the channel and its channel-exclusive integrations are deleted. The channel itself is soft-deleted: `POST /channel/info` still returns it with `status` `deleted`.\n- An unknown `channel_id` returns `InvalidParameter`.\n- The caller must also be able to edit the channel: the account owner or an admin, the channel creator, or a member of its managing teams (of its owning team when `managing_team_ids` is empty). Otherwise the call returns `AccessDenied`.\n- Every call is recorded in the account audit log.",
           "href": "/en/api-reference/on-call/channels/channel-delete",
           "metadata": {
             "sidebarTitle": "Delete channel"
@@ -10209,6 +10581,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -10235,12 +10610,12 @@
       "post": {
         "operationId": "channelUnsubscribeRuleCreate",
         "summary": "Create drop rule",
-        "description": "Create a drop rule to filter out unwanted alerts before they become incidents.",
+        "description": "Create a drop rule that discards matching alert events before any alert or incident is created.",
         "tags": [
           "On-call/Channels"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Drop rules are checked first, before silence and inhibit rules. An event matching any enabled drop rule is discarded: no alert, incident or notification is produced.\n- Without `filters`, or with an empty list, the rule matches nothing.\n- An unknown `channel_id` returns `InvalidParameter`.\n- The caller must also be able to edit the channel: the account owner or an admin, the channel creator, or a member of its managing teams (of its owning team when `managing_team_ids` is empty). Otherwise the call returns `AccessDenied`.\n- Every call is recorded in the account audit log.",
           "href": "/en/api-reference/on-call/channels/channel-unsubscribe-rule-create",
           "metadata": {
             "sidebarTitle": "Create drop rule"
@@ -10270,7 +10645,7 @@
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "rule_id": "69db2f6ba0fe7db6448b1505",
-                    "rule_name": "Test drop rule"
+                    "rule_name": "Drop test environment alerts"
                   }
                 }
               }
@@ -10282,6 +10657,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -10322,12 +10700,12 @@
       "post": {
         "operationId": "channelInhibitRuleUpdate",
         "summary": "Update inhibit rule",
-        "description": "Update an existing inhibit rule configuration.",
+        "description": "Replace the configuration of an existing inhibit rule.",
         "tags": [
           "On-call/Channels"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |\n\n## Usage\n\n- Full replacement: omitted `source_filters` and `target_filters` become empty, an omitted `is_directly_discard` becomes `false`, and an omitted `description` becomes empty.\n- An unknown `channel_id` or `rule_id` returns `InvalidParameter`.\n- The caller must also be able to edit the channel: the account owner or an admin, the channel creator, or a member of its managing teams (of its owning team when `managing_team_ids` is empty). Otherwise the call returns `AccessDenied`.\n- Every call is recorded in the account audit log.",
           "href": "/en/api-reference/on-call/channels/channel-inhibit-rule-update",
           "metadata": {
             "sidebarTitle": "Update inhibit rule"
@@ -10366,6 +10744,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -10397,12 +10778,12 @@
       "post": {
         "operationId": "alert-write-merge",
         "summary": "Merge alerts into an incident",
-        "description": "Associate one or more alerts with an existing incident. If a source alert previously belonged to a different incident and that incident becomes empty after the merge, it will be automatically closed.",
+        "description": "Move one or more alerts into an existing incident and close source incidents left empty.",
         "tags": [
           "On-call/Alerts"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Read** (`on-call`) |\n\n## Usage\n\n- All `alert_ids` and the `incident_id` must belong to the caller's account.\n- Optionally set `title` and `owner_id` to update the target incident at the same time.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Every `alert_ids` entry and the `incident_id` must belong to the account; an unknown ID returns `InvalidParameter`.\n- Alerts already in the target incident are skipped. A source incident left with no alerts is closed.\n- `title` and `owner_id` update the target incident only when they differ from its current values.\n- Only one incident change runs per account at a time; a concurrent call returns `RequestTooFrequently`.",
           "href": "/en/api-reference/on-call/alerts/alert-write-merge",
           "metadata": {
             "sidebarTitle": "Merge alerts into an incident"
@@ -10422,7 +10803,7 @@
                       "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/EmptyResponse"
+                          "$ref": "#/components/schemas/EmptyObject"
                         }
                       }
                     }
@@ -10441,6 +10822,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -10470,12 +10854,12 @@
       "post": {
         "operationId": "statusPageChangeTimelineUpdate",
         "summary": "Update event timeline entry",
-        "description": "Update a timeline entry for a status page event.",
+        "description": "Edit the time or description of a status page event timeline entry.",
         "tags": [
           "On-call/Status pages"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Status Pages Events Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Status Pages Events Manage** (`on-call`) |\n\n## Usage\n\n- Only `at_seconds` and `description` can be edited; an entry's status and component changes are fixed.\n- Pass at least one of `at_seconds` (greater than 0) or a non-empty `description`; otherwise the call returns `InvalidParameter`.\n- `at_seconds` must stay between the previous and next entries; editing the first entry also moves the event start time.\n- Editing the latest entry's description also updates the event description. No subscriber notification is sent.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/on-call/status-pages/status-page-change-timeline-update",
           "metadata": {
             "sidebarTitle": "Update event timeline entry"
@@ -10514,6 +10898,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -10544,12 +10931,12 @@
       "post": {
         "operationId": "incidentReopen",
         "summary": "Reopen incident",
-        "description": "Reopen a previously resolved incident.",
+        "description": "Reopen closed incidents and dispatch them again from the first escalation level.",
         "tags": [
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Incidents Manage** or **Channels Manage** (`on-call`) |\n\n## Usage\n\n- Every incident must be `Closed`; otherwise the whole call fails with `InvalidParameter`.\n- Reopened incidents return to `Triggered`, with `ack_time`, `close_time`, `closer_id`, and every responder's acknowledgement reset.\n- Each incident is reassigned to its previous assignment target starting at the first escalation level, with `assigned_to.type` set to `reopen`.\n- Returns `RequestTooFrequently` while another resolve, reopen, merge, comment, or delete is running in the same account; retry after a short delay.",
           "href": "/en/api-reference/on-call/incidents/incident-reopen",
           "metadata": {
             "sidebarTitle": "Reopen incident"
@@ -10588,6 +10975,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -10622,7 +11012,7 @@
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |\n\n## Usage\n\n- To mention a member, embed a markdown link in `comment` in the form `[@Display Name](flashduty://ref/member/<member_id>)`. Mentioned members receive a dedicated personal notification, which is not affected by `mute_reply`.\n- Plain `@name` text without the link syntax does not create a mention.\n- The server rewrites each mention's display label to the member's canonical name.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Incidents Manage** or **Channels Manage** (`on-call`) |\n\n## Usage\n\n- To mention a member, embed a markdown link in `comment` in the form `[@Display Name](flashduty://ref/member/<member_id>)`. Mentioned members receive a dedicated personal notification, which is not affected by `mute_reply`.\n- Plain `@name` text without the link syntax does not create a mention.\n- The server rewrites each mention's display label to the member's canonical name.\n- Returns `RequestTooFrequently` while another resolve, reopen, merge, comment, or delete is running in the same account; retry after a short delay.",
           "href": "/en/api-reference/on-call/incidents/incident-comment",
           "metadata": {
             "sidebarTitle": "Add comment to incident"
@@ -10661,6 +11051,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -10696,7 +11089,7 @@
           "On-call/Alert enrichment"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Integrations Read** (`on-call`) or **Integrations Manage** (`on-call`) or **Mappings Read** (`on-call`) or **Mappings Manage** (`on-call`) |\n\n## Usage\n\n- The response is a CSV file with `Content-Disposition: attachment` header.\n- The CSV header row matches the schema's source and result labels in order.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **60 requests/minute**; **3 requests/second** per account |\n| Permissions | **Integrations Read** (`on-call`) or **Integrations Manage** (`on-call`) or **Mappings Read** (`on-call`) or **Mappings Manage** (`on-call`) |\n\n## Usage\n\n- The response is a CSV stream (`Content-Type: application/octet-stream`), not JSON. The file name in `Content-Disposition` is the schema name with spaces replaced by `_`.\n- The first row lists `source_labels` followed by `result_labels`; each following row is one data row, most recently written first.\n- The schema must exist and not be deleted; otherwise a JSON `InvalidParameter` error is returned.",
           "href": "/en/api-reference/on-call/alert-enrichment/mapping-data-read-download",
           "metadata": {
             "sidebarTitle": "Download mapping data as CSV"
@@ -10712,7 +11105,7 @@
                   "format": "binary",
                   "description": "CSV file stream (`Content-Type: application/octet-stream`, `Content-Disposition: attachment; filename=<schema_name>.csv`). The header row lists the schema's source_labels followed by result_labels in order; each subsequent row is one mapping document."
                 },
-                "example": "host,owner,team\nserver01,alice,sre\nserver02,bob,backend\n"
+                "example": "host,owner,team,service\nserver01,alice,sre,api\n"
               }
             }
           },
@@ -10722,6 +11115,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -10748,12 +11144,12 @@
       "post": {
         "operationId": "channelUnsubscribeRuleList",
         "summary": "List drop rules",
-        "description": "List drop rules for a channel.",
+        "description": "List a channel's drop rules, oldest first.",
         "tags": [
           "On-call/Channels"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- An unknown `channel_id` returns `InvalidParameter`.",
           "href": "/en/api-reference/on-call/channels/channel-unsubscribe-rule-list",
           "metadata": {
             "sidebarTitle": "List drop rules"
@@ -10817,6 +11213,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -10843,12 +11242,12 @@
       "post": {
         "operationId": "routeList",
         "summary": "List routing rules",
-        "description": "Return routing rules for the specified integrations. Integrations without a configured rule are omitted from the response.",
+        "description": "Return the routing rules of several shared integrations in one call.",
         "tags": [
           "On-call/Channels"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Integrations Read** (`on-call`) or **Integrations Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Integrations Read** (`on-call`) or **Integrations Manage** (`on-call`) |\n\n## Usage\n\n- Integrations without a routing rule are omitted from `items`.\n- Every ID must be an existing shared integration; a single unknown or channel-exclusive ID fails the whole call with `InvalidParameter`.",
           "href": "/en/api-reference/on-call/channels/route-list",
           "metadata": {
             "sidebarTitle": "List routing rules"
@@ -10922,6 +11321,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -10951,12 +11353,12 @@
       "post": {
         "operationId": "channelList",
         "summary": "List channels",
-        "description": "List channels accessible to the current user with optional filters.",
+        "description": "List the channels visible to the caller, with filters, sorting and pagination.",
         "tags": [
           "On-call/Channels"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Without filters, every channel in the account is returned except private channels the caller cannot access. Deleted channels are never returned.\n- Setting both `is_my_team` and `is_my_starred` to `true` returns `InvalidParameter`. `is_my_managed` takes precedence over both. With `is_my_managed` or `is_my_team`, `team_ids` is ignored.\n- With `is_brief: true`, items carry only `channel_id`, `channel_name`, `description`, `status` and `is_starred`, and all matches are returned in one page.\n- Always pass `p`. When it is omitted the first page is returned, but `has_next_page` is then `true` whenever anything matches.",
           "href": "/en/api-reference/on-call/channels/channel-list",
           "metadata": {
             "sidebarTitle": "List channels"
@@ -11005,6 +11407,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -11034,12 +11439,12 @@
       "post": {
         "operationId": "channelEscalateRuleCreate",
         "summary": "Create escalation rule",
-        "description": "Create an escalation rule defining who gets notified and when during an incident.",
+        "description": "Create an escalation rule that decides who is notified about a channel's incidents, and how.",
         "tags": [
           "On-call/Channels"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |\n\n## Usage\n\n- Rules are evaluated in ascending `priority`. The first enabled rule whose `time_filters` and `filters` match a new incident takes it; later rules are skipped. Omit `priority` to place the rule after all existing ones.\n- `template_id` must be an existing notification template, every member in `person_ids` must exist and every team in `team_ids` must have members; otherwise `InvalidParameter`.\n- The new rule is `enabled`.\n- An unknown `channel_id` returns `InvalidParameter`.\n- The caller must also be able to edit the channel: the account owner or an admin, the channel creator, or a member of its managing teams (of its owning team when `managing_team_ids` is empty). Otherwise the call returns `AccessDenied`.\n- Every call is recorded in the account audit log.",
           "href": "/en/api-reference/on-call/channels/channel-escalate-rule-create",
           "metadata": {
             "sidebarTitle": "Create escalation rule"
@@ -11069,7 +11474,7 @@
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "rule_id": "69db2f72a0fe7db6448b1506",
-                    "rule_name": "Test escalation rule"
+                    "rule_name": "On-call escalation"
                   }
                 }
               }
@@ -11081,6 +11486,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -11126,12 +11534,12 @@
       "post": {
         "operationId": "channelUpdate",
         "summary": "Update channel",
-        "description": "Update an existing channel's configuration and settings.",
+        "description": "Update a channel's settings; only the fields present in the request are changed.",
         "tags": [
           "On-call/Channels"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |\n\n## Usage\n\n- Omitted or `null` fields keep their current value. `group`, `flapping` and `event_group` each replace the whole stored object.\n- Pass `managing_team_ids: []` to remove all managing teams.\n- `auto_resolve_mode` is applied only together with `auto_resolve_timeout`; when `auto_resolve_timeout` is sent without `auto_resolve_mode`, the mode resets to `trigger`.\n- Setting `is_external_report_enabled` to `true` generates a new `external_report_token` on every call and the previous token stops working; `false` clears the token.\n- A `channel_name` used by another channel returns `InvalidParameter`; `group.method` `p` or `i` without the matching license returns `NoLicense`.\n- The caller must also be able to edit the channel: the account owner or an admin, the channel creator, or a member of its managing teams (of its owning team when `managing_team_ids` is empty). Otherwise the call returns `AccessDenied`.\n- Every call is recorded in the account audit log.",
           "href": "/en/api-reference/on-call/channels/channel-update",
           "metadata": {
             "sidebarTitle": "Update channel"
@@ -11172,6 +11580,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -11187,7 +11598,7 @@
                 "$ref": "#/components/schemas/UpdateChannelRequest"
               },
               "example": {
-                "channel_id": 1001,
+                "channel_id": 3521074710131,
                 "channel_name": "Production Alerts (v2)",
                 "description": "Updated description"
               }
@@ -11200,12 +11611,12 @@
       "post": {
         "operationId": "channelEnable",
         "summary": "Enable channel",
-        "description": "Enable a channel to resume incident routing. Only a `disabled` channel can be enabled.",
+        "description": "Enable a disabled channel so it processes incoming alert events again.",
         "tags": [
           "On-call/Channels"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |\n\n## Usage\n\n- Only a `disabled` channel can be enabled; any other status returns `InvalidParameter`.\n- An unknown `channel_id` returns `InvalidParameter`.\n- The caller must also be able to edit the channel: the account owner or an admin, the channel creator, or a member of its managing teams (of its owning team when `managing_team_ids` is empty). Otherwise the call returns `AccessDenied`.\n- Every call is recorded in the account audit log.",
           "href": "/en/api-reference/on-call/channels/channel-enable",
           "metadata": {
             "sidebarTitle": "Enable channel"
@@ -11244,6 +11655,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -11270,12 +11684,12 @@
       "post": {
         "operationId": "channelEscalateRuleDelete",
         "summary": "Delete escalation rule",
-        "description": "Delete an escalation rule. Only a `disabled` rule can be deleted.",
+        "description": "Delete a disabled escalation rule so it no longer appears in the channel's rule list.",
         "tags": [
           "On-call/Channels"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |\n\n## Usage\n\n- Only a `disabled` rule can be deleted; any other status returns `InvalidParameter`.\n- The rule is soft-deleted: it disappears from the list, but `POST /channel/escalate/rule/info` still returns it with `status` `deleted`.\n- An unknown `channel_id` or `rule_id` returns `InvalidParameter`.\n- The caller must also be able to edit the channel: the account owner or an admin, the channel creator, or a member of its managing teams (of its owning team when `managing_team_ids` is empty). Otherwise the call returns `AccessDenied`.\n- Every call is recorded in the account audit log.",
           "href": "/en/api-reference/on-call/channels/channel-escalate-rule-delete",
           "metadata": {
             "sidebarTitle": "Delete escalation rule"
@@ -11314,6 +11728,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -11341,12 +11758,12 @@
       "post": {
         "operationId": "mapping-api-write-delete",
         "summary": "Delete mapping API",
-        "description": "Delete a mapping API. Deletion is blocked if the API is referenced by any enrichment rule.",
+        "description": "Soft-delete a mapping API; refused while an enrichment rule uses it.",
         "tags": [
           "On-call/Alert enrichment"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Mappings Manage** (`on-call`) |\n\n## Usage\n\n- If the API is still referenced, the response returns HTTP 400 with a `refs` list.\n- Only the API creator, account admin, or team member can delete the API.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Mappings Manage** (`on-call`) |\n\n## Usage\n\n- The mapping API is soft-deleted (`status` becomes `deleted`) and enrichment rules stop calling it.\n- If an integration's enrichment rule uses it (`mapping_type` = `api`), the call returns HTTP 400 `ReferenceExist` with `data.refs` listing up to 20 integrations (`kind` = `integration`).\n- An unknown `api_id` returns `InvalidParameter`.\n- Only an account admin, the mapping API creator, or a member of the mapping API's owning team may call this; others get `AccessDenied`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/on-call/alert-enrichment/mapping-api-write-delete",
           "metadata": {
             "sidebarTitle": "Delete mapping API"
@@ -11385,6 +11802,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -11411,12 +11831,12 @@
       "post": {
         "operationId": "channelInhibitRuleList",
         "summary": "List inhibit rules",
-        "description": "List all inhibit rules configured for a channel.",
+        "description": "List a channel's inhibit rules, oldest first.",
         "tags": [
           "On-call/Channels"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Read** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Read** (`on-call`) or **Channels Manage** (`on-call`) |\n\n## Usage\n\n- An unknown `channel_id` returns `InvalidParameter`.",
           "href": "/en/api-reference/on-call/channels/channel-inhibit-rule-list",
           "metadata": {
             "sidebarTitle": "List inhibit rules"
@@ -11457,7 +11877,7 @@
                               "key": "severity",
                               "oper": "IN",
                               "vals": [
-                                "Info"
+                                "Critical"
                               ]
                             }
                           ]
@@ -11474,8 +11894,8 @@
                           ]
                         ],
                         "equals": [
-                          "data_source_id",
-                          "labels._account_id"
+                          "labels.cluster",
+                          "labels.service"
                         ],
                         "is_directly_discard": false,
                         "status": "enabled",
@@ -11496,6 +11916,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -11527,7 +11950,7 @@
           "On-call/Alert enrichment"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **20 requests/minute**; **2 requests/second** per account |\n| Permissions | **Mappings Manage** (`on-call`) |\n\n## Usage\n\n- The request must use `Content-Type: multipart/form-data`. The file field name is `file` and `schema_id` is a query parameter.\n- CSV header row must include all source and result label names.\n- Maximum file size: 100 MB.\n- By default the schema's existing data is truncated before import. Pass query param `do_not_truncate_first=TRUE` to append instead.\n- Duplicate source label value combinations in the CSV cause a 400 error.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **60 requests/minute**; **3 requests/second** per account |\n| Permissions | **Mappings Manage** (`on-call`) |\n\n## Usage\n\n- Send `multipart/form-data` with the CSV in the `file` field; `schema_id` and `do_not_truncate_first` are query parameters. The file may be at most 100 MB.\n- The first CSV row is the header and must contain every source and result label; other columns are dropped. Values longer than 2,048 bytes are rejected, and byte-order marks are stripped. A file with no data rows returns `InvalidParameter`.\n- By default all existing rows are deleted before the import. With `do_not_truncate_first=TRUE` existing rows are kept and rows with the same source label values are replaced.\n- Rows with the same source label values are merged; the later row wins.\n- The schema row limit (10,000 rows by default, higher for some accounts) is checked against the row count after the import; exceeding it returns `InvalidParameter`.\n- Rows are written in batches of 100. If a batch fails, the truncation and the batches before it stay applied.\n- The schema must exist and not be deleted; otherwise `InvalidParameter`.\n- Only an account admin, the schema creator, or a member of the schema's owning team may call this; others get `AccessDenied`.\n- Data writes to one schema (upsert, delete, truncate, CSV upload) run one at a time; a call made while another is running returns `RequestTooFrequently`.",
           "href": "/en/api-reference/on-call/alert-enrichment/mapping-data-write-upload",
           "metadata": {
             "sidebarTitle": "Upload mapping data via CSV"
@@ -11566,6 +11989,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -11629,7 +12055,7 @@
           "On-call/Alerts"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Read** (`on-call`) |\n\n## Usage\n\n- `alert_id` is an ObjectID hex string returned by `POST /alert/list` or `POST /alert-event/list`.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Read** (`on-call`) or **Channels Manage** (`on-call`) or **Incidents Read** (`on-call`) or **Incidents Manage** (`on-call`) |\n\n## Usage\n\n- `alert_id` is an ObjectID hex string returned by `POST /alert/list` or `POST /alert-event/list`.\n- An `alert_id` not found in the account returns `InvalidParameter`.",
           "href": "/en/api-reference/on-call/alerts/alert-read-info",
           "metadata": {
             "sidebarTitle": "Get alert detail"
@@ -11675,6 +12101,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -11701,12 +12130,12 @@
       "post": {
         "operationId": "incidentAssign",
         "summary": "Assign incident",
-        "description": "Dispatch an incident to a specific escalation level or responder.",
+        "description": "Reassign incidents to members or an escalation rule, replacing the current responders.",
         "tags": [
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Incidents Manage** or **Channels Manage** (`on-call`) |\n\n## Usage\n\n- Responders not in the new target are removed; responders who stay keep their acknowledgement. If none of the remaining responders has acknowledged, the incident returns to `Triggered`. Any snooze is cleared.\n- When `assigned_to` sets none of `person_ids`, `escalate_rule_id`, and `emails`, the server re-runs the channel's escalation rule matching instead.\n- Closed incidents are skipped without error.\n- The server fills `assigned_at`, `id`, and `escalate_rule_name`, and derives `type` when it is omitted.",
           "href": "/en/api-reference/on-call/incidents/incident-assign",
           "metadata": {
             "sidebarTitle": "Assign incident"
@@ -11745,6 +12174,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -11777,12 +12209,12 @@
       "post": {
         "operationId": "channelInhibitRuleDisable",
         "summary": "Disable inhibit rule",
-        "description": "Disable an inhibit rule without deleting it. Only an `enabled` rule can be disabled.",
+        "description": "Disable an inhibit rule without deleting it.",
         "tags": [
           "On-call/Channels"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |\n\n## Usage\n\n- Only an `enabled` rule can be disabled; any other status returns `InvalidParameter`.\n- An unknown `channel_id` or `rule_id` returns `InvalidParameter`.\n- The caller must also be able to edit the channel: the account owner or an admin, the channel creator, or a member of its managing teams (of its owning team when `managing_team_ids` is empty). Otherwise the call returns `AccessDenied`.\n- Every call is recorded in the account audit log.",
           "href": "/en/api-reference/on-call/channels/channel-inhibit-rule-disable",
           "metadata": {
             "sidebarTitle": "Disable inhibit rule"
@@ -11821,6 +12253,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -11848,12 +12283,12 @@
       "post": {
         "operationId": "calendarInfo",
         "summary": "Get calendar info",
-        "description": "Return details of a service calendar.",
+        "description": "Return the details of one service calendar of the account by its ID.",
         "tags": [
           "On-call/Calendars"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- An unknown `cal_id` returns `InvalidParameter`.",
           "href": "/en/api-reference/on-call/calendars/calendar-info",
           "metadata": {
             "sidebarTitle": "Get calendar info"
@@ -11914,6 +12349,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -11940,12 +12378,12 @@
       "post": {
         "operationId": "channelSilenceRuleCreate",
         "summary": "Create silence rule",
-        "description": "Create a silence rule to suppress notifications matching specified conditions.",
+        "description": "Create a silence rule that mutes or drops matching alert events during a time window.",
         "tags": [
           "On-call/Channels"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |\n\n## Usage\n\n- Set exactly one of `time_filter` (one-off window) or `time_filters` (recurring windows), and give `filters` at least one condition; otherwise `InvalidParameter`.\n- Each incoming event is checked against drop rules first, then silence rules, then inhibit rules. The first enabled silence rule whose window covers the current time and whose `filters` match is applied.\n- With `from_incident_id`, only one enabled silence rule may exist per incident; creating a second returns `InvalidParameter`.\n- An unknown `channel_id` returns `InvalidParameter`.\n- The caller must also be able to edit the channel: the account owner or an admin, the channel creator, or a member of its managing teams (of its owning team when `managing_team_ids` is empty). Otherwise the call returns `AccessDenied`.\n- Every call is recorded in the account audit log.",
           "href": "/en/api-reference/on-call/channels/channel-silence-rule-create",
           "metadata": {
             "sidebarTitle": "Create silence rule"
@@ -11975,7 +12413,7 @@
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "rule_id": "69db2f66a0fe7db6448b1503",
-                    "rule_name": "Test silence rule"
+                    "rule_name": "Maintenance window silence"
                   }
                 }
               }
@@ -11987,6 +12425,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -12031,12 +12472,12 @@
       "post": {
         "operationId": "channelSilenceRuleDelete",
         "summary": "Delete silence rule",
-        "description": "Delete a silence rule. Only a `disabled` rule can be deleted.",
+        "description": "Delete a disabled silence rule so it no longer appears in the channel's rule list.",
         "tags": [
           "On-call/Channels"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |\n\n## Usage\n\n- Only a `disabled` rule can be deleted; any other status returns `InvalidParameter`.\n- An unknown `channel_id` or `rule_id` returns `InvalidParameter`.\n- The caller must also be able to edit the channel: the account owner or an admin, the channel creator, or a member of its managing teams (of its owning team when `managing_team_ids` is empty). Otherwise the call returns `AccessDenied`.\n- Every call is recorded in the account audit log.",
           "href": "/en/api-reference/on-call/channels/channel-silence-rule-delete",
           "metadata": {
             "sidebarTitle": "Delete silence rule"
@@ -12075,6 +12516,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -12107,7 +12551,7 @@
           "On-call/Status pages"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Status Pages Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **30 requests/minute**; **2 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Requires the On-call Professional plan; other accounts get `AccessDenied`.\n- Runs asynchronously: the call checks the API key and source page, returns `job_id`, and the import continues in the background; poll `GET /status-page/migration/status`.\n- Only one migration job per account can run at a time; starting another returns `InvalidParameter`.\n- Creates a public status page with email subscription enabled; running it again for the same source page reuses the page created earlier.\n- Imports sections (from component groups), components, past incidents and maintenances, and incident templates; template failures are recorded in `progress.warnings` and do not fail the job.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/on-call/status-pages/status-page-migrate-structure",
           "metadata": {
             "sidebarTitle": "Migrate status page structure"
@@ -12148,6 +12592,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -12180,7 +12627,7 @@
           "On-call/Status pages"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Status Pages Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **30 requests/minute**; **2 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Requires the On-call Professional plan; other accounts get `AccessDenied`.\n- Runs asynchronously and returns `job_id`; poll `GET /status-page/migration/status`. Only one migration job per account can run at a time.\n- Run it after `POST /status-page/migrate-structure` for the same source page: component subscriptions are mapped to the components that migration created, and a subscriber whose components cannot be mapped is subscribed to all components.\n- Non-email, quarantined, and address-less subscribers are skipped and counted in `progress.subscribers_skipped`; recipients already subscribed on the target page are left unchanged.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/on-call/status-pages/status-page-migrate-email-subscribers",
           "metadata": {
             "sidebarTitle": "Migrate email subscribers"
@@ -12221,6 +12668,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -12249,12 +12699,12 @@
       "post": {
         "operationId": "template-write-create",
         "summary": "Create a template",
-        "description": "Create a new notification template.",
+        "description": "Create a notification template with per-channel message sources.",
         "tags": [
           "On-call/Notification templates"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Templates Manage** (`on-call`) |\n\n## Usage\n\n- `template_name` must be unique within the account; duplicates return `InvalidParameter`.\n- The server validates every non-empty channel template by rendering it against a mock incident — a syntactic error in any channel fails the whole request with `InvalidParameter`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Templates Manage** (`on-call`) |\n\n## Usage\n\n- Requires the Pro plan or higher; otherwise `NoLicense`.\n- `template_name` must be unique among the account's non-deleted templates and must not equal the built-in preset template's name in any supported language; otherwise `InvalidParameter`.\n- Every non-empty channel source is test-rendered against a mock incident; a template error in any channel fails the whole request with `InvalidParameter`. With `wecom_markdown_v2_enabled` = `true`, the rendered `wecom` content must be at most 4,096 bytes.\n- Channels left empty use the built-in preset content when notifications are sent.\n- A non-zero `team_id` must be an existing team; otherwise `InvalidParameter`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/on-call/notification-templates/template-write-create",
           "metadata": {
             "sidebarTitle": "Create a template"
@@ -12296,6 +12746,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -12314,8 +12767,8 @@
                 "team_id": 0,
                 "template_name": "Prod incident default",
                 "description": "Default template for production incidents.",
-                "email": "Incident {{ .IncidentName }} on {{ .Severity }}",
-                "sms": "[Flashduty] {{ .IncidentName }} — {{ .Severity }}"
+                "email": "Incident {{.Title}} is {{.IncidentSeverity}}",
+                "sms": "[Flashduty] {{.Title}} - {{.IncidentSeverity}}"
               }
             }
           }
@@ -12326,12 +12779,12 @@
       "post": {
         "operationId": "routeInfo",
         "summary": "Get routing rule detail",
-        "description": "Retrieve the routing rule configuration for a specific integration. Returns null when the integration has no routing rule configured.",
+        "description": "Return the routing rule of one shared integration.",
         "tags": [
           "On-call/Channels"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Integrations Read** (`on-call`) or **Integrations Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Integrations Read** (`on-call`) or **Integrations Manage** (`on-call`) |\n\n## Usage\n\n- When the integration has no routing rule, the response carries only `request_id`, with no `data` field.\n- A channel-exclusive or unknown `integration_id` returns `InvalidParameter`.",
           "href": "/en/api-reference/on-call/channels/route-info",
           "metadata": {
             "sidebarTitle": "Get routing rule detail"
@@ -12416,6 +12869,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -12447,7 +12903,7 @@
           "On-call/Alert enrichment"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Read** (`on-call`) or **Channels Manage** (`on-call`) or **Integrations Read** (`on-call`) or **Integrations Manage** (`on-call`) |\n\n## Usage\n\n- Returns `null` if no enrichment rules have been configured for the integration.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Read** (`on-call`) or **Channels Manage** (`on-call`) or **Integrations Read** (`on-call`) or **Integrations Manage** (`on-call`) |\n\n## Usage\n\n- `integration_id` must be an existing integration of the account; otherwise `InvalidParameter`.\n- Returns `data: null` when the integration has no rule set.",
           "href": "/en/api-reference/on-call/alert-enrichment/enrichment-read-info",
           "metadata": {
             "sidebarTitle": "Get enrichment rules"
@@ -12504,6 +12960,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -12530,12 +12989,12 @@
       "post": {
         "operationId": "channelInfo",
         "summary": "Get channel detail",
-        "description": "Retrieve detailed information for a specific channel.",
+        "description": "Return one channel's full configuration with counts of its active incidents from the last 30 days.",
         "tags": [
           "On-call/Channels"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Deleted channels are still returned, with `status` `deleted`.\n- A private channel (`is_private: true`) returns `AccessDenied` unless the caller is the account owner or an admin, its creator, or a member of its owning or managing teams.\n- `team_name`, `creator_name` and `is_starred` are not returned here; use `POST /channel/list` for them.\n- An unknown `channel_id` returns `InvalidParameter`.",
           "href": "/en/api-reference/on-call/channels/channel-info",
           "metadata": {
             "sidebarTitle": "Get channel detail"
@@ -12579,6 +13038,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -12610,7 +13072,7 @@
           "On-call/Notification templates"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Templates Read** (`on-call`) or **Templates Manage** (`on-call`) |\n\n## Usage\n\n- Pagination defaults to page 1 with 20 rows. The response's `has_next_page` tells you whether another page exists without needing a separate count request.\n- When `is_my_team` is `true`, `team_ids` is ignored.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Read** (`on-call`) or **Channels Manage** (`on-call`) or **Templates Read** (`on-call`) or **Templates Manage** (`on-call`) |\n\n## Usage\n\n- The first page always starts with the built-in preset template (`template_id` `6321aad26c12104586a88916`), whatever the filters; it is also counted in `total`.\n- Results are sorted by `orderby` (default `created_at`), newest first unless `asc` is `true`. Soft-deleted templates are excluded.\n- `is_my_team: true` limits results to templates of the caller's teams; with `team_ids` also sent, only the teams in both lists are kept. If that intersection is empty, no team filter is applied and templates of all teams are returned. If the caller belongs to no team, the response is empty (`total` = 0, no preset).\n- `query` is a case-insensitive regular expression on `template_name`; an invalid expression is matched as literal text.",
           "href": "/en/api-reference/on-call/notification-templates/template-read-list",
           "metadata": {
             "sidebarTitle": "List templates"
@@ -12648,8 +13110,8 @@
                         "template_id": "6605a1b2c3d4e5f6a7b8c9d0",
                         "template_name": "Prod incident default",
                         "description": "Default template for production incidents.",
-                        "email": "Incident {{ .IncidentName }} on {{ .Severity }}",
-                        "sms": "[Flashduty] {{ .IncidentName }} — {{ .Severity }}",
+                        "email": "Incident {{.Title}} is {{.IncidentSeverity}}",
+                        "sms": "[Flashduty] {{.Title}} - {{.IncidentSeverity}}",
                         "voice": "",
                         "dingtalk": "",
                         "wecom": "",
@@ -12662,6 +13124,14 @@
                         "telegram": "",
                         "slack": "",
                         "zoom": "",
+                        "wecom_markdown_v2_enabled": false,
+                        "feishu_app_card_v2_table_enabled": false,
+                        "feishu_app_card_v2_preserve_blank_lines": false,
+                        "feishu_app_war_room_enabled": false,
+                        "dingtalk_app_war_room_enabled": false,
+                        "slack_app_war_room_enabled": false,
+                        "incident_card_closed_action_apps": [],
+                        "incident_card_hidden_fields": {},
                         "status": "enabled",
                         "creator_id": 80011,
                         "updated_by": 80011,
@@ -12680,6 +13150,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -12710,12 +13183,12 @@
       "post": {
         "operationId": "insightByResponder",
         "summary": "Get responder insight",
-        "description": "Return insight metrics aggregated by responder.",
+        "description": "Return per-responder incident handling metrics, one row per responder per time bucket.",
         "tags": [
           "On-call/Analytics"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Analytics Read** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Analytics Read** (`on-call`) |\n\n## Usage\n\n- One row per responder per time bucket; `responder_ids` limits which responders are returned. `seconds_to_close_from`/`seconds_to_close_to` and `incident_ids` are ignored.\n- Incidents are counted by creation time. Rows are sorted by `ts` from newest to oldest, and a bucket (or dimension value) with no incidents produces no row — missing rows mean zero. `split_hours: true` returns up to three rows per bucket, one per `hours` value.\n- Members who are neither the account owner nor an admin only get data from channels they can access; other channels are silently excluded.\n- With `is_my_team: true`, `team_ids` is narrowed to the caller's teams; a caller who belongs to no team gets an empty result.",
           "href": "/en/api-reference/on-call/analytics/insight-by-responder",
           "metadata": {
             "sidebarTitle": "Get responder insight"
@@ -12774,6 +13247,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -12805,12 +13281,12 @@
       "get": {
         "operationId": "statusPageChangeList",
         "summary": "List status page events",
-        "description": "List status page events for console management. Unlike the public display endpoints, the response includes hidden components.",
+        "description": "List the incidents or maintenances of a status page by status and time window, including hidden components.",
         "tags": [
           "On-call/Status pages"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Returns every matching event in one response (no pagination), sorted by `start_at_seconds`, newest first.\n- Without `start_at_seconds` and `end_at_seconds`, the time window is unbounded.",
           "href": "/en/api-reference/on-call/status-pages/status-page-change-list",
           "metadata": {
             "sidebarTitle": "List status page events"
@@ -12901,6 +13377,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -12982,7 +13461,7 @@
           "On-call/Status pages"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Returns all non-terminal events of the given type in one response, newest first: `investigating`/`identified`/`monitoring` incidents, or `scheduled`/`ongoing` maintenances.",
           "href": "/en/api-reference/on-call/status-pages/status-page-change-active-list",
           "metadata": {
             "sidebarTitle": "List active status page events"
@@ -13059,6 +13538,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -13102,7 +13584,7 @@
           "On-call/Status pages"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- The `draft` payload is stored verbatim (up to 64 KB); the console publish form reads it back to prefill the event.\n- A draft lives for 30 days and is consumed exactly once when the event is published.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Status Pages Events Manage** (`on-call`) |\n\n## Usage\n\n- The `draft` payload is stored verbatim (up to 64 KB); the console publish form reads it back to prefill the event.\n- `draft.page_id` must be a page of the caller's account, every component in `draft.affected_components` must exist on it, and a `draft.change_id` greater than 0 must be an event of the same `type`.\n- Publish the draft by passing `draft_id` to `POST /status-page/change/create` (new event) or `POST /status-page/change/timeline/create` (update to `draft.change_id`); a draft can be published only once.\n- A draft is deleted 30 days after creation, whether or not it was published.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/on-call/status-pages/status-page-draft-create",
           "metadata": {
             "sidebarTitle": "Create status page draft"
@@ -13144,6 +13626,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -13183,12 +13668,12 @@
       "post": {
         "operationId": "mapping-api-write-create",
         "summary": "Create mapping API",
-        "description": "Create a new external HTTP API endpoint used to enrich alerts via HTTP lookup.",
+        "description": "Register an external HTTP API that enrichment rules call to look up alert labels.",
         "tags": [
           "On-call/Alert enrichment"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Mappings Manage** (`on-call`) |\n\n## Usage\n\n- `url` must start with `http://` or `https://` and cannot resolve to an internal IP (in SaaS mode).\n- `timeout` is the HTTP read timeout in seconds (1–3, default 2).\n- `retry_count` is the number of retries on failure (0–1, default 0).\n- Headers with security-sensitive names (e.g. `authorization`, `cookie`) are rejected in SaaS mode.\n- An account can have at most 50 mapping APIs.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Mappings Manage** (`on-call`) |\n\n## Usage\n\n- An enrichment rule with `mapping_type` = `api` sends `POST <url>` with the configured `headers` and the JSON body `{\"result_label_keys\": [...], \"event\": {...}}` (the alert event). The API must answer HTTP 200 with `{\"result_labels\": {\"<label>\": \"<value>\"}}`.\n- `url` must use `http` or `https`; in SaaS the host must not resolve to an internal IP address.\n- `timeout` is the total request timeout in seconds (1–3, default 2); `retry_count` is the number of retries after a failure (0–1, default 0).\n- In SaaS, sensitive header names are rejected: `Authorization`, `Proxy-Authorization`, `Cookie`, `X-Api-Key`, `X-Access-Token`, `X-Forwarded-For`, `X-Real-Ip`, `True-Client-Ip`, `X-Client-Ip`, `Host`, `X-Forwarded-Host`, `X-Forwarded-Proto`, `X-Internal-Id`, `X-User-Id`, `Transfer-Encoding`, `Upgrade`, `Connection` (case-insensitive).\n- `api_name` must be unique among non-deleted mapping APIs; an account holds at most 50 non-deleted mapping APIs. A non-zero `team_id` must be an existing team.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/on-call/alert-enrichment/mapping-api-write-create",
           "metadata": {
             "sidebarTitle": "Create mapping API"
@@ -13230,6 +13715,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -13264,12 +13752,12 @@
       "post": {
         "operationId": "scheduleUpdate",
         "summary": "Update schedule",
-        "description": "Update an existing on-call schedule. Provide schedule_id to identify the schedule.",
+        "description": "Update an on-call schedule identified by `schedule_id`; the layer list is replaced as a whole.",
         "tags": [
           "On-call/Schedules"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Schedules Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Schedules Manage** (`on-call`) |\n\n## Usage\n\n- `layers` is always replaced as a whole: send every layer you want to keep. Omitting `layers` (or sending an empty array) removes all layers.\n- Omitted `schedule_name`, `description`, `team_id`, `notify` and `status` keep their current values. A sent `notify` replaces the whole notification configuration.\n- On update, the legacy `name` and `disabled` fields are ignored; rename with `schedule_name` and enable/disable with `status` (`0` enabled, `1` disabled).\n- `time_zone` cannot be changed: omit it or send the current value; any other value is rejected. Wall-clock layer fields are converted in the stored time zone.\n- Every call is recorded in the account audit log.",
           "href": "/en/api-reference/on-call/schedules/schedule-update",
           "metadata": {
             "sidebarTitle": "Update schedule"
@@ -13308,6 +13796,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -13323,10 +13814,59 @@
                 "$ref": "#/components/schemas/ScheduleUpsertRequest"
               },
               "example": {
-                "schedule_id": 2001,
-                "schedule_name": "Production On-Call (Updated)",
-                "description": "Updated primary on-call rotation",
-                "team_id": 4291079133131
+                "schedule_id": 5789640530410,
+                "schedule_name": "Production On-Call",
+                "description": "Primary on-call rotation for the production team",
+                "team_id": 4291079133131,
+                "status": 0,
+                "layers": [
+                  {
+                    "layer_name": "Layer 1",
+                    "mode": 0,
+                    "groups": [
+                      {
+                        "group_name": "A",
+                        "members": [
+                          {
+                            "role_id": 0,
+                            "person_ids": [
+                              2451002751131
+                            ]
+                          }
+                        ]
+                      },
+                      {
+                        "group_name": "B",
+                        "members": [
+                          {
+                            "role_id": 0,
+                            "person_ids": [
+                              2476123212131
+                            ]
+                          }
+                        ]
+                      }
+                    ],
+                    "rotation_unit": "day",
+                    "rotation_value": 1,
+                    "starts_at": {
+                      "date": "2026-04-13",
+                      "time": "09:00"
+                    },
+                    "restrict_mode": 0,
+                    "day_mask": {
+                      "repeat": [
+                        1,
+                        2,
+                        3,
+                        4,
+                        5
+                      ]
+                    },
+                    "fair_rotation": false,
+                    "mask_continuous_enabled": false
+                  }
+                ]
               }
             }
           }
@@ -13337,12 +13877,12 @@
       "post": {
         "operationId": "template-write-delete",
         "summary": "Delete a template",
-        "description": "Soft-delete a template by ID.",
+        "description": "Soft-delete a notification template by ID.",
         "tags": [
           "On-call/Notification templates"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Templates Manage** (`on-call`) |\n\n## Usage\n\n- Fails with `400 ReferenceExist` if the template is still referenced by any channel, escalation rule, or notification subscription.\n- Deletion is soft — `deleted_at` is set. The record remains for audit, but the template stops appearing in listings.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Templates Manage** (`on-call`) |\n\n## Usage\n\n- If an escalation rule still uses the template, the call returns HTTP 400 `ReferenceExist` with `data.refs` (`kind` = `escalate_rule`, the rule `name`, a console `href`).\n- The template's `status` becomes `deleted`: it disappears from `/template/list` and its name can be reused, but `/template/info` still returns it.\n- An unknown or already-deleted `template_id` returns `InvalidParameter`.\n- Only an account admin, the template creator, or a member of the template's owning team may call this; others get `AccessDenied`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/on-call/notification-templates/template-write-delete",
           "metadata": {
             "sidebarTitle": "Delete a template"
@@ -13415,7 +13955,7 @@
           "On-call/Alert enrichment"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Mappings Manage** (`on-call`) |\n\n## Usage\n\n- Each doc must contain values for all labels defined in `source_labels` and `result_labels`.\n- Values for unknown labels are silently dropped.\n- Each value must be at most 2048 characters.\n- Upsert is keyed on the combination of source label values — existing rows with the same source key are updated.\n- A schema can hold at most 10,000 rows by default.\n- The operation is locked per schema; concurrent upserts to the same schema may fail with `ErrRequestTooFrequently`.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Mappings Manage** (`on-call`) |\n\n## Usage\n\n- A row is identified by its source label values. A row whose values match an existing row replaces it entirely, and its `created_at` and `updated_at` are reset.\n- Each row must contain every source and result label (otherwise `InvalidParameter`); other keys are dropped. Values longer than 2,048 bytes are rejected.\n- Rows with the same source label values in one request are merged; the later row wins.\n- A schema holds at most 10,000 rows by default (higher for some accounts). A request that would grow the schema beyond the limit returns `InvalidParameter`; replacing existing rows is still allowed.\n- Rows are written in batches of 100; if a batch fails, the batches before it stay written.\n- The schema must exist and not be deleted; otherwise `InvalidParameter`.\n- Only an account admin, the schema creator, or a member of the schema's owning team may call this; others get `AccessDenied`.\n- Data writes to one schema (upsert, delete, truncate, CSV upload) run one at a time; a call made while another is running returns `RequestTooFrequently`.",
           "href": "/en/api-reference/on-call/alert-enrichment/mapping-data-write-upsert",
           "metadata": {
             "sidebarTitle": "Upsert mapping data rows"
@@ -13459,6 +13999,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -13504,7 +14047,7 @@
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) or **Channels Manage** (`on-call`) |\n\n## Usage\n\n- The field must exist and be enabled on the account; `field_value` must match its type and options.\n- Omitting `field_value` or sending `null` clears the field on the incident.\n- If the value equals the current one, nothing changes.\n- A change adds a field-change entry to the incident timeline and triggers the same notifications and webhooks as a console edit.",
           "href": "/en/api-reference/on-call/incidents/incident-field-reset",
           "metadata": {
             "sidebarTitle": "Update incident custom field"
@@ -13543,6 +14086,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -13571,12 +14117,12 @@
       "post": {
         "operationId": "scheduleSelf",
         "summary": "List my schedules",
-        "description": "Return on-call schedules where the current user is assigned.",
+        "description": "List the enabled on-call schedules the calling member belongs to, with the member's own shifts in the window.",
         "tags": [
           "On-call/Schedules"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Schedules Read** (`on-call`) or **Schedules Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Schedules Read** (`on-call`) or **Schedules Manage** (`on-call`) |\n\n## Usage\n\n- Lists every enabled schedule in which the calling member appears in any layer, whether or not they are on call in the window. Disabled schedules are skipped.\n- `final_schedule` keeps only the caller's shifts: periods where the caller is off duty have `group` set to `null`. `layers` and `schedule_layers` describe the whole schedule.\n- `cur_oncall` and `next_oncall` are always `null` here; use `/schedule/by-person` for the caller's current and next shift.\n- `start` and `end` are 10-digit Unix timestamps in seconds; `end` must be after `start` and at most 45 days later.",
           "href": "/en/api-reference/on-call/schedules/schedule-self",
           "metadata": {
             "sidebarTitle": "List my schedules"
@@ -13611,6 +14157,7 @@
                         "name": "Open Source Q&A",
                         "account_id": 2451002751131,
                         "group_id": 2477033058131,
+                        "time_zone": "",
                         "disabled": 0,
                         "create_at": 1702623874,
                         "create_by": 2451002751131,
@@ -13717,6 +14264,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -13744,12 +14294,12 @@
       "post": {
         "operationId": "channelUnsubscribeRuleDisable",
         "summary": "Disable drop rule",
-        "description": "Disable a drop rule without deleting it. Only an `enabled` rule can be disabled.",
+        "description": "Disable a drop rule without deleting it.",
         "tags": [
           "On-call/Channels"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Only an `enabled` rule can be disabled; any other status returns `InvalidParameter`.\n- An unknown `channel_id` or `rule_id` returns `InvalidParameter`.\n- The caller must also be able to edit the channel: the account owner or an admin, the channel creator, or a member of its managing teams (of its owning team when `managing_team_ids` is empty). Otherwise the call returns `AccessDenied`.\n- Every call is recorded in the account audit log.",
           "href": "/en/api-reference/on-call/channels/channel-unsubscribe-rule-disable",
           "metadata": {
             "sidebarTitle": "Disable drop rule"
@@ -13788,6 +14338,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -13815,12 +14368,12 @@
       "post": {
         "operationId": "channelSilenceRuleList",
         "summary": "List silence rules",
-        "description": "List all silence rules configured for a channel.",
+        "description": "List a channel's silence rules and whether each one is in effect right now.",
         "tags": [
           "On-call/Channels"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Read** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Read** (`on-call`) or **Channels Manage** (`on-call`) or **Incidents Read** (`on-call`) or **Incidents Manage** (`on-call`) |\n\n## Usage\n\n- Listing also permanently removes one-off-window rules that are due for automatic cleanup (see `is_auto_delete`), so they no longer appear. Rules with recurring `time_filters` are never removed this way.\n- An unknown `channel_id` returns `InvalidParameter`.",
           "href": "/en/api-reference/on-call/channels/channel-silence-rule-list",
           "metadata": {
             "sidebarTitle": "List silence rules"
@@ -13892,6 +14445,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -13923,7 +14479,7 @@
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |\n\n## Usage\n\n- When an account create form applies, its visible custom fields and required system values must be supplied.\n- To attach images, send `multipart/form-data` with the JSON request in `data` and files in `images`; the complete request must not exceed 50 MiB.\n- Audited — changes are recorded in the audit log.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) or **Channels Manage** (`on-call`) |\n\n## Usage\n\n- Without an account create form, only `incident_severity` is required.\n- When the account has a create form, `title` (non-blank), `channel_id` and `assigned_to` become required, `fields` may contain only custom fields visible in the form, and the form's required fields must be filled.\n- Images can be attached only when the create form contains an image-upload element (at most 10 images): send `multipart/form-data` with the JSON request in `data` and files in `images`; the whole request must not exceed 50 MiB.\n- Assignment runs after the incident is created. Without `assigned_to`, the channel's escalation rules decide; a standalone incident with no `assigned_to` gets no responders. If assignment fails (for example an out-of-range `layer_idx`), the incident is still created, without responders.",
           "href": "/en/api-reference/on-call/incidents/incident-create",
           "metadata": {
             "sidebarTitle": "Create incident"
@@ -13965,6 +14521,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -14030,7 +14589,7 @@
           "On-call/Alert enrichment"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Read** (`on-call`) or **Incidents Manage** (`on-call`) |\n\n## Usage\n\n- An unknown `field_id` yields a 400 error. A soft-deleted field is still returned, with `status` = `deleted` and `deleted_at` set.\n- The shape of `options` and `default_value` varies by `field_type` — see the `FieldItem` schema.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Custom Fields Read** (`on-call`) or **Custom Fields Manage** (`on-call`) |\n\n## Usage\n\n- An unknown `field_id` returns `InvalidParameter`. A deleted field is returned with `status` = `deleted` until the background cleanup started by `/field/delete` finishes; after that its ID is unknown.\n- The shape of `options` and `default_value` depends on `field_type`; see the `FieldItem` schema.",
           "href": "/en/api-reference/on-call/alert-enrichment/field-read-info",
           "metadata": {
             "sidebarTitle": "Get field detail"
@@ -14089,6 +14648,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -14120,7 +14682,7 @@
           "On-call/Alert enrichment"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Read** (`on-call`) or **Incidents Manage** (`on-call`) |\n\n## Usage\n\n- All non-deleted fields are returned in a single response — there is no pagination and no `total` counter.\n- `query` matches against `field_name` only; invalid regular expressions are auto-escaped to a literal substring match.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Custom Fields Read** (`on-call`) or **Custom Fields Manage** (`on-call`) or **Channels Read** (`on-call`) or **Channels Manage** (`on-call`) or **Incidents Read** (`on-call`) or **Incidents Manage** (`on-call`) or **Integrations Read** (`on-call`) or **Integrations Manage** (`on-call`) or **Templates Read** (`on-call`) or **Templates Manage** (`on-call`) |\n\n## Usage\n\n- All non-deleted fields are returned in one response, without pagination or `total`. Sorted by `orderby` (default `created_at`), newest first unless `asc` is `true`.\n- `query` is a case-insensitive regular expression on `field_name`; an invalid expression is matched as literal text.",
           "href": "/en/api-reference/on-call/alert-enrichment/field-read-list",
           "metadata": {
             "sidebarTitle": "List fields"
@@ -14183,6 +14745,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -14216,7 +14781,7 @@
           "On-call/Alert enrichment"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |\n\n## Usage\n\n- Maximum **15** custom fields per account.\n- `field_name` must match `^[a-zA-Z_][a-zA-Z0-9_]{0,39}$` and is immutable after creation; `display_name` must also be unique within the account.\n- Type-specific rules: `checkbox` requires `value_type=bool` and no `options`; `single_select`/`multi_select` require `value_type=string` and a non-empty unique `options` list; `text` requires `value_type=string` and no `options`.\n- Response contains only `field_id` and `field_name`; use `/field/info` to fetch the full object.\n- Audited — changes are recorded in the audit log.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Custom Fields Manage** (`on-call`) |\n\n## Usage\n\n- Requires the Standard plan or higher; otherwise `NoLicense`.\n- An account holds at most 15 non-deleted custom fields by default (some accounts have a higher limit); exceeding it returns `InvalidParameter`.\n- `field_name` is 1–39 characters matching `^[a-zA-Z_][a-zA-Z0-9_]*$`, unique, and immutable. The name of a deleted field can be reused only with the same `field_type` and `value_type`. `display_name` must be unique among non-deleted fields.\n- Type rules: `checkbox` requires `value_type=bool` and no `options`; `single_select`/`multi_select` require `value_type=string` and a non-empty list of unique `options`; `text` requires `value_type=string` and no `options`.\n- The response contains only `field_id` and `field_name`; use `/field/info` for the full object.\n- Concurrent create calls in one account return `RequestTooFrequently`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/on-call/alert-enrichment/field-write-create",
           "metadata": {
             "sidebarTitle": "Create field"
@@ -14258,6 +14823,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -14300,7 +14868,7 @@
           "On-call/Alert enrichment"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |\n\n## Usage\n\n- Only `display_name`, `description`, `options`, and `default_value` can be changed; `field_name`, `field_type`, and `value_type` are immutable.\n- `options` and `default_value` must remain consistent with the field's existing type — same rules as create.\n- Audited — changes are recorded in the audit log.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Custom Fields Manage** (`on-call`) |\n\n## Usage\n\n- `display_name`, `description`, `options` and `default_value` are all overwritten with the request values on every call; a field left out is cleared. Always send the full desired values.\n- `field_name`, `field_type` and `value_type` cannot change; `options` and `default_value` must satisfy the type rules of create.\n- An unknown `field_id` returns `InvalidParameter`; `display_name` must stay unique among non-deleted fields.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/on-call/alert-enrichment/field-write-update",
           "metadata": {
             "sidebarTitle": "Update field"
@@ -14339,6 +14907,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -14379,7 +14950,7 @@
           "On-call/Alert enrichment"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |\n\n## Usage\n\n- The field is marked deleted synchronously; clearing its values from historical incidents runs in the background and may take time on large datasets.\n- Re-creating a field with the same `field_name` is only allowed if `field_type` and `value_type` match the deleted entry.\n- Deletion is rejected with `ReferenceExist` and the referencing custom forms in `data.refs` until no form uses the field.\n- Audited — changes are recorded in the audit log.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Custom Fields Manage** (`on-call`) |\n\n## Usage\n\n- If a custom form references the field, the call returns HTTP 400 `ReferenceExist` with the referencing forms in `data.refs`; remove the references first.\n- The field is marked deleted right away. A background job then removes its value from existing incidents and finally removes the field record.\n- Deleting an already-deleted field succeeds without change; an unknown `field_id` returns `InvalidParameter`.\n- The `field_name` can be reused later only with the same `field_type` and `value_type`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/on-call/alert-enrichment/field-write-delete",
           "metadata": {
             "sidebarTitle": "Delete field"
@@ -14452,6 +15023,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -14483,7 +15057,7 @@
           "On-call/Changes"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- `start_time` and `end_time` are both required: `start_time` must be less than `end_time`, and the window can span at most 31 days.\n- A change matches when its `[start_time, last_time]` range overlaps the query window.\n- Set `include_events` to `true` to attach each change's underlying events in `events`.",
           "href": "/en/api-reference/on-call/changes/change-read-list",
           "metadata": {
             "sidebarTitle": "List changes"
@@ -14548,6 +15122,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -14583,12 +15160,12 @@
       "post": {
         "operationId": "incident-read-get-war-room-default-observers",
         "summary": "Get war-room default observers",
-        "description": "Return historical responders suggested as default observers when opening a war room.",
+        "description": "Return people assigned to an incident earlier who are no longer responders, as suggested war-room observers.",
         "tags": [
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Requires the On-call Pro license.\n- Observers are people who were assigned to or added as responders on the incident at some point (per its timeline) and are not current responders.\n- An empty `observers` array means there is no such person.\n- Returns `ResourceNotFound` when the incident does not exist.",
           "href": "/en/api-reference/on-call/incidents/incident-read-get-war-room-default-observers",
           "metadata": {
             "sidebarTitle": "Get war-room default observers"
@@ -14619,16 +15196,15 @@
                   "data": {
                     "observers": [
                       {
-                        "account_id": 10001,
-                        "person_id": 20001,
+                        "account_id": 2451002751131,
+                        "person_id": 3790925372131,
                         "person_name": "Alice Chen",
-                        "avatar": "https://cdn.flashcat.cloud/avatar/20001.png",
-                        "email": "alice@acme.com",
-                        "phone": "+8613800000000",
+                        "avatar": "https://example.com/avatars/3790925372131.png",
+                        "email": "alice@example.com",
                         "locale": "zh-CN",
                         "time_zone": "Asia/Shanghai",
-                        "as": "responder",
-                        "status": "active"
+                        "as": "member",
+                        "status": "enabled"
                       }
                     ]
                   }
@@ -14642,6 +15218,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -14657,7 +15236,7 @@
                 "$ref": "#/components/schemas/GetWarRoomDefaultObserversRequest"
               },
               "example": {
-                "incident_id": "664a1b2c3d4e5f6a7b8c9d0e"
+                "incident_id": "69bb9233331067560c718ecd"
               }
             }
           }
@@ -14668,12 +15247,12 @@
       "post": {
         "operationId": "incident-write-add-war-room-member",
         "summary": "Add war-room member",
-        "description": "Add one or more members to the IM war room bound to an incident integration.",
+        "description": "Add members to an existing incident war room on Feishu (Lark), DingTalk, WeCom, or Slack.",
         "tags": [
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) or **Channels Manage** (`on-call`) |\n\n## Usage\n\n- Requires the On-call Pro license.\n- `chat_id` must identify a war room created through Flashduty on integration `integration_id`; otherwise the call returns `ResourceNotFound`.\n- Only Feishu (Lark), DingTalk, WeCom and Slack integrations support war rooms; other integrations return `InvalidParameter`.\n- Every ID in `member_ids` must be a person in the account; one unknown ID fails the whole request.\n- On success `data` is the string `ok`.",
           "href": "/en/api-reference/on-call/incidents/incident-write-add-war-room-member",
           "metadata": {
             "sidebarTitle": "Add war-room member"
@@ -14713,6 +15292,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -14728,11 +15310,11 @@
                 "$ref": "#/components/schemas/AddWarRoomMemberRequest"
               },
               "example": {
-                "integration_id": 362,
+                "integration_id": 2551105804131,
                 "chat_id": "oc_5ce6d572455d361153b7cb51da133945",
                 "member_ids": [
-                  20001,
-                  20002
+                  3790925372131,
+                  5068740052131
                 ]
               }
             }
@@ -14744,12 +15326,12 @@
       "post": {
         "operationId": "template-read-preview",
         "summary": "Preview template",
-        "description": "Render a notification template against incident data or mock data and return the output.",
+        "description": "Render a template source against an incident or mock data and return what the channel would send.",
         "tags": [
           "On-call/Notification templates"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **60 requests/minute**; **10 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- `incident_card_hidden_fields` applies only to supported IM-card previews; unsupported app types or field names return `InvalidParameter`.\n- `fixed_fields` is returned only when the selected IM preview has a non-empty fixed incident-card value.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **100 requests/minute**; **5 requests/second** per account |\n| Permissions | **Templates Read** (`on-call`) or **Templates Manage** (`on-call`) |\n\n## Usage\n\n- Renders against `incident_id` when given (it must exist in the account, otherwise `InvalidParameter`), or against a mock incident. Empty `content` previews the channel's built-in preset.\n- A template error is not an HTTP error: the response has `success: false` and `message` explains why.\n- `card` describes the message frame around the rendered template (email subject, IM app card elements and buttons) for `email`, `feishu_app`, `dingtalk_app`, `wecom_app`, `slack_app` and `teams_app`; it is omitted for other types. Buttons that need an integration (AI analysis, war room) are not shown.\n- `incident_card_hidden_fields` applies to IM app cards; unsupported app types or field names return `InvalidParameter`.\n- Nothing is sent or saved.",
           "href": "/en/api-reference/on-call/notification-templates/template-read-preview",
           "metadata": {
             "sidebarTitle": "Preview template"
@@ -14779,14 +15361,44 @@
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "success": true,
-                    "content": "Incident Database latency spike is Critical",
+                    "content": "**Database latency spike** is Critical",
                     "message": "",
-                    "fixed_fields": [
+                    "card": {
+                      "title": "Database latency spike",
+                      "elements": [
+                        {
+                          "type": "template"
+                        },
+                        {
+                          "type": "divider"
+                        },
+                        {
+                          "type": "actions",
+                          "actions": [
+                            {
+                              "text": "Acknowledge",
+                              "style": "primary"
+                            },
+                            {
+                              "text": "Resolve",
+                              "style": "danger"
+                            },
+                            {
+                              "text": "Snooze",
+                              "style": "select"
+                            }
+                          ]
+                        }
+                      ]
+                    },
+                    "blocks": [
                       {
-                        "field": "channel",
-                        "value": "Payment Alerts"
+                        "type": "markdown",
+                        "content": "**Database latency spike** is Critical"
                       }
-                    ]
+                    ],
+                    "size_bytes": 38,
+                    "size_limit_bytes": 30720
                   }
                 }
               }
@@ -14798,6 +15410,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -14813,7 +15428,7 @@
                 "$ref": "#/components/schemas/PreviewTemplateRequest"
               },
               "example": {
-                "content": "Incident {{.Title}} is {{.Status}}",
+                "content": "**{{.Title}}** is {{.IncidentSeverity}}",
                 "type": "feishu_app",
                 "incident_id": "664a1b2c3d4e5f6a7b8c9d0e",
                 "incident_card_hidden_fields": {
@@ -14836,7 +15451,7 @@
           "On-call/IM integrations"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Read** (`on-call`) or **Channels Manage** (`on-call`) or **Incidents Read** (`on-call`) or **Incidents Manage** (`on-call`) or **Integrations Read** (`on-call`) or **Integrations Manage** (`on-call`) |\n\n## Usage\n\n- Returns enabled and disabled Feishu, DingTalk, WeCom, Slack, and Microsoft Teams integrations whose settings have `war_room_enabled` set to `true`; deleted integrations are excluded.\n- Secret values inside `settings` are masked as `******`.",
           "href": "/en/api-reference/on-call/integrations/im-war-room-enabled-list",
           "metadata": {
             "sidebarTitle": "List war-room-enabled IM integrations"
@@ -14874,7 +15489,7 @@
                         "name": "Feishu Ops",
                         "status": "enabled",
                         "category": "im",
-                        "plugin_type": "feishu",
+                        "plugin_type": "feishu_app",
                         "plugin_type_name": "Feishu",
                         "description": "Feishu war-room integration",
                         "integration_key": "ik_8f3a2b1c9d0e",
@@ -14903,6 +15518,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -14932,7 +15550,7 @@
           "On-call/Status pages"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Returns public and internal pages in one response (no pagination), most recently created first.",
           "href": "/en/api-reference/on-call/status-pages/status-page-read-page-list",
           "metadata": {
             "sidebarTitle": "List status pages"
@@ -14963,38 +15581,37 @@
                   "data": {
                     "items": [
                       {
-                        "page_id": 7001,
-                        "name": "Acme Status",
-                        "url_name": "acme",
+                        "page_id": 5750613685214,
+                        "name": "Example Status",
+                        "url_name": "example-status",
                         "type": "public",
-                        "custom_domain": "status.acme.com",
-                        "logo_url": "https://acme.com",
-                        "page_header": "Acme System Status",
+                        "custom_domain": "status.example.com",
+                        "logo_url": "https://www.example.com",
+                        "page_header": "Example System Status",
                         "date_view": "calendar",
                         "display_uptime_mode": "chart_and_percentage",
                         "custom_links": [
                           {
-                            "name": "Home",
-                            "url": "https://acme.com"
+                            "key": "Home",
+                            "value": "https://www.example.com"
                           }
                         ],
-                        "contact_info": "mailto:support@acme.com",
+                        "contact_info": "mailto:support@example.com",
                         "components": [
                           {
-                            "component_id": "cmp_001",
-                            "section_id": "sec_001",
+                            "component_id": "01KC3GAZ6ZJE40H55GM31RPWZE",
+                            "section_id": "01KC3FKKX5TSVG6Z3X1QNGF6V2",
                             "name": "API",
                             "description": "Core API service",
                             "available_since_seconds": 1716962400,
-                            "order_id": 1,
-                            "hide_uptime": false,
-                            "hide_all": false
+                            "order_id": 1
                           }
                         ],
                         "sections": [
                           {
-                            "section_id": "sec_001",
+                            "section_id": "01KC3FKKX5TSVG6Z3X1QNGF6V2",
                             "name": "Core Services",
+                            "description": "",
                             "order_id": 1,
                             "hide_uptime": false,
                             "hide_all": false
@@ -15003,7 +15620,8 @@
                         "subscription": {
                           "email": true,
                           "im": false
-                        }
+                        },
+                        "template_preference": "message"
                       }
                     ]
                   }
@@ -15017,6 +15635,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -15035,7 +15656,7 @@
           "On-call/Integrations"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Integrations Manage** (`on-call`) |\n\n## Usage\n\n- The server uses member email and phone values to find matching users in DingTalk, Feishu, or WeCom.\n- When no member can be linked, the response either carries an empty `new_linked_person_ids` array or omits the `data` field entirely.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Integrations Manage** (`on-call`) |\n\n## Usage\n\n- Looks up every account member not yet linked to this integration's IM app by email and phone; only Feishu, DingTalk and WeCom integrations are supported, other types return `InvalidParameter`.\n- A disabled integration returns `InvalidParameter`.\n- Returns `RequestLocked` while another linking run for the same integration is in progress, and `InvalidParameter` when the IM platform refuses the lookup (missing contact permissions or rejected credentials).\n- `new_linked_person_ids` is an empty array when nobody could be newly linked.",
           "href": "/en/api-reference/on-call/integrations/datasource-im-person-try-link",
           "metadata": {
             "sidebarTitle": "Attempt IM person linking"
@@ -15066,7 +15687,9 @@
                   "data": {
                     "new_linked_person_ids": [
                       5348648172131
-                    ]
+                    ],
+                    "unmatched_count": 2,
+                    "no_contact_count": 1
                   }
                 }
               }
@@ -15078,6 +15701,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -15109,7 +15735,7 @@
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |\n\n## Usage\n\n- Links at most 10 incidents to one post-mortem report.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Requires the On-call Pro license.\n- The report ID is derived from the account and the sorted `incident_ids`; calling again with the same incidents returns the existing report unchanged.\n- Fails with `InvalidParameter` when any incident is already linked to a different post-mortem.\n- Team, channel and privacy are copied from the channel of the first incident loaded; an incident without a channel cannot start a report.\n- The title is the incident titles joined by `, ` (at most 512 characters), or the template name when all titles are empty.\n- A new report starts as `drafting` with an empty body; its basics (severity, times, responders) are computed from the incidents.\n- Converted follow-ups of these incidents that are not yet bound to a report are bound to it.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/on-call/incidents/postmortem-write-init",
           "metadata": {
             "sidebarTitle": "Initialize post-mortem"
@@ -15140,41 +15766,44 @@
                   "data": {
                     "meta": {
                       "account_id": 2451002751131,
-                      "title": "Postmortem1",
-                      "status": "published",
-                      "post_mortem_id": "8104935102bf89dc01ac638a5261fe7e",
+                      "title": "Database connection timeout on prod-db-01",
+                      "status": "drafting",
+                      "post_mortem_id": "d3c9a7f2e5b14c8a9f0e6b2d4a1c7e35",
                       "template_id": "post_mortem_default_tmpl_en-us",
                       "incident_ids": [
                         "69bb9233331067560c718ecd"
                       ],
                       "media_count": 0,
                       "author_ids": [
-                        2477273692131
+                        3790925372131
                       ],
                       "team_id": 2477033058131,
-                      "channel_id": 3047621227131,
+                      "channel_id": 2551105804131,
                       "is_private": false,
+                      "generation": 0,
+                      "revision": 0,
                       "channel_name": "Ops Channel",
                       "created_at_seconds": 1773900354,
-                      "updated_at_seconds": 1773909012
+                      "updated_at_seconds": 1773900354
                     },
                     "basics": {
-                      "incidents_highest_severity": "Warning",
-                      "incidents_earliest_start_seconds": 1761133512,
-                      "incidents_latest_close_seconds": 1761133632,
-                      "incidents_total_duration_seconds": 120,
+                      "incidents_highest_severity": "Critical",
+                      "incidents_earliest_start_seconds": 1773890000,
+                      "incidents_latest_close_seconds": 1773897200,
+                      "incidents_total_duration_seconds": 7200,
                       "responders": [
                         {
                           "person_id": 3790925372131,
-                          "assigned_at": 1761133515,
-                          "acknowledged_at": 0
+                          "assigned_at": 1773890012,
+                          "acknowledged_at": 1773890100
                         }
                       ]
                     },
                     "content": {
-                      "content": "{\"type\":\"doc\",\"content\":[]}"
+                      "content": ""
                     },
-                    "follow_ups": ""
+                    "follow_ups": "",
+                    "has_active_incident": false
                   }
                 }
               }
@@ -15186,6 +15815,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -15215,12 +15847,12 @@
       "post": {
         "operationId": "postmortem-write-reset-basics",
         "summary": "Update post-mortem basics",
-        "description": "Replace the incident facts stored in a post-mortem report.",
+        "description": "Overwrite the incident facts (severity, times, responders) stored on a post-mortem report.",
         "tags": [
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |\n\n## Usage\n\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Requires the On-call Pro license.\n- The caller must be an account owner or admin, or a member of the report's team; otherwise the call returns `AccessDenied`.\n- Full overwrite: omitted `incidents_latest_close_seconds` and `incidents_total_duration_seconds` become 0, and omitted `responder_ids` clears the responders.\n- IDs in `responder_ids` that do not resolve to a person are dropped; each stored responder gets the current time as `assigned_at` and `acknowledged_at` = 0.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/on-call/incidents/postmortem-write-reset-basics",
           "metadata": {
             "sidebarTitle": "Update post-mortem basics"
@@ -15247,8 +15879,7 @@
                   ]
                 },
                 "example": {
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
-                  "data": {}
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
             }
@@ -15259,6 +15890,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -15274,11 +15908,11 @@
                 "$ref": "#/components/schemas/ResetPostMortemBasicsRequest"
               },
               "example": {
-                "post_mortem_id": "8104935102bf89dc01ac638a5261fe7e",
-                "incidents_highest_severity": "Warning",
-                "incidents_earliest_start_seconds": 1761133512,
-                "incidents_latest_close_seconds": 1761133632,
-                "incidents_total_duration_seconds": 120,
+                "post_mortem_id": "d3c9a7f2e5b14c8a9f0e6b2d4a1c7e35",
+                "incidents_highest_severity": "Critical",
+                "incidents_earliest_start_seconds": 1773890000,
+                "incidents_latest_close_seconds": 1773897200,
+                "incidents_total_duration_seconds": 7200,
                 "responder_ids": [
                   3790925372131
                 ]
@@ -15297,7 +15931,7 @@
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | Edit access to the target report is required. |\n\n## Usage\n\n- The report must be drafting and its current revision must equal `expected_revision`; otherwise the API returns `409 Conflict`.\n- Reuse an `idempotency_key` only for the same report, revision, and Markdown content; different reuse returns `409 Conflict`.\n- A successful reset disconnects the previous collaboration (Yjs) room. Reconnect to the new generation room `post-mortem-{accountId}-{postMortemId}-g{N}` (generation 0 has no `-g` suffix). The reset cannot be rolled back.\n- Markdown content is limited to 4 MiB.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Requires the On-call Pro license.\n- The caller must be an account owner or admin, or a member of the report's team; otherwise the call returns `AccessDenied`.\n- The report must be drafting and its current revision must equal `expected_revision`; otherwise the API returns `409 Conflict`.\n- Reuse an `idempotency_key` only for the same report, revision, and Markdown content; different reuse returns `409 Conflict`.\n- While another reset of the same report is still running, the call returns `RequestTooFrequently`; retry later.\n- A successful reset disconnects the previous collaboration (Yjs) room. Reconnect to the new generation room `post-mortem-{accountId}-{postMortemId}-g{N}` (generation 0 has no `-g` suffix). The reset cannot be rolled back.\n- Markdown content is limited to 4 MiB.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/on-call/incidents/incident-post-mortem-write-reset-content",
           "metadata": {
             "sidebarTitle": "Reset post-mortem content"
@@ -15326,7 +15960,7 @@
                 "example": {
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
-                    "post_mortem_id": "8104935102bf89dc01ac638a5261fe7e",
+                    "post_mortem_id": "d3c9a7f2e5b14c8a9f0e6b2d4a1c7e35",
                     "generation": 2,
                     "revision": 12,
                     "previous_generation": 1,
@@ -15423,10 +16057,10 @@
                 "$ref": "#/components/schemas/ResetPostMortemContentRequest"
               },
               "example": {
-                "post_mortem_id": "8104935102bf89dc01ac638a5261fe7e",
+                "post_mortem_id": "d3c9a7f2e5b14c8a9f0e6b2d4a1c7e35",
                 "markdown": "# Database saturation incident\n\nThe database pool was exhausted; added saturation alert.",
                 "expected_revision": 11,
-                "idempotency_key": "postmortem-reset-8104935102-11"
+                "idempotency_key": "postmortem-reset-d3c9a7f2-11"
               }
             }
           }
@@ -15442,7 +16076,7 @@
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |\n\n## Usage\n\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Requires the On-call Pro license.\n- The caller must be an account owner or admin, or a member of the report's team; otherwise the call returns `AccessDenied`.\n- Status can move both ways. Only a `drafting` report accepts `POST /incident/post-mortem/content/reset`.\n- Publishing deletes uploaded media files that the report body no longer references.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/on-call/incidents/postmortem-write-reset-status",
           "metadata": {
             "sidebarTitle": "Update post-mortem status"
@@ -15469,8 +16103,7 @@
                   ]
                 },
                 "example": {
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
-                  "data": {}
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
             }
@@ -15481,6 +16114,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -15496,7 +16132,7 @@
                 "$ref": "#/components/schemas/ResetPostMortemStatusRequest"
               },
               "example": {
-                "post_mortem_id": "8104935102bf89dc01ac638a5261fe7e",
+                "post_mortem_id": "d3c9a7f2e5b14c8a9f0e6b2d4a1c7e35",
                 "status": "published"
               }
             }
@@ -15513,7 +16149,7 @@
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |\n\n## Usage\n\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Requires the On-call Pro license.\n- The caller must be an account owner or admin, or a member of the report's team; otherwise the call returns `AccessDenied`.\n- The caller is added to the report's `author_ids`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/on-call/incidents/postmortem-write-reset-title",
           "metadata": {
             "sidebarTitle": "Update post-mortem title"
@@ -15540,8 +16176,7 @@
                   ]
                 },
                 "example": {
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
-                  "data": {}
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
             }
@@ -15552,6 +16187,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -15567,7 +16205,7 @@
                 "$ref": "#/components/schemas/ResetPostMortemTitleRequest"
               },
               "example": {
-                "post_mortem_id": "8104935102bf89dc01ac638a5261fe7e",
+                "post_mortem_id": "d3c9a7f2e5b14c8a9f0e6b2d4a1c7e35",
                 "title": "Production API latency incident"
               }
             }
@@ -15579,12 +16217,12 @@
       "post": {
         "operationId": "postmortem-write-reset-follow-ups",
         "summary": "Update post-mortem follow-ups",
-        "description": "Replace the follow-up action items on a post-mortem report.",
+        "description": "Replace the free-text follow-ups string stored on a post-mortem report.",
         "tags": [
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |\n\n## Usage\n\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Requires the On-call Pro license.\n- The caller must be an account owner or admin, or a member of the report's team; otherwise the call returns `AccessDenied`.\n- Works in any report status. Omitting `follow_ups` or sending `\"\"` clears the string.\n- When `follow_ups` is a JSON array in the console's follow-up format, its entries are also synced into structured follow-up work items (`source_kind` = `legacy_follow_up`); other text leaves the structured items unchanged.\n- To manage individual follow-ups, prefer the `/incident/work-item/*` endpoints.\n- The caller is added to the report's `author_ids`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/on-call/incidents/postmortem-write-reset-follow-ups",
           "metadata": {
             "sidebarTitle": "Update post-mortem follow-ups"
@@ -15611,8 +16249,7 @@
                   ]
                 },
                 "example": {
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
-                  "data": {}
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
             }
@@ -15623,6 +16260,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -15638,7 +16278,7 @@
                 "$ref": "#/components/schemas/ResetPostMortemFollowUpsRequest"
               },
               "example": {
-                "post_mortem_id": "8104935102bf89dc01ac638a5261fe7e",
+                "post_mortem_id": "d3c9a7f2e5b14c8a9f0e6b2d4a1c7e35",
                 "follow_ups": "- Add database saturation alert\n- Review cache TTL rollout"
               }
             }
@@ -15650,12 +16290,12 @@
       "post": {
         "operationId": "postmortem-write-upsert-template",
         "summary": "Create or update post-mortem template",
-        "description": "Create a custom post-mortem template or update an existing one.",
+        "description": "Create a custom post-mortem template, or replace an existing one identified by `template_id`.",
         "tags": [
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |\n\n## Usage\n\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Requires the On-call Pro license.\n- Omit `template_id` to create: `team_id` must name an existing team, and the server generates the template ID.\n- With `template_id`, the existing custom template is replaced; an unknown ID returns `ResourceNotFound`. Updating requires being an account owner or admin, or a member of the template's team.\n- All text fields are replaced: an omitted `description` or `content_markdown` becomes empty. On update, `team_id` moves the template to that team; omit it or send 0 to keep the current team.\n- Built-in templates (`post_mortem_default_tmpl_*`) cannot be modified.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/on-call/incidents/postmortem-write-upsert-template",
           "metadata": {
             "sidebarTitle": "Create or update post-mortem template"
@@ -15685,10 +16325,10 @@
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "account_id": 2451002751131,
-                    "template_id": "post_mortem_default_tmpl_en-us",
-                    "name": "Default post-mortem report",
-                    "description": "Default sections for post-mortem reports.",
-                    "content": "[{\"type\":\"heading\",\"content\":\"Summary\"}]",
+                    "template_id": "kQ3vXn8pR2mT7wYbZc4dEf",
+                    "name": "Production incident template",
+                    "description": "Template for production incident reviews.",
+                    "content": "[{\"type\":\"heading\",\"props\":{\"level\":2},\"content\":\"Summary\"}]",
                     "content_markdown": "## Summary\nDescribe what happened.",
                     "team_id": 2477033058131,
                     "created_at_seconds": 1773900000,
@@ -15704,6 +16344,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -15722,7 +16365,7 @@
                 "team_id": 2477033058131,
                 "name": "Production incident template",
                 "description": "Template for production incident reviews.",
-                "content": "[{\"type\":\"heading\",\"content\":\"Summary\"}]",
+                "content": "[{\"type\":\"heading\",\"props\":{\"level\":2},\"content\":\"Summary\"}]",
                 "content_markdown": "## Summary\nDescribe what happened."
               }
             }
@@ -15739,7 +16382,7 @@
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |\n\n## Usage\n\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Requires the On-call Pro license.\n- Built-in templates (`post_mortem_default_tmpl_*`) cannot be deleted; an unknown ID returns `ResourceNotFound`.\n- Requires being an account owner or admin, or a member of the template's team.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/on-call/incidents/postmortem-write-delete-template",
           "metadata": {
             "sidebarTitle": "Delete post-mortem template"
@@ -15766,8 +16409,7 @@
                   ]
                 },
                 "example": {
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
-                  "data": {}
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
             }
@@ -15778,6 +16420,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -15793,7 +16438,7 @@
                 "$ref": "#/components/schemas/DeletePostMortemTemplateRequest"
               },
               "example": {
-                "template_id": "post_mortem_custom_tmpl_01"
+                "template_id": "kQ3vXn8pR2mT7wYbZc4dEf"
               }
             }
           }
@@ -15804,12 +16449,12 @@
       "post": {
         "operationId": "postmortem-read-list-templates",
         "summary": "List post-mortem templates",
-        "description": "Return built-in and custom post-mortem templates for the account.",
+        "description": "Return the built-in post-mortem template followed by the account's custom templates.",
         "tags": [
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Read** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Requires the On-call Pro license.\n- The built-in template always comes first and matches the request language: Chinese returns `post_mortem_default_tmpl_zh-cn`, anything else `post_mortem_default_tmpl_en-us`. `total` includes it.\n- Custom templates are sorted by `created_at_seconds`, newest first unless `asc` is true.\n- Paginate with `p` and `limit`; `p` × `limit` must not exceed 10,000.\n- Built-in templates have `account_id`, `team_id` and both timestamps set to 0.",
           "href": "/en/api-reference/on-call/incidents/postmortem-read-list-templates",
           "metadata": {
             "sidebarTitle": "List post-mortem templates"
@@ -15842,11 +16487,22 @@
                     "has_next_page": false,
                     "items": [
                       {
-                        "account_id": 2451002751131,
+                        "account_id": 0,
                         "template_id": "post_mortem_default_tmpl_en-us",
-                        "name": "Default post-mortem report",
-                        "description": "Default sections for post-mortem reports.",
-                        "content": "[{\"type\":\"heading\",\"content\":\"Summary\"}]",
+                        "name": "Default Post Mortem Report Template",
+                        "description": "Standard post-mortem template with common sections",
+                        "content": "[{\"type\":\"heading\",\"props\":{\"level\":2},\"content\":\"Summary\"}]",
+                        "content_markdown": "## Summary\n> Provide a high-level description of the incident.",
+                        "team_id": 0,
+                        "created_at_seconds": 0,
+                        "updated_at_seconds": 0
+                      },
+                      {
+                        "account_id": 2451002751131,
+                        "template_id": "kQ3vXn8pR2mT7wYbZc4dEf",
+                        "name": "Production incident template",
+                        "description": "Template for production incident reviews.",
+                        "content": "[{\"type\":\"heading\",\"props\":{\"level\":2},\"content\":\"Summary\"}]",
                         "content_markdown": "## Summary\nDescribe what happened.",
                         "team_id": 2477033058131,
                         "created_at_seconds": 1773900000,
@@ -15864,6 +16520,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -15898,7 +16557,7 @@
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Read** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Requires the On-call Pro license.\n- Accepts the built-in IDs `post_mortem_default_tmpl_zh-cn` and `post_mortem_default_tmpl_en-us` regardless of request language; an unknown ID returns `ResourceNotFound`.",
           "href": "/en/api-reference/on-call/incidents/postmortem-read-template-info",
           "metadata": {
             "sidebarTitle": "Get post-mortem template detail"
@@ -15927,15 +16586,15 @@
                 "example": {
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
-                    "account_id": 2451002751131,
+                    "account_id": 0,
                     "template_id": "post_mortem_default_tmpl_en-us",
-                    "name": "Default post-mortem report",
-                    "description": "Default sections for post-mortem reports.",
-                    "content": "[{\"type\":\"heading\",\"content\":\"Summary\"}]",
-                    "content_markdown": "## Summary\nDescribe what happened.",
-                    "team_id": 2477033058131,
-                    "created_at_seconds": 1773900000,
-                    "updated_at_seconds": 1773903600
+                    "name": "Default Post Mortem Report Template",
+                    "description": "Standard post-mortem template with common sections",
+                    "content": "[{\"type\":\"heading\",\"props\":{\"level\":2},\"content\":\"Summary\"}]",
+                    "content_markdown": "## Summary\n> Provide a high-level description of the incident.",
+                    "team_id": 0,
+                    "created_at_seconds": 0,
+                    "updated_at_seconds": 0
                   }
                 }
               }
@@ -15947,6 +16606,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -15962,7 +16624,7 @@
             "schema": {
               "type": "string"
             },
-            "description": "Template ID."
+            "description": "Template ID: a built-in ID such as `post_mortem_default_tmpl_en-us`, or a custom template ID from `POST /incident/post-mortem/template/list`."
           }
         ]
       }
@@ -16059,6 +16721,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -16084,12 +16749,12 @@
       "post": {
         "operationId": "statusPageCreate",
         "summary": "Create status page",
-        "description": "Create a new status page.",
+        "description": "Create a public or internal status page for the account.",
         "tags": [
           "On-call/Status pages"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Status Pages Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Status Pages Manage** (`on-call`) |\n\n## Usage\n\n- Page quota by On-call plan: public pages, 1 on Free and Standard and 5 on Professional; internal pages, Professional only, up to 20. Exceeding the quota returns `InvalidParameter`.\n- `url_name` is normalized to a lowercase slug and must be unique among the account's pages of the same type; `page_url_name` in the response is the final value.\n- Public pages support only email subscription and are the only type that can use `custom_domain`; internal pages support only IM subscription.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/on-call/status-pages/status-page-create",
           "metadata": {
             "sidebarTitle": "Create status page"
@@ -16132,6 +16797,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -16150,8 +16818,14 @@
                 "name": "My Status Page",
                 "url_name": "my-status-page",
                 "type": "public",
+                "date_view": "list",
+                "display_uptime_mode": "chart_and_percentage",
                 "page_header": "Welcome to our status page",
-                "contact_info": "mailto:support@example.com"
+                "contact_info": "mailto:support@example.com",
+                "subscription": {
+                  "email": true,
+                  "im": false
+                }
               }
             }
           }
@@ -16162,12 +16836,12 @@
       "post": {
         "operationId": "statusPageUpdate",
         "summary": "Update status page",
-        "description": "Update an existing status page configuration.",
+        "description": "Update the configuration of an existing status page; omitted fields keep their values.",
         "tags": [
           "On-call/Status pages"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Status Pages Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Status Pages Manage** (`on-call`) |\n\n## Usage\n\n- A field that is omitted or `null` keeps its value; an empty string clears a string field.\n- `custom_links` cannot be cleared: an omitted or empty array keeps the current links.\n- A new `url_name` is normalized to a slug and must be unique among the account's pages of the same type; `custom_domain` is rejected for internal pages.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/on-call/status-pages/status-page-update",
           "metadata": {
             "sidebarTitle": "Update status page"
@@ -16206,6 +16880,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -16235,12 +16912,12 @@
       "post": {
         "operationId": "statusPageDelete",
         "summary": "Delete status page",
-        "description": "Delete a status page.",
+        "description": "Delete a status page together with its events and subscriptions.",
         "tags": [
           "On-call/Status pages"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Status Pages Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Status Pages Manage** (`on-call`) |\n\n## Usage\n\n- Deleting a page that does not exist returns success.\n- The page's events and subscriptions are deleted in the background after the call returns.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/on-call/status-pages/status-page-delete",
           "metadata": {
             "sidebarTitle": "Delete status page"
@@ -16279,6 +16956,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -16305,12 +16985,12 @@
       "post": {
         "operationId": "statusPageComponentUpsert",
         "summary": "Upsert status page component",
-        "description": "Create or update a service component on a status page.",
+        "description": "Create or update one or more service components on a status page.",
         "tags": [
           "On-call/Status pages"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Status Pages Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Status Pages Manage** (`on-call`) |\n\n## Usage\n\n- An item without `component_id` creates a component; an item with `component_id` updates that component.\n- An update overwrites `name`, `description`, `section_id`, `order_id`, `hide_uptime`, and `hide_all` with the values sent, so omitted fields are reset (omitting `section_id` moves the component to the top level); `available_since_seconds` is ignored on update.\n- Component names must be unique within the page and `section_id` must be an existing section; any invalid item rejects the whole request.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/on-call/status-pages/status-page-component-upsert",
           "metadata": {
             "sidebarTitle": "Upsert status page component"
@@ -16353,6 +17033,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -16387,12 +17070,12 @@
       "post": {
         "operationId": "statusPageComponentDelete",
         "summary": "Delete status page component",
-        "description": "Delete a service component from a status page.",
+        "description": "Delete one or more service components from a status page.",
         "tags": [
           "On-call/Status pages"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Status Pages Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Status Pages Manage** (`on-call`) |\n\n## Usage\n\n- If any ID in `component_ids` does not exist on the page, nothing is deleted and the call still returns success.\n- Subscriptions to the deleted components are removed.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/on-call/status-pages/status-page-component-delete",
           "metadata": {
             "sidebarTitle": "Delete status page component"
@@ -16431,6 +17114,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -16460,12 +17146,12 @@
       "post": {
         "operationId": "statusPageSectionUpsert",
         "summary": "Upsert status page section",
-        "description": "Create or update a section on a status page.",
+        "description": "Create or update one or more sections that group components on a status page.",
         "tags": [
           "On-call/Status pages"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Status Pages Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Status Pages Manage** (`on-call`) |\n\n## Usage\n\n- An item without `section_id` creates a section; an item with `section_id` updates that section.\n- An update overwrites `name`, `description`, `order_id`, `hide_uptime`, and `hide_all` with the values sent, so omitted fields are reset.\n- Section names must be unique within the page; any invalid item rejects the whole request.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/on-call/status-pages/status-page-section-upsert",
           "metadata": {
             "sidebarTitle": "Upsert status page section"
@@ -16508,6 +17194,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -16541,12 +17230,12 @@
       "post": {
         "operationId": "statusPageSectionDelete",
         "summary": "Delete status page section",
-        "description": "Delete a section from a status page.",
+        "description": "Delete one or more sections from a status page; their components move to the top level.",
         "tags": [
           "On-call/Status pages"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Status Pages Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Status Pages Manage** (`on-call`) |\n\n## Usage\n\n- If any ID in `section_ids` does not exist on the page, nothing is deleted and the call still returns success.\n- Components in a deleted section are kept and moved to the top level.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/on-call/status-pages/status-page-section-delete",
           "metadata": {
             "sidebarTitle": "Delete status page section"
@@ -16585,6 +17274,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -16614,12 +17306,12 @@
       "post": {
         "operationId": "statusPageTemplateUpsert",
         "summary": "Upsert status page template",
-        "description": "Create or update an event template for a status page.",
+        "description": "Create or update a predefined event template or a message template of a status page.",
         "tags": [
           "On-call/Status pages"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Status Pages Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Status Pages Manage** (`on-call`) |\n\n## Usage\n\n- Omit `template.template_id` to create a template; supply it to update one. An unknown `template_id` returns `InternalError`.\n- On update, empty fields keep their stored values. A predefined template's `type` cannot be changed; a message template's `type` can.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/on-call/status-pages/status-page-template-upsert",
           "metadata": {
             "sidebarTitle": "Upsert status page template"
@@ -16660,6 +17352,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -16693,12 +17388,12 @@
       "post": {
         "operationId": "statusPageTemplateDelete",
         "summary": "Delete status page template",
-        "description": "Delete an event template from a status page.",
+        "description": "Delete a predefined event template or a message template from a status page.",
         "tags": [
           "On-call/Status pages"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Status Pages Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Status Pages Manage** (`on-call`) |\n\n## Usage\n\n- Deleting a template that does not exist returns success.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/on-call/status-pages/status-page-template-delete",
           "metadata": {
             "sidebarTitle": "Delete status page template"
@@ -16737,6 +17432,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -16765,7 +17463,7 @@
       "get": {
         "operationId": "statusPageTemplateList",
         "summary": "List status page templates",
-        "description": "List all event templates for a status page.",
+        "description": "List the predefined event templates or message templates of a status page.",
         "tags": [
           "On-call/Status pages"
         ],
@@ -16819,6 +17517,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -16922,6 +17623,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -16951,7 +17655,7 @@
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Read** (`on-call`) |\n\n## Usage\n\n- Returns the full list in one call — there is no pagination.\n- An account can have at most 10 comment types.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Read** (`on-call`) or **Comment Types Manage** (`on-call`) |\n\n## Usage\n\n- Returns the full list in one call — there is no pagination.\n- An account can have at most 10 comment types.",
           "href": "/en/api-reference/on-call/incidents/incident-comment-type-list",
           "metadata": {
             "sidebarTitle": "List comment types"
@@ -17015,6 +17719,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -17044,7 +17751,7 @@
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Comment Types Manage** (`on-call`) |\n\n## Usage\n\n- The new type is appended to the end of the display ordering.\n- The name must be unique within the account (case-insensitive, after trimming whitespace).\n- An account can have at most 10 comment types.\n- This permission is admin-only by default; custom roles must be granted it explicitly.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Comment Types Manage** (`on-call`) |\n\n## Usage\n\n- The new type is appended to the end of the display ordering.\n- The name must be unique within the account (case-insensitive, after trimming whitespace).\n- An account can have at most 10 comment types.\n- This permission is admin-only by default; custom roles must be granted it explicitly.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/on-call/incidents/incident-comment-type-create",
           "metadata": {
             "sidebarTitle": "Create a comment type"
@@ -17079,11 +17786,11 @@
                       "account_id": 2451002751131,
                       "name": "Key finding",
                       "color": "#30A46C",
-                      "position": 1,
+                      "position": 3,
                       "creator_id": 5068740052131,
                       "updated_by": 5068740052131,
                       "created_at": 1784190422,
-                      "updated_at": 1784207748
+                      "updated_at": 1784190422
                     }
                   }
                 }
@@ -17096,6 +17803,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -17128,7 +17838,7 @@
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Comment Types Manage** (`on-call`) |\n\n## Usage\n\n- Partial update — only the provided fields are changed, but at least one of `name` or `color` must be provided.\n- The name must remain unique within the account (case-insensitive, after trimming whitespace).\n- This permission is admin-only by default; custom roles must be granted it explicitly.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Comment Types Manage** (`on-call`) |\n\n## Usage\n\n- Partial update — only the provided fields are changed, but at least one of `name` or `color` must be provided.\n- The name must remain unique within the account (case-insensitive, after trimming whitespace).\n- This permission is admin-only by default; custom roles must be granted it explicitly.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/on-call/incidents/incident-comment-type-update",
           "metadata": {
             "sidebarTitle": "Update a comment type"
@@ -17167,6 +17877,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -17194,12 +17907,12 @@
       "post": {
         "operationId": "incidentCommentTypeDelete",
         "summary": "Delete a comment type",
-        "description": "Delete a comment type. Comments that used it keep their text but lose the type label.",
+        "description": "Permanently delete a comment type; comments that used it keep their text but lose the label.",
         "tags": [
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Comment Types Manage** (`on-call`) |\n\n## Usage\n\n- Hard delete — the comment type is removed permanently and cannot be restored.\n- Existing comments that referenced the type lose the type label but are not otherwise affected.\n- This permission is admin-only by default; custom roles must be granted it explicitly.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Comment Types Manage** (`on-call`) |\n\n## Usage\n\n- Hard delete — the comment type is removed permanently and cannot be restored.\n- Existing comments that referenced the type lose the type label but are not otherwise affected.\n- This permission is admin-only by default; custom roles must be granted it explicitly.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/on-call/incidents/incident-comment-type-delete",
           "metadata": {
             "sidebarTitle": "Delete a comment type"
@@ -17238,6 +17951,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -17269,7 +17985,7 @@
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Comment Types Manage** (`on-call`) |\n\n## Usage\n\n- Full-set reorder — `comment_type_ids` must contain every comment type of the account, each exactly once, in the desired order.\n- Positions are reassigned starting from 1: the first ID in the array becomes position 1.\n- This permission is admin-only by default; custom roles must be granted it explicitly.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Comment Types Manage** (`on-call`) |\n\n## Usage\n\n- Full-set reorder — `comment_type_ids` must contain every comment type of the account, each exactly once, in the desired order.\n- Positions are reassigned starting from 1: the first ID in the array becomes position 1.\n- This permission is admin-only by default; custom roles must be granted it explicitly.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/on-call/incidents/incident-comment-type-reorder",
           "metadata": {
             "sidebarTitle": "Reorder comment types"
@@ -17308,6 +18024,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -17342,7 +18061,7 @@
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Read** (`on-call`) |\n\n## Usage\n\n- At least one of `incident_id`, `post_mortem_id`, `assignee_id`, or `assignee_type` = `ai_sre` is required.\n- `assignee_type` = `ai_sre` lists items assigned to AI SRE and can be used on its own.\n- Cursor pagination sorted by `updated_at_seconds` descending — pass the previous response's `next_cursor` as `cursor` until `has_more` is false.\n- Listing by `incident_id` also includes follow-ups anchored on the incident's post-mortem.\n- Listing by `assignee_id` alone requires being that assignee or an account admin.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- At least one of `incident_id`, `post_mortem_id`, `assignee_id`, or `assignee_type` = `ai_sre` is required.\n- Filtering by `incident_id` or `post_mortem_id` requires read access to that incident or report; listing by `incident_id` also includes follow-ups bound to the incident's post-mortem when the caller can read it.\n- Listing by `assignee_id` alone requires being that member or an account owner or admin. Without `incident_id` and `post_mortem_id`, callers who are not owner or admin see only items whose incident or report they can read.\n- Sorted by `updated_at_seconds` descending. Pass the previous response's `next_cursor` as `cursor` until `has_more` is false.",
           "href": "/en/api-reference/on-call/incidents/incident-work-item-list",
           "metadata": {
             "sidebarTitle": "List work items"
@@ -17377,17 +18096,29 @@
                         "item_type": "follow_up",
                         "incident_id": "6a5f1e28807515413b384bce",
                         "post_mortem_id": "51d65cd9525c369379ba471b5512df63",
-                        "title": "Follow-ups assigned to Bowen and Weili",
+                        "title": "Add a saturation alert for the orders database pool",
                         "status": "done",
+                        "priority": "medium",
                         "source_kind": "native",
-                        "version": 2,
+                        "version": 3,
                         "assignee_ids": [
                           3790925372131,
-                          4756301322131,
                           5068740052131
                         ],
-                        "created_by": 5329873302131,
+                        "assignees": [
+                          {
+                            "type": "person",
+                            "id": 3790925372131
+                          },
+                          {
+                            "type": "person",
+                            "id": 5068740052131
+                          }
+                        ],
+                        "created_by": 4756301322131,
                         "updated_by": 3790925372131,
+                        "converted_by": 4756301322131,
+                        "converted_at_seconds": 1785495900,
                         "created_at_seconds": 1785495329,
                         "updated_at_seconds": 1785496384
                       },
@@ -17396,20 +18127,29 @@
                         "item_type": "follow_up",
                         "incident_id": "6a5f1e28807515413b384bce",
                         "post_mortem_id": "51d65cd9525c369379ba471b5512df63",
-                        "title": "Check whether this to-do notifies Bowen",
+                        "title": "Document the cache TTL rollback procedure",
                         "status": "open",
+                        "priority": "low",
                         "source_kind": "native",
-                        "version": 1,
+                        "version": 2,
                         "assignee_ids": [
                           5068740052131
                         ],
+                        "assignees": [
+                          {
+                            "type": "person",
+                            "id": 5068740052131
+                          }
+                        ],
                         "created_by": 3790925372131,
                         "updated_by": 3790925372131,
+                        "converted_by": 3790925372131,
+                        "converted_at_seconds": 1785495200,
                         "created_at_seconds": 1785495164,
-                        "updated_at_seconds": 1785495164
+                        "updated_at_seconds": 1785495200
                       }
                     ],
-                    "next_cursor": "MTc4NTQ5NTE2NHx3aV9kTVJZVGVaSGl2RTV2Zjg3UFFFZUZY",
+                    "next_cursor": "MTc4NTQ5NTIwMHx3aV9kTVJZVGVaSGl2RTV2Zjg3UFFFZUZY",
                     "has_more": true
                   }
                 }
@@ -17422,6 +18162,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -17438,7 +18181,7 @@
               },
               "example": {
                 "incident_id": "6a5f1e28807515413b384bce",
-                "limit": 50
+                "limit": 2
               }
             }
           }
@@ -17449,12 +18192,12 @@
       "post": {
         "operationId": "incidentWorkItemCreate",
         "summary": "Create a work item",
-        "description": "Create an action on an active incident or a follow-up on one of its post-mortems.",
+        "description": "Create an action on an open incident, or a follow-up on a closed incident.",
         "tags": [
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |\n\n## Usage\n\n- Requires the On-call Pro license.\n- An `action` anchors to an active incident and must NOT set `post_mortem_id`; a `follow_up` REQUIRES the `post_mortem_id` of a post-mortem linked to `incident_id`.\n- Set either `assignees` or the legacy `assignee_ids`, not both. `assignees` entries are `{type, id?}` with `type` `person` or `ai_sre`; an `ai_sre` entry omits `id`. `assignee_ids` is equivalent to an all-`person` list. Sending both returns an error.\n- Person assignees must be active members who can already read the anchor incident or post-mortem — assignment never grants access.\n- Newly added assignees are notified.\n- Retrying with the same (`creator`, `idempotency_key`) replays the original item with `idempotent_replay: true` instead of creating a duplicate.\n- Audited — changes are recorded in the audit log.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Requires the On-call Pro license.\n- `action`: the incident must not be closed, the caller needs edit access to it, and `post_mortem_id` must be empty.\n- `follow_up`: the incident must be closed. With `post_mortem_id`, the caller needs edit access to that report and the incident must be linked to it. Without it, the caller needs edit access to the incident, and the server binds the incident's post-mortem if one exists; otherwise the item stays unbound until a report is created.\n- Set either `assignees` (entries `{type, id?}`; `type` is `person` or `ai_sre`, and an `ai_sre` entry omits `id`) or the legacy `assignee_ids` (all `person`), not both — sending both returns an error.\n- Person assignees must be active members who can already read the incident or post-mortem — assignment never grants access.\n- Newly added person assignees are notified; assigning `ai_sre` starts an AI SRE session that works on the item.\n- Retrying with the same `idempotency_key` from the same caller returns the original item with `idempotent_replay: true`; if that item was deleted, the call returns `RequestLocked`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/on-call/incidents/incident-work-item-create",
           "metadata": {
             "sidebarTitle": "Create a work item"
@@ -17488,12 +18231,20 @@
                       "item_type": "action",
                       "incident_id": "6a5f1e28807515413b384bce",
                       "title": "Roll back the v2.14 deployment on web-server-01",
+                      "description": "CPU saturation started right after the v2.14 rollout; roll back and watch the error rate.",
                       "status": "open",
+                      "priority": "high",
                       "source_kind": "native",
                       "version": 1,
                       "assignee_ids": [
                         3790925372131
                       ],
+                      "assignees": [
+                        {
+                          "type": "person",
+                          "id": 3790925372131
+                        }
+                      ],
                       "created_by": 3790925372131,
                       "updated_by": 3790925372131,
                       "created_at_seconds": 1785496400,
@@ -17513,6 +18264,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -17553,7 +18307,7 @@
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |\n\n## Usage\n\n- Requires the On-call Pro license.\n- Partial patch: omitted fields stay unchanged; an explicit `null` clears the field.\n- Optimistic locking — `version` must match the item's current version; a mismatch returns a conflict error.\n- Assignees, `item_type`, and the incident/post-mortem anchors cannot be changed here — use the dedicated endpoints.\n- Audited — changes are recorded in the audit log.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Requires the On-call Pro license.\n- Partial patch: omitted fields and fields sent as `null` stay unchanged. Send `\"\"` to clear `description` or `priority`; `title` and `status` cannot be empty.\n- Optimistic locking — `version` must equal the item's current version; a mismatch returns `RequestLocked` (HTTP 423). Re-read the item and retry.\n- When nothing would change, the current item is returned without checking `version` and without incrementing it.\n- The caller needs edit access to the item's anchor: the post-mortem when the item is bound to one, otherwise the incident.\n- A `follow_up` item can be changed only while its incident is closed.\n- Assignees, `item_type`, and the incident/post-mortem anchors cannot be changed here — use the dedicated endpoints.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/on-call/incidents/incident-work-item-update",
           "metadata": {
             "sidebarTitle": "Update a work item"
@@ -17583,23 +18337,28 @@
                   "request_id": "01J8XQ3E5Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "item": {
-                      "work_item_id": "wi_68MHnkWBiyjrh6uhkxUyiZ",
-                      "item_type": "follow_up",
+                      "work_item_id": "wi_9fK2mNqRtVwXyZaBcDeFgH",
+                      "item_type": "action",
                       "incident_id": "6a5f1e28807515413b384bce",
-                      "post_mortem_id": "51d65cd9525c369379ba471b5512df63",
-                      "title": "Follow-ups assigned to Bowen and Weili",
-                      "status": "done",
+                      "title": "Roll back the v2.14 deployment on web-server-01 and web-server-02",
+                      "description": "CPU saturation started right after the v2.14 rollout; roll back and watch the error rate.",
+                      "status": "in_progress",
+                      "priority": "high",
                       "source_kind": "native",
                       "version": 2,
                       "assignee_ids": [
-                        3790925372131,
-                        4756301322131,
-                        5068740052131
+                        3790925372131
+                      ],
+                      "assignees": [
+                        {
+                          "type": "person",
+                          "id": 3790925372131
+                        }
                       ],
-                      "created_by": 5329873302131,
+                      "created_by": 3790925372131,
                       "updated_by": 3790925372131,
-                      "created_at_seconds": 1785495329,
-                      "updated_at_seconds": 1785496384
+                      "created_at_seconds": 1785496400,
+                      "updated_at_seconds": 1785496700
                     }
                   }
                 }
@@ -17612,6 +18371,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -17641,12 +18403,12 @@
       "post": {
         "operationId": "incidentWorkItemDelete",
         "summary": "Delete a work item",
-        "description": "Soft-delete a work item.",
+        "description": "Soft-delete a work item so it no longer appears in work item lists.",
         "tags": [
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |\n\n## Usage\n\n- Requires the On-call Pro license.\n- Soft delete — the item no longer appears in listings but is retained.\n- Optimistic locking — `version` must match the item's current version; a mismatch returns a conflict error.\n- Audited — changes are recorded in the audit log.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Requires the On-call Pro license.\n- Soft delete — the item no longer appears in listings but is retained; its create `idempotency_key` cannot be reused.\n- Optimistic locking — `version` must equal the item's current version; a mismatch returns `RequestLocked` (HTTP 423). Re-read the item and retry.\n- The caller needs edit access to the item's anchor: the post-mortem when the item is bound to one, otherwise the incident.\n- A `follow_up` item can be changed only while its incident is closed.\n- On success `data` is an empty object.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/on-call/incidents/incident-work-item-delete",
           "metadata": {
             "sidebarTitle": "Delete a work item"
@@ -17685,6 +18447,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -17701,7 +18466,7 @@
               },
               "example": {
                 "work_item_id": "wi_9fK2mNqRtVwXyZaBcDeFgH",
-                "version": 2
+                "version": 3
               }
             }
           }
@@ -17712,12 +18477,12 @@
       "post": {
         "operationId": "incidentWorkItemComplete",
         "summary": "Complete a work item",
-        "description": "Mark a work item as completed by setting a client-defined target status.",
+        "description": "Mark a work item as done; only its current assignees can do this.",
         "tags": [
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |\n\n## Usage\n\n- Requires the On-call Pro license.\n- Only current assignees can complete a work item.\n- `target_status` is a client-defined string — there is no fixed state machine.\n- The same `idempotency_key` with the same `target_status` replays idempotently; the same key with a different `target_status` returns an error.\n- Audited — changes are recorded in the audit log.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Requires the On-call Pro license.\n- `target_status` must be `done`.\n- Only a current person assignee can complete the item (account owners and admins are not implicit assignees); an item assigned to AI SRE can also be completed by the AI SRE session working on it. The caller also needs read access to the incident or post-mortem.\n- A `follow_up` item can be changed only while its incident is closed.\n- Repeating the call with the same `idempotency_key` returns the item with `idempotent_replay: true`.\n- Optimistic locking — `version` must equal the item's current version; a mismatch returns `RequestLocked` (HTTP 423). Re-read the item and retry.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/on-call/incidents/incident-work-item-complete",
           "metadata": {
             "sidebarTitle": "Complete a work item"
@@ -17747,23 +18512,28 @@
                   "request_id": "01J8XQ3E5Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "item": {
-                      "work_item_id": "wi_68MHnkWBiyjrh6uhkxUyiZ",
-                      "item_type": "follow_up",
+                      "work_item_id": "wi_9fK2mNqRtVwXyZaBcDeFgH",
+                      "item_type": "action",
                       "incident_id": "6a5f1e28807515413b384bce",
-                      "post_mortem_id": "51d65cd9525c369379ba471b5512df63",
-                      "title": "Follow-ups assigned to Bowen and Weili",
+                      "title": "Roll back the v2.14 deployment on web-server-01 and web-server-02",
+                      "description": "CPU saturation started right after the v2.14 rollout; roll back and watch the error rate.",
                       "status": "done",
+                      "priority": "high",
                       "source_kind": "native",
-                      "version": 2,
+                      "version": 3,
                       "assignee_ids": [
-                        3790925372131,
-                        4756301322131,
-                        5068740052131
+                        3790925372131
                       ],
-                      "created_by": 5329873302131,
+                      "assignees": [
+                        {
+                          "type": "person",
+                          "id": 3790925372131
+                        }
+                      ],
+                      "created_by": 3790925372131,
                       "updated_by": 3790925372131,
-                      "created_at_seconds": 1785495329,
-                      "updated_at_seconds": 1785496384
+                      "created_at_seconds": 1785496400,
+                      "updated_at_seconds": 1785497600
                     }
                   }
                 }
@@ -17776,6 +18546,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -17810,7 +18583,7 @@
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |\n\n## Usage\n\n- Requires the On-call Pro license.\n- Converts an `action` item into a post-mortem `follow_up` in place — the `work_item_id` does not change.\n- Converting an item that is already a `follow_up` returns `idempotent_replay: true`.\n- If a post-mortem already exists for the incident, the converted item auto-binds to it.\n- Audited — changes are recorded in the audit log.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Requires the On-call Pro license.\n- Converts an `action` into a post-mortem `follow_up` in place — the `work_item_id` does not change.\n- Converting an item that is already a `follow_up` changes nothing and returns `idempotent_replay: true`.\n- If the incident already has a post-mortem, the item is bound to it, which requires edit access to that report; otherwise bind it later with `POST /incident/work-item/post-mortem/bind`.\n- The caller needs edit access to the item's anchor: the post-mortem when the item is bound to one, otherwise the incident.\n- Optimistic locking — `version` must equal the item's current version; a mismatch returns `RequestLocked` (HTTP 423). Re-read the item and retry.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/on-call/incidents/incident-work-item-convert",
           "metadata": {
             "sidebarTitle": "Convert a work item to a follow-up"
@@ -17840,23 +18613,31 @@
                   "request_id": "01J8XQ3E5Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "item": {
-                      "work_item_id": "wi_68MHnkWBiyjrh6uhkxUyiZ",
+                      "work_item_id": "wi_9fK2mNqRtVwXyZaBcDeFgH",
                       "item_type": "follow_up",
                       "incident_id": "6a5f1e28807515413b384bce",
                       "post_mortem_id": "51d65cd9525c369379ba471b5512df63",
-                      "title": "Follow-ups assigned to Bowen and Weili",
-                      "status": "done",
+                      "title": "Roll back the v2.14 deployment on web-server-01 and web-server-02",
+                      "description": "CPU saturation started right after the v2.14 rollout; roll back and watch the error rate.",
+                      "status": "open",
+                      "priority": "high",
                       "source_kind": "native",
-                      "version": 2,
+                      "version": 3,
                       "assignee_ids": [
-                        3790925372131,
-                        4756301322131,
-                        5068740052131
+                        3790925372131
+                      ],
+                      "assignees": [
+                        {
+                          "type": "person",
+                          "id": 3790925372131
+                        }
                       ],
-                      "created_by": 5329873302131,
+                      "created_by": 3790925372131,
                       "updated_by": 3790925372131,
-                      "created_at_seconds": 1785495329,
-                      "updated_at_seconds": 1785496384
+                      "converted_by": 3790925372131,
+                      "converted_at_seconds": 1785497600,
+                      "created_at_seconds": 1785496400,
+                      "updated_at_seconds": 1785497600
                     }
                   }
                 }
@@ -17869,6 +18650,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -17903,7 +18687,7 @@
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |\n\n## Usage\n\n- Requires the On-call Pro license.\n- Full replacement of the assignee set — an empty array clears all assignees.\n- Set either `assignees` or the legacy `assignee_ids`, not both (sending both returns an error). An `ai_sre` entry omits `id`.\n- Only newly added assignees are notified; removals never notify.\n- Audited — changes are recorded in the audit log.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Requires the On-call Pro license.\n- Full replacement of the assignee set. Send `assignees` or the legacy `assignee_ids` (not both); omitting both returns an error, and `[]` or `null` clears all assignees.\n- Person assignees must be active members who can already read the incident or post-mortem — assignment never grants access.\n- Only newly added person assignees are notified; removals never notify. Newly adding `ai_sre` starts an AI SRE session for the item.\n- When the set does not change, `version` is not incremented.\n- Optimistic locking — `version` must equal the item's current version; a mismatch returns `RequestLocked` (HTTP 423). Re-read the item and retry.\n- The caller needs edit access to the item's anchor: the post-mortem when the item is bound to one, otherwise the incident.\n- A `follow_up` item can be changed only while its incident is closed.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/on-call/incidents/incident-work-item-reset-assignees",
           "metadata": {
             "sidebarTitle": "Reset work item assignees"
@@ -17933,29 +18717,36 @@
                   "request_id": "01J8XQ3E5Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "item": {
-                      "work_item_id": "wi_68MHnkWBiyjrh6uhkxUyiZ",
-                      "item_type": "follow_up",
+                      "work_item_id": "wi_9fK2mNqRtVwXyZaBcDeFgH",
+                      "item_type": "action",
                       "incident_id": "6a5f1e28807515413b384bce",
-                      "post_mortem_id": "51d65cd9525c369379ba471b5512df63",
-                      "title": "Follow-ups assigned to Bowen and Weili",
-                      "status": "done",
+                      "title": "Roll back the v2.14 deployment on web-server-01 and web-server-02",
+                      "description": "CPU saturation started right after the v2.14 rollout; roll back and watch the error rate.",
+                      "status": "in_progress",
+                      "priority": "high",
                       "source_kind": "native",
-                      "version": 2,
+                      "version": 3,
                       "assignee_ids": [
                         3790925372131,
-                        4756301322131,
                         5068740052131
                       ],
-                      "created_by": 5329873302131,
+                      "assignees": [
+                        {
+                          "type": "person",
+                          "id": 3790925372131
+                        },
+                        {
+                          "type": "person",
+                          "id": 5068740052131
+                        }
+                      ],
+                      "created_by": 3790925372131,
                       "updated_by": 3790925372131,
-                      "created_at_seconds": 1785495329,
-                      "updated_at_seconds": 1785496384
+                      "created_at_seconds": 1785496400,
+                      "updated_at_seconds": 1785497000
                     },
                     "added_assignee_ids": [
                       5068740052131
-                    ],
-                    "removed_assignee_ids": [
-                      4756301322131
                     ]
                   }
                 }
@@ -17968,6 +18759,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -18004,7 +18798,7 @@
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |\n\n## Usage\n\n- Requires the On-call Pro license.\n- Binds ALL of the incident's converted-but-unbound follow-ups to the given post-mortem in one call.\n- `items` holds the newly bound batch; `next_cursor` and `has_more` are not set.\n- Idempotent by `idempotency_key` — retrying with the same key replays the original result.\n- Audited — changes are recorded in the audit log.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Requires the On-call Pro license.\n- Binds every item of the incident that was converted from an action and is not yet bound to any post-mortem.\n- The caller needs edit access to the post-mortem, and `incident_id` must be linked to it.\n- `items` holds the items bound by this call and may be empty; `next_cursor` is not set and `has_more` is false.\n- Retrying with the same `idempotency_key` returns the items bound earlier with `idempotent_replay: true`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/on-call/incidents/incident-work-item-bind-post-mortem",
           "metadata": {
             "sidebarTitle": "Bind work items to a post-mortem"
@@ -18039,17 +18833,29 @@
                         "item_type": "follow_up",
                         "incident_id": "6a5f1e28807515413b384bce",
                         "post_mortem_id": "51d65cd9525c369379ba471b5512df63",
-                        "title": "Follow-ups assigned to Bowen and Weili",
+                        "title": "Add a saturation alert for the orders database pool",
                         "status": "done",
+                        "priority": "medium",
                         "source_kind": "native",
-                        "version": 2,
+                        "version": 3,
                         "assignee_ids": [
                           3790925372131,
-                          4756301322131,
                           5068740052131
                         ],
-                        "created_by": 5329873302131,
+                        "assignees": [
+                          {
+                            "type": "person",
+                            "id": 3790925372131
+                          },
+                          {
+                            "type": "person",
+                            "id": 5068740052131
+                          }
+                        ],
+                        "created_by": 4756301322131,
                         "updated_by": 3790925372131,
+                        "converted_by": 4756301322131,
+                        "converted_at_seconds": 1785495900,
                         "created_at_seconds": 1785495329,
                         "updated_at_seconds": 1785496384
                       },
@@ -18058,17 +18864,26 @@
                         "item_type": "follow_up",
                         "incident_id": "6a5f1e28807515413b384bce",
                         "post_mortem_id": "51d65cd9525c369379ba471b5512df63",
-                        "title": "Check whether this to-do notifies Bowen",
+                        "title": "Document the cache TTL rollback procedure",
                         "status": "open",
+                        "priority": "low",
                         "source_kind": "native",
-                        "version": 1,
+                        "version": 2,
                         "assignee_ids": [
                           5068740052131
                         ],
+                        "assignees": [
+                          {
+                            "type": "person",
+                            "id": 5068740052131
+                          }
+                        ],
                         "created_by": 3790925372131,
                         "updated_by": 3790925372131,
+                        "converted_by": 3790925372131,
+                        "converted_at_seconds": 1785495200,
                         "created_at_seconds": 1785495164,
-                        "updated_at_seconds": 1785495164
+                        "updated_at_seconds": 1785495200
                       }
                     ],
                     "has_more": false
@@ -18083,6 +18898,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -18116,7 +18934,7 @@
           "On-call/Schedules"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Schedules Read** (`on-call`) or **Schedules Manage** (`on-call`) |\n\n## Usage\n\n- `current` carries the shift in progress with its true start time; `next` is the upcoming shift, absent when nothing is scheduled within the lookup window.\n- Disabled schedules are not listed.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- `current` is the shift in progress with its real start time; when the member is on call in several schedules at once, the one ending last is returned. `next` is the earliest upcoming shift. Each is `null` when nothing is found within 45 days of now.\n- `schedules` lists the enabled schedules where the member is in at least one layer that has not ended. Disabled schedules are not listed and do not count toward `current`/`next`.\n- Any member of the account can be queried; `person_id` comes from the member list.",
           "href": "/en/api-reference/on-call/schedules/schedule-by-person",
           "metadata": {
             "sidebarTitle": "Get member on-call status"
@@ -18154,8 +18972,7 @@
                     "next": {
                       "schedule_id": 2539108069860,
                       "schedule_name": "Open Source Q&A",
-                      "start_at": 1773532800,
-                      "end_at": 1773619199
+                      "start_at": 1773532800
                     },
                     "schedules": [
                       {
@@ -18174,6 +18991,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -18203,7 +19023,7 @@
         "type": "apiKey",
         "in": "query",
         "name": "app_key",
-        "description": "App key issued from the Flashduty console under Account → APP Keys. Required on every public API call. Keep it secret — it grants the same access as the owning account."
+        "description": "APP Key created in the Flashduty console under My → APP Key. Send it as the `app_key` query parameter or in the `Fd-App-Key` request header. Its effective access is the intersection of the key's permission scope and the creator's current role permissions. Keep it secret."
       }
     },
     "responses": {
@@ -18250,7 +19070,7 @@
         }
       },
       "Forbidden": {
-        "description": "The app_key is valid but lacks permission for this operation.",
+        "description": "The app_key is valid, but its permission scope or the creator's role does not allow this operation or object.",
         "content": {
           "application/json": {
             "schema": {
@@ -18292,7 +19112,7 @@
         }
       },
       "TooManyRequests": {
-        "description": "Rate limit hit. Either the global API limit, a per-account limit, or a per-integration limit.",
+        "description": "Rate limit hit (per-account limit or the operation's platform-wide limit). Wait for the number of seconds in `Flashcat-Request-Rate-Limit-Delay`, then retry.",
         "content": {
           "application/json": {
             "schema": {
@@ -18310,6 +19130,15 @@
               }
             }
           }
+        },
+        "headers": {
+          "Flashcat-Request-Rate-Limit-Delay": {
+            "description": "Seconds until the current rate-limit window resets. Absent when the request was rejected by the gateway's global protection limit.",
+            "schema": {
+              "type": "integer",
+              "minimum": 0
+            }
+          }
         }
       },
       "ServerError": {
@@ -18461,30 +19290,30 @@
               "type": "integer",
               "format": "int64"
             },
-            "description": "Member IDs to add as responders."
+            "description": "Member IDs to add as responders. IDs that are already responders, or that do not exist in the account, are skipped."
           },
           "notify": {
             "type": "object",
-            "description": "Optional notification override. Defaults to following each person's personal preference.",
+            "description": "Notification settings for the newly added responders. Defaults to `{\"follow_preference\": true}`.",
             "properties": {
               "follow_preference": {
                 "type": [
                   "boolean",
                   "null"
                 ],
-                "description": "When false, use `personal_channels`; when true or omitted, use each responder's personal preference."
+                "description": "`true`: notify each person through their personal notification preference. `false`: use `personal_channels`, which must then be non-empty. When omitted, `personal_channels` must be set."
               },
               "personal_channels": {
                 "type": "array",
                 "items": {
                   "type": "string"
                 },
-                "description": "Channels to use (e.g. `voice`, `sms`, `email`)."
+                "description": "Channels used when `follow_preference` is `false`: `sms`, `voice`, `email`, `push` (mobile app push), or an IM app channel written as `feishu_app:<integration_id>`, `dingtalk_app:<integration_id>`, `wecom_app:<integration_id>`, `slack_app:<integration_id>`, or `teams_app:<integration_id>`. Ignored when `follow_preference` is `true`."
               },
               "template_id": {
                 "type": "string",
                 "pattern": "^[0-9a-fA-F]{24}$",
-                "description": "Notification template ID (MongoDB ObjectID)."
+                "description": "Notification template ID, as returned by the notification template endpoints. Must exist in the account; otherwise the call fails with `InvalidParameter`."
               }
             }
           }
@@ -18616,7 +19445,7 @@
           },
           "severities": {
             "type": "string",
-            "description": "Comma-separated severity filter, e.g. `Critical,Warning`. Accepted values: `Critical`, `Warning`, `Info`, `Ok`."
+            "description": "Comma-separated filter on `event_severity`, e.g. `Critical,Warning`. Meaningful values: `Critical`, `Warning`, `Info`. Values are not validated; an unknown value (or `Ok`) matches nothing."
           },
           "orderby": {
             "type": "string",
@@ -18673,7 +19502,7 @@
           "account_id": {
             "type": "integer",
             "format": "int64",
-            "description": "Account ID."
+            "description": "ID of the account that owns this record; the same for every record returned to one `app_key`."
           },
           "channel_id": {
             "type": "integer",
@@ -18687,7 +19516,7 @@
           },
           "integration_type": {
             "type": "string",
-            "description": "Type/plugin key of the integration that produced this event."
+            "description": "Plugin type of the integration, such as `prometheus.alert`, `grafana.alert`, `zabbix.alert`, `monit.alert`, or `email.alert`. The set is open and grows with new integrations; `POST /integration/type/list` returns the full list."
           },
           "data_source_id": {
             "type": "integer",
@@ -18929,7 +19758,7 @@
           },
           "alt": {
             "type": "string",
-            "description": "Alt text."
+            "description": "Alternative text shown when the image cannot be displayed; empty when not set."
           }
         }
       },
@@ -18986,12 +19815,12 @@
           "channel_id": {
             "type": "integer",
             "format": "int64",
-            "description": "Channel ID."
+            "description": "ID of the channel the alert was routed to; its name is in `channel_name`."
           },
           "account_id": {
             "type": "integer",
             "format": "int64",
-            "description": "Account ID."
+            "description": "ID of the account that owns this record; the same for every record returned to one `app_key`."
           },
           "description": {
             "type": "string",
@@ -19045,7 +19874,10 @@
             "description": "Unix timestamp (seconds) when the alert recovered. 0 if still active."
           },
           "labels": {
-            "type": "object",
+            "type": [
+              "object",
+              "null"
+            ],
             "additionalProperties": {
               "type": "string"
             },
@@ -19076,7 +19908,7 @@
           },
           "integration_type": {
             "type": "string",
-            "description": "Integration type string."
+            "description": "Plugin type of the integration, such as `prometheus.alert`, `grafana.alert`, `zabbix.alert`, `monit.alert`, or `email.alert`. The set is open and grows with new integrations; `POST /integration/type/list` returns the full list."
           },
           "integration_ref_id": {
             "type": "string",
@@ -19088,15 +19920,21 @@
           },
           "channel_status": {
             "type": "string",
-            "description": "Channel status."
+            "description": "Status of the channel: `enabled`, `disabled`, or `deleted`. Empty string when the record has no channel or the channel no longer exists.",
+            "enum": [
+              "enabled",
+              "disabled",
+              "deleted",
+              ""
+            ]
           },
           "responder_name": {
             "type": "string",
-            "description": "Primary responder name, if any."
+            "description": "Always an empty string in API responses; filled only when the alert is rendered for notifications."
           },
           "responder_email": {
             "type": "string",
-            "description": "Primary responder email, if any."
+            "description": "Always an empty string in API responses; filled only when the alert is rendered for notifications."
           },
           "incident": {
             "$ref": "#/components/schemas/IncidentShort",
@@ -19115,11 +19953,14 @@
             "description": "Total number of raw events merged into this alert."
           },
           "images": {
-            "type": "array",
+            "type": [
+              "array",
+              "null"
+            ],
             "items": {
               "$ref": "#/components/schemas/Image"
             },
-            "description": "Attached images."
+            "description": "Images attached to the alert; `null` when there are none."
           },
           "detail_url": {
             "description": "Console URL of this alert (`{console}/alert/detail/{alert_id}`). Empty when the deployment has no console base configured.",
@@ -19131,7 +19972,7 @@
           },
           "data_source_type": {
             "type": "string",
-            "description": "Deprecated. Use `integration_type`."
+            "description": "Deprecated; same value as `integration_type`."
           },
           "data_source_ref_id": {
             "type": "string",
@@ -19179,7 +20020,7 @@
           "account_id": {
             "type": "integer",
             "format": "int64",
-            "description": "Account ID."
+            "description": "ID of the account that owns the alert."
           },
           "title": {
             "type": "string",
@@ -19232,11 +20073,14 @@
             "description": "Resolution time, Unix epoch seconds. 0 if still active."
           },
           "labels": {
-            "type": "object",
+            "type": [
+              "object",
+              "null"
+            ],
             "additionalProperties": {
               "type": "string"
             },
-            "description": "Label key-value pairs."
+            "description": "Label key-value pairs; `null` when the alert has no labels."
           },
           "ever_muted": {
             "type": "boolean",
@@ -19258,11 +20102,11 @@
           },
           "integration_type": {
             "type": "string",
-            "description": "Type/plugin key of the integration."
+            "description": "Type key of the integration that produced the alert, e.g. `prometheus.alert` or `zabbix.alert`; same values as `plugin_type` from `POST /integration/type/list`."
           },
           "integration_ref_id": {
             "type": "string",
-            "description": "External reference ID of the integration."
+            "description": "Owner reference of the integration: `a_<account_id>` for an account-level integration, `c_<channel_id>` for a channel-owned one."
           },
           "channel_name": {
             "type": "string",
@@ -19301,11 +20145,14 @@
             "description": "Raw events of this alert. Omitted here; populated only by `POST /incident/alert/list`."
           },
           "images": {
-            "type": "array",
+            "type": [
+              "array",
+              "null"
+            ],
             "items": {
               "$ref": "#/components/schemas/AlertImage"
             },
-            "description": "Images attached to the alert."
+            "description": "Images attached to the alert; `null` when there are none."
           },
           "detail_url": {
             "description": "Console URL of this alert (`{console}/alert/detail/{alert_id}`). Empty when the deployment has no console base configured.",
@@ -19318,7 +20165,7 @@
           },
           "data_source_type": {
             "type": "string",
-            "description": "Deprecated: use `integration_type` instead. Omitted when empty.",
+            "description": "Deprecated: use `integration_type` instead (same value, e.g. `prometheus.alert`). Omitted when empty.",
             "deprecated": true
           },
           "data_source_ref_id": {
@@ -19344,8 +20191,7 @@
             "items": {
               "type": "string"
             },
-            "description": "Alert IDs (ObjectID hex strings) to fetch.",
-            "minItems": 1
+            "description": "Alert IDs (ObjectID hex strings) to fetch. A malformed ID fails the request; IDs not found in the account are left out of the result."
           }
         }
       },
@@ -19360,12 +20206,12 @@
           "start_time": {
             "type": "integer",
             "format": "int64",
-            "description": "Start of the search window, Unix epoch seconds."
+            "description": "Start of the search window, Unix epoch seconds, applied to the alert's `start_time`. A value earlier than the account's data retention period is moved up to the retention start."
           },
           "end_time": {
             "type": "integer",
             "format": "int64",
-            "description": "End of the search window, Unix epoch seconds. Must be greater than `start_time`; the span must not exceed 31 days and must lie within the account's data retention period."
+            "description": "End of the search window, Unix epoch seconds. Must be greater than `start_time`; the span must not exceed 31 days (7 days with `by_updated_at`). A value before the start of the data retention period returns `InvalidParameter`."
           },
           "p": {
             "type": [
@@ -19409,7 +20255,7 @@
           },
           "alert_severity": {
             "type": "string",
-            "description": "Comma-separated severity filter, e.g. `Critical,Warning`. Allowed values: `Critical`, `Warning`, `Info`, `Ok`."
+            "description": "Comma-separated filter on `alert_severity`, e.g. `Critical,Warning`. Allowed values: `Critical`, `Warning`, `Info`, `Ok`; other values return `InvalidParameter`. `Ok` matches nothing because `alert_severity` is never `Ok`."
           },
           "channel_ids": {
             "type": "array",
@@ -19447,7 +20293,7 @@
           },
           "by_updated_at": {
             "type": "boolean",
-            "description": "When `true`, the time range filter is applied on `updated_at` rather than `start_time`."
+            "description": "When `true`, also require the alert's `updated_at` to fall within [`start_time`, `end_time`], in addition to the `start_time` filter; the span must then not exceed 7 days."
           }
         }
       },
@@ -19458,15 +20304,15 @@
           "total": {
             "type": "integer",
             "format": "int64",
-            "description": "Total matching alerts, capped at 1000."
+            "description": "Number of matching alerts, capped at 1,000."
           },
           "has_next_page": {
             "type": "boolean",
-            "description": "True if more pages are available."
+            "description": "`true` when another page exists. In cursor mode (`search_after_ctx` sent) it is exact. In page-number mode it compares `p * limit` with the capped `total`, so it is `false` past 1,000 alerts even when more match; continue with `search_after_ctx` instead."
           },
           "search_after_ctx": {
             "type": "string",
-            "description": "Cursor for the next page — the ObjectID hex of the last alert on this page; pass it back as `search_after_ctx`. Present only when `has_next_page` is true."
+            "description": "Cursor for the next page — the ObjectID hex of the last alert on this page; pass it back as `search_after_ctx`. Omitted when the page is empty; in cursor mode also omitted when there is no next page."
           },
           "items": {
             "type": "array",
@@ -19489,8 +20335,7 @@
             "items": {
               "type": "string"
             },
-            "description": "Alert IDs to merge (ObjectID hex strings); obtain them from `POST /alert/list`. Every ID must belong to the caller's account.",
-            "minItems": 1
+            "description": "Alert IDs to merge (ObjectID hex strings); obtain them from `POST /alert/list`. Every ID must belong to the caller's account."
           },
           "incident_id": {
             "type": "string",
@@ -19537,7 +20382,7 @@
             "items": {
               "$ref": "#/components/schemas/FilterCondition"
             },
-            "description": "AND-filter list — the rule applies only when every condition matches. `null` or omitted means the rule applies to all events."
+            "description": "AND-filter list — the rule applies only when every condition matches the incoming event. Keys: `severity` (aliases `alert_severity`, `event_severity`), `status`, `title`, `title_rule`, `description`, `alert_key`, `integration_id` (alias `data_source_id`), and `labels.<name>`; other keys return `InvalidParameter`. `null` or omitted means the rule applies to all events."
           },
           "settings": {
             "type": "object",
@@ -19668,27 +20513,26 @@
           "integration_id": {
             "type": "integer",
             "format": "int64",
-            "description": "Integration ID to configure."
+            "description": "ID of the integration to configure; account-level and channel-owned integrations are both accepted."
           },
           "rules": {
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/AlertPipeline"
             },
-            "description": "Rules to apply, evaluated in array order. Between 1 and 50 entries.",
-            "maxItems": 50,
-            "minItems": 1
+            "description": "Rules to apply, evaluated in array order. At most 50 entries; an empty array removes all rules.",
+            "maxItems": 50
           }
         }
       },
       "ApAlertDrop": {
         "type": "object",
-        "description": "Settings for `alert_drop` rule: no additional settings required. Matched alerts are silently discarded.",
+        "description": "Settings for `alert_drop`: no fields; send `{}`. A matching event is discarded and no alert is created or updated.",
         "properties": {}
       },
       "ApAlertInhibit": {
         "type": "object",
-        "description": "Settings for `alert_inhibit` rule: suppresses source alerts that match the filter when they share the same label values as the current alert.",
+        "description": "Settings for `alert_inhibit`: the current event is discarded when an active alert of the same integration, with a different `alert_key` and started within the 10 minutes before the event, matches `source_filters` and has the same value as the event for every `equals` key.",
         "required": [
           "equals",
           "source_filters"
@@ -19699,33 +20543,33 @@
             "items": {
               "type": "string"
             },
-            "description": "Label keys whose values must be equal between the source and current alert for inhibition to apply."
+            "description": "Keys whose values must be equal on the source alert and the current event: `title`, `severity`, or `labels.<name>`. An empty list, any other key, or a label missing on the event means the rule never inhibits."
           },
           "source_filters": {
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/FilterCondition"
             },
-            "description": "AND-filter list identifying the source alerts to inhibit — every condition must match."
+            "description": "AND-conditions a source alert must meet. Allowed keys: `severity`, `title`, and `labels.<name>`; other keys return `InvalidParameter`."
           }
         }
       },
       "ApDescriptionReset": {
         "type": "object",
-        "description": "Settings for `description_reset` rule: overrides the alert description.",
+        "description": "Settings for `description_reset`: replaces the event description with a rendered template.",
         "required": [
           "description"
         ],
         "properties": {
           "description": {
             "type": "string",
-            "description": "New description template."
+            "description": "Description template. Only a value starting with `[TPL]` takes effect: the rest is rendered as a Go template against the event and replaces the description. A value without the prefix leaves the description unchanged."
           }
         }
       },
       "ApSeverityReset": {
         "type": "object",
-        "description": "Settings for `severity_reset` rule: forces the alert severity to a fixed value.",
+        "description": "Settings for `severity_reset`: sets the event severity, and its status, to a fixed value.",
         "required": [
           "severity"
         ],
@@ -19737,20 +20581,20 @@
               "Warning",
               "Info"
             ],
-            "description": "Target severity level."
+            "description": "Severity to set: `Critical`, `Warning` or `Info`. The event status is set to the same value."
           }
         }
       },
       "ApTitleReset": {
         "type": "object",
-        "description": "Settings for `title_reset` rule: overrides the alert title with a template string.",
+        "description": "Settings for `title_reset`: replaces the event title using a title rule.",
         "required": [
           "title"
         ],
         "properties": {
           "title": {
             "type": "string",
-            "description": "New title template. Supports Golang template syntax referencing alert fields."
+            "description": "Title rule. A value starting with `[TPL]` is a Go template rendered against the event, e.g. `[TPL]{{.Labels.service}}`. Otherwise it is a `::`-separated list in which each `$name` part is replaced by the value of label `name` and other parts are kept as written."
           }
         }
       },
@@ -19778,13 +20622,13 @@
           },
           "assigned_to": {
             "$ref": "#/components/schemas/AssignedTo",
-            "description": "Assign target; at least one of `person_ids` and `escalate_rule_id` must be set."
+            "description": "Assignment target. Set `person_ids`, `escalate_rule_id`, or `emails`; when none is set, the server re-runs the channel's escalation rule matching."
           }
         }
       },
       "AssignedTo": {
         "type": "object",
-        "description": "Incident assignment target. Either `person_ids` or `escalate_rule_id` must be provided.",
+        "description": "Assignment target. In requests, set `person_ids`, `escalate_rule_id`, or `emails`; when none is set the server re-runs the channel's escalation rule matching. In responses the object is always present; an incident that was never assigned has empty `type`, `id`, and `assigned_at` of `0`.",
         "properties": {
           "person_ids": {
             "type": "array",
@@ -19803,16 +20647,17 @@
           },
           "layer_idx": {
             "type": "integer",
-            "description": "Current level index within the escalation rule."
+            "description": "Zero-based escalation level within `escalate_rule_id` (`0` = first level). Responders are taken from this level."
           },
           "type": {
             "type": "string",
-            "description": "Assignment type: `assign` direct assignment, `reassign` reassignment, `escalate` escalation-rule driven, `reopen` automatic reassignment on reopen.",
+            "description": "How the assignment happened: `assign` first assignment; `reassign` reassignment of an already assigned incident; `escalate` moved by the escalation flow; `reopen` reassignment after the incident was reopened; empty string in responses when the incident was never assigned. Omit it in requests and the server derives it.",
             "enum": [
               "assign",
               "reassign",
               "escalate",
-              "reopen"
+              "reopen",
+              ""
             ]
           },
           "emails": {
@@ -19823,7 +20668,7 @@
             },
             "minItems": 1,
             "maxItems": 100,
-            "description": "Email recipients, used by integrations such as ServiceNow."
+            "description": "Member emails; each is resolved to a member ID and merged into `person_ids`. Emails without a matching member are ignored."
           },
           "notify": {
             "type": "object",
@@ -19834,14 +20679,14 @@
                   "boolean",
                   "null"
                 ],
-                "description": "When false, use `personal_channels`; when true or omitted, use each responder's personal preference."
+                "description": "`true`: notify each person through their personal notification preference. `false`: use `personal_channels`, which must then be non-empty. When omitted, `personal_channels` must be set."
               },
               "personal_channels": {
                 "type": "array",
                 "items": {
                   "type": "string"
                 },
-                "description": "Channels to use (e.g. `voice`, `sms`, `email`)."
+                "description": "Channels used when `follow_preference` is `false`: `sms`, `voice`, `email`, `push` (mobile app push), or an IM app channel written as `feishu_app:<integration_id>`, `dingtalk_app:<integration_id>`, `wecom_app:<integration_id>`, `slack_app:<integration_id>`, or `teams_app:<integration_id>`. Ignored when `follow_preference` is `true`."
               },
               "template_id": {
                 "type": "string",
@@ -19852,16 +20697,24 @@
           },
           "escalate_rule_name": {
             "type": "string",
-            "description": "Escalation rule display name, filled by the server."
+            "description": "Escalation rule name, filled by the server in responses; ignored in requests."
           },
           "assigned_at": {
             "type": "integer",
             "format": "int64",
-            "description": "Unix timestamp (seconds) when the assignment was made."
+            "description": "Unix timestamp (seconds) when the assignment was made; set by the server."
           },
           "id": {
             "type": "string",
-            "description": "Opaque assignment ID generated by the server."
+            "description": "Assignment ID generated by the server for each assignment; set by the server."
+          },
+          "effective_person_ids": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "int64"
+            },
+            "description": "Member IDs that actually received the assignment: `person_ids` plus the members of the selected escalation level, deduplicated and sorted. Set by the server; omitted when empty."
           }
         }
       },
@@ -19921,7 +20774,7 @@
           },
           "event_id": {
             "type": "string",
-            "description": "Event ID."
+            "description": "Event ID. `cale.<id>` for the calendar's own events, `non_work.YYYYMMDD` for generated non-working weekdays, and `<holiday cal_id>.<id>` for events inherited from a holiday calendar."
           },
           "summary": {
             "type": "string",
@@ -19946,12 +20799,12 @@
           "created_at": {
             "type": "integer",
             "format": "int64",
-            "description": "Creation timestamp (Unix seconds)."
+            "description": "Creation timestamp (Unix seconds); `0` for generated `non_work.*` entries."
           },
           "updated_at": {
             "type": "integer",
             "format": "int64",
-            "description": "Last update timestamp (Unix seconds)."
+            "description": "Last update timestamp (Unix seconds); `0` for generated `non_work.*` entries."
           }
         }
       },
@@ -20116,7 +20969,7 @@
         "properties": {
           "cal_name": {
             "type": "string",
-            "description": "Calendar display name.",
+            "description": "Calendar display name; must be unique within the account.",
             "minLength": 1,
             "maxLength": 39
           },
@@ -20127,13 +20980,13 @@
           },
           "timezone": {
             "type": "string",
-            "description": "IANA timezone. Defaults to Asia/Shanghai when empty.",
+            "description": "IANA timezone, e.g. `America/New_York`. Defaults to `Asia/Shanghai` when empty; an invalid name returns `InvalidParameter`.",
             "default": "Asia/Shanghai"
           },
           "team_id": {
             "type": "integer",
             "format": "uint64",
-            "description": "Owning team ID. 0 means no team."
+            "description": "Owning team ID; `0` or omitted means no team. A nonzero ID must be a team of the account."
           },
           "workdays": {
             "type": "array",
@@ -20142,7 +20995,7 @@
               "minimum": 0,
               "maximum": 6
             },
-            "description": "Workday numbers (0 = Sunday, 6 = Saturday)."
+            "description": "Weekly working days, `0` = Sunday … `6` = Saturday. Days not listed are non-working days. When empty, no weekday is treated as non-working."
           },
           "extra_cal_ids": {
             "type": "array",
@@ -20210,7 +21063,7 @@
           "account_id": {
             "type": "integer",
             "format": "uint64",
-            "description": "Account ID."
+            "description": "ID of the account that owns the calendar."
           },
           "team_id": {
             "type": "integer",
@@ -20249,7 +21102,7 @@
               "minimum": 0,
               "maximum": 6
             },
-            "description": "Workday numbers (0 = Sunday, 6 = Saturday). Omitted when empty."
+            "description": "Weekly working days, `0` = Sunday … `6` = Saturday. Days not listed are non-working days. When empty, no weekday is treated as non-working. Omitted when empty."
           },
           "extra_cal_ids": {
             "type": "array",
@@ -20344,7 +21197,7 @@
               "string",
               "null"
             ],
-            "description": "New calendar name.",
+            "description": "New calendar name; must be unique within the account.",
             "minLength": 1,
             "maxLength": 39
           },
@@ -20361,7 +21214,7 @@
               "string",
               "null"
             ],
-            "description": "New IANA timezone."
+            "description": "New IANA timezone, e.g. `Asia/Shanghai`; an invalid name returns `InvalidParameter`."
           },
           "team_id": {
             "type": [
@@ -20369,7 +21222,7 @@
               "null"
             ],
             "format": "uint64",
-            "description": "New owning team ID; obtain it from `POST /team/list`."
+            "description": "New owning team ID; obtain it from `POST /team/list`. `0` removes the team; a nonzero ID must be a team of the account."
           },
           "workdays": {
             "type": "array",
@@ -20378,14 +21231,14 @@
               "minimum": 0,
               "maximum": 6
             },
-            "description": "Workday numbers (0 = Sunday, 6 = Saturday)."
+            "description": "Weekly working days, `0` = Sunday … `6` = Saturday. Days not listed are non-working days. When empty, no weekday is treated as non-working. When sent, replaces the stored list; omit to keep it."
           },
           "extra_cal_ids": {
             "type": "array",
             "items": {
               "type": "string"
             },
-            "description": "Additional public-holiday calendar IDs to inherit events from."
+            "description": "Public holiday calendar IDs to inherit events from (see `POST /calendar/list` with `kind` = `region.official.holiday`). When sent, replaces the stored list; an empty array removes them all; omit to keep it."
           }
         }
       },
@@ -20420,7 +21273,7 @@
           },
           "external_report_token": {
             "type": "string",
-            "description": "External report token. Emitted only when external reporting is enabled."
+            "description": "Token for external reporters. Returned only when the request set `is_external_report_enabled` to `true`; it can be read again later from `POST /channel/info`."
           }
         }
       },
@@ -20478,7 +21331,7 @@
             "items": {
               "$ref": "#/components/schemas/ChannelShort"
             },
-            "description": "Brief info for the requested `channel_ids` that actually exist; IDs not found are ignored."
+            "description": "Requested channels that exist, including deleted ones; unknown IDs are skipped. Ordered by channel creation, not by request order."
           }
         }
       },
@@ -20489,7 +21342,7 @@
           "channel_id": {
             "type": "integer",
             "format": "int64",
-            "description": "Channel ID."
+            "description": "Channel ID; pass it as `channel_id` to the other channel and rule endpoints."
           },
           "team_id": {
             "type": "integer",
@@ -20498,7 +21351,7 @@
           },
           "team_name": {
             "type": "string",
-            "description": "Owning team name (resolved from the team directory; empty when unavailable)."
+            "description": "Owning team name, resolved from the team directory. Returned only by `POST /channel/list` without `is_brief`; omitted when the lookup fails."
           },
           "managing_team_ids": {
             "type": "array",
@@ -20515,7 +21368,7 @@
           },
           "creator_name": {
             "type": "string",
-            "description": "Name of the member who created the channel (resolved from the member directory; empty when unavailable)."
+            "description": "Name of the member who created the channel. Returned only by `POST /channel/list` without `is_brief`; omitted when the lookup fails."
           },
           "account_id": {
             "type": "integer",
@@ -20524,7 +21377,7 @@
           },
           "channel_name": {
             "type": "string",
-            "description": "Channel name."
+            "description": "Channel name, unique within the account, 1–59 characters."
           },
           "description": {
             "type": "string",
@@ -20537,7 +21390,7 @@
               "disabled",
               "deleted"
             ],
-            "description": "Channel status. `enabled` receives and processes events normally; `disabled` drops incoming events outright; `deleted` is returned only when fetching a channel by ID — list endpoints never return it."
+            "description": "Channel status:\n- `enabled`: incoming alert events are processed.\n- `disabled`: incoming alert events are discarded.\n- `deleted`: the channel was deleted; returned only by `POST /channel/info` and `POST /channel/infos`, never by `POST /channel/list`."
           },
           "deleted_at": {
             "type": "integer",
@@ -20581,19 +21434,19 @@
           },
           "group": {
             "$ref": "#/components/schemas/Group",
-            "description": "Alert grouping configuration."
+            "description": "Alert grouping configuration. When never set, `{\"method\": \"n\"}` (no grouping) is returned."
           },
           "flapping": {
             "$ref": "#/components/schemas/Flapping",
-            "description": "Flapping detection configuration."
+            "description": "Flapping detection configuration. When never set, the defaults are returned: enabled, 4 changes within 60 minutes, muted for 120 minutes."
           },
           "progress_to_incident_cnts": {
             "$ref": "#/components/schemas/IncProgressCnts",
-            "description": "Incident counts by progress over the last 30 days."
+            "description": "Counts of incidents started in the last 30 days that are still open, by progress. Not returned with `is_brief`."
           },
           "is_starred": {
             "type": "boolean",
-            "description": "Whether the current user has starred this channel. Present only in `POST /channel/list` responses."
+            "description": "Whether the caller has starred this channel. Returned only by `POST /channel/list`."
           },
           "active_incident_highest_severity": {
             "type": "string",
@@ -20615,11 +21468,11 @@
           },
           "external_report_token": {
             "type": "string",
-            "description": "Token granted to external reporters. Omitted unless external reporting is enabled on the channel."
+            "description": "Token external reporters use to file incidents into this channel. Returned only when external reporting is enabled."
           },
           "event_group": {
             "$ref": "#/components/schemas/EventGroup",
-            "description": "Alert event merge configuration."
+            "description": "Alert event merge configuration. When never set, merging is enabled with a 1,440-minute window."
           }
         }
       },
@@ -20638,7 +21491,7 @@
           "rule_id": {
             "type": "string",
             "pattern": "^[0-9a-fA-F]{24}$",
-            "description": "Rule ID (MongoDB ObjectID)."
+            "description": "Rule ID (24-character hex), as returned in `rule_id` by the create or list endpoint of the same rule type."
           }
         }
       },
@@ -20651,7 +21504,7 @@
           "channel_id": {
             "type": "integer",
             "format": "int64",
-            "description": "Channel to list rules for."
+            "description": "Channel whose rules to list; obtain it from `POST /channel/list`."
           }
         }
       },
@@ -20665,11 +21518,11 @@
           "channel_id": {
             "type": "integer",
             "format": "int64",
-            "description": "Channel ID."
+            "description": "Channel ID, one of the requested `channel_ids`."
           },
           "channel_name": {
             "type": "string",
-            "description": "Channel name."
+            "description": "Channel name, unique within the account."
           },
           "status": {
             "type": "string",
@@ -20678,7 +21531,7 @@
               "disabled",
               "deleted"
             ],
-            "description": "Channel status: `enabled` processes events normally; `disabled` discards incoming events; `deleted` is soft-deleted."
+            "description": "Channel status:\n- `enabled`: incoming alert events are processed.\n- `disabled`: incoming alert events are discarded.\n- `deleted`: the channel was deleted."
           }
         }
       },
@@ -20730,7 +21583,7 @@
           "team_id": {
             "type": "integer",
             "format": "int64",
-            "description": "Owning team ID; obtain it from `POST /team/list`."
+            "description": "Owning team ID; obtain it from `POST /team/list`. Required and must exist."
           },
           "managing_team_ids": {
             "type": "array",
@@ -20745,7 +21598,7 @@
             "type": "string",
             "minLength": 1,
             "maxLength": 59,
-            "description": "Channel name. 1 to 59 characters."
+            "description": "Channel name, 1–59 characters, unique within the account."
           },
           "description": {
             "type": "string",
@@ -20754,7 +21607,7 @@
           },
           "escalate_rule": {
             "type": "object",
-            "description": "Default escalation rule applied to the channel. Omit to skip default escalation.",
+            "description": "Creates an enabled escalation rule named `Default` with a single level that notifies `target` once. Omit to create the channel without escalation rules.",
             "required": [
               "template_id",
               "target"
@@ -20764,242 +21617,26 @@
                 "type": "integer",
                 "minimum": 0,
                 "maximum": 3600,
-                "description": "Delay window in seconds. 0 disables delay."
+                "description": "Delay in seconds, 0–3600, before the first notification for a newly assigned incident; `0` notifies immediately."
               },
               "template_id": {
                 "type": "string",
                 "pattern": "^[0-9a-fA-F]{24}$",
-                "description": "Notification template ID (MongoDB ObjectID)."
+                "description": "Notification template ID (24-character hex); obtain it from `POST /template/list`. Must exist."
               },
               "target": {
-                "type": "object",
-                "description": "Notification target. At least one of `person_ids`, `team_ids`, `schedule_to_role_ids`, or `emails` must be set, together with either `by` or `webhooks`.",
-                "properties": {
-                  "person_ids": {
-                    "type": "array",
-                    "items": {
-                      "type": "integer",
-                      "format": "int64"
-                    },
-                    "description": "Member IDs to notify directly; obtain member IDs from `POST /member/list`."
-                  },
-                  "team_ids": {
-                    "type": "array",
-                    "items": {
-                      "type": "integer",
-                      "format": "int64"
-                    },
-                    "description": "Team IDs to notify; obtain team IDs from `POST /team/list`."
-                  },
-                  "schedule_to_role_ids": {
-                    "type": "object",
-                    "additionalProperties": {
-                      "type": "array",
-                      "items": {
-                        "type": "integer",
-                        "format": "int64"
-                      }
-                    },
-                    "description": "Map of schedule ID to the role IDs on that schedule to notify."
-                  },
-                  "emails": {
-                    "type": "array",
-                    "items": {
-                      "type": "string",
-                      "format": "email"
-                    },
-                    "description": "Email addresses to notify (push-only scenarios)."
-                  },
-                  "by": {
-                    "type": "object",
-                    "description": "Per-severity personal notification channels. Required unless `webhooks` is provided.",
-                    "properties": {
-                      "follow_preference": {
-                        "type": "boolean",
-                        "description": "When true, use each responder's personal preference instead of the lists below."
-                      },
-                      "critical": {
-                        "type": "array",
-                        "items": {
-                          "type": "string"
-                        },
-                        "description": "Notify channels used for Critical severity. Personal channels: `sms`, `voice`, `email`, `push`; IM group-chat channels: `feishu_app:<chat_id>`, `dingtalk_app:<chat_id>`, `wecom_app:<chat_id>`, `slack_app:<chat_id>`, `teams_app:<chat_id>`."
-                      },
-                      "warning": {
-                        "type": "array",
-                        "items": {
-                          "type": "string"
-                        },
-                        "description": "Notify channels used for Warning severity. Values as for `critical`."
-                      },
-                      "info": {
-                        "type": "array",
-                        "items": {
-                          "type": "string"
-                        },
-                        "description": "Notify channels used for Info severity. Values as for `critical`."
-                      }
-                    }
-                  },
-                  "webhooks": {
-                    "type": "array",
-                    "description": "Group chat / webhook targets. Required unless `by` is provided.",
-                    "items": {
-                      "type": "object",
-                      "required": [
-                        "type",
-                        "settings"
-                      ],
-                      "properties": {
-                        "type": {
-                          "type": "string",
-                          "description": "Webhook type, one of `feishu`, `feishu_app`, `dingtalk`, `dingtalk_app`, `wecom`, `slack`, `slack_app`, `teams_app`, `telegram`, `zoom`."
-                        },
-                        "settings": {
-                          "type": "object",
-                          "additionalProperties": true,
-                          "description": "Type-specific settings (chat IDs, URLs, etc.)."
-                        }
-                      }
-                    }
-                  }
-                }
+                "$ref": "#/components/schemas/EscalateTarget",
+                "description": "Who to notify and through which channels."
               }
             }
           },
           "group": {
-            "type": "object",
-            "description": "Alert grouping configuration.",
-            "required": [
-              "method"
-            ],
-            "properties": {
-              "method": {
-                "type": "string",
-                "enum": [
-                  "i",
-                  "p",
-                  "n"
-                ],
-                "description": "Grouping method: `i` intelligent, `p` pattern, `n` none."
-              },
-              "equals": {
-                "type": "array",
-                "items": {
-                  "type": "array",
-                  "items": {
-                    "type": "string"
-                  }
-                },
-                "maxItems": 5,
-                "description": "Groups of label keys whose equality defines a bucket."
-              },
-              "cases": {
-                "type": "array",
-                "maxItems": 100,
-                "description": "Per-filter grouping overrides.",
-                "items": {
-                  "type": "object",
-                  "description": "Conditional grouping override: stored alerts matching `if` are grouped by `equals` instead of the top-level grouping keys.",
-                  "required": [
-                    "if",
-                    "equals"
-                  ],
-                  "properties": {
-                    "if": {
-                      "type": "array",
-                      "description": "AND-ed match conditions evaluated against stored alert fields.",
-                      "items": {
-                        "$ref": "#/components/schemas/FilterCondition"
-                      }
-                    },
-                    "equals": {
-                      "type": "array",
-                      "items": {
-                        "type": "string"
-                      },
-                      "minItems": 1,
-                      "maxItems": 5,
-                      "description": "Grouping keys for matching alerts. Supported values: `title`, `description`, `severity`, or any `labels.<name>`."
-                    }
-                  }
-                }
-              },
-              "all_equals_required": {
-                "type": "boolean",
-                "description": "When true, all listed keys must be present for grouping."
-              },
-              "time_window": {
-                "type": "integer",
-                "minimum": 0,
-                "description": "Grouping time window in minutes. Default max is 1440 minutes (24 h); extended accounts may allow up to 43200 minutes (30 days)."
-              },
-              "window_type": {
-                "type": "string",
-                "enum": [
-                  "tumbling",
-                  "sliding"
-                ],
-                "description": "Window type, default `tumbling`. `tumbling` is a fixed window counted from incident creation — once it expires, new alerts open a new incident; `sliding` is a sliding window counted from the incident's most recent alert, extended each time a new alert merges in."
-              },
-              "storm_threshold": {
-                "type": "integer",
-                "minimum": 0,
-                "maximum": 10000,
-                "description": "Alert storm threshold."
-              },
-              "storm_thresholds": {
-                "type": "array",
-                "items": {
-                  "type": "integer"
-                },
-                "maxItems": 5,
-                "description": "Multi-level storm thresholds."
-              },
-              "i_keys": {
-                "type": "array",
-                "items": {
-                  "type": "string"
-                },
-                "maxItems": 10,
-                "description": "Label keys used for intelligent grouping embeddings."
-              },
-              "i_score_threshold": {
-                "type": "number",
-                "format": "float",
-                "minimum": 0.5,
-                "maximum": 1,
-                "description": "Intelligent grouping similarity threshold."
-              }
-            }
+            "$ref": "#/components/schemas/Group",
+            "description": "Alert grouping configuration. Omit for no grouping (`method` `n`)."
           },
           "flapping": {
-            "type": "object",
-            "description": "Flapping detection configuration.",
-            "properties": {
-              "is_disabled": {
-                "type": "boolean",
-                "description": "Disable flapping detection."
-              },
-              "max_changes": {
-                "type": "integer",
-                "minimum": 2,
-                "maximum": 100,
-                "description": "Max state changes allowed within `in_mins`."
-              },
-              "in_mins": {
-                "type": "integer",
-                "minimum": 1,
-                "maximum": 1440,
-                "description": "Observation window in minutes."
-              },
-              "mute_mins": {
-                "type": "integer",
-                "minimum": 0,
-                "maximum": 1440,
-                "description": "Mute duration in minutes after flapping is detected."
-              }
-            }
+            "$ref": "#/components/schemas/Flapping",
+            "description": "Flapping detection configuration. Omit to use the defaults."
           },
           "auto_resolve_timeout": {
             "type": "integer",
@@ -21014,7 +21651,7 @@
               "trigger",
               "update"
             ],
-            "description": "Auto-resolve timing mode: `trigger` starts the timer when the incident triggers, `update` restarts it on every alert update."
+            "description": "How the auto-resolve timer runs. `trigger` (default) starts the timer once when the incident is triggered; `update` restarts it whenever a new alert merges into the incident."
           },
           "plugin_ids": {
             "type": "array",
@@ -21022,7 +21659,7 @@
               "type": "integer",
               "format": "int64"
             },
-            "description": "IDs of plugins (integrations) subscribed to this channel."
+            "description": "Integration type IDs (the `plugin_id` shown on integrations returned by `POST /integration/list`). For each ID, a channel-exclusive integration of that type is created, named after the type. An unknown ID returns `InvalidParameter`."
           },
           "is_private": {
             "type": "boolean",
@@ -21038,7 +21675,7 @@
           },
           "is_external_report_enabled": {
             "type": "boolean",
-            "description": "Allow external reporters to file incidents into this channel."
+            "description": "When true, external reporters can file incidents into this channel, and the response carries the generated `external_report_token`."
           },
           "event_group": {
             "$ref": "#/components/schemas/EventGroup",
@@ -21071,40 +21708,8 @@
             "description": "Rule description, up to 500 characters."
           },
           "filters": {
-            "type": "array",
-            "description": "Alert event match conditions (OR-of-AND); matching events are discarded entirely — no alert, incident, or notification is produced. When omitted or empty, the rule matches nothing.",
-            "items": {
-              "type": "array",
-              "items": {
-                "type": "object",
-                "required": [
-                  "key",
-                  "oper",
-                  "vals"
-                ],
-                "properties": {
-                  "key": {
-                    "type": "string",
-                    "description": "Field key (e.g. `alert_severity`, `labels.service`)."
-                  },
-                  "oper": {
-                    "type": "string",
-                    "enum": [
-                      "IN",
-                      "NOTIN"
-                    ],
-                    "description": "Filter operator."
-                  },
-                  "vals": {
-                    "type": "array",
-                    "items": {
-                      "type": "string"
-                    },
-                    "description": "Values to match."
-                  }
-                }
-              }
-            }
+            "$ref": "#/components/schemas/FilterGroup",
+            "description": "Alert event conditions (OR of AND groups). A matching event is discarded entirely: no alert, incident or notification. Keys: `title`, `description`, `severity` (alias `alert_severity`, `event_severity`), `status`, `alert_key`, `title_rule`, `integration_id` (alias `data_source_id`), or any `labels.<name>`. When omitted or empty, the rule matches nothing."
           }
         }
       },
@@ -21130,18 +21735,18 @@
             ],
             "minimum": 0,
             "maximum": 200,
-            "description": "Evaluation priority. Lower runs first."
+            "description": "Evaluation order from `0` to `200`; lower values are evaluated first. Omit to place the rule after all existing rules (current highest priority + 1)."
           },
           "aggr_window": {
             "type": "integer",
             "minimum": 0,
             "maximum": 3600,
-            "description": "Delay window in seconds. 0 disables delay."
+            "description": "Delay in seconds, 0–3600, before the first notification for a newly assigned incident; `0` notifies immediately."
           },
           "template_id": {
             "type": "string",
             "pattern": "^[0-9a-fA-F]{24}$",
-            "description": "Notification template ID (MongoDB ObjectID)."
+            "description": "Notification template ID (24-character hex); obtain it from `POST /template/list`. Must exist."
           },
           "rule_name": {
             "type": "string",
@@ -21156,201 +21761,21 @@
           },
           "layers": {
             "type": "array",
-            "description": "Escalation levels in order. At least one level is required.",
             "items": {
-              "type": "object",
-              "required": [
-                "target"
-              ],
-              "properties": {
-                "max_times": {
-                  "type": "integer",
-                  "minimum": 0,
-                  "maximum": 6,
-                  "description": "Max repeat notifications within the level."
-                },
-                "notify_step": {
-                  "type": "number",
-                  "format": "float",
-                  "minimum": 0.5,
-                  "maximum": 120,
-                  "description": "Repeat interval in minutes."
-                },
-                "target": {
-                  "type": "object",
-                  "description": "Notification target. At least one of `person_ids`, `team_ids`, `schedule_to_role_ids`, or `emails` must be set, together with either `by` or `webhooks`.",
-                  "properties": {
-                    "person_ids": {
-                      "type": "array",
-                      "items": {
-                        "type": "integer",
-                        "format": "int64"
-                      },
-                      "description": "Member IDs to notify directly; obtain member IDs from `POST /member/list`."
-                    },
-                    "team_ids": {
-                      "type": "array",
-                      "items": {
-                        "type": "integer",
-                        "format": "int64"
-                      },
-                      "description": "Team IDs to notify; obtain team IDs from `POST /team/list`."
-                    },
-                    "schedule_to_role_ids": {
-                      "type": "object",
-                      "additionalProperties": {
-                        "type": "array",
-                        "items": {
-                          "type": "integer",
-                          "format": "int64"
-                        }
-                      },
-                      "description": "Map of schedule ID to the role IDs on that schedule to notify."
-                    },
-                    "emails": {
-                      "type": "array",
-                      "items": {
-                        "type": "string",
-                        "format": "email"
-                      },
-                      "description": "Email addresses to notify (push-only scenarios)."
-                    },
-                    "by": {
-                      "type": "object",
-                      "description": "Per-severity personal notification channels. Required unless `webhooks` is provided.",
-                      "properties": {
-                        "follow_preference": {
-                          "type": "boolean",
-                          "description": "When true, use each responder's personal preference instead of the lists below."
-                        },
-                        "critical": {
-                          "type": "array",
-                          "items": {
-                            "type": "string"
-                          },
-                          "description": "Notify channels used for Critical severity. Personal channels: `sms`, `voice`, `email`, `push`; IM group-chat channels: `feishu_app:<chat_id>`, `dingtalk_app:<chat_id>`, `wecom_app:<chat_id>`, `slack_app:<chat_id>`, `teams_app:<chat_id>`."
-                        },
-                        "warning": {
-                          "type": "array",
-                          "items": {
-                            "type": "string"
-                          },
-                          "description": "Notify channels used for Warning severity. Values as for `critical`."
-                        },
-                        "info": {
-                          "type": "array",
-                          "items": {
-                            "type": "string"
-                          },
-                          "description": "Notify channels used for Info severity. Values as for `critical`."
-                        }
-                      }
-                    },
-                    "webhooks": {
-                      "type": "array",
-                      "description": "Group chat / webhook targets. Required unless `by` is provided.",
-                      "items": {
-                        "type": "object",
-                        "required": [
-                          "type",
-                          "settings"
-                        ],
-                        "properties": {
-                          "type": {
-                            "type": "string",
-                            "description": "Webhook type, one of `feishu`, `feishu_app`, `dingtalk`, `dingtalk_app`, `wecom`, `slack`, `slack_app`, `teams_app`, `telegram`, `zoom`."
-                          },
-                          "settings": {
-                            "type": "object",
-                            "additionalProperties": true,
-                            "description": "Type-specific settings (chat IDs, URLs, etc.)."
-                          }
-                        }
-                      }
-                    }
-                  }
-                },
-                "escalate_window": {
-                  "type": "integer",
-                  "minimum": 0,
-                  "maximum": 720,
-                  "description": "Wait before moving to the next level, in minutes."
-                },
-                "force_escalate": {
-                  "type": "boolean",
-                  "description": "When true, always escalate regardless of acknowledgement."
-                }
-              }
-            }
+              "$ref": "#/components/schemas/EscalateLayer"
+            },
+            "description": "Escalation levels in order; the incident starts at the first level."
           },
           "time_filters": {
             "type": "array",
             "items": {
-              "type": "object",
-              "description": "Recurring time window. `start`/`end` use 24-hour `HH:MM` format; `repeat` uses ISO-style weekday indices (0=Sunday … 6=Saturday).",
-              "properties": {
-                "start": {
-                  "type": "string",
-                  "description": "Start of the window in `HH:MM`."
-                },
-                "end": {
-                  "type": "string",
-                  "description": "End of the window in `HH:MM`."
-                },
-                "repeat": {
-                  "type": "array",
-                  "items": {
-                    "type": "integer"
-                  },
-                  "description": "Days of the week this window repeats on. Empty means every day."
-                },
-                "cal_id": {
-                  "type": "string",
-                  "description": "Optional calendar ID; restricts the window to days matching the calendar."
-                },
-                "is_off": {
-                  "type": "boolean",
-                  "description": "When true, match days marked as days-off in the calendar."
-                }
-              }
+              "$ref": "#/components/schemas/TimeFilter"
             },
-            "description": "Optional recurring time windows during which the rule applies."
+            "description": "Recurring time windows during which the rule can match; omit or leave empty to match at any time."
           },
           "filters": {
-            "type": "array",
-            "description": "Incident-level match conditions (OR-of-AND tree): the rule is matched against the incident the alert was grouped into, not against the alert itself. Omit or leave empty to apply the rule to all incidents in the channel.",
-            "items": {
-              "type": "array",
-              "items": {
-                "type": "object",
-                "required": [
-                  "key",
-                  "oper",
-                  "vals"
-                ],
-                "properties": {
-                  "key": {
-                    "type": "string",
-                    "description": "Field key (e.g. `alert_severity`, `labels.service`)."
-                  },
-                  "oper": {
-                    "type": "string",
-                    "enum": [
-                      "IN",
-                      "NOTIN"
-                    ],
-                    "description": "Filter operator."
-                  },
-                  "vals": {
-                    "type": "array",
-                    "items": {
-                      "type": "string"
-                    },
-                    "description": "Values to match."
-                  }
-                }
-              }
-            }
+            "$ref": "#/components/schemas/FilterGroup",
+            "description": "Incident conditions (OR of AND groups), matched against the incident the alert was grouped into, not against the alert. Keys: `title`, `description`, `severity` (alias `incident_severity`, `alert_severity`), `status` (alias `incident_status`, `alert_status`), `dedup_key`, `integration_id` (alias `data_source_id`), or any `labels.<name>`. Omit or leave empty to match every incident in the channel."
           }
         }
       },
@@ -21373,7 +21798,7 @@
           "title": {
             "type": "string",
             "maxLength": 512,
-            "description": "Incident title, up to 512 characters."
+            "description": "Incident title, up to 512 characters. Required (non-blank) when the account has a create form."
           },
           "description": {
             "type": "string",
@@ -21383,11 +21808,11 @@
           "channel_id": {
             "type": "integer",
             "format": "int64",
-            "description": "Channel to file the incident into. Optional; leave unset for a standalone incident."
+            "description": "Channel to file the incident into; must exist in the account. Optional unless the account has a create form; leave it unset for a standalone incident."
           },
           "assigned_to": {
             "type": "object",
-            "description": "Incident assignment target. May be omitted entirely: when unset or empty, the channel's default assignment applies; required when the account's create form is in effect. `person_ids`, `escalate_rule_id`, and `emails` can be combined — responders are the union.",
+            "description": "Who to assign. When omitted or empty, the channel's escalation rules decide (a standalone incident gets no responders); required when the account has a create form. `person_ids`, `escalate_rule_id` and `emails` can be combined — responders are the union. Assignment runs after creation, and its failure does not undo the incident.",
             "properties": {
               "person_ids": {
                 "type": "array",
@@ -21406,7 +21831,7 @@
               },
               "layer_idx": {
                 "type": "integer",
-                "description": "Zero-based starting layer index of the escalation rule (default 0, the first layer); an out-of-range value returns an error. Only takes effect with `escalate_rule_id`."
+                "description": "Zero-based escalation-rule layer to assign (default 0, the first layer). Used only with `escalate_rule_id`; an out-of-range value leaves the incident without responders instead of failing the request."
               },
               "type": {
                 "type": "string",
@@ -21416,7 +21841,7 @@
                   "escalate",
                   "reopen"
                 ],
-                "description": "Assignment type, derived server-side — callers do not set it: `assign` for manual creation, `reassign` for re-assignment, `escalate` for escalation-driven assignment.\n| Value | Meaning |\n|---|---|\n| `assign` | Initial assignment when the incident is created manually. |\n| `reassign` | Re-assignment of an existing incident. |\n| `escalate` | Assignment triggered by escalation policy advancement. |\n| `reopen` | Assignment restarted from the first layer after the incident is reopened. |"
+                "description": "Assignment type. Normally omitted: the server then sets `assign`, because a manual create is always a first assignment. A value you send is stored as-is.\n- `assign`: first assignment of the incident.\n- `reassign`: assignment replacing an earlier one.\n- `escalate`: assignment triggered by escalation to the next layer.\n- `reopen`: assignment restarted from the first layer after the incident is reopened."
               },
               "emails": {
                 "type": "array",
@@ -21444,7 +21869,7 @@
                     "items": {
                       "type": "string"
                     },
-                    "description": "Channels to use (e.g. `voice`, `sms`, `email`)."
+                    "description": "Channels to use when `follow_preference` is false: `sms`, `voice`, `email`, `push`, or an IM app channel prefixed `feishu_app:`, `dingtalk_app:`, `wecom_app:`, `slack_app:` or `teams_app:`."
                   },
                   "template_id": {
                     "type": "string",
@@ -21476,7 +21901,7 @@
           },
           "title": {
             "type": "string",
-            "description": "Echoes the incident title from the request."
+            "description": "Incident title as sent in the request; empty when the request had no title."
           }
         }
       },
@@ -21510,79 +21935,15 @@
             "items": {
               "type": "string"
             },
-            "description": "Field keys whose values must be equal between the source (inhibiting) alert and the target (suppressed) alert, e.g. `data_source_id` or `labels.cluster`."
+            "description": "Keys whose values must be equal on the source alert and the incoming event. Only `title`, `severity` and `labels.<name>` take effect; any other key (for example `data_source_id`) is accepted but makes the rule never fire. Must be present; an empty array also makes the rule inert."
           },
           "source_filters": {
-            "type": "array",
-            "description": "Conditions the source alert must match, evaluated against stored active alerts. Supported keys: `status`, `incident_status`, `alert_status`, `severity`, `incident_severity`, `alert_severity`, `title`, `description`, or any `labels.<name>`. Empty makes the rule inert.",
-            "items": {
-              "type": "array",
-              "items": {
-                "type": "object",
-                "required": [
-                  "key",
-                  "oper",
-                  "vals"
-                ],
-                "properties": {
-                  "key": {
-                    "type": "string",
-                    "description": "Field key (e.g. `alert_severity`, `labels.service`)."
-                  },
-                  "oper": {
-                    "type": "string",
-                    "enum": [
-                      "IN",
-                      "NOTIN"
-                    ],
-                    "description": "Filter operator."
-                  },
-                  "vals": {
-                    "type": "array",
-                    "items": {
-                      "type": "string"
-                    },
-                    "description": "Values to match."
-                  }
-                }
-              }
-            }
+            "$ref": "#/components/schemas/FilterGroup",
+            "description": "Conditions the source (inhibiting) alert must match, evaluated against active alerts already stored in the channel. Keys: `title`, `description`, `severity` (alias `incident_severity`, `alert_severity`), `status` (alias `incident_status`, `alert_status`), or any `labels.<name>`. Empty makes the rule inert."
           },
           "target_filters": {
-            "type": "array",
-            "description": "Conditions the incoming target alert event must match to be suppressed; empty means every event is a target.",
-            "items": {
-              "type": "array",
-              "items": {
-                "type": "object",
-                "required": [
-                  "key",
-                  "oper",
-                  "vals"
-                ],
-                "properties": {
-                  "key": {
-                    "type": "string",
-                    "description": "Field key (e.g. `alert_severity`, `labels.service`)."
-                  },
-                  "oper": {
-                    "type": "string",
-                    "enum": [
-                      "IN",
-                      "NOTIN"
-                    ],
-                    "description": "Filter operator."
-                  },
-                  "vals": {
-                    "type": "array",
-                    "items": {
-                      "type": "string"
-                    },
-                    "description": "Values to match."
-                  }
-                }
-              }
-            }
+            "$ref": "#/components/schemas/FilterGroup",
+            "description": "Conditions the incoming target alert event must match to be inhibited; empty means every incoming event is a target. Keys: `title`, `description`, `severity` (alias `alert_severity`, `event_severity`), `status`, `alert_key`, `title_rule`, `integration_id` (alias `data_source_id`), or any `labels.<name>`."
           },
           "is_directly_discard": {
             "type": "boolean",
@@ -21616,99 +21977,23 @@
           },
           "from_incident_id": {
             "type": "string",
-            "description": "Incident ID (ObjectID hex) to attach the rule to. Optional; when set, only one enabled silence rule may exist per incident.",
+            "description": "ID of the incident this rule is created from (24-character hex). The incident must exist, and only one enabled silence rule may exist per incident.",
             "pattern": "^[0-9a-fA-F]{24}$"
           },
           "time_filters": {
             "type": "array",
             "items": {
-              "type": "object",
-              "description": "Recurring time window. `start`/`end` use 24-hour `HH:MM` format; `repeat` uses ISO-style weekday indices (0=Sunday … 6=Saturday).",
-              "properties": {
-                "start": {
-                  "type": "string",
-                  "description": "Start of the window in `HH:MM`."
-                },
-                "end": {
-                  "type": "string",
-                  "description": "End of the window in `HH:MM`."
-                },
-                "repeat": {
-                  "type": "array",
-                  "items": {
-                    "type": "integer"
-                  },
-                  "description": "Days of the week this window repeats on. Empty means every day."
-                },
-                "cal_id": {
-                  "type": "string",
-                  "description": "Optional calendar ID; restricts the window to days matching the calendar."
-                },
-                "is_off": {
-                  "type": "boolean",
-                  "description": "When true, match days marked as days-off in the calendar."
-                }
-              }
+              "$ref": "#/components/schemas/TimeFilter"
             },
-            "description": "Recurring time windows during which silencing applies. Mutually exclusive with `time_filter`."
+            "description": "Recurring silence windows. Set exactly one of `time_filters` or `time_filter`."
           },
           "time_filter": {
-            "type": "object",
-            "description": "One-off time window defined by unix seconds.",
-            "required": [
-              "start_time",
-              "end_time"
-            ],
-            "properties": {
-              "start_time": {
-                "type": "integer",
-                "format": "int64",
-                "description": "Window start, Unix timestamp in seconds. Must be greater than 0 and less than `end_time`.",
-                "exclusiveMinimum": 0
-              },
-              "end_time": {
-                "type": "integer",
-                "format": "int64",
-                "description": "Window end, Unix timestamp in seconds. Must be greater than 0.",
-                "exclusiveMinimum": 0
-              }
-            }
+            "$ref": "#/components/schemas/OnceTimeFilter",
+            "description": "One-off silence window. Set exactly one of `time_filter` or `time_filters`."
           },
           "filters": {
-            "type": "array",
-            "description": "Alert event match conditions (OR-of-AND). Required and must contain at least one condition.",
-            "items": {
-              "type": "array",
-              "items": {
-                "type": "object",
-                "required": [
-                  "key",
-                  "oper",
-                  "vals"
-                ],
-                "properties": {
-                  "key": {
-                    "type": "string",
-                    "description": "Field key (e.g. `alert_severity`, `labels.service`)."
-                  },
-                  "oper": {
-                    "type": "string",
-                    "enum": [
-                      "IN",
-                      "NOTIN"
-                    ],
-                    "description": "Filter operator."
-                  },
-                  "vals": {
-                    "type": "array",
-                    "items": {
-                      "type": "string"
-                    },
-                    "description": "Values to match."
-                  }
-                }
-              }
-            }
+            "$ref": "#/components/schemas/FilterGroup",
+            "description": "Alert event conditions (OR of AND groups); matching events are silenced while the time window is active. Required, with at least one condition. Keys: `title`, `description`, `severity` (alias `alert_severity`, `event_severity`), `status`, `alert_key`, `title_rule`, `integration_id` (alias `data_source_id`), or any `labels.<name>`."
           },
           "is_directly_discard": {
             "type": "boolean",
@@ -21716,7 +22001,7 @@
           },
           "is_auto_delete": {
             "type": "boolean",
-            "description": "When true, the silence rule is automatically deleted after its time window expires. Defaults to false."
+            "description": "When true, a rule with a one-off `time_filter` is permanently removed about 24 hours after `end_time` (or after its last update, whichever is later). Rules created with `from_incident_id` are cleaned up the same way. Rules with recurring `time_filters` are never removed automatically. Defaults to `false`."
           }
         }
       },
@@ -21770,7 +22055,7 @@
           "start_at_seconds": {
             "type": "integer",
             "format": "int64",
-            "description": "Event start time in Unix seconds. The stored start time is always derived from the first update's `at_seconds` (which defaults to the current time when omitted); for maintenances with `auto_update_by_schedule`, this value schedules the automatic transition to `ongoing`."
+            "description": "Event start time in Unix seconds. Maintenances store this value as the scheduled start (with `auto_update_by_schedule`, the time the event switches to `ongoing`); when it is omitted or 0, and always for incidents, the start time is the first update's `at_seconds`."
           },
           "responders": {
             "type": "array",
@@ -21790,7 +22075,7 @@
           "close_at_seconds": {
             "type": "integer",
             "format": "int64",
-            "description": "Event close time in Unix seconds. Must be greater than or equal to the first update's `at_seconds`. For retrospective events this is the time the event ended; for maintenances with `auto_update_by_schedule` it schedules the automatic transition to `completed` and must be within 30 days from now."
+            "description": "Event close time in Unix seconds; must be greater than or equal to the first update's `at_seconds`. For maintenances this is the scheduled end; with `auto_update_by_schedule` the event switches to `completed` at this time, which must be within 30 days from now. For a retrospective event in a terminal status, omitting it uses the latest update's time."
           },
           "updates": {
             "type": "array",
@@ -21860,12 +22145,12 @@
                 }
               }
             },
-            "description": "Timeline updates. At least one update is required, and at least one of them must contain `component_changes`. Immediate events normally pass one update; retrospective events must pass all historical updates.",
+            "description": "Timeline updates in non-decreasing `at_seconds` order. At least one update is required, and at least one of them must contain `component_changes`. Immediate events normally pass one update; retrospective events must pass at least 2.",
             "minItems": 1
           },
           "notify_subscribers": {
             "type": "boolean",
-            "description": "Notify subscribers about this event and all its updates."
+            "description": "Notify subscribers about this event. On creation one notification is sent for the last update; later timeline entries also notify while this is `true`."
           },
           "auto_update_by_schedule": {
             "type": "boolean",
@@ -21873,7 +22158,11 @@
           },
           "is_retrospective": {
             "type": "boolean",
-            "description": "Mark this event as a retrospective (historical) one."
+            "description": "Mark the event as retrospective (a past event recorded afterwards). Requires at least 2 entries in `updates`."
+          },
+          "draft_id": {
+            "type": "string",
+            "description": "ID of a draft created by `POST /status-page/draft/create` to publish with this event. The draft must be pending, target this `page_id` and `type`, and have no `change_id`; it is marked published once the event is created. Omit when not publishing a draft."
           }
         }
       },
@@ -21900,7 +22189,7 @@
           "at_seconds": {
             "type": "integer",
             "format": "int64",
-            "description": "Update timestamp in Unix seconds. Defaults to the current time when omitted or 0."
+            "description": "Update time in Unix seconds; must not be earlier than the event's latest timeline entry. Defaults to the current time when omitted or 0."
           },
           "status": {
             "type": "string",
@@ -21913,7 +22202,7 @@
               "ongoing",
               "completed"
             ],
-            "description": "Change status after this update; must be valid for the change type. When transitioning to `resolved` or `completed`, all affected components must be back to `operational`.\n| Value | Meaning |\n|---|---|\n| `investigating` | Investigating (incident). |\n| `identified` | Root cause identified (incident). |\n| `monitoring` | Fix deployed, monitoring (incident). |\n| `resolved` | Resolved (incident). |\n| `scheduled` | Scheduled (maintenance). |\n| `ongoing` | In progress (maintenance). |\n| `completed` | Completed (maintenance). |"
+            "description": "Event status after this update; must be valid for the event type. Pass the current status to post an update without a status change. When moving to `resolved` or `completed`, all affected components must be back to `operational`.\n| Value | Meaning |\n|---|---|\n| `investigating` | Investigating (incident). |\n| `identified` | Root cause identified (incident). |\n| `monitoring` | Fix deployed, monitoring (incident). |\n| `resolved` | Resolved (incident). |\n| `scheduled` | Scheduled (maintenance). |\n| `ongoing` | In progress (maintenance). |\n| `completed` | Completed (maintenance). |"
           },
           "description": {
             "type": "string",
@@ -21946,6 +22235,10 @@
               }
             },
             "description": "Component status transitions applied by this update. Component IDs must be unique."
+          },
+          "draft_id": {
+            "type": "string",
+            "description": "ID of a pending draft created by `POST /status-page/draft/create` whose `change_id` is this event; it is marked published when the update is stored. Omit when not publishing a draft."
           }
         }
       },
@@ -21958,12 +22251,110 @@
         "properties": {
           "draft": {
             "type": "object",
-            "description": "Draft payload, stored verbatim, up to 64 KB serialized. Validated fields: `page_id`, `type` (`incident` or `maintenance`), `name`, `message`; optional `change_id` (append an update to an existing event when > 0), `status`, `affected_components`, and `start_time`/`end_time` (Unix epoch seconds, new maintenance only)."
+            "description": "Draft payload, stored verbatim (at most 64 KB serialized). The server validates the fields below and keeps any other fields unchanged for the console.",
+            "required": [
+              "page_id",
+              "type",
+              "name",
+              "message"
+            ],
+            "additionalProperties": true,
+            "properties": {
+              "v": {
+                "type": "integer",
+                "description": "Payload format version chosen by the producer; stored, not interpreted."
+              },
+              "page_id": {
+                "type": "integer",
+                "format": "int64",
+                "description": "Target status page ID; must belong to the caller's account."
+              },
+              "page_name": {
+                "type": "string",
+                "description": "Page name for display in the console; not validated."
+              },
+              "type": {
+                "type": "string",
+                "enum": [
+                  "incident",
+                  "maintenance"
+                ],
+                "description": "Event type the draft creates or updates: `incident` unplanned incident, `maintenance` planned maintenance."
+              },
+              "name": {
+                "type": "string",
+                "maxLength": 255,
+                "description": "Event title, 1 to 255 characters."
+              },
+              "message": {
+                "type": "string",
+                "description": "Event or update description (Markdown). Must not be empty."
+              },
+              "change_id": {
+                "type": "integer",
+                "format": "int64",
+                "description": "Event to append an update to; it must be an event of the same `type` on `page_id`. Omit or pass 0 to draft a new event."
+              },
+              "status": {
+                "type": "string",
+                "enum": [
+                  "investigating",
+                  "identified",
+                  "monitoring",
+                  "resolved",
+                  "scheduled",
+                  "ongoing",
+                  "completed"
+                ],
+                "description": "Proposed event status; when set, it must be valid for `type` (`investigating`/`identified`/`monitoring`/`resolved` for incidents, `scheduled`/`ongoing`/`completed` for maintenances)."
+              },
+              "affected_components": {
+                "type": "array",
+                "description": "Components the draft affects.",
+                "items": {
+                  "type": "object",
+                  "required": [
+                    "component_id"
+                  ],
+                  "properties": {
+                    "component_id": {
+                      "type": "string",
+                      "description": "Component ID; must exist on the page."
+                    },
+                    "name": {
+                      "type": "string",
+                      "description": "Component name for display; not validated."
+                    },
+                    "status": {
+                      "type": "string",
+                      "enum": [
+                        "operational",
+                        "degraded",
+                        "partial_outage",
+                        "full_outage",
+                        "under_maintenance"
+                      ],
+                      "description": "Proposed component status; when set, it must be valid for `type` (`operational`/`degraded`/`partial_outage`/`full_outage` for incidents, `operational`/`under_maintenance` for maintenances)."
+                    }
+                  }
+                }
+              },
+              "start_time": {
+                "type": "integer",
+                "format": "int64",
+                "description": "Scheduled start in Unix seconds, for a new maintenance."
+              },
+              "end_time": {
+                "type": "integer",
+                "format": "int64",
+                "description": "Scheduled end in Unix seconds, for a new maintenance; must be greater than `start_time` when both are set."
+              }
+            }
           },
           "source": {
             "type": "string",
             "maxLength": 64,
-            "description": "Opaque marker of the drafting origin, e.g. `ai_sre:sess_xxx`. Up to 64 characters."
+            "description": "Free-form text recording where the draft came from, such as an AI session reference; stored and shown with the draft, not interpreted. Up to 64 characters."
           }
         }
       },
@@ -21983,7 +22374,7 @@
           "integration_id": {
             "type": "integer",
             "format": "int64",
-            "description": "IM integration ID. Must have war room enabled; Feishu, DingTalk, WeCom (self-built), Slack and Teams are supported."
+            "description": "IM integration ID with war room enabled; obtain it from `POST /datasource/im/war-room-enabled/list`. Feishu, DingTalk, WeCom (self-built app only), and Slack are supported."
           },
           "member_ids": {
             "type": "array",
@@ -21991,11 +22382,11 @@
               "type": "integer",
               "format": "int64"
             },
-            "description": "Additional member IDs to add to the war room."
+            "description": "Member IDs to invite into the group; every ID must be a valid member of the account."
           },
           "add_observers": {
             "type": "boolean",
-            "description": "When true, also add historical responders of the incident as observers."
+            "description": "When true, also invite members who were assigned or added as responders earlier but are no longer current responders."
           }
         }
       },
@@ -22074,6 +22465,14 @@
             "type": "integer",
             "format": "int64",
             "description": "IM integration ID; obtain it from `POST /datasource/im/war-room-enabled/list`."
+          },
+          "unlink_only": {
+            "type": "boolean",
+            "description": "When true, only remove the link between the incident and the war room without dissolving the group. Allowed only for account owners and admins, only when the IM integration is disabled or deleted, and requires `chat_id`."
+          },
+          "chat_id": {
+            "type": "string",
+            "description": "Chat ID of the war room to unlink, from `POST /incident/war-room/list`. Required when `unlink_only` is `true` and must match the current war room; ignored otherwise."
           }
         }
       },
@@ -22203,7 +22602,7 @@
             "items": {
               "$ref": "#/components/schemas/DimensionInsightItem"
             },
-            "description": "Insight metric rows aggregated by the endpoint's dimension (account/team/channel); further split by hour bucket or time bucket when `split_hours` or `aggregate_unit` is enabled."
+            "description": "Metric rows, newest bucket first. Buckets or dimension values without incidents produce no row; an empty array means no incidents matched."
           }
         }
       },
@@ -22246,12 +22645,15 @@
         }
       },
       "DoIncidentCustomActionResponse": {
-        "type": "object",
-        "description": "Result of a custom action dispatch.",
+        "type": [
+          "object",
+          "null"
+        ],
+        "description": "`null` when the action's HTTP request succeeded; an object with `message` when it failed.",
         "properties": {
           "message": {
             "type": "string",
-            "description": "Error message if the action's HTTP call failed; omitted on success."
+            "description": "Error returned by the HTTP request to the action's URL (for example, a timeout after 2 seconds)."
           }
         }
       },
@@ -22264,7 +22666,7 @@
           },
           "message": {
             "type": "string",
-            "description": "Human-readable error message, localized by the caller's Accept-Language. May contain field names, IDs, or other context from the failing request.",
+            "description": "Human-readable error message in the response language (`locale` / `lang` query parameter or `Accept-Language` header). May name the offending field; do not parse it.",
             "example": "The specified parameter template_id is not valid."
           }
         },
@@ -22285,7 +22687,7 @@
       },
       "EmptyResponse": {
         "type": "object",
-        "description": "Empty response body. The server returns `data: null` on success.",
+        "description": "No payload. Depending on the operation, `data` is `{}` or omitted from the envelope; rely only on the HTTP 200 status and the absence of `error`.",
         "properties": {}
       },
       "EnrichFilter": {
@@ -22299,7 +22701,7 @@
         "properties": {
           "key": {
             "type": "string",
-            "description": "Event key to match on (e.g. `labels.severity`, `title`). Must be non-empty.",
+            "description": "Event key to match on: `title`, `description`, `labels.<name>` or another alert/change event key. A `labels.<name>` key must use a valid label name.",
             "minLength": 1
           },
           "oper": {
@@ -22308,14 +22710,14 @@
               "IN",
               "NOTIN"
             ],
-            "description": "Match operator. `IN` matches when any value matches; `NOTIN` matches when none of the values match."
+            "description": "Match operator.\n- `IN`: matches when the key's value matches any of `vals`. A key missing from the event never matches.\n- `NOTIN`: matches when the value matches none of `vals`. A key missing from the event always matches."
           },
           "vals": {
             "type": "array",
             "items": {
               "type": "string"
             },
-            "description": "Values to match against. Must contain at least one value.",
+            "description": "Values to match (at least one). Each value is one of: an exact string; `/regex/` for a regular expression; a wildcard pattern with `*` and `?`; `cidr:<CIDR>` (e.g. `cidr:203.0.113.0/24`) for an IP range; `num:lt:<n>`, `num:le:<n>`, `num:gt:<n>` or `num:ge:<n>` for a numeric comparison.",
             "minItems": 1
           }
         }
@@ -22397,14 +22799,14 @@
           "integration_id": {
             "type": "integer",
             "format": "int64",
-            "description": "Integration ID."
+            "description": "ID of the integration this rule set belongs to; one integration has at most one rule set."
           },
           "rules": {
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/EnrichRule"
             },
-            "description": "Ordered enrichment rules."
+            "description": "Rules in execution order; each rule sees the labels written by the rules before it."
           },
           "status": {
             "type": "string",
@@ -22499,13 +22901,13 @@
             "items": {
               "$ref": "#/components/schemas/EnrichRule"
             },
-            "description": "Ordered list of enrichment rules. Replaces all existing rules."
+            "description": "Ordered rule list that replaces the integration's whole rule set; send `[]` to remove all rules. Rules run in this order."
           }
         }
       },
       "ErrorCode": {
         "type": "string",
-        "description": "Flashduty error code enum. Every failed API response sets `error.code` to one of these stable wire strings. HTTP status is informational — the authoritative signal is the enum value.\n\n| Code | HTTP | Meaning |\n|---|---|---|\n| `OK` | 200 | Reserved — not returned on real errors. |\n| `InvalidParameter` | 400 | A required parameter is missing or failed validation. |\n| `BadRequest` | 400 | Generic 400 used when no more specific code fits. |\n| `InvalidContentType` | 400 | The `Content-Type` header is not `application/json`. |\n| `ResourceNotFound` | 400 | The referenced resource does not exist. Note: returned as HTTP 400, not 404 (historical choice). |\n| `NoLicense` | 400 | The feature is license-gated and no active license was found. |\n| `ReferenceExist` | 400 | Deletion blocked — other entities still reference this resource. |\n| `Unauthorized` | 401 | `app_key` is missing, invalid, or expired. |\n| `BalanceNotEnough` | 402 | Billing-gated operation with insufficient account balance. |\n| `AccessDenied` | 403 | Authenticated but lacking the permission required for this operation. |\n| `RouteNotFound` | 404 | The request URL path is not a known route. |\n| `MethodNotAllowed` | 405 | The HTTP method is not allowed on this otherwise-known path. |\n| `UndonedOrderExist` | 409 | An outstanding billing order blocks this new one. Wait and retry. |\n| `RequestLocked` | 423 | Operation temporarily locked due to repeated failures. |\n| `EntityTooLarge` | 413 | Request body exceeds the configured max size. |\n| `RequestTooFrequently` | 429 | Rate limit hit — API-global, per-account, or per-integration. |\n| `RequestVerifyRequired` | 428 | Second-factor verification required but not supplied. |\n| `DangerousOperation` | 428 | High-risk operation requires MFA verification. |\n| `InternalError` | 500 | Unhandled server-side error. Include `request_id` in the bug report. |\n| `ServiceUnavailable` | 503 | A backend dependency is unavailable. Try again later. |",
+        "description": "Error code. Every failed response sets `error.code` to one of these stable strings; branch on it rather than on the HTTP status.\n\n| Code | HTTP | Meaning |\n|---|---|---|\n| `OK` | 200 | Reserved; never returned on a failed request. |\n| `InvalidParameter` | 400 | A parameter is missing, has the wrong type, or failed validation; `message` usually names the field. |\n| `BadRequest` | 400 | The request breaks a business rule or conflicts with the current state of an object; `message` says which. |\n| `InvalidContentType` | 400 | The body is not sent as `application/json`. |\n| `ResourceNotFound` | 400 | The referenced object does not exist in this account or was deleted. Returned as HTTP 400, not 404. |\n| `NoLicense` | 400 | The account's plan does not include the feature, a plan quota is used up, the plan has expired, or credits are insufficient. |\n| `ReferenceExist` | 400 | The object is still referenced by other objects, so it cannot be deleted. |\n| `Unauthorized` | 401 | The APP Key is missing, invalid, or deleted. |\n| `BalanceNotEnough` | 402 | Console-only (billing); not returned by Open API operations. |\n| `AccessDenied` | 403 | The APP Key's permission scope or the creator's role does not allow this operation or object. |\n| `RouteNotFound` | 404 | No operation matches the HTTP method and path. |\n| `MethodNotAllowed` | 405 | The path exists but not for this HTTP method. |\n| `UndonedOrderExist` | 409 | Console-only (billing); not returned by Open API operations. |\n| `EntityTooLarge` | 413 | The request body exceeds the size limit. |\n| `RequestLocked` | 423 | Console-only (sign-in protection); not returned by Open API operations. |\n| `RequestVerifyRequired` | 428 | Console-only (verification code); not returned by Open API operations. |\n| `DangerousOperation` | 428 | Console-only (MFA for high-risk actions); not returned by Open API operations. |\n| `RequestTooFrequently` | 429 | A rate limit was hit; wait for the `Flashcat-Request-Rate-Limit-Delay` response header (seconds) before retrying. |\n| `InternalError` | 500 | Unexpected server error; retry with backoff and include `request_id` when reporting. |\n| `ServiceUnavailable` | 503 | A backend dependency is overloaded or unavailable; retry with backoff. |",
         "enum": [
           "OK",
           "InvalidParameter",
@@ -22520,35 +22922,35 @@
           "RouteNotFound",
           "MethodNotAllowed",
           "UndonedOrderExist",
-          "RequestLocked",
           "EntityTooLarge",
-          "RequestTooFrequently",
+          "RequestLocked",
           "RequestVerifyRequired",
           "DangerousOperation",
+          "RequestTooFrequently",
           "InternalError",
           "ServiceUnavailable"
         ],
         "x-enumDescriptions": {
-          "OK": "Reserved — not returned on real errors.",
-          "InvalidParameter": "A required parameter is missing or failed validation.",
-          "BadRequest": "Generic 400 used when no more specific code fits.",
-          "InvalidContentType": "The `Content-Type` header is not `application/json`.",
-          "ResourceNotFound": "The referenced resource does not exist. Note: returned as HTTP 400, not 404 (historical choice).",
-          "NoLicense": "The feature is license-gated and no active license was found.",
-          "ReferenceExist": "Deletion blocked — other entities still reference this resource.",
-          "Unauthorized": "`app_key` is missing, invalid, or expired.",
-          "BalanceNotEnough": "Billing-gated operation with insufficient account balance.",
-          "AccessDenied": "Authenticated but lacking the permission required for this operation.",
-          "RouteNotFound": "The request URL path is not a known route.",
-          "MethodNotAllowed": "The HTTP method is not allowed on this otherwise-known path.",
-          "UndonedOrderExist": "An outstanding billing order blocks this new one. Wait and retry.",
-          "RequestLocked": "Operation temporarily locked due to repeated failures.",
-          "EntityTooLarge": "Request body exceeds the configured max size.",
-          "RequestTooFrequently": "Rate limit hit — API-global, per-account, or per-integration.",
-          "RequestVerifyRequired": "Second-factor verification required but not supplied.",
-          "DangerousOperation": "High-risk operation requires MFA verification.",
-          "InternalError": "Unhandled server-side error. Include `request_id` in the bug report.",
-          "ServiceUnavailable": "A backend dependency is unavailable. Try again later."
+          "OK": "Reserved; never returned on a failed request.",
+          "InvalidParameter": "A parameter is missing, has the wrong type, or failed validation; `message` usually names the field.",
+          "BadRequest": "The request breaks a business rule or conflicts with the current state of an object; `message` says which.",
+          "InvalidContentType": "The body is not sent as `application/json`.",
+          "ResourceNotFound": "The referenced object does not exist in this account or was deleted. Returned as HTTP 400, not 404.",
+          "NoLicense": "The account's plan does not include the feature, a plan quota is used up, the plan has expired, or credits are insufficient.",
+          "ReferenceExist": "The object is still referenced by other objects, so it cannot be deleted.",
+          "Unauthorized": "The APP Key is missing, invalid, or deleted.",
+          "BalanceNotEnough": "Console-only (billing); not returned by Open API operations.",
+          "AccessDenied": "The APP Key's permission scope or the creator's role does not allow this operation or object.",
+          "RouteNotFound": "No operation matches the HTTP method and path.",
+          "MethodNotAllowed": "The path exists but not for this HTTP method.",
+          "UndonedOrderExist": "Console-only (billing); not returned by Open API operations.",
+          "EntityTooLarge": "The request body exceeds the size limit.",
+          "RequestLocked": "Console-only (sign-in protection); not returned by Open API operations.",
+          "RequestVerifyRequired": "Console-only (verification code); not returned by Open API operations.",
+          "DangerousOperation": "Console-only (MFA for high-risk actions); not returned by Open API operations.",
+          "RequestTooFrequently": "A rate limit was hit; wait for the `Flashcat-Request-Rate-Limit-Delay` response header (seconds) before retrying.",
+          "InternalError": "Unexpected server error; retry with backoff and include `request_id` when reporting.",
+          "ServiceUnavailable": "A backend dependency is overloaded or unavailable; retry with backoff."
         },
         "example": "InvalidParameter"
       },
@@ -22591,7 +22993,7 @@
           },
           "override": {
             "type": "boolean",
-            "description": "When `true`, overwrite the label if it already exists. Defaults to `false`."
+            "description": "When `false` (default) the rule is skipped if `result_label` already exists on the event; when `true` the existing value is overwritten."
           }
         }
       },
@@ -22607,7 +23009,8 @@
             "items": {
               "type": "string"
             },
-            "description": "List of label keys to remove from the alert."
+            "description": "Label names to remove from the event (at least one), given without the `labels.` prefix.",
+            "minItems": 1
           }
         }
       },
@@ -22630,15 +23033,15 @@
           },
           "pattern": {
             "type": "string",
-            "description": "RE2 regular expression applied to the source value. Must contain at least one capture group; the captured groups are joined with a space and written to `result_label`. Mutually exclusive with `g_json`."
+            "description": "Regular expression (RE2) applied to the source value; may be wrapped in `/.../`. All capture groups are joined with a space and written to `result_label`. Nothing is written when the expression does not match, has no capture group, or the first group is empty. Exactly one of `pattern` and `g_json` must be set."
           },
           "g_json": {
             "type": "string",
-            "description": "GJson path expression used to extract a value from a JSON-encoded field. Mutually exclusive with `pattern`."
+            "description": "GJSON path (a leading `$.` is ignored) used when the source value is a JSON string, e.g. `host.name`. If the source value is not valid JSON the rule is skipped; if the path does not exist an empty string is written. Exactly one of `pattern` and `g_json` must be set."
           },
           "override": {
             "type": "boolean",
-            "description": "When `true`, overwrite the label if it already exists. Defaults to `false`."
+            "description": "When `false` (default) the rule is skipped if `result_label` already exists on the event; when `true` the existing value is overwritten."
           }
         }
       },
@@ -22655,7 +23058,8 @@
               "type": "string",
               "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$"
             },
-            "description": "Label keys to populate from the mapping lookup result. Each must match `^[a-zA-Z_][a-zA-Z0-9_]*$`."
+            "description": "Label keys to fill from the lookup result (at least one). For `schema` they are normally the schema's `result_labels`; for `api` they are sent to the API as `result_label_keys`.",
+            "minItems": 1
           },
           "mapping_type": {
             "type": "string",
@@ -22664,7 +23068,7 @@
               "api"
             ],
             "default": "schema",
-            "description": "Mapping source type. `schema` uses a mapping schema table; `api` calls an external HTTP API."
+            "description": "Lookup source.\n- `schema` (default): look up a row in the mapping schema `schema_id` using the event's values of the schema's `source_labels`; the rule does nothing if any source label is missing or no row matches.\n- `api`: call the mapping API `api_id` with the event; runs for alert events only."
           },
           "schema_id": {
             "type": "string",
@@ -22676,7 +23080,7 @@
           },
           "override": {
             "type": "boolean",
-            "description": "When `true`, overwrite labels that already exist. Defaults to `false`."
+            "description": "When `false` (default) the rule is skipped if every label in `result_labels` already exists, and otherwise only the missing labels are filled. When `true` all `result_labels` are overwritten with the lookup result."
           }
         }
       },
@@ -22690,14 +23094,14 @@
             "type": "integer",
             "minimum": 0,
             "maximum": 6,
-            "description": "Max repeat notifications within the level."
+            "description": "Total notifications sent in this level, including the first, 0–6; `0` and `1` both notify once."
           },
           "notify_step": {
             "type": "number",
             "format": "float",
             "minimum": 0.5,
             "maximum": 120,
-            "description": "Repeat interval in minutes."
+            "description": "Minutes between repeat notifications in this level, 0.5–120, kept to one decimal place. Used only when `max_times` is greater than 1."
           },
           "target": {
             "$ref": "#/components/schemas/EscalateTarget"
@@ -22706,11 +23110,11 @@
             "type": "integer",
             "minimum": 0,
             "maximum": 720,
-            "description": "Wait before moving to the next level, in minutes."
+            "description": "Minutes to wait after this level's first notification before escalating to the next level, 0–720. Ignored on the last level."
           },
           "force_escalate": {
             "type": "boolean",
-            "description": "When true, always escalate regardless of acknowledgement."
+            "description": "When true, escalate even after the incident has been acknowledged (`Processing`). When false, escalation stops once the incident is acknowledged. Closed or snoozed incidents never escalate."
           }
         }
       },
@@ -22746,15 +23150,15 @@
           },
           "priority": {
             "type": "integer",
-            "description": "Evaluation priority. Lower runs first."
+            "description": "Evaluation order from `0` to `200`: lower values are evaluated first, ties broken by creation time. The first enabled rule whose time windows and filters match a new incident takes it."
           },
           "aggr_window": {
             "type": "integer",
-            "description": "Delay window in seconds."
+            "description": "Delay in seconds, 0–3600, before the first notification for a newly assigned incident is sent; `0` notifies immediately."
           },
           "rule_name": {
             "type": "string",
-            "description": "Rule name."
+            "description": "Rule name, 1–39 characters."
           },
           "description": {
             "type": "string",
@@ -22772,11 +23176,11 @@
             "items": {
               "$ref": "#/components/schemas/TimeFilter"
             },
-            "description": "Recurring time windows during which the rule applies."
+            "description": "Recurring time windows during which the rule can match; empty means at any time."
           },
           "filters": {
             "$ref": "#/components/schemas/FilterGroup",
-            "description": "Incident-level match conditions (OR-of-AND tree): the rule is matched against the incident the alert was grouped into, not against the alert itself. Omit or leave empty to apply the rule to all incidents in the channel."
+            "description": "Incident conditions (OR of AND groups), matched against the incident the alert was grouped into. Empty means the rule matches every incident in the channel."
           },
           "status": {
             "type": "string",
@@ -22790,7 +23194,7 @@
           "template_id": {
             "type": "string",
             "pattern": "^[0-9a-fA-F]{24}$",
-            "description": "Notification template ID (MongoDB ObjectID)."
+            "description": "Notification template ID (24-character hex); see `POST /template/list`."
           },
           "rule_id": {
             "type": "string",
@@ -22816,10 +23220,6 @@
             "type": "integer",
             "format": "int64",
             "description": "Last update time, Unix timestamp in seconds."
-          },
-          "channel_name": {
-            "type": "string",
-            "description": "Channel name, populated for cross-channel listing responses."
           }
         }
       },
@@ -22833,7 +23233,7 @@
               "type": "integer",
               "format": "int64"
             },
-            "description": "Member IDs to notify directly."
+            "description": "Member IDs to notify directly; obtain them from `POST /member/list`. Every ID must exist."
           },
           "team_ids": {
             "type": "array",
@@ -22841,7 +23241,7 @@
               "type": "integer",
               "format": "int64"
             },
-            "description": "Team IDs to notify."
+            "description": "Team IDs whose members are notified; obtain them from `POST /team/list`. Each team must have at least one member."
           },
           "schedule_to_role_ids": {
             "type": "object",
@@ -22852,7 +23252,7 @@
                 "format": "int64"
               }
             },
-            "description": "Map of schedule ID to the role IDs on that schedule to notify."
+            "description": "Notify whoever is on call: keys are schedule IDs (from `POST /schedule/list`) written as strings, values are the role IDs on that schedule. Each value must be non-empty."
           },
           "emails": {
             "type": "array",
@@ -22860,42 +23260,48 @@
               "type": "string",
               "format": "email"
             },
-            "description": "Email addresses to notify (push-only scenarios)."
+            "description": "Email addresses of account members; each address is resolved to the member who owns it when the level fires."
           },
           "by": {
-            "type": "object",
-            "description": "Per-severity personal notification channels. Required unless `webhooks` is provided.",
+            "type": [
+              "object",
+              "null"
+            ],
+            "description": "Personal notification channels for the people in this target, per incident severity. Required unless `webhooks` is set; returned as `null` when not set.",
             "properties": {
               "follow_preference": {
                 "type": "boolean",
-                "description": "When true, use each responder's personal preference instead of the lists below."
+                "description": "When true, each person is notified through the channels in their own notification preferences for the incident's severity, and `critical`, `warning` and `info` are ignored."
               },
               "critical": {
                 "type": "array",
                 "items": {
                   "type": "string"
                 },
-                "description": "Notify channels used for Critical severity. Personal channels: `sms`, `voice`, `email`, `push`; IM group-chat channels: `feishu_app:<chat_id>`, `dingtalk_app:<chat_id>`, `wecom_app:<chat_id>`, `slack_app:<chat_id>`, `teams_app:<chat_id>`."
+                "description": "Channels used when the incident severity is `Critical`: `sms`, `voice`, `email`, `push`, or a direct message through an IM app integration written as `<app>:<integration_id>`, where `<app>` is `feishu_app`, `dingtalk_app`, `wecom_app`, `slack_app` or `teams_app` and `<integration_id>` is the ID of that IM integration. Other values return `InvalidParameter`."
               },
               "warning": {
                 "type": "array",
                 "items": {
                   "type": "string"
                 },
-                "description": "Notify channels used for Warning severity. Values as for `critical`."
+                "description": "Channels used when the incident severity is `Warning`; same values as `critical`."
               },
               "info": {
                 "type": "array",
                 "items": {
                   "type": "string"
                 },
-                "description": "Notify channels used for Info severity. Values as for `critical`."
+                "description": "Channels used when the incident severity is `Info`; same values as `critical`."
               }
             }
           },
           "webhooks": {
-            "type": "array",
-            "description": "Group chat / webhook targets. Required unless `by` is provided.",
+            "type": [
+              "array",
+              "null"
+            ],
+            "description": "Group chats to notify through robots or IM apps. Required unless `by` is set; returned as `null` when not set.",
             "items": {
               "type": "object",
               "required": [
@@ -22905,12 +23311,24 @@
               "properties": {
                 "type": {
                   "type": "string",
-                  "description": "Webhook type, one of `feishu`, `feishu_app`, `dingtalk`, `dingtalk_app`, `wecom`, `slack`, `slack_app`, `teams_app`, `telegram`, `zoom`."
+                  "description": "Delivery type:\n- `feishu`, `dingtalk`, `wecom`, `slack`, `telegram`, `zoom`: a group robot (incoming webhook) of that IM.\n- `feishu_app`, `dingtalk_app`, `slack_app`, `teams_app`: group chats reached through the corresponding IM app integration.",
+                  "enum": [
+                    "feishu",
+                    "dingtalk",
+                    "wecom",
+                    "slack",
+                    "telegram",
+                    "zoom",
+                    "feishu_app",
+                    "dingtalk_app",
+                    "slack_app",
+                    "teams_app"
+                  ]
                 },
                 "settings": {
                   "type": "object",
                   "additionalProperties": true,
-                  "description": "Type-specific settings (chat IDs, URLs, etc.)."
+                  "description": "Type-specific settings, such as the robot's webhook token or the app's chat IDs; `feishu_app` and `dingtalk_app` require it. To see the exact shape for a type, configure one in the console and read it back with `POST /channel/escalate/rule/info`."
                 }
               }
             }
@@ -22965,7 +23383,7 @@
             "items": {
               "$ref": "#/components/schemas/StatusPageComponentItem"
             },
-            "description": "Components this subscriber has subscribed to."
+            "description": "Components the subscriber follows; each item carries only `component_id` and `name`. Empty when `all` is `true`."
           },
           "all": {
             "type": "boolean",
@@ -23014,7 +23432,10 @@
         "properties": {
           "progress": {
             "type": "string",
-            "description": "Progress note entered at acknowledgement."
+            "description": "`Processing` when this acknowledgement moved the incident from `Triggered` to `Processing`; omitted when the incident was already `Processing`.",
+            "enum": [
+              "Processing"
+            ]
           },
           "comment": {
             "type": "string",
@@ -23093,7 +23514,8 @@
             "description": "ObjectID of the account-level comment type attached to the comment."
           },
           "comment_type": {
-            "$ref": "#/components/schemas/IncidentCommentTypeDisplay"
+            "$ref": "#/components/schemas/IncidentCommentTypeDisplay",
+            "description": "Name and color of the attached comment type, resolved at read time; omitted when no comment type is attached or it no longer exists."
           }
         },
         "title": "i_comm"
@@ -23127,23 +23549,24 @@
             "items": {
               "$ref": "#/components/schemas/IncidentShort"
             },
-            "description": "Source incidents that were merged."
+            "description": "Incidents merged into the target; present on the target incident's entry."
           },
           "target_incident": {
-            "$ref": "#/components/schemas/IncidentShort"
+            "$ref": "#/components/schemas/IncidentShort",
+            "description": "Incident this incident was merged into; present on each source incident's entry."
           },
           "owner_id": {
             "type": "integer",
             "format": "int64",
-            "description": "Member ID that performed the merge."
+            "description": "Not set by incident merges, which never change the owner; present only on older entries."
           },
           "title": {
             "type": "string",
-            "description": "Resulting incident title."
+            "description": "New title the merge set on the target incident; present only on the target's entry and only when the title changed."
           },
           "remove_source_incidents": {
             "type": "boolean",
-            "description": "True if the source incidents were removed after merging."
+            "description": "`true` when the source incidents were permanently deleted after the merge."
           },
           "source_responders": {
             "type": "array",
@@ -23151,7 +23574,7 @@
               "type": "integer",
               "format": "int64"
             },
-            "description": "Responder member IDs carried over from the source incidents."
+            "description": "Member IDs that were responders on the source incidents, for reference; they are not added to the target's responders."
           }
         },
         "title": "i_merge"
@@ -23187,7 +23610,8 @@
         "description": "Detail payload for `i_new`.",
         "properties": {
           "severity": {
-            "$ref": "#/components/schemas/FeedSeverity"
+            "$ref": "#/components/schemas/FeedSeverity",
+            "description": "Severity of the incident when it was created."
           },
           "title": {
             "type": "string",
@@ -23270,7 +23694,7 @@
         "properties": {
           "reason": {
             "type": "string",
-            "description": "Reason why the incident was reopened."
+            "description": "Free-text reason passed as `reason` to `POST /incident/reopen`; omitted when none was given."
           }
         },
         "title": "i_reopen"
@@ -23325,10 +23749,12 @@
         "description": "Detail payload for `i_r_severity`.",
         "properties": {
           "from": {
-            "$ref": "#/components/schemas/FeedSeverity"
+            "$ref": "#/components/schemas/FeedSeverity",
+            "description": "Severity before the change."
           },
           "to": {
-            "$ref": "#/components/schemas/FeedSeverity"
+            "$ref": "#/components/schemas/FeedSeverity",
+            "description": "Severity after the change."
           }
         },
         "title": "i_r_severity"
@@ -23339,11 +23765,11 @@
         "properties": {
           "from": {
             "type": "string",
-            "description": "Previous title."
+            "description": "Title before the change."
           },
           "to": {
             "type": "string",
-            "description": "New title."
+            "description": "Title after the change."
           }
         },
         "title": "i_r_title"
@@ -23412,7 +23838,10 @@
         "properties": {
           "progress": {
             "type": "string",
-            "description": "Progress note entered when acknowledgement was removed."
+            "description": "`Triggered` when removing this acknowledgement returned the incident to `Triggered` (no responder still acknowledged); omitted otherwise.",
+            "enum": [
+              "Triggered"
+            ]
           }
         },
         "title": "i_unack"
@@ -23424,7 +23853,7 @@
           "snoozedBefore": {
             "type": "integer",
             "format": "int64",
-            "description": "Unix timestamp at which the prior snooze was scheduled to end."
+            "description": "Unix timestamp (seconds) at which the cancelled snooze would have ended."
           }
         },
         "title": "i_wake"
@@ -23448,7 +23877,13 @@
           },
           "plugin_type": {
             "type": "string",
-            "description": "Chat integration plugin type."
+            "description": "Plugin type of the IM integration: `feishu_app` (Feishu), `dingtalk_app` (DingTalk), `wecom_app` (WeCom), or `slack_app` (Slack).",
+            "enum": [
+              "feishu_app",
+              "dingtalk_app",
+              "wecom_app",
+              "slack_app"
+            ]
           },
           "integration_name": {
             "type": "string",
@@ -23470,6 +23905,10 @@
             "format": "int64",
             "description": "Integration ID that hosted the war room chat group."
           },
+          "unlink_only": {
+            "type": "boolean",
+            "description": "`true` when the war room was only unlinked from the incident (`unlink_only` request) and the group was not dissolved. Omitted otherwise."
+          },
           "chat_id": {
             "type": "string",
             "description": "Chat group identifier."
@@ -23480,7 +23919,13 @@
           },
           "plugin_type": {
             "type": "string",
-            "description": "Chat integration plugin type."
+            "description": "Plugin type of the IM integration: `feishu_app` (Feishu), `dingtalk_app` (DingTalk), `wecom_app` (WeCom), or `slack_app` (Slack).",
+            "enum": [
+              "feishu_app",
+              "dingtalk_app",
+              "wecom_app",
+              "slack_app"
+            ]
           },
           "integration_name": {
             "type": "string",
@@ -23563,7 +24008,7 @@
           "account_id": {
             "type": "integer",
             "format": "int64",
-            "description": "Account ID."
+            "description": "ID of the account that owns the alert."
           },
           "creator_id": {
             "type": "integer",
@@ -23615,7 +24060,7 @@
         "properties": {
           "key": {
             "type": "string",
-            "description": "Field name to filter on. Use plain names for built-in alert fields (e.g. `alert_severity`, `alert_key`, `check`, `resource`, `service`, `cluster`) or the `labels.<name>` prefix for custom alert labels (e.g. `labels.env`, `labels.region`)."
+            "description": "Field to match. Which built-in keys are allowed depends on the rule type and is listed on the field that holds the conditions; any `labels.<name>` key (for example `labels.env`) is always accepted. An unknown key returns `InvalidParameter`. When the alert or incident has no value for the key, `IN` does not match and `NOTIN` matches."
           },
           "oper": {
             "type": "string",
@@ -23623,14 +24068,14 @@
               "IN",
               "NOTIN"
             ],
-            "description": "Filter operator. `IN` — value must match one of `vals`; `NOTIN` — value must not match any of `vals`. Supports regex patterns wrapped in `/pattern/`."
+            "description": "Match operator, case-sensitive. `IN`: matches when the field value matches any entry in `vals`. `NOTIN`: matches when it matches none of them."
           },
           "vals": {
             "type": "array",
             "items": {
               "type": "string"
             },
-            "description": "List of values to match against. Each entry is a plain string or a `/regex/` pattern."
+            "description": "Values to compare, at least one. Each entry is matched as: an exact string; a wildcard pattern when it contains `*` or `?` (must match the whole value); a regular expression when wrapped in slashes, such as `/^db-/` (may match anywhere in the value); an IP range written `cidr:<network>`, such as `cidr:203.0.113.0/24`; or a numeric comparison `num:<op>:<number>` with `lt`, `le`, `gt` or `ge`, such as `num:gt:90`."
           }
         }
       },
@@ -23643,13 +24088,13 @@
         "properties": {
           "is_disabled": {
             "type": "boolean",
-            "description": "Disable flapping detection."
+            "description": "When true, flapping detection is turned off."
           },
           "max_changes": {
             "type": "integer",
             "minimum": 2,
             "maximum": 100,
-            "description": "Max state changes allowed within `in_mins`."
+            "description": "Max state changes allowed within `in_mins`, 2–100. When omitted or `0`, all three values fall back to the defaults: 4 changes, `in_mins` 60, `mute_mins` 120."
           },
           "in_mins": {
             "type": "integer",
@@ -23694,7 +24139,7 @@
         "properties": {
           "event_id": {
             "type": "string",
-            "description": "Event ID returned by `ListWebhookHistory`."
+            "description": "`event_id` of a record returned by `POST /webhook/history/list`. It starts with the delivery date (`YYYYMMDD`); an ID without that prefix fails the request."
           },
           "integration_id": {
             "type": "integer",
@@ -23718,7 +24163,7 @@
               "p",
               "n"
             ],
-            "description": "Grouping method: `i` intelligent, `p` pattern, `n` none."
+            "description": "Grouping method:\n- `n`: no grouping; every new alert opens its own incident.\n- `p`: rule-based grouping by the keys in `equals` and `cases`; requires the Standard license or higher.\n- `i`: intelligent grouping by content similarity (see `i_keys`, `i_score_threshold`); requires the Pro license."
           },
           "equals": {
             "type": "array",
@@ -23729,7 +24174,7 @@
               }
             },
             "maxItems": 5,
-            "description": "Groups of label keys whose equality defines a bucket."
+            "description": "Key sets for rule-based (`p`) grouping, up to 5 sets. A new alert joins an active incident when every key of any one set has the same value on both. Keys: `title`, `description`, `severity`, or `labels.<name>`; each set must be non-empty. With `p`, at least one of `equals` or `cases` is required."
           },
           "cases": {
             "type": "array",
@@ -23764,7 +24209,7 @@
           },
           "all_equals_required": {
             "type": "boolean",
-            "description": "When true, all listed keys must be present for grouping."
+            "description": "When true, a key set matches only if every key in it is present on the alert. When false, missing keys compare as empty, but at least one key of the set must be present."
           },
           "time_window": {
             "type": "integer",
@@ -23783,7 +24228,7 @@
             "type": "integer",
             "minimum": 0,
             "maximum": 10000,
-            "description": "Alert storm threshold."
+            "description": "Legacy single storm threshold; used only when `storm_thresholds` is empty and the value is greater than 1. `0` disables it."
           },
           "storm_thresholds": {
             "type": "array",
@@ -23791,7 +24236,7 @@
               "type": "integer"
             },
             "maxItems": 5,
-            "description": "Multi-level storm thresholds."
+            "description": "Alert counts at which an incident storm event fires: when the number of alerts merged into one incident reaches a threshold, a storm notification is sent. Up to 5 values, each at least 2; duplicates are removed and values are sorted."
           },
           "i_keys": {
             "type": "array",
@@ -23799,14 +24244,14 @@
               "type": "string"
             },
             "maxItems": 10,
-            "description": "Label keys used for intelligent grouping embeddings."
+            "description": "Fields used by intelligent (`i`) grouping, up to 10: `title`, `description`, `severity`, or `labels.<name>`. Empty uses `title`, `description`, `labels.service` and `labels.resource`."
           },
           "i_score_threshold": {
             "type": "number",
             "format": "float",
             "minimum": 0.5,
             "maximum": 1,
-            "description": "Intelligent grouping similarity threshold."
+            "description": "Minimum similarity, 0.5–1, for intelligent grouping to merge an alert into an existing incident. Omitted or `0` uses 0.9."
           }
         }
       },
@@ -23827,7 +24272,7 @@
           },
           "alt": {
             "type": "string",
-            "description": "Alt text."
+            "description": "Alternative text shown when the image cannot be displayed; empty when not set."
           }
         }
       },
@@ -23860,7 +24305,7 @@
           },
           "all": {
             "type": "boolean",
-            "description": "When true, the subscriber receives notifications for all components. Must be true when `component_ids` and `change_ids` are both empty."
+            "description": "When `true`, the subscriber receives notifications for all components and events, and `component_ids`/`change_ids` are ignored. Must be `true` when both lists are empty."
           },
           "locale": {
             "type": "string",
@@ -23894,7 +24339,7 @@
             "items": {
               "$ref": "#/components/schemas/ImportStatusPageSubscriberItem"
             },
-            "description": "Subscribers to import."
+            "description": "Subscribers to import. Each recipient's existing subscriptions on this page are replaced; an empty or omitted list does nothing."
           }
         }
       },
@@ -23908,12 +24353,12 @@
           "Triggered": {
             "type": "integer",
             "format": "int64",
-            "description": "Count of triggered incidents in the last 30 days."
+            "description": "Incidents started in the last 30 days that are still `Triggered` (not yet acknowledged)."
           },
           "Processing": {
             "type": "integer",
             "format": "int64",
-            "description": "Count of processing incidents in the last 30 days."
+            "description": "Incidents started in the last 30 days that are `Processing` (acknowledged, not yet closed)."
           }
         }
       },
@@ -23933,7 +24378,7 @@
           "ref_id": {
             "type": "string",
             "pattern": "^[0-9a-fA-F]{24}$",
-            "description": "ObjectID of the source alert or incident this entry references."
+            "description": "ID of the incident the entry belongs to; equals the requested `incident_id`."
           },
           "type": {
             "$ref": "#/components/schemas/IncidentFeedType"
@@ -24042,6 +24487,35 @@
               },
               {
                 "$ref": "#/components/schemas/FeedDetailAlertMerge"
+              },
+              {
+                "type": "object",
+                "title": "i_wi_auto_converted",
+                "description": "Detail payload for `i_wi_auto_converted`.",
+                "properties": {
+                  "count": {
+                    "type": "integer",
+                    "description": "Number of action items converted to follow-ups."
+                  },
+                  "work_item_ids": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    },
+                    "description": "IDs of the converted work items."
+                  },
+                  "titles": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    },
+                    "description": "Titles of the converted work items, in the same order as `work_item_ids`."
+                  },
+                  "post_mortem_id": {
+                    "type": "string",
+                    "description": "ID of the post-mortem the follow-ups are bound to; empty when the incident has no post-mortem."
+                  }
+                }
               }
             ],
             "discriminator": {
@@ -24087,7 +24561,7 @@
           "account_id": {
             "type": "integer",
             "format": "int64",
-            "description": "Account ID."
+            "description": "ID of the account that owns this record; the same for every record returned to one `app_key`."
           },
           "creator_id": {
             "type": "integer",
@@ -24108,12 +24582,23 @@
             "type": "integer",
             "format": "int64",
             "description": "Last update timestamp in milliseconds."
+          },
+          "via": {
+            "type": "string",
+            "enum": [
+              "ai_sre"
+            ],
+            "description": "`ai_sre` when AI SRE performed the action on behalf of `creator_id`; omitted for direct actions."
+          },
+          "agent_session_id": {
+            "type": "string",
+            "description": "ID of the AI SRE session that performed the action; present only when `via` is `ai_sre` and a session was recorded."
           }
         }
       },
       "IncidentFeedType": {
         "type": "string",
-        "description": "Incident timeline entry type. Each value identifies one lifecycle event; the matching `detail` payload shape is determined by this field. Incident types are prefixed with `i_`.\n\n| Type | Meaning |\n|---|---|\n| `i_new` | Incident Created: A new incident was created automatically or manually. |\n| `i_assign` | Assigned: Incident was assigned to responders. |\n| `i_a_rspd` | Responder Added: Additional responders joined the incident. |\n| `i_notify` | Notification dispatched through a channel at a specific escalation level. |\n| `i_storm` | Alert storm threshold reached on the incident. |\n| `i_snooze` | Notifications snoozed for a given duration. |\n| `i_wake` | Snooze cancelled and notifications resumed. |\n| `i_ack` | Acknowledged: Responder confirmed they are working on the incident. |\n| `i_unack` | Acknowledgement removed. |\n| `i_comm` | Comment: Responder logged progress or key information. |\n| `i_rslv` | Resolved: Incident was marked as resolved. |\n| `i_reopen` | Reopened: Resolved incident was reopened, possibly due to recurrence. |\n| `i_merge` | Merged: Multiple related incidents were merged into one. |\n| `i_r_title` | Title updated. |\n| `i_r_desc` | Description updated. |\n| `i_r_impact` | Impact updated. |\n| `i_r_rc` | Root cause updated. |\n| `i_r_rsltn` | Resolution updated. |\n| `i_r_severity` | Severity Changed: Incident severity level was adjusted. |\n| `i_r_field` | Custom field value updated. |\n| `i_m_flapping` | Incident muted by flapping detection. |\n| `i_m_reply` | Mute reply marker on a comment. |\n| `i_custom` | Action: Automated action or script was triggered. |\n| `i_wr_create` | War Room Created: Chat group was created for collaborative response. |\n| `i_wr_delete` | War room chat group deleted. |\n| `i_auto_refresh` | Card auto-refresh event posted back to the timeline. |\n| `i_wi_created` | Work Item Created: An Action or Follow-up was created. |\n| `i_wi_updated` | Work Item Updated: Title, description, status, or priority was changed. |\n| `i_wi_assignees` | Work Item Assignees Changed: Assignees were updated. |\n| `i_wi_completed` | Work Item Completed: An assignee marked the work item complete. |\n| `i_wi_converted` | Work Item Converted: An Action was converted to a Follow-up. |\n| `i_wi_bound` | Work Item Bound: A converted Follow-up was bound to a post-mortem. |\n| `i_wi_deleted` | Work Item Deleted: An Action or Follow-up was soft-deleted. |\n| `a_merge` | Alert Merged: An alert was merged into an existing incident. |",
+        "description": "Incident timeline entry type. Each value identifies one lifecycle event; the matching `detail` payload shape is determined by this field. Incident types are prefixed with `i_`.\n\n| Type | Meaning |\n|---|---|\n| `i_new` | Incident Created: A new incident was created automatically or manually. |\n| `i_assign` | Assigned: Incident was assigned to responders. |\n| `i_a_rspd` | Responder Added: Additional responders joined the incident. |\n| `i_notify` | Notification dispatched through a channel at a specific escalation level. |\n| `i_storm` | Alert storm threshold reached on the incident. |\n| `i_snooze` | Notifications snoozed for a given duration. |\n| `i_wake` | Snooze cancelled and notifications resumed. |\n| `i_ack` | Acknowledged: Responder confirmed they are working on the incident. |\n| `i_unack` | Acknowledgement removed. |\n| `i_comm` | Comment: Responder logged progress or key information. |\n| `i_rslv` | Resolved: Incident was marked as resolved. |\n| `i_reopen` | Reopened: Resolved incident was reopened, possibly due to recurrence. |\n| `i_merge` | Merged: Multiple related incidents were merged into one. |\n| `i_r_title` | Title updated. |\n| `i_r_desc` | Description updated. |\n| `i_r_impact` | Impact updated. |\n| `i_r_rc` | Root cause updated. |\n| `i_r_rsltn` | Resolution updated. |\n| `i_r_severity` | Severity Changed: Incident severity level was adjusted. |\n| `i_r_field` | Custom field value updated. |\n| `i_m_flapping` | Incident muted by flapping detection. |\n| `i_m_reply` | Mute reply marker on a comment. |\n| `i_custom` | Action: Automated action or script was triggered. |\n| `i_wr_create` | War Room Created: Chat group was created for collaborative response. |\n| `i_wr_delete` | War room chat group deleted. |\n| `i_auto_refresh` | Card auto-refresh event posted back to the timeline. |\n| `i_wi_created` | Work Item Created: An Action or Follow-up was created. |\n| `i_wi_updated` | Work Item Updated: Title, description, status, or priority was changed. |\n| `i_wi_assignees` | Work Item Assignees Changed: Assignees were updated. |\n| `i_wi_completed` | Work Item Completed: An assignee marked the work item complete. |\n| `i_wi_converted` | Work Item Converted: An Action was converted to a Follow-up. |\n| `i_wi_bound` | Work Item Bound: A converted Follow-up was bound to a post-mortem. |\n| `i_wi_deleted` | Work Item Deleted: An Action or Follow-up was soft-deleted. |\n| `i_wi_auto_converted` | Work Items Auto-converted: Closing the incident converted its unfinished action items to follow-ups. |\n| `a_merge` | Alert Merged: An alert was merged into an existing incident. |",
         "enum": [
           "i_new",
           "i_assign",
@@ -24148,6 +24633,7 @@
           "i_wi_converted",
           "i_wi_bound",
           "i_wi_deleted",
+          "i_wi_auto_converted",
           "a_merge"
         ]
       },
@@ -24203,7 +24689,8 @@
           "silence_url",
           "post_mortem_id",
           "images",
-          "manual_overrides"
+          "manual_overrides",
+          "has_unfinished_work_item"
         ],
         "properties": {
           "incident_id": {
@@ -24232,19 +24719,25 @@
             "description": "First integration associated with the incident."
           },
           "integration_ids": {
-            "type": "array",
+            "type": [
+              "array",
+              "null"
+            ],
             "items": {
               "type": "integer",
               "format": "int64"
             },
-            "description": "All integration IDs contributing alerts to this incident."
+            "description": "IDs of all integrations contributing alerts to this incident; `null` for incidents without integrations, such as manually created ones."
           },
           "integration_types": {
-            "type": "array",
+            "type": [
+              "array",
+              "null"
+            ],
             "items": {
               "type": "string"
             },
-            "description": "Integration type strings for all contributing integrations."
+            "description": "Plugin types of all contributing integrations (see `integration_type`); `null` when there are none."
           },
           "dedup_key": {
             "type": "string",
@@ -24392,8 +24885,15 @@
             "type": "boolean",
             "description": "Whether the incident has ever been silenced."
           },
+          "has_unfinished_work_item": {
+            "type": "boolean",
+            "description": "`true` when the incident still has at least one action item or follow-up that is neither `done` nor `cancelled`."
+          },
           "labels": {
-            "type": "object",
+            "type": [
+              "object",
+              "null"
+            ],
             "additionalProperties": {
               "type": "string"
             },
@@ -24406,7 +24906,7 @@
           },
           "assigned_to": {
             "$ref": "#/components/schemas/AssignedTo",
-            "description": "Current assignment target for the incident."
+            "description": "Current assignment target. Always present; for an incident that was never assigned, `type` and `id` are empty and `assigned_at` is `0`."
           },
           "reporter_email": {
             "type": "string",
@@ -24432,7 +24932,7 @@
             "items": {
               "$ref": "#/components/schemas/AlertInfo"
             },
-            "description": "Embedded alerts, only populated for notification templates and custom actions."
+            "description": "Not returned by the incident endpoints; present only in notification template and custom action payloads."
           },
           "closer": {
             "$ref": "#/components/schemas/PersonShort",
@@ -24456,15 +24956,15 @@
           },
           "account_name": {
             "type": "string",
-            "description": "Account name."
+            "description": "Always an empty string in API responses; filled only when the incident is rendered for notifications."
           },
           "account_locale": {
             "type": "string",
-            "description": "Account locale."
+            "description": "Always an empty string in API responses; filled only when the incident is rendered for notifications."
           },
           "account_time_zone": {
             "type": "string",
-            "description": "Account time zone."
+            "description": "Always an empty string in API responses; filled only when the incident is rendered for notifications."
           },
           "channel_name": {
             "type": "string",
@@ -24472,7 +24972,13 @@
           },
           "channel_status": {
             "type": "string",
-            "description": "Channel status."
+            "description": "Status of the channel: `enabled`, `disabled`, or `deleted`. Empty string when the record has no channel or the channel no longer exists.",
+            "enum": [
+              "enabled",
+              "disabled",
+              "deleted",
+              ""
+            ]
           },
           "detail_url": {
             "type": "string",
@@ -24491,25 +24997,36 @@
           },
           "integration_type": {
             "type": "string",
-            "description": "First alert's integration type string, used by the detail page for label mappings."
+            "description": "Plugin type of the incident's first integration (see `integration_types` for all). Open set, for example `prometheus.alert` or `monit.alert`; `POST /integration/type/list` returns the full list. Omitted when the incident has no integration or the endpoint does not fill it."
           },
           "post_mortem_id": {
             "type": "string",
             "description": "Associated post-mortem ID, if any. One incident can only link to a single post-mortem."
           },
           "images": {
-            "type": "array",
+            "type": [
+              "array",
+              "null"
+            ],
             "items": {
               "$ref": "#/components/schemas/Image"
             },
-            "description": "Attached images."
+            "description": "Images attached to the incident; `null` when there are none. Tokens starting with `img_` are returned as download URLs."
           },
           "manual_overrides": {
-            "type": "array",
+            "type": [
+              "array",
+              "null"
+            ],
             "items": {
-              "type": "string"
+              "type": "string",
+              "enum": [
+                "title",
+                "description",
+                "incident_severity"
+              ]
             },
-            "description": "Fields that were manually overridden after auto-population."
+            "description": "Fields edited manually and therefore no longer overwritten by merged alerts: `title`, `description`, `incident_severity`. `null` when none."
           },
           "data_source_id": {
             "type": "integer",
@@ -24518,7 +25035,10 @@
             "deprecated": true
           },
           "data_source_ids": {
-            "type": "array",
+            "type": [
+              "array",
+              "null"
+            ],
             "items": {
               "type": "integer",
               "format": "int64"
@@ -24528,11 +25048,14 @@
           },
           "data_source_type": {
             "type": "string",
-            "description": "Deprecated. Use `integration_type` instead.",
+            "description": "Deprecated; same value as `integration_type`.",
             "deprecated": true
           },
           "data_source_types": {
-            "type": "array",
+            "type": [
+              "array",
+              "null"
+            ],
             "items": {
               "type": "string"
             },
@@ -24575,15 +25098,15 @@
           "total": {
             "type": "integer",
             "format": "int64",
-            "description": "Total number of matching incidents."
+            "description": "Number of matching incidents, capped at 1,000. For `POST /incident/list-by-ids`, the number of incidents found."
           },
           "has_next_page": {
             "type": "boolean",
-            "description": "True when more results are available beyond this page."
+            "description": "Whether another page exists. With `p`/`limit` paging it is computed against the capped `total`, so it is `false` past 1,000 matches even when more exist; with `search_after_ctx` paging it reflects the real data. Always `false` for `POST /incident/list-by-ids`."
           },
           "search_after_ctx": {
             "type": "string",
-            "description": "Opaque cursor to pass as `search_after_ctx` on the next request."
+            "description": "Cursor pointing at the last item of this page; pass it as `search_after_ctx` on the next request to continue past the 1,000-item page limit. Returned for every non-empty page in `p`/`limit` mode, and in cursor mode only when `has_next_page` is `true`. Omitted by `POST /incident/list-by-ids`."
           }
         }
       },
@@ -24891,7 +25414,12 @@
           },
           "progress": {
             "type": "string",
-            "description": "Incident progress — one of `Triggered`, `Processing`, `Closed`."
+            "description": "Incident progress: `Triggered` not yet acknowledged; `Processing` acknowledged and being handled; `Closed` resolved.",
+            "enum": [
+              "Triggered",
+              "Processing",
+              "Closed"
+            ]
           }
         }
       },
@@ -24925,7 +25453,7 @@
           },
           "rule_name": {
             "type": "string",
-            "description": "Rule name."
+            "description": "Inhibit rule name, 1–39 characters."
           },
           "description": {
             "type": "string",
@@ -24937,14 +25465,14 @@
           },
           "target_filters": {
             "$ref": "#/components/schemas/FilterGroup",
-            "description": "Conditions the incoming target alert event must match to be suppressed; empty means every event is a target."
+            "description": "Conditions the incoming target alert event must match to be inhibited; empty means every incoming event is a target. Keys: `title`, `description`, `severity` (alias `alert_severity`, `event_severity`), `status`, `alert_key`, `title_rule`, `integration_id` (alias `data_source_id`), or any `labels.<name>`."
           },
           "equals": {
             "type": "array",
             "items": {
               "type": "string"
             },
-            "description": "Field keys whose values must be equal between the source (inhibiting) alert and the target (suppressed) alert, e.g. `data_source_id` or `labels.cluster`."
+            "description": "Keys whose values must be equal on the source alert and the incoming event. Only `title`, `severity` and `labels.<name>` take effect; with any other key the rule never fires."
           },
           "is_directly_discard": {
             "type": "boolean",
@@ -25068,7 +25596,7 @@
               "type": "integer",
               "format": "int64"
             },
-            "description": "Filter by responder person IDs. At most 100 entries.",
+            "description": "Filter by responder member IDs. Used by `/insight/responder` (which responders to return) and the incident list/export (incidents any of them responded to); ignored by the account/team/channel and top-K endpoints. At most 100 entries.",
             "maxItems": 100
           },
           "severities": {
@@ -25082,7 +25610,7 @@
                 "Ok"
               ]
             },
-            "description": "Filter by severity. At most 3 entries.",
+            "description": "Filter by severity: `Critical`, `Warning`, `Info`, or `Ok`. At most 3 entries.",
             "maxItems": 3
           },
           "incident_ids": {
@@ -25091,7 +25619,7 @@
               "type": "string",
               "pattern": "^[0-9a-fA-F]{24}$"
             },
-            "description": "Filter by incident IDs (MongoDB ObjectIDs). At most 100 entries.",
+            "description": "Filter by incident IDs (24-character hex). Used only by the incident list and export. At most 100 entries.",
             "maxItems": 100
           },
           "query": {
@@ -25115,19 +25643,19 @@
             "enum": [
               "created_at"
             ],
-            "description": "Sort field of the incident list; only `created_at` (incident creation time) is supported. Used by `/insight/incident/list` only."
+            "description": "Sort field of the incident list; only `created_at` (incident creation time, the default). Used by `/insight/incident/list` and `/insight/incident/export`."
           },
           "asc": {
             "type": "boolean",
-            "description": "Sort ascending when `true`, descending otherwise. Only used by `/insight/incident/list`."
+            "description": "Sort ascending when `true`, descending (default) otherwise. Used by the incident list and export; `/insight/alert/topk-by-label` has its own `asc`."
           },
           "is_my_team": {
             "type": "boolean",
-            "description": "Restrict results to teams the caller belongs to. When true and the caller has no teams, the result set is empty."
+            "description": "Restrict results to the caller's teams (intersected with `team_ids` when both are set). When the caller belongs to no team, the result is empty."
           },
           "time_zone": {
             "type": "string",
-            "description": "IANA time zone name used to cut day/week/month buckets (e.g. `Asia/Shanghai`). Optional; defaults to UTC, except that `/insight/incident/export` falls back to the account time zone and then `Asia/Shanghai`."
+            "description": "IANA time zone (for example `Asia/Shanghai` or `UTC`) used to cut `aggregate_unit` buckets; abbreviations such as `EST` and `Etc/GMT±N` are rejected. Defaults to UTC. `/insight/incident/export` uses it to render times, falling back to the account time zone and then `Asia/Shanghai`."
           },
           "seconds_to_close_from": {
             "type": "integer",
@@ -25219,7 +25747,7 @@
           "total": {
             "type": "integer",
             "format": "int64",
-            "description": "Total matching incidents."
+            "description": "Number of matching incidents. When the request carried `search_after_ctx`, only incidents after the cursor are counted."
           },
           "has_next_page": {
             "type": "boolean",
@@ -25234,7 +25762,7 @@
             "items": {
               "$ref": "#/components/schemas/IncidentRawItem"
             },
-            "description": "Incident items."
+            "description": "Incidents on this page; an empty array when none match."
           }
         }
       },
@@ -25249,7 +25777,7 @@
             "properties": {
               "split_hours": {
                 "type": "boolean",
-                "description": "When true, metrics are split into `work`/`sleep`/`off` hour buckets."
+                "description": "When `true`, each bucket is further split into `work`, `sleep` and `off` hours, returned as separate rows with `hours` set."
               },
               "aggregate_unit": {
                 "type": "string",
@@ -25258,7 +25786,7 @@
                   "week",
                   "month"
                 ],
-                "description": "Aggregates metrics by time granularity. When set, the time range must be at least 24 hours; with `day` granularity the range must not exceed 31 days. `day` buckets by calendar day, `week` by calendar week, and `month` by calendar month, with boundaries aligned to `time_zone`."
+                "description": "Split the range into time buckets; omit for a single bucket covering the whole range. Requires a range of at least 24 hours, and `day` allows at most 31 days.\n- `day`: calendar days in `time_zone` (the first bucket runs from `start_time` to the next midnight).\n- `week`: consecutive 7-day buckets starting at `start_time` (not aligned to Monday).\n- `month`: calendar months in `time_zone` (the first bucket runs from `start_time` to the 1st of the next month)."
               }
             }
           }
@@ -25285,7 +25813,7 @@
               },
               "k": {
                 "type": "integer",
-                "description": "Number of top entries to return, between 1 and 100. Defaults to 20.",
+                "description": "Number of label values to return, between 1 and 100 (default 20). With `split_hours`, applied per hour bucket.",
                 "minimum": 1,
                 "maximum": 100,
                 "default": 20
@@ -25339,7 +25867,7 @@
           "p": {
             "type": "integer",
             "minimum": 1,
-            "description": "Page number (1-based)."
+            "description": "Page number, starting at 1. Always pass it: when omitted the first page is returned but `has_next_page` is unreliable."
           },
           "limit": {
             "type": "integer",
@@ -25357,7 +25885,7 @@
               "channel_name",
               "last_incident_at"
             ],
-            "description": "Field used to order results. Defaults to `created_at`."
+            "description": "Sort field, default `created_at`. `ranking` uses the caller's own channel order saved in the console and falls back to creation order when none is saved; `channel_name` sorts case-insensitively."
           },
           "asc": {
             "type": "boolean",
@@ -25365,19 +25893,19 @@
           },
           "is_my_managed": {
             "type": "boolean",
-            "description": "When true, return only channels the caller manages."
+            "description": "When true, return only channels owned by one of the caller's teams or created by the caller. Takes precedence over `is_my_team` and `is_my_starred`."
           },
           "is_my_starred": {
             "type": "boolean",
-            "description": "When true, return only channels the caller has starred. Mutually exclusive with `is_my_team`."
+            "description": "When true, return only channels the caller has starred. Cannot be combined with `is_my_team`."
           },
           "is_brief": {
             "type": "boolean",
-            "description": "When true, return only `channel_id`, `channel_name`, `description` and `status`, and return all matches without pagination."
+            "description": "When true, return only `channel_id`, `channel_name`, `description`, `status` and `is_starred` for each channel, with all matches in one page."
           },
           "is_my_team": {
             "type": "boolean",
-            "description": "When true, return channels owned by the caller's teams. Mutually exclusive with `is_my_starred`."
+            "description": "When true, return only channels whose owning team is one of the caller's teams. Cannot be combined with `is_my_starred`."
           },
           "team_ids": {
             "type": "array",
@@ -25385,7 +25913,7 @@
               "type": "integer",
               "format": "int64"
             },
-            "description": "Filter by team IDs."
+            "description": "Return only channels owned by these teams. Ignored when `is_my_managed` or `is_my_team` is true."
           },
           "query": {
             "type": "string",
@@ -25423,11 +25951,11 @@
           "total": {
             "type": "integer",
             "format": "int64",
-            "description": "Total matching channels."
+            "description": "Total number of matching channels across all pages."
           },
           "has_next_page": {
             "type": "boolean",
-            "description": "Whether more pages are available."
+            "description": "Whether more pages follow. Reliable only when `p` is passed."
           }
         }
       },
@@ -25457,7 +25985,7 @@
             "items": {
               "$ref": "#/components/schemas/EscalateRuleItem"
             },
-            "description": "All escalation rules of the channel, excluding deleted ones, ordered by priority ascending."
+            "description": "Escalation rules of the channel, excluding deleted ones, in evaluation order: ascending `priority`, then creation time."
           }
         }
       },
@@ -25514,7 +26042,7 @@
             "items": {
               "$ref": "#/components/schemas/AlertInfo"
             },
-            "description": "Alert list."
+            "description": "Alerts on the requested page; an empty array when no alert matches."
           },
           "total": {
             "type": "integer",
@@ -25539,7 +26067,8 @@
             "type": "integer",
             "format": "int64",
             "minimum": 1,
-            "description": "Page number starting at 1."
+            "description": "Page number starting at 1.",
+            "default": 1
           },
           "limit": {
             "type": "integer",
@@ -25558,7 +26087,7 @@
             "items": {
               "$ref": "#/components/schemas/IncidentFeedType"
             },
-            "description": "Optional filter restricting the returned entries to specific types."
+            "description": "Return only entries of these types; omit to return all types."
           }
         }
       },
@@ -25642,9 +26171,13 @@
             "type": "boolean",
             "description": "When true, include only outlier (rare) incidents."
           },
+          "has_unfinished_work_item": {
+            "type": "boolean",
+            "description": "When true, include only incidents that still have an action item or follow-up that is neither `done` nor `cancelled`. `false` applies no filter."
+          },
           "progress": {
             "type": "string",
-            "description": "Comma-separated list of progress states to match (e.g. `Triggered,Processing`)."
+            "description": "Comma-separated progress states to match, for example `Triggered,Processing`. Values: `Triggered` not yet acknowledged; `Processing` acknowledged and being handled; `Closed` resolved. Omit to match every state."
           },
           "query": {
             "type": "string",
@@ -25652,7 +26185,7 @@
           },
           "incident_severity": {
             "type": "string",
-            "description": "Comma-separated list of severities (`Critical,Warning,Info`)."
+            "description": "Comma-separated severities to match, for example `Critical,Warning`. Values: `Critical` most severe, `Warning`, `Info` least severe."
           },
           "channel_ids": {
             "type": "array",
@@ -25732,7 +26265,7 @@
           },
           "search_after_ctx": {
             "type": "string",
-            "description": "Cursor from a previous response for forward pagination."
+            "description": "Cursor from the previous response's `search_after_ctx`; when set, `p` is ignored."
           }
         }
       },
@@ -25838,7 +26371,8 @@
               "created_at_seconds",
               "updated_at_seconds"
             ],
-            "description": "Field used to order results."
+            "description": "Sort field: `created_at_seconds` creation time, `updated_at_seconds` last update time.",
+            "default": "created_at_seconds"
           },
           "asc": {
             "type": "boolean",
@@ -25908,7 +26442,7 @@
               "type": "integer",
               "format": "int64"
             },
-            "description": "Integration IDs to fetch routing rules for.",
+            "description": "Shared integration IDs to fetch routing rules for, at least one; obtain them from `POST /integration/list`.",
             "minItems": 1
           }
         }
@@ -25996,7 +26530,7 @@
             "type": "integer",
             "minimum": 1,
             "maximum": 100,
-            "description": "Page size."
+            "description": "Number of records per page, 1–100."
           },
           "asc": {
             "type": "boolean",
@@ -26018,7 +26552,7 @@
             "type": "integer",
             "format": "int64",
             "minimum": 0,
-            "description": "Filter by webhook integration ID."
+            "description": "Filter by webhook integration ID; `0` or omitted returns all integrations."
           },
           "event_types": {
             "type": "array",
@@ -26069,7 +26603,7 @@
           },
           "total": {
             "type": "integer",
-            "description": "Total number of matching records.",
+            "description": "Total number of records matching the filters, not capped.",
             "format": "int64"
           },
           "search_after_ctx": {
@@ -26088,7 +26622,7 @@
           "api_name": {
             "type": "string",
             "maxLength": 199,
-            "description": "Unique API name (max 199 chars)."
+            "description": "Name of the mapping API, unique among non-deleted mapping APIs (max 199 characters)."
           },
           "description": {
             "type": "string",
@@ -26098,7 +26632,7 @@
             "type": "string",
             "format": "uri",
             "maxLength": 500,
-            "description": "HTTP/HTTPS endpoint URL (max 500 chars)."
+            "description": "Endpoint called with `POST`. Must be an `http` or `https` URL of at most 500 characters; in SaaS the host must not resolve to an internal IP address."
           },
           "insecure_skip_verify": {
             "type": "boolean",
@@ -26113,20 +26647,22 @@
           },
           "timeout": {
             "type": "integer",
-            "description": "Request timeout in seconds (1–3). Default 2.",
+            "description": "Timeout of the whole request in seconds (1–3). Defaults to 2 when omitted or 0.",
             "minimum": 1,
-            "maximum": 3
+            "maximum": 3,
+            "default": 2
           },
           "retry_count": {
             "type": "integer",
-            "description": "Number of retries on failure (0–1). Default 0.",
+            "description": "Number of retries after a failed call (0–1). Defaults to 0.",
             "minimum": 0,
-            "maximum": 1
+            "maximum": 1,
+            "default": 0
           },
           "team_id": {
             "type": "integer",
             "format": "int64",
-            "description": "Owning team ID; obtain it from `POST /team/list`."
+            "description": "Owning team ID; obtain it from `POST /team/list`. `0` or omitted means no team. A non-zero ID must be an existing team."
           }
         }
       },
@@ -26139,7 +26675,7 @@
           },
           "api_name": {
             "type": "string",
-            "description": "API name."
+            "description": "Name of the created mapping API, as sent in the request."
           }
         },
         "required": [
@@ -26169,11 +26705,11 @@
           },
           "api_name": {
             "type": "string",
-            "description": "API name."
+            "description": "Name of the mapping API, unique among non-deleted mapping APIs."
           },
           "description": {
             "type": "string",
-            "description": "Description."
+            "description": "Free-text description (at most 500 characters); an empty string when none was given."
           },
           "url": {
             "type": "string",
@@ -26187,15 +26723,15 @@
             "additionalProperties": {
               "type": "string"
             },
-            "description": "Custom request headers. `null` when none are configured."
+            "description": "Request headers sent with every call, returned in plain text. `null` when none are configured."
           },
           "timeout": {
             "type": "integer",
-            "description": "Request timeout in seconds."
+            "description": "Timeout of the whole request in seconds (1–3)."
           },
           "retry_count": {
             "type": "integer",
-            "description": "Retry count."
+            "description": "Number of retries after a failed call: `0` or `1`."
           },
           "insecure_skip_verify": {
             "type": "boolean",
@@ -26260,7 +26796,7 @@
         "properties": {
           "total": {
             "type": "integer",
-            "description": "Total API count."
+            "description": "Number of items returned; the list is not paginated."
           },
           "items": {
             "type": "array",
@@ -26291,14 +26827,14 @@
               "null"
             ],
             "maxLength": 199,
-            "description": "New API name (max 199 chars)."
+            "description": "New name, unique among non-deleted mapping APIs (max 199 characters). Omit to keep."
           },
           "description": {
             "type": [
               "string",
               "null"
             ],
-            "description": "New description."
+            "description": "New description; longer than 500 characters is truncated. Omit to keep, send `\"\"` to clear."
           },
           "url": {
             "type": [
@@ -26307,28 +26843,28 @@
             ],
             "format": "uri",
             "maxLength": 500,
-            "description": "New endpoint URL (max 500 chars)."
+            "description": "New `http`/`https` endpoint (max 500 characters); in SaaS the host must not resolve to an internal IP. Omit to keep."
           },
           "insecure_skip_verify": {
             "type": [
               "boolean",
               "null"
             ],
-            "description": "New TLS skip-verify setting."
+            "description": "New TLS skip-verify setting. Omit to keep."
           },
           "headers": {
             "type": "object",
             "additionalProperties": {
               "type": "string"
             },
-            "description": "Custom HTTP request headers. In SaaS mode, security-sensitive names (`authorization`, `cookie`, `x-forwarded-for`, etc.) are rejected; keys must be RFC 7230 token characters (max 1024 chars) and values max 4096 chars."
+            "description": "Replaces the whole header map when sent; send `{}` to remove all headers. Omit to keep. In SaaS, sensitive header names (see `/enrichment/mapping/api/create`) are rejected; keys are at most 1,024 characters and values at most 4,096."
           },
           "timeout": {
             "type": [
               "integer",
               "null"
             ],
-            "description": "New timeout in seconds.",
+            "description": "New whole-request timeout in seconds (1–3). Omit to keep.",
             "minimum": 1,
             "maximum": 3
           },
@@ -26337,7 +26873,7 @@
               "integer",
               "null"
             ],
-            "description": "New retry count.",
+            "description": "New retry count (0–1). Omit to keep.",
             "minimum": 0,
             "maximum": 1
           },
@@ -26347,7 +26883,7 @@
               "null"
             ],
             "format": "int64",
-            "description": "New owning team ID; obtain it from `POST /team/list`."
+            "description": "New owning team ID from `POST /team/list`; `0` removes the team. Omit to keep."
           }
         }
       },
@@ -26368,7 +26904,7 @@
               "type": "string"
             },
             "maxItems": 100,
-            "description": "Keys of rows to delete."
+            "description": "Row keys to delete (at most 100), as returned in `key` by `/enrichment/mapping/data/list` or in `keys` by `/enrichment/mapping/data/upsert`. Keys that match no row are ignored."
           }
         }
       },
@@ -26390,7 +26926,7 @@
           "created_at": {
             "type": "integer",
             "format": "int64",
-            "description": "Creation time, Unix seconds. Omitted when 0."
+            "description": "Time the row was last written, Unix seconds; a replaced row gets a new value. Omitted when 0."
           },
           "updated_at": {
             "type": "integer",
@@ -26426,7 +26962,8 @@
           },
           "asc": {
             "type": "boolean",
-            "description": "Sort ascending when `true`."
+            "description": "Sort ascending when `true`; defaults to `false` (newest first).",
+            "default": false
           },
           "p": {
             "type": [
@@ -26464,16 +27001,21 @@
             "items": {
               "$ref": "#/components/schemas/MappingDataItem"
             },
-            "description": "Data rows."
+            "description": "Data rows of this page, ordered by `orderby`/`asc`. Empty when nothing matches."
           },
           "total": {
             "type": "integer",
             "format": "int64",
-            "description": "Total matching rows."
+            "description": "Number of rows matching `query`, counted up to 1,000; a value of 1,000 means at least 1,000."
           },
           "has_next_page": {
             "type": "boolean",
-            "description": "Whether more pages exist."
+            "description": "`true` when more rows follow this page."
+          },
+          "used_cnt": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Total number of rows stored in the schema, regardless of `query`. Compare it with the schema row limit (10,000 by default)."
           },
           "search_after_ctx": {
             "type": "string",
@@ -26483,7 +27025,8 @@
         "required": [
           "items",
           "total",
-          "has_next_page"
+          "has_next_page",
+          "used_cnt"
         ]
       },
       "MappingDataUpsertRequest": {
@@ -26506,7 +27049,7 @@
               }
             },
             "maxItems": 1000,
-            "description": "Rows to insert or update. Each row must include all source and result labels; unknown labels are silently dropped; a value longer than 2048 characters is rejected."
+            "description": "Rows to insert or replace (at most 1,000). Each row maps label names to values and must include every source and result label; other keys are dropped; a value longer than 2,048 bytes is rejected. A row whose source label values match an existing row replaces it."
           }
         }
       },
@@ -26518,7 +27061,7 @@
             "items": {
               "type": "string"
             },
-            "description": "Composite keys of upserted rows."
+            "description": "Row keys of the written rows (one per distinct row, in no particular order); use them with `/enrichment/mapping/data/delete`."
           }
         },
         "required": [
@@ -26536,7 +27079,7 @@
           "schema_name": {
             "type": "string",
             "maxLength": 39,
-            "description": "Unique schema name (max 39 chars)."
+            "description": "Schema name, unique among the account's non-deleted schemas (max 39 characters)."
           },
           "description": {
             "type": "string",
@@ -26546,7 +27089,7 @@
           "team_id": {
             "type": "integer",
             "format": "int64",
-            "description": "Owning team ID. `0` means no team."
+            "description": "Owning team ID from `POST /team/list`. `0` or omitted means no team; a non-zero ID must be an existing team."
           },
           "source_labels": {
             "type": "array",
@@ -26556,7 +27099,8 @@
             },
             "maxItems": 3,
             "description": "Lookup key label names (1–3). Each must match `^[a-zA-Z_][a-zA-Z0-9_]*$`; entries must be unique and must not overlap with `result_labels`.",
-            "uniqueItems": true
+            "uniqueItems": true,
+            "minItems": 1
           },
           "result_labels": {
             "type": "array",
@@ -26566,7 +27110,8 @@
             },
             "maxItems": 10,
             "description": "Output label names written on a match (1–10). Each must match `^[a-zA-Z_][a-zA-Z0-9_]*$`; entries must be unique and must not overlap with `source_labels`.",
-            "uniqueItems": true
+            "uniqueItems": true,
+            "minItems": 1
           }
         }
       },
@@ -26579,7 +27124,7 @@
           },
           "schema_name": {
             "type": "string",
-            "description": "Schema name."
+            "description": "Name of the created schema, as sent in the request."
           }
         },
         "required": [
@@ -26609,7 +27154,7 @@
           },
           "schema_name": {
             "type": "string",
-            "description": "Schema name."
+            "description": "Schema name, unique among the account's non-deleted schemas."
           },
           "description": {
             "type": "string",
@@ -26620,14 +27165,14 @@
             "items": {
               "type": "string"
             },
-            "description": "Lookup key label names."
+            "description": "Label names whose values form the lookup key of a data row (1–3); fixed at creation."
           },
           "result_labels": {
             "type": "array",
             "items": {
               "type": "string"
             },
-            "description": "Output label names."
+            "description": "Label names written to the event when a row matches (1–10); fixed at creation."
           },
           "status": {
             "type": "string",
@@ -26640,7 +27185,7 @@
           "team_id": {
             "type": "integer",
             "format": "int64",
-            "description": "Owning team ID."
+            "description": "Owning team ID; `0` when the schema belongs to no team."
           },
           "creator_id": {
             "type": "integer",
@@ -26685,7 +27230,7 @@
         "properties": {
           "total": {
             "type": "integer",
-            "description": "Total schema count."
+            "description": "Number of items returned; the list is not paginated."
           },
           "items": {
             "type": "array",
@@ -26716,7 +27261,7 @@
               "null"
             ],
             "maxLength": 39,
-            "description": "New schema name (max 39 chars)."
+            "description": "New name, unique among non-deleted schemas (max 39 characters). Omit to keep."
           },
           "description": {
             "type": [
@@ -26724,7 +27269,7 @@
               "null"
             ],
             "maxLength": 500,
-            "description": "New description (max 500 chars)."
+            "description": "New description (max 500 characters). Omit to keep, send `\"\"` to clear."
           },
           "team_id": {
             "type": [
@@ -26732,7 +27277,7 @@
               "null"
             ],
             "format": "int64",
-            "description": "New owning team ID. `0` removes the team association."
+            "description": "New owning team ID from `POST /team/list`; `0` removes the team. Omit to keep."
           }
         }
       },
@@ -26776,7 +27321,7 @@
           },
           "remove_source_incidents": {
             "type": "boolean",
-            "description": "When true, soft-delete the source incidents after merging instead of closing them."
+            "description": "When true, permanently delete the source incidents after their alerts move to the target. When false, the sources are closed and kept."
           }
         }
       },
@@ -26796,7 +27341,7 @@
           "ts": {
             "type": "integer",
             "format": "int64",
-            "description": "Start of the aggregation bucket, Unix epoch seconds. Equals `start_time` when no `aggregate_unit` is given."
+            "description": "Start of the time bucket, Unix seconds. Equals `start_time` when `aggregate_unit` is not set."
           },
           "channel_id": {
             "type": "integer",
@@ -26806,7 +27351,7 @@
           "team_id": {
             "type": "integer",
             "format": "int64",
-            "description": "Team ID, returned only when aggregating by team (`/insight/team`)."
+            "description": "Team ID, returned only by `/insight/team`. Omitted on the row that aggregates incidents without a team."
           },
           "responder_id": {
             "type": "integer",
@@ -26842,7 +27387,7 @@
           },
           "source_page_id": {
             "type": "string",
-            "description": "Atlassian Statuspage source page ID."
+            "description": "Atlassian Statuspage source page ID; only letters, digits, `_`, and `-` are accepted."
           },
           "target_page_id": {
             "type": "integer",
@@ -26865,7 +27410,7 @@
           },
           "source_page_id": {
             "type": "string",
-            "description": "Atlassian Statuspage source page ID."
+            "description": "Atlassian Statuspage source page ID; only letters, digits, `_`, and `-` are accepted."
           },
           "url_name": {
             "type": [
@@ -26896,7 +27441,7 @@
           },
           "failed_reason": {
             "type": "string",
-            "description": "Failure reason if delivery did not succeed."
+            "description": "Localized, human-readable reason the delivery failed, as reported by the delivery channel; omitted when delivery succeeded or no failure was reported. The text is not a fixed code set."
           }
         }
       },
@@ -26911,7 +27456,7 @@
           },
           "failed_reason": {
             "type": "string",
-            "description": "Failure reason if delivery did not succeed."
+            "description": "Localized, human-readable reason the delivery failed, as reported by the delivery channel; omitted when delivery succeeded or no failure was reported. The text is not a fixed code set."
           },
           "sms_content": {
             "type": "string",
@@ -26933,7 +27478,7 @@
           },
           "failed_reason": {
             "type": "string",
-            "description": "Failure reason if delivery did not succeed."
+            "description": "Localized, human-readable reason the delivery failed, as reported by the delivery channel; omitted when delivery succeeded or no failure was reported. The text is not a fixed code set."
           }
         }
       },
@@ -26997,7 +27542,7 @@
           "person_id": {
             "type": "integer",
             "format": "int64",
-            "description": "Member ID."
+            "description": "Member ID; the same ID that `POST /member/list` returns."
           },
           "person_name": {
             "type": "string",
@@ -27069,7 +27614,8 @@
           "meta",
           "basics",
           "content",
-          "follow_ups"
+          "follow_ups",
+          "has_active_incident"
         ],
         "properties": {
           "meta": {
@@ -27087,22 +27633,28 @@
             "properties": {
               "incidents_highest_severity": {
                 "type": "string",
-                "description": "Highest severity among linked incidents."
+                "description": "Highest severity among linked incidents: `Critical`, `Warning`, or `Info`; `Ok` only when it was set manually.",
+                "enum": [
+                  "Critical",
+                  "Warning",
+                  "Info",
+                  "Ok"
+                ]
               },
               "incidents_earliest_start_seconds": {
                 "type": "integer",
                 "format": "int64",
-                "description": "Earliest start time among linked incidents (seconds)."
+                "description": "Earliest start time among linked incidents (Unix seconds)."
               },
               "incidents_latest_close_seconds": {
                 "type": "integer",
                 "format": "int64",
-                "description": "Latest close time among linked incidents (seconds)."
+                "description": "Latest close time among linked incidents (Unix seconds); an incident not yet closed contributes its `end_time`."
               },
               "incidents_total_duration_seconds": {
                 "type": "integer",
                 "format": "int64",
-                "description": "Cumulative duration in seconds."
+                "description": "Seconds from the earliest start to the latest close among linked incidents (not the sum of each incident's duration)."
               },
               "responders": {
                 "type": "array",
@@ -27130,6 +27682,10 @@
           "follow_ups": {
             "type": "string",
             "description": "Follow-up action items rendered as a single string."
+          },
+          "has_active_incident": {
+            "type": "boolean",
+            "description": "`true` when at least one linked incident is not closed yet; follow-ups stay locked until all are closed. Computed per request."
           }
         }
       },
@@ -27158,7 +27714,7 @@
           "account_id": {
             "type": "integer",
             "format": "int64",
-            "description": "Account ID."
+            "description": "ID of the account that owns this record; the same for every record returned to one `app_key`."
           },
           "title": {
             "type": "string",
@@ -27174,7 +27730,7 @@
           },
           "post_mortem_id": {
             "type": "string",
-            "description": "Deterministic post-mortem ID derived from account and incident IDs."
+            "description": "Post-mortem ID: a 32-character hex string derived from the account ID and the linked incident IDs."
           },
           "template_id": {
             "type": "string",
@@ -27278,7 +27834,7 @@
           "reason": {
             "type": "string",
             "maxLength": 1024,
-            "description": "Optional reason recorded on the timeline."
+            "description": "Optional free-text reason, recorded on the `i_reopen` timeline entry. At most 1,024 characters."
           }
         }
       },
@@ -27297,10 +27853,10 @@
           },
           "field_name": {
             "type": "string",
-            "description": "Custom field name; must match a field defined on the account."
+            "description": "Custom field name (the field's `field_name`, not its display name). The field must exist and be enabled; list fields with `POST /field/list`."
           },
           "field_value": {
-            "description": "New field value. Type must match the field definition."
+            "description": "New value. Its type must match the field: `checkbox` takes a boolean, `single_select` one of the options, `multi_select` an array of options, `text` a string. Omit it or send `null` to clear the field."
           }
         }
       },
@@ -27482,7 +28038,7 @@
             "items": {
               "$ref": "#/components/schemas/ResponderInsightItem"
             },
-            "description": "Incident response metric rows aggregated by responder; further split by hour bucket or time bucket when `split_hours` or `aggregate_unit` is enabled."
+            "description": "Per-responder metric rows, newest bucket first. Responders without incidents in a bucket produce no row."
           }
         }
       },
@@ -27495,7 +28051,7 @@
         "properties": {
           "if": {
             "type": "array",
-            "description": "List of match conditions that are AND-ed together.",
+            "description": "Conditions joined with AND; an empty list matches every event. Required.",
             "items": {
               "$ref": "#/components/schemas/RouteMatchCondition"
             }
@@ -27513,7 +28069,7 @@
           },
           "fallthrough": {
             "type": "boolean",
-            "description": "If `true`, evaluation continues to the next case after this one matches; otherwise matching stops at the first hit."
+            "description": "When `true`, evaluation continues with the next case after this one matches and the channels of all matched cases are combined; when `false`, evaluation stops at this case."
           },
           "routing_mode": {
             "type": "string",
@@ -27521,11 +28077,11 @@
               "standard",
               "name_mapping"
             ],
-            "description": "Routing mode. `standard` (default, also used when left empty) routes to the fixed channel IDs; `name_mapping` resolves channels by reading a label value from the alert event."
+            "description": "Routing mode. `standard` routes to the fixed `channel_ids`; `name_mapping` routes to the enabled channel whose name equals the value of `name_mapping_label` on the event. An empty value is treated as `standard` and is omitted in responses."
           },
           "name_mapping_label": {
             "type": "string",
-            "description": "Label key whose value is used as the target channel name. Required when `routing_mode` is `name_mapping`."
+            "description": "Event field whose value is used as the target channel name, for example `labels.service`. Required when `routing_mode` is `name_mapping`; if no enabled channel has that name, the case adds no channel."
           }
         }
       },
@@ -27539,7 +28095,7 @@
               "type": "integer",
               "format": "int64"
             },
-            "description": "Channel IDs to fall back to."
+            "description": "Channels used when no case yields a channel. An empty list is treated as no default branch."
           }
         }
       },
@@ -27553,14 +28109,14 @@
           "integration_id": {
             "type": "integer",
             "format": "int64",
-            "description": "Integration ID. Must be greater than 0.",
+            "description": "Shared integration ID, greater than 0; obtain it from `POST /integration/list`.",
             "exclusiveMinimum": 0
           }
         }
       },
       "RouteItem": {
         "type": "object",
-        "description": "Routing rule of an integration. Alerts are evaluated against `cases` in order; unmatched alerts fall through to `default`. Returns `null` when the integration has no configured rule.",
+        "description": "Routing rule of a shared integration. Alerts are evaluated against `cases` in order; when no case yields a channel, `default` is used.",
         "required": [
           "version",
           "updated_by",
@@ -27595,12 +28151,12 @@
               "enabled",
               "deleted"
             ],
-            "description": "Route status. `enabled` means active; `deleted` means removed, visible only in historical versions."
+            "description": "Rule status. These endpoints return only `enabled` rules; `deleted` rules (for example of a deleted integration) are not returned."
           },
           "version": {
             "type": "integer",
             "format": "int64",
-            "description": "Monotonic version number, incremented on each update. Use it for optimistic concurrency control."
+            "description": "Version number, increased on every `POST /route/upsert`. The server does not use it for concurrency checks."
           },
           "updated_by": {
             "type": "integer",
@@ -27615,7 +28171,7 @@
           "deleted_at": {
             "type": "integer",
             "format": "int64",
-            "description": "Soft-delete timestamp, Unix seconds. Omitted when the rule is active."
+            "description": "Soft-delete time, Unix timestamp in seconds. Not returned by these endpoints, which return only active rules."
           },
           "created_at": {
             "type": "integer",
@@ -27640,7 +28196,7 @@
         "properties": {
           "key": {
             "type": "string",
-            "description": "Field key to match against the alert event (e.g. `alert_severity`, `labels.service`)."
+            "description": "Alert or change event field to match: `title`, `description`, `severity` (alias `alert_severity`, `event_severity`), `status`, `alert_key`, `change_key`, `title_rule`, `integration_id` (alias `data_source_id`), or any `labels.<name>`. An unknown key returns `InvalidParameter`."
           },
           "oper": {
             "type": "string",
@@ -27648,14 +28204,14 @@
               "IN",
               "NOTIN"
             ],
-            "description": "Match operator. `IN` matches when the field value is one of `vals`; `NOTIN` matches when it is not."
+            "description": "Match operator. `IN` matches when the field value matches any entry in `vals`; `NOTIN` matches when it matches none. A missing field never matches `IN` and always matches `NOTIN`."
           },
           "vals": {
             "type": "array",
             "items": {
               "type": "string"
             },
-            "description": "Values to compare against. Each value may be a literal string, a wildcard (`*`, `?`), a regular expression wrapped in slashes (`/pattern/`), a CIDR (`cidr:10.0.0.0/8`), or a numeric comparison (`num:lt:100`)."
+            "description": "Values to compare, at least one. Each entry is matched as: an exact string; a wildcard pattern when it contains `*` or `?` (must match the whole value); a regular expression when wrapped in slashes, such as `/^db-/` (may match anywhere in the value); an IP range written `cidr:<network>`, such as `cidr:203.0.113.0/24`; or a numeric comparison `num:<op>:<number>` with `lt`, `le`, `gt` or `ge`, such as `num:gt:90`."
           }
         }
       },
@@ -27707,15 +28263,19 @@
         "properties": {
           "layer_name": {
             "type": "string",
-            "description": "Layer display name."
+            "description": "Layer name; empty string in `final_schedule`."
           },
           "name": {
             "type": "string",
-            "description": "Layer internal name."
+            "description": "Same as `layer_name`."
           },
           "mode": {
             "type": "integer",
-            "description": "Layer mode: 0 = common rotation, 1 = override."
+            "enum": [
+              0,
+              1
+            ],
+            "description": "Type of the source layer: `0` = rotation layer, `1` = override layer. Always `0` in `final_schedule`."
           },
           "schedules": {
             "type": [
@@ -27750,12 +28310,19 @@
             "description": "Shift end timestamp (Unix seconds)."
           },
           "group": {
-            "$ref": "#/components/schemas/ScheduleGroup",
-            "description": "Oncall group covering the shift; null marks a coverage gap."
+            "oneOf": [
+              {
+                "$ref": "#/components/schemas/ScheduleGroup"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "Group on call during the shift; `null` marks a gap with nobody on call."
           },
           "index": {
             "type": "integer",
-            "description": "Index inside the rotation."
+            "description": "Zero-based position, in the schedule's layer list, of the layer the shift comes from."
           }
         }
       },
@@ -27773,7 +28340,7 @@
               "minimum": 0,
               "maximum": 6
             },
-            "description": "Weekday numbers (0 = Sunday) included in the rotation. Conflicts with restrict_mode = 2 (week)."
+            "description": "Weekdays on which the layer is on call: `0` = Sunday … `6` = Saturday, in the schedule's time zone. Empty or all seven days means every day. Cannot be combined with `restrict_mode` 2."
           }
         }
       },
@@ -27845,12 +28412,12 @@
           "start": {
             "type": "integer",
             "format": "int64",
-            "description": "Group start timestamp (Unix seconds)."
+            "description": "Start of the group's shift (Unix seconds) in computed results; `0` in layer definitions and ignored on input."
           },
           "end": {
             "type": "integer",
             "format": "int64",
-            "description": "Group end timestamp (Unix seconds)."
+            "description": "End of the group's shift (Unix seconds) in computed results; `0` in layer definitions and ignored on input."
           }
         }
       },
@@ -27870,7 +28437,7 @@
       },
       "ScheduleIDsBodyRequest": {
         "type": "object",
-        "description": "Request carrying a list of schedule IDs (used by delete/enable/disable).",
+        "description": "Request carrying a list of schedule IDs.",
         "required": [
           "schedule_ids"
         ],
@@ -27912,7 +28479,19 @@
         "properties": {
           "type": {
             "type": "string",
-            "description": "IM provider type (for example feishu_app, dingtalk_app, wecom_app, teams_app, slack_app)."
+            "enum": [
+              "feishu",
+              "dingtalk",
+              "wecom",
+              "slack",
+              "telegram",
+              "zoom",
+              "feishu_app",
+              "dingtalk_app",
+              "slack_app",
+              "teams_app"
+            ],
+            "description": "Where the notification goes:\n- `feishu`, `dingtalk`, `wecom`, `slack`: group robot webhook given by `settings.token`.\n- `telegram`: bot `settings.token` posting to `settings.chat_ids`.\n- `zoom`: Zoom robot with `settings.token` and `settings.verify_token`.\n- `feishu_app`, `dingtalk_app`, `slack_app`, `teams_app`: an IM integration (`settings.data_source_id`) posting to the group chats in `settings.chat_ids`.\nOther values are stored but never sent."
           },
           "settings": {
             "$ref": "#/components/schemas/ScheduleImNotifySettings",
@@ -27934,37 +28513,37 @@
         "properties": {
           "token": {
             "type": "string",
-            "description": "Webhook token."
+            "description": "Robot webhook token for `feishu`, `dingtalk`, `wecom`, `slack`, `telegram` and `zoom`; empty for the `*_app` types."
           },
           "alias": {
             "type": "string",
-            "description": "Channel alias."
+            "description": "Display alias for the entry; not used when sending."
           },
           "data_source_id": {
             "type": "integer",
             "format": "int64",
-            "description": "Data source ID."
+            "description": "ID of the IM integration used by the `*_app` types; `0` for robot types."
           },
           "chat_ids": {
             "type": "array",
             "items": {
               "type": "string"
             },
-            "description": "Chat IDs."
+            "description": "Target chat IDs: group chats of the IM integration for `*_app` types, or Telegram chat IDs for `telegram`."
           },
           "verify_token": {
             "type": "string",
-            "description": "Verification token."
+            "description": "Verification token, used by the `zoom` type."
           },
           "sign_secret": {
             "type": "string",
-            "description": "Signature secret."
+            "description": "Robot signing secret. Stored with the entry."
           }
         }
       },
       "ScheduleInfoRequest": {
         "type": "object",
-        "description": "Schedule detail request. start/end define the window for computed layers; the span must be less than 45 days.",
+        "description": "Schedule detail request. `start`/`end` set the window for computed shifts; at most 45 days apart.",
         "required": [
           "schedule_id",
           "start",
@@ -27990,12 +28569,13 @@
       },
       "ScheduleItem": {
         "type": "object",
-        "description": "Full schedule detail returned by info/preview/list.",
+        "description": "On-call schedule as returned by info, list, infos, self and preview. Which computed fields are filled depends on the endpoint — see each operation's notes.",
         "required": [
           "id",
           "name",
           "account_id",
           "group_id",
+          "time_zone",
           "disabled",
           "create_at",
           "create_by",
@@ -28033,7 +28613,7 @@
           "account_id": {
             "type": "integer",
             "format": "int64",
-            "description": "Account ID."
+            "description": "ID of the account that owns the schedule."
           },
           "group_id": {
             "type": [
@@ -28043,12 +28623,21 @@
             "format": "int64",
             "description": "Legacy team/group ID. null when returned from /schedule/preview."
           },
+          "time_zone": {
+            "type": "string",
+            "description": "IANA time zone (for example `Asia/Shanghai`) in which the schedule's handoffs, restriction windows, weekdays and fixed-time notifications are evaluated. Set at creation and immutable. An empty string means none was set and the schedule is evaluated in `Asia/Shanghai`."
+          },
           "disabled": {
             "type": [
               "integer",
               "null"
             ],
-            "description": "Disabled flag (0 = enabled, 1 = disabled). Deprecated. null when returned from /schedule/preview."
+            "enum": [
+              0,
+              1,
+              null
+            ],
+            "description": "Whether the schedule is disabled: `0` = enabled, `1` = disabled (disabled schedules send no shift notifications and are skipped by `/schedule/self` and `/schedule/by-person`). Same value as `status`. `null` in `/schedule/preview` unless sent."
           },
           "create_at": {
             "type": "integer",
@@ -28080,10 +28669,6 @@
             },
             "description": "Rotation layers defined on the schedule. Null when layers were not loaded (for example by `/schedule/infos`, or by `/schedule/list` without start/end)."
           },
-          "field": {
-            "type": "string",
-            "description": "Field name used by the legacy update-field endpoint."
-          },
           "schedule_layers": {
             "type": [
               "array",
@@ -28092,25 +28677,32 @@
             "items": {
               "$ref": "#/components/schemas/ScheduleCalculatedLayer"
             },
-            "description": "Computed per-layer schedules for the requested window. Null when not computed."
+            "description": "Shifts of each visible (non-hidden) layer in the requested window. `null` when no window was computed (`/schedule/infos`, `/schedule/self`, `/schedule/list` without `start`/`end`)."
           },
           "final_schedule": {
             "$ref": "#/components/schemas/ScheduleCalculatedLayer",
-            "description": "Collapsed final schedule across all layers."
+            "description": "All layers merged into one timeline for the window: where layers overlap, override layers win over rotation layers and later layers win over earlier ones. In `/schedule/self` it keeps only the caller's shifts. Empty (`schedules` is `null`) when nothing was computed."
           },
           "start": {
             "type": "integer",
             "format": "int64",
-            "description": "Window start (Unix seconds). Omitted when 0 (no window requested)."
+            "description": "Window start (Unix seconds). Only echoed by `/schedule/preview`; omitted elsewhere."
           },
           "end": {
             "type": "integer",
             "format": "int64",
-            "description": "Window end (Unix seconds). Omitted when 0 (no window requested)."
+            "description": "Window end (Unix seconds). Only echoed by `/schedule/preview`; omitted elsewhere."
           },
           "notify": {
-            "$ref": "#/components/schemas/ScheduleNotify",
-            "description": "Notification configuration. Null when the schedule has none."
+            "oneOf": [
+              {
+                "$ref": "#/components/schemas/ScheduleNotify"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "Shift notification configuration; `null` when the schedule has none."
           },
           "schedule_id": {
             "type": [
@@ -28150,28 +28742,47 @@
             "items": {
               "$ref": "#/components/schemas/ScheduleCalculatedLayer"
             },
-            "description": "Alias of schedule_layers returned for compatibility. Null when not computed."
+            "description": "Same content as `schedule_layers`, filled by `/schedule/info` and `/schedule/preview` only; `null` elsewhere."
           },
           "status": {
             "type": [
               "integer",
               "null"
             ],
-            "description": "Legacy status flag. Deprecated. null when returned from /schedule/preview."
+            "enum": [
+              0,
+              1,
+              null
+            ],
+            "description": "Mirror of `disabled`: `0` = enabled, `1` = disabled. Send it on `/schedule/update` to enable or disable a schedule. `null` in `/schedule/preview` unless sent."
           },
           "cur_oncall": {
-            "$ref": "#/components/schemas/ScheduleOncallGroup",
-            "description": "Current on-call group, or null when nobody is on-call."
+            "oneOf": [
+              {
+                "$ref": "#/components/schemas/ScheduleOncallGroup"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "The shift in progress now; `null` when nobody is on call, or when the endpoint does not compute it (`/schedule/infos`, `/schedule/self`, `/schedule/list` without a window)."
           },
           "next_oncall": {
-            "$ref": "#/components/schemas/ScheduleOncallGroup",
-            "description": "Next on-call group, or null when unknown."
+            "oneOf": [
+              {
+                "$ref": "#/components/schemas/ScheduleOncallGroup"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "The next shift with someone on duty after the current one; `null` when none is found within 45 days or the endpoint does not compute it."
           }
         }
       },
       "ScheduleLayer": {
         "type": "object",
-        "description": "One rotation layer inside a schedule.",
+        "description": "One layer of a schedule. A rotation layer (`mode` 0) cycles through `groups`; an override layer (`mode` 1) puts its first group on call from `layer_start` to `layer_end`. Response-only fields (`account_id`, `schedule_id`, `create_*`, `update_*`) are ignored in requests.",
         "required": [
           "account_id",
           "name",
@@ -28202,24 +28813,28 @@
           "account_id": {
             "type": "integer",
             "format": "int64",
-            "description": "Account ID."
+            "description": "ID of the account that owns the layer. Set by the server."
           },
           "name": {
             "type": "string",
-            "description": "Layer internal name."
+            "description": "Layer name. Either `name` or `layer_name` is required; `layer_name` wins when both are set."
           },
           "schedule_id": {
             "type": "integer",
             "format": "int64",
-            "description": "Parent schedule ID."
+            "description": "ID of the schedule the layer belongs to. Set by the server."
           },
           "hidden": {
             "type": "integer",
-            "description": "Whether the layer is hidden in the UI (0 = no, 1 = yes)."
+            "enum": [
+              0,
+              1
+            ],
+            "description": "`1` leaves the layer out of `schedule_layers`; its shifts still feed `final_schedule`. `0` (default) shows it."
           },
           "mode": {
             "type": "integer",
-            "description": "Layer mode: 0 = common rotation, 1 = override.",
+            "description": "Layer type:\n- `0`: rotation layer — groups take turns according to `rotation_unit`/`rotation_value`.\n- `1`: override layer — the first group in `groups` is on call for the whole `layer_start`–`layer_end` period and takes precedence over rotation layers.",
             "enum": [
               0,
               1
@@ -28227,7 +28842,7 @@
           },
           "weight": {
             "type": "integer",
-            "description": "Layer weight for ordering."
+            "description": "Stored as sent; not used when computing shifts."
           },
           "groups": {
             "type": [
@@ -28237,31 +28852,31 @@
             "items": {
               "$ref": "#/components/schemas/ScheduleGroup"
             },
-            "description": "Oncall groups participating in the rotation. Null when not set."
+            "description": "On-call groups of the layer, in rotation order. Each group needs `group_name` (or `name`) and members with at least one person. `start`/`end` are ignored on input."
           },
           "rotation_duration": {
             "type": "integer",
             "format": "int64",
-            "description": "Rotation duration in seconds."
+            "description": "Rotation length in seconds. Legacy alternative to `rotation_unit` + `rotation_value`: when only this is set, the server derives them (whole weeks, days or hours), and when only those are set, it fills this in (a month counts as 30 days)."
           },
           "handoff_time": {
             "type": "integer",
             "format": "int64",
-            "description": "Rotation handoff time as a weekly offset in seconds (weekday x 86400 + seconds since midnight), not an absolute Unix timestamp."
+            "description": "Weekly handoff point for weekly rotations, as seconds from Monday 00:00 in the schedule's time zone (`weekday × 86400 + seconds of day`, Monday = 0 … Sunday = 6). Not a Unix timestamp. Easier to set with `handoff`."
           },
           "enable_time": {
             "type": "integer",
             "format": "int64",
-            "description": "When the layer becomes effective (Unix seconds)."
+            "description": "When the layer takes effect (Unix seconds). For rotations its time of day is also the daily handoff time. `layer_start` overrides it when sent."
           },
           "expire_time": {
             "type": "integer",
             "format": "int64",
-            "description": "When the layer expires (Unix seconds, 0 means never)."
+            "description": "When the layer stops (Unix seconds); `0` = never. Must not be earlier than `enable_time`. `layer_end` overrides it when sent."
           },
           "restrict_mode": {
             "type": "integer",
-            "description": "Restriction mode: 0 = none, 1 = day, 2 = week.",
+            "description": "Restricts the layer to time windows given in `restrict_periods`:\n- `0`: no restriction.\n- `1`: daily windows; offsets are seconds from 00:00 (0–86400).\n- `2`: weekly windows; offsets are seconds from Monday 00:00 (0–604800). Cannot be combined with `day_mask`.\nWindows use the schedule's time zone.",
             "enum": [
               0,
               1,
@@ -28271,12 +28886,12 @@
           "restrict_start": {
             "type": "integer",
             "format": "int64",
-            "description": "Legacy start offset inside the restriction window (seconds)."
+            "description": "Legacy single-window start offset in seconds; prefer `restrict_periods`."
           },
           "restrict_end": {
             "type": "integer",
             "format": "int64",
-            "description": "Legacy end offset inside the restriction window (seconds)."
+            "description": "Legacy single-window end offset in seconds; prefer `restrict_periods`."
           },
           "restrict_periods": {
             "type": [
@@ -28286,11 +28901,11 @@
             "items": {
               "$ref": "#/components/schemas/ScheduleRestrictPeriod"
             },
-            "description": "Restriction windows inside each rotation cycle. Null when not set."
+            "description": "Time windows in which the layer is on call, interpreted by `restrict_mode`. Outside them the layer has nobody on call. `null` when not set."
           },
           "day_mask": {
             "$ref": "#/components/schemas/ScheduleDayMask",
-            "description": "Day-of-week mask."
+            "description": "Weekdays on which the rotation layer is on call."
           },
           "create_at": {
             "type": "integer",
@@ -28317,11 +28932,11 @@
               "string",
               "null"
             ],
-            "description": "User-facing layer name. Null when not set."
+            "description": "Layer name shown in the console; same value as `name` in responses."
           },
           "fair_rotation": {
             "type": "boolean",
-            "description": "Whether fair rotation is enabled."
+            "description": "When `true`, the group that starts each full round shifts by one, so that no group is always first. `false` (default) always restarts from the first group."
           },
           "layer_start": {
             "type": [
@@ -28329,7 +28944,7 @@
               "null"
             ],
             "format": "int64",
-            "description": "Layer effective start (Unix seconds). Null when not set."
+            "description": "Same as `enable_time`; takes precedence over it in requests. `null` when `enable_time` is 0."
           },
           "layer_end": {
             "type": [
@@ -28337,7 +28952,7 @@
               "null"
             ],
             "format": "int64",
-            "description": "Layer end timestamp (Unix seconds). null means open-ended."
+            "description": "Same as `expire_time`; takes precedence over it in requests. `null` means the layer never ends."
           },
           "rotation_unit": {
             "type": "string",
@@ -28352,22 +28967,106 @@
           "rotation_value": {
             "type": "integer",
             "format": "int64",
-            "description": "Rotation quantity (number of rotation_unit per cycle).",
+            "description": "Number of `rotation_unit`s each group stays on call before handing off. A rotation layer needs either this (with `rotation_unit`) or `rotation_duration`.",
             "minimum": 0
           },
           "mask_continuous_enabled": {
             "type": "boolean",
-            "description": "Whether continuous masking is enabled."
+            "description": "Only applies when `day_mask` selects 1–6 weekdays. When `true`, each on-call day runs from the layer's start time of day to the same time the next day instead of midnight to midnight."
+          },
+          "starts_at": {
+            "type": "object",
+            "writeOnly": true,
+            "description": "Request only. Layer start as a wall-clock date and time in the schedule's time zone; overrides `layer_start`/`enable_time`.",
+            "required": [
+              "date"
+            ],
+            "properties": {
+              "date": {
+                "type": "string",
+                "description": "Calendar date, `YYYY-MM-DD`."
+              },
+              "time": {
+                "type": "string",
+                "description": "Time of day, `HH:MM` (24-hour); defaults to `00:00`."
+              }
+            }
+          },
+          "ends_at": {
+            "type": "object",
+            "writeOnly": true,
+            "description": "Request only. Layer end as a wall-clock date and time in the schedule's time zone; overrides `layer_end`/`expire_time`. Send `{\"date\": \"\"}` to make the layer never end.",
+            "properties": {
+              "date": {
+                "type": "string",
+                "description": "Calendar date, `YYYY-MM-DD`."
+              },
+              "time": {
+                "type": "string",
+                "description": "Time of day, `HH:MM` (24-hour); defaults to `00:00`."
+              }
+            }
+          },
+          "handoff": {
+            "type": "object",
+            "writeOnly": true,
+            "required": [
+              "weekday",
+              "time"
+            ],
+            "description": "Request only. Handoff weekday and time in the schedule's time zone; sets `handoff_time` and the time of day of `enable_time`.",
+            "properties": {
+              "weekday": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 7,
+                "description": "ISO weekday: `1` = Monday … `7` = Sunday."
+              },
+              "time": {
+                "type": "string",
+                "description": "Time of day, `HH:MM` (24-hour)."
+              }
+            }
+          },
+          "restricts_wall": {
+            "type": "array",
+            "writeOnly": true,
+            "description": "Request only. Restriction windows as wall-clock times in the schedule's time zone; replaces `restrict_periods`. With `restrict_mode` 1 use `from`/`to` (`to` = `00:00` means end of day); with `restrict_mode` 2 also set `from_day`/`to_day`. Rejected when `restrict_mode` is 0.",
+            "items": {
+              "type": "object",
+              "properties": {
+                "from_day": {
+                  "type": "integer",
+                  "minimum": 1,
+                  "maximum": 7,
+                  "description": "ISO weekday the window starts on (`restrict_mode` 2 only): `1` = Monday … `7` = Sunday."
+                },
+                "from": {
+                  "type": "string",
+                  "description": "Window start, `HH:MM`."
+                },
+                "to_day": {
+                  "type": "integer",
+                  "minimum": 1,
+                  "maximum": 7,
+                  "description": "ISO weekday the window ends on (`restrict_mode` 2 only)."
+                },
+                "to": {
+                  "type": "string",
+                  "description": "Window end, `HH:MM`."
+                }
+              }
+            }
           }
         }
       },
       "ScheduleListRequest": {
         "type": "object",
-        "description": "Schedule list request. limit defaults to 10 and is capped at 100; p defaults to 1. is_my_team and is_my_manage are mutually exclusive.",
+        "description": "Schedule list filters. `limit` defaults to 10 and is capped at 100; `p` defaults to 1. `is_my_team` and `is_my_manage` cannot both be true.",
         "properties": {
           "query": {
             "type": "string",
-            "description": "Search keyword matched against schedule name or description."
+            "description": "Substring matched against the schedule name or description."
           },
           "p": {
             "type": "integer",
@@ -28376,17 +29075,17 @@
           },
           "limit": {
             "type": "integer",
-            "description": "Page size. Default 10, max 100.",
+            "description": "Page size. Default 10; values above 100 are treated as 100.",
             "default": 10,
             "maximum": 100
           },
           "is_my_team": {
             "type": "boolean",
-            "description": "Only return schedules whose owning team the current user belongs to."
+            "description": "Only schedules owned by the caller's teams. A caller in no team gets an empty list."
           },
           "is_my_manage": {
             "type": "boolean",
-            "description": "Only return schedules created by the current user within their teams."
+            "description": "Only schedules owned by the caller's teams or created by the caller."
           },
           "team_ids": {
             "type": "array",
@@ -28394,17 +29093,17 @@
               "type": "integer",
               "format": "int64"
             },
-            "description": "Filter by team IDs."
+            "description": "Only schedules owned by these teams; intersected with `is_my_team`/`is_my_manage` when either is set."
           },
           "start": {
             "type": "integer",
             "format": "int64",
-            "description": "When set together with end, computed layer schedules are returned. Span must be less than 45 days."
+            "description": "Window start, 10-digit Unix seconds. Send together with `end` to compute layers and shifts."
           },
           "end": {
             "type": "integer",
             "format": "int64",
-            "description": "Window end timestamp (Unix seconds)."
+            "description": "Window end, 10-digit Unix seconds, after `start` and at most 45 days later. Sending `end` without `start` is rejected."
           }
         }
       },
@@ -28417,14 +29116,11 @@
         ],
         "properties": {
           "items": {
-            "type": [
-              "array",
-              "null"
-            ],
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/ScheduleItem"
             },
-            "description": "Schedules on this page; null when no schedule matches."
+            "description": "Schedules on this page; an empty array when none match."
           },
           "total": {
             "type": "integer",
@@ -28444,7 +29140,7 @@
           "role_id": {
             "type": "integer",
             "format": "int64",
-            "description": "Oncall role ID.",
+            "description": "On-call role assigned to the people in this slot; `0` = no role.",
             "minimum": 0
           },
           "person_ids": {
@@ -28453,7 +29149,7 @@
               "type": "integer",
               "format": "int64"
             },
-            "description": "Person IDs in this slot.",
+            "description": "Member IDs in this slot; at least one.",
             "minItems": 1
           }
         }
@@ -28473,22 +29169,36 @@
               "null"
             ],
             "format": "int64",
-            "description": "Advance notification lead time in seconds. `0` notifies exactly at shift start; omitting disables advance notification."
+            "description": "Lead time in seconds for the shift-change notification: `0` notifies at the start of the shift, `300` five minutes before. Omitted or `null` disables shift-change notifications."
           },
           "fixed_time": {
-            "$ref": "#/components/schemas/ScheduleFixedTimeNotifyInfo",
-            "description": "Fixed-time notification config; null when not configured."
+            "oneOf": [
+              {
+                "$ref": "#/components/schemas/ScheduleFixedTimeNotifyInfo"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "Send a shift summary at a fixed time; `null` when not configured."
           },
           "by": {
-            "$ref": "#/components/schemas/ScheduleNotifyBy",
-            "description": "Recipient notification preference; null when not configured."
+            "oneOf": [
+              {
+                "$ref": "#/components/schemas/ScheduleNotifyBy"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "Personal notifications sent to the people on call; `null` when not configured."
           },
           "im": {
             "type": "object",
             "additionalProperties": {
               "type": "string"
             },
-            "description": "Legacy IM-type to token map."
+            "description": "Legacy map of robot type to webhook token. Entries not already in `webhooks` are added to `webhooks` when read; use `webhooks` instead."
           },
           "webhooks": {
             "type": [
@@ -28498,7 +29208,7 @@
             "items": {
               "$ref": "#/components/schemas/ScheduleImNotify"
             },
-            "description": "IM webhook notification channels; null when not configured."
+            "description": "Group chats or robots that receive shift-change notifications; `null` when not configured."
           }
         }
       },
@@ -28512,14 +29222,17 @@
         "properties": {
           "follow_preference": {
             "type": "boolean",
-            "description": "Whether to follow each responder's personal notification preference."
+            "description": "`true`: notify each person through the channels in their own shift-notification preference, ignoring `personal_channels`. `false`: use `personal_channels`."
           },
           "personal_channels": {
-            "type": "array",
+            "type": [
+              "array",
+              "null"
+            ],
             "items": {
               "type": "string"
             },
-            "description": "Personal notification channel keys."
+            "description": "Channels used when `follow_preference` is `false`: `email`, `sms`, `push` (mobile app), and the IM apps `feishu_app`, `dingtalk_app`, `wecom_app`, `teams_app`, `slack_app`. An IM app value may carry the integration ID as `<type>:<integration ID>` (for example `feishu_app:5427276014131`). Unknown values are stored but never used. `null` when not set."
           }
         }
       },
@@ -28552,21 +29265,21 @@
           "update_at": {
             "type": "integer",
             "format": "int64",
-            "description": "Update timestamp (Unix seconds)."
+            "description": "Update time as a Unix timestamp in seconds; always `0` in these responses."
           },
           "weight": {
             "type": "integer",
-            "description": "Layer weight the shift comes from."
+            "description": "Always `0` in these responses."
           },
           "index": {
             "type": "integer",
-            "description": "Index inside the rotation."
+            "description": "Always `0` in these responses."
           }
         }
       },
       "ScheduleRestrictPeriod": {
         "type": "object",
-        "description": "Restrict window inside a rotation cycle. restrict_start and restrict_end are second offsets and cannot be equal unless both are 0.",
+        "description": "One on-call window inside a day or week (see `restrict_mode`). A window whose start is later than its end wraps past midnight (or the end of the week). `{0, 0}` means the whole day or week. Start and end may not be equal otherwise.",
         "required": [
           "restrict_start",
           "restrict_end"
@@ -28575,12 +29288,12 @@
           "restrict_start": {
             "type": "integer",
             "format": "int64",
-            "description": "Start offset inside the rotation cycle."
+            "description": "Window start in seconds: from 00:00 when `restrict_mode` is 1, from Monday 00:00 when it is 2."
           },
           "restrict_end": {
             "type": "integer",
             "format": "int64",
-            "description": "End offset inside the rotation cycle."
+            "description": "Window end in seconds, same reference point as `restrict_start`."
           }
         }
       },
@@ -28606,26 +29319,23 @@
       },
       "ScheduleSelfResponse": {
         "type": "object",
-        "description": "Response of /schedule/self and /schedule/infos. Only the items field is populated.",
+        "description": "Response of `/schedule/self` and `/schedule/infos`.",
         "required": [
           "items"
         ],
         "properties": {
           "items": {
-            "type": [
-              "array",
-              "null"
-            ],
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/ScheduleItem"
             },
-            "description": "Schedules assigned to the current user (or matching the requested IDs); null when none."
+            "description": "Matching schedules; an empty array when none match."
           }
         }
       },
       "ScheduleUpsertRequest": {
         "type": "object",
-        "description": "Schedule create/update/preview request body. The server accepts the same shape as the schedule detail model; only the key fields are listed here. `schedule_name` (or the legacy `name`) is required on create, `schedule_id` is required on update, and `start`/`end` are required on preview.",
+        "description": "Request body of `/schedule/create`, `/schedule/update` and `/schedule/preview`. `schedule_name` (or the legacy `name`) is required on create, `schedule_id` on update, and `start`/`end` on preview.",
         "properties": {
           "schedule_id": {
             "type": [
@@ -28640,7 +29350,7 @@
               "string",
               "null"
             ],
-            "description": "Schedule display name. Max 40 characters.",
+            "description": "Schedule name, at most 40 characters, unique within the account. On update, omitting it keeps the current name.",
             "maxLength": 40
           },
           "name": {
@@ -28648,7 +29358,7 @@
               "string",
               "null"
             ],
-            "description": "Legacy schedule name field. Used when schedule_name is empty.",
+            "description": "Legacy name field, used on create only when `schedule_name` is empty. Ignored on update.",
             "maxLength": 40
           },
           "description": {
@@ -28656,7 +29366,7 @@
               "string",
               "null"
             ],
-            "description": "Schedule description. Max 500 characters.",
+            "description": "Schedule description, at most 500 characters. On update, omitting it keeps the current text and an empty string clears it.",
             "maxLength": 500
           },
           "team_id": {
@@ -28665,35 +29375,63 @@
               "null"
             ],
             "format": "int64",
-            "description": "Owning team ID; obtain it from `POST /team/list`."
+            "description": "ID of the owning team; obtain it from `POST /team/list`. On create, omitting it leaves the schedule without a team (`0`); on update, omitting it keeps the current team."
+          },
+          "time_zone": {
+            "type": "string",
+            "description": "IANA time zone in which the schedule's wall-clock rules are evaluated, for example `Asia/Shanghai` or `UTC`; abbreviations such as `EST` and `Etc/GMT±N` are rejected. Set on create (default: evaluated in `Asia/Shanghai`); immutable afterwards — on update send nothing or the current value. On preview it sets the evaluation time zone."
           },
           "layers": {
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/ScheduleLayer"
             },
-            "description": "Rotation layers."
+            "description": "Rotation layers. Required in practice: on update the list replaces all existing layers, so omitting it deletes every layer."
           },
           "notify": {
-            "$ref": "#/components/schemas/ScheduleNotify",
-            "description": "Rotation notification configuration."
+            "oneOf": [
+              {
+                "$ref": "#/components/schemas/ScheduleNotify"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "Shift notification configuration. On update, omitting it keeps the current configuration; a sent object replaces it entirely."
           },
           "start": {
             "type": "integer",
             "format": "int64",
-            "description": "Preview window start (Unix seconds, 10 digits). Required for /schedule/preview."
+            "description": "Preview window start, 10-digit Unix seconds. Required for `/schedule/preview`; ignored by create and update."
           },
           "end": {
             "type": "integer",
             "format": "int64",
-            "description": "Preview window end (Unix seconds, 10 digits). Required for /schedule/preview. Max 45 days after start."
+            "description": "Preview window end, 10-digit Unix seconds, after `start` and at most 45 days later. Required for `/schedule/preview`; ignored by create and update."
           },
           "disabled": {
             "type": [
               "integer",
               "null"
             ],
-            "description": "0 = enabled, 1 = disabled. Defaults to enabled when omitted."
+            "enum": [
+              0,
+              1,
+              null
+            ],
+            "description": "Create only: `0` = enabled (default), `1` = disabled. Ignored on update — use `status` instead."
+          },
+          "status": {
+            "type": [
+              "integer",
+              "null"
+            ],
+            "enum": [
+              0,
+              1,
+              null
+            ],
+            "description": "`0` = enabled, `1` = disabled. On update, omitting it keeps the current state. On create it takes precedence over `disabled`."
           }
         }
       },
@@ -28728,7 +29466,7 @@
           },
           "rule_name": {
             "type": "string",
-            "description": "Rule name."
+            "description": "Silence rule name, 1–39 characters."
           },
           "description": {
             "type": "string",
@@ -28752,11 +29490,11 @@
           },
           "filters": {
             "$ref": "#/components/schemas/FilterGroup",
-            "description": "Alert event match conditions; matching events are silenced within the time window."
+            "description": "Alert event conditions (OR of AND groups); matching events are silenced while the time window is active."
           },
           "is_directly_discard": {
             "type": "boolean",
-            "description": "When true, silenced alerts are dropped instead of suppressed into incidents."
+            "description": "When true, matching alert events are discarded entirely; when false, alerts are still recorded but marked as silenced by this rule."
           },
           "status": {
             "type": "string",
@@ -28792,7 +29530,7 @@
           },
           "is_auto_delete": {
             "type": "boolean",
-            "description": "When true, the silence rule is automatically deleted after its time window expires. Defaults to false."
+            "description": "When true, the rule is permanently removed about 24 hours after its one-off window ends; rules with recurring windows are never removed. Returned only when `true`."
           },
           "deleted_at": {
             "type": "integer",
@@ -28859,7 +29597,7 @@
           "change_id": {
             "type": "integer",
             "format": "int64",
-            "description": "Event ID."
+            "description": "Event ID, returned by `POST /status-page/change/create`; pass it as `change_id` to the other event endpoints."
           },
           "page_id": {
             "type": "integer",
@@ -28920,7 +29658,7 @@
           "start_at_seconds": {
             "type": "integer",
             "format": "int64",
-            "description": "Event start time in Unix seconds, derived from the first timeline update. Omitted when 0."
+            "description": "Event start time in Unix seconds. For incidents it is the time of the first timeline entry; for maintenances it is the scheduled start given at creation, or the first entry's time when none was given. Omitted when 0."
           },
           "close_at_seconds": {
             "type": "integer",
@@ -28987,7 +29725,7 @@
         "properties": {
           "update_id": {
             "type": "string",
-            "description": "Update ID."
+            "description": "Timeline entry ID (a ULID string), assigned by the server; pass it as `update_id` to edit or delete the entry."
           },
           "at_seconds": {
             "type": "integer",
@@ -29030,7 +29768,7 @@
         "properties": {
           "component_id": {
             "type": "string",
-            "description": "Component ID."
+            "description": "ID of the component whose status changes; matches `component_id` in `GET /status-page/info`."
           },
           "component_name": {
             "type": "string",
@@ -29102,7 +29840,7 @@
         "properties": {
           "draft_id": {
             "type": "string",
-            "description": "Draft ID matching `draft_[A-Za-z0-9]{22}`; the console review link carries it."
+            "description": "Draft ID matching `draft_[A-Za-z0-9]{22}`; pass it as `draft_id` to `POST /status-page/change/create` or `POST /status-page/change/timeline/create` to publish."
           },
           "created_at": {
             "type": "integer",
@@ -29142,7 +29880,7 @@
           "target_page_id": {
             "type": "integer",
             "format": "int64",
-            "description": "Flashduty target status page ID. Set once the job produces one, or supplied up front for subscriber migration."
+            "description": "Flashduty target status page ID. For a structure migration it is 0 until the page is created or reused; for a subscriber migration it is the `target_page_id` from the request."
           },
           "phase": {
             "type": "string",
@@ -29200,7 +29938,7 @@
         "properties": {
           "total_steps": {
             "type": "integer",
-            "description": "Total steps this job will perform."
+            "description": "Total steps of the job: 5 for a structure migration (page, sections, components, incidents and maintenances, templates) and 1 for a subscriber migration."
           },
           "completed_steps": {
             "type": "integer",
@@ -29232,7 +29970,7 @@
           },
           "subscribers_skipped": {
             "type": "integer",
-            "description": "Number of subscribers skipped (e.g. because they would create duplicates)."
+            "description": "Number of source subscribers skipped because they are not email subscribers, have no email address, or are quarantined. Recipients already subscribed on the target page are not counted here."
           },
           "warnings": {
             "type": "array",
@@ -29298,12 +30036,11 @@
             "example": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
           },
           "data": {
-            "description": "Endpoint-specific payload. See each operation's 200 response schema."
+            "description": "Operation-specific payload, documented in each operation's 200 response. Operations without a payload return `{}` or omit `data` entirely."
           }
         },
         "required": [
-          "request_id",
-          "data"
+          "request_id"
         ]
       },
       "TemplateCreateRequest": {
@@ -29316,14 +30053,14 @@
           "team_id": {
             "type": "integer",
             "format": "int64",
-            "description": "Team scope. 0 for account-wide.",
+            "description": "Owning team ID from `POST /team/list`; `0` (default) means account-wide. A non-zero ID must be an existing team.",
             "default": 0
           },
           "template_name": {
             "type": "string",
             "minLength": 1,
             "maxLength": 39,
-            "description": "Template name, unique per account. 1–39 characters.",
+            "description": "Template name, 1–39 characters, unique among the account's non-deleted templates and different from the built-in preset template's name in every supported language.",
             "example": "Prod incident default"
           },
           "description": {
@@ -29353,7 +30090,7 @@
           },
           "wecom_markdown_v2_enabled": {
             "type": "boolean",
-            "description": "Send WeCom robot notifications as `markdown_v2` messages instead of plain markdown."
+            "description": "Send WeCom robot notifications as `markdown_v2` messages instead of plain markdown. While enabled, the rendered `wecom` content must be at most 4,096 bytes."
           },
           "feishu": {
             "type": "string",
@@ -29366,7 +30103,7 @@
           "feishu_app_card_v2_table_enabled": {
             "type": "boolean",
             "default": false,
-            "description": "Render alert labels as a table in Feishu app cards."
+            "description": "Render Markdown tables in the `feishu_app` content as native Feishu card tables."
           },
           "feishu_app_card_v2_preserve_blank_lines": {
             "type": "boolean",
@@ -29428,7 +30165,7 @@
           },
           "incident_card_hidden_fields": {
             "$ref": "#/components/schemas/IncidentCardHiddenFields",
-            "description": "Incident card fields hidden per IM app type."
+            "description": "Incident card fields to hide per IM app type."
           }
         }
       },
@@ -29519,7 +30256,7 @@
           "template_id": {
             "type": "string",
             "pattern": "^[0-9a-fA-F]{24}$",
-            "description": "Template ID.",
+            "description": "Template ID (24-character hex). The built-in preset template always has the ID `6321aad26c12104586a88916`.",
             "example": "6605a1b2c3d4e5f6a7b8c9d0"
           },
           "template_name": {
@@ -29528,7 +30265,7 @@
           },
           "description": {
             "type": "string",
-            "description": "Free-form description."
+            "description": "Free-form description (up to 500 characters); empty string when none was given."
           },
           "email": {
             "type": "string",
@@ -29564,7 +30301,7 @@
           },
           "feishu_app_card_v2_table_enabled": {
             "type": "boolean",
-            "description": "Whether alert labels use table rendering in Feishu app cards."
+            "description": "Whether Markdown tables in the `feishu_app` content are rendered as native Feishu card tables."
           },
           "feishu_app_card_v2_preserve_blank_lines": {
             "type": "boolean",
@@ -29611,7 +30348,10 @@
             "description": "Zoom bot message template source."
           },
           "incident_card_closed_action_apps": {
-            "type": "array",
+            "type": [
+              "array",
+              "null"
+            ],
             "items": {
               "type": "string",
               "enum": [
@@ -29622,7 +30362,7 @@
                 "teams_app"
               ]
             },
-            "description": "IM apps whose closed-incident cards keep the custom action buttons. Supported values: `feishu_app`, `dingtalk_app`, `wecom_app`, `slack_app`, `teams_app`. An empty list hides the buttons on every app."
+            "description": "IM apps whose cards for closed incidents keep the custom action buttons (open incidents always show them). Values: `feishu_app`, `dingtalk_app`, `wecom_app`, `slack_app`, `teams_app`. Empty or `null` hides the buttons on closed-incident cards in every app."
           },
           "incident_card_hidden_fields": {
             "$ref": "#/components/schemas/IncidentCardHiddenFields",
@@ -29630,7 +30370,7 @@
           },
           "status": {
             "type": "string",
-            "description": "Template lifecycle status. `enabled` templates can be referenced by escalation policies for notifications; `disabled` templates are no longer used for new notifications; `deleted` templates are never returned by list endpoints.",
+            "description": "Template status.\n- `enabled`: usable by escalation rules.\n- `disabled`: not used for new notifications; cannot be set through this API.\n- `deleted`: soft-deleted by `/template/delete`; excluded from `/template/list` but still returned by `/template/info`.",
             "enum": [
               "enabled",
               "disabled",
@@ -29685,7 +30425,7 @@
           },
           "orderby": {
             "type": "string",
-            "description": "Sort field.",
+            "description": "Sort field: `created_at` (default, creation time) or `updated_at` (last update time).",
             "enum": [
               "created_at",
               "updated_at"
@@ -29693,12 +30433,12 @@
           },
           "asc": {
             "type": "boolean",
-            "description": "Ascending sort order.",
+            "description": "Sort ascending when `true`; defaults to newest first.",
             "default": false
           },
           "is_my_team": {
             "type": "boolean",
-            "description": "When true, only return templates scoped to teams the caller belongs to.",
+            "description": "When `true`, only templates of teams the caller belongs to are returned. If `team_ids` is also sent, only teams in both lists are kept; when they share no team, no team filter is applied and templates of all teams are returned. A caller in no team gets an empty result.",
             "default": false
           },
           "team_ids": {
@@ -29707,7 +30447,7 @@
               "type": "integer",
               "format": "int64"
             },
-            "description": "Filter by specific team IDs."
+            "description": "Return only templates of these team IDs (from `POST /team/list`); `0` selects account-wide templates. Empty or omitted applies no team filter. See `is_my_team` for how the two combine."
           },
           "creator_id": {
             "type": [
@@ -29719,7 +30459,7 @@
           },
           "query": {
             "type": "string",
-            "description": "Regex or substring match on template_name."
+            "description": "Case-insensitive regular expression matched against `template_name`; an invalid expression is matched as literal text."
           }
         }
       },
@@ -29778,7 +30518,7 @@
             "type": "string",
             "minLength": 1,
             "maxLength": 39,
-            "description": "Template name. 1–39 characters."
+            "description": "Template name, 1–39 characters. Required and written on every call; must not be used by another template."
           },
           "description": {
             "type": [
@@ -29828,7 +30568,7 @@
               "boolean",
               "null"
             ],
-            "description": "When set, switch WeCom robot notifications between `markdown_v2` and plain markdown. Omit to keep the existing setting."
+            "description": "Send WeCom robot notifications as `markdown_v2` messages instead of plain markdown. While enabled, the rendered `wecom` content must be at most 4,096 bytes. Omit to keep the current setting."
           },
           "feishu": {
             "type": [
@@ -29849,7 +30589,7 @@
               "boolean",
               "null"
             ],
-            "description": "When set, enable or disable table rendering for alert labels in Feishu app cards. Omit to keep the existing setting."
+            "description": "Render Markdown tables in the `feishu_app` content as native Feishu card tables. Omit to keep the current setting."
           },
           "feishu_app_card_v2_preserve_blank_lines": {
             "type": [
@@ -29944,21 +30684,21 @@
           },
           "incident_card_hidden_fields": {
             "$ref": "#/components/schemas/IncidentCardHiddenFields",
-            "description": "Incident card fields hidden per IM app type."
+            "description": "Incident card fields to hide per IM app type. When sent, replaces the stored value as a whole; omit to keep."
           }
         }
       },
       "TimeFilter": {
         "type": "object",
-        "description": "Recurring time window. `start`/`end` use 24-hour `HH:MM` format; `repeat` lists ISO-style weekday indices (0=Sunday … 6=Saturday).",
+        "description": "Recurring time window. `start` and `end` are `HH:MM` in 24-hour format with `start` not later than `end` (windows cannot cross midnight); `00:00`–`00:00` means the whole day.",
         "properties": {
           "start": {
             "type": "string",
-            "description": "Start of the window in `HH:MM`."
+            "description": "Window start, `HH:MM`, inclusive."
           },
           "end": {
             "type": "string",
-            "description": "End of the window in `HH:MM`."
+            "description": "Window end, `HH:MM`, inclusive (`23:59` lasts to midnight)."
           },
           "repeat": {
             "type": "array",
@@ -29967,15 +30707,15 @@
               "minimum": 0,
               "maximum": 6
             },
-            "description": "Days of the week this window repeats on. Empty means every day."
+            "description": "Days of the week the window applies on: `0` = Sunday … `6` = Saturday. Empty means every day."
           },
           "cal_id": {
             "type": "string",
-            "description": "Optional calendar ID; restricts the window to days matching the calendar."
+            "description": "Service calendar ID from `POST /calendar/list` (for example `cal.xxxx`). When set, the window applies only on the calendar's workdays or days off, as chosen by `is_off`."
           },
           "is_off": {
             "type": "boolean",
-            "description": "When true, match days marked as days-off in the calendar."
+            "description": "Used with `cal_id`: `true` applies the window only on the calendar's days off, `false` only on its workdays."
           }
         }
       },
@@ -30026,7 +30766,7 @@
           },
           "rule_name": {
             "type": "string",
-            "description": "Rule name."
+            "description": "Drop rule name, 1–39 characters."
           },
           "description": {
             "type": "string",
@@ -30034,7 +30774,7 @@
           },
           "filters": {
             "$ref": "#/components/schemas/FilterGroup",
-            "description": "Alert event match conditions (OR-of-AND); matching events are discarded entirely. Empty means the rule matches nothing."
+            "description": "Alert event conditions (OR of AND groups); matching events are discarded entirely. Empty means the rule matches nothing; `null` when the last update omitted `filters`."
           },
           "status": {
             "type": "string",
@@ -30089,7 +30829,7 @@
               "null"
             ],
             "format": "int64",
-            "description": "New owning team ID; obtain it from `POST /team/list`."
+            "description": "New owning team ID; obtain it from `POST /team/list`. Must exist. Omit or pass `null` to keep the current team."
           },
           "managing_team_ids": {
             "type": "array",
@@ -30098,7 +30838,7 @@
               "format": "int64"
             },
             "maxItems": 3,
-            "description": "Additional teams that can manage the channel. Up to 3 entries."
+            "description": "Replaces the additional managing teams, up to 3; every ID must exist. Pass `[]` to remove them all; omit to keep the current list."
           },
           "channel_name": {
             "type": [
@@ -30107,7 +30847,7 @@
             ],
             "minLength": 1,
             "maxLength": 59,
-            "description": "New channel name. 1 to 59 characters."
+            "description": "New channel name, 1–59 characters, unique within the account. Omit or pass `null` to keep the current name."
           },
           "description": {
             "type": [
@@ -30133,7 +30873,7 @@
               "trigger",
               "update"
             ],
-            "description": "Auto-resolve timing mode: `trigger` starts the timer when the incident triggers, `update` restarts it on every alert update. Applied only when `auto_resolve_timeout` is also present in the request."
+            "description": "How the auto-resolve timer runs: `trigger` starts it once when the incident is triggered, `update` restarts it whenever a new alert merges in. Applied only together with `auto_resolve_timeout`; if `auto_resolve_timeout` is sent without it, the mode resets to `trigger`."
           },
           "is_private": {
             "type": [
@@ -30144,11 +30884,11 @@
           },
           "group": {
             "$ref": "#/components/schemas/Group",
-            "description": "Alert grouping configuration."
+            "description": "Alert grouping configuration; replaces the stored configuration as a whole when present."
           },
           "flapping": {
             "$ref": "#/components/schemas/Flapping",
-            "description": "Flapping detection configuration."
+            "description": "Flapping detection configuration; replaces the stored configuration as a whole when present."
           },
           "disable_outlier_detection": {
             "type": [
@@ -30169,21 +30909,21 @@
               "boolean",
               "null"
             ],
-            "description": "Allow external reporters to file incidents into this channel."
+            "description": "`true` enables external reporting and generates a new token, returned in the response (any previous token stops working); `false` disables it and clears the token."
           },
           "event_group": {
             "$ref": "#/components/schemas/EventGroup",
-            "description": "Alert event merge configuration. Updated only when present."
+            "description": "Alert event merge configuration; replaces the stored configuration as a whole when present."
           }
         }
       },
       "UpdateChannelResponse": {
         "type": "object",
-        "description": "Response from updating a channel. Only populated when `is_external_report_enabled` is set to `true`; otherwise all fields are empty.",
+        "description": "Contains `external_report_token` only when the request set `is_external_report_enabled` to `true`; otherwise `data` is an empty object.",
         "properties": {
           "external_report_token": {
             "type": "string",
-            "description": "Newly generated token for external reporters. Only returned when `is_external_report_enabled` is set to `true` in the request. Callers should store this value; it cannot be retrieved afterwards."
+            "description": "Newly generated token for external reporters; the previous token stops working. It can be read again later from `external_report_token` in `POST /channel/info`."
           }
         }
       },
@@ -30215,11 +30955,11 @@
           "description": {
             "type": "string",
             "maxLength": 500,
-            "description": "Rule description, up to 500 characters."
+            "description": "Rule description, up to 500 characters. Omitting it clears the stored description."
           },
           "filters": {
             "$ref": "#/components/schemas/FilterGroup",
-            "description": "Alert event match conditions (OR-of-AND); matching events are discarded entirely. When empty, the rule matches nothing."
+            "description": "Alert event conditions (OR of AND groups); matching events are discarded entirely. Keys: `title`, `description`, `severity` (alias `alert_severity`, `event_severity`), `status`, `alert_key`, `title_rule`, `integration_id` (alias `data_source_id`), or any `labels.<name>`. The stored conditions are replaced; omitting this field clears them and the rule then matches nothing."
           }
         }
       },
@@ -30249,16 +30989,16 @@
               "integer",
               "null"
             ],
-            "description": "Evaluation priority. Lower runs first."
+            "description": "Evaluation order; lower values are evaluated first. Omit or pass `null` to keep the current value."
           },
           "aggr_window": {
             "type": "integer",
-            "description": "Delay window in seconds. 0 disables delay."
+            "description": "Delay in seconds before the first notification for a newly assigned incident; `0` notifies immediately. Omitting it resets the value to `0`."
           },
           "template_id": {
             "type": "string",
             "pattern": "^[0-9a-fA-F]{24}$",
-            "description": "Notification template ID (MongoDB ObjectID)."
+            "description": "Notification template ID (24-character hex); obtain it from `POST /template/list`. Must exist."
           },
           "rule_name": {
             "type": "string",
@@ -30269,7 +31009,7 @@
           "description": {
             "type": "string",
             "maxLength": 500,
-            "description": "Rule description, up to 500 characters."
+            "description": "Rule description, up to 500 characters. Omitting it clears the stored description."
           },
           "layers": {
             "type": "array",
@@ -30283,17 +31023,17 @@
             "items": {
               "$ref": "#/components/schemas/TimeFilter"
             },
-            "description": "Optional recurring time windows during which the rule applies."
+            "description": "Recurring time windows during which the rule can match. Replaces the stored windows; omit or leave empty to match at any time."
           },
           "filters": {
             "$ref": "#/components/schemas/FilterGroup",
-            "description": "Incident-level match conditions (OR-of-AND tree): the rule is matched against the incident the alert was grouped into, not against the alert itself. Omit or leave empty to apply the rule to all incidents in the channel."
+            "description": "Incident conditions (OR of AND groups), matched against the incident the alert was grouped into, not against the alert. Keys: `title`, `description`, `severity` (alias `incident_severity`, `alert_severity`), `status` (alias `incident_status`, `alert_status`), `dedup_key`, `integration_id` (alias `data_source_id`), or any `labels.<name>`. Replaces the stored conditions; omit or leave empty to match every incident in the channel."
           }
         }
       },
       "UpdateIncidentFieldsRequest": {
         "type": "object",
-        "description": "Parameters for updating user-editable fields of an incident. At least one field must be provided; the handler will update only the fields you supply.",
+        "description": "Fields to update on an incident. At least one field besides `incident_id` must be non-empty; omitted or empty fields keep their current values.",
         "required": [
           "incident_id"
         ],
@@ -30373,26 +31113,26 @@
           "description": {
             "type": "string",
             "maxLength": 500,
-            "description": "Rule description, up to 500 characters."
+            "description": "Rule description, up to 500 characters. Omitting it clears the stored description."
           },
           "equals": {
             "type": "array",
             "items": {
               "type": "string"
             },
-            "description": "Field keys whose values must be equal between the source (inhibiting) alert and the target (suppressed) alert, e.g. `data_source_id` or `labels.cluster`."
+            "description": "Keys whose values must be equal on the source alert and the incoming event. Only `title`, `severity` and `labels.<name>` take effect; any other key (for example `data_source_id`) is accepted but makes the rule never fire. Must be present; an empty array also makes the rule inert."
           },
           "source_filters": {
             "$ref": "#/components/schemas/FilterGroup",
-            "description": "Conditions the source alert must match, evaluated against stored active alerts. Supported keys: `status`, `incident_status`, `alert_status`, `severity`, `incident_severity`, `alert_severity`, `title`, `description`, or any `labels.<name>`. Empty makes the rule inert."
+            "description": "Conditions the source (inhibiting) alert must match, evaluated against active alerts already stored in the channel. Keys: `title`, `description`, `severity` (alias `incident_severity`, `alert_severity`), `status` (alias `incident_status`, `alert_status`), or any `labels.<name>`. Empty makes the rule inert. Omitting it clears the stored conditions."
           },
           "target_filters": {
             "$ref": "#/components/schemas/FilterGroup",
-            "description": "Conditions the incoming target alert event must match to be suppressed; empty means every event is a target."
+            "description": "Conditions the incoming target alert event must match to be inhibited; empty means every incoming event is a target. Keys: `title`, `description`, `severity` (alias `alert_severity`, `event_severity`), `status`, `alert_key`, `title_rule`, `integration_id` (alias `data_source_id`), or any `labels.<name>`. Omitting it clears the stored conditions."
           },
           "is_directly_discard": {
             "type": "boolean",
-            "description": "When true, matching alert events are discarded entirely; when false, alerts are still recorded but marked as muted by this rule."
+            "description": "When true, matching alert events are discarded entirely; when false, alerts are still recorded but marked as muted by this rule. Omitting it sets it to `false`."
           }
         }
       },
@@ -30424,7 +31164,7 @@
           "description": {
             "type": "string",
             "maxLength": 500,
-            "description": "Rule description, up to 500 characters."
+            "description": "Rule description, up to 500 characters. Omitting it clears the stored description."
           },
           "time_filters": {
             "type": "array",
@@ -30439,15 +31179,15 @@
           },
           "filters": {
             "$ref": "#/components/schemas/FilterGroup",
-            "description": "Match conditions for the alerts to silence; required and must not be empty."
+            "description": "Alert event conditions (OR of AND groups); matching events are silenced while the time window is active. Required, with at least one condition. Keys: `title`, `description`, `severity` (alias `alert_severity`, `event_severity`), `status`, `alert_key`, `title_rule`, `integration_id` (alias `data_source_id`), or any `labels.<name>`."
           },
           "is_directly_discard": {
             "type": "boolean",
-            "description": "When true, matching alert events are discarded entirely; when false, alerts are still recorded but marked as muted by this rule."
+            "description": "When true, matching alert events are discarded entirely; when false, alerts are still recorded but marked as silenced by this rule. Omitting it sets it to `false`."
           },
           "is_auto_delete": {
             "type": "boolean",
-            "description": "When true, the silence rule is automatically deleted after its time window expires. Defaults to false."
+            "description": "When true, a rule with a one-off `time_filter` is permanently removed about 24 hours after `end_time` (or after its last update, whichever is later). Rules created with `from_incident_id` are cleaned up the same way. Rules with recurring `time_filters` are never removed automatically. Omitting it sets it to `false`."
           }
         }
       },
@@ -30483,14 +31223,14 @@
               "type": "integer",
               "format": "int64"
             },
-            "description": "Member IDs responsible for this event. Pass the full replacement list."
+            "description": "Member IDs responsible for this event, replacing the current list. An omitted or empty array keeps the current list."
           },
           "linked_changes": {
             "type": "array",
             "items": {
               "type": "string"
             },
-            "description": "Linked event IDs. Pass the full replacement list."
+            "description": "Linked event IDs, replacing the current list. An omitted or empty array keeps the current list."
           }
         }
       },
@@ -30520,17 +31260,17 @@
           "at_seconds": {
             "type": "integer",
             "format": "int64",
-            "description": "New update timestamp in Unix seconds."
+            "description": "New update time in Unix seconds; must not be earlier than the previous entry or later than the next one. Omit or pass 0 to keep the current time."
           },
           "description": {
             "type": "string",
-            "description": "New update description (Markdown)."
+            "description": "New update description (Markdown). Omit or pass an empty string to keep the current text; editing the latest entry also updates the event description."
           }
         }
       },
       "UpsertRouteRequest": {
         "type": "object",
-        "description": "Parameters for creating or updating the routing rule of an integration. The handler creates a rule when none exists for the integration, otherwise it overwrites the existing one. At least one of `cases` or `default` must be provided.",
+        "description": "Creates the integration's routing rule, or replaces it entirely when one exists. At least one of `cases` or `default` must be provided.",
         "required": [
           "integration_id"
         ],
@@ -30538,7 +31278,7 @@
           "integration_id": {
             "type": "integer",
             "format": "int64",
-            "description": "Integration the rule belongs to."
+            "description": "Shared integration ID; obtain it from `POST /integration/list`. Channel-exclusive integrations are rejected with `InvalidParameter`."
           },
           "cases": {
             "type": "array",
@@ -30556,12 +31296,12 @@
           },
           "default": {
             "$ref": "#/components/schemas/RouteDefault",
-            "description": "Fallback branch used when no case matches."
+            "description": "Fallback branch used when no case yields a channel. Omitting it removes any existing default branch."
           },
           "version": {
             "type": "integer",
             "format": "int64",
-            "description": "Reserved for optimistic concurrency control; currently ignored — the server increments `version` automatically on every upsert."
+            "description": "Ignored. The server increments `version` on every upsert and does not compare it with this value."
           }
         }
       },
@@ -30586,7 +31326,7 @@
       },
       "WarRoom": {
         "type": "object",
-        "description": "Live war room details fetched from the IM side. Returns an empty object if the group was deleted externally.",
+        "description": "War room group details read from the IM platform. When the IM lookup fails (for example, the group was dissolved outside Flashduty), all fields are empty strings.",
         "required": [
           "chat_id",
           "chat_name",
@@ -30625,7 +31365,7 @@
           "account_id": {
             "type": "integer",
             "format": "int64",
-            "description": "Account ID."
+            "description": "ID of the account that owns this record; the same for every record returned to one `app_key`."
           },
           "integration_id": {
             "type": "integer",
@@ -30648,20 +31388,26 @@
           },
           "status": {
             "type": "string",
-            "description": "War room record status: `enabled` active, `deleted` disbanded.",
+            "description": "Record status. Always `enabled` in this list, because deleted war rooms are not returned.",
             "enum": [
-              "enabled",
-              "deleted"
+              "enabled"
             ]
           },
           "created_at": {
             "type": "integer",
             "format": "int64",
-            "description": "Creation timestamp (seconds)."
+            "description": "Unix timestamp (seconds) when the war room was created."
           },
           "plugin_type": {
             "type": "string",
-            "description": "IM plugin type (e.g. `feishu`, `dingtalk`, `wecom`, `slack`)."
+            "description": "Plugin type of the IM integration: `feishu_app` (Feishu), `dingtalk_app` (DingTalk), `wecom_app` (WeCom), or `slack_app` (Slack). Empty string when the integration no longer exists.",
+            "enum": [
+              "feishu_app",
+              "dingtalk_app",
+              "wecom_app",
+              "slack_app",
+              ""
+            ]
           },
           "chat_name": {
             "type": "string",
@@ -30692,11 +31438,11 @@
           "integration_id": {
             "type": "integer",
             "format": "int64",
-            "description": "Integration ID."
+            "description": "ID of the webhook integration that sent the request."
           },
           "event_id": {
             "type": "string",
-            "description": "Event ID."
+            "description": "ID of this delivery record: the delivery date (`YYYYMMDD`) followed by a random suffix. Pass it to `POST /webhook/history/detail`."
           },
           "webhook_type": {
             "type": "string",
@@ -30725,7 +31471,7 @@
           },
           "request_body": {
             "type": "string",
-            "description": "Outbound request body payload."
+            "description": "JSON payload sent to the endpoint, truncated to the stored size limit."
           },
           "endpoint": {
             "type": "string",
@@ -30733,11 +31479,11 @@
           },
           "attempt": {
             "type": "integer",
-            "description": "Attempt sequence number."
+            "description": "Number of HTTP tries made for this delivery; retries happen only on connection errors."
           },
           "duration": {
             "type": "integer",
-            "description": "Total elapsed time of the attempt in milliseconds."
+            "description": "Total time of the delivery including retries, in milliseconds."
           },
           "status": {
             "type": "string",
@@ -30745,15 +31491,15 @@
               "success",
               "failed"
             ],
-            "description": "Delivery outcome."
+            "description": "Delivery outcome: `success` when the endpoint answered HTTP 200; `failed` on a connection error or any other status code."
           },
           "status_code": {
             "type": "integer",
-            "description": "HTTP status code."
+            "description": "HTTP status code returned by the endpoint; `0` when no response was received."
           },
           "error_message": {
             "type": "string",
-            "description": "Error message when delivery failed."
+            "description": "Error text when the delivery failed (connection error or unexpected status code), truncated. Omitted on success."
           },
           "response_headers": {
             "type": "string",
@@ -30761,7 +31507,7 @@
           },
           "response_body": {
             "type": "string",
-            "description": "Response body."
+            "description": "Body returned by the endpoint, truncated to the stored size limit. Omitted when empty or when no response was received."
           },
           "event_time": {
             "type": "string",
@@ -30796,11 +31542,11 @@
           "integration_id": {
             "type": "integer",
             "format": "int64",
-            "description": "Integration ID that triggered the webhook."
+            "description": "ID of the webhook integration that sent the request."
           },
           "event_id": {
             "type": "string",
-            "description": "Unique event identifier for the delivery attempt."
+            "description": "ID of this delivery record: the delivery date (`YYYYMMDD`) followed by a random suffix. Pass it to `POST /webhook/history/detail`."
           },
           "webhook_type": {
             "type": "string",
@@ -30829,7 +31575,7 @@
           },
           "request_body": {
             "type": "string",
-            "description": "Outbound request body payload."
+            "description": "JSON payload sent to the endpoint, truncated to the stored size limit."
           },
           "endpoint": {
             "type": "string",
@@ -30837,11 +31583,11 @@
           },
           "attempt": {
             "type": "integer",
-            "description": "Attempt sequence number."
+            "description": "Number of HTTP tries made for this delivery; retries happen only on connection errors."
           },
           "duration": {
             "type": "integer",
-            "description": "Total elapsed time of the attempt in milliseconds."
+            "description": "Total time of the delivery including retries, in milliseconds."
           },
           "status": {
             "type": "string",
@@ -30849,15 +31595,15 @@
               "success",
               "failed"
             ],
-            "description": "Delivery outcome."
+            "description": "Delivery outcome: `success` when the endpoint answered HTTP 200; `failed` on a connection error or any other status code."
           },
           "status_code": {
             "type": "integer",
-            "description": "HTTP status code returned by the destination."
+            "description": "HTTP status code returned by the endpoint; `0` when no response was received."
           },
           "error_message": {
             "type": "string",
-            "description": "Error message when delivery failed."
+            "description": "Error text when the delivery failed (connection error or unexpected status code), truncated. Omitted on success."
           },
           "response_headers": {
             "type": "string",
@@ -30865,7 +31611,7 @@
           },
           "response_body": {
             "type": "string",
-            "description": "Response body returned by the destination."
+            "description": "Body returned by the endpoint, truncated to the stored size limit. Omitted when empty or when no response was received."
           },
           "event_time": {
             "type": "string",
@@ -31074,7 +31820,7 @@
             "type": "string",
             "pattern": "^[a-zA-Z_][a-zA-Z0-9_]{0,39}$",
             "maxLength": 39,
-            "description": "Machine name. Must start with a letter or underscore; 1–40 chars of `[a-zA-Z0-9_]`. Immutable after creation."
+            "description": "Machine name: 1–39 characters of `[a-zA-Z0-9_]`, starting with a letter or underscore. Immutable after creation."
           },
           "display_name": {
             "type": "string",
@@ -31148,11 +31894,11 @@
           "display_name": {
             "type": "string",
             "maxLength": 39,
-            "description": "New display name. Must remain unique within the account."
+            "description": "New display name (max 39 characters); must stay unique among non-deleted fields. Always written."
           },
           "description": {
             "type": "string",
-            "description": "New description."
+            "description": "New description. Always written: omitting it clears the description."
           },
           "options": {
             "type": "array",
@@ -31162,7 +31908,7 @@
             "description": "Replacement options list. Must obey the same per-type rules as create. Note: the update always overwrites `display_name`, `description`, `options`, and `default_value` with the submitted values, so for `single_select`/`multi_select` fields a non-empty `options` list must be sent on every update."
           },
           "default_value": {
-            "description": "Replacement default value. Type must match the field's existing `field_type`.",
+            "description": "New default value; its type must match the field's `field_type`. Always written: omitting it clears the default.",
             "oneOf": [
               {
                 "type": "boolean"
@@ -31270,7 +32016,10 @@
             "description": "Unix timestamp in seconds when the change event occurred."
           },
           "labels": {
-            "type": "object",
+            "type": [
+              "object",
+              "null"
+            ],
             "additionalProperties": {
               "type": "string"
             },
@@ -31291,7 +32040,22 @@
             "format": "int64",
             "description": "Unix timestamp in seconds when the change event was deleted. Omitted when not deleted."
           }
-        }
+        },
+        "required": [
+          "event_id",
+          "account_id",
+          "channel_id",
+          "integration_id",
+          "title",
+          "description",
+          "change_key",
+          "change_status",
+          "link",
+          "event_time",
+          "labels",
+          "created_at",
+          "updated_at"
+        ]
       },
       "ChangeItem": {
         "type": "object",
@@ -31312,14 +32076,15 @@
           },
           "channel_name": {
             "type": "string",
-            "description": "Name of the collaboration channel."
+            "description": "Name of the collaboration channel; an empty string when the change is not routed to an existing channel."
           },
           "channel_status": {
             "type": "string",
-            "description": "Status of the collaboration channel: `enabled` or `disabled`.",
+            "description": "Status of the collaboration channel: `enabled` or `disabled`; an empty string when the change is not routed to an existing channel.",
             "enum": [
               "enabled",
-              "disabled"
+              "disabled",
+              ""
             ]
           },
           "integration_id": {
@@ -31371,11 +32136,14 @@
             "description": "Unix timestamp in seconds when the change ended."
           },
           "labels": {
-            "type": "object",
+            "type": [
+              "object",
+              "null"
+            ],
             "additionalProperties": {
               "type": "string"
             },
-            "description": "Key-value labels attached to the change."
+            "description": "Key-value labels attached to the change; `null` when it has none."
           },
           "link": {
             "type": "string",
@@ -31386,9 +32154,27 @@
             "items": {
               "$ref": "#/components/schemas/ChangeEventItem"
             },
-            "description": "Underlying change events, returned only when include_events is true."
+            "description": "Raw change events reported by the integration that make up this change. Present only when `include_events` is `true`."
           }
-        }
+        },
+        "required": [
+          "change_id",
+          "account_id",
+          "channel_id",
+          "channel_name",
+          "channel_status",
+          "integration_id",
+          "integration_name",
+          "title",
+          "description",
+          "change_key",
+          "change_status",
+          "start_time",
+          "last_time",
+          "end_time",
+          "labels",
+          "link"
+        ]
       },
       "ListChangeRequest": {
         "type": "object",
@@ -31396,24 +32182,25 @@
           "start_time": {
             "type": "integer",
             "format": "int64",
-            "description": "Start of the query window, Unix epoch seconds. Optional — when both `start_time` and `end_time` are omitted or 0, the window defaults to the last hour. Must be less than `end_time`, with a span of at most 31 days. A change matches when its [start_time, last_time] window overlaps the query window.",
+            "description": "Start of the query window, Unix seconds. Required in practice: it must be less than `end_time`, and the window can span at most 31 days. A change matches when its [start_time, last_time] range overlaps the window.",
             "minimum": 0
           },
           "end_time": {
             "type": "integer",
             "format": "int64",
-            "description": "End of the query window, Unix epoch seconds. See `start_time` for defaults and constraints.",
+            "description": "End of the query window, Unix seconds. Required in practice; see `start_time`.",
             "minimum": 0
           },
           "p": {
             "type": "integer",
-            "description": "Page number, starting at 1.",
+            "description": "Page number, starting at 1. Defaults to 1.",
             "format": "int64",
-            "minimum": 1
+            "minimum": 1,
+            "default": 1
           },
           "limit": {
             "type": "integer",
-            "description": "Number of items per page.",
+            "description": "Number of items per page, 1-100. Defaults to 10.",
             "format": "int64",
             "minimum": 1,
             "maximum": 100,
@@ -31423,7 +32210,7 @@
             "type": "array",
             "items": {
               "type": "integer",
-              "description": "",
+              "description": "Channel ID.",
               "format": "int64"
             },
             "description": "Filter by channel IDs."
@@ -31432,7 +32219,7 @@
             "type": "array",
             "items": {
               "type": "integer",
-              "description": "",
+              "description": "Integration ID.",
               "format": "int64"
             },
             "description": "Filter by reporting integration IDs. At least 1 entry when provided.",
@@ -31490,7 +32277,11 @@
             "deprecated": true,
             "description": "Deprecated: use `integration_ids` instead. Single integration ID to filter by."
           }
-        }
+        },
+        "required": [
+          "start_time",
+          "end_time"
+        ]
       },
       "ListChangeResponse": {
         "type": "object",
@@ -31511,7 +32302,12 @@
             },
             "description": "Changes on the current page."
           }
-        }
+        },
+        "required": [
+          "total",
+          "has_next_page",
+          "items"
+        ]
       },
       "WarRoomPersonItem": {
         "type": "object",
@@ -31523,7 +32319,7 @@
           },
           "person_id": {
             "type": "integer",
-            "description": "Person ID.",
+            "description": "Person ID: a member ID, or the account ID when the person is the account owner (`as` = `account`).",
             "format": "int64"
           },
           "person_name": {
@@ -31536,27 +32332,36 @@
           },
           "email": {
             "type": "string",
-            "description": "Email address of the person."
+            "description": "Email address; omitted when the member has not verified it."
           },
           "phone": {
             "type": "string",
-            "description": "Phone number of the person."
+            "description": "Phone number; omitted when the member has not verified it."
           },
           "locale": {
             "type": "string",
-            "description": "Preferred language locale of the person."
+            "description": "Preferred language, e.g. `zh-CN` or `en-US`."
           },
           "time_zone": {
             "type": "string",
-            "description": "Time zone of the person."
+            "description": "IANA time zone name, e.g. `Asia/Shanghai`."
           },
           "as": {
             "type": "string",
-            "description": "Role the person holds in the related context."
+            "enum": [
+              "account",
+              "member"
+            ],
+            "description": "Identity type of the person.\n- `account`: the account owner.\n- `member`: a regular member of the account."
           },
           "status": {
             "type": "string",
-            "description": "Current status of the person."
+            "enum": [
+              "enabled",
+              "pending",
+              "deleted"
+            ],
+            "description": "Membership status.\n- `enabled`: active.\n- `pending`: invited but has not joined yet.\n- `deleted`: removed from the account."
           }
         },
         "required": [
@@ -31569,7 +32374,8 @@
         "properties": {
           "incident_id": {
             "type": "string",
-            "description": "Incident ID, a MongoDB ObjectID hex string."
+            "pattern": "^[0-9a-fA-F]{24}$",
+            "description": "Incident ID (MongoDB ObjectID)."
           }
         },
         "required": [
@@ -31584,9 +32390,12 @@
             "items": {
               "$ref": "#/components/schemas/WarRoomPersonItem"
             },
-            "description": "Historical responders suggested as default war-room observers."
+            "description": "Suggested observers, in timeline order. Empty array when there are none."
           }
-        }
+        },
+        "required": [
+          "observers"
+        ]
       },
       "AddWarRoomMemberRequest": {
         "type": "object",
@@ -31598,15 +32407,16 @@
           },
           "chat_id": {
             "type": "string",
-            "description": "Chat ID of the war room within the IM platform."
+            "description": "Chat ID of the war-room group on the IM platform, as returned for the war room by `POST /incident/war-room/list`."
           },
           "member_ids": {
             "type": "array",
+            "minItems": 1,
             "items": {
               "type": "integer",
               "format": "int64"
             },
-            "description": "Person IDs to add to the war room."
+            "description": "Person IDs (member IDs, or the account ID for the owner) to add. Must not be empty."
           }
         },
         "required": [
@@ -31620,32 +32430,54 @@
         "properties": {
           "content": {
             "type": "string",
-            "description": "Template content to render."
+            "description": "Template source to render for the channel `type`. Empty or omitted previews the channel's built-in preset content. Ignored for `push`."
           },
           "type": {
             "type": "string",
-            "description": "Template channel type that selects the rendering engine. `email` renders as Go html/template; other channels render as text/template. Values match the template channel fields, for example `email`, `sms`, `voice`, `dingtalk`, `wecom`, `feishu`, `feishu_app`, `dingtalk_app`, `wecom_app`, `slack_app`, `teams_app`, `telegram`, `slack`, `zoom`."
+            "description": "Channel to preview; other values return `InvalidParameter`.\n- `email`: email body (HTML template).\n- `sms`, `voice`: SMS text and voice call script.\n- `push`: mobile app push (fixed content; `content` is ignored).\n- `dingtalk`, `wecom`, `feishu`, `zoom`, `telegram`, `slack`: robot (webhook) messages.\n- `feishu_app`, `dingtalk_app`, `wecom_app`, `slack_app`, `teams_app`: IM app cards.",
+            "enum": [
+              "email",
+              "sms",
+              "voice",
+              "push",
+              "dingtalk",
+              "wecom",
+              "feishu",
+              "zoom",
+              "telegram",
+              "slack",
+              "feishu_app",
+              "dingtalk_app",
+              "wecom_app",
+              "slack_app",
+              "teams_app"
+            ]
           },
           "incident_id": {
             "type": "string",
-            "description": "Incident ID whose data is used to render the template; mock data is used when omitted. A MongoDB ObjectID hex string.",
+            "description": "Incident whose data is rendered (24-character hex ID from `/incident/list`); must exist in the account, otherwise `InvalidParameter`. When omitted a mock incident is used.",
             "pattern": "^[0-9a-fA-F]{24}$"
           },
           "incident_card_hidden_fields": {
             "$ref": "#/components/schemas/IncidentCardHiddenFields",
             "description": "Incident card fields to hide per IM app when previewing."
           },
-          "feishu_app_card_v2_enabled": {
+          "feishu_app_card_v2_table_enabled": {
             "type": "boolean",
-            "description": "Render the preview as a Feishu app card v2 message."
+            "default": false,
+            "description": "Render Markdown tables in `feishu_app` content as native Feishu card tables, as the template setting of the same name does."
           },
           "feishu_app_card_v2_preserve_blank_lines": {
             "type": "boolean",
             "description": "Keep blank lines in the body of the Feishu app card v2 preview."
+          },
+          "wecom_markdown_v2_enabled": {
+            "type": "boolean",
+            "default": false,
+            "description": "Preview `wecom` content as a `markdown_v2` message, as the template setting of the same name does (size limit 4,096 bytes)."
           }
         },
         "required": [
-          "content",
           "type"
         ],
         "description": "Template preview request."
@@ -31659,24 +32491,166 @@
           },
           "content": {
             "type": "string",
-            "description": "Rendered template output, present when success is true."
+            "description": "Rendered template output; an empty string when `success` is `false`."
           },
           "message": {
             "type": "string",
-            "description": "Error message describing why rendering failed, present when success is false."
+            "description": "Why rendering failed, in the caller's language; an empty string when `success` is `true`."
           },
-          "fixed_fields": {
+          "card": {
+            "type": "object",
+            "description": "Message frame around the rendered template, in the account language. Returned for `email`, `feishu_app`, `dingtalk_app`, `wecom_app`, `slack_app` and `teams_app`; omitted otherwise.",
+            "required": [
+              "title",
+              "elements"
+            ],
+            "properties": {
+              "title": {
+                "type": "string",
+                "description": "Email subject or card title."
+              },
+              "elements": {
+                "type": "array",
+                "description": "Card elements in display order.",
+                "items": {
+                  "type": "object",
+                  "required": [
+                    "type"
+                  ],
+                  "properties": {
+                    "type": {
+                      "type": "string",
+                      "enum": [
+                        "template",
+                        "markdown",
+                        "divider",
+                        "actions"
+                      ],
+                      "description": "Element kind.\n- `template`: where the rendered template (`content`) appears.\n- `markdown`: fixed text in the channel's Markdown, in `content`.\n- `divider`: a horizontal rule.\n- `actions`: a row of buttons, in `actions`."
+                    },
+                    "content": {
+                      "type": "string",
+                      "description": "Markdown text of a `markdown` element; omitted for other kinds."
+                    },
+                    "actions": {
+                      "type": "array",
+                      "description": "Buttons of an `actions` element; omitted for other kinds.",
+                      "items": {
+                        "type": "object",
+                        "required": [
+                          "text"
+                        ],
+                        "properties": {
+                          "text": {
+                            "type": "string",
+                            "description": "Button label."
+                          },
+                          "style": {
+                            "type": "string",
+                            "enum": [
+                              "primary",
+                              "danger",
+                              "select"
+                            ],
+                            "description": "Button style: `primary` (highlighted), `danger` (destructive), `select` (a drop-down menu). Omitted for a plain button."
+                          }
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "blocks": {
             "type": "array",
+            "description": "How the recipient's client shows `content`, split into blocks. Omitted for channels that show the text as is.",
             "items": {
-              "$ref": "#/components/schemas/PreviewIncidentCardFixedField"
-            },
-            "description": "Fixed incident-card fields returned for supported IM previews after the requested hiding rules are applied."
+              "type": "object",
+              "required": [
+                "type"
+              ],
+              "properties": {
+                "type": {
+                  "type": "string",
+                  "enum": [
+                    "markdown",
+                    "table"
+                  ],
+                  "description": "Block kind: `markdown` (text in `content`) or `table` (a table in `columns`/`rows`)."
+                },
+                "content": {
+                  "type": "string",
+                  "description": "Text of a `markdown` block."
+                },
+                "native": {
+                  "type": "boolean",
+                  "description": "`true` when a `table` block is shown as a native card table; omitted otherwise."
+                },
+                "columns": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  },
+                  "description": "Column headers of a `table` block."
+                },
+                "rows": {
+                  "type": "array",
+                  "items": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    }
+                  },
+                  "description": "Cell values of a `table` block, one array per row."
+                },
+                "page_size": {
+                  "type": "integer",
+                  "description": "Rows shown per page in a native table; omitted when not set."
+                }
+              }
+            }
+          },
+          "notices": {
+            "type": "array",
+            "description": "Warnings about how the content will be delivered. Omitted when there are none.",
+            "items": {
+              "type": "object",
+              "required": [
+                "code"
+              ],
+              "properties": {
+                "code": {
+                  "type": "string",
+                  "enum": [
+                    "table_not_rendered",
+                    "native_table_fallback",
+                    "content_too_large"
+                  ],
+                  "description": "Warning kind.\n- `table_not_rendered`: the channel cannot show Markdown tables; they are sent as text.\n- `native_table_fallback`: a table cannot be a native card table and is sent as Markdown; `reason` says why (`too_many_tables`, `too_many_columns`, `too_many_rows`, `cell_too_long`, `unsupported_cell`, `card_too_large`).\n- `content_too_large`: the content exceeds `size_limit_bytes`; `reason` is `truncated` (cut to fit), `compact_fallback` (sent in a compact form) or `rejected` (the channel will refuse it)."
+                },
+                "reason": {
+                  "type": "string",
+                  "description": "Detail for `code`, as listed there; omitted for `table_not_rendered`."
+                }
+              }
+            }
+          },
+          "size_bytes": {
+            "type": "integer",
+            "description": "Size of the rendered content in bytes, measured before any truncation."
+          },
+          "size_limit_bytes": {
+            "type": "integer",
+            "description": "Size limit the channel applies in bytes: 4,000 for robot channels (and `wecom` without `markdown_v2`), 4,096 for `wecom` with `markdown_v2`, 15,000 for `slack_app`, 30,720 for `feishu_app`; `0` when the channel has no limit."
           }
         },
         "required": [
           "success",
           "content",
-          "message"
+          "message",
+          "size_bytes",
+          "size_limit_bytes"
         ],
         "description": "Template preview result."
       },
@@ -31717,11 +32691,21 @@
           },
           "category": {
             "type": "string",
-            "description": "Plugin category; `im` for the IM integrations returned here."
+            "description": "Plugin category. Always `im`, because this endpoint returns only IM integrations.",
+            "enum": [
+              "im"
+            ]
           },
           "plugin_type": {
             "type": "string",
-            "description": "Plugin type identifier of the IM integration, for example `feishu_app`, `dingtalk_app`, `wecom_app`, `slack_app`, or `teams_app`."
+            "description": "IM integration type: `feishu_app` Feishu (Lark), `dingtalk_app` DingTalk, `wecom_app` WeCom, `slack_app` Slack, `teams_app` Microsoft Teams.",
+            "enum": [
+              "feishu_app",
+              "dingtalk_app",
+              "wecom_app",
+              "slack_app",
+              "teams_app"
+            ]
           },
           "plugin_type_name": {
             "type": "string",
@@ -31742,7 +32726,7 @@
           "settings": {
             "type": "object",
             "additionalProperties": true,
-            "description": "Plugin-specific configuration of the integration."
+            "description": "Plugin-specific configuration of the integration; includes `war_room_enabled: true`. Secret values are masked as `******`."
           },
           "no_editable": {
             "type": "boolean",
@@ -31775,12 +32759,12 @@
           },
           "exclusive_data_source_id": {
             "type": "integer",
-            "description": "Legacy exclusive-integration linkage; deprecated.",
+            "description": "Deprecated; always `0` in this response.",
             "format": "int64"
           },
           "integration_id": {
             "type": "integer",
-            "description": "Integration ID, alias of data_source_id.",
+            "description": "Integration ID; same value as `data_source_id`.",
             "format": "int64"
           }
         },
@@ -31892,7 +32876,7 @@
           },
           "url_name": {
             "type": "string",
-            "description": "URL-safe slug, unique per account."
+            "description": "URL-safe slug of the page, unique among the account's pages of the same type."
           },
           "type": {
             "type": "string",
@@ -31951,6 +32935,16 @@
             "type": "array",
             "items": {
               "type": "object",
+              "properties": {
+                "key": {
+                  "type": "string",
+                  "description": "Link text shown on the page."
+                },
+                "value": {
+                  "type": "string",
+                  "description": "URL the link text points to, such as `https://www.example.com`."
+                }
+              },
               "additionalProperties": {
                 "type": "string"
               }
@@ -31981,7 +32975,11 @@
           },
           "template_preference": {
             "type": "string",
-            "description": "Preferred event template type: `pre_defined` or `message`. Omitted when never set."
+            "description": "Event template mode used when publishing events in the console: `message` (status descriptions: per-status texts) or `pre_defined` (full status updates: complete examples with title, status, and description). Omitted when never set; the console then uses `message`.",
+            "enum": [
+              "pre_defined",
+              "message"
+            ]
           }
         },
         "required": [
@@ -32018,7 +33016,7 @@
         "properties": {
           "template_id": {
             "type": "string",
-            "description": "Template ID; obtain it from `POST /incident/post-mortem/template/list`."
+            "description": "ID of the custom template to delete; obtain it from `POST /incident/post-mortem/template/list`."
           }
         }
       },
@@ -32035,13 +33033,14 @@
             "minItems": 1,
             "maxItems": 10,
             "items": {
-              "type": "string"
+              "type": "string",
+              "pattern": "^[0-9a-fA-F]{24}$"
             },
-            "description": "Incident IDs to link to the report. 1-10 incidents."
+            "description": "Incident IDs (MongoDB ObjectIDs) to link to the report, 1–10. All must exist in the account. The same set always maps to the same report."
           },
           "template_id": {
             "type": "string",
-            "description": "Template ID used to initialize the report."
+            "description": "Template ID from `POST /incident/post-mortem/template/list`, e.g. the built-in `post_mortem_default_tmpl_en-us` or `post_mortem_default_tmpl_zh-cn`, or a custom template ID."
           }
         }
       },
@@ -32054,17 +33053,17 @@
             "enum": [
               "created_at_seconds"
             ],
-            "description": "Field used to order results."
+            "description": "Sort field for custom templates. Only `created_at_seconds` is supported, which is also the default."
           },
           "asc": {
             "type": "boolean",
-            "description": "Ascending order when true."
+            "description": "Sort custom templates in ascending order when true; default false (newest first)."
           },
           "p": {
             "type": "integer",
             "format": "int64",
             "minimum": 0,
-            "description": "Page number starting at 1."
+            "description": "Page number starting at 1; 0 or omitted means 1."
           },
           "limit": {
             "type": "integer",
@@ -32072,11 +33071,11 @@
             "minimum": 0,
             "maximum": 100,
             "default": 20,
-            "description": "Page size, at most 100."
+            "description": "Page size, 1–100; 0 or omitted means 20."
           },
           "search_after_ctx": {
             "type": "string",
-            "description": "Cursor from a previous response for forward pagination."
+            "description": "Not supported by this operation; leave it unset and paginate with `p`. If sent, it must be an integer string, and `p` is then ignored (results start from the first page)."
           }
         }
       },
@@ -32094,20 +33093,16 @@
             "items": {
               "$ref": "#/components/schemas/PostMortemTemplate"
             },
-            "description": "Templates in the current page."
+            "description": "Templates on this page; the built-in template is first on page 1."
           },
           "total": {
             "type": "integer",
             "format": "int64",
-            "description": "Total matching templates."
+            "description": "Total number of templates, including the built-in one."
           },
           "has_next_page": {
             "type": "boolean",
             "description": "True when another page is available."
-          },
-          "search_after_ctx": {
-            "type": "string",
-            "description": "Cursor for forward pagination."
           }
         }
       },
@@ -32129,11 +33124,11 @@
           "account_id": {
             "type": "integer",
             "format": "int64",
-            "description": "Account ID that owns the template. 0 for built-in templates."
+            "description": "Account ID that owns the template; 0 for the built-in template."
           },
           "template_id": {
             "type": "string",
-            "description": "Template ID. Built-in templates use a stable `post_mortem_default_tmpl_*` ID."
+            "description": "Template ID: `post_mortem_default_tmpl_zh-cn` or `post_mortem_default_tmpl_en-us` for the built-in templates, a server-generated ID for custom ones."
           },
           "name": {
             "type": "string",
@@ -32145,7 +33140,7 @@
           },
           "content": {
             "type": "string",
-            "description": "BlockNote JSON content used to initialize the report body."
+            "description": "Template body as BlockNote editor JSON (an array of blocks), serialized as a string."
           },
           "content_markdown": {
             "type": "string",
@@ -32154,17 +33149,17 @@
           "team_id": {
             "type": "integer",
             "format": "int64",
-            "description": "Managing team ID. Built-in templates use 0."
+            "description": "Managing team ID; 0 for the built-in template."
           },
           "created_at_seconds": {
             "type": "integer",
             "format": "int64",
-            "description": "Unix timestamp in seconds when the template was created."
+            "description": "Creation time, Unix timestamp in seconds; 0 for the built-in template."
           },
           "updated_at_seconds": {
             "type": "integer",
             "format": "int64",
-            "description": "Unix timestamp in seconds when the template was last updated."
+            "description": "Last update time, Unix timestamp in seconds; 0 for the built-in template."
           }
         }
       },
@@ -32183,7 +33178,7 @@
           },
           "incidents_highest_severity": {
             "type": "string",
-            "description": "Highest severity among linked incidents: `Critical`, `Warning`, `Info`, or `Ok`.",
+            "description": "Highest severity among the linked incidents.\n- `Critical`: critical.\n- `Warning`: warning.\n- `Info`: informational.\n- `Ok`: recovered.",
             "enum": [
               "Critical",
               "Warning",
@@ -32201,13 +33196,13 @@
             "type": "integer",
             "format": "int64",
             "minimum": 0,
-            "description": "Unix timestamp in seconds for the latest linked incident close time. 0 when still open."
+            "description": "Latest close time among the linked incidents, Unix timestamp in seconds. 0 (also when omitted) means still open."
           },
           "incidents_total_duration_seconds": {
             "type": "integer",
             "format": "int64",
             "minimum": 0,
-            "description": "Total incident duration in seconds."
+            "description": "Total incident duration in seconds; 0 when omitted."
           },
           "responder_ids": {
             "type": "array",
@@ -32215,7 +33210,7 @@
               "type": "integer",
               "format": "int64"
             },
-            "description": "Responder member IDs to store on the report."
+            "description": "Member IDs to store as the report's responders. Replaces the stored list; omit or send `[]` to clear it. IDs that do not resolve to a person are dropped."
           }
         }
       },
@@ -32267,7 +33262,7 @@
           },
           "follow_ups": {
             "type": "string",
-            "description": "Follow-up action items as free text."
+            "description": "Follow-ups as free text, replacing the stored string. A JSON array in the console's follow-up format (objects with `title`, `status`, `priority`, `assignee_ids`, …) is also synced into structured follow-up work items."
           }
         }
       },
@@ -32289,7 +33284,7 @@
               "drafting",
               "published"
             ],
-            "description": "Target report status: `drafting` draft, `published` published."
+            "description": "Target report status.\n- `drafting`: being edited; the body can still be replaced with a content reset.\n- `published`: published; media files no longer referenced by the body are deleted."
           }
         }
       },
@@ -32307,7 +33302,8 @@
           },
           "title": {
             "type": "string",
-            "description": "New report title."
+            "maxLength": 256,
+            "description": "New report title, at most 256 characters."
           }
         }
       },
@@ -32327,9 +33323,11 @@
       },
       "TryLinkPersonResponse": {
         "type": "object",
-        "description": "People linked by this attempt. When nobody could be newly linked, the response either carries an empty `new_linked_person_ids` array or omits the `data` field entirely.",
+        "description": "Result of one linking run for the integration.",
         "required": [
-          "new_linked_person_ids"
+          "new_linked_person_ids",
+          "unmatched_count",
+          "no_contact_count"
         ],
         "properties": {
           "new_linked_person_ids": {
@@ -32338,7 +33336,15 @@
               "type": "integer",
               "format": "int64"
             },
-            "description": "Person IDs newly linked during this call."
+            "description": "Person IDs linked to the IM app during this call. Empty when nobody was newly linked."
+          },
+          "unmatched_count": {
+            "type": "integer",
+            "description": "Members with an email or phone that were looked up but not newly linked: not found on the IM platform, the IM account is already linked to another member, or the lookup failed for them."
+          },
+          "no_contact_count": {
+            "type": "integer",
+            "description": "Unlinked members skipped because they have neither an email nor a phone number."
           }
         }
       },
@@ -32352,28 +33358,28 @@
         "properties": {
           "template_id": {
             "type": "string",
-            "description": "Template ID. Omit to create a new template; provide it to update an existing template."
+            "description": "ID of the custom template to replace. Omit it to create a new template (the server generates the ID)."
           },
           "team_id": {
             "type": "integer",
             "format": "int64",
-            "description": "Managing team ID. Required when creating a custom template."
+            "description": "Managing team ID. Required when creating; the team must exist. On update, a different team ID moves the template; omit it or send 0 to keep the current team."
           },
           "name": {
             "type": "string",
-            "description": "Template name."
+            "description": "Template name shown in the console."
           },
           "description": {
             "type": "string",
-            "description": "Template description."
+            "description": "Template description; empty when omitted."
           },
           "content": {
             "type": "string",
-            "description": "BlockNote JSON template content."
+            "description": "Template body as BlockNote editor JSON (an array of blocks), serialized as a string. New reports created from this template start from this body."
           },
           "content_markdown": {
             "type": "string",
-            "description": "Markdown version of the template content."
+            "description": "Markdown version of the body, used as the outline when AI generates a report. Empty when omitted."
           }
         }
       },
@@ -32479,11 +33485,11 @@
                 },
                 "section_id": {
                   "type": "string",
-                  "description": "Parent section ID. Omit to place the component at the top level."
+                  "description": "Parent section ID; must be an existing section of the page. Omit to place the component at the top level (on update too)."
                 },
                 "name": {
                   "type": "string",
-                  "description": "Component display name."
+                  "description": "Component display name; must be unique within the page."
                 },
                 "description": {
                   "type": "string",
@@ -32492,7 +33498,7 @@
                 "order_id": {
                   "type": "integer",
                   "format": "int64",
-                  "description": "Display order within its section."
+                  "description": "Display order within its section; on update an omitted value resets to 0."
                 },
                 "hide_uptime": {
                   "type": "boolean",
@@ -32505,7 +33511,7 @@
                 "available_since_seconds": {
                   "type": "integer",
                   "format": "int64",
-                  "description": "Time the component became (or becomes) available, in Unix seconds. On create, defaults to the current time; on update, replaces the stored value."
+                  "description": "Time the component became available, in Unix seconds, used as the start of its uptime history. Applies only on create, defaulting to the current time; ignored on update."
                 }
               }
             },
@@ -32557,7 +33563,7 @@
                 },
                 "name": {
                   "type": "string",
-                  "description": "Section display name."
+                  "description": "Section display name; must be unique within the page."
                 },
                 "description": {
                   "type": "string",
@@ -32566,7 +33572,7 @@
                 "order_id": {
                   "type": "integer",
                   "format": "int64",
-                  "description": "Display order."
+                  "description": "Display order of the section; on update an omitted value resets to 0."
                 },
                 "hide_uptime": {
                   "type": "boolean",
@@ -32656,7 +33662,7 @@
           },
           "url_name": {
             "type": "string",
-            "description": "URL-safe slug, unique per account and page type.",
+            "description": "URL-safe slug; normalized to lowercase with non-alphanumeric characters replaced by hyphens, and must be unique among the account's pages of the same type.",
             "maxLength": 255
           },
           "type": {
@@ -32669,12 +33675,12 @@
           },
           "custom_domain": {
             "type": "string",
-            "description": "Custom domain for a public status page.",
+            "description": "Custom domain; allowed only for public pages and must not be used by another status page.",
             "maxLength": 255
           },
           "page_title": {
             "type": "string",
-            "description": "Browser title shown for the status page."
+            "description": "Accepted for compatibility but not stored; it has no effect."
           },
           "page_header": {
             "type": "string",
@@ -32706,6 +33712,16 @@
             "description": "Custom navigation links shown on the status page.",
             "items": {
               "type": "object",
+              "properties": {
+                "key": {
+                  "type": "string",
+                  "description": "Link text shown on the page."
+                },
+                "value": {
+                  "type": "string",
+                  "description": "URL the link text points to, such as `https://www.example.com`."
+                }
+              },
               "additionalProperties": {
                 "type": "string"
               }
@@ -32717,7 +33733,7 @@
           },
           "subscription": {
             "$ref": "#/components/schemas/StatusPageSubscriptionItem",
-            "description": "Subscription channel toggles."
+            "description": "Subscription channel toggles; both default to `false`. A public page can enable only `email` and an internal page only `im`."
           }
         },
         "required": [
@@ -32776,7 +33792,7 @@
               "string",
               "null"
             ],
-            "description": "URL-safe slug, unique per account and page type. Omit or pass null to keep the existing value.",
+            "description": "URL-safe slug; normalized to lowercase with non-alphanumeric characters replaced by hyphens, and must be unique among the account's pages of the same type. Omit or pass null to keep the existing value.",
             "maxLength": 255
           },
           "custom_domain": {
@@ -32784,7 +33800,7 @@
               "string",
               "null"
             ],
-            "description": "Custom domain for a public status page. Omit or pass null to keep the existing value.",
+            "description": "Custom domain for a public status page; must not be used by another status page. Rejected for internal pages. Omit or pass null to keep the existing value; an empty string removes the domain.",
             "maxLength": 255
           },
           "page_title": {
@@ -32792,7 +33808,7 @@
               "string",
               "null"
             ],
-            "description": "Browser title shown for the status page. Omit or pass null to keep the existing value."
+            "description": "Accepted for compatibility but not stored; it has no effect."
           },
           "logo": {
             "type": [
@@ -32842,10 +33858,12 @@
               "string",
               "null"
             ],
-            "description": "How change dates are displayed. Leave empty to keep the current value. `calendar` uses a calendar view; `list` uses a list view.",
+            "description": "How event dates are displayed: `calendar` uses a calendar view, `list` uses a list view. Omit or pass null to keep the current value; an empty string clears the setting.",
             "enum": [
               "calendar",
-              "list"
+              "list",
+              "",
+              null
             ]
           },
           "display_uptime_mode": {
@@ -32853,11 +33871,13 @@
               "string",
               "null"
             ],
-            "description": "How uptime is displayed. Leave empty to keep the current value. `chart_and_percentage` shows both chart and percentage; `chart` shows only the chart; `none` hides uptime.",
+            "description": "How uptime is displayed: `chart_and_percentage` shows the chart and the percentage, `chart` shows only the chart, `none` hides uptime. Omit or pass null to keep the current value; an empty string clears the setting.",
             "enum": [
               "chart_and_percentage",
               "chart",
-              "none"
+              "none",
+              "",
+              null
             ]
           },
           "custom_links": {
@@ -32865,6 +33885,16 @@
             "description": "Custom navigation links shown on the status page. Omit or pass an empty array to keep the current links.",
             "items": {
               "type": "object",
+              "properties": {
+                "key": {
+                  "type": "string",
+                  "description": "Link text shown on the page."
+                },
+                "value": {
+                  "type": "string",
+                  "description": "URL the link text points to, such as `https://www.example.com`."
+                }
+              },
               "additionalProperties": {
                 "type": "string"
               }
@@ -32879,14 +33909,19 @@
           },
           "subscription": {
             "$ref": "#/components/schemas/StatusPageSubscriptionItem",
-            "description": "Subscription channel toggles. Omit or pass null to keep the existing value."
+            "description": "Subscription channel toggles. A public page can enable only `email` and an internal page only `im`. Omit or pass null to keep the existing value."
           },
           "template_preference": {
             "type": [
               "string",
               "null"
             ],
-            "description": "Preferred event template type: `pre_defined` or `message`. Omit or pass null to keep the existing value."
+            "description": "Event template mode used when publishing events in the console: `message` (status descriptions: per-status texts) or `pre_defined` (full status updates: complete examples with title, status, and description). Omit or pass null to keep the current value; the value is not validated.",
+            "enum": [
+              "pre_defined",
+              "message",
+              null
+            ]
           }
         }
       },
@@ -32945,7 +33980,7 @@
         },
         "additionalProperties": {
           "type": "array",
-          "description": "Incident-card field names to hide for this IM app.",
+          "description": "Fields to hide on this app's incident cards: `channel` (channel name), `snoozed_before` (snooze end time), `severity`, `responders`, `aggregate_alert_count` (number of merged alerts), `detail` (Detail button), `ai_analysis` (AI Analysis button).",
           "items": {
             "type": "string",
             "enum": [
@@ -32960,31 +33995,6 @@
           }
         }
       },
-      "PreviewIncidentCardFixedField": {
-        "type": "object",
-        "description": "Fixed incident-card fields returned for supported IM previews after the requested hiding rules are applied.",
-        "required": [
-          "field",
-          "value"
-        ],
-        "properties": {
-          "field": {
-            "type": "string",
-            "enum": [
-              "channel",
-              "snoozed_before",
-              "severity",
-              "responders",
-              "aggregate_alert_count"
-            ],
-            "description": "Incident-card field name.\n\n| Value | Meaning |\n|---|---|\n| `channel` | Name of the alert channel that produced the incident; returned only when non-empty. |\n| `snoozed_before` | Snooze-until timestamp formatted as `YYYY-MM-DD HH:MM:SS`; returned only while the incident is snoozed. |\n| `severity` | Incident severity label; returned only when non-empty. |\n| `responders` | Names of the current responders, separated by spaces; returned only when the incident has responders. |\n| `aggregate_alert_count` | Number of alerts aggregated into the incident; returned only when greater than 1. |"
-          },
-          "value": {
-            "type": "string",
-            "description": "Rendered display value for the fixed field."
-          }
-        }
-      },
       "FieldDeleteReference": {
         "type": "object",
         "description": "Custom form that still references the field.",
@@ -32996,8 +34006,10 @@
         "properties": {
           "kind": {
             "type": "string",
-            "const": "custom_form",
-            "description": "Referenced resource kind. Always `custom_form` for this response."
+            "description": "Referenced resource kind. Always `custom_form` for this response.",
+            "enum": [
+              "custom_form"
+            ]
           },
           "name": {
             "type": "string",
@@ -33100,7 +34112,7 @@
             "type": "integer",
             "format": "int64",
             "minimum": 0,
-            "description": "Page number starting at 1. Ignored when `search_after_ctx` is set."
+            "description": "Not supported; pagination uses only `search_after_ctx`, so this value is ignored."
           },
           "limit": {
             "type": "integer",
@@ -33289,7 +34301,10 @@
             },
             "description": "All comment types of the account, ordered by position."
           }
-        }
+        },
+        "required": [
+          "items"
+        ]
       },
       "CreateIncidentCommentTypeRequest": {
         "type": "object",
@@ -33302,7 +34317,7 @@
           "name": {
             "type": "string",
             "maxLength": 40,
-            "description": "Display name. Trimmed before storing; must be unique within the account (case-insensitive). At most 40 characters."
+            "description": "Display name. Trimmed before storing; must be unique within the account (case-insensitive). At most 40 characters. Must not contain control or text-direction characters."
           },
           "color": {
             "type": "string",
@@ -33344,7 +34359,7 @@
           "name": {
             "type": "string",
             "maxLength": 40,
-            "description": "New display name. Trimmed before storing; must be unique within the account (case-insensitive). At most 40 characters."
+            "description": "New display name. Trimmed before storing; must be unique within the account (case-insensitive). At most 40 characters. Must not contain control or text-direction characters."
           },
           "color": {
             "type": "string",
@@ -33415,7 +34430,7 @@
               "action",
               "follow_up"
             ],
-            "description": "`action` for an item anchored to an active incident; `follow_up` for a post-mortem follow-up."
+            "description": "Work item type.\n- `action`: a to-do on an incident that is not closed yet.\n- `follow_up`: a post-mortem follow-up, created on a closed incident or converted from an action."
           },
           "incident_id": {
             "type": "string",
@@ -33424,7 +34439,7 @@
           },
           "post_mortem_id": {
             "type": "string",
-            "description": "Post-mortem ID (32-character hex string). Present on follow-up items once bound to a post-mortem."
+            "description": "Post-mortem ID (32-character hex string). Present only on follow-ups bound to a report; omitted otherwise."
           },
           "title": {
             "type": "string",
@@ -33439,12 +34454,12 @@
           "status": {
             "type": "string",
             "maxLength": 64,
-            "description": "Client-defined status (max 64 characters). There is no fixed state machine."
+            "description": "Item status: `open` (not started), `in_progress` (being worked on), `done` (finished) or `cancelled` (no longer needed). `done` and `cancelled` count as finished. Older items may still hold other free text, which counts as unfinished."
           },
           "priority": {
             "type": "string",
             "maxLength": 64,
-            "description": "Optional client-defined priority (max 64 characters)."
+            "description": "Free-form priority, at most 64 characters; omitted when empty. The console uses `high`, `medium` and `low`, but any string set through the API is returned as-is."
           },
           "source_kind": {
             "type": "string",
@@ -33538,7 +34553,7 @@
               "type": "integer",
               "format": "int64"
             },
-            "description": "Assignee member IDs that were newly added (and notified)."
+            "description": "Member IDs of the person assignees added by this call (and notified); AI SRE is not included. Omitted when none."
           },
           "idempotent_replay": {
             "type": "boolean",
@@ -33548,7 +34563,7 @@
       },
       "WorkItemMutationResult": {
         "type": "object",
-        "description": "Result of mutating a work item.",
+        "description": "Result of mutating a work item. `item` is absent for delete.",
         "properties": {
           "item": {
             "$ref": "#/components/schemas/WorkItemItem"
@@ -33559,7 +34574,7 @@
               "type": "integer",
               "format": "int64"
             },
-            "description": "Assignee member IDs that were newly added (and notified)."
+            "description": "Member IDs of the person assignees added by this call (and notified); AI SRE is not included. Omitted when none."
           },
           "removed_assignee_ids": {
             "type": "array",
@@ -33567,7 +34582,7 @@
               "type": "integer",
               "format": "int64"
             },
-            "description": "Assignee member IDs that were removed (never notified)."
+            "description": "Member IDs of the person assignees removed by this call (never notified). Omitted when none."
           },
           "idempotent_replay": {
             "type": "boolean",
@@ -33628,7 +34643,7 @@
           "assignee_id": {
             "type": "integer",
             "format": "int64",
-            "description": "Restrict results to items assigned to this member ID. Listing by assignee alone requires being that assignee or an account admin. Ignored when `assignee_type` is `ai_sre`."
+            "description": "Restrict results to items assigned to this member ID. Listing by assignee alone requires being that member or an account owner or admin. Ignored when `assignee_type` is `ai_sre`."
           },
           "assignee_type": {
             "description": "Filter by assignee type: `person` or `ai_sre`. `ai_sre` returns items assigned to AI SRE (an AI caller uses this to list its own tasks) and does not require `assignee_id`. `person` together with `assignee_id` restricts results to that member. Omitted with a positive `assignee_id` means `person`.",
@@ -33640,15 +34655,13 @@
           },
           "cursor": {
             "type": "string",
-            "description": "Pagination cursor from a previous response's `next_cursor`."
+            "description": "Opaque cursor from a previous response's `next_cursor`. An invalid cursor returns `InvalidParameter`."
           },
           "limit": {
             "type": "integer",
             "format": "int64",
-            "minimum": 0,
-            "maximum": 200,
             "default": 50,
-            "description": "Page size, at most 200. Defaults to 50."
+            "description": "Page size. 0, negative or omitted means 50; values above 200 are treated as 200."
           }
         }
       },
@@ -33668,12 +34681,12 @@
               "action",
               "follow_up"
             ],
-            "description": "`action` anchors to an active incident and must not set `post_mortem_id`; `follow_up` requires `post_mortem_id`."
+            "description": "Work item type.\n- `action`: a to-do on an incident that is not closed yet; must not set `post_mortem_id`.\n- `follow_up`: a post-mortem follow-up on a closed incident; `post_mortem_id` is optional."
           },
           "title": {
             "type": "string",
             "maxLength": 512,
-            "description": "Item title (max 512 characters)."
+            "description": "Item title, at most 512 characters; leading and trailing spaces are trimmed and it must not be blank."
           },
           "description": {
             "type": "string",
@@ -33694,7 +34707,7 @@
           "priority": {
             "type": "string",
             "maxLength": 64,
-            "description": "Optional client-defined priority (max 64 characters)."
+            "description": "Optional free-form priority, at most 64 characters. The console uses `high`, `medium` and `low`; any other string is stored as-is."
           },
           "incident_id": {
             "type": "string",
@@ -33703,7 +34716,7 @@
           },
           "post_mortem_id": {
             "type": "string",
-            "description": "Post-mortem ID (32-character hex string). Required for `follow_up`, forbidden for `action`. The post-mortem must be linked to `incident_id`."
+            "description": "Post-mortem ID (32-character hex string). Forbidden for `action`. Optional for `follow_up`: when set, the incident must be linked to that report; when omitted, the incident's post-mortem is used if it exists."
           },
           "assignee_ids": {
             "type": "array",
@@ -33731,7 +34744,7 @@
       },
       "UpdateWorkItemRequest": {
         "type": "object",
-        "description": "Partial patch for a work item. Omitted fields stay unchanged; an explicit `null` clears the field.",
+        "description": "Partial patch for a work item. Omitted fields and fields sent as `null` stay unchanged.",
         "required": [
           "work_item_id",
           "version"
@@ -33745,14 +34758,14 @@
           "version": {
             "type": "integer",
             "format": "int64",
-            "description": "Current item version for optimistic locking. Must match the stored version."
+            "description": "The item's current `version` (≥ 1) for optimistic locking."
           },
           "title": {
             "type": [
               "string",
               "null"
             ],
-            "description": "New title (max 512 characters).",
+            "description": "New title, at most 512 characters; trimmed and must not be blank. `null` or omitted keeps the current title.",
             "maxLength": 512
           },
           "description": {
@@ -33760,7 +34773,7 @@
               "string",
               "null"
             ],
-            "description": "New description (max 65,535 characters).",
+            "description": "New description, at most 65,535 characters; `\"\"` clears it. `null` or omitted keeps the current value.",
             "maxLength": 65535
           },
           "status": {
@@ -33772,17 +34785,17 @@
               "open",
               "in_progress",
               "done",
-              "cancelled"
+              "cancelled",
+              null
             ],
-            "description": "New status. One of `open`, `in_progress`, `done`, `cancelled`.",
-            "maxLength": 64
+            "description": "New status. `null` or omitted keeps the current status.\n- `open`: not started.\n- `in_progress`: being worked on.\n- `done`: finished.\n- `cancelled`: no longer needed."
           },
           "priority": {
             "type": [
               "string",
               "null"
             ],
-            "description": "New client-defined priority (max 64 characters).",
+            "description": "New free-form priority, at most 64 characters; `\"\"` clears it. `null` or omitted keeps the current value.",
             "maxLength": 64
           }
         }
@@ -33803,7 +34816,7 @@
           "version": {
             "type": "integer",
             "format": "int64",
-            "description": "Current item version for optimistic locking. Must match the stored version."
+            "description": "The item's current `version` (≥ 1) for optimistic locking."
           }
         }
       },
@@ -33860,7 +34873,7 @@
           "version": {
             "type": "integer",
             "format": "int64",
-            "description": "Current item version for optimistic locking. Must match the stored version."
+            "description": "The item's current `version` (≥ 1) for optimistic locking."
           },
           "target_status": {
             "type": [
@@ -33871,10 +34884,11 @@
               "open",
               "in_progress",
               "done",
-              "cancelled"
+              "cancelled",
+              null
             ],
-            "description": "Optional status to set on the converted follow-up. One of `open`, `in_progress`, `done`, `cancelled`.",
-            "maxLength": 64
+            "maxLength": 64,
+            "description": "Optional status to set on the converted follow-up; omitted or `null` keeps the current status. Values: `open` (not started), `in_progress` (being worked on), `done` (finished), `cancelled` (no longer needed)."
           },
           "idempotency_key": {
             "type": "string",
@@ -33886,7 +34900,7 @@
       },
       "ResetWorkItemAssigneesRequest": {
         "type": "object",
-        "description": "Full replacement of a work item's assignee set.",
+        "description": "Full replacement of a work item's assignee set. Exactly one of `assignees` or `assignee_ids` must be sent.",
         "required": [
           "work_item_id",
           "version"
@@ -33900,7 +34914,7 @@
           "version": {
             "type": "integer",
             "format": "int64",
-            "description": "Current item version for optimistic locking. Must match the stored version."
+            "description": "The item's current `version` (≥ 1) for optimistic locking."
           },
           "assignee_ids": {
             "type": "array",
@@ -33936,7 +34950,7 @@
           "incident_id": {
             "type": "string",
             "pattern": "^[0-9a-fA-F]{24}$",
-            "description": "Incident ID (MongoDB ObjectID) whose converted-but-unbound follow-ups are bound."
+            "description": "Incident ID (MongoDB ObjectID) whose converted, unbound items are bound. It must be linked to `post_mortem_id`."
           },
           "idempotency_key": {
             "type": "string",
@@ -33978,7 +34992,7 @@
         "properties": {
           "work_item_id": {
             "type": "string",
-            "description": "Work item ID."
+            "description": "Work item ID (`wi_` followed by a random string); use it with the `/incident/work-item/*` endpoints."
           },
           "item_type": {
             "type": "string",
@@ -33994,7 +35008,13 @@
           },
           "status": {
             "type": "string",
-            "description": "Work item status label (e.g. `open`, `done`)."
+            "description": "Work item status at creation: `open` not started; `in_progress` being worked on; `done` completed; `cancelled` no longer needed.",
+            "enum": [
+              "open",
+              "in_progress",
+              "done",
+              "cancelled"
+            ]
           },
           "assignee_ids": {
             "type": "array",
@@ -34024,7 +35044,7 @@
         "properties": {
           "work_item_id": {
             "type": "string",
-            "description": "Work item ID."
+            "description": "Work item ID (`wi_` followed by a random string); use it with the `/incident/work-item/*` endpoints."
           },
           "item_type": {
             "type": "string",
@@ -34044,19 +35064,25 @@
           },
           "from_status": {
             "type": "string",
-            "description": "Status label before the update."
+            "description": "Status before the update; present only when the status changed. Usually one of `open`, `in_progress`, `done`, `cancelled`; items created before these statuses existed may carry other text."
           },
           "to_status": {
             "type": "string",
-            "description": "Status label after the update."
+            "description": "Status after the update; present only when the status changed. `open` not started; `in_progress` being worked on; `done` completed; `cancelled` no longer needed.",
+            "enum": [
+              "open",
+              "in_progress",
+              "done",
+              "cancelled"
+            ]
           },
           "from_priority": {
             "type": "string",
-            "description": "Priority label before the update."
+            "description": "Priority before the update. Free-text priority label defined by the client (up to 64 characters); present only when the priority changed."
           },
           "to_priority": {
             "type": "string",
-            "description": "Priority label after the update."
+            "description": "Priority after the update. Free-text priority label defined by the client (up to 64 characters); present only when the priority changed."
           },
           "from_description": {
             "type": "string",
@@ -34075,7 +35101,7 @@
         "properties": {
           "work_item_id": {
             "type": "string",
-            "description": "Work item ID."
+            "description": "Work item ID (`wi_` followed by a random string); use it with the `/incident/work-item/*` endpoints."
           },
           "item_type": {
             "type": "string",
@@ -34143,7 +35169,7 @@
         "properties": {
           "work_item_id": {
             "type": "string",
-            "description": "Work item ID."
+            "description": "Work item ID (`wi_` followed by a random string); use it with the `/incident/work-item/*` endpoints."
           },
           "item_type": {
             "type": "string",
@@ -34159,11 +35185,14 @@
           },
           "from_status": {
             "type": "string",
-            "description": "Status label before completion."
+            "description": "Status before completion, usually `open` or `in_progress`; items created before these statuses existed may carry other text."
           },
           "to_status": {
             "type": "string",
-            "description": "Status label after completion."
+            "description": "Status after completion; always `done`.",
+            "enum": [
+              "done"
+            ]
           },
           "post_mortem_id": {
             "type": "string",
@@ -34178,7 +35207,7 @@
         "properties": {
           "work_item_id": {
             "type": "string",
-            "description": "Work item ID."
+            "description": "Work item ID (`wi_` followed by a random string); use it with the `/incident/work-item/*` endpoints."
           },
           "title": {
             "type": "string",
@@ -34206,7 +35235,7 @@
           },
           "status": {
             "type": "string",
-            "description": "Work item status label after the conversion."
+            "description": "Work item status after the conversion, usually `open` or `in_progress` (conversion keeps the status)."
           }
         },
         "title": "i_wi_converted"
@@ -34217,7 +35246,7 @@
         "properties": {
           "work_item_id": {
             "type": "string",
-            "description": "Work item ID."
+            "description": "Work item ID (`wi_` followed by a random string); use it with the `/incident/work-item/*` endpoints."
           },
           "item_type": {
             "type": "string",
@@ -34244,7 +35273,7 @@
         "properties": {
           "work_item_id": {
             "type": "string",
-            "description": "Work item ID."
+            "description": "Work item ID (`wi_` followed by a random string); use it with the `/incident/work-item/*` endpoints."
           },
           "item_type": {
             "type": "string",
@@ -34317,12 +35346,12 @@
         "properties": {
           "is_enabled": {
             "type": "boolean",
-            "description": "When true, repeated events merge into the existing alert; when false, every event creates a separate alert. Defaults to true."
+            "description": "When true, repeated events of the same alert merge into the existing alert; when false, every event creates a separate alert. If you send `event_group`, set this explicitly: an omitted value means `false`. When the whole `event_group` is omitted on create, merging is enabled."
           },
           "time_window": {
             "type": "integer",
             "minimum": 1,
-            "description": "Merge window in minutes, 1-1440 (24 h); accounts with the extended limit may use up to 10080 (7 days). Defaults to 1440."
+            "description": "Merge window in minutes, required when `is_enabled` is true. The range is 1–1440 by default; accounts with the extended merge window enabled can set up to 10080 (7 days). Ignored when merging is disabled."
           }
         }
       },
@@ -34365,7 +35394,7 @@
               "incident",
               "maintenance"
             ],
-            "description": "Change type the template applies to: `incident` unplanned incident, `maintenance` planned maintenance."
+            "description": "Change type the template applies to: `incident` unplanned incident, `maintenance` planned maintenance. Set on create; ignored on update."
           },
           "status": {
             "type": "string",
@@ -34542,10 +35571,26 @@
         "description": "The member's on-call status: the shift in progress, the next one, and every enabled schedule they participate in.",
         "properties": {
           "current": {
-            "$ref": "#/components/schemas/MemberOncallInterval"
+            "oneOf": [
+              {
+                "$ref": "#/components/schemas/MemberOncallInterval"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "Shift in progress now; `null` when the member is not on call."
           },
           "next": {
-            "$ref": "#/components/schemas/MemberOncallInterval"
+            "oneOf": [
+              {
+                "$ref": "#/components/schemas/MemberOncallInterval"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "Next upcoming shift (without `end_at`); `null` when none within 45 days."
           },
           "schedules": {
             "type": "array",
@@ -34565,12 +35610,12 @@
         "properties": {
           "schedule_id": {
             "type": "integer",
-            "description": "Schedule ID.",
+            "description": "ID of a schedule the member participates in; pass it to `/schedule/info`.",
             "format": "int64"
           },
           "schedule_name": {
             "type": "string",
-            "description": "Schedule name."
+            "description": "Name of that schedule."
           }
         }
       },
@@ -34594,7 +35639,7 @@
           },
           "end_at": {
             "type": "integer",
-            "description": "Unix timestamp in seconds - when the shift ends. Absent while the shift is ongoing.",
+            "description": "Unix timestamp in seconds when the shift ends. Present on `current`; omitted on `next`.",
             "format": "int64"
           }
         }
@@ -34629,7 +35674,7 @@
           },
           "category": {
             "type": "string",
-            "description": "Filter by category. Accepts a comma-separated list, for example `event.alert,event.change`."
+            "description": "Comma-separated category filter. Values: `event.alert` (alert events), `event.change` (change events), `im` (IM bots), `webhook` (custom webhooks). Unknown values are not rejected and match nothing."
           },
           "asc": {
             "type": [
@@ -34655,7 +35700,7 @@
         "properties": {
           "plugin_type": {
             "type": "string",
-            "description": "Type identifier to pass as `plugin_type` when creating an integration.",
+            "description": "Type key to pass as `plugin_type` when creating an integration, for example `standard.alert`, `prometheus.alert`, `zabbix.alert` or `feishu`. The set grows as integrations are added; this endpoint returns the full list.",
             "example": "standard.alert"
           },
           "plugin_type_name": {
@@ -34679,7 +35724,11 @@
           },
           "status": {
             "type": "string",
-            "description": "Platform status of the type."
+            "description": "Platform status of the type: `enabled` types can be used; `disabled` types are switched off platform-wide and `POST /integration/create` or `POST /integration/update` returns `InvalidParameter` for them.",
+            "enum": [
+              "enabled",
+              "disabled"
+            ]
           },
           "supports_api_create": {
             "type": "boolean",
@@ -34749,23 +35798,23 @@
           },
           "category": {
             "type": "string",
-            "description": "Filter by category. Accepts a comma-separated list."
+            "description": "Comma-separated category filter. Values: `event.alert` (alert events), `event.change` (change events), `im` (IM bots), `webhook` (custom webhooks). Unknown values are not rejected and match nothing."
           },
           "type": {
             "type": "string",
-            "description": "Deprecated. Merged into `plugin_type` when both are set."
+            "description": "Deprecated alias of `plugin_type` (comma-separated type keys such as `prometheus.alert`, `zabbix.alert`). Ignored when `plugin_type` is also set."
           },
           "plugin_type": {
             "type": "string",
-            "description": "Filter by integration type. Accepts a comma-separated list."
+            "description": "Comma-separated integration type keys, for example `standard.alert,prometheus.alert`; the keys are the `plugin_type` values from `POST /integration/type/list`."
           },
           "status": {
             "type": "string",
-            "description": "Filter by status. Accepts a comma-separated list."
+            "description": "Comma-separated status filter: `enabled` (accepting events) and/or `disabled` (paused)."
           },
           "name": {
             "type": "string",
-            "description": "Filter by integration name."
+            "description": "Filter by integration name; matches any name that contains this text."
           },
           "ref_ids": {
             "type": "array",
@@ -34823,7 +35872,7 @@
           "integration_id": {
             "type": "integer",
             "format": "int64",
-            "description": "Integration ID."
+            "description": "Integration ID; pass it as `integration_id` to the other `/integration/*` endpoints."
           },
           "team_id": {
             "type": "integer",
@@ -34975,7 +36024,7 @@
             "type": "integer",
             "format": "int64",
             "minimum": 1,
-            "description": "Integration ID.",
+            "description": "ID of a public integration, returned by `POST /integration/list`. An unknown ID or a channel-owned integration returns `ResourceNotFound`.",
             "example": 6113996590131
           }
         }
@@ -35008,7 +36057,7 @@
           "integration_id": {
             "type": "integer",
             "format": "int64",
-            "description": "Integration ID."
+            "description": "Integration ID; pass it as `integration_id` to the other `/integration/*` endpoints."
           },
           "team_id": {
             "type": "integer",
@@ -35220,7 +36269,7 @@
             "type": "integer",
             "format": "int64",
             "minimum": 1,
-            "description": "Integration ID.",
+            "description": "ID of a public integration, returned by `POST /integration/list`. An unknown ID or a channel-owned integration returns `ResourceNotFound`.",
             "example": 6113996590131
           },
           "name": {
@@ -35271,7 +36320,7 @@
             "type": "integer",
             "format": "int64",
             "minimum": 1,
-            "description": "Integration ID.",
+            "description": "ID of a public integration, returned by `POST /integration/list`. An unknown ID or a channel-owned integration returns `ResourceNotFound`.",
             "example": 6113996590131
           }
         }
diff --git a/api-reference/on-call.openapi.zh.json b/api-reference/on-call.openapi.zh.json
index 7a73371c9..23528f69e 100644
--- a/api-reference/on-call.openapi.zh.json
+++ b/api-reference/on-call.openapi.zh.json
@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Flashduty 开放 API",
-    "description": "Flashduty 事件管理平台的公开 HTTP API —— 覆盖故障、通知模板、协作空间、值班排班、监控、RUM、以及平台管理。每次调用都需在 query 中携带 `app_key`，该 key 在 Flashduty 控制台 账户 → APP Key 中签发。所有响应使用统一结构：成功时为 `{ request_id, data }`，失败时为 `{ request_id, error }`。",
+    "description": "Flashduty 事件管理平台的公开 HTTP API —— 覆盖故障、通知模板、协作空间、值班排班、监控、RUM、以及平台管理。每次调用都需在 query 中携带 `app_key`，该 key 在 Flashduty 控制台 我的 → APP Key 中创建（也可放在请求头 `Fd-App-Key` 中）。所有响应使用统一结构：成功时为 `{ request_id, data }`，失败时为 `{ request_id, error }`。",
     "version": "1.0.0"
   },
   "servers": [
@@ -75,12 +75,12 @@
       "post": {
         "operationId": "channelInhibitRuleDelete",
         "summary": "删除抑制策略",
-        "description": "删除抑制策略。仅 `disabled` 状态的策略可删除。",
+        "description": "删除已禁用的抑制策略，使其不再出现在协作空间的策略列表中。",
         "tags": [
           "On-call/协作空间"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 仅 `disabled` 状态的策略可删除，其他状态返回 `InvalidParameter`。\n- `channel_id` 或 `rule_id` 不存在时返回 `InvalidParameter`。\n- 调用者还必须拥有该协作空间的编辑权：账户所有者或管理员、协作空间创建者，或其管理团队成员（`managing_team_ids` 为空时为所属团队成员），否则返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志。",
           "href": "/zh/api-reference/on-call/channels/channel-inhibit-rule-delete",
           "metadata": {
             "sidebarTitle": "删除抑制策略"
@@ -119,6 +119,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -151,7 +154,7 @@
           "On-call/集成中心"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **集成中心查看**（`on-call`） |\n\n## 使用说明\n\n- 不传 `orderby` 时按控制台排序返回，此时 `p`/`limit` 依然生效。\n- `supports_api_create` 表示该类型能否通过 `POST /integration/create` 创建。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **集成中心查看**（`on-call`） |\n\n## 使用说明\n\n- 不传 `orderby` 时按控制台排序返回，此时 `p`/`limit` 依然生效。\n- `supports_api_create` 表示该类型能否通过 `POST /integration/create` 创建。\n- `category` 取值不做校验，未知值会返回空列表。",
           "href": "/zh/api-reference/on-call/integrations/integration-api-read-type-list",
           "metadata": {
             "sidebarTitle": "查询集成类型列表"
@@ -212,6 +215,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -245,7 +251,7 @@
           "On-call/集成中心"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **集成中心查看**（`on-call`） |\n\n## 使用说明\n\n- `orderby` 默认 `created_at`；`plugin_type` 按底层插件排序。\n- `plugin_type`、`status`、`category` 支持逗号分隔多值；`ref_ids` 每个值必须以 `c_`、`a_` 或 `w_` 开头；`c_` 过滤值通过格式校验，但不会返回协作空间专属集成。\n- 传入 `is_my_team` 时仅返回你所在团队的集成，`team_ids` 会在该范围内进一步收窄。\n- 这些接口仅管理公共（账户级）集成，不管理协作空间专属集成。\n- 列表项包含 `settings`、`integration_key`、`plugin_id`、`account_id` 及旧 ID 别名 `data_source_id`。`settings` 中已保存的密钥类值返回 `******`，`integration_key` 按原值返回。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **集成中心查看**（`on-call`） |\n\n## 使用说明\n\n- `orderby` 默认 `created_at`；`plugin_type` 按底层插件排序。结果先按 `ref_id` 升序排列，`orderby` 在相同 `ref_id` 内生效。\n- `plugin_type`、`status`、`category` 支持逗号分隔多值；`ref_ids` 每个值必须以 `c_`、`a_` 或 `w_` 开头；`c_` 过滤值通过格式校验，但不会返回协作空间专属集成。\n- 传入 `is_my_team` 时仅返回你所在团队的集成，`team_ids` 会在该范围内进一步收窄；你不属于任何团队，或 `team_ids` 与你的团队没有交集时，返回空列表。\n- 这些接口仅管理公共（账户级）集成，不管理协作空间专属集成。\n- 列表项包含 `settings`、`integration_key`、`plugin_id`、`account_id` 及旧 ID 别名 `data_source_id`。`settings` 中已保存的密钥类值返回 `******`，`integration_key` 按原值返回。",
           "href": "/zh/api-reference/on-call/integrations/integration-api-read-list",
           "metadata": {
             "sidebarTitle": "查询集成列表"
@@ -317,6 +323,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -350,7 +359,7 @@
           "On-call/集成中心"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **集成中心查看**（`on-call`） |\n\n## 使用说明\n\n- 这些接口仅管理公共（账户级）集成，不管理协作空间专属集成。\n- `settings` 中已保存的密钥类值返回 `******`，未设置的保持为空；集成 Key 按原值返回。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **集成中心查看**（`on-call`） |\n\n## 使用说明\n\n- 这些接口仅管理公共（账户级）集成，不管理协作空间专属集成。\n- `settings` 中已保存的密钥类值返回 `******`，未设置的保持为空；集成 Key 按原值返回。\n- ID 不存在或属于协作空间专属集成时返回 `ResourceNotFound`。",
           "href": "/zh/api-reference/on-call/integrations/integration-api-read-info",
           "metadata": {
             "sidebarTitle": "查询集成详情"
@@ -412,6 +421,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -443,7 +455,7 @@
           "On-call/集成中心"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **集成中心管理**（`on-call`） |\n\n## 使用说明\n\n- `plugin_type` 必须是 `POST /integration/type/list` 中 `supports_api_create: true` 的类型，否则返回 `InvalidParameter`。\n- 这些接口仅管理公共（账户级）集成，不管理协作空间专属集成。\n- 不传 `integration_key` 时自动生成；传入时须满足长度、账户后缀与唯一性校验。\n- 传 `is_test: true` 时请检查 `test.success`，不能只根据 HTTP 200 判断插件测试成功。\n- 每次调用都会记录到账户审计日志。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **集成中心管理**（`on-call`） |\n\n## 使用说明\n\n- `plugin_type` 必须是 `POST /integration/type/list` 中 `supports_api_create: true` 的类型，否则返回 `InvalidParameter`。\n- `status` 为 `disabled` 的类型返回 `InvalidParameter`；当前套餐不包含的类型返回 `NoLicense`。\n- 这些接口仅管理公共（账户级）集成，不管理协作空间专属集成。\n- 不传 `integration_key` 时自动生成；传入时须满足长度、账户后缀与唯一性校验。\n- 传 `is_test: true` 时请检查 `test.success`，不能只根据 HTTP 200 判断插件测试成功。\n- 每次调用都会记录到账户审计日志。",
           "href": "/zh/api-reference/on-call/integrations/integration-api-write-create",
           "metadata": {
             "sidebarTitle": "创建集成"
@@ -489,6 +501,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -528,7 +543,7 @@
           "On-call/集成中心"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **集成中心管理**（`on-call`） |\n\n## 使用说明\n\n- 仅发送的字段会被修改，未发送的字段保持原值。\n- 提交 `settings` 会替换配置；已识别的敏感字段不传或传 `******` 时保留原值。保留已存密钥的同时修改它的发送目标（如 `endpoint`、`url`、数据库主机或端口、IM 接口地址）会被拒绝，需要随新目标重新填写密钥；没有已存值的字段传 `******` 也会被拒绝。清空 Headers 请传 `headers: {}`；清空 Body 请使用该集成类型的显式空值。\n- 同时提交 `settings` 与 `is_test: true` 可获得插件测试结果，返回的 settings 中密钥同样返回 `******`。\n- 这些接口仅管理公共（账户级）集成，不管理协作空间专属集成。\n- 写操作还需对象权限：主体账户、管理员、创建者或所属团队成员可操作；未设置团队时，拥有集成中心管理权限的成员可操作，只读集成不可修改。\n- 每次调用都会记录到账户审计日志。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **集成中心管理**（`on-call`） |\n\n## 使用说明\n\n- 仅发送的字段会被修改，未发送的字段保持原值。\n- 提交 `settings` 会替换配置；已识别的敏感字段不传或传 `******` 时保留原值。保留已存密钥的同时修改它的发送目标（如 `endpoint`、`url`、数据库主机或端口、IM 接口地址）会被拒绝，需要随新目标重新填写密钥；没有已存值的字段传 `******` 也会被拒绝。清空 Headers 请传 `headers: {}`；清空 Body 请使用该集成类型的显式空值。\n- 同时提交 `settings` 与 `is_test: true` 可获得插件测试结果，返回的 settings 中密钥同样返回 `******`。\n- 处理期间若有其他请求修改了同一集成的配置，本次调用返回 `RequestLocked`，重试即可。当前套餐已不包含该集成类型时返回 `NoLicense`。\n- 这些接口仅管理公共（账户级）集成，不管理协作空间专属集成。\n- 写操作还需对象权限：主体账户、管理员、创建者或所属团队成员可操作；未设置团队时，拥有集成中心管理权限的成员可操作，只读集成不可修改。\n- 每次调用都会记录到账户审计日志。",
           "href": "/zh/api-reference/on-call/integrations/integration-api-write-update",
           "metadata": {
             "sidebarTitle": "更新集成"
@@ -594,6 +609,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -671,6 +689,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -702,7 +723,7 @@
           "On-call/集成中心"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **集成中心管理**（`on-call`） |\n\n## 使用说明\n\n- 启用会恢复该集成的拉取任务与心跳，并要求当前套餐包含该集成类型。\n- 每次调用都会记录到账户审计日志。\n- 这些接口仅管理公共（账户级）集成，不管理协作空间专属集成。\n- 写操作还需对象权限：主体账户、管理员、创建者或所属团队成员可操作；未设置团队时，拥有集成中心管理权限的成员可操作，只读集成不可修改。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **集成中心管理**（`on-call`） |\n\n## 使用说明\n\n- 启用会恢复该集成的拉取任务与心跳，并要求当前套餐包含该集成类型。\n- 对已启用的集成调用启用、或对已禁用的集成调用禁用，会直接成功且不做变更。\n- 每次调用都会记录到账户审计日志。\n- 这些接口仅管理公共（账户级）集成，不管理协作空间专属集成。\n- 写操作还需对象权限：主体账户、管理员、创建者或所属团队成员可操作；未设置团队时，拥有集成中心管理权限的成员可操作，只读集成不可修改。",
           "href": "/zh/api-reference/on-call/integrations/integration-api-write-enable",
           "metadata": {
             "sidebarTitle": "启用集成"
@@ -741,6 +762,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -772,7 +796,7 @@
           "On-call/集成中心"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **集成中心管理**（`on-call`） |\n\n## 使用说明\n\n- 禁用后停止接收事件并暂停定时拉取任务，配置保留，可再次启用。\n- 每次调用都会记录到账户审计日志。\n- 这些接口仅管理公共（账户级）集成，不管理协作空间专属集成。\n- 写操作还需对象权限：主体账户、管理员、创建者或所属团队成员可操作；未设置团队时，拥有集成中心管理权限的成员可操作，只读集成不可修改。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **集成中心管理**（`on-call`） |\n\n## 使用说明\n\n- 禁用后停止接收事件并暂停定时拉取任务，配置保留，可再次启用。\n- 对已启用的集成调用启用、或对已禁用的集成调用禁用，会直接成功且不做变更。\n- 每次调用都会记录到账户审计日志。\n- 这些接口仅管理公共（账户级）集成，不管理协作空间专属集成。\n- 写操作还需对象权限：主体账户、管理员、创建者或所属团队成员可操作；未设置团队时，拥有集成中心管理权限的成员可操作，只读集成不可修改。",
           "href": "/zh/api-reference/on-call/integrations/integration-api-write-disable",
           "metadata": {
             "sidebarTitle": "禁用集成"
@@ -811,6 +835,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -883,6 +910,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -914,7 +944,7 @@
           "On-call/标签增强"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **映射数据管理**（`on-call`） |\n\n## 使用说明\n\n- 此操作不可逆，将删除映射规则中的所有数据。\n- 本接口为高危操作。控制台 JWT 调用需二次验证码；`app_key` 调用跳过 MFA 但仍会被完整记录，请妥善保管 app_key。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **映射数据管理**（`on-call`） |\n\n## 使用说明\n\n- 永久删除该映射规则下的全部数据行，映射规则本身保留。\n- 映射规则必须存在且未被删除，否则返回 `InvalidParameter`。\n- 仅账户管理员、映射规则创建者或映射规则所属团队的成员可以调用，其他人返回 `AccessDenied`。\n- 同一映射规则的数据写操作（写入、删除、清空、CSV 上传）串行执行；另一个写操作进行中时调用会返回 `RequestTooFrequently`。",
           "href": "/zh/api-reference/on-call/alert-enrichment/mapping-data-write-truncate",
           "metadata": {
             "sidebarTitle": "清空映射数据"
@@ -953,6 +983,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -984,7 +1017,7 @@
           "On-call/标签增强"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 映射 API 不存在时返回 `null`。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 账户内不存在该 ID 的映射 API 时返回 `data: null`。\n- 已软删除的映射 API 仍会返回，此时 `status` 为 `deleted`。\n- 不做团队校验：账户内任何调用方都能读取任意映射 API，包括明文的 `headers`。",
           "href": "/zh/api-reference/on-call/alert-enrichment/mapping-api-read-info",
           "metadata": {
             "sidebarTitle": "查看映射 API 详情"
@@ -1015,12 +1048,18 @@
                   "data": {
                     "api_id": "665f1a2b3c4d5e6f7a8b9c02",
                     "api_name": "CMDB API",
+                    "description": "Query CMDB for host metadata",
                     "url": "https://cmdb.example.com/api/lookup",
+                    "headers": {
+                      "X-Token": "example-token"
+                    },
                     "timeout": 2,
                     "retry_count": 1,
                     "insecure_skip_verify": false,
                     "status": "enabled",
+                    "team_id": 0,
                     "creator_id": 80011,
+                    "updated_by": 80011,
                     "created_at": 1710000000,
                     "updated_at": 1710000000
                   }
@@ -1034,6 +1073,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -1065,7 +1107,7 @@
           "On-call/状态页"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 轮询直到 `status` 不再是 `running`；`progress.completed_steps` 与 `progress.total_steps` 之比表示任务进度。\n- 任务状态在最后一次更新后保留 24 小时，过期后调用返回 `ResourceNotFound`。\n- `job_id` 属于其他账户时返回 `AccessDenied`。",
           "href": "/zh/api-reference/on-call/status-pages/status-page-migration-status",
           "metadata": {
             "sidebarTitle": "获取迁移状态"
@@ -1124,6 +1166,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -1148,12 +1193,12 @@
       "post": {
         "operationId": "channelEscalateRuleInfo",
         "summary": "获取分派策略详情",
-        "description": "获取指定分派策略的详细信息。",
+        "description": "返回协作空间下的单条分派策略，包括环节、时间窗口和过滤条件。",
         "tags": [
           "On-call/协作空间"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间查看**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间查看**（`on-call`） 或 **协作空间管理**（`on-call`） 或 **故障查看**（`on-call`） 或 **故障管理**（`on-call`） |\n\n## 使用说明\n\n- 已删除的策略仍会返回，`status` 为 `deleted`。\n- `channel_id` 或 `rule_id` 不存在时返回 `InvalidParameter`。",
           "href": "/zh/api-reference/on-call/channels/channel-escalate-rule-info",
           "metadata": {
             "sidebarTitle": "获取分派策略详情"
@@ -1224,6 +1269,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -1256,7 +1304,7 @@
           "On-call/标签增强"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **集成中心查看**（`on-call`） 或 **集成中心管理**（`on-call`） 或 **映射数据查看**（`on-call`） 或 **映射数据管理**（`on-call`） |\n\n## 使用说明\n\n- 若提供 `query`，须包含全部来源标签——不支持部分来源标签查询。\n- 支持游标分页（`search_after_ctx`）或页码分页（`p`、`limit`）。`limit` 默认 20，最大 100。\n- 响应中的 `search_after_ctx` 可用于获取下一页。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **集成中心查看**（`on-call`） 或 **集成中心管理**（`on-call`） 或 **映射数据查看**（`on-call`） 或 **映射数据管理**（`on-call`） |\n\n## 使用说明\n\n- 映射规则必须存在且未被删除，否则返回 `InvalidParameter`。\n- `query` 按来源标签值精确过滤。不属于来源标签的键会被丢弃；只要还剩下键，就必须给出全部来源标签，否则返回 `InvalidParameter`。\n- 页码分页（`p`、`limit`）最多取到第 10,000 行（`p * limit <= 10000`），更靠后的数据请用 `search_after_ctx` 游标翻页。\n- `total` 最多统计 1,000 条匹配行；`used_cnt` 是该映射规则的实际总行数。",
           "href": "/zh/api-reference/on-call/alert-enrichment/mapping-data-read-list",
           "metadata": {
             "sidebarTitle": "查询映射数据列表"
@@ -1287,7 +1335,7 @@
                   "data": {
                     "items": [
                       {
-                        "key": "server01",
+                        "key": "02b8754747905747f7f76d802202d214",
                         "fields": {
                           "host": "server01",
                           "owner": "alice",
@@ -1299,7 +1347,8 @@
                       }
                     ],
                     "total": 1,
-                    "has_next_page": false
+                    "has_next_page": false,
+                    "used_cnt": 1
                   }
                 }
               }
@@ -1311,6 +1360,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -1341,12 +1393,12 @@
       "post": {
         "operationId": "incidentPastList",
         "summary": "查询历史相似故障",
-        "description": "查询与当前故障相关的历史故障列表，用于参考排查。",
+        "description": "查询与指定故障相似、同一协作空间内已关闭的历史故障，便于复用过往的根因和解决方案。",
         "tags": [
           "On-call/故障管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **100 次/分钟**；**20 次/秒** |\n| 权限要求 | **故障查看**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **100 次/分钟**；**5 次/秒** |\n| 权限要求 | **故障查看**或**故障管理**或**协作空间查看**或**协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 需要专业版及以上版本，否则返回 `NoLicense`。\n- 候选范围：同一协作空间内、开始时间在参考故障开始前 30 天内、语义相似度超过该协作空间相似度阈值的已关闭故障。\n- 排序规则：`root_cause` 与 `resolution` 文本越长越靠前；相同时 `score` 越高越靠前；再相同时 `start_time` 越新越靠前。\n- `limit` 不传或为 `0` 时默认返回 5 条。\n- `items` 为空数组表示没有找到相似故障，或参考故障尚未建立相似度索引。\n- 参考故障必须属于某个协作空间，否则返回 `InvalidParameter`。",
           "href": "/zh/api-reference/on-call/incidents/incident-past-list",
           "metadata": {
             "sidebarTitle": "查询历史相似故障"
@@ -1387,6 +1439,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -1414,12 +1469,12 @@
       "post": {
         "operationId": "incidentSnooze",
         "summary": "暂停故障通知",
-        "description": "暂时屏蔽故障通知直到指定时间。",
+        "description": "在指定分钟数内暂停已认领故障的通知。",
         "tags": [
           "On-call/故障管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **故障管理**或**协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 只有处理进度为 `Processing` 的故障可以暂停；任一故障处于其他进度时整个请求返回 `InvalidParameter`。\n- 经过 `minutes` 分钟后自动恢复通知，也可以提前调用 `POST /incident/wake` 恢复。暂停结束时间记录在故障的 `snoozed_before` 字段（Unix 秒）。\n- 故障被重新分派或回到 `Triggered` 时，暂停也会被清除。",
           "href": "/zh/api-reference/on-call/incidents/incident-snooze",
           "metadata": {
             "sidebarTitle": "暂停故障通知"
@@ -1458,6 +1513,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -1487,12 +1545,12 @@
       "post": {
         "operationId": "statusPageSubscriberExport",
         "summary": "导出订阅者",
-        "description": "以 CSV 附件形式导出状态页的订阅者列表。响应为 `text/csv` 文件，包含列：Method、Recipient、Components、Subscribe All、Locale。",
+        "description": "以 CSV 文件导出状态页的订阅者。",
         "tags": [
           "On-call/状态页"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **100 次/天**；**20 次/分钟**；**10 次/秒** |\n| 权限要求 | **状态页面管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **100 次/天**；**20 次/分钟**；**10 次/秒** |\n| 权限要求 | **状态页面管理**（`on-call`） |\n\n## 使用说明\n\n- 需要 On-call 标准版及以上套餐，否则返回 `AccessDenied`。\n- 响应为 `text/csv` 附件而非 JSON 信封，列依次为 Method、Recipient、Components、Subscribe All（`Yes`/`No`）、Locale。\n- Components 列为以 `, ` 连接的组件名；位于分组内的组件写作 `分组名 › 组件名`。\n- 公开页导出邮件订阅者，内部页导出 IM 订阅者；按 `component_ids` 过滤时也会包含订阅了全部组件的订阅者。",
           "href": "/zh/api-reference/on-call/status-pages/status-page-subscriber-export",
           "metadata": {
             "sidebarTitle": "导出订阅者"
@@ -1516,6 +1574,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -1542,12 +1603,12 @@
       "post": {
         "operationId": "insightByTeam",
         "summary": "查看团队洞察",
-        "description": "返回按团队聚合的洞察指标。",
+        "description": "按团队分组返回故障与告警指标，每个团队、每个时间桶一行。",
         "tags": [
           "On-call/分析看板"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **分析看板查看**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **分析看板查看**（`on-call`） |\n\n## 使用说明\n\n- 每个团队、每个时间桶返回一行。未归属团队的故障汇总为一行，该行没有 `team_id`。`responder_ids` 和 `incident_ids` 不生效。\n- 故障按创建时间归入时间桶。结果按 `ts` 从新到旧排列；没有故障的时间桶（或维度取值）不会出现在结果中，缺行即为 0。`split_hours` 为 true 时，每个时间桶最多返回 3 行，每个 `hours` 取值一行。\n- `total_alert_cnt`、`total_alert_event_cnt` 和 `noise_reduction_pct` 只受时间范围、团队、协作空间和严重程度过滤影响；`query`、`labels`、`fields` 以及时长过滤只作用于故障指标。\n- 非账户所有者、非管理员的成员只能看到自己有权访问的协作空间的数据，其他协作空间会被静默排除。\n- `is_my_team` 为 true 时，`team_ids` 收窄为调用者所在的团队；调用者不属于任何团队时返回空结果。",
           "href": "/zh/api-reference/on-call/analytics/insight-by-team",
           "metadata": {
             "sidebarTitle": "查看团队洞察"
@@ -1615,6 +1676,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -1646,12 +1710,12 @@
       "post": {
         "operationId": "insightChannelExport",
         "summary": "导出协作空间洞察",
-        "description": "将协作空间维度洞察指标导出为 CSV 文件——每行一个协作空间（使用 `aggregate_unit`/`split_hours` 时按时间桶/小时桶拆分）。响应为 CSV 字节流（`Content-Disposition: attachment`），不是 JSON 响应包。`time_zone` 缺省为 UTC。无有效协作空间 ID 的行会被跳过。可用的 `export_fields` key：channel_id, channel_name, total_incident_cnt, total_incidents_acknowledged, total_incidents_closed, total_incidents_auto_closed, total_incidents_manually_closed, total_incidents_timeout_closed, total_incidents_escalated, total_incidents_manually_escalated, total_incidents_timeout_escalated, total_incidents_reassigned, total_interruptions, total_notifications, total_engaged_seconds, mean_seconds_to_ack, mean_seconds_to_close, noise_reduction_pct, acknowledgement_pct, total_alert_cnt, total_alert_event_cnt, hours。`hours` 列仅在 `split_hours` 为 true 时默认包含。为兼容起见，故障导出列的 key 也可传入，但导出为空列。",
+        "description": "将协作空间维度洞察指标导出为 CSV 文件，行与 `/insight/channel` 的返回一致。",
         "tags": [
           "On-call/分析看板"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **100 次/天**；**20 次/分钟**；**10 次/秒** |\n| 权限要求 | **分析看板查看**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **100 次/天**；**20 次/分钟**；**10 次/秒** |\n| 权限要求 | **分析看板查看**（`on-call`） |\n\n## 使用说明\n\n- 响应是 CSV 文件（`Content-Type: application/octet-stream`），不是 JSON 响应包。参数校验失败时，在写出任何 CSV 内容之前返回 JSON 错误。\n- 过滤参数与 `/insight/channel` 相同。没有协作空间 ID 的行的行会被跳过。文件中没有时间桶列，使用 `aggregate_unit` 时不同时间桶的行无法区分；如需按时间拆分，请每个时间桶单独导出一次。\n- `export_fields` 决定导出哪些列及其顺序：channel_id, channel_name, total_incident_cnt, total_incidents_acknowledged, total_incidents_closed, total_incidents_auto_closed, total_incidents_manually_closed, total_incidents_timeout_closed, total_incidents_escalated, total_incidents_manually_escalated, total_incidents_timeout_escalated, total_incidents_reassigned, total_interruptions, total_notifications, total_engaged_seconds, mean_seconds_to_ack, mean_seconds_to_close, noise_reduction_pct, acknowledgement_pct, total_alert_cnt, total_alert_event_cnt, hours。未知或重复的 key 会被拒绝。不传时导出全部列，其中 `hours` 列仅在 `split_hours` 为 true 时包含。\n- 为兼容起见，也接受故障快照类 key（progress, assigned_to, raw_assigned_to, escalate_rule_name, responders, raw_responders, ackers, owner_id, owner_name, creator_id, creator_name, closer_id, closer_name, snooze_status, snoozed_before, ever_muted, frequency, is_rare, alert_cnt, active_alert_cnt, alert_event_cnt, description, labels, fields），这些列导出为空。\n- 列名按语言本地化（依次取请求语言、成员语言、账户语言）。时间桶按 `time_zone` 切分（不传为 UTC）。",
           "href": "/zh/api-reference/on-call/analytics/insight-channel-export",
           "metadata": {
             "sidebarTitle": "导出协作空间洞察"
@@ -1665,7 +1729,7 @@
                 "schema": {
                   "type": "string",
                   "format": "binary",
-                  "description": "CSV 字节流（`Content-Type: application/octet-stream`，`Content-Disposition: attachment; filename=channel_export_yyyyMMdd_HHmmss.csv`）。首行为本地化列名。列默认为完整字段集，或由 `export_fields` 指定。"
+                  "description": "CSV 文件（`Content-Type: application/octet-stream`，`Content-Disposition: attachment; filename*=UTF-8''channel_export_yyyyMMdd_HHmmss.csv`）。第一行为本地化的列名。"
                 },
                 "example": "channel_id,channel_name,total_incident_cnt,total_incidents_closed\n4321322010131,Production Alerts,12,10\n"
               }
@@ -1677,6 +1741,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -1716,7 +1783,7 @@
           "On-call/告警管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **集成中心管理**（`on-call`） |\n\n## 使用说明\n\n- 每条处理规则最多 50 条规则。\n- 每条规则包含 `kind`（`title_reset`、`description_reset`、`severity_reset`、`alert_drop`、`alert_inhibit` 之一）、可选的 `if` 过滤器，以及与 kind 对应的 `settings`。\n- `alert_inhibit` 类型需要 Standard 及以上许可证。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） 或 **集成中心管理**（`on-call`） |\n\n## 使用说明\n\n- 用 `rules` 整体替换该集成的规则列表；传空数组会清空所有规则。最多 50 条。\n- 规则按数组顺序作用于该集成收到的每个事件，在事件生成告警之前执行；`alert_drop` 或命中的 `alert_inhibit` 会丢弃事件并停止后续处理。\n- `integration_id` 可以是账户级集成，也可以是协作空间专属集成；账户中不存在的 ID 返回 `InvalidParameter`。\n- 写操作还需对象权限：主体账户、管理员、集成创建者或其所属团队成员可操作（协作空间专属集成看协作空间所属团队）；未设置团队时，拥有接口权限的调用方均可操作。\n- `alert_inhibit` 规则需要 Standard 及以上套餐，否则返回 `NoLicense`。\n- 成功时响应只包含 `request_id`，不返回 `data` 字段。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/on-call/alerts/alert-write-pipeline-upsert",
           "metadata": {
             "sidebarTitle": "创建或更新告警处理规则"
@@ -1743,8 +1810,7 @@
                   ]
                 },
                 "example": {
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
-                  "data": null
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
             }
@@ -1755,6 +1821,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -1810,7 +1879,7 @@
           "On-call/状态页"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 返回全部受影响组件（包括隐藏组件）；组件名称、分组和排序取自状态页当前配置。\n- 状态页或事件不存在时返回 `ResourceNotFound`。",
           "href": "/zh/api-reference/on-call/status-pages/status-page-change-info",
           "metadata": {
             "sidebarTitle": "获取状态页事件详情"
@@ -1897,6 +1966,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -1932,12 +2004,12 @@
       "post": {
         "operationId": "incidentResolve",
         "summary": "恢复故障",
-        "description": "将故障标记为已恢复。",
+        "description": "关闭一个或多个故障，可同时记录根因、解决方案和关闭表单的填写内容。",
         "tags": [
           "On-call/故障管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障管理**（`on-call`） |\n\n## 使用说明\n\n- 解决表单生效时，`custom_fields`、`summary` 和 `images` 必须符合其中可见元素及必填规则。\n- 批量操作只有在全部选中的故障解析到同一张表单时才接受表单值；否则请逐条解决。\n- 旧字段 `values` 和 `custom_values` 会被拒绝，请使用 `custom_fields`。\n- 已审计 —— 变更会记录到审计日志。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **故障管理**或**协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 关闭表单生效时，`custom_fields`、`summary` 和 `images` 必须符合其中可见元素及必填规则。\n- 批量操作只有在全部选中的故障解析到同一张表单时才接受表单值；否则请逐条关闭。\n- 旧字段 `values` 和 `custom_values` 会被拒绝，请使用 `custom_fields`。\n- 已关闭的故障会被跳过，不报错；存在不认识的故障 ID 时整个请求返回 `InvalidParameter`。\n- 关闭处于 `Triggered` 的故障时，会先以调用者身份自动认领。\n- 关闭后，故障下未完成的行动项会转为后续行动，之后到达的事件也不再合并进该故障已有的告警。\n- 同一账户内有其他关闭、重开、合并、评论或删除操作正在执行时返回 `RequestTooFrequently`，稍后重试即可。",
           "href": "/zh/api-reference/on-call/incidents/incident-resolve",
           "metadata": {
             "sidebarTitle": "恢复故障"
@@ -1976,6 +2048,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -2006,12 +2081,12 @@
       "post": {
         "operationId": "incidentWarRoomList",
         "summary": "查询战情室列表",
-        "description": "查询故障关联的所有战情室。",
+        "description": "查询故障关联的 IM 作战室群组。",
         "tags": [
           "On-call/故障管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障查看**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障查看**或**故障管理**或**协作空间查看**或**协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 所属 IM 集成已禁用或已删除的作战室仍会返回，并将 `integration_unavailable` 置为 `true`。\n- 可将 `chat_id` 和 `integration_id` 传给 `POST /incident/war-room/detail`，读取群组当前名称和加入链接。",
           "href": "/zh/api-reference/on-call/incidents/incident-war-room-list",
           "metadata": {
             "sidebarTitle": "查询战情室列表"
@@ -2040,7 +2115,19 @@
                 "example": {
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
-                    "items": []
+                    "items": [
+                      {
+                        "account_id": 2451002751131,
+                        "integration_id": 2490562293131,
+                        "created_by": 2476444212131,
+                        "chat_id": "oc_a0553eda9014c2de1b3a8f75b4e0c000",
+                        "incident_id": "69da451ef77b1b51f40e83ee",
+                        "status": "enabled",
+                        "created_at": 1775972300,
+                        "plugin_type": "feishu_app",
+                        "chat_name": "Incident #0E83EE war room"
+                      }
+                    ]
                   }
                 }
               }
@@ -2052,6 +2139,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -2083,7 +2173,7 @@
           "On-call/告警管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间查看**（`on-call`） |\n\n## 使用说明\n\n- `start_time` 和 `end_time` 均为必填的 Unix 时间戳（秒），最大跨度 31 天。\n- 使用上次响应中的 `search_after_ctx` 获取下一页。\n- 结果会根据调用方的协作空间数据访问权限进行过滤。\n- 将 `is_active` 设为 `true` 可仅返回活跃（触发中）告警；设为 `false` 返回已恢复告警。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间查看**（`on-call`） 或 **协作空间管理**（`on-call`） 或 **故障查看**（`on-call`） 或 **故障管理**（`on-call`） 或 **集成中心查看**（`on-call`） 或 **集成中心管理**（`on-call`） |\n\n## 使用说明\n\n- `start_time` 和 `end_time` 为必填的 Unix 时间戳（秒），按告警的 `start_time` 过滤，跨度不超过 31 天。\n- `by_updated_at` 为 `true` 时，在 `start_time` 过滤之外再按相同区间过滤 `updated_at`，且跨度不超过 7 天。\n- `start_time` 早于账户数据保留期时会被调整为保留期起点；`end_time` 早于该起点时返回 `InvalidParameter`。\n- 传入上次响应中的 `search_after_ctx` 获取下一页；不传时按 `p`/`limit` 页码分页，且 `p * limit` 不超过 10,000。\n- `total` 最多为 1,000。页码模式下 `has_next_page` 基于这个封顶后的总数计算，读到第 1,000 条后会变为 `false`，即使还有更多匹配的告警。每个非空页都会返回最后一条告警的 `search_after_ctx`；要读取 1,000 条以后的数据，请传回该值改用游标模式，游标模式下 `has_next_page` 是准确的。\n- 结果会根据调用方的协作空间数据访问权限进行过滤。\n- 将 `is_active` 设为 `true` 可仅返回活跃（触发中）告警；设为 `false` 返回已恢复告警。",
           "href": "/zh/api-reference/on-call/alerts/alert-read-list",
           "metadata": {
             "sidebarTitle": "查询告警列表"
@@ -2137,7 +2227,8 @@
                         "channel_name": "Production",
                         "event_cnt": 3
                       }
-                    ]
+                    ],
+                    "search_after_ctx": "663a1b2c3d4e5f6789abcdef"
                   }
                 }
               }
@@ -2149,6 +2240,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -2178,12 +2272,12 @@
       "post": {
         "operationId": "statusPageChangeUpdate",
         "summary": "更新状态页事件",
-        "description": "更新已有状态页事件。",
+        "description": "更新状态页事件的标题、负责人或关联事件。",
         "tags": [
           "On-call/状态页"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **状态页面事件管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **状态页面事件管理**（`on-call`） |\n\n## 使用说明\n\n- 状态、描述和组件影响无法通过本接口修改，请调用 `POST /status-page/change/timeline/create` 发布时间线更新。\n- `responders` 或 `linked_changes` 省略或为空数组时保留原列表，因此无法通过本接口清空。\n- 每次调用都会记录到账户审计日志，请勿在请求字段中写入敏感信息。",
           "href": "/zh/api-reference/on-call/status-pages/status-page-change-update",
           "metadata": {
             "sidebarTitle": "更新状态页事件"
@@ -2222,6 +2316,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -2255,7 +2352,7 @@
           "On-call/故障管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障查看**（`on-call`） |\n\n## 使用说明\n\n- 仅在需要预览每条告警的原始事件时设置 `include_events=true`。\n- 事件预览最多返回每条告警最新的 20 条事件；完整事件历史请使用 `POST /alert/event/list` 分页查询。\n- `event_cnt` 仍表示合并到每条告警的原始事件总数。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障查看**或**故障管理**或**协作空间查看**或**协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 仅在需要预览每条告警的原始事件时设置 `include_events=true`。\n- 事件预览最多返回每条告警最新的 20 条事件；完整事件历史请使用 `POST /alert/event/list` 分页查询。\n- `event_cnt` 仍表示合并到每条告警的原始事件总数。\n- `p` 默认为 1；`limit` 不传或为 `0` 时每页最多返回 1,000 条告警。",
           "href": "/zh/api-reference/on-call/incidents/incident-alert-list",
           "metadata": {
             "sidebarTitle": "查询故障关联告警"
@@ -2351,6 +2448,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -2381,12 +2481,12 @@
       "post": {
         "operationId": "channelEscalateRuleUpdate",
         "summary": "更新分派策略",
-        "description": "更新已有分派策略的配置。",
+        "description": "整体替换已有分派策略的配置。",
         "tags": [
           "On-call/协作空间"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 整体替换：未传的 `description`、`aggr_window`、`time_filters`、`filters` 会被重置为空或 `0`。只有 `priority` 未传时保持原值。\n- 校验规则与创建相同。不会改变策略的 `status`，启停请使用启用、禁用接口。\n- `channel_id` 或 `rule_id` 不存在时返回 `InvalidParameter`。\n- 调用者还必须拥有该协作空间的编辑权：账户所有者或管理员、协作空间创建者，或其管理团队成员（`managing_team_ids` 为空时为所属团队成员），否则返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志。",
           "href": "/zh/api-reference/on-call/channels/channel-escalate-rule-update",
           "metadata": {
             "sidebarTitle": "更新分派策略"
@@ -2425,6 +2525,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -2471,12 +2574,12 @@
       "post": {
         "operationId": "calEventUpsert",
         "summary": "创建或更新日历事件",
-        "description": "创建或更新日历自己的事件（休息日或工作日覆盖），作用于 [start_at, end_at) 这些日期。不传 event_id 时创建新事件；传入的 event_id 必须是该日历已有的事件。写入时会把该日历自己的其他事件从这些日期上移除：完全落在范围内的事件被删除，部分重叠的被截短，跨越整个范围的被拆成两段，因此这些日期以最后一次写入为准。end_at 必须晚于 start_at。",
+        "description": "创建或更新个人日历自有的事件：休息日或工作日覆盖。",
         "tags": [
           "On-call/日历管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **服务日历管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **服务日历管理**（`on-call`） |\n\n## 使用说明\n\n- 事件覆盖 [`start_at`, `end_at`) 这些日期，格式为 `YYYY-MM-DD`；`end_at` 必须晚于 `start_at`。\n- 不传 `event_id` 时创建新事件；传入的 `event_id` 必须是该日历已有的事件。\n- 写入时会把该日历自己的其他事件从这些日期上移除：完全落在范围内的事件被删除，部分重叠的被截短，跨越整个范围的被拆成两段，因此这些日期以最后一次写入为准。\n- 仅个人日历可修改，且仅限主体账户、管理员、日历创建者或日历所属团队成员操作，其他调用方返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志。",
           "href": "/zh/api-reference/on-call/calendars/cal-event-upsert",
           "metadata": {
             "sidebarTitle": "创建或更新日历事件"
@@ -2519,6 +2622,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -2550,12 +2656,12 @@
       "post": {
         "operationId": "statusPageChangeDelete",
         "summary": "删除状态页事件",
-        "description": "删除指定的状态页事件。",
+        "description": "删除状态页上的一个故障或维护事件。",
         "tags": [
           "On-call/状态页"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **状态页面事件管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **状态页面事件管理**（`on-call`） |\n\n## 使用说明\n\n- 删除不存在的事件也返回成功。\n- 订阅该事件的订阅关系会被删除；自动更新的维护事件的定时状态切换会被取消。\n- 每次调用都会记录到账户审计日志，请勿在请求字段中写入敏感信息。",
           "href": "/zh/api-reference/on-call/status-pages/status-page-change-delete",
           "metadata": {
             "sidebarTitle": "删除状态页事件"
@@ -2594,6 +2700,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -2621,12 +2730,12 @@
       "post": {
         "operationId": "incidentWarRoomDetail",
         "summary": "获取战情室详情",
-        "description": "获取故障的战情室配置和成员信息。",
+        "description": "从 IM 平台读取作战室群组当前的名称和加入链接。",
         "tags": [
           "On-call/故障管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障查看**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障查看**或**故障管理**或**协作空间查看**（`on-call`） |\n\n## 使用说明\n\n- 支持飞书、钉钉、企业微信和 Slack IM 集成；其他集成返回 `InvalidParameter`。\n- 如果 IM 平台查询失败（例如群组已在 Flashduty 之外解散），请求仍然成功，所有字段均为空字符串。",
           "href": "/zh/api-reference/on-call/incidents/incident-war-room-detail",
           "metadata": {
             "sidebarTitle": "获取战情室详情"
@@ -2669,6 +2778,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -2696,12 +2808,12 @@
       "post": {
         "operationId": "calendarDelete",
         "summary": "删除服务日历",
-        "description": "删除个人服务日历。当日历被分派或静默策略引用时删除会失败。",
+        "description": "删除个人服务日历及其事件，前提是没有策略引用它。",
         "tags": [
           "On-call/日历管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **服务日历管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **服务日历管理**（`on-call`） |\n\n## 使用说明\n\n- 日历仍被分派策略或静默策略使用时，返回 HTTP 400，`error.code` 为 `ReferenceExist`，`data.refs` 列出引用方。\n- 日历自有的事件会一并删除。\n- 仅个人日历可修改，且仅限主体账户、管理员、日历创建者或日历所属团队成员操作，其他调用方返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志。",
           "href": "/zh/api-reference/on-call/calendars/calendar-delete",
           "metadata": {
             "sidebarTitle": "删除服务日历"
@@ -2740,6 +2852,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -2771,7 +2886,7 @@
           "On-call/告警管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间查看**（`on-call`） |\n\n## 使用说明\n\n- 默认按最新事件优先返回；设置 `asc=true` 可按最早事件优先读取。\n- 使用上次响应中的 `search_after_ctx` 搭配 `limit` 获取下一页。\n- 也支持通过 `p` 使用页码分页，但 `p * limit` 必须在 10,000 条以内。\n- 单条告警可能累积大量原始事件，热点告警建议优先使用游标分页。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间查看**（`on-call`） 或 **协作空间管理**（`on-call`） 或 **故障查看**（`on-call`） 或 **故障管理**（`on-call`） |\n\n## 使用说明\n\n- 默认按最新事件优先返回；设置 `asc=true` 可按最早事件优先读取。\n- 使用上次响应中的 `search_after_ctx` 搭配 `limit` 获取下一页。\n- 也支持通过 `p` 使用页码分页，但 `p * limit` 必须在 10,000 条以内。\n- 账户中不存在的 `alert_id` 返回 `InvalidParameter`。",
           "href": "/zh/api-reference/on-call/alerts/alert-read-event-list",
           "metadata": {
             "sidebarTitle": "查询告警事件列表"
@@ -2827,6 +2942,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -2859,7 +2977,7 @@
           "On-call/故障管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **故障管理**或**协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 源故障的全部告警会移动到目标故障，目标故障同时继承源故障的集成。\n- 仍未关闭的源故障会被关闭。`remove_source_incidents` 为 `true` 时随后永久删除源故障；否则源故障保持关闭，并在时间线写入一条指向目标故障的 `i_merge` 记录。\n- 目标故障的处理进度、处理人和分派不变；传入 `title` 时会替换目标故障标题。\n- 同一账户内有其他关闭、重开、合并、评论或删除操作正在执行时返回 `RequestTooFrequently`，稍后重试即可。",
           "href": "/zh/api-reference/on-call/incidents/incident-merge",
           "metadata": {
             "sidebarTitle": "合并故障"
@@ -2898,6 +3016,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -2934,7 +3055,7 @@
           "On-call/标签增强"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **映射数据管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **映射数据管理**（`on-call`） |\n\n## 使用说明\n\n- `keys` 取自 `/enrichment/mapping/data/list` 或 `/enrichment/mapping/data/upsert` 返回的行 `key`；匹配不到任何行的 key 会被忽略。\n- 映射规则必须存在且未被删除，否则返回 `InvalidParameter`。\n- 仅账户管理员、映射规则创建者或映射规则所属团队的成员可以调用，其他人返回 `AccessDenied`。\n- 同一映射规则的数据写操作（写入、删除、清空、CSV 上传）串行执行；另一个写操作进行中时调用会返回 `RequestTooFrequently`。",
           "href": "/zh/api-reference/on-call/alert-enrichment/mapping-data-write-delete",
           "metadata": {
             "sidebarTitle": "删除映射数据"
@@ -2973,6 +3094,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -3003,12 +3127,12 @@
       "post": {
         "operationId": "incidentPostMortemDelete",
         "summary": "删除复盘报告",
-        "description": "删除指定的复盘报告。",
+        "description": "永久删除故障复盘报告及其上传的媒体文件。",
         "tags": [
           "On-call/故障管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 任意有效 `app_key` 均可调用 |\n\n## 使用说明\n\n- 需要专业版及以上版本，否则返回 `NoLicense`。\n- 调用者必须是账户所有者或管理员，或属于该复盘报告所属团队，否则返回 `AccessDenied`。\n- 关联的故障会解除关联，其 `post_mortem_id` 变为空。\n- `post_mortem_id` 不存在时返回 `ResourceNotFound`。\n- 成功时响应不含 `data` 字段。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/on-call/incidents/incident-post-mortem-delete",
           "metadata": {
             "sidebarTitle": "删除复盘报告"
@@ -3035,8 +3159,7 @@
                   ]
                 },
                 "example": {
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
-                  "data": {}
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
             }
@@ -3047,6 +3170,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -3073,12 +3199,12 @@
       "post": {
         "operationId": "calendarUpdate",
         "summary": "更新服务日历",
-        "description": "更新个人服务日历，仅更新传入的非空字段。",
+        "description": "更新个人服务日历，仅修改传入的字段。",
         "tags": [
           "On-call/日历管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **服务日历管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **服务日历管理**（`on-call`） |\n\n## 使用说明\n\n- 除 `cal_id` 外至少传一个字段，否则返回 `InvalidParameter`。\n- 传入 `workdays` 或 `extra_cal_ids` 会整体替换原列表（空数组即清空）；`team_id: 0` 表示取消团队归属。\n- `cal_name` 在账户内必须唯一。\n- 仅个人日历可修改，且仅限主体账户、管理员、日历创建者或日历所属团队成员操作，其他调用方返回 `AccessDenied`。\n- 成功时响应只包含 `request_id`，不返回 `data` 字段。\n- 每次调用都会记录到账户审计日志。",
           "href": "/zh/api-reference/on-call/calendars/calendar-update",
           "metadata": {
             "sidebarTitle": "更新服务日历"
@@ -3105,8 +3231,7 @@
                   ]
                 },
                 "example": {
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
-                  "data": {}
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
             }
@@ -3117,6 +3242,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -3152,12 +3280,12 @@
       "post": {
         "operationId": "incidentWarRoomDelete",
         "summary": "删除战情室",
-        "description": "删除指定的故障战情室。",
+        "description": "在 IM 平台解散故障的作战室群组，并解除与故障的关联。",
         "tags": [
           "On-call/故障管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **故障管理**或**协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 先删除作战室记录；IM 侧解散群组失败（例如群组已被解散）会被忽略。\n- 故障在该集成上没有作战室时直接返回成功，不做任何变更。\n- 如果只想解除关联（适用于 IM 集成已禁用或已删除的情况），设置 `unlink_only: true` 并传入该作战室的 `chat_id`。此模式仅限账户所有者和管理员使用，集成仍处于启用状态时返回 `InvalidParameter`，且不会解散群组。\n- 成功时响应不含 `data` 字段。",
           "href": "/zh/api-reference/on-call/incidents/incident-war-room-delete",
           "metadata": {
             "sidebarTitle": "删除战情室"
@@ -3184,8 +3312,7 @@
                   ]
                 },
                 "example": {
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
-                  "data": {}
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
             }
@@ -3196,6 +3323,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -3223,12 +3353,12 @@
       "post": {
         "operationId": "incidentRemove",
         "summary": "删除故障",
-        "description": "永久删除一个故障及其关联数据。",
+        "description": "永久删除故障及其告警、原始事件和时间线。",
         "tags": [
           "On-call/故障管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **故障管理**或**协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 删除不可恢复。被删除故障的分析统计数据会在后台清除。\n- 任一故障属于调用者无权访问的协作空间时返回 `InvalidParameter`。\n- 不存在的故障 ID 会被忽略。\n- 同一账户内有其他关闭、重开、合并、评论或删除操作正在执行时返回 `RequestTooFrequently`，稍后重试即可。",
           "href": "/zh/api-reference/on-call/incidents/incident-remove",
           "metadata": {
             "sidebarTitle": "删除故障"
@@ -3267,6 +3397,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -3295,12 +3428,12 @@
       "post": {
         "operationId": "channelUnsubscribeRuleEnable",
         "summary": "启用排除规则",
-        "description": "启用已禁用的排除规则。仅 `disabled` 状态的规则可启用。",
+        "description": "启用已禁用的排除规则，使其重新丢弃命中的告警事件。",
         "tags": [
           "On-call/协作空间"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 仅 `disabled` 状态的规则可启用，其他状态返回 `InvalidParameter`。\n- `channel_id` 或 `rule_id` 不存在时返回 `InvalidParameter`。\n- 调用者还必须拥有该协作空间的编辑权：账户所有者或管理员、协作空间创建者，或其管理团队成员（`managing_team_ids` 为空时为所属团队成员），否则返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志。",
           "href": "/zh/api-reference/on-call/channels/channel-unsubscribe-rule-enable",
           "metadata": {
             "sidebarTitle": "启用排除规则"
@@ -3339,6 +3472,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -3371,7 +3507,7 @@
           "On-call/分析看板"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **分析看板查看**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **分析看板查看**（`on-call`） |\n\n## 使用说明\n\n- 默认按故障创建时间从新到旧排序（`asc: true` 为从旧到新）。\n- 可用 `p` + `limit` 翻页（最多可取到第 10,000 条），更深的翻页请把上一页返回的 `search_after_ctx` 传回。传入 `search_after_ctx` 时，`total` 只统计游标之后的故障数。\n- `responder_ids` 保留任一指定成员参与响应的故障。\n- 非账户所有者、非管理员的成员只能看到自己有权访问的协作空间的数据，其他协作空间会被静默排除。\n- `is_my_team` 为 true 时，`team_ids` 收窄为调用者所在的团队；调用者不属于任何团队时返回空结果。",
           "href": "/zh/api-reference/on-call/analytics/insight-incident-list",
           "metadata": {
             "sidebarTitle": "查询洞察故障列表"
@@ -3465,6 +3601,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -3502,7 +3641,7 @@
           "On-call/状态页"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **状态页面事件管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **状态页面事件管理**（`on-call`） |\n\n## 使用说明\n\n- `status` 以及 `updates` 中的组件状态都必须与 `type` 匹配，且每个 `component_id` 都必须是该状态页上已有的组件。\n- `updates` 必须按 `at_seconds` 非递减排列。若 `status` 为 `resolved` 或 `completed`，所有受影响组件的最终状态都必须是 `operational`。\n- `notify_subscribers` 为 `true` 时，仅针对 `updates` 中最后一条更新通知订阅者一次。\n- 维护事件开启 `auto_update_by_schedule` 后，服务端会在 `start_at_seconds` 将其从 `scheduled` 切换为 `ongoing`，在 `close_at_seconds` 从 `ongoing` 切换为 `completed`，并把受影响组件恢复为 `operational`。\n- 传入 `draft_id` 可发布由 `POST /status-page/draft/create` 存储的草稿；草稿必须指向同一状态页和 `type`，且只能发布一次。\n- 每次调用都会记录到账户审计日志，请勿在请求字段中写入敏感信息。",
           "href": "/zh/api-reference/on-call/status-pages/status-page-change-create",
           "metadata": {
             "sidebarTitle": "创建状态页事件"
@@ -3544,6 +3683,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -3593,7 +3735,7 @@
           "On-call/值班排班"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **60 次/分钟**；**10 次/秒** |\n| 权限要求 | **值班查看**（`on-call`） 或 **值班管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **100 次/分钟**；**5 次/秒** |\n| 权限要求 | **值班查看**（`on-call`） 或 **值班管理**（`on-call`） |\n\n## 使用说明\n\n- 不会保存任何数据。请求体字段与 `/schedule/create` 相同，另需必填的 `start`/`end` 窗口。`start` 和 `end` 为 10 位 Unix 秒级时间戳；`end` 必须晚于 `start`，且相差不超过 45 天。\n- 传入 `time_zone` 可按值班表将要使用的时区预览；不传时，墙钟时间按 `Asia/Shanghai` 解读。\n- 只有已保存的值班表才有的字段（`id`、`name`、`group_id`、`disabled`、`status`）按请求原样回显，通常为 `null`。\n- `cur_oncall` 是此刻正在进行的班次，`next_oncall` 是之后第一个有人值班的班次；在当前时刻前后 45 天内找不到时为 `null`，与请求的时间窗口无关。",
           "href": "/zh/api-reference/on-call/schedules/schedule-preview",
           "metadata": {
             "sidebarTitle": "预览值班表"
@@ -3626,6 +3768,7 @@
                     "name": null,
                     "account_id": 0,
                     "group_id": null,
+                    "time_zone": "",
                     "disabled": null,
                     "create_at": 0,
                     "create_by": 0,
@@ -3794,6 +3937,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -3873,7 +4019,7 @@
           "On-call/集成中心"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **集成中心查看**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- `start_time` 和 `end_time` 为 Unix 毫秒时间戳。\n- 每条记录对应一个事件向一个地址的一次推送；`attempt` 为 HTTP 尝试次数，仅在连接错误时重试。\n- 保存的请求与响应 Header 和 Body 会被截断。\n- 传入上次响应中的 `search_after_ctx` 获取下一页；最后一页时它为空字符串。\n- 部署未开启推送历史记录时返回 `InvalidParameter`。",
           "href": "/zh/api-reference/on-call/integrations/webhook-history-list",
           "metadata": {
             "sidebarTitle": "查询 Webhook 推送历史"
@@ -3931,6 +4077,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -3961,12 +4110,12 @@
       "post": {
         "operationId": "incidentWake",
         "summary": "恢复故障通知",
-        "description": "取消故障的暂停状态，恢复通知。",
+        "description": "结束故障的暂停状态，立即恢复通知。",
         "tags": [
           "On-call/故障管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **故障管理**或**协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 暂停已经结束的故障会被跳过；任一故障已关闭时整个请求返回 `InvalidParameter`。",
           "href": "/zh/api-reference/on-call/incidents/incident-wake",
           "metadata": {
             "sidebarTitle": "恢复故障通知"
@@ -4005,6 +4154,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -4033,12 +4185,12 @@
       "post": {
         "operationId": "channelSilenceRuleEnable",
         "summary": "启用静默策略",
-        "description": "启用已禁用的静默策略。仅 `disabled` 状态的策略可启用。",
+        "description": "启用已禁用的静默策略，使其重新静默命中的告警事件。",
         "tags": [
           "On-call/协作空间"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 仅 `disabled` 状态的策略可启用，其他状态返回 `InvalidParameter`。\n- `channel_id` 或 `rule_id` 不存在时返回 `InvalidParameter`。\n- 调用者还必须拥有该协作空间的编辑权：账户所有者或管理员、协作空间创建者，或其管理团队成员（`managing_team_ids` 为空时为所属团队成员），否则返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志。",
           "href": "/zh/api-reference/on-call/channels/channel-silence-rule-enable",
           "metadata": {
             "sidebarTitle": "启用静默策略"
@@ -4077,6 +4229,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -4104,12 +4259,12 @@
       "post": {
         "operationId": "channelSilenceRuleUpdate",
         "summary": "更新静默策略",
-        "description": "更新已有静默策略的配置。",
+        "description": "整体替换已有静默策略的配置。",
         "tags": [
           "On-call/协作空间"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 时间窗口与 `filters` 的要求同创建接口。在 `time_filter` 与 `time_filters` 之间切换时，另一种会被清空。\n- `description`、`is_directly_discard`、`is_auto_delete` 总会被覆盖，未传即重置为空或 `false`。`from_incident_id` 不可修改。\n- `channel_id` 或 `rule_id` 不存在时返回 `InvalidParameter`。\n- 调用者还必须拥有该协作空间的编辑权：账户所有者或管理员、协作空间创建者，或其管理团队成员（`managing_team_ids` 为空时为所属团队成员），否则返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志。",
           "href": "/zh/api-reference/on-call/channels/channel-silence-rule-update",
           "metadata": {
             "sidebarTitle": "更新静默策略"
@@ -4148,6 +4303,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -4191,12 +4349,12 @@
       "post": {
         "operationId": "incidentFeed",
         "summary": "获取故障时间线",
-        "description": "获取指定故障的时间线动态，包括状态变更、评论和系统事件。",
+        "description": "查询故障的时间线条目，包括状态变化、分派、通知、评论和工作项事件等。",
         "tags": [
           "On-call/故障管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障查看**（`on-call`） |\n\n## 使用说明\n\n- 对于 `i_comm` 条目，`detail.comment_type` 在读取时根据当前账户级评论类型定义解析，因此始终反映类型的最新名称和颜色。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障查看**或**故障管理**或**协作空间查看**或**协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 对于 `i_comm` 条目，`detail.comment_type` 在读取时根据当前账户级评论类型定义解析，因此始终反映类型的最新名称和颜色。\n- 只返回记录在故障本身上的条目；告警级别的条目请通过告警相关接口查询。\n- 条目按创建时间排序，默认最新在前，`asc` 为 `true` 时最早在前。通过 `p` 和 `limit` 分页；`has_next_page` 表示是否还有下一页，不返回总数。\n- 对于 `i_notify` 条目，`failed_reason` 是读取时填充的本地化投递失败原因。",
           "href": "/zh/api-reference/on-call/incidents/incident-feed",
           "metadata": {
             "sidebarTitle": "获取故障时间线"
@@ -4291,6 +4449,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -4319,12 +4480,12 @@
       "post": {
         "operationId": "channelInhibitRuleCreate",
         "summary": "创建抑制策略",
-        "description": "创建一条抑制策略，当高优先级告警触发时抑制低优先级告警。",
+        "description": "创建抑制策略，在相关的源告警仍处于活跃状态时屏蔽新的告警事件。",
         "tags": [
           "On-call/协作空间"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 需要 Standard 及以上许可证，否则返回 `NoLicense`。\n- 当新事件命中 `target_filters`，且同一协作空间内存在一条未恢复、`alert_key` 不同、命中 `source_filters`、在该事件前 10 分钟内开始、并且 `equals` 中每个字段取值都相同的告警时，该事件被抑制。\n- `equals` 或 `source_filters` 为空，或新事件缺少 `equals` 中列出的标签时，该策略永远不会生效。\n- 抑制策略在排除和静默策略之后检查，命中第一条即生效。\n- `channel_id` 不存在时返回 `InvalidParameter`。\n- 调用者还必须拥有该协作空间的编辑权：账户所有者或管理员、协作空间创建者，或其管理团队成员（`managing_team_ids` 为空时为所属团队成员），否则返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志。",
           "href": "/zh/api-reference/on-call/channels/channel-inhibit-rule-create",
           "metadata": {
             "sidebarTitle": "创建抑制策略"
@@ -4354,7 +4515,7 @@
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "rule_id": "69db2f69a0fe7db6448b1504",
-                    "rule_name": "Test inhibit rule"
+                    "rule_name": "Suppress Info when Critical fires"
                   }
                 }
               }
@@ -4366,6 +4527,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -4421,12 +4585,12 @@
       "post": {
         "operationId": "channelInhibitRuleEnable",
         "summary": "启用抑制策略",
-        "description": "启用已禁用的抑制策略。仅 `disabled` 状态的策略可启用。",
+        "description": "启用已禁用的抑制策略，使其重新抑制命中的告警事件。",
         "tags": [
           "On-call/协作空间"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 需要 Standard 及以上许可证，否则返回 `NoLicense`。\n- 仅 `disabled` 状态的策略可启用，其他状态返回 `InvalidParameter`。\n- `channel_id` 或 `rule_id` 不存在时返回 `InvalidParameter`。\n- 调用者还必须拥有该协作空间的编辑权：账户所有者或管理员、协作空间创建者，或其管理团队成员（`managing_team_ids` 为空时为所属团队成员），否则返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志。",
           "href": "/zh/api-reference/on-call/channels/channel-inhibit-rule-enable",
           "metadata": {
             "sidebarTitle": "启用抑制策略"
@@ -4465,6 +4629,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -4492,12 +4659,12 @@
       "post": {
         "operationId": "mapping-schema-read-list",
         "summary": "查询映射规则列表",
-        "description": "返回账户下所有映射规则，按创建时间升序排列。",
+        "description": "返回账户下的全部映射规则，按创建时间倒序排列。",
         "tags": [
           "On-call/标签增强"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间查看**（`on-call`） 或 **协作空间管理**（`on-call`） 或 **集成中心查看**（`on-call`） 或 **集成中心管理**（`on-call`） 或 **映射数据查看**（`on-call`） 或 **映射数据管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间查看**（`on-call`） 或 **协作空间管理**（`on-call`） 或 **集成中心查看**（`on-call`） 或 **集成中心管理**（`on-call`） 或 **映射数据查看**（`on-call`） 或 **映射数据管理**（`on-call`） |\n\n## 使用说明\n\n- 一次返回账户下全部未删除的映射规则，不分页；`total` 即条目数。\n- 返回所有团队的映射规则，不按团队过滤。",
           "href": "/zh/api-reference/on-call/alert-enrichment/mapping-schema-read-list",
           "metadata": {
             "sidebarTitle": "查询映射规则列表"
@@ -4543,6 +4710,7 @@
                         "status": "enabled",
                         "team_id": 0,
                         "creator_id": 80011,
+                        "updated_by": 80011,
                         "created_at": 1710000000,
                         "updated_at": 1710000000
                       }
@@ -4558,6 +4726,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -4582,12 +4753,12 @@
       "post": {
         "operationId": "channelUnsubscribeRuleDelete",
         "summary": "删除排除规则",
-        "description": "删除排除规则。仅 `disabled` 状态的规则可删除。",
+        "description": "删除已禁用的排除规则，使其不再出现在协作空间的策略列表中。",
         "tags": [
           "On-call/协作空间"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 仅 `disabled` 状态的规则可删除，其他状态返回 `InvalidParameter`。\n- `channel_id` 或 `rule_id` 不存在时返回 `InvalidParameter`。\n- 调用者还必须拥有该协作空间的编辑权：账户所有者或管理员、协作空间创建者，或其管理团队成员（`managing_team_ids` 为空时为所属团队成员），否则返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志。",
           "href": "/zh/api-reference/on-call/channels/channel-unsubscribe-rule-delete",
           "metadata": {
             "sidebarTitle": "删除排除规则"
@@ -4626,6 +4797,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -4658,7 +4832,7 @@
           "On-call/告警管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **集成中心查看**（`on-call`） |\n\n## 使用说明\n\n- 若该集成尚未配置告警处理规则，则 data 为 `null`。\n- 调用方需有该集成的访问权限。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间查看**（`on-call`） 或 **协作空间管理**（`on-call`） 或 **集成中心查看**（`on-call`） 或 **集成中心管理**（`on-call`） |\n\n## 使用说明\n\n- 该集成未配置告警处理规则时，响应只包含 `request_id`，不返回 `data` 字段。\n- `integration_id` 可以是账户中任意账户级或协作空间专属集成；不存在的 ID 返回 `InvalidParameter`。",
           "href": "/zh/api-reference/on-call/alerts/alert-read-pipeline-info",
           "metadata": {
             "sidebarTitle": "查看告警处理规则"
@@ -4728,6 +4902,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -4754,12 +4931,12 @@
       "post": {
         "operationId": "mapping-schema-write-delete",
         "summary": "删除映射规则",
-        "description": "删除映射规则及其所有关联数据。若该规则被富化规则或 Webhook 引用，则拒绝删除。",
+        "description": "删除映射规则及其全部数据行；仍被富化规则或机器人 Webhook 引用时拒绝删除。",
         "tags": [
           "On-call/标签增强"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **映射数据管理**（`on-call`） |\n\n## 使用说明\n\n- 若映射规则仍被引用，响应返回 HTTP 400，`refs` 字段列出所有阻止删除的引用。\n- 仅映射规则创建者、账户管理员或所属团队成员可删除。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。\n- 本接口为高危操作。控制台 JWT 调用需二次验证码；`app_key` 调用跳过 MFA 但仍会被完整记录，请妥善保管 app_key。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **映射数据管理**（`on-call`） |\n\n## 使用说明\n\n- 映射规则被软删除（`status` 变为 `deleted`），其全部数据行被永久删除。\n- 若有集成的富化规则、或分派策略中的飞书 / 企业微信 / Zoom 机器人 Webhook 引用该映射规则，返回 HTTP 400 `ReferenceExist`，`data.refs` 列出引用方（每项含 `kind`（`integration` 或 `escalate_rule`）、`name`、`href`），集成最多列出 20 个。\n- `schema_id` 不存在时返回 `InvalidParameter`。\n- 仅账户管理员、映射规则创建者或映射规则所属团队的成员可以调用，其他人返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/on-call/alert-enrichment/mapping-schema-write-delete",
           "metadata": {
             "sidebarTitle": "删除映射规则"
@@ -4798,6 +4975,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -4824,12 +5004,12 @@
       "post": {
         "operationId": "insightByAccount",
         "summary": "查看账户级别洞察",
-        "description": "返回整个账户的聚合故障洞察指标。",
+        "description": "按时间桶返回整个账户的故障与告警指标汇总。",
         "tags": [
           "On-call/分析看板"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **分析看板查看**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **分析看板查看**（`on-call`） |\n\n## 使用说明\n\n- 每个时间桶返回一行整个账户的汇总。`responder_ids` 和 `incident_ids` 不生效；如需按人员或按故障查看，请使用 `/insight/responder` 或 `/insight/incident/list`。\n- 故障按创建时间归入时间桶。结果按 `ts` 从新到旧排列；没有故障的时间桶（或维度取值）不会出现在结果中，缺行即为 0。`split_hours` 为 true 时，每个时间桶最多返回 3 行，每个 `hours` 取值一行。\n- `total_alert_cnt`、`total_alert_event_cnt` 和 `noise_reduction_pct` 只受时间范围、团队、协作空间和严重程度过滤影响；`query`、`labels`、`fields` 以及时长过滤只作用于故障指标。\n- 非账户所有者、非管理员的成员只能看到自己有权访问的协作空间的数据，其他协作空间会被静默排除。\n- `is_my_team` 为 true 时，`team_ids` 收窄为调用者所在的团队；调用者不属于任何团队时返回空结果。",
           "href": "/zh/api-reference/on-call/analytics/insight-by-account",
           "metadata": {
             "sidebarTitle": "查看账户级别洞察"
@@ -4895,6 +5075,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -4927,12 +5110,12 @@
       "post": {
         "operationId": "insightIncidentExport",
         "summary": "导出洞察故障",
-        "description": "将过滤后的故障分析明细导出为 CSV 文件。响应为 CSV 字节流（`Content-Disposition: attachment`），不是 JSON 响应包。CSV 列名和格式化值优先使用请求语言，其次成员语言、账户语言。`time_zone` 缺省时依次回退到账户时区、`Asia/Shanghai`。最多导出 100,000 行。可用的 `export_fields` key：incident_id, title, severity, progress, channel_id, channel_name, team_id, team_name, created_at, alert_cnt, active_alert_cnt, alert_event_cnt, seconds_to_ack, seconds_to_close, closed_by, owner_id, owner_name, creator_id, creator_name, closer_id, closer_name, engaged_seconds, hours, notifications, interruptions, acknowledgements, ackers, assignments, reassignments, escalations, manual_escalations, timeout_escalations, assigned_to, raw_assigned_to, escalate_rule_name, responders, raw_responders, snooze_status, snoozed_before, ever_muted, frequency, is_rare, description, labels, fields。不传 `export_fields` 时导出全部列。",
+        "description": "将分析过滤条件命中的故障导出为 CSV 文件，每条故障一行。",
         "tags": [
           "On-call/分析看板"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **100 次/天**；**20 次/分钟**；**10 次/秒** |\n| 权限要求 | **分析看板查看**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **100 次/天**；**20 次/分钟**；**10 次/秒** |\n| 权限要求 | **分析看板查看**（`on-call`） |\n\n## 使用说明\n\n- 响应是 CSV 文件（`Content-Type: application/octet-stream`），不是 JSON 响应包。参数校验失败时，在写出任何 CSV 内容之前返回 JSON 错误。\n- 过滤条件与排序方式与 `/insight/incident/list` 相同。写出的行数超过 100,000 后停止导出。\n- `start_time` 会被推后到账户数据保留期内最早的日期；整个时间范围都早于该日期时请求会被拒绝。\n- `export_fields` 决定导出哪些列及其顺序：incident_id, title, severity, progress, channel_id, channel_name, team_id, team_name, created_at, alert_cnt, active_alert_cnt, alert_event_cnt, seconds_to_ack, seconds_to_close, closed_by, owner_id, owner_name, creator_id, creator_name, closer_id, closer_name, engaged_seconds, hours, notifications, interruptions, acknowledgements, ackers, assignments, reassignments, escalations, manual_escalations, timeout_escalations, assigned_to, raw_assigned_to, escalate_rule_name, responders, raw_responders, snooze_status, snoozed_before, ever_muted, frequency, is_rare, description, labels, fields。未知或重复的 key 会被拒绝；不传时导出除别名 `owner_id`、`creator_id`、`closer_id`、`snoozed_before`、`is_rare` 以外的全部列。\n- `description_html_to_text` 为 true 时去掉 `description` 列中的 HTML 标记。\n- 列名和格式化值依次使用请求语言、成员语言、账户语言。时间按 `time_zone` 渲染，未传时依次回退到账户时区、`Asia/Shanghai`。",
           "href": "/zh/api-reference/on-call/analytics/insight-incident-export",
           "metadata": {
             "sidebarTitle": "导出洞察故障"
@@ -4946,7 +5129,7 @@
                 "schema": {
                   "type": "string",
                   "format": "binary",
-                  "description": "CSV 字节流（`Content-Type: application/octet-stream`，`Content-Disposition: attachment; filename=incident_export_yyyyMMdd_HHmmss.csv`）。首行为本地化列名。列默认为完整故障字段集，或由 `export_fields` 指定。"
+                  "description": "CSV 文件（`Content-Type: application/octet-stream`，`Content-Disposition: attachment; filename*=UTF-8''incident_export_yyyyMMdd_HHmmss.csv`）。第一行为本地化的列名。"
                 },
                 "example": "incident_id,title,severity,created_at\n6a86b5d6f72de50ae1ce2ffb,CPU usage above 90%,Critical,2026-01-01 10:00:00 +0800 CST\n"
               }
@@ -4958,6 +5141,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -4997,12 +5183,12 @@
       "post": {
         "operationId": "scheduleInfo",
         "summary": "获取值班表详情",
-        "description": "返回值班表的详细信息，并按照指定时间窗口（最多 45 天）返回计算出的值班分层。",
+        "description": "返回单个值班表的配置及分层，并计算指定时间窗口（最长 45 天）内的班次。",
         "tags": [
           "On-call/值班排班"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **值班查看**（`on-call`） 或 **值班管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **值班查看**（`on-call`） 或 **值班管理**（`on-call`） |\n\n## 使用说明\n\n- `start` 和 `end` 为 10 位 Unix 秒级时间戳；`end` 必须晚于 `start`，且相差不超过 45 天。\n- `schedule_layers`（及其别名 `layer_schedules`）是窗口内各个未隐藏分层的班次；`final_schedule` 是所有分层合并后的结果，`group` 为 `null` 的班次表示该时段无人值班。\n- 计算结果中的第一个班次可能早于 `start` 开始：在 `start` 时刻已经开始的班次按真实开始时间返回。\n- `cur_oncall` 是此刻正在进行的班次，`next_oncall` 是之后第一个有人值班的班次；在当前时刻前后 45 天内找不到时为 `null`，与请求的时间窗口无关。\n- `schedule_id` 不存在时返回 `400`。",
           "href": "/zh/api-reference/on-call/schedules/schedule-info",
           "metadata": {
             "sidebarTitle": "获取值班表详情"
@@ -5035,6 +5221,7 @@
                     "name": "test-000001",
                     "account_id": 2451002751131,
                     "group_id": 4291079133131,
+                    "time_zone": "Asia/Shanghai",
                     "disabled": 0,
                     "create_at": 1766110836,
                     "create_by": 2476123212131,
@@ -5292,6 +5479,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -5307,9 +5497,9 @@
                 "$ref": "#/components/schemas/ScheduleInfoRequest"
               },
               "example": {
-                "schedule_id": 2001,
-                "start": 1712000000,
-                "end": 1712086400
+                "schedule_id": 5789640530410,
+                "start": 1776009600,
+                "end": 1776268800
               }
             }
           }
@@ -5320,12 +5510,12 @@
       "post": {
         "operationId": "template-write-update",
         "summary": "更新模板",
-        "description": "更新指定模板。仅写入请求中出现的字段：省略的通道保持当前内容，显式传空字符串表示清空该通道。",
+        "description": "更新通知模板，只写入请求中出现的字段。",
         "tags": [
           "On-call/通知模板"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **模板管理**（`on-call`） |\n\n## 使用说明\n\n- 仅写入请求中出现的字段：省略的通道保持当前内容；想清空某通道，把该字段显式设置为空字符串。\n- 调用者必须对目标模板所属团队拥有数据权限，否则返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **模板管理**（`on-call`） |\n\n## 使用说明\n\n- `template_name` 每次都必填且总会被写入。其他字段不传则保持原值；某个通道传空字符串表示清空，之后该通道的通知使用内置预设内容。\n- 请求中每个非空的通道模板都会用模拟故障试渲染一次，任一通道有语法错误整个请求返回 `InvalidParameter`。`wecom_markdown_v2_enabled` 为 `true` 时，`wecom` 渲染结果不得超过 4,096 字节。\n- `incident_card_hidden_fields` 和 `incident_card_closed_action_apps` 一旦传入，整体替换已存的值。\n- `template_id` 不存在时返回 `InvalidParameter`；新的 `template_name` 不能与其他模板重名。\n- 仅账户管理员、模板创建者或模板所属团队的成员可以调用，其他人返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/on-call/notification-templates/template-write-update",
           "metadata": {
             "sidebarTitle": "更新模板"
@@ -5385,8 +5575,8 @@
                 "template_id": "6605a1b2c3d4e5f6a7b8c9d0",
                 "template_name": "Prod incident default",
                 "description": "Updated description.",
-                "email": "Incident {{ .IncidentName }} on {{ .Severity }}",
-                "sms": "[Flashduty] {{ .IncidentName }} — {{ .Severity }}"
+                "email": "Incident {{.Title}} is {{.IncidentSeverity}}",
+                "sms": "[Flashduty] {{.Title}} - {{.IncidentSeverity}}"
               }
             }
           }
@@ -5397,12 +5587,12 @@
       "post": {
         "operationId": "channelInfos",
         "summary": "批量获取协作空间",
-        "description": "通过 ID 列表批量获取协作空间信息。",
+        "description": "一次返回最多 1,000 个协作空间的 ID、名称和状态。",
         "tags": [
           "On-call/协作空间"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 不存在的 ID 会被忽略；已删除的协作空间也会返回，`status` 为 `deleted`。\n- 结果按协作空间创建顺序排列，而不是 `channel_ids` 的顺序。\n- 私有协作空间不做可见性过滤，同样返回。",
           "href": "/zh/api-reference/on-call/channels/channel-infos",
           "metadata": {
             "sidebarTitle": "批量获取协作空间"
@@ -5449,6 +5639,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -5478,12 +5671,12 @@
       "post": {
         "operationId": "scheduleInfos",
         "summary": "批量获取值班表",
-        "description": "根据 ID 列表批量返回值班表信息。",
+        "description": "按 ID 批量返回值班表的基础配置，不含分层和班次计算结果。",
         "tags": [
           "On-call/值班排班"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **值班查看**（`on-call`） 或 **值班管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **值班查看**（`on-call`） 或 **值班管理**（`on-call`） |\n\n## 使用说明\n\n- 只返回已保存的基础配置：`layers`、`schedule_layers`、`layer_schedules`、`cur_oncall`、`next_oncall` 恒为 `null`，`final_schedule` 为空。需要分层和班次时请使用 `/schedule/info`。\n- 不存在的 ID 会被跳过，不报错；已禁用的值班表也会返回。",
           "href": "/zh/api-reference/on-call/schedules/schedule-infos",
           "metadata": {
             "sidebarTitle": "批量获取值班表"
@@ -5518,6 +5711,7 @@
                         "name": "test-000001",
                         "account_id": 2451002751131,
                         "group_id": 4291079133131,
+                        "time_zone": "Asia/Shanghai",
                         "disabled": 0,
                         "create_at": 1766110836,
                         "create_by": 2476123212131,
@@ -5577,6 +5771,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -5593,9 +5790,8 @@
               },
               "example": {
                 "schedule_ids": [
-                  2001,
-                  2002,
-                  2003
+                  5789640530410,
+                  5432326025106
                 ]
               }
             }
@@ -5612,7 +5808,7 @@
           "On-call/通知模板"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **模板查看**（`on-call`） |\n\n## 使用说明\n\n- 传入 `000000000000000000000001` 作为 `template_id` 可以获取当前账户语种下的系统预置模板。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **模板查看**（`on-call`） 或 **模板管理**（`on-call`） |\n\n## 使用说明\n\n- `template_id` 传 `6321aad26c12104586a88916` 可获取内置预设模板：各通道内容使用账户语言，名称和描述使用调用方语言。\n- `template_id` 不存在时返回 `InvalidParameter`；已软删除的模板仍会返回，此时 `status` 为 `deleted`。",
           "href": "/zh/api-reference/on-call/notification-templates/template-read-info",
           "metadata": {
             "sidebarTitle": "查看模板详情"
@@ -5646,8 +5842,8 @@
                     "template_id": "6605a1b2c3d4e5f6a7b8c9d0",
                     "template_name": "Prod incident default",
                     "description": "Default template for production incidents.",
-                    "email": "Incident {{ .IncidentName }} on {{ .Severity }}",
-                    "sms": "[Flashduty] {{ .IncidentName }} — {{ .Severity }}",
+                    "email": "Incident {{.Title}} is {{.IncidentSeverity}}",
+                    "sms": "[Flashduty] {{.Title}} - {{.IncidentSeverity}}",
                     "voice": "",
                     "dingtalk": "",
                     "wecom": "",
@@ -5660,6 +5856,14 @@
                     "telegram": "",
                     "slack": "",
                     "zoom": "",
+                    "wecom_markdown_v2_enabled": false,
+                    "feishu_app_card_v2_table_enabled": false,
+                    "feishu_app_card_v2_preserve_blank_lines": false,
+                    "feishu_app_war_room_enabled": false,
+                    "dingtalk_app_war_room_enabled": false,
+                    "slack_app_war_room_enabled": false,
+                    "incident_card_closed_action_apps": [],
+                    "incident_card_hidden_fields": {},
                     "status": "enabled",
                     "creator_id": 80011,
                     "updated_by": 80011,
@@ -5676,6 +5880,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -5702,12 +5909,12 @@
       "post": {
         "operationId": "channelEscalateRuleDisable",
         "summary": "禁用分派策略",
-        "description": "禁用分派策略而不删除。仅 `enabled` 状态的策略可禁用。",
+        "description": "禁用分派策略但不删除。",
         "tags": [
           "On-call/协作空间"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 仅 `enabled` 状态的策略可禁用，其他状态返回 `InvalidParameter`。\n- 禁用后的策略不再接收新故障，已通过它分派的故障也不再收到它的通知和升级。\n- `channel_id` 或 `rule_id` 不存在时返回 `InvalidParameter`。\n- 调用者还必须拥有该协作空间的编辑权：账户所有者或管理员、协作空间创建者，或其管理团队成员（`managing_team_ids` 为空时为所属团队成员），否则返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志。",
           "href": "/zh/api-reference/on-call/channels/channel-escalate-rule-disable",
           "metadata": {
             "sidebarTitle": "禁用分派策略"
@@ -5746,6 +5953,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -5773,12 +5983,12 @@
       "post": {
         "operationId": "incidentReset",
         "summary": "更新故障信息",
-        "description": "一次调用更新故障的多个可编辑字段，包括标题、描述、影响范围、根因、恢复方案和严重程度。至少需要提供一个字段。",
+        "description": "在一次调用中更新故障的标题、描述、影响、根因、解决方案或严重程度。",
         "tags": [
           "On-call/故障管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **故障管理**或**协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 至少要传一个字段。未传的字段和空字符串都保持原值，因此本接口无法清空字段。\n- 与当前值相同的字段会被跳过。每个发生变化的字段各写一条时间线记录（`i_r_title`、`i_r_desc`、`i_r_impact`、`i_r_rc`、`i_r_rsltn` 或 `i_r_severity`）。\n- 修改 `title`、`description` 或 `incident_severity` 会把该字段加入 `manual_overrides`，此后合并进来的告警不再覆盖它。\n- 已关闭的故障同样可以更新。",
           "href": "/zh/api-reference/on-call/incidents/incident-reset",
           "metadata": {
             "sidebarTitle": "更新故障信息"
@@ -5817,6 +6027,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -5845,12 +6058,12 @@
       "post": {
         "operationId": "channelDisable",
         "summary": "禁用协作空间",
-        "description": "禁用协作空间以停止故障路由（不删除）；禁用后新事件会被直接丢弃。仅 `enabled` 状态的协作空间可禁用。",
+        "description": "禁用协作空间；禁用期间新进入的告警事件全部丢弃。",
         "tags": [
           "On-call/协作空间"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 仅 `enabled` 状态的协作空间可禁用，其他状态返回 `InvalidParameter`。\n- 策略与集成均保留。告警处理链路最长约一分钟后才感知到新状态。\n- `channel_id` 不存在时返回 `InvalidParameter`。\n- 调用者还必须拥有该协作空间的编辑权：账户所有者或管理员、协作空间创建者，或其管理团队成员（`managing_team_ids` 为空时为所属团队成员），否则返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志。",
           "href": "/zh/api-reference/on-call/channels/channel-disable",
           "metadata": {
             "sidebarTitle": "禁用协作空间"
@@ -5889,6 +6102,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -5920,7 +6136,7 @@
           "On-call/集成中心"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **集成中心查看**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- `event_id` 与 `integration_id` 取自 `POST /webhook/history/list` 返回的记录；`event_id` 以推送日期（`YYYYMMDD`）开头，查询依赖该日期。\n- 未找到记录时 `data` 为空对象。\n- 部署未开启推送历史记录时返回 `InvalidParameter`。",
           "href": "/zh/api-reference/on-call/integrations/webhook-history-detail",
           "metadata": {
             "sidebarTitle": "获取 Webhook 推送详情"
@@ -5978,6 +6194,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -6005,12 +6224,12 @@
       "post": {
         "operationId": "scheduleList",
         "summary": "查询值班表列表",
-        "description": "返回值班表的分页列表。若同时传入 start 与 end（间隔不超过 45 天），响应会包含计算后的排班分层。",
+        "description": "分页查询值班表，支持过滤；同时传入 `start` 和 `end` 时会一并计算班次。",
         "tags": [
           "On-call/值班排班"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 按创建时间从新到旧排序。`query` 对值班表名称或描述做子串匹配。\n- `is_my_team` 为 true 时只保留调用者所在团队的值班表；`is_my_manage` 为 true 时保留调用者所在团队的值班表以及调用者创建的值班表。两者不能同时为 true。`team_ids` 会与上述过滤取交集。\n- 不传 `start`/`end` 时只返回已保存的配置（`layers`、`schedule_layers`、`cur_oncall`、`next_oncall` 为 `null`）。两者都传时计算 `layers`、`schedule_layers`、`final_schedule`、`cur_oncall` 和 `next_oncall`；本接口中 `layer_schedules` 始终为 `null`。\n- `start` 和 `end` 为 10 位 Unix 秒级时间戳；`end` 必须晚于 `start`，且相差不超过 45 天。只传 `end` 不传 `start` 会被拒绝。",
           "href": "/zh/api-reference/on-call/schedules/schedule-list",
           "metadata": {
             "sidebarTitle": "查询值班表列表"
@@ -6045,6 +6264,7 @@
                         "name": "test-000001",
                         "account_id": 2451002751131,
                         "group_id": 4291079133131,
+                        "time_zone": "Asia/Shanghai",
                         "disabled": 0,
                         "create_at": 1766110836,
                         "create_by": 2476123212131,
@@ -6097,6 +6317,7 @@
                         "name": "test-2509300001",
                         "account_id": 2451002751131,
                         "group_id": 2477033058131,
+                        "time_zone": "",
                         "disabled": 0,
                         "create_at": 1759132037,
                         "create_by": 2476123212131,
@@ -6141,6 +6362,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -6170,12 +6394,12 @@
       "post": {
         "operationId": "mapping-schema-write-create",
         "summary": "创建映射规则",
-        "description": "创建新的映射规则，定义查找来源标签和待填充的结果标签。需要 Pro 计划。",
+        "description": "创建映射规则，定义用于查找的来源标签和要填充的结果标签。",
         "tags": [
           "On-call/标签增强"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **映射数据管理**（`on-call`） |\n\n## 使用说明\n\n- 映射规则名称在账户内唯一。\n- `source_labels`（1–3 个）为查找键，`result_labels`（1–10 个）为匹配后写入的标签。\n- 标签名须匹配 `^[a-zA-Z_][a-zA-Z0-9_]*$`，且各列表内不得重复。\n- `source_labels` 与 `result_labels` 不得重叠。\n- 账户最多可创建 20 个映射规则。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **映射数据管理**（`on-call`） |\n\n## 使用说明\n\n- 需要专业版或更高版本的订阅，否则返回 `NoLicense`。\n- `schema_name` 在账户未删除的映射规则中必须唯一。\n- `source_labels`（1–3 个）组成查找键，`result_labels`（1–10 个）在匹配后写入告警。标签名须匹配 `^[a-zA-Z_][a-zA-Z0-9_]*$`，列表内不得重复，两个列表不得重叠。两个列表创建后都不能修改。\n- 每个账户默认最多 20 个未删除的映射规则（部分账户上限更高），超出返回 `InvalidParameter`。\n- 同一账户并发创建会返回 `RequestTooFrequently`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/on-call/alert-enrichment/mapping-schema-write-create",
           "metadata": {
             "sidebarTitle": "创建映射规则"
@@ -6217,6 +6441,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -6257,7 +6484,7 @@
           "On-call/标签增强"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **映射数据管理**（`on-call`） |\n\n## 使用说明\n\n- 仅 API 创建者、账户管理员或所属团队成员可更新。\n- 所有可更新字段均为可选，仅更新提供的字段。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **映射数据管理**（`on-call`） |\n\n## 使用说明\n\n- 不传的字段保持原值。`headers` 一旦传入即整体替换请求头，传 `{}` 可清空全部请求头；`team_id` 传 `0` 表示解除团队关联。\n- 传入的字段按创建时的规则校验（`url` 协议与内网地址检查、请求头规则、`timeout` 1–3、`retry_count` 0–1）；`description` 超过 500 字符会被截断。\n- `api_id` 不存在时返回 `InvalidParameter`；新的 `api_name` 不能与其他映射 API 重名。\n- 仅账户管理员、映射 API 创建者或映射 API 所属团队的成员可以调用，其他人返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/on-call/alert-enrichment/mapping-api-write-update",
           "metadata": {
             "sidebarTitle": "更新映射 API"
@@ -6296,6 +6523,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -6329,7 +6559,7 @@
           "On-call/日历管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 不传 `kind` 时返回个人日历。`region.official.holiday` 返回公共节假日日历，默认按调用方语言区域过滤，`no_locale` 为 `true` 时不过滤；其 `cal_id` 可填入 `extra_cal_ids`。\n- 列表不分页，`total` 等于返回的条目数。",
           "href": "/zh/api-reference/on-call/calendars/calendar-list",
           "metadata": {
             "sidebarTitle": "查询服务日历列表"
@@ -6412,6 +6642,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -6438,12 +6671,12 @@
       "post": {
         "operationId": "incidentResponderAdd",
         "summary": "添加故障处理人员",
-        "description": "向已有故障添加处理人员。",
+        "description": "为未关闭的故障添加处理人，并通知新加入的处理人。",
         "tags": [
           "On-call/故障管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **故障管理**或**协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 已有处理人保持不变，已经是处理人的 ID 会被跳过。如需替换整组处理人，请使用 `POST /incident/assign`。\n- 已关闭的故障返回 `InvalidParameter`。\n- 账户中不存在的成员 ID 会被忽略。\n- 新处理人按 `notify` 设置接收通知；默认按各自的个人通知偏好发送。",
           "href": "/zh/api-reference/on-call/incidents/incident-responder-add",
           "metadata": {
             "sidebarTitle": "添加故障处理人员"
@@ -6482,6 +6715,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -6512,12 +6748,12 @@
       "post": {
         "operationId": "insightTeamExport",
         "summary": "导出团队洞察",
-        "description": "将团队维度洞察指标导出为 CSV 文件——每行一个团队（使用 `aggregate_unit`/`split_hours` 时按时间桶/小时桶拆分）。响应为 CSV 字节流（`Content-Disposition: attachment`），不是 JSON 响应包。`time_zone` 缺省为 UTC。无有效团队 ID 的行会被跳过。可用的 `export_fields` key：team_id, team_name, total_incident_cnt, total_incidents_acknowledged, total_incidents_closed, total_incidents_auto_closed, total_incidents_manually_closed, total_incidents_timeout_closed, total_incidents_escalated, total_incidents_manually_escalated, total_incidents_timeout_escalated, total_incidents_reassigned, total_interruptions, total_notifications, total_engaged_seconds, mean_seconds_to_ack, mean_seconds_to_close, noise_reduction_pct, acknowledgement_pct, total_alert_cnt, total_alert_event_cnt, hours。`hours` 列仅在 `split_hours` 为 true 时默认包含。为兼容起见，故障导出列的 key 也可传入，但导出为空列。",
+        "description": "将团队维度洞察指标导出为 CSV 文件，行与 `/insight/team` 的返回一致。",
         "tags": [
           "On-call/分析看板"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **100 次/天**；**20 次/分钟**；**10 次/秒** |\n| 权限要求 | **分析看板查看**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **100 次/天**；**20 次/分钟**；**10 次/秒** |\n| 权限要求 | **分析看板查看**（`on-call`） |\n\n## 使用说明\n\n- 响应是 CSV 文件（`Content-Type: application/octet-stream`），不是 JSON 响应包。参数校验失败时，在写出任何 CSV 内容之前返回 JSON 错误。\n- 过滤参数与 `/insight/team` 相同。没有团队 ID 的行（未归属团队的故障）的行会被跳过。文件中没有时间桶列，使用 `aggregate_unit` 时不同时间桶的行无法区分；如需按时间拆分，请每个时间桶单独导出一次。\n- `export_fields` 决定导出哪些列及其顺序：team_id, team_name, total_incident_cnt, total_incidents_acknowledged, total_incidents_closed, total_incidents_auto_closed, total_incidents_manually_closed, total_incidents_timeout_closed, total_incidents_escalated, total_incidents_manually_escalated, total_incidents_timeout_escalated, total_incidents_reassigned, total_interruptions, total_notifications, total_engaged_seconds, mean_seconds_to_ack, mean_seconds_to_close, noise_reduction_pct, acknowledgement_pct, total_alert_cnt, total_alert_event_cnt, hours。未知或重复的 key 会被拒绝。不传时导出全部列，其中 `hours` 列仅在 `split_hours` 为 true 时包含。\n- 为兼容起见，也接受故障快照类 key（progress, assigned_to, raw_assigned_to, escalate_rule_name, responders, raw_responders, ackers, owner_id, owner_name, creator_id, creator_name, closer_id, closer_name, snooze_status, snoozed_before, ever_muted, frequency, is_rare, alert_cnt, active_alert_cnt, alert_event_cnt, description, labels, fields），这些列导出为空。\n- 列名按语言本地化（依次取请求语言、成员语言、账户语言）。时间桶按 `time_zone` 切分（不传为 UTC）。",
           "href": "/zh/api-reference/on-call/analytics/insight-team-export",
           "metadata": {
             "sidebarTitle": "导出团队洞察"
@@ -6531,7 +6767,7 @@
                 "schema": {
                   "type": "string",
                   "format": "binary",
-                  "description": "CSV 字节流（`Content-Type: application/octet-stream`，`Content-Disposition: attachment; filename=team_export_yyyyMMdd_HHmmss.csv`）。首行为本地化列名。列默认为完整字段集，或由 `export_fields` 指定。"
+                  "description": "CSV 文件（`Content-Type: application/octet-stream`，`Content-Disposition: attachment; filename*=UTF-8''team_export_yyyyMMdd_HHmmss.csv`）。第一行为本地化的列名。"
                 },
                 "example": "team_id,team_name,total_incident_cnt,total_incidents_closed\n4295771902131,SRE Team,12,10\n"
               }
@@ -6543,6 +6779,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -6577,12 +6816,12 @@
       "post": {
         "operationId": "scheduleDelete",
         "summary": "删除值班表",
-        "description": "根据 ID 删除一个或多个值班表。",
+        "description": "按 ID 删除一个或多个值班表及其分层。",
         "tags": [
           "On-call/值班排班"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **值班管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **值班管理**（`on-call`） |\n\n## 使用说明\n\n- 仍被分派策略引用的值班表不能删除：请求返回 HTTP 400 `ReferenceExist`，不会删除任何值班表，`data.refs` 列出引用它的规则（`kind`、`name`、`href`）。\n- 不存在的 ID 会被忽略。列出的值班表在同一事务中删除。\n- 每次调用都会记录到账户审计日志。",
           "href": "/zh/api-reference/on-call/schedules/schedule-delete",
           "metadata": {
             "sidebarTitle": "删除值班表"
@@ -6621,6 +6860,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -6637,7 +6879,7 @@
               },
               "example": {
                 "schedule_ids": [
-                  2001
+                  5789640530410
                 ]
               }
             }
@@ -6649,12 +6891,12 @@
       "post": {
         "operationId": "statusPageChangeTimelineDelete",
         "summary": "删除事件时间线",
-        "description": "从状态页事件中删除时间线条目。",
+        "description": "从状态页事件中删除一条时间线更新。",
         "tags": [
           "On-call/状态页"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **状态页面事件管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **状态页面事件管理**（`on-call`） |\n\n## 使用说明\n\n- 最新一条时间线更新不能删除，否则返回 `InvalidParameter`。\n- 删除后，事件的状态、描述、结束时间和受影响组件会根据剩余更新重新计算。\n- 事件不存在时返回成功；事件存在但 `update_id` 不存在时返回 `ResourceNotFound`。\n- 每次调用都会记录到账户审计日志，请勿在请求字段中写入敏感信息。",
           "href": "/zh/api-reference/on-call/status-pages/status-page-change-timeline-delete",
           "metadata": {
             "sidebarTitle": "删除事件时间线"
@@ -6693,6 +6935,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -6721,12 +6966,12 @@
       "post": {
         "operationId": "incidentWarRoomCreate",
         "summary": "创建战情室",
-        "description": "为故障协同响应创建战情室频道。",
+        "description": "为故障创建 IM 群聊作为作战室，并邀请成员加入。",
         "tags": [
           "On-call/故障管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **故障管理**或**协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 需要专业版及以上版本，否则返回 `NoLicense`。\n- IM 集成必须处于启用状态并开启作战室功能。支持飞书、钉钉、企业微信（仅自建应用）和 Slack。\n- 每个故障只能有一个作战室。使用相同 `integration_id` 再次调用会返回已有群组（`share_link` 为空）；使用不同的 `integration_id` 返回 `InvalidParameter`。\n- 同一故障并发创建时返回 `RequestTooFrequently`。\n- 创建成功后会写入一条 `i_wr_create` 时间线记录。",
           "href": "/zh/api-reference/on-call/incidents/incident-war-room-create",
           "metadata": {
             "sidebarTitle": "创建战情室"
@@ -6769,6 +7014,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -6797,12 +7045,12 @@
       "post": {
         "operationId": "channelUnsubscribeRuleUpdate",
         "summary": "更新排除规则",
-        "description": "更新已有排除规则的配置。",
+        "description": "整体替换已有排除规则的名称、描述和匹配条件。",
         "tags": [
           "On-call/协作空间"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 整体替换：未传 `description` 会被清空；未传 `filters` 会清除全部条件，规则不再匹配任何事件。\n- `channel_id` 或 `rule_id` 不存在时返回 `InvalidParameter`。\n- 调用者还必须拥有该协作空间的编辑权：账户所有者或管理员、协作空间创建者，或其管理团队成员（`managing_team_ids` 为空时为所属团队成员），否则返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志。",
           "href": "/zh/api-reference/on-call/channels/channel-unsubscribe-rule-update",
           "metadata": {
             "sidebarTitle": "更新排除规则"
@@ -6841,6 +7089,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -6880,12 +7131,12 @@
       "post": {
         "operationId": "routeUpsert",
         "summary": "创建或更新路由规则",
-        "description": "创建或更新集成的路由规则，将告警导向特定协作空间。`cases` 与 `default` 至少需要提供其一。",
+        "description": "创建或整体替换共享集成的路由规则，决定其告警进入哪些协作空间。",
         "tags": [
           "On-call/协作空间"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **集成中心管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **集成中心管理**（`on-call`） |\n\n## 使用说明\n\n- 整体替换：请求中未出现的 `cases`、`sections`、`default` 会被删除。每次调用 `version` 递增，旧版本保留在路由历史中。\n- `cases` 与 `default` 至少提供其一；`channel_ids` 为空的 `default` 视为未提供。\n- 只有共享集成才有路由规则：`integration_id` 为协作空间专属集成或不存在，或任一协作空间 ID 不存在时，返回 `InvalidParameter`。\n- 集成归属某个团队时，调用者必须是账户所有者或管理员、集成创建者或该团队成员，否则返回 `AccessDenied`。\n- 成功响应只包含 `request_id`，没有 `data` 字段。\n- 每次调用都会记录到账户审计日志。",
           "href": "/zh/api-reference/on-call/channels/route-upsert",
           "metadata": {
             "sidebarTitle": "创建或更新路由规则"
@@ -6912,8 +7163,7 @@
                   ]
                 },
                 "example": {
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
-                  "data": {}
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
             }
@@ -6924,6 +7174,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -6973,12 +7226,12 @@
       "post": {
         "operationId": "calendarCreate",
         "summary": "创建服务日历",
-        "description": "创建个人服务日历。每个账户默认最多 5 个日历，可通过 Flashcat-Break-Cal-Limit 请求头突破限制。",
+        "description": "创建个人服务日历，并设置每周工作日与关联的节假日日历。",
         "tags": [
           "On-call/日历管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **服务日历管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **服务日历管理**（`on-call`） |\n\n## 使用说明\n\n- 5 个日历的上限仅在调用方为主体账户时校验：账户已有 5 个日历后，主体账户的创建请求返回 `InvalidParameter`；其他成员发起的调用不受此上限限制。\n- `cal_name` 在账户内必须唯一，`timezone` 必须是合法的 IANA 时区，非零 `team_id` 必须是账户中的团队，否则返回 `InvalidParameter`。\n- 每次调用都会记录到账户审计日志。",
           "href": "/zh/api-reference/on-call/calendars/calendar-create",
           "metadata": {
             "sidebarTitle": "创建服务日历"
@@ -7020,6 +7273,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -7060,7 +7316,7 @@
           "On-call/故障管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障管理**（`on-call`） |\n\n## 使用说明\n\n- 认领表单生效时，`custom_fields`、`summary` 和 `images` 必须符合其中可见元素及必填规则。\n- 批量操作只有在全部选中的故障解析到同一张表单时才接受表单值；否则请逐条认领。\n- 旧字段 `values` 和 `custom_values` 会被拒绝，请使用 `custom_fields`。\n- 已审计 —— 变更会记录到审计日志。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **故障管理**或**协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 认领表单生效时，`custom_fields`、`summary` 和 `images` 必须符合其中可见元素及必填规则。\n- 批量操作只有在全部选中的故障解析到同一张表单时才接受表单值；否则请逐条认领。\n- 旧字段 `values` 和 `custom_values` 会被拒绝，请使用 `custom_fields`。\n- 调用成员若还不是处理人会被加入处理人，故障进入 `Processing`。重复认领自己已认领的故障不会产生变化。\n- 任一故障已关闭或 ID 不存在时整个请求返回 `InvalidParameter`。",
           "href": "/zh/api-reference/on-call/incidents/incident-ack",
           "metadata": {
             "sidebarTitle": "认领故障"
@@ -7099,6 +7355,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -7127,12 +7386,12 @@
       "post": {
         "operationId": "channelEscalateRuleList",
         "summary": "查询分派策略列表",
-        "description": "查询协作空间下的所有分派策略。",
+        "description": "按匹配顺序列出协作空间的分派策略。",
         "tags": [
           "On-call/协作空间"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间查看**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间查看**（`on-call`） 或 **协作空间管理**（`on-call`） 或 **故障查看**（`on-call`） 或 **故障管理**（`on-call`） |\n\n## 使用说明\n\n- `channel_id` 不存在时返回 `InvalidParameter`。",
           "href": "/zh/api-reference/on-call/channels/channel-escalate-rule-list",
           "metadata": {
             "sidebarTitle": "查询分派策略列表"
@@ -7207,6 +7466,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -7233,12 +7495,12 @@
       "post": {
         "operationId": "channelCreate",
         "summary": "创建协作空间",
-        "description": "创建一个新的协作空间用于故障管理。",
+        "description": "创建协作空间，可同时创建默认分派策略和协作空间专属集成。",
         "tags": [
           "On-call/协作空间"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- `channel_name` 在账户内必须唯一，重名返回 `InvalidParameter`。\n- `group.method` 为 `p` 需要 Standard 及以上许可证，为 `i` 需要 Pro 许可证。超过当前套餐的协作空间数量上限同样返回 `NoLicense`。\n- 传入 `escalate_rule` 时，会同时创建一条名为 `Default` 的已启用分派策略，只有一个环节，对 `escalate_rule.target` 通知一次。\n- `plugin_ids` 中的每个 ID 会创建一个该类型的协作空间专属集成，集成名称为该类型名称。\n- `is_external_report_enabled` 为 `true` 时，响应中会额外返回 `external_report_token`。\n- 每次调用都会记录到账户审计日志。",
           "href": "/zh/api-reference/on-call/channels/channel-create",
           "metadata": {
             "sidebarTitle": "创建协作空间"
@@ -7268,7 +7530,7 @@
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "channel_id": 6294542005131,
-                    "channel_name": "API Test Channel"
+                    "channel_name": "Production Alerts"
                   }
                 }
               }
@@ -7280,6 +7542,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -7300,6 +7565,11 @@
                 "description": "Handles all production environment alerts",
                 "group": {
                   "method": "p",
+                  "equals": [
+                    [
+                      "labels.service"
+                    ]
+                  ],
                   "time_window": 10,
                   "window_type": "tumbling"
                 },
@@ -7320,7 +7590,7 @@
           "On-call/状态页"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 公开页返回邮件订阅者，内部页返回 IM 订阅者。\n- 按 `component_ids` 过滤时，也会返回订阅了全部组件的订阅者。\n- 每一项合并了同一接收人的全部订阅；对单个事件的订阅不会列出。",
           "href": "/zh/api-reference/on-call/status-pages/status-page-subscriber-list",
           "metadata": {
             "sidebarTitle": "查询状态页订阅者列表"
@@ -7378,6 +7648,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -7437,12 +7710,12 @@
       "post": {
         "operationId": "incidentInfo",
         "summary": "获取故障详情",
-        "description": "获取单个故障的详细信息，包括时间线、关联告警、处理人员和自定义字段。",
+        "description": "按 ID 或短编号查询单个故障，包含处理人、分派、自定义字段和告警数量。",
         "tags": [
           "On-call/故障管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障查看**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障查看**或**故障管理**或**协作空间查看**或**协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- `num` 不唯一，多个故障共用同一编号时返回最新的那个。建议优先使用 `incident_id`。\n- 本接口不填充 `alerts` 和 `account_*` 字段。告警请使用 `POST /incident/alert/list`，时间线请使用 `POST /incident/feed`。\n- `images` 中以 `img_` 开头的图片令牌会被替换为下载地址。\n- 故障不存在时返回 `InvalidParameter`。",
           "href": "/zh/api-reference/on-call/incidents/incident-info",
           "metadata": {
             "sidebarTitle": "获取故障详情"
@@ -7508,6 +7781,7 @@
                     "snoozed_before": 0,
                     "group_method": "n",
                     "ever_muted": false,
+                    "has_unfinished_work_item": false,
                     "labels": {
                       "check": "cpu_usage_high",
                       "resource": "web-server-01",
@@ -7559,6 +7833,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -7590,7 +7867,7 @@
           "On-call/标签增强"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **集成中心查看**（`on-call`） 或 **集成中心管理**（`on-call`） 或 **映射数据查看**（`on-call`） 或 **映射数据管理**（`on-call`） |\n\n## 使用说明\n\n- 映射规则不存在时返回 `null`。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **集成中心查看**（`on-call`） 或 **集成中心管理**（`on-call`） 或 **映射数据查看**（`on-call`） 或 **映射数据管理**（`on-call`） |\n\n## 使用说明\n\n- 账户内不存在该 ID 的映射规则时返回 `data: null`。\n- 已软删除的映射规则仍会返回，此时 `status` 为 `deleted`。",
           "href": "/zh/api-reference/on-call/alert-enrichment/mapping-schema-read-info",
           "metadata": {
             "sidebarTitle": "查看映射规则详情"
@@ -7633,6 +7910,7 @@
                     "status": "enabled",
                     "team_id": 0,
                     "creator_id": 80011,
+                    "updated_by": 80011,
                     "created_at": 1710000000,
                     "updated_at": 1710000000
                   }
@@ -7646,6 +7924,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -7672,12 +7953,12 @@
       "post": {
         "operationId": "statusPageSubscriberImport",
         "summary": "批量导入订阅者",
-        "description": "批量导入状态页订阅者。账户需开通订阅者导入白名单，否则将被拒绝（返回权限不足错误）。",
+        "description": "批量导入状态页订阅者，不发送确认邮件。",
         "tags": [
           "On-call/状态页"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **20 次/分钟**；**2 次/秒** |\n| 权限要求 | **状态页面管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **60 次/分钟**；**3 次/秒** |\n| 权限要求 | **状态页面管理**（`on-call`） |\n\n## 使用说明\n\n- 需要 On-call 专业版套餐，且账户需开通订阅者导入白名单，否则返回 `AccessDenied`。\n- `method` 必须与状态页匹配：公开页且已开启邮件订阅时用 `email`，内部页且已开启 IM 订阅时用 `im`。\n- 每个导入的接收人在该状态页上已有的订阅会被导入内容整体替换。\n- `component_ids` 和 `change_ids` 中的每个 ID 都必须存在于该状态页，任一无效则整个请求失败。\n- 每次调用都会记录到账户审计日志，请勿在请求字段中写入敏感信息。",
           "href": "/zh/api-reference/on-call/status-pages/status-page-subscriber-import",
           "metadata": {
             "sidebarTitle": "批量导入订阅者"
@@ -7716,6 +7997,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -7763,7 +8047,7 @@
           "On-call/告警管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间查看**（`on-call`） |\n\n## 使用说明\n\n- `start_time` 和 `end_time` 均为必填的 Unix 时间戳（秒）。`start_time` 必须小于 `end_time`，跨度不超过 31 天。\n- 结果会根据调用方的协作空间数据访问权限进行过滤。\n- `severities` 为逗号分隔的字符串，如 `\"Critical,Warning\"`。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- `start_time` 和 `end_time` 均为必填的 Unix 时间戳（秒）。`start_time` 必须小于 `end_time`，跨度不超过 31 天。\n- 结果会根据调用方的协作空间数据访问权限进行过滤。\n- `severities` 为逗号分隔的列表，按 `event_severity` 匹配，如 `\"Critical,Warning\"`。取值不做校验，未知值（或 `Ok`）不会匹配任何事件。\n- 传入上次响应中的 `search_after_ctx` 获取下一页；不传时按 `p`/`limit` 页码分页，且 `p * limit` 不超过 10,000。",
           "href": "/zh/api-reference/on-call/alerts/alert-event-read-list",
           "metadata": {
             "sidebarTitle": "查询原始告警事件列表"
@@ -7802,7 +8086,8 @@
                         "event_severity": "Critical",
                         "event_time": 1712650000
                       }
-                    ]
+                    ],
+                    "search_after_ctx": "663a1b2c3d4e5f6789abc001"
                   }
                 }
               }
@@ -7814,6 +8099,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -7843,12 +8131,12 @@
       "post": {
         "operationId": "calEventDelete",
         "summary": "删除日历事件",
-        "description": "按 event_id 删除个人日历的一个事件，或清除该日历自己在 [start_at, end_at) 这些日期上的事件。event_id 与 start_at/end_at 二选一，start_at 和 end_at 须同时传入。清除后这些日期回到关联节假日日历和每周工作日设置的判定。",
+        "description": "按 ID 删除个人日历的一个事件，或清除该日历自有事件在某个日期范围内的部分。",
         "tags": [
           "On-call/日历管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **服务日历管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **服务日历管理**（`on-call`） |\n\n## 使用说明\n\n- 传 `event_id`，或同时传 `start_at` 与 `end_at`（格式 `YYYY-MM-DD`，覆盖 [`start_at`, `end_at`)）；其他组合返回 `InvalidParameter`。\n- 清除后这些日期回到关联节假日日历和每周工作日设置的判定。\n- 仅个人日历可修改，且仅限主体账户、管理员、日历创建者或日历所属团队成员操作，其他调用方返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志。",
           "href": "/zh/api-reference/on-call/calendars/cal-event-delete",
           "metadata": {
             "sidebarTitle": "删除日历事件"
@@ -7887,6 +8175,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -7919,7 +8210,7 @@
           "On-call/告警管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **集成中心查看**（`on-call`） |\n\n## 使用说明\n\n- 所有 `integration_ids` 必须对调用方可访问。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **集成中心查看**（`on-call`） 或 **集成中心管理**（`on-call`） |\n\n## 使用说明\n\n- `integration_ids` 中每个 ID 都必须是账户中的集成；只要有一个不存在，整个请求返回 `InvalidParameter`。\n- `items` 中每个已配置规则的集成对应一项，未配置的集成不出现。",
           "href": "/zh/api-reference/on-call/alerts/alert-read-pipeline-list",
           "metadata": {
             "sidebarTitle": "批量查询告警处理规则"
@@ -7965,11 +8256,11 @@
                             ],
                             "settings": {
                               "equals": [
-                                "service"
+                                "labels.service"
                               ],
                               "source_filters": [
                                 {
-                                  "key": "alert_severity",
+                                  "key": "severity",
                                   "oper": "IN",
                                   "vals": [
                                     "Critical"
@@ -7997,6 +8288,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -8026,12 +8320,12 @@
       "get": {
         "operationId": "incidentPostMortemInfo",
         "summary": "获取复盘报告",
-        "description": "通过 `post_mortem_id` 获取复盘报告。先用 `/incident/post-mortem/list` 列出报告（每行标明所属故障），再用其 id 在此获取完整报告。",
+        "description": "按 ID 查询故障复盘报告的完整内容和自动汇总的基础信息。",
         "tags": [
           "On-call/故障管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障查看**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 任意有效 `app_key` 均可调用 |\n\n## 使用说明\n\n- `post_mortem_id` 可通过 `POST /incident/post-mortem/list` 获取，也可取自故障的 `post_mortem_id` 字段。\n- 私有复盘报告只有账户所有者、管理员和报告所属团队成员可以查看，其他人返回 `AccessDenied`。\n- `post_mortem_id` 不存在时返回 `ResourceNotFound`。",
           "href": "/zh/api-reference/on-call/incidents/incident-post-mortem-info",
           "metadata": {
             "sidebarTitle": "获取复盘报告"
@@ -8076,6 +8370,8 @@
                       "team_id": 2477033058131,
                       "channel_id": 3047621227131,
                       "is_private": false,
+                      "generation": 0,
+                      "revision": 12,
                       "channel_name": "Ops Channel",
                       "created_at_seconds": 1773900354,
                       "updated_at_seconds": 1773909012
@@ -8096,7 +8392,8 @@
                     "content": {
                       "content": "{\"type\":\"doc\",\"content\":[]}"
                     },
-                    "follow_ups": ""
+                    "follow_ups": "",
+                    "has_active_incident": false
                   }
                 }
               }
@@ -8108,6 +8405,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -8123,7 +8423,7 @@
             "schema": {
               "type": "string"
             },
-            "description": "故障复盘 ID。由账户 ID 与关联故障 ID 集合推导出的确定性哈希值。"
+            "description": "复盘报告 ID：由账户 ID 和关联故障 ID 计算出的 32 位十六进制字符串。"
           }
         ]
       }
@@ -8132,12 +8432,12 @@
       "post": {
         "operationId": "calEventList",
         "summary": "查询日历事件列表",
-        "description": "返回个人日历在指定年/月/日范围内的事件列表。未同时传入 month 和 day 时返回整年数据。响应中的 days 给出范围内每一天的判定结果。",
+        "description": "返回个人日历在指定年、月或日内的事件，以及每一天的判定结果。",
         "tags": [
           "On-call/日历管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- `year` 默认为当前年份；不传 `month` 时返回整年，传 `day` 时必须同时传 `month`。\n- `items` 合并了日历自有事件（ID 为 `cale.*`）、设置了 `workdays` 时按非工作日逐日生成的 `non_work.YYYYMMDD` 条目，以及关联节假日日历的事件；`total` 统计全部条目。\n- `days` 给出范围内每一天的判定结果。\n- 仅支持个人日历（`cal_id` 以 `cal.` 开头），其他 ID 返回 `InvalidParameter`。",
           "href": "/zh/api-reference/on-call/calendars/cal-event-list",
           "metadata": {
             "sidebarTitle": "查询日历事件列表"
@@ -8226,6 +8526,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -8259,7 +8562,7 @@
           "On-call/状态页"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **状态页面事件管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **状态页面事件管理**（`on-call`） |\n\n## 使用说明\n\n- `at_seconds` 不能早于事件最新一条时间线更新的时间。\n- 与组件当前状态相同的组件变更会被丢弃，不写入该条更新。\n- 切换为 `resolved` 或 `completed` 时，所有受影响组件都必须为 `operational`；对已结束的事件发布非终态状态会重新打开该事件。\n- 事件描述会被更新为本条更新的描述。若事件开启了 `notify_subscribers`，会就本条更新通知订阅者。\n- 手动将自动更新的维护事件切换为 `ongoing` 或 `completed`，会取消对应的定时切换。\n- 传入 `draft_id` 可发布 `change_id` 指向本事件的草稿；草稿只能发布一次。\n- 每次调用都会记录到账户审计日志，请勿在请求字段中写入敏感信息。",
           "href": "/zh/api-reference/on-call/status-pages/status-page-change-timeline-create",
           "metadata": {
             "sidebarTitle": "创建事件时间线"
@@ -8300,6 +8603,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -8336,12 +8642,12 @@
       "post": {
         "operationId": "incidentDisableMerge",
         "summary": "禁止故障合并",
-        "description": "禁用指定故障的自动合并功能。",
+        "description": "停止将新的告警和事件合并进指定故障。",
         "tags": [
           "On-call/故障管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 任意有效 `app_key` 均可调用 |\n\n## 使用说明\n\n- 之后到达的事件不再合并进这些故障已有的告警，告警聚合也不再把新告警加入这些故障。\n- 不存在的故障 ID 会被忽略。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/on-call/incidents/incident-disable-merge",
           "metadata": {
             "sidebarTitle": "禁止故障合并"
@@ -8380,6 +8686,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -8408,12 +8717,12 @@
       "post": {
         "operationId": "statusPageMigrationCancel",
         "summary": "取消状态页迁移",
-        "description": "取消正在进行的状态页迁移任务。只能取消处于 `running` 状态的任务。",
+        "description": "取消正在运行的 Atlassian Statuspage 迁移任务。",
         "tags": [
           "On-call/状态页"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **状态页面管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 只有 `status` 为 `running` 的任务可以取消，否则返回 `InvalidParameter`。\n- 任务会立即标记为 `cancelled`，账户可随即发起新的迁移；已导入的数据会保留。\n- 每次调用都会记录到账户审计日志，请勿在请求字段中写入敏感信息。",
           "href": "/zh/api-reference/on-call/status-pages/status-page-migration-cancel",
           "metadata": {
             "sidebarTitle": "取消状态页迁移"
@@ -8452,6 +8761,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -8478,12 +8790,12 @@
       "post": {
         "operationId": "enrichment-write-upsert",
         "summary": "创建或替换富化规则",
-        "description": "创建或全量替换指定集成的告警富化规则集，`rules` 数组将被原子替换。",
+        "description": "创建或整体替换某个集成的告警富化规则集。",
         "tags": [
           "On-call/标签增强"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） 或 **集成中心管理**（`on-call`） |\n\n## 使用说明\n\n- 富化规则按顺序依次执行。\n- 每条规则有一个 `kind`：`extraction`（正则/gjson 提取）、`composition`（模板组合标签）、`mapping`（通过映射规则或 API 查找）、`drop`（删除标签）。\n- 可选的 `if` 字段为 `AndFilters` 条件，不匹配时跳过该规则。\n- `kind: extraction`：`source_field` 须为 `title`、`description` 或 `labels.*` 前缀的键；`pattern`（RE2 正则，捕获组用空格连接后写入 `result_label`）和 `g_json`（GJson 路径）二选一。\n- `kind: composition`：`template` 为基于事件结构体渲染的 Go text/template，如 `{{.Title}}`、`{{.Description}}`、`{{.Labels.key}}`。\n- `kind: mapping`：`mapping_type` 为 `schema`（默认）或 `api`；分别提供 `schema_id` 或 `api_id`。\n- `kind: drop`：`drop_labels` 列出要删除的标签键名。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） 或 **集成中心管理**（`on-call`） |\n\n## 使用说明\n\n- `rules` 整体替换已存的规则集，传 `[]` 可删除全部规则。\n- 集成必须存在（否则返回 `InvalidParameter`），且调用方须有权编辑该集成：账户管理员、集成创建者、能编辑其所属协作空间的成员（协作空间内的集成），或集成所属团队的成员；既无团队也不属于协作空间的集成任何成员都可编辑。其他人返回 `AccessDenied`。\n- 规则按数组顺序作用于每个进入的告警事件和变更事件，后面的规则能看到前面规则写入的标签。`if` 条件未全部满足的规则会被跳过；运行时失败的规则（正则未匹配、映射未命中、API 调用失败等）同样跳过，不影响事件本身。\n- `if` 中的条件键必须是告警或变更事件的键（如 `title`、`description`、`labels.<name>`），其他键返回 `InvalidParameter`。\n- 保存时不校验 `schema_id`、`api_id` 是否存在；指向不存在或已删除的映射规则 / API 的规则在运行时不生效。`mapping_type` 为 `api` 的 `mapping` 规则只对告警事件生效。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/on-call/alert-enrichment/enrichment-write-upsert",
           "metadata": {
             "sidebarTitle": "创建或替换富化规则"
@@ -8522,6 +8834,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -8567,12 +8882,12 @@
       "post": {
         "operationId": "alert-read-list-by-ids",
         "summary": "批量查询告警",
-        "description": "通过多个告警 ID 一次性返回多条告警详情。 注意：本接口不分页——`total`、`has_next_page` 恒为 `0`/`false`，`search_after_ctx` 不会返回。",
+        "description": "按告警 ID 一次返回多条告警详情，不分页。",
         "tags": [
           "On-call/告警管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间查看**（`on-call`） |\n\n## 使用说明\n\n- 所有 `alert_ids` 必须属于调用方账户，任何无效 ID 都会导致整个请求失败。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间查看**（`on-call`） 或 **协作空间管理**（`on-call`） 或 **故障查看**（`on-call`） 或 **故障管理**（`on-call`） |\n\n## 使用说明\n\n- 格式错误的 ID 会使请求返回 `InvalidParameter`；格式正确但账户中不存在的 ID 不会出现在 `items` 中。\n- 响应不分页：`total` 恒为 `0`，`has_next_page` 恒为 `false`，不返回 `search_after_ctx`。",
           "href": "/zh/api-reference/on-call/alerts/alert-read-list-by-ids",
           "metadata": {
             "sidebarTitle": "批量查询告警"
@@ -8620,6 +8935,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -8648,12 +8966,12 @@
       "post": {
         "operationId": "channelEscalateRuleEnable",
         "summary": "启用分派策略",
-        "description": "启用已禁用的分派策略。仅 `disabled` 状态的策略可启用。",
+        "description": "启用已禁用的分派策略，使其重新参与新故障的分派。",
         "tags": [
           "On-call/协作空间"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 仅 `disabled` 状态的策略可启用，其他状态返回 `InvalidParameter`。\n- `channel_id` 或 `rule_id` 不存在时返回 `InvalidParameter`。\n- 调用者还必须拥有该协作空间的编辑权：账户所有者或管理员、协作空间创建者，或其管理团队成员（`managing_team_ids` 为空时为所属团队成员），否则返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志。",
           "href": "/zh/api-reference/on-call/channels/channel-escalate-rule-enable",
           "metadata": {
             "sidebarTitle": "启用分派策略"
@@ -8692,6 +9010,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -8724,7 +9045,7 @@
           "On-call/故障管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障查看**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障查看**或**故障管理**或**协作空间查看**或**协作空间管理**或**模板查看**或**模板管理**（`on-call`） |\n\n## 使用说明\n\n- 只返回调用者有权访问的协作空间中的故障。\n- `start_time` 和 `end_time` 按故障开始时间过滤，跨度最多 31 天。`start_time` 早于账户数据保留期时会被调整到保留期起点；`end_time` 早于该起点时返回 `InvalidParameter`。\n- 结果按 `start_time` 排序，默认最新在前，`asc` 为 `true` 时最早在前。\n- 可用 `p` 和 `limit` 分页，也可传入上次响应的 `search_after_ctx`，此时忽略 `p`。\n- `total` 最多为 1,000。按 `p`/`limit` 分页时，一旦 `p` × `limit` 达到 1,000，即使还有更多匹配故障 `has_next_page` 也会变为 `false`。如需继续读取，请传入每个非空页都会返回的 `search_after_ctx`；游标模式下 `has_next_page` 如实反映是否还有更多数据。\n- 不传 `progress` 时返回所有处理进度的故障。",
           "href": "/zh/api-reference/on-call/incidents/incident-list",
           "metadata": {
             "sidebarTitle": "查询故障列表"
@@ -8795,6 +9116,7 @@
                         "snoozed_before": 0,
                         "group_method": "n",
                         "ever_muted": false,
+                        "has_unfinished_work_item": false,
                         "labels": {
                           "check": "cpu_usage_high",
                           "resource": "web-server-01",
@@ -8848,6 +9170,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -8887,7 +9212,7 @@
           "On-call/故障管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障查看**（`on-call`） |\n\n## 使用说明\n\n- 查询 ServiceDeskPlus 请求与 Flashduty 故障之间的同步映射记录，用于排查 ITSM 同步状态或定位外部请求链接。\n- 不按 `incident_id` 查询时，`start_time` 和 `end_time` 必填，均为 Unix 秒时间戳；时间范围不能超过 30 天。\n- `status` 仅支持 `success` 和 `failed`，分别表示同步成功和同步失败。\n- 响应按内部记录 ID 排序；`asc` 为 `true` 时升序，否则降序。继续翻页时传入上次响应的 `search_after_ctx`。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障查看**或**故障管理**或**协作空间查看**或**协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 查询 ServiceDeskPlus 请求与 Flashduty 故障之间的同步映射记录，用于排查 ITSM 同步状态或定位外部请求链接。\n- 不按 `incident_id` 查询时，`start_time` 和 `end_time` 必填，均为 Unix 秒时间戳；时间范围不能超过 30 天。\n- `status` 仅支持 `success` 和 `failed`，分别表示同步成功和同步失败。\n- 响应按内部记录 ID 排序；`asc` 为 `true` 时升序，否则降序。\n- 只能通过 `search_after_ctx` 翻页：传入上次响应返回的值；`p` 会被忽略。",
           "href": "/zh/api-reference/on-call/incidents/incident-service-desk-plus-request-read-list",
           "metadata": {
             "sidebarTitle": "获取 ServiceDeskPlus 关联故障"
@@ -8943,6 +9268,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -8980,7 +9308,7 @@
           "On-call/分析看板"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **分析看板查看**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **分析看板查看**（`on-call`） |\n\n## 使用说明\n\n- 只有时间范围、`team_ids`、`channel_ids`、`severities`、`is_my_team` 和 `split_hours` 会影响结果；其他过滤字段以及 `aggregate_unit` 不生效。\n- 告警按小时粒度统计，实际时间范围按整点对齐。\n- `split_hours` 为 true 时，会分别对 `work`、`sleep`、`off` 各取前 `k` 条，最多返回 3 × `k` 行。\n- 非账户所有者、非管理员的成员只能看到自己有权访问的协作空间的数据，其他协作空间会被静默排除。",
           "href": "/zh/api-reference/on-call/analytics/insight-topk-alerts-by-label",
           "metadata": {
             "sidebarTitle": "查看按 check/resource 聚合的 Top-K 告警"
@@ -9037,6 +9365,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -9072,7 +9403,7 @@
           "On-call/标签增强"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **集成中心查看**（`on-call`） 或 **集成中心管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **集成中心查看**（`on-call`） 或 **集成中心管理**（`on-call`） |\n\n## 使用说明\n\n- 每个 ID 都必须是账户内已存在的集成，否则返回 `InvalidParameter`。\n- 没有配置规则集的集成不会出现在 `items` 中。",
           "href": "/zh/api-reference/on-call/alert-enrichment/enrichment-read-list",
           "metadata": {
             "sidebarTitle": "批量查询富化规则"
@@ -9123,6 +9454,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -9152,12 +9486,12 @@
       "post": {
         "operationId": "channelSilenceRuleDisable",
         "summary": "禁用静默策略",
-        "description": "禁用静默策略而不删除。仅 `enabled` 状态的策略可禁用。",
+        "description": "禁用静默策略但不删除。",
         "tags": [
           "On-call/协作空间"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 仅 `enabled` 状态的策略可禁用，其他状态返回 `InvalidParameter`。\n- `channel_id` 或 `rule_id` 不存在时返回 `InvalidParameter`。\n- 调用者还必须拥有该协作空间的编辑权：账户所有者或管理员、协作空间创建者，或其管理团队成员（`managing_team_ids` 为空时为所属团队成员），否则返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志。",
           "href": "/zh/api-reference/on-call/channels/channel-silence-rule-disable",
           "metadata": {
             "sidebarTitle": "禁用静默策略"
@@ -9196,6 +9530,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -9228,7 +9565,7 @@
           "On-call/故障管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **故障管理**或**协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 集成必须是已启用的自定义操作集成，且其关联的协作空间包含该故障所在的协作空间，否则返回 `InvalidParameter`。\n- 服务端会以 2 秒超时把故障数据 POST 到该操作配置的地址。该请求失败时接口仍返回 HTTP 200，错误信息放在 `data.message` 中；成功时 `data` 为 `null`。\n- 执行成功后会写入一条 `i_custom` 时间线记录。",
           "href": "/zh/api-reference/on-call/incidents/incident-custom-action-do",
           "metadata": {
             "sidebarTitle": "执行自定义操作"
@@ -9256,9 +9593,7 @@
                 },
                 "example": {
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
-                  "data": {
-                    "message": ""
-                  }
+                  "data": null
                 }
               }
             }
@@ -9269,6 +9604,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -9301,7 +9639,7 @@
           "On-call/告警管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间查看**（`on-call`） |\n\n## 使用说明\n\n- 使用 `p`（页码，从 1 开始）和 `limit`（最大 100，默认 20）进行分页。\n- 将 `asc` 设为 `true` 可按时间正序返回。\n- 使用 `types` 过滤特定动态类型（如 `a_comm`、`a_merge`）。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 使用 `p`（页码，从 1 开始）和 `limit`（最大 100，默认 20）进行分页。\n- 将 `asc` 设为 `true` 可按时间正序返回。\n- 使用 `types` 过滤特定动态类型（如 `a_comm`、`a_merge`）。\n- 账户中不存在的 `alert_id` 返回 `InvalidParameter`。",
           "href": "/zh/api-reference/on-call/alerts/alert-read-feed",
           "metadata": {
             "sidebarTitle": "查询告警动态"
@@ -9338,8 +9676,10 @@
                         "detail": {
                           "comment": "Investigating now."
                         },
+                        "account_id": 10023,
                         "creator_id": 80011,
-                        "created_at": 1712651000
+                        "created_at": 1712651000000,
+                        "updated_at": 1712651000000
                       }
                     ]
                   }
@@ -9353,6 +9693,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -9381,12 +9724,12 @@
       "post": {
         "operationId": "insightResponderExport",
         "summary": "导出处理人员洞察",
-        "description": "将响应人维度洞察指标导出为 CSV 文件——每行一个响应人（使用 `aggregate_unit`/`split_hours` 时按时间桶/小时桶拆分）。响应为 CSV 字节流（`Content-Disposition: attachment`），不是 JSON 响应包。`time_zone` 缺省为 UTC。无有效响应人 ID 的行会被跳过。可用的 `export_fields` key：responder_id, responder_name, total_incident_cnt, total_incidents_acknowledged, total_incidents_reassigned, total_incidents_escalated, total_incidents_manually_escalated, total_incidents_timeout_escalated, total_interruptions, total_notifications, total_engaged_seconds, mean_seconds_to_ack, acknowledgement_pct, hours。`hours` 列仅在 `split_hours` 为 true 时默认包含。为兼容起见，故障导出列的 key 也可传入，但导出为空列。",
+        "description": "将响应人维度洞察指标导出为 CSV 文件，行与 `/insight/responder` 的返回一致。",
         "tags": [
           "On-call/分析看板"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **100 次/天**；**20 次/分钟**；**10 次/秒** |\n| 权限要求 | **分析看板查看**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **100 次/天**；**20 次/分钟**；**10 次/秒** |\n| 权限要求 | **分析看板查看**（`on-call`） |\n\n## 使用说明\n\n- 响应是 CSV 文件（`Content-Type: application/octet-stream`），不是 JSON 响应包。参数校验失败时，在写出任何 CSV 内容之前返回 JSON 错误。\n- 过滤参数与 `/insight/responder` 相同。没有响应人 ID 的行的行会被跳过。文件中没有时间桶列，使用 `aggregate_unit` 时不同时间桶的行无法区分；如需按时间拆分，请每个时间桶单独导出一次。\n- `export_fields` 决定导出哪些列及其顺序：responder_id, responder_name, total_incident_cnt, total_incidents_acknowledged, total_incidents_reassigned, total_incidents_escalated, total_incidents_manually_escalated, total_incidents_timeout_escalated, total_interruptions, total_notifications, total_engaged_seconds, mean_seconds_to_ack, acknowledgement_pct, hours。未知或重复的 key 会被拒绝。不传时导出全部列，其中 `hours` 列仅在 `split_hours` 为 true 时包含。\n- 为兼容起见，也接受故障快照类 key（progress, assigned_to, raw_assigned_to, escalate_rule_name, responders, raw_responders, ackers, owner_id, owner_name, creator_id, creator_name, closer_id, closer_name, snooze_status, snoozed_before, ever_muted, frequency, is_rare, alert_cnt, active_alert_cnt, alert_event_cnt, description, labels, fields），这些列导出为空。\n- 列名按语言本地化（依次取请求语言、成员语言、账户语言）。时间桶按 `time_zone` 切分（不传为 UTC）。",
           "href": "/zh/api-reference/on-call/analytics/insight-responder-export",
           "metadata": {
             "sidebarTitle": "导出处理人员洞察"
@@ -9400,7 +9743,7 @@
                 "schema": {
                   "type": "string",
                   "format": "binary",
-                  "description": "CSV 字节流（`Content-Type: application/octet-stream`，`Content-Disposition: attachment; filename=responder_export_yyyyMMdd_HHmmss.csv`）。首行为本地化列名。列默认为完整字段集，或由 `export_fields` 指定。"
+                  "description": "CSV 文件（`Content-Type: application/octet-stream`，`Content-Disposition: attachment; filename*=UTF-8''responder_export_yyyyMMdd_HHmmss.csv`）。第一行为本地化的列名。"
                 },
                 "example": "responder_id,responder_name,total_incident_cnt,total_incidents_acknowledged\n3790925372131,alice,5,4\n"
               }
@@ -9412,6 +9755,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -9451,7 +9797,7 @@
           "On-call/故障管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障查看**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障查看**或**故障管理**或**协作空间查看**（`on-call`） |\n\n## 使用说明\n\n- 不存在的 ID 会被忽略；`total` 为实际找到的故障数，`has_next_page` 恒为 `false`。\n- 结果按 `start_time` 排序，最新在前。\n- 本接口不填充 `integration_type` 和 `assigned_to.escalate_rule_name`。",
           "href": "/zh/api-reference/on-call/incidents/incident-list-by-ids",
           "metadata": {
             "sidebarTitle": "批量查询故障"
@@ -9480,7 +9826,7 @@
                 "example": {
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
-                    "total": 2,
+                    "total": 1,
                     "has_next_page": false,
                     "items": [
                       {
@@ -9521,6 +9867,7 @@
                         "snoozed_before": 0,
                         "group_method": "n",
                         "ever_muted": false,
+                        "has_unfinished_work_item": false,
                         "labels": {},
                         "fields": {},
                         "assigned_to": {
@@ -9559,6 +9906,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -9588,12 +9938,12 @@
       "post": {
         "operationId": "incidentPostMortemList",
         "summary": "查询复盘报告列表",
-        "description": "分页查询复盘报告列表，支持过滤条件。",
+        "description": "查询故障复盘报告列表，可按状态、团队、协作空间和创建时间过滤。",
         "tags": [
           "On-call/故障管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障查看**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 任意有效 `app_key` 均可调用 |\n\n## 使用说明\n\n- 账户所有者和管理员可以看到全部复盘报告；其他成员可以看到公开报告以及自己所在团队的私有报告。\n- 结果按 `order_by` 排序（默认 `created_at_seconds`），默认降序，`asc` 为 `true` 时升序。\n- 列表只返回元数据；完整内容请通过 `GET /incident/post-mortem/info` 获取。",
           "href": "/zh/api-reference/on-call/incidents/incident-post-mortem-list",
           "metadata": {
             "sidebarTitle": "查询复盘报告列表"
@@ -9641,6 +9991,8 @@
                         "team_id": 2477033058131,
                         "channel_id": 3047621227131,
                         "is_private": false,
+                        "generation": 0,
+                        "revision": 12,
                         "channel_name": "Ops Channel",
                         "created_at_seconds": 1773900354,
                         "updated_at_seconds": 1773909012
@@ -9657,6 +10009,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -9685,12 +10040,12 @@
       "post": {
         "operationId": "mapping-api-read-list",
         "summary": "查询映射 API 列表",
-        "description": "返回账户下所有配置的映射 API。",
+        "description": "返回账户下的全部映射 API，按创建时间倒序排列。",
         "tags": [
           "On-call/标签增强"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **映射数据查看**（`on-call`） 或 **映射数据管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **映射数据查看**（`on-call`） 或 **映射数据管理**（`on-call`） |\n\n## 使用说明\n\n- 一次返回全部未删除的映射 API，不分页；`total` 即条目数。\n- 返回所有团队的映射 API，`headers` 以明文返回。",
           "href": "/zh/api-reference/on-call/alert-enrichment/mapping-api-read-list",
           "metadata": {
             "sidebarTitle": "查询映射 API 列表"
@@ -9727,7 +10082,7 @@
                         "description": "Query CMDB for host metadata",
                         "url": "https://cmdb.example.com/api/lookup",
                         "headers": {
-                          "Authorization": "Bearer eyJhbGciOiJIUzI1NiJ9.example-token"
+                          "X-Token": "example-token"
                         },
                         "timeout": 2,
                         "retry_count": 1,
@@ -9735,6 +10090,7 @@
                         "status": "enabled",
                         "team_id": 0,
                         "creator_id": 80011,
+                        "updated_by": 80011,
                         "created_at": 1710000000,
                         "updated_at": 1710000000
                       }
@@ -9750,6 +10106,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -9774,12 +10133,12 @@
       "post": {
         "operationId": "incidentUnack",
         "summary": "取消认领故障",
-        "description": "取消故障的认领状态。",
+        "description": "撤销调用成员对一个或多个故障的认领。",
         "tags": [
           "On-call/故障管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **故障管理**或**协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 只撤销调用成员自己的认领。只有当没有其他处理人仍处于已认领状态时，故障才会回到 `Triggered` 并清除暂停。\n- 所有故障都必须处于 `Processing`；任一故障为 `Triggered` 或 `Closed` 时整个请求返回 `InvalidParameter`。",
           "href": "/zh/api-reference/on-call/incidents/incident-unack",
           "metadata": {
             "sidebarTitle": "取消认领故障"
@@ -9818,6 +10177,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -9851,7 +10213,7 @@
           "On-call/标签增强"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **映射数据管理**（`on-call`） |\n\n## 使用说明\n\n- 仅映射规则创建者、账户管理员或所属团队成员可更新。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **映射数据管理**（`on-call`） |\n\n## 使用说明\n\n- 不传的字段保持原值；`team_id` 传 `0` 表示解除团队关联。\n- `schema_id` 不存在时返回 `InvalidParameter`；新的 `schema_name` 不能与其他映射规则重名。\n- 仅账户管理员、映射规则创建者或映射规则所属团队的成员可以调用，其他人返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/on-call/alert-enrichment/mapping-schema-write-update",
           "metadata": {
             "sidebarTitle": "更新映射规则"
@@ -9890,6 +10252,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -9918,12 +10283,12 @@
       "post": {
         "operationId": "scheduleCreate",
         "summary": "创建值班表",
-        "description": "创建新的值班表（分派策略值班表）。",
+        "description": "创建值班表，包括轮转分层和换班通知设置。",
         "tags": [
           "On-call/值班排班"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **值班管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **值班管理**（`on-call`） |\n\n## 使用说明\n\n- `schedule_name`（或旧字段 `name`）必填，最长 40 个字符，且在账户内唯一。`description` 最长 500 个字符。\n- `time_zone` 决定值班表所有墙钟规则（交接时间、限制时段、星期、定时通知）所用的时区，创建后不可修改。不传时按 `Asia/Shanghai` 计算，读取时 `time_zone` 为空字符串。\n- 分层时间既可以用数字字段（`layer_start`、`handoff_time`、`restrict_periods` 等）传入，也可以用墙钟字符串（`starts_at`、`ends_at`、`handoff`、`restricts_wall`）传入；同时传入时以墙钟字段为准，并按值班表时区换算。\n- 值班表数量超过账户套餐上限时返回 `NoLicense` 错误。\n- 保存前可用 `/schedule/preview` 预览排班结果。\n- 每次调用都会记录到账户审计日志。",
           "href": "/zh/api-reference/on-call/schedules/schedule-create",
           "metadata": {
             "sidebarTitle": "创建值班表"
@@ -9964,6 +10329,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -9982,6 +10350,7 @@
                 "schedule_name": "Production On-Call",
                 "description": "Primary on-call rotation for the production team",
                 "team_id": 4291079133131,
+                "time_zone": "Asia/Shanghai",
                 "layers": [
                   {
                     "layer_name": "Layer 1",
@@ -10061,12 +10430,12 @@
       "post": {
         "operationId": "insightByChannel",
         "summary": "查看协作空间洞察",
-        "description": "返回按协作空间聚合的洞察指标。",
+        "description": "按协作空间分组返回故障与告警指标，每个协作空间、每个时间桶一行。",
         "tags": [
           "On-call/分析看板"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **分析看板查看**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **分析看板查看**（`on-call`） |\n\n## 使用说明\n\n- 每个协作空间、每个时间桶返回一行。`responder_ids` 和 `incident_ids` 不生效。\n- 故障按创建时间归入时间桶。结果按 `ts` 从新到旧排列；没有故障的时间桶（或维度取值）不会出现在结果中，缺行即为 0。`split_hours` 为 true 时，每个时间桶最多返回 3 行，每个 `hours` 取值一行。\n- `total_alert_cnt`、`total_alert_event_cnt` 和 `noise_reduction_pct` 只受时间范围、团队、协作空间和严重程度过滤影响；`query`、`labels`、`fields` 以及时长过滤只作用于故障指标。\n- 非账户所有者、非管理员的成员只能看到自己有权访问的协作空间的数据，其他协作空间会被静默排除。\n- `is_my_team` 为 true 时，`team_ids` 收窄为调用者所在的团队；调用者不属于任何团队时返回空结果。",
           "href": "/zh/api-reference/on-call/analytics/insight-by-channel",
           "metadata": {
             "sidebarTitle": "查看协作空间洞察"
@@ -10134,6 +10503,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -10165,12 +10537,12 @@
       "post": {
         "operationId": "channelDelete",
         "summary": "删除协作空间",
-        "description": "删除协作空间。仅 `disabled` 状态的协作空间可删除，其下的分派、静默、排除和抑制策略会一并删除。当仍有集成路由引用该空间时调用失败。",
+        "description": "删除已禁用的协作空间，并一并删除其下的策略和协作空间专属集成。",
         "tags": [
           "On-call/协作空间"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 仅 `disabled` 状态的协作空间可删除，其他状态返回 `InvalidParameter`。\n- 若仍有共享集成的路由规则（任一 case 或默认分支）指向该协作空间，返回 HTTP 400，`error.code` 为 `ReferenceExist`，`data.refs` 列出引用它的集成。请先通过 `POST /route/upsert` 把它从这些路由中移除。\n- 协作空间下的分派、静默、排除、抑制和订阅策略以及专属集成全部删除。协作空间本身为软删除：`POST /channel/info` 仍可查到，`status` 为 `deleted`。\n- `channel_id` 不存在时返回 `InvalidParameter`。\n- 调用者还必须拥有该协作空间的编辑权：账户所有者或管理员、协作空间创建者，或其管理团队成员（`managing_team_ids` 为空时为所属团队成员），否则返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志。",
           "href": "/zh/api-reference/on-call/channels/channel-delete",
           "metadata": {
             "sidebarTitle": "删除协作空间"
@@ -10209,6 +10581,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -10235,12 +10610,12 @@
       "post": {
         "operationId": "channelUnsubscribeRuleCreate",
         "summary": "创建排除规则",
-        "description": "创建排除规则，在告警成为故障之前过滤不需要的告警。",
+        "description": "创建排除规则，在生成告警和故障之前丢弃命中的告警事件。",
         "tags": [
           "On-call/协作空间"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 排除规则最先检查，早于静默和抑制策略。命中任一启用的排除规则的事件直接丢弃，不产生告警、故障或通知。\n- 不传 `filters` 或传空列表时，该规则不匹配任何事件。\n- `channel_id` 不存在时返回 `InvalidParameter`。\n- 调用者还必须拥有该协作空间的编辑权：账户所有者或管理员、协作空间创建者，或其管理团队成员（`managing_team_ids` 为空时为所属团队成员），否则返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志。",
           "href": "/zh/api-reference/on-call/channels/channel-unsubscribe-rule-create",
           "metadata": {
             "sidebarTitle": "创建排除规则"
@@ -10270,7 +10645,7 @@
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "rule_id": "69db2f6ba0fe7db6448b1505",
-                    "rule_name": "Test drop rule"
+                    "rule_name": "Drop test environment alerts"
                   }
                 }
               }
@@ -10282,6 +10657,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -10322,12 +10700,12 @@
       "post": {
         "operationId": "channelInhibitRuleUpdate",
         "summary": "更新抑制策略",
-        "description": "更新已有抑制策略的配置。",
+        "description": "整体替换已有抑制策略的配置。",
         "tags": [
           "On-call/协作空间"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 整体替换：未传的 `source_filters`、`target_filters` 会被清空，未传 `is_directly_discard` 视为 `false`，未传 `description` 会被清空。\n- `channel_id` 或 `rule_id` 不存在时返回 `InvalidParameter`。\n- 调用者还必须拥有该协作空间的编辑权：账户所有者或管理员、协作空间创建者，或其管理团队成员（`managing_team_ids` 为空时为所属团队成员），否则返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志。",
           "href": "/zh/api-reference/on-call/channels/channel-inhibit-rule-update",
           "metadata": {
             "sidebarTitle": "更新抑制策略"
@@ -10366,6 +10744,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -10397,12 +10778,12 @@
       "post": {
         "operationId": "alert-write-merge",
         "summary": "将告警合并到故障",
-        "description": "将一条或多条告警关联到已有故障。若来源告警之前属于其他故障，且合并后该故障中没有其他告警，则该故障将自动关闭。",
+        "description": "将一条或多条告警移入已有故障，并关闭因此变空的来源故障。",
         "tags": [
           "On-call/告警管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间查看**（`on-call`） |\n\n## 使用说明\n\n- 所有 `alert_ids` 和 `incident_id` 必须属于调用方账户。\n- 可选填 `title` 和 `owner_id` 以同时更新目标故障。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- `alert_ids` 中的每个 ID 和 `incident_id` 都必须属于调用方账户，不存在的 ID 返回 `InvalidParameter`。\n- 已在目标故障中的告警会被跳过。来源故障合并后若不再有告警，会被关闭。\n- `title` 和 `owner_id` 仅在与目标故障当前值不同时才会更新。\n- 同一账户同一时间只处理一个故障变更，并发调用返回 `RequestTooFrequently`。",
           "href": "/zh/api-reference/on-call/alerts/alert-write-merge",
           "metadata": {
             "sidebarTitle": "将告警合并到故障"
@@ -10422,7 +10803,7 @@
                       "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/EmptyResponse"
+                          "$ref": "#/components/schemas/EmptyObject"
                         }
                       }
                     }
@@ -10441,6 +10822,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -10470,12 +10854,12 @@
       "post": {
         "operationId": "statusPageChangeTimelineUpdate",
         "summary": "更新事件时间线",
-        "description": "更新状态页事件的时间线条目。",
+        "description": "修改状态页事件时间线更新的时间或描述。",
         "tags": [
           "On-call/状态页"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **状态页面事件管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **状态页面事件管理**（`on-call`） |\n\n## 使用说明\n\n- 只能修改 `at_seconds` 和 `description`；更新的状态和组件变更不可修改。\n- `at_seconds`（大于 0）与非空 `description` 至少传一个，否则返回 `InvalidParameter`。\n- `at_seconds` 必须介于前一条与后一条更新之间；修改第一条更新的时间会同步修改事件开始时间。\n- 修改最新一条更新的描述会同步更新事件描述。本接口不会通知订阅者。\n- 每次调用都会记录到账户审计日志，请勿在请求字段中写入敏感信息。",
           "href": "/zh/api-reference/on-call/status-pages/status-page-change-timeline-update",
           "metadata": {
             "sidebarTitle": "更新事件时间线"
@@ -10514,6 +10898,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -10544,12 +10931,12 @@
       "post": {
         "operationId": "incidentReopen",
         "summary": "重开故障",
-        "description": "重新打开一个已恢复的故障。",
+        "description": "重新打开已关闭的故障，并从第一级重新分派。",
         "tags": [
           "On-call/故障管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **故障管理**或**协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 所有故障都必须处于 `Closed`，否则整个请求返回 `InvalidParameter`。\n- 重开后故障回到 `Triggered`，`ack_time`、`close_time`、`closer_id` 以及所有处理人的认领状态都会被重置。\n- 每个故障按原分派对象从第一级重新分派，`assigned_to.type` 置为 `reopen`。\n- 同一账户内有其他关闭、重开、合并、评论或删除操作正在执行时返回 `RequestTooFrequently`，稍后重试即可。",
           "href": "/zh/api-reference/on-call/incidents/incident-reopen",
           "metadata": {
             "sidebarTitle": "重开故障"
@@ -10588,6 +10975,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -10622,7 +11012,7 @@
           "On-call/故障管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障管理**（`on-call`） |\n\n## 使用说明\n\n- 要提及成员，在 `comment` 中嵌入形如 `[@显示名](flashduty://ref/member/<member_id>)` 的 markdown 链接。被提及的成员会收到专门的个人通知，不受 `mute_reply` 影响。\n- 不带链接语法的纯 `@名字` 文本不会形成提及。\n- 服务端会将每个提及的显示名改写为成员的规范名称。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **故障管理**或**协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 要提及成员，在 `comment` 中嵌入形如 `[@显示名](flashduty://ref/member/<member_id>)` 的 markdown 链接。被提及的成员会收到专门的个人通知，不受 `mute_reply` 影响。\n- 不带链接语法的纯 `@名字` 文本不会形成提及。\n- 服务端会将每个提及的显示名改写为成员的规范名称。\n- 同一账户内有其他关闭、重开、合并、评论或删除操作正在执行时返回 `RequestTooFrequently`，稍后重试即可。",
           "href": "/zh/api-reference/on-call/incidents/incident-comment",
           "metadata": {
             "sidebarTitle": "评论故障"
@@ -10661,6 +11051,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -10696,7 +11089,7 @@
           "On-call/标签增强"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **集成中心查看**（`on-call`） 或 **集成中心管理**（`on-call`） 或 **映射数据查看**（`on-call`） 或 **映射数据管理**（`on-call`） |\n\n## 使用说明\n\n- 响应为 CSV 文件，包含 `Content-Disposition: attachment` 响应头。\n- CSV 标题行按顺序对应映射规则的来源标签和结果标签。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **60 次/分钟**；**3 次/秒** |\n| 权限要求 | **集成中心查看**（`on-call`） 或 **集成中心管理**（`on-call`） 或 **映射数据查看**（`on-call`） 或 **映射数据管理**（`on-call`） |\n\n## 使用说明\n\n- 响应是 CSV 文件流（`Content-Type: application/octet-stream`），不是 JSON。`Content-Disposition` 中的文件名为映射规则名称，空格替换为 `_`。\n- 首行依次为 `source_labels` 和 `result_labels`；之后每行是一条数据，最近写入的在前。\n- 映射规则必须存在且未被删除，否则返回 JSON 格式的 `InvalidParameter` 错误。",
           "href": "/zh/api-reference/on-call/alert-enrichment/mapping-data-read-download",
           "metadata": {
             "sidebarTitle": "下载映射数据 CSV"
@@ -10712,7 +11105,7 @@
                   "format": "binary",
                   "description": "CSV 文件流（`Content-Type: application/octet-stream`，`Content-Disposition: attachment; filename=<schema_name>.csv`）。首行为表头，按 schema 的 source_labels + result_labels 顺序排列；之后每行一条映射数据。"
                 },
-                "example": "host,owner,team\nserver01,alice,sre\nserver02,bob,backend\n"
+                "example": "host,owner,team,service\nserver01,alice,sre,api\n"
               }
             }
           },
@@ -10722,6 +11115,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -10748,12 +11144,12 @@
       "post": {
         "operationId": "channelUnsubscribeRuleList",
         "summary": "查询排除规则列表",
-        "description": "查询协作空间的排除规则列表。",
+        "description": "按创建时间先后列出协作空间的排除规则。",
         "tags": [
           "On-call/协作空间"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- `channel_id` 不存在时返回 `InvalidParameter`。",
           "href": "/zh/api-reference/on-call/channels/channel-unsubscribe-rule-list",
           "metadata": {
             "sidebarTitle": "查询排除规则列表"
@@ -10817,6 +11213,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -10843,12 +11242,12 @@
       "post": {
         "operationId": "routeList",
         "summary": "查询路由规则列表",
-        "description": "返回指定集成的路由规则列表。未配置路由规则的集成将不出现在响应中。",
+        "description": "一次返回多个共享集成的路由规则。",
         "tags": [
           "On-call/协作空间"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **集成中心查看**（`on-call`） 或 **集成中心管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **集成中心查看**（`on-call`） 或 **集成中心管理**（`on-call`） |\n\n## 使用说明\n\n- 未配置路由规则的集成不会出现在 `items` 中。\n- 每个 ID 都必须是存在的共享集成；只要有一个不存在或属于协作空间专属集成，整个请求返回 `InvalidParameter`。",
           "href": "/zh/api-reference/on-call/channels/route-list",
           "metadata": {
             "sidebarTitle": "查询路由规则列表"
@@ -10922,6 +11321,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -10951,12 +11353,12 @@
       "post": {
         "operationId": "channelList",
         "summary": "查询协作空间列表",
-        "description": "查询当前用户可访问的协作空间列表，支持过滤条件。",
+        "description": "分页查询调用者可见的协作空间，支持过滤和排序。",
         "tags": [
           "On-call/协作空间"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 不加过滤条件时返回账户内全部协作空间，但不包含调用者无权访问的私有协作空间。已删除的协作空间不会返回。\n- `is_my_team` 与 `is_my_starred` 同时为 `true` 时返回 `InvalidParameter`。`is_my_managed` 优先于这两者。使用 `is_my_managed` 或 `is_my_team` 时忽略 `team_ids`。\n- `is_brief: true` 时每项只含 `channel_id`、`channel_name`、`description`、`status`、`is_starred`，并一次返回全部结果。\n- 请始终传入 `p`。不传时虽然返回第一页，但只要有结果 `has_next_page` 就恒为 `true`。",
           "href": "/zh/api-reference/on-call/channels/channel-list",
           "metadata": {
             "sidebarTitle": "查询协作空间列表"
@@ -11005,6 +11407,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -11034,12 +11439,12 @@
       "post": {
         "operationId": "channelEscalateRuleCreate",
         "summary": "创建分派策略",
-        "description": "创建分派策略，定义故障发生时通知谁以及何时通知。",
+        "description": "创建分派策略，决定协作空间的故障通知谁、如何通知。",
         "tags": [
           "On-call/协作空间"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 策略按 `priority` 从小到大匹配，第一条启用且 `time_filters`、`filters` 都命中新故障的策略负责该故障，其后的策略不再匹配。不传 `priority` 时排在现有策略之后。\n- `template_id` 必须是已存在的通知模板，`person_ids` 中的成员必须存在，`team_ids` 中的团队必须有成员，否则返回 `InvalidParameter`。\n- 新建的策略为 `enabled` 状态。\n- `channel_id` 不存在时返回 `InvalidParameter`。\n- 调用者还必须拥有该协作空间的编辑权：账户所有者或管理员、协作空间创建者，或其管理团队成员（`managing_team_ids` 为空时为所属团队成员），否则返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志。",
           "href": "/zh/api-reference/on-call/channels/channel-escalate-rule-create",
           "metadata": {
             "sidebarTitle": "创建分派策略"
@@ -11069,7 +11474,7 @@
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "rule_id": "69db2f72a0fe7db6448b1506",
-                    "rule_name": "Test escalation rule"
+                    "rule_name": "On-call escalation"
                   }
                 }
               }
@@ -11081,6 +11486,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -11126,12 +11534,12 @@
       "post": {
         "operationId": "channelUpdate",
         "summary": "更新协作空间",
-        "description": "更新已有协作空间的配置和设置。",
+        "description": "更新协作空间设置，仅修改请求中出现的字段。",
         "tags": [
           "On-call/协作空间"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 未传或为 `null` 的字段保持原值。`group`、`flapping`、`event_group` 一旦传入即整体替换原配置。\n- 传 `managing_team_ids: []` 可清空管理团队。\n- `auto_resolve_mode` 只有与 `auto_resolve_timeout` 一起传入时才生效；只传 `auto_resolve_timeout` 时，模式会重置为 `trigger`。\n- 每次把 `is_external_report_enabled` 设为 `true` 都会生成新的 `external_report_token`，旧令牌随即失效；设为 `false` 会清空令牌。\n- `channel_name` 与其他协作空间重名时返回 `InvalidParameter`；`group.method` 为 `p` 或 `i` 但许可证不足时返回 `NoLicense`。\n- 调用者还必须拥有该协作空间的编辑权：账户所有者或管理员、协作空间创建者，或其管理团队成员（`managing_team_ids` 为空时为所属团队成员），否则返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志。",
           "href": "/zh/api-reference/on-call/channels/channel-update",
           "metadata": {
             "sidebarTitle": "更新协作空间"
@@ -11172,6 +11580,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -11187,7 +11598,7 @@
                 "$ref": "#/components/schemas/UpdateChannelRequest"
               },
               "example": {
-                "channel_id": 1001,
+                "channel_id": 3521074710131,
                 "channel_name": "Production Alerts (v2)",
                 "description": "Updated description"
               }
@@ -11200,12 +11611,12 @@
       "post": {
         "operationId": "channelEnable",
         "summary": "启用协作空间",
-        "description": "启用协作空间以恢复故障路由。仅 `disabled` 状态的协作空间可启用。",
+        "description": "启用已禁用的协作空间，使其重新处理新的告警事件。",
         "tags": [
           "On-call/协作空间"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 仅 `disabled` 状态的协作空间可启用，其他状态返回 `InvalidParameter`。\n- `channel_id` 不存在时返回 `InvalidParameter`。\n- 调用者还必须拥有该协作空间的编辑权：账户所有者或管理员、协作空间创建者，或其管理团队成员（`managing_team_ids` 为空时为所属团队成员），否则返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志。",
           "href": "/zh/api-reference/on-call/channels/channel-enable",
           "metadata": {
             "sidebarTitle": "启用协作空间"
@@ -11244,6 +11655,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -11270,12 +11684,12 @@
       "post": {
         "operationId": "channelEscalateRuleDelete",
         "summary": "删除分派策略",
-        "description": "删除分派策略。仅 `disabled` 状态的策略可删除。",
+        "description": "删除已禁用的分派策略，使其不再出现在协作空间的策略列表中。",
         "tags": [
           "On-call/协作空间"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 仅 `disabled` 状态的策略可删除，其他状态返回 `InvalidParameter`。\n- 策略为软删除：不再出现在列表中，但 `POST /channel/escalate/rule/info` 仍可查到，`status` 为 `deleted`。\n- `channel_id` 或 `rule_id` 不存在时返回 `InvalidParameter`。\n- 调用者还必须拥有该协作空间的编辑权：账户所有者或管理员、协作空间创建者，或其管理团队成员（`managing_team_ids` 为空时为所属团队成员），否则返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志。",
           "href": "/zh/api-reference/on-call/channels/channel-escalate-rule-delete",
           "metadata": {
             "sidebarTitle": "删除分派策略"
@@ -11314,6 +11728,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -11341,12 +11758,12 @@
       "post": {
         "operationId": "mapping-api-write-delete",
         "summary": "删除映射 API",
-        "description": "删除映射 API。若该 API 被富化规则引用，则拒绝删除。",
+        "description": "软删除映射 API；仍被富化规则引用时拒绝删除。",
         "tags": [
           "On-call/标签增强"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **映射数据管理**（`on-call`） |\n\n## 使用说明\n\n- 若 API 仍被引用，响应返回 HTTP 400，`refs` 字段列出所有阻止删除的引用。\n- 仅 API 创建者、账户管理员或所属团队成员可删除。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **映射数据管理**（`on-call`） |\n\n## 使用说明\n\n- 映射 API 被软删除（`status` 变为 `deleted`），富化规则不再调用它。\n- 若有集成的富化规则使用它（`mapping_type` 为 `api`），返回 HTTP 400 `ReferenceExist`，`data.refs` 最多列出 20 个集成（`kind` 为 `integration`）。\n- `api_id` 不存在时返回 `InvalidParameter`。\n- 仅账户管理员、映射 API 创建者或映射 API 所属团队的成员可以调用，其他人返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/on-call/alert-enrichment/mapping-api-write-delete",
           "metadata": {
             "sidebarTitle": "删除映射 API"
@@ -11385,6 +11802,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -11411,12 +11831,12 @@
       "post": {
         "operationId": "channelInhibitRuleList",
         "summary": "查询抑制策略列表",
-        "description": "查询为指定协作空间配置的所有抑制策略。",
+        "description": "按创建时间先后列出协作空间的抑制策略。",
         "tags": [
           "On-call/协作空间"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间查看**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间查看**（`on-call`） 或 **协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- `channel_id` 不存在时返回 `InvalidParameter`。",
           "href": "/zh/api-reference/on-call/channels/channel-inhibit-rule-list",
           "metadata": {
             "sidebarTitle": "查询抑制策略列表"
@@ -11457,7 +11877,7 @@
                               "key": "severity",
                               "oper": "IN",
                               "vals": [
-                                "Info"
+                                "Critical"
                               ]
                             }
                           ]
@@ -11474,8 +11894,8 @@
                           ]
                         ],
                         "equals": [
-                          "data_source_id",
-                          "labels._account_id"
+                          "labels.cluster",
+                          "labels.service"
                         ],
                         "is_directly_discard": false,
                         "status": "enabled",
@@ -11496,6 +11916,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -11527,7 +11950,7 @@
           "On-call/标签增强"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **20 次/分钟**；**2 次/秒** |\n| 权限要求 | **映射数据管理**（`on-call`） |\n\n## 使用说明\n\n- 请求须使用 `Content-Type: multipart/form-data`，文件字段名为 `file`，`schema_id` 通过查询参数传入。\n- CSV 标题行须包含所有来源标签和结果标签名称。\n- 文件大小上限：100 MB。\n- 默认情况下，导入前先清空现有数据；传入查询参数 `do_not_truncate_first=TRUE` 可改为追加模式。\n- CSV 中存在重复来源标签组合时返回 400 错误。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **60 次/分钟**；**3 次/秒** |\n| 权限要求 | **映射数据管理**（`on-call`） |\n\n## 使用说明\n\n- 请求为 `multipart/form-data`，CSV 放在 `file` 字段；`schema_id` 和 `do_not_truncate_first` 是查询参数。文件最大 100 MB。\n- CSV 首行为表头，必须包含全部来源标签和结果标签，其他列会被丢弃。值超过 2,048 字节会被拒绝；BOM 会被去除。没有数据行的文件返回 `InvalidParameter`。\n- 默认导入前先删除全部现有数据行。传 `do_not_truncate_first=TRUE` 时保留现有数据，来源标签值相同的行会被替换。\n- 来源标签值相同的多行会合并，以后出现的行为准。\n- 按导入后的行数检查行数上限（默认 10,000 行，部分账户更高），超出返回 `InvalidParameter`。\n- 数据每 100 行一批写入；某一批失败时，之前的清空和已写入的批次不会回滚。\n- 映射规则必须存在且未被删除，否则返回 `InvalidParameter`。\n- 仅账户管理员、映射规则创建者或映射规则所属团队的成员可以调用，其他人返回 `AccessDenied`。\n- 同一映射规则的数据写操作（写入、删除、清空、CSV 上传）串行执行；另一个写操作进行中时调用会返回 `RequestTooFrequently`。",
           "href": "/zh/api-reference/on-call/alert-enrichment/mapping-data-write-upload",
           "metadata": {
             "sidebarTitle": "通过 CSV 上传映射数据"
@@ -11566,6 +11989,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -11629,7 +12055,7 @@
           "On-call/告警管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间查看**（`on-call`） |\n\n## 使用说明\n\n- `alert_id` 为 ObjectID 十六进制字符串，可从 `POST /alert/list` 或 `POST /alert-event/list` 获取。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间查看**（`on-call`） 或 **协作空间管理**（`on-call`） 或 **故障查看**（`on-call`） 或 **故障管理**（`on-call`） |\n\n## 使用说明\n\n- `alert_id` 为 ObjectID 十六进制字符串，可从 `POST /alert/list` 或 `POST /alert-event/list` 获取。\n- 账户中不存在的 `alert_id` 返回 `InvalidParameter`。",
           "href": "/zh/api-reference/on-call/alerts/alert-read-info",
           "metadata": {
             "sidebarTitle": "查看告警详情"
@@ -11675,6 +12101,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -11701,12 +12130,12 @@
       "post": {
         "operationId": "incidentAssign",
         "summary": "分派故障",
-        "description": "将故障分派到指定的升级环节或处理人员。",
+        "description": "将故障重新分派给成员或分派策略，替换当前处理人。",
         "tags": [
           "On-call/故障管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **故障管理**或**协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 不在新分派对象中的处理人会被移除，保留下来的处理人维持原认领状态。若剩余处理人都未认领，故障回到 `Triggered`。同时清除暂停。\n- `assigned_to` 中 `person_ids`、`escalate_rule_id`、`emails` 都未设置时，服务端会改为重新匹配协作空间的分派策略。\n- 已关闭的故障会被跳过，不报错。\n- 服务端会填写 `assigned_at`、`id` 和 `escalate_rule_name`，未传 `type` 时自动推断。",
           "href": "/zh/api-reference/on-call/incidents/incident-assign",
           "metadata": {
             "sidebarTitle": "分派故障"
@@ -11745,6 +12174,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -11777,12 +12209,12 @@
       "post": {
         "operationId": "channelInhibitRuleDisable",
         "summary": "禁用抑制策略",
-        "description": "禁用抑制策略而不删除。仅 `enabled` 状态的策略可禁用。",
+        "description": "禁用抑制策略但不删除。",
         "tags": [
           "On-call/协作空间"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 仅 `enabled` 状态的策略可禁用，其他状态返回 `InvalidParameter`。\n- `channel_id` 或 `rule_id` 不存在时返回 `InvalidParameter`。\n- 调用者还必须拥有该协作空间的编辑权：账户所有者或管理员、协作空间创建者，或其管理团队成员（`managing_team_ids` 为空时为所属团队成员），否则返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志。",
           "href": "/zh/api-reference/on-call/channels/channel-inhibit-rule-disable",
           "metadata": {
             "sidebarTitle": "禁用抑制策略"
@@ -11821,6 +12253,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -11848,12 +12283,12 @@
       "post": {
         "operationId": "calendarInfo",
         "summary": "获取服务日历详情",
-        "description": "返回服务日历的详细信息。",
+        "description": "按 ID 返回账户中一个服务日历的详情。",
         "tags": [
           "On-call/日历管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 不存在的 `cal_id` 返回 `InvalidParameter`。",
           "href": "/zh/api-reference/on-call/calendars/calendar-info",
           "metadata": {
             "sidebarTitle": "获取服务日历详情"
@@ -11914,6 +12349,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -11940,12 +12378,12 @@
       "post": {
         "operationId": "channelSilenceRuleCreate",
         "summary": "创建静默策略",
-        "description": "创建一条静默策略，用于抑制满足特定条件的通知。",
+        "description": "创建静默策略，在时间窗口内屏蔽或丢弃命中的告警事件。",
         "tags": [
           "On-call/协作空间"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- `time_filter`（一次性窗口）与 `time_filters`（周期窗口）必须且只能设置其一，且 `filters` 至少包含一个条件，否则返回 `InvalidParameter`。\n- 每个进入的事件依次经过排除策略、静默策略、抑制策略。命中第一条启用、时间窗口覆盖当前时刻且 `filters` 匹配的静默策略即生效。\n- 设置 `from_incident_id` 时，每个故障只能有一条启用的静默策略，再次创建返回 `InvalidParameter`。\n- `channel_id` 不存在时返回 `InvalidParameter`。\n- 调用者还必须拥有该协作空间的编辑权：账户所有者或管理员、协作空间创建者，或其管理团队成员（`managing_team_ids` 为空时为所属团队成员），否则返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志。",
           "href": "/zh/api-reference/on-call/channels/channel-silence-rule-create",
           "metadata": {
             "sidebarTitle": "创建静默策略"
@@ -11975,7 +12413,7 @@
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "rule_id": "69db2f66a0fe7db6448b1503",
-                    "rule_name": "Test silence rule"
+                    "rule_name": "Maintenance window silence"
                   }
                 }
               }
@@ -11987,6 +12425,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -12031,12 +12472,12 @@
       "post": {
         "operationId": "channelSilenceRuleDelete",
         "summary": "删除静默策略",
-        "description": "删除静默策略。仅 `disabled` 状态的策略可删除。",
+        "description": "删除已禁用的静默策略，使其不再出现在协作空间的策略列表中。",
         "tags": [
           "On-call/协作空间"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 仅 `disabled` 状态的策略可删除，其他状态返回 `InvalidParameter`。\n- `channel_id` 或 `rule_id` 不存在时返回 `InvalidParameter`。\n- 调用者还必须拥有该协作空间的编辑权：账户所有者或管理员、协作空间创建者，或其管理团队成员（`managing_team_ids` 为空时为所属团队成员），否则返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志。",
           "href": "/zh/api-reference/on-call/channels/channel-silence-rule-delete",
           "metadata": {
             "sidebarTitle": "删除静默策略"
@@ -12075,6 +12516,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -12107,7 +12551,7 @@
           "On-call/状态页"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **状态页面管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **30 次/分钟**；**2 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 需要 On-call 专业版套餐，否则返回 `AccessDenied`。\n- 异步执行：接口校验 API Key 和源页面后返回 `job_id`，导入在后台进行；请轮询 `GET /status-page/migration/status`。\n- 每个账户同一时间只能运行一个迁移任务，再次发起返回 `InvalidParameter`。\n- 会创建一个开启邮件订阅的公开状态页；对同一源页面再次执行时复用之前创建的状态页。\n- 导入分组（来自组件组）、组件、历史故障与维护以及故障模板；模板导入失败只记入 `progress.warnings`，不会导致任务失败。\n- 每次调用都会记录到账户审计日志，请勿在请求字段中写入敏感信息。",
           "href": "/zh/api-reference/on-call/status-pages/status-page-migrate-structure",
           "metadata": {
             "sidebarTitle": "迁移状态页结构"
@@ -12148,6 +12592,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -12180,7 +12627,7 @@
           "On-call/状态页"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **状态页面管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **30 次/分钟**；**2 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 需要 On-call 专业版套餐，否则返回 `AccessDenied`。\n- 异步执行并返回 `job_id`，请轮询 `GET /status-page/migration/status`。每个账户同一时间只能运行一个迁移任务。\n- 请在对同一源页面执行 `POST /status-page/migrate-structure` 之后调用：组件订阅会映射到结构迁移创建的组件，无法映射的订阅者改为订阅全部组件。\n- 非邮件、已隔离或无邮箱地址的订阅者会被跳过并计入 `progress.subscribers_skipped`；目标页上已存在的接收人保持不变。\n- 每次调用都会记录到账户审计日志，请勿在请求字段中写入敏感信息。",
           "href": "/zh/api-reference/on-call/status-pages/status-page-migrate-email-subscribers",
           "metadata": {
             "sidebarTitle": "迁移邮件订阅者"
@@ -12221,6 +12668,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -12249,12 +12699,12 @@
       "post": {
         "operationId": "template-write-create",
         "summary": "创建模板",
-        "description": "创建一个新的通知模板。",
+        "description": "创建通知模板，按通道配置消息模板。",
         "tags": [
           "On-call/通知模板"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **模板管理**（`on-call`） |\n\n## 使用说明\n\n- `template_name` 必须在账户内唯一，重名会返回 `InvalidParameter`。\n- 服务端会对所有非空通道按 Mock 故障做一次渲染校验，任何通道的语法错误都会导致整个请求返回 `InvalidParameter`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **模板管理**（`on-call`） |\n\n## 使用说明\n\n- 需要专业版或更高版本的订阅，否则返回 `NoLicense`。\n- `template_name` 在账户未删除的模板中必须唯一，且不能与内置预设模板在任一支持语言下的名称相同，否则返回 `InvalidParameter`。\n- 每个非空的通道模板都会用模拟故障试渲染一次，任一通道有语法错误整个请求返回 `InvalidParameter`。`wecom_markdown_v2_enabled` 为 `true` 时，`wecom` 渲染结果不得超过 4,096 字节。\n- 留空的通道在发送通知时使用内置预设内容。\n- `team_id` 非 0 时必须是已存在的团队，否则返回 `InvalidParameter`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/on-call/notification-templates/template-write-create",
           "metadata": {
             "sidebarTitle": "创建模板"
@@ -12296,6 +12746,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -12314,8 +12767,8 @@
                 "team_id": 0,
                 "template_name": "Prod incident default",
                 "description": "Default template for production incidents.",
-                "email": "Incident {{ .IncidentName }} on {{ .Severity }}",
-                "sms": "[Flashduty] {{ .IncidentName }} — {{ .Severity }}"
+                "email": "Incident {{.Title}} is {{.IncidentSeverity}}",
+                "sms": "[Flashduty] {{.Title}} - {{.IncidentSeverity}}"
               }
             }
           }
@@ -12326,12 +12779,12 @@
       "post": {
         "operationId": "routeInfo",
         "summary": "获取路由规则详情",
-        "description": "获取指定集成的路由规则配置。当集成尚未配置路由规则时返回 null。",
+        "description": "返回单个共享集成的路由规则。",
         "tags": [
           "On-call/协作空间"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **集成中心查看**（`on-call`） 或 **集成中心管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **集成中心查看**（`on-call`） 或 **集成中心管理**（`on-call`） |\n\n## 使用说明\n\n- 集成未配置路由规则时，响应只包含 `request_id`，没有 `data` 字段。\n- `integration_id` 为协作空间专属集成或不存在时返回 `InvalidParameter`。",
           "href": "/zh/api-reference/on-call/channels/route-info",
           "metadata": {
             "sidebarTitle": "获取路由规则详情"
@@ -12416,6 +12869,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -12447,7 +12903,7 @@
           "On-call/标签增强"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间查看**（`on-call`） 或 **协作空间管理**（`on-call`） 或 **集成中心查看**（`on-call`） 或 **集成中心管理**（`on-call`） |\n\n## 使用说明\n\n- 若该集成尚未配置富化规则，返回 `null`。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间查看**（`on-call`） 或 **协作空间管理**（`on-call`） 或 **集成中心查看**（`on-call`） 或 **集成中心管理**（`on-call`） |\n\n## 使用说明\n\n- `integration_id` 必须是账户内已存在的集成，否则返回 `InvalidParameter`。\n- 集成没有配置规则集时返回 `data: null`。",
           "href": "/zh/api-reference/on-call/alert-enrichment/enrichment-read-info",
           "metadata": {
             "sidebarTitle": "查看富化规则"
@@ -12504,6 +12960,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -12530,12 +12989,12 @@
       "post": {
         "operationId": "channelInfo",
         "summary": "获取协作空间详情",
-        "description": "获取指定协作空间的详细信息。",
+        "description": "返回单个协作空间的完整配置，以及近 30 天内活跃故障的统计。",
         "tags": [
           "On-call/协作空间"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 已删除的协作空间仍会返回，`status` 为 `deleted`。\n- 私有协作空间（`is_private: true`）仅对账户所有者或管理员、创建者、所属团队或管理团队成员可见，其他调用者返回 `AccessDenied`。\n- 此接口不返回 `team_name`、`creator_name`、`is_starred`，需要时请用 `POST /channel/list`。\n- `channel_id` 不存在时返回 `InvalidParameter`。",
           "href": "/zh/api-reference/on-call/channels/channel-info",
           "metadata": {
             "sidebarTitle": "获取协作空间详情"
@@ -12579,6 +13038,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -12610,7 +13072,7 @@
           "On-call/通知模板"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **模板查看**（`on-call`） 或 **模板管理**（`on-call`） |\n\n## 使用说明\n\n- 默认返回第 1 页、每页 20 条。响应中的 `has_next_page` 可以直接告知是否还有下一页，无需额外计数请求。\n- 当 `is_my_team=true` 时 `team_ids` 字段会被忽略。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间查看**（`on-call`） 或 **协作空间管理**（`on-call`） 或 **模板查看**（`on-call`） 或 **模板管理**（`on-call`） |\n\n## 使用说明\n\n- 第一页的第一条总是内置预设模板（`template_id` 为 `6321aad26c12104586a88916`），不受过滤条件影响，并计入 `total`。\n- 按 `orderby`（默认 `created_at`）排序，默认倒序，`asc` 为 `true` 时正序。已软删除的模板不返回。\n- `is_my_team: true` 时只返回调用方所在团队的模板；同时传了 `team_ids` 则只保留两者共有的团队。若交集为空，则不按团队过滤，返回所有团队的模板。调用方不属于任何团队时返回空结果（`total` 为 0，也没有预设模板）。\n- `query` 是对 `template_name` 的正则匹配，不区分大小写；不合法的正则按普通文本匹配。",
           "href": "/zh/api-reference/on-call/notification-templates/template-read-list",
           "metadata": {
             "sidebarTitle": "查询模板列表"
@@ -12648,8 +13110,8 @@
                         "template_id": "6605a1b2c3d4e5f6a7b8c9d0",
                         "template_name": "Prod incident default",
                         "description": "Default template for production incidents.",
-                        "email": "Incident {{ .IncidentName }} on {{ .Severity }}",
-                        "sms": "[Flashduty] {{ .IncidentName }} — {{ .Severity }}",
+                        "email": "Incident {{.Title}} is {{.IncidentSeverity}}",
+                        "sms": "[Flashduty] {{.Title}} - {{.IncidentSeverity}}",
                         "voice": "",
                         "dingtalk": "",
                         "wecom": "",
@@ -12662,6 +13124,14 @@
                         "telegram": "",
                         "slack": "",
                         "zoom": "",
+                        "wecom_markdown_v2_enabled": false,
+                        "feishu_app_card_v2_table_enabled": false,
+                        "feishu_app_card_v2_preserve_blank_lines": false,
+                        "feishu_app_war_room_enabled": false,
+                        "dingtalk_app_war_room_enabled": false,
+                        "slack_app_war_room_enabled": false,
+                        "incident_card_closed_action_apps": [],
+                        "incident_card_hidden_fields": {},
                         "status": "enabled",
                         "creator_id": 80011,
                         "updated_by": 80011,
@@ -12680,6 +13150,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -12710,12 +13183,12 @@
       "post": {
         "operationId": "insightByResponder",
         "summary": "查看处理人员洞察",
-        "description": "返回按处理人员聚合的洞察指标。",
+        "description": "按响应人返回故障处理指标，每个响应人、每个时间桶一行。",
         "tags": [
           "On-call/分析看板"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **分析看板查看**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **分析看板查看**（`on-call`） |\n\n## 使用说明\n\n- 每个响应人、每个时间桶返回一行；`responder_ids` 用于限定返回哪些响应人。`seconds_to_close_from`/`seconds_to_close_to` 和 `incident_ids` 不生效。\n- 故障按创建时间归入时间桶。结果按 `ts` 从新到旧排列；没有故障的时间桶（或维度取值）不会出现在结果中，缺行即为 0。`split_hours` 为 true 时，每个时间桶最多返回 3 行，每个 `hours` 取值一行。\n- 非账户所有者、非管理员的成员只能看到自己有权访问的协作空间的数据，其他协作空间会被静默排除。\n- `is_my_team` 为 true 时，`team_ids` 收窄为调用者所在的团队；调用者不属于任何团队时返回空结果。",
           "href": "/zh/api-reference/on-call/analytics/insight-by-responder",
           "metadata": {
             "sidebarTitle": "查看处理人员洞察"
@@ -12774,6 +13247,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -12805,12 +13281,12 @@
       "get": {
         "operationId": "statusPageChangeList",
         "summary": "查询状态页事件列表",
-        "description": "查询状态页事件列表（管理端）。与公开展示接口不同，响应包含隐藏组件在内的完整数据。",
+        "description": "按状态和时间窗查询状态页的故障或维护事件，包含隐藏组件。",
         "tags": [
           "On-call/状态页"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 一次返回全部匹配事件（不分页），按 `start_at_seconds` 从新到旧排序。\n- 不传 `start_at_seconds` 和 `end_at_seconds` 时不限制时间范围。",
           "href": "/zh/api-reference/on-call/status-pages/status-page-change-list",
           "metadata": {
             "sidebarTitle": "查询状态页事件列表"
@@ -12901,6 +13377,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -12982,7 +13461,7 @@
           "On-call/状态页"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 一次返回该类型全部非终态事件，按开始时间从新到旧排序：故障为 `investigating`/`identified`/`monitoring`，维护为 `scheduled`/`ongoing`。",
           "href": "/zh/api-reference/on-call/status-pages/status-page-change-active-list",
           "metadata": {
             "sidebarTitle": "查询状态页活跃事件列表"
@@ -13059,6 +13538,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -13102,7 +13584,7 @@
           "On-call/状态页"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 任意有效 `app_key` 均可调用 |\n\n## 使用说明\n\n- `draft` 载荷将被原样存储（最大 64 KB）；控制台发布表单会读取它来预填事件内容。\n- 草稿保留 30 天，事件发布时被消费且仅可消费一次。\n- 每次调用都会记录到账户审计日志，请勿在请求字段中写入敏感信息。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **状态页面事件管理**（`on-call`） |\n\n## 使用说明\n\n- `draft` 载荷将被原样存储（最大 64 KB）；控制台发布表单会读取它来预填事件内容。\n- `draft.page_id` 必须是调用方账户下的状态页，`draft.affected_components` 中的组件必须存在于该页，`draft.change_id` 大于 0 时必须指向同一 `type` 的事件。\n- 发布时将 `draft_id` 传给 `POST /status-page/change/create`（新事件）或 `POST /status-page/change/timeline/create`（向 `draft.change_id` 追加更新）；草稿只能发布一次。\n- 草稿创建 30 天后删除，无论是否已发布。\n- 每次调用都会记录到账户审计日志，请勿在请求字段中写入敏感信息。",
           "href": "/zh/api-reference/on-call/status-pages/status-page-draft-create",
           "metadata": {
             "sidebarTitle": "创建状态页草稿"
@@ -13144,6 +13626,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -13183,12 +13668,12 @@
       "post": {
         "operationId": "mapping-api-write-create",
         "summary": "创建映射 API",
-        "description": "创建新的外部 HTTP API 端点，用于通过 HTTP 查询富化告警。",
+        "description": "登记一个外部 HTTP API，供富化规则调用以查询告警标签。",
         "tags": [
           "On-call/标签增强"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **映射数据管理**（`on-call`） |\n\n## 使用说明\n\n- `url` 须以 `http://` 或 `https://` 开头，SaaS 模式下不得解析为内网 IP。\n- `timeout` 为 HTTP 读取超时秒数（1–3，默认 2）。\n- `retry_count` 为失败重试次数（0–1，默认 0）。\n- SaaS 模式下，含敏感名称的请求头（如 `authorization`、`cookie`）将被拒绝。\n- 账户最多可创建 50 个映射 API。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **映射数据管理**（`on-call`） |\n\n## 使用说明\n\n- `mapping_type` 为 `api` 的富化规则会携带配置的 `headers` 发送 `POST <url>`，请求体为 JSON `{\"result_label_keys\": [...], \"event\": {...}}`（告警事件）。API 须返回 HTTP 200 和 `{\"result_labels\": {\"<label>\": \"<value>\"}}`。\n- `url` 必须使用 `http` 或 `https`；SaaS 环境下主机名不得解析到内网 IP。\n- `timeout` 是整个请求的超时秒数（1–3，默认 2）；`retry_count` 是失败后的重试次数（0–1，默认 0）。\n- SaaS 环境下会拒绝以下敏感请求头（不区分大小写）：`Authorization`、`Proxy-Authorization`、`Cookie`、`X-Api-Key`、`X-Access-Token`、`X-Forwarded-For`、`X-Real-Ip`、`True-Client-Ip`、`X-Client-Ip`、`Host`、`X-Forwarded-Host`、`X-Forwarded-Proto`、`X-Internal-Id`、`X-User-Id`、`Transfer-Encoding`、`Upgrade`、`Connection`。\n- `api_name` 在未删除的映射 API 中必须唯一；每个账户最多 50 个未删除的映射 API。`team_id` 非 0 时必须是已存在的团队。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/on-call/alert-enrichment/mapping-api-write-create",
           "metadata": {
             "sidebarTitle": "创建映射 API"
@@ -13230,6 +13715,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -13264,12 +13752,12 @@
       "post": {
         "operationId": "scheduleUpdate",
         "summary": "更新值班表",
-        "description": "更新已有的值班表，需要通过 schedule_id 指定值班表。",
+        "description": "更新 `schedule_id` 指定的值班表；分层列表整体替换。",
         "tags": [
           "On-call/值班排班"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **值班管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **值班管理**（`on-call`） |\n\n## 使用说明\n\n- `layers` 总是整体替换：请把要保留的分层全部传入。不传 `layers`（或传空数组）会删除所有分层。\n- 未传的 `schedule_name`、`description`、`team_id`、`notify` 和 `status` 保持原值。传入的 `notify` 会整体替换通知配置。\n- 更新时旧字段 `name` 和 `disabled` 不生效；改名请用 `schedule_name`，启用/禁用请用 `status`（`0` 启用，`1` 禁用）。\n- `time_zone` 不可修改：不传或传当前值；传入其他值会被拒绝。分层的墙钟字段按已保存的时区换算。\n- 每次调用都会记录到账户审计日志。",
           "href": "/zh/api-reference/on-call/schedules/schedule-update",
           "metadata": {
             "sidebarTitle": "更新值班表"
@@ -13308,6 +13796,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -13323,10 +13814,59 @@
                 "$ref": "#/components/schemas/ScheduleUpsertRequest"
               },
               "example": {
-                "schedule_id": 2001,
-                "schedule_name": "Production On-Call (Updated)",
-                "description": "Updated primary on-call rotation",
-                "team_id": 4291079133131
+                "schedule_id": 5789640530410,
+                "schedule_name": "Production On-Call",
+                "description": "Primary on-call rotation for the production team",
+                "team_id": 4291079133131,
+                "status": 0,
+                "layers": [
+                  {
+                    "layer_name": "Layer 1",
+                    "mode": 0,
+                    "groups": [
+                      {
+                        "group_name": "A",
+                        "members": [
+                          {
+                            "role_id": 0,
+                            "person_ids": [
+                              2451002751131
+                            ]
+                          }
+                        ]
+                      },
+                      {
+                        "group_name": "B",
+                        "members": [
+                          {
+                            "role_id": 0,
+                            "person_ids": [
+                              2476123212131
+                            ]
+                          }
+                        ]
+                      }
+                    ],
+                    "rotation_unit": "day",
+                    "rotation_value": 1,
+                    "starts_at": {
+                      "date": "2026-04-13",
+                      "time": "09:00"
+                    },
+                    "restrict_mode": 0,
+                    "day_mask": {
+                      "repeat": [
+                        1,
+                        2,
+                        3,
+                        4,
+                        5
+                      ]
+                    },
+                    "fair_rotation": false,
+                    "mask_continuous_enabled": false
+                  }
+                ]
               }
             }
           }
@@ -13337,12 +13877,12 @@
       "post": {
         "operationId": "template-write-delete",
         "summary": "删除模板",
-        "description": "按 ID 软删除一个模板。",
+        "description": "按 ID 软删除通知模板。",
         "tags": [
           "On-call/通知模板"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **模板管理**（`on-call`） |\n\n## 使用说明\n\n- 若模板仍被任何协作空间、分派策略或通知订阅引用，会返回 `400 ReferenceExist`。\n- 删除是软删除（`deleted_at` 被置值），记录仍保留用于审计，但模板不会再出现在列表中。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **模板管理**（`on-call`） |\n\n## 使用说明\n\n- 若仍有分派策略使用该模板，返回 HTTP 400 `ReferenceExist`，`data.refs` 列出引用方（`kind` 为 `escalate_rule`，含策略 `name` 和控制台 `href`）。\n- 模板的 `status` 变为 `deleted`：不再出现在 `/template/list` 中、名称可被复用，但 `/template/info` 仍能查到。\n- `template_id` 不存在或已删除时返回 `InvalidParameter`。\n- 仅账户管理员、模板创建者或模板所属团队的成员可以调用，其他人返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/on-call/notification-templates/template-write-delete",
           "metadata": {
             "sidebarTitle": "删除模板"
@@ -13415,7 +13955,7 @@
           "On-call/标签增强"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **映射数据管理**（`on-call`） |\n\n## 使用说明\n\n- 每条数据须包含映射规则中定义的所有来源标签和结果标签的值。\n- 未知标签的值将被静默忽略。\n- 每个值最多 2048 个字符。\n- Upsert 以来源标签组合为键，来源键相同的行将被更新。\n- 单个映射规则默认最多存储 10,000 条数据。\n- 每个映射规则的写入操作有锁保护，并发 Upsert 可能返回 `ErrRequestTooFrequently`。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **映射数据管理**（`on-call`） |\n\n## 使用说明\n\n- 每行以来源标签值作为标识。来源标签值与已有行相同时整行替换，其 `created_at` 和 `updated_at` 会被重置。\n- 每行必须包含全部来源标签和结果标签（否则返回 `InvalidParameter`），其他键会被丢弃；值超过 2,048 字节会被拒绝。\n- 同一请求中来源标签值相同的多行会合并，以后出现的行为准。\n- 每个映射规则默认最多 10,000 行（部分账户更高）。会使行数超过上限的请求返回 `InvalidParameter`；只替换已有行的请求不受影响。\n- 数据每 100 行一批写入；某一批失败时，之前已写入的批次不会回滚。\n- 映射规则必须存在且未被删除，否则返回 `InvalidParameter`。\n- 仅账户管理员、映射规则创建者或映射规则所属团队的成员可以调用，其他人返回 `AccessDenied`。\n- 同一映射规则的数据写操作（写入、删除、清空、CSV 上传）串行执行；另一个写操作进行中时调用会返回 `RequestTooFrequently`。",
           "href": "/zh/api-reference/on-call/alert-enrichment/mapping-data-write-upsert",
           "metadata": {
             "sidebarTitle": "写入映射数据"
@@ -13459,6 +13999,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -13504,7 +14047,7 @@
           "On-call/故障管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **故障管理**（`on-call`）或 **协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 字段必须在账户中存在且处于启用状态；`field_value` 必须符合字段类型和选项。\n- 省略 `field_value` 或传 `null` 会清空该故障上的这个字段。\n- 若新值与当前值相同，则不做任何修改。\n- 修改会在故障时间线上新增一条字段变更记录，并像控制台修改一样触发通知和 Webhook。",
           "href": "/zh/api-reference/on-call/incidents/incident-field-reset",
           "metadata": {
             "sidebarTitle": "更新故障自定义字段"
@@ -13543,6 +14086,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -13571,12 +14117,12 @@
       "post": {
         "operationId": "scheduleSelf",
         "summary": "查询我的值班表",
-        "description": "返回当前用户被分配的值班表列表。",
+        "description": "列出调用成员所属的已启用值班表，并给出该成员在时间窗口内的班次。",
         "tags": [
           "On-call/值班排班"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **值班查看**（`on-call`） 或 **值班管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **值班查看**（`on-call`） 或 **值班管理**（`on-call`） |\n\n## 使用说明\n\n- 列出调用成员出现在任一分层中的全部已启用值班表，不论其在窗口内是否值班。已禁用的值班表会被跳过。\n- `final_schedule` 只保留调用者本人的班次：调用者不在班的时段 `group` 为 `null`。`layers` 和 `schedule_layers` 描述整个值班表。\n- 本接口中 `cur_oncall` 和 `next_oncall` 恒为 `null`；如需调用者当前及下一次值班，请使用 `/schedule/by-person`。\n- `start` 和 `end` 为 10 位 Unix 秒级时间戳；`end` 必须晚于 `start`，且相差不超过 45 天。",
           "href": "/zh/api-reference/on-call/schedules/schedule-self",
           "metadata": {
             "sidebarTitle": "查询我的值班表"
@@ -13611,6 +14157,7 @@
                         "name": "Open Source Q&A",
                         "account_id": 2451002751131,
                         "group_id": 2477033058131,
+                        "time_zone": "",
                         "disabled": 0,
                         "create_at": 1702623874,
                         "create_by": 2451002751131,
@@ -13717,6 +14264,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -13744,12 +14294,12 @@
       "post": {
         "operationId": "channelUnsubscribeRuleDisable",
         "summary": "禁用排除规则",
-        "description": "禁用排除规则而不删除。仅 `enabled` 状态的规则可禁用。",
+        "description": "禁用排除规则但不删除。",
         "tags": [
           "On-call/协作空间"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 仅 `enabled` 状态的规则可禁用，其他状态返回 `InvalidParameter`。\n- `channel_id` 或 `rule_id` 不存在时返回 `InvalidParameter`。\n- 调用者还必须拥有该协作空间的编辑权：账户所有者或管理员、协作空间创建者，或其管理团队成员（`managing_team_ids` 为空时为所属团队成员），否则返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志。",
           "href": "/zh/api-reference/on-call/channels/channel-unsubscribe-rule-disable",
           "metadata": {
             "sidebarTitle": "禁用排除规则"
@@ -13788,6 +14338,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -13815,12 +14368,12 @@
       "post": {
         "operationId": "channelSilenceRuleList",
         "summary": "查询静默策略列表",
-        "description": "查询为指定协作空间配置的所有静默策略。",
+        "description": "列出协作空间的静默策略，以及每条策略当前是否生效。",
         "tags": [
           "On-call/协作空间"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间查看**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间查看**（`on-call`） 或 **协作空间管理**（`on-call`） 或 **故障查看**（`on-call`） 或 **故障管理**（`on-call`） |\n\n## 使用说明\n\n- 查询列表时会顺带永久移除已到自动清理时间的一次性窗口策略（见 `is_auto_delete`），这些策略不再出现。使用周期 `time_filters` 的策略不会因此被移除。\n- `channel_id` 不存在时返回 `InvalidParameter`。",
           "href": "/zh/api-reference/on-call/channels/channel-silence-rule-list",
           "metadata": {
             "sidebarTitle": "查询静默策略列表"
@@ -13892,6 +14445,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -13923,7 +14479,7 @@
           "On-call/故障管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障管理**（`on-call`） |\n\n## 使用说明\n\n- 账户的创建表单生效时，必须提供其中可见的自定义字段和必填系统字段。\n- 如需在创建时附加图片，请使用 `multipart/form-data`：在 `data` 中传 JSON 请求体，在 `images` 中传文件；完整请求不得超过 50 MiB。\n- 已审计 —— 变更会记录到审计日志。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **故障管理**（`on-call`）或 **协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 账户未配置创建表单时，只有 `incident_severity` 必填。\n- 账户配置了创建表单时，`title`（非空）、`channel_id` 和 `assigned_to` 变为必填；`fields` 只能包含表单中可见的自定义字段，且表单的必填字段必须填写。\n- 仅当创建表单包含图片上传元素时才能附加图片（最多 10 张）：使用 `multipart/form-data`，在 `data` 中传 JSON 请求体，在 `images` 中传文件；整个请求不得超过 50 MiB。\n- 分派在故障创建之后执行。未传 `assigned_to` 时由协作空间的分派策略决定；未传 `assigned_to` 的独立故障不会有处理人员。分派失败（例如 `layer_idx` 越界）时故障仍会创建，只是没有处理人员。",
           "href": "/zh/api-reference/on-call/incidents/incident-create",
           "metadata": {
             "sidebarTitle": "创建故障"
@@ -13965,6 +14521,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -14030,7 +14589,7 @@
           "On-call/标签增强"
         ],
         "x-mint": {
-          "content": "## 调用限制\n\n| 项 | 值 |\n| ------ | ----- |\n| 速率限制 | 每账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限 | **故障可读** (`on-call`) 或 **故障可管理** (`on-call`) |\n\n## 使用说明\n\n- `field_id` 不存在时返回 400；已软删除的字段仍会返回，此时 `status` 为 `deleted` 且带 `deleted_at`。\n- `options` 与 `default_value` 的形态随 `field_type` 变化，详见 `FieldItem`。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **自定义字段查看**（`on-call`） 或 **自定义字段管理**（`on-call`） |\n\n## 使用说明\n\n- `field_id` 不存在时返回 `InvalidParameter`。已删除的字段在 `/field/delete` 触发的后台清理完成前仍会返回，`status` 为 `deleted`；清理完成后该 ID 视为不存在。\n- `options` 和 `default_value` 的结构取决于 `field_type`，详见 `FieldItem`。",
           "href": "/zh/api-reference/on-call/alert-enrichment/field-read-info",
           "metadata": {
             "sidebarTitle": "查看自定义字段"
@@ -14089,6 +14648,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -14120,7 +14682,7 @@
           "On-call/标签增强"
         ],
         "x-mint": {
-          "content": "## 调用限制\n\n| 项 | 值 |\n| ------ | ----- |\n| 速率限制 | 每账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限 | **故障可读** (`on-call`) 或 **故障可管理** (`on-call`) |\n\n## 使用说明\n\n- 一次性返回全部未删除字段，无分页与 `total`。\n- `query` 仅匹配 `field_name`；非法正则会自动转义为字面量子串匹配。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **自定义字段查看**（`on-call`） 或 **自定义字段管理**（`on-call`） 或 **协作空间查看**（`on-call`） 或 **协作空间管理**（`on-call`） 或 **故障查看**（`on-call`） 或 **故障管理**（`on-call`） 或 **集成中心查看**（`on-call`） 或 **集成中心管理**（`on-call`） 或 **模板查看**（`on-call`） 或 **模板管理**（`on-call`） |\n\n## 使用说明\n\n- 一次返回全部未删除的字段，无分页、无 `total`。按 `orderby`（默认 `created_at`）排序，默认倒序，`asc` 为 `true` 时正序。\n- `query` 是对 `field_name` 的正则匹配，不区分大小写；不合法的正则按普通文本匹配。",
           "href": "/zh/api-reference/on-call/alert-enrichment/field-read-list",
           "metadata": {
             "sidebarTitle": "查看自定义字段列表"
@@ -14183,6 +14745,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -14216,7 +14781,7 @@
           "On-call/标签增强"
         ],
         "x-mint": {
-          "content": "## 调用限制\n\n| 项 | 值 |\n| ------ | ----- |\n| 速率限制 | 每账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限 | **故障可管理** (`on-call`) |\n\n## 使用说明\n\n- 每个账号最多 **15** 个自定义字段。\n- `field_name` 必须匹配 `^[a-zA-Z_][a-zA-Z0-9_]{0,39}$`，创建后不可更改；`display_name` 在账号内须唯一。\n- 类型规则：`checkbox` 仅支持 `value_type=bool` 且无 `options`；`single_select`/`multi_select` 要求 `value_type=string` 且 `options` 非空且元素唯一；`text` 仅支持 `value_type=string` 且无 `options`。\n- 响应仅包含 `field_id` 与 `field_name`，如需完整对象请调用 `/field/info`。\n- 该接口会被审计日志记录。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **自定义字段管理**（`on-call`） |\n\n## 使用说明\n\n- 需要标准版或更高版本的订阅，否则返回 `NoLicense`。\n- 每个账户默认最多 15 个未删除的自定义字段（部分账户上限更高），超出返回 `InvalidParameter`。\n- `field_name` 为 1–39 个字符，须匹配 `^[a-zA-Z_][a-zA-Z0-9_]*$`，唯一且创建后不可修改。已删除字段的名称只能在 `field_type` 和 `value_type` 都相同时复用。`display_name` 在未删除字段中须唯一。\n- 类型规则：`checkbox` 要求 `value_type=bool` 且不带 `options`；`single_select`/`multi_select` 要求 `value_type=string` 且 `options` 非空、不重复；`text` 要求 `value_type=string` 且不带 `options`。\n- 响应只包含 `field_id` 和 `field_name`，完整信息请调用 `/field/info`。\n- 同一账户并发创建会返回 `RequestTooFrequently`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/on-call/alert-enrichment/field-write-create",
           "metadata": {
             "sidebarTitle": "创建自定义字段"
@@ -14258,6 +14823,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -14300,7 +14868,7 @@
           "On-call/标签增强"
         ],
         "x-mint": {
-          "content": "## 调用限制\n\n| 项 | 值 |\n| ------ | ----- |\n| 速率限制 | 每账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限 | **故障可管理** (`on-call`) |\n\n## 使用说明\n\n- 仅可修改 `display_name`、`description`、`options`、`default_value`；`field_name`、`field_type`、`value_type` 不可更改。\n- `options` 与 `default_value` 需保持与字段当前类型一致，规则同创建接口。\n- 该接口会被审计日志记录。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **自定义字段管理**（`on-call`） |\n\n## 使用说明\n\n- 每次调用都会用请求值覆盖 `display_name`、`description`、`options` 和 `default_value`，不传即被清空，请始终传完整的目标值。\n- `field_name`、`field_type`、`value_type` 不可修改；`options` 和 `default_value` 须满足创建时的类型规则。\n- `field_id` 不存在时返回 `InvalidParameter`；`display_name` 在未删除字段中须保持唯一。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/on-call/alert-enrichment/field-write-update",
           "metadata": {
             "sidebarTitle": "变更自定义字段"
@@ -14339,6 +14907,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -14379,7 +14950,7 @@
           "On-call/标签增强"
         ],
         "x-mint": {
-          "content": "## 调用限制\n\n| 项 | 值 |\n| ------ | ----- |\n| 速率限制 | 每账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限 | **故障可管理** (`on-call`) |\n\n## 使用说明\n\n- 字段会被同步标记为已删除；历史故障中的字段值会在后台清理，大型数据集可能需要时间。\n- 仅当 `field_type` 和 `value_type` 与已删除字段一致时，才能使用相同 `field_name` 重新创建。\n- 自定义表单仍使用该字段时，删除会返回 `ReferenceExist`，引用表单位于 `data.refs`；移除所有引用后才能删除。\n- 已审计 —— 变更会记录到审计日志。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **自定义字段管理**（`on-call`） |\n\n## 使用说明\n\n- 若有自定义表单引用该字段，返回 HTTP 400 `ReferenceExist`，`data.refs` 列出引用的表单；需先移除引用。\n- 字段立即被标记为已删除，随后后台任务清除历史故障中的该字段值，最后删除字段记录。\n- 删除已删除的字段直接返回成功；`field_id` 不存在时返回 `InvalidParameter`。\n- 之后只有 `field_type` 和 `value_type` 都相同时才能复用该 `field_name`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/on-call/alert-enrichment/field-write-delete",
           "metadata": {
             "sidebarTitle": "删除自定义字段"
@@ -14452,6 +15023,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -14483,7 +15057,7 @@
           "On-call/变更管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- `start_time` 和 `end_time` 均为必填：`start_time` 必须小于 `end_time`，且时间跨度不超过 31 天。\n- 变更的 `[start_time, last_time]` 区间与查询时间窗有重叠即视为匹配。\n- 将 `include_events` 设为 `true` 可在 `events` 中附带每个变更的原始变更事件。",
           "href": "/zh/api-reference/on-call/changes/change-read-list",
           "metadata": {
             "sidebarTitle": "查询变更列表"
@@ -14548,6 +15122,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -14583,12 +15160,12 @@
       "post": {
         "operationId": "incident-read-get-war-room-default-observers",
         "summary": "查看作战室默认观察者",
-        "description": "返回开启作战室时建议作为默认观察者的历史响应人。",
+        "description": "返回曾被分派到故障、但当前已不是处理人员的人，作为作战室的建议观察者。",
         "tags": [
           "On-call/故障管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 需要 On-call Pro 许可。\n- 观察者为在故障时间线中曾被分派或被添加为处理人员、但当前不在处理人员中的人。\n- `observers` 为空数组表示没有符合条件的人。\n- 故障不存在时返回 `ResourceNotFound`。",
           "href": "/zh/api-reference/on-call/incidents/incident-read-get-war-room-default-observers",
           "metadata": {
             "sidebarTitle": "查看作战室默认观察者"
@@ -14619,16 +15196,15 @@
                   "data": {
                     "observers": [
                       {
-                        "account_id": 10001,
-                        "person_id": 20001,
+                        "account_id": 2451002751131,
+                        "person_id": 3790925372131,
                         "person_name": "Alice Chen",
-                        "avatar": "https://cdn.flashcat.cloud/avatar/20001.png",
-                        "email": "alice@acme.com",
-                        "phone": "+8613800000000",
+                        "avatar": "https://example.com/avatars/3790925372131.png",
+                        "email": "alice@example.com",
                         "locale": "zh-CN",
                         "time_zone": "Asia/Shanghai",
-                        "as": "responder",
-                        "status": "active"
+                        "as": "member",
+                        "status": "enabled"
                       }
                     ]
                   }
@@ -14642,6 +15218,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -14657,7 +15236,7 @@
                 "$ref": "#/components/schemas/GetWarRoomDefaultObserversRequest"
               },
               "example": {
-                "incident_id": "664a1b2c3d4e5f6a7b8c9d0e"
+                "incident_id": "69bb9233331067560c718ecd"
               }
             }
           }
@@ -14668,12 +15247,12 @@
       "post": {
         "operationId": "incident-write-add-war-room-member",
         "summary": "添加作战室成员",
-        "description": "向与故障集成绑定的 IM 作战室添加一名或多名成员。",
+        "description": "向飞书、钉钉、企业微信或 Slack 上已有的故障作战室添加成员。",
         "tags": [
           "On-call/故障管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **故障管理**（`on-call`）或 **协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 需要 On-call Pro 许可。\n- `chat_id` 必须对应通过 Flashduty 在集成 `integration_id` 上创建的作战室，否则返回 `ResourceNotFound`。\n- 仅飞书、钉钉、企业微信和 Slack 集成支持作战室；其他集成返回 `InvalidParameter`。\n- `member_ids` 中的每个 ID 都必须是本账户的人员；任一 ID 无效则整个请求失败。\n- 成功时 `data` 为字符串 `ok`。",
           "href": "/zh/api-reference/on-call/incidents/incident-write-add-war-room-member",
           "metadata": {
             "sidebarTitle": "添加作战室成员"
@@ -14713,6 +15292,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -14728,11 +15310,11 @@
                 "$ref": "#/components/schemas/AddWarRoomMemberRequest"
               },
               "example": {
-                "integration_id": 362,
+                "integration_id": 2551105804131,
                 "chat_id": "oc_5ce6d572455d361153b7cb51da133945",
                 "member_ids": [
-                  20001,
-                  20002
+                  3790925372131,
+                  5068740052131
                 ]
               }
             }
@@ -14744,12 +15326,12 @@
       "post": {
         "operationId": "template-read-preview",
         "summary": "预览模板",
-        "description": "使用故障数据或模拟数据渲染通知模板并返回结果。",
+        "description": "用故障数据或模拟数据渲染模板，返回该通道实际会发送的内容。",
         "tags": [
           "On-call/通知模板"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **60 次/分钟**；**10 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- `incident_card_hidden_fields` 仅用于受支持的 IM 故障卡片预览；不支持的应用类型或字段名会返回 `InvalidParameter`。\n- 只有所选 IM 预览存在非空固定故障卡片值时，才会返回 `fixed_fields`。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **100 次/分钟**；**5 次/秒** |\n| 权限要求 | **模板查看**（`on-call`） 或 **模板管理**（`on-call`） |\n\n## 使用说明\n\n- 传 `incident_id` 时用该故障渲染（须为账户内存在的故障，否则返回 `InvalidParameter`），否则用模拟故障。`content` 为空时预览该通道的内置预设内容。\n- 模板错误不会返回 HTTP 错误：响应中 `success` 为 `false`，`message` 说明原因。\n- `card` 描述渲染结果外层的消息框架（邮件主题、IM 应用卡片的元素和按钮），仅 `email`、`feishu_app`、`dingtalk_app`、`wecom_app`、`slack_app`、`teams_app` 返回，其他类型省略。依赖集成的按钮（AI 分析、作战室）不会出现。\n- `incident_card_hidden_fields` 作用于 IM 应用卡片；不支持的应用类型或字段名返回 `InvalidParameter`。\n- 该接口不会发送消息，也不会保存任何内容。",
           "href": "/zh/api-reference/on-call/notification-templates/template-read-preview",
           "metadata": {
             "sidebarTitle": "预览模板"
@@ -14779,14 +15361,44 @@
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "success": true,
-                    "content": "Incident Database latency spike is Critical",
+                    "content": "**Database latency spike** is Critical",
                     "message": "",
-                    "fixed_fields": [
+                    "card": {
+                      "title": "Database latency spike",
+                      "elements": [
+                        {
+                          "type": "template"
+                        },
+                        {
+                          "type": "divider"
+                        },
+                        {
+                          "type": "actions",
+                          "actions": [
+                            {
+                              "text": "Acknowledge",
+                              "style": "primary"
+                            },
+                            {
+                              "text": "Resolve",
+                              "style": "danger"
+                            },
+                            {
+                              "text": "Snooze",
+                              "style": "select"
+                            }
+                          ]
+                        }
+                      ]
+                    },
+                    "blocks": [
                       {
-                        "field": "channel",
-                        "value": "Payment Alerts"
+                        "type": "markdown",
+                        "content": "**Database latency spike** is Critical"
                       }
-                    ]
+                    ],
+                    "size_bytes": 38,
+                    "size_limit_bytes": 30720
                   }
                 }
               }
@@ -14798,6 +15410,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -14813,7 +15428,7 @@
                 "$ref": "#/components/schemas/PreviewTemplateRequest"
               },
               "example": {
-                "content": "Incident {{.Title}} is {{.Status}}",
+                "content": "**{{.Title}}** is {{.IncidentSeverity}}",
                 "type": "feishu_app",
                 "incident_id": "664a1b2c3d4e5f6a7b8c9d0e",
                 "incident_card_hidden_fields": {
@@ -14836,7 +15451,7 @@
           "On-call/IM 集成"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间查看**（`on-call`） 或 **协作空间管理**（`on-call`） 或 **故障查看**（`on-call`） 或 **故障管理**（`on-call`） 或 **集成中心查看**（`on-call`） 或 **集成中心管理**（`on-call`） |\n\n## 使用说明\n\n- 返回设置中 `war_room_enabled` 为 `true` 的飞书、钉钉、企业微信、Slack 和 Microsoft Teams 集成（含已启用和已禁用），不含已删除的集成。\n- `settings` 中的密钥类字段会被掩码为 `******`。",
           "href": "/zh/api-reference/on-call/integrations/im-war-room-enabled-list",
           "metadata": {
             "sidebarTitle": "查看开启作战室功能的集成"
@@ -14874,7 +15489,7 @@
                         "name": "Feishu Ops",
                         "status": "enabled",
                         "category": "im",
-                        "plugin_type": "feishu",
+                        "plugin_type": "feishu_app",
                         "plugin_type_name": "Feishu",
                         "description": "Feishu war-room integration",
                         "integration_key": "ik_8f3a2b1c9d0e",
@@ -14903,6 +15518,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -14932,7 +15550,7 @@
           "On-call/状态页"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 一次返回全部公开页和内部页（不分页），按创建时间从新到旧排序。",
           "href": "/zh/api-reference/on-call/status-pages/status-page-read-page-list",
           "metadata": {
             "sidebarTitle": "查询状态页列表"
@@ -14963,38 +15581,37 @@
                   "data": {
                     "items": [
                       {
-                        "page_id": 7001,
-                        "name": "Acme Status",
-                        "url_name": "acme",
+                        "page_id": 5750613685214,
+                        "name": "Example Status",
+                        "url_name": "example-status",
                         "type": "public",
-                        "custom_domain": "status.acme.com",
-                        "logo_url": "https://acme.com",
-                        "page_header": "Acme System Status",
+                        "custom_domain": "status.example.com",
+                        "logo_url": "https://www.example.com",
+                        "page_header": "Example System Status",
                         "date_view": "calendar",
                         "display_uptime_mode": "chart_and_percentage",
                         "custom_links": [
                           {
-                            "name": "Home",
-                            "url": "https://acme.com"
+                            "key": "Home",
+                            "value": "https://www.example.com"
                           }
                         ],
-                        "contact_info": "mailto:support@acme.com",
+                        "contact_info": "mailto:support@example.com",
                         "components": [
                           {
-                            "component_id": "cmp_001",
-                            "section_id": "sec_001",
+                            "component_id": "01KC3GAZ6ZJE40H55GM31RPWZE",
+                            "section_id": "01KC3FKKX5TSVG6Z3X1QNGF6V2",
                             "name": "API",
                             "description": "Core API service",
                             "available_since_seconds": 1716962400,
-                            "order_id": 1,
-                            "hide_uptime": false,
-                            "hide_all": false
+                            "order_id": 1
                           }
                         ],
                         "sections": [
                           {
-                            "section_id": "sec_001",
+                            "section_id": "01KC3FKKX5TSVG6Z3X1QNGF6V2",
                             "name": "Core Services",
+                            "description": "",
                             "order_id": 1,
                             "hide_uptime": false,
                             "hide_all": false
@@ -15003,7 +15620,8 @@
                         "subscription": {
                           "email": true,
                           "im": false
-                        }
+                        },
+                        "template_preference": "message"
                       }
                     ]
                   }
@@ -15017,6 +15635,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -15035,7 +15656,7 @@
           "On-call/集成中心"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **集成中心管理**（`on-call`） |\n\n## 使用说明\n\n- 服务端使用成员邮箱和手机号在钉钉、飞书或企业微信中查找匹配用户。\n- 如果没有成员可关联，响应中的 `new_linked_person_ids` 可能为空数组，或整个 `data` 字段被省略。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **集成中心管理**（`on-call`） |\n\n## 使用说明\n\n- 按邮箱和手机号查找尚未关联到该集成 IM 应用的所有账户成员；仅支持飞书、钉钉和企业微信集成，其他类型返回 `InvalidParameter`。\n- 已禁用的集成返回 `InvalidParameter`。\n- 同一集成已有关联任务在运行时返回 `RequestLocked`；IM 平台拒绝查询（缺少通讯录权限或凭证被拒）时返回 `InvalidParameter`。\n- 没有成员被新关联时，`new_linked_person_ids` 为空数组。",
           "href": "/zh/api-reference/on-call/integrations/datasource-im-person-try-link",
           "metadata": {
             "sidebarTitle": "尝试关联 IM 人员"
@@ -15066,7 +15687,9 @@
                   "data": {
                     "new_linked_person_ids": [
                       5348648172131
-                    ]
+                    ],
+                    "unmatched_count": 2,
+                    "no_contact_count": 1
                   }
                 }
               }
@@ -15078,6 +15701,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -15109,7 +15735,7 @@
           "On-call/故障管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障管理**（`on-call`） |\n\n## 使用说明\n\n- 最多可将 10 个故障关联到同一份复盘报告。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 需要 On-call Pro 许可。\n- 报告 ID 由账户和排序后的 `incident_ids` 推导得出；用同一组故障再次调用会原样返回已有报告。\n- 任一故障已关联其他复盘时返回 `InvalidParameter`。\n- 团队、协作空间和私有设置取自首个加载到的故障所属的协作空间；不属于任何协作空间的故障无法创建复盘。\n- 标题为各故障标题以 `, ` 拼接（最多 512 个字符）；所有标题为空时使用模板名称。\n- 新报告状态为 `drafting`，正文为空；基本信息（严重程度、时间、处理人员）根据故障计算得出。\n- 这些故障中已转为后续行动但尚未绑定复盘的事项会绑定到该报告。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/on-call/incidents/postmortem-write-init",
           "metadata": {
             "sidebarTitle": "初始化故障复盘"
@@ -15140,41 +15766,44 @@
                   "data": {
                     "meta": {
                       "account_id": 2451002751131,
-                      "title": "Postmortem1",
-                      "status": "published",
-                      "post_mortem_id": "8104935102bf89dc01ac638a5261fe7e",
+                      "title": "Database connection timeout on prod-db-01",
+                      "status": "drafting",
+                      "post_mortem_id": "d3c9a7f2e5b14c8a9f0e6b2d4a1c7e35",
                       "template_id": "post_mortem_default_tmpl_en-us",
                       "incident_ids": [
                         "69bb9233331067560c718ecd"
                       ],
                       "media_count": 0,
                       "author_ids": [
-                        2477273692131
+                        3790925372131
                       ],
                       "team_id": 2477033058131,
-                      "channel_id": 3047621227131,
+                      "channel_id": 2551105804131,
                       "is_private": false,
+                      "generation": 0,
+                      "revision": 0,
                       "channel_name": "Ops Channel",
                       "created_at_seconds": 1773900354,
-                      "updated_at_seconds": 1773909012
+                      "updated_at_seconds": 1773900354
                     },
                     "basics": {
-                      "incidents_highest_severity": "Warning",
-                      "incidents_earliest_start_seconds": 1761133512,
-                      "incidents_latest_close_seconds": 1761133632,
-                      "incidents_total_duration_seconds": 120,
+                      "incidents_highest_severity": "Critical",
+                      "incidents_earliest_start_seconds": 1773890000,
+                      "incidents_latest_close_seconds": 1773897200,
+                      "incidents_total_duration_seconds": 7200,
                       "responders": [
                         {
                           "person_id": 3790925372131,
-                          "assigned_at": 1761133515,
-                          "acknowledged_at": 0
+                          "assigned_at": 1773890012,
+                          "acknowledged_at": 1773890100
                         }
                       ]
                     },
                     "content": {
-                      "content": "{\"type\":\"doc\",\"content\":[]}"
+                      "content": ""
                     },
-                    "follow_ups": ""
+                    "follow_ups": "",
+                    "has_active_incident": false
                   }
                 }
               }
@@ -15186,6 +15815,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -15215,12 +15847,12 @@
       "post": {
         "operationId": "postmortem-write-reset-basics",
         "summary": "更新故障复盘基础信息",
-        "description": "替换复盘报告中记录的故障基础信息。",
+        "description": "覆盖复盘报告中保存的故障基本信息（严重程度、时间、处理人员）。",
         "tags": [
           "On-call/故障管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障管理**（`on-call`） |\n\n## 使用说明\n\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 需要 On-call Pro 许可。\n- 调用方须为账户所有者或管理员，或是该报告所属团队的成员，否则返回 `AccessDenied`。\n- 整体覆盖：省略 `incidents_latest_close_seconds` 和 `incidents_total_duration_seconds` 时写为 0，省略 `responder_ids` 时清空处理人员。\n- `responder_ids` 中无法解析为人员的 ID 会被丢弃；保存的每个处理人员 `assigned_at` 为当前时间，`acknowledged_at` 为 0。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/on-call/incidents/postmortem-write-reset-basics",
           "metadata": {
             "sidebarTitle": "更新故障复盘基础信息"
@@ -15247,8 +15879,7 @@
                   ]
                 },
                 "example": {
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
-                  "data": {}
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
             }
@@ -15259,6 +15890,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -15274,11 +15908,11 @@
                 "$ref": "#/components/schemas/ResetPostMortemBasicsRequest"
               },
               "example": {
-                "post_mortem_id": "8104935102bf89dc01ac638a5261fe7e",
-                "incidents_highest_severity": "Warning",
-                "incidents_earliest_start_seconds": 1761133512,
-                "incidents_latest_close_seconds": 1761133632,
-                "incidents_total_duration_seconds": 120,
+                "post_mortem_id": "d3c9a7f2e5b14c8a9f0e6b2d4a1c7e35",
+                "incidents_highest_severity": "Critical",
+                "incidents_earliest_start_seconds": 1773890000,
+                "incidents_latest_close_seconds": 1773897200,
+                "incidents_total_duration_seconds": 7200,
                 "responder_ids": [
                   3790925372131
                 ]
@@ -15297,7 +15931,7 @@
           "On-call/故障管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 调用方须拥有目标复盘的编辑权限。 |\n\n## 使用说明\n\n- 仅草稿状态的报告可重置，且当前修订版本必须等于 `expected_revision`；否则返回 `409 Conflict`。\n- 同一 `idempotency_key` 只能重试相同的复盘、修订版本和 Markdown 正文；复用到不同请求会返回 `409 Conflict`。\n- 重置成功后旧的协作（Yjs）房间会被断开，客户端需切换到新 generation 的房间 `post-mortem-{accountId}-{postMortemId}-g{N}`（generation 0 无 `-g` 后缀）。重置不可回滚。\n- Markdown 正文最大为 4 MiB。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 需要 On-call Pro 许可。\n- 调用方须为账户所有者或管理员，或是该报告所属团队的成员，否则返回 `AccessDenied`。\n- 仅草稿状态的报告可重置，且当前修订版本必须等于 `expected_revision`；否则返回 `409 Conflict`。\n- 同一 `idempotency_key` 只能重试相同的复盘、修订版本和 Markdown 正文；复用到不同请求会返回 `409 Conflict`。\n- 同一报告的另一次重置仍在进行时返回 `RequestTooFrequently`，请稍后重试。\n- 重置成功后旧的协作（Yjs）房间会被断开，客户端需切换到新 generation 的房间 `post-mortem-{accountId}-{postMortemId}-g{N}`（generation 0 无 `-g` 后缀）。重置不可回滚。\n- Markdown 正文最大为 4 MiB。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/on-call/incidents/incident-post-mortem-write-reset-content",
           "metadata": {
             "sidebarTitle": "重置故障复盘正文"
@@ -15326,7 +15960,7 @@
                 "example": {
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
-                    "post_mortem_id": "8104935102bf89dc01ac638a5261fe7e",
+                    "post_mortem_id": "d3c9a7f2e5b14c8a9f0e6b2d4a1c7e35",
                     "generation": 2,
                     "revision": 12,
                     "previous_generation": 1,
@@ -15423,10 +16057,10 @@
                 "$ref": "#/components/schemas/ResetPostMortemContentRequest"
               },
               "example": {
-                "post_mortem_id": "8104935102bf89dc01ac638a5261fe7e",
+                "post_mortem_id": "d3c9a7f2e5b14c8a9f0e6b2d4a1c7e35",
                 "markdown": "# Database saturation incident\n\nThe database pool was exhausted; added saturation alert.",
                 "expected_revision": 11,
-                "idempotency_key": "postmortem-reset-8104935102-11"
+                "idempotency_key": "postmortem-reset-d3c9a7f2-11"
               }
             }
           }
@@ -15442,7 +16076,7 @@
           "On-call/故障管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障管理**（`on-call`） |\n\n## 使用说明\n\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 需要 On-call Pro 许可。\n- 调用方须为账户所有者或管理员，或是该报告所属团队的成员，否则返回 `AccessDenied`。\n- 状态可双向切换。只有 `drafting` 状态的报告可以调用 `POST /incident/post-mortem/content/reset`。\n- 发布时会删除报告正文中已不再引用的已上传媒体文件。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/on-call/incidents/postmortem-write-reset-status",
           "metadata": {
             "sidebarTitle": "更新故障复盘状态"
@@ -15469,8 +16103,7 @@
                   ]
                 },
                 "example": {
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
-                  "data": {}
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
             }
@@ -15481,6 +16114,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -15496,7 +16132,7 @@
                 "$ref": "#/components/schemas/ResetPostMortemStatusRequest"
               },
               "example": {
-                "post_mortem_id": "8104935102bf89dc01ac638a5261fe7e",
+                "post_mortem_id": "d3c9a7f2e5b14c8a9f0e6b2d4a1c7e35",
                 "status": "published"
               }
             }
@@ -15513,7 +16149,7 @@
           "On-call/故障管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障管理**（`on-call`） |\n\n## 使用说明\n\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 需要 On-call Pro 许可。\n- 调用方须为账户所有者或管理员，或是该报告所属团队的成员，否则返回 `AccessDenied`。\n- 调用方会被加入报告的 `author_ids`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/on-call/incidents/postmortem-write-reset-title",
           "metadata": {
             "sidebarTitle": "更新故障复盘标题"
@@ -15540,8 +16176,7 @@
                   ]
                 },
                 "example": {
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
-                  "data": {}
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
             }
@@ -15552,6 +16187,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -15567,7 +16205,7 @@
                 "$ref": "#/components/schemas/ResetPostMortemTitleRequest"
               },
               "example": {
-                "post_mortem_id": "8104935102bf89dc01ac638a5261fe7e",
+                "post_mortem_id": "d3c9a7f2e5b14c8a9f0e6b2d4a1c7e35",
                 "title": "Production API latency incident"
               }
             }
@@ -15579,12 +16217,12 @@
       "post": {
         "operationId": "postmortem-write-reset-follow-ups",
         "summary": "更新故障复盘后续行动",
-        "description": "替换复盘报告中的后续行动项。",
+        "description": "替换复盘报告中保存的后续行动文本。",
         "tags": [
           "On-call/故障管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障管理**（`on-call`） |\n\n## 使用说明\n\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 需要 On-call Pro 许可。\n- 调用方须为账户所有者或管理员，或是该报告所属团队的成员，否则返回 `AccessDenied`。\n- 任何报告状态下均可调用。省略 `follow_ups` 或传 `\"\"` 会清空该文本。\n- 当 `follow_ups` 是控制台后续行动格式的 JSON 数组时，其中的条目还会同步为结构化的后续行动事项（`source_kind` = `legacy_follow_up`）；其他文本不会改动结构化事项。\n- 如需管理单条后续行动，建议使用 `/incident/work-item/*` 系列接口。\n- 调用方会被加入报告的 `author_ids`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/on-call/incidents/postmortem-write-reset-follow-ups",
           "metadata": {
             "sidebarTitle": "更新故障复盘后续行动"
@@ -15611,8 +16249,7 @@
                   ]
                 },
                 "example": {
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
-                  "data": {}
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
             }
@@ -15623,6 +16260,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -15638,7 +16278,7 @@
                 "$ref": "#/components/schemas/ResetPostMortemFollowUpsRequest"
               },
               "example": {
-                "post_mortem_id": "8104935102bf89dc01ac638a5261fe7e",
+                "post_mortem_id": "d3c9a7f2e5b14c8a9f0e6b2d4a1c7e35",
                 "follow_ups": "- Add database saturation alert\n- Review cache TTL rollout"
               }
             }
@@ -15650,12 +16290,12 @@
       "post": {
         "operationId": "postmortem-write-upsert-template",
         "summary": "创建或更新故障复盘模板",
-        "description": "创建自定义复盘模板，或更新已有模板。",
+        "description": "创建自定义复盘模板，或按 `template_id` 替换已有模板。",
         "tags": [
           "On-call/故障管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障管理**（`on-call`） |\n\n## 使用说明\n\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 需要 On-call Pro 许可。\n- 省略 `template_id` 表示创建：`team_id` 必须是已存在的团队，模板 ID 由服务端生成。\n- 传 `template_id` 表示替换已有自定义模板；ID 不存在时返回 `ResourceNotFound`。更新需为账户所有者或管理员，或是模板所属团队的成员。\n- 所有文本字段整体替换：省略的 `description` 或 `content_markdown` 会变为空。更新时传 `team_id` 会把模板移到该团队；省略或传 0 则保持当前团队。\n- 内置模板（`post_mortem_default_tmpl_*`）不可修改。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/on-call/incidents/postmortem-write-upsert-template",
           "metadata": {
             "sidebarTitle": "创建或更新故障复盘模板"
@@ -15685,10 +16325,10 @@
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "account_id": 2451002751131,
-                    "template_id": "post_mortem_default_tmpl_en-us",
-                    "name": "Default post-mortem report",
-                    "description": "Default sections for post-mortem reports.",
-                    "content": "[{\"type\":\"heading\",\"content\":\"Summary\"}]",
+                    "template_id": "kQ3vXn8pR2mT7wYbZc4dEf",
+                    "name": "Production incident template",
+                    "description": "Template for production incident reviews.",
+                    "content": "[{\"type\":\"heading\",\"props\":{\"level\":2},\"content\":\"Summary\"}]",
                     "content_markdown": "## Summary\nDescribe what happened.",
                     "team_id": 2477033058131,
                     "created_at_seconds": 1773900000,
@@ -15704,6 +16344,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -15722,7 +16365,7 @@
                 "team_id": 2477033058131,
                 "name": "Production incident template",
                 "description": "Template for production incident reviews.",
-                "content": "[{\"type\":\"heading\",\"content\":\"Summary\"}]",
+                "content": "[{\"type\":\"heading\",\"props\":{\"level\":2},\"content\":\"Summary\"}]",
                 "content_markdown": "## Summary\nDescribe what happened."
               }
             }
@@ -15739,7 +16382,7 @@
           "On-call/故障管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障管理**（`on-call`） |\n\n## 使用说明\n\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 需要 On-call Pro 许可。\n- 内置模板（`post_mortem_default_tmpl_*`）不可删除；ID 不存在时返回 `ResourceNotFound`。\n- 需为账户所有者或管理员，或是模板所属团队的成员。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/on-call/incidents/postmortem-write-delete-template",
           "metadata": {
             "sidebarTitle": "删除故障复盘模板"
@@ -15766,8 +16409,7 @@
                   ]
                 },
                 "example": {
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
-                  "data": {}
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
             }
@@ -15778,6 +16420,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -15793,7 +16438,7 @@
                 "$ref": "#/components/schemas/DeletePostMortemTemplateRequest"
               },
               "example": {
-                "template_id": "post_mortem_custom_tmpl_01"
+                "template_id": "kQ3vXn8pR2mT7wYbZc4dEf"
               }
             }
           }
@@ -15804,12 +16449,12 @@
       "post": {
         "operationId": "postmortem-read-list-templates",
         "summary": "查询故障复盘模板列表",
-        "description": "返回账号下的内置和自定义故障复盘模板。",
+        "description": "返回内置复盘模板，以及账户的自定义模板。",
         "tags": [
           "On-call/故障管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障查看**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 需要 On-call Pro 许可。\n- 内置模板总是排在最前，并与请求语言对应：中文返回 `post_mortem_default_tmpl_zh-cn`，其他语言返回 `post_mortem_default_tmpl_en-us`。`total` 包含该内置模板。\n- 自定义模板按 `created_at_seconds` 排序，默认最新在前，`asc` 为 true 时升序。\n- 使用 `p` 和 `limit` 分页；`p` × `limit` 不得超过 10,000。\n- 内置模板的 `account_id`、`team_id` 及两个时间戳均为 0。",
           "href": "/zh/api-reference/on-call/incidents/postmortem-read-list-templates",
           "metadata": {
             "sidebarTitle": "查询故障复盘模板列表"
@@ -15842,11 +16487,22 @@
                     "has_next_page": false,
                     "items": [
                       {
-                        "account_id": 2451002751131,
+                        "account_id": 0,
                         "template_id": "post_mortem_default_tmpl_en-us",
-                        "name": "Default post-mortem report",
-                        "description": "Default sections for post-mortem reports.",
-                        "content": "[{\"type\":\"heading\",\"content\":\"Summary\"}]",
+                        "name": "Default Post Mortem Report Template",
+                        "description": "Standard post-mortem template with common sections",
+                        "content": "[{\"type\":\"heading\",\"props\":{\"level\":2},\"content\":\"Summary\"}]",
+                        "content_markdown": "## Summary\n> Provide a high-level description of the incident.",
+                        "team_id": 0,
+                        "created_at_seconds": 0,
+                        "updated_at_seconds": 0
+                      },
+                      {
+                        "account_id": 2451002751131,
+                        "template_id": "kQ3vXn8pR2mT7wYbZc4dEf",
+                        "name": "Production incident template",
+                        "description": "Template for production incident reviews.",
+                        "content": "[{\"type\":\"heading\",\"props\":{\"level\":2},\"content\":\"Summary\"}]",
                         "content_markdown": "## Summary\nDescribe what happened.",
                         "team_id": 2477033058131,
                         "created_at_seconds": 1773900000,
@@ -15864,6 +16520,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -15898,7 +16557,7 @@
           "On-call/故障管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障查看**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 需要 On-call Pro 许可。\n- 内置 ID `post_mortem_default_tmpl_zh-cn` 和 `post_mortem_default_tmpl_en-us` 不受请求语言限制均可查询；ID 不存在时返回 `ResourceNotFound`。",
           "href": "/zh/api-reference/on-call/incidents/postmortem-read-template-info",
           "metadata": {
             "sidebarTitle": "查看故障复盘模板详情"
@@ -15927,15 +16586,15 @@
                 "example": {
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
-                    "account_id": 2451002751131,
+                    "account_id": 0,
                     "template_id": "post_mortem_default_tmpl_en-us",
-                    "name": "Default post-mortem report",
-                    "description": "Default sections for post-mortem reports.",
-                    "content": "[{\"type\":\"heading\",\"content\":\"Summary\"}]",
-                    "content_markdown": "## Summary\nDescribe what happened.",
-                    "team_id": 2477033058131,
-                    "created_at_seconds": 1773900000,
-                    "updated_at_seconds": 1773903600
+                    "name": "Default Post Mortem Report Template",
+                    "description": "Standard post-mortem template with common sections",
+                    "content": "[{\"type\":\"heading\",\"props\":{\"level\":2},\"content\":\"Summary\"}]",
+                    "content_markdown": "## Summary\n> Provide a high-level description of the incident.",
+                    "team_id": 0,
+                    "created_at_seconds": 0,
+                    "updated_at_seconds": 0
                   }
                 }
               }
@@ -15947,6 +16606,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -15962,7 +16624,7 @@
             "schema": {
               "type": "string"
             },
-            "description": "Template ID."
+            "description": "模板 ID：内置 ID（如 `post_mortem_default_tmpl_en-us`）或从 `POST /incident/post-mortem/template/list` 获取的自定义模板 ID。"
           }
         ]
       }
@@ -16059,6 +16721,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -16084,12 +16749,12 @@
       "post": {
         "operationId": "statusPageCreate",
         "summary": "创建状态页",
-        "description": "创建一个新的状态页。",
+        "description": "为账户创建一个公开或内部状态页。",
         "tags": [
           "On-call/状态页"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **状态页面管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **状态页面管理**（`on-call`） |\n\n## 使用说明\n\n- 状态页数量受 On-call 套餐限制：公开页免费版和标准版 1 个、专业版 5 个；内部页仅专业版可用，最多 20 个。超出返回 `InvalidParameter`。\n- `url_name` 会被规范化为小写 slug，且在账户内同类型状态页中必须唯一；响应中的 `page_url_name` 为最终值。\n- 公开页只支持邮件订阅，且只有公开页可设置 `custom_domain`；内部页只支持 IM 订阅。\n- 每次调用都会记录到账户审计日志，请勿在请求字段中写入敏感信息。",
           "href": "/zh/api-reference/on-call/status-pages/status-page-create",
           "metadata": {
             "sidebarTitle": "创建状态页"
@@ -16132,6 +16797,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -16150,8 +16818,14 @@
                 "name": "My Status Page",
                 "url_name": "my-status-page",
                 "type": "public",
+                "date_view": "list",
+                "display_uptime_mode": "chart_and_percentage",
                 "page_header": "Welcome to our status page",
-                "contact_info": "mailto:support@example.com"
+                "contact_info": "mailto:support@example.com",
+                "subscription": {
+                  "email": true,
+                  "im": false
+                }
               }
             }
           }
@@ -16162,12 +16836,12 @@
       "post": {
         "operationId": "statusPageUpdate",
         "summary": "更新状态页",
-        "description": "更新已有状态页的配置。",
+        "description": "更新已有状态页的配置，未传的字段保持不变。",
         "tags": [
           "On-call/状态页"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **状态页面管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **状态页面管理**（`on-call`） |\n\n## 使用说明\n\n- 省略或传 `null` 的字段保持原值；传空字符串会清空该字符串字段。\n- `custom_links` 无法清空：省略或传空数组时保留当前链接。\n- 新的 `url_name` 会被规范化为 slug，且在账户内同类型状态页中必须唯一；内部页不能设置 `custom_domain`。\n- 每次调用都会记录到账户审计日志，请勿在请求字段中写入敏感信息。",
           "href": "/zh/api-reference/on-call/status-pages/status-page-update",
           "metadata": {
             "sidebarTitle": "更新状态页"
@@ -16206,6 +16880,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -16235,12 +16912,12 @@
       "post": {
         "operationId": "statusPageDelete",
         "summary": "删除状态页",
-        "description": "删除指定的状态页。",
+        "description": "删除状态页及其全部事件和订阅。",
         "tags": [
           "On-call/状态页"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **状态页面管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **状态页面管理**（`on-call`） |\n\n## 使用说明\n\n- 删除不存在的状态页也返回成功。\n- 状态页的事件和订阅会在接口返回后于后台删除。\n- 每次调用都会记录到账户审计日志，请勿在请求字段中写入敏感信息。",
           "href": "/zh/api-reference/on-call/status-pages/status-page-delete",
           "metadata": {
             "sidebarTitle": "删除状态页"
@@ -16279,6 +16956,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -16305,12 +16985,12 @@
       "post": {
         "operationId": "statusPageComponentUpsert",
         "summary": "创建或更新状态页组件",
-        "description": "在状态页上创建或更新服务组件。",
+        "description": "在状态页上批量创建或更新服务组件。",
         "tags": [
           "On-call/状态页"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **状态页面管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **状态页面管理**（`on-call`） |\n\n## 使用说明\n\n- 不带 `component_id` 的条目会创建组件；带 `component_id` 的条目更新对应组件。\n- 更新会用请求值覆盖 `name`、`description`、`section_id`、`order_id`、`hide_uptime` 和 `hide_all`，未传字段会被重置（不传 `section_id` 会把组件移到顶层）；更新时忽略 `available_since_seconds`。\n- 组件名称在状态页内必须唯一，`section_id` 必须是已有分组；任一条目无效则整个请求失败。\n- 每次调用都会记录到账户审计日志，请勿在请求字段中写入敏感信息。",
           "href": "/zh/api-reference/on-call/status-pages/status-page-component-upsert",
           "metadata": {
             "sidebarTitle": "创建或更新状态页组件"
@@ -16353,6 +17033,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -16387,12 +17070,12 @@
       "post": {
         "operationId": "statusPageComponentDelete",
         "summary": "删除状态页组件",
-        "description": "从状态页删除服务组件。",
+        "description": "从状态页批量删除服务组件。",
         "tags": [
           "On-call/状态页"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **状态页面管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **状态页面管理**（`on-call`） |\n\n## 使用说明\n\n- `component_ids` 中任一 ID 不存在于该状态页时，不会删除任何组件，但接口仍返回成功。\n- 订阅了被删除组件的订阅关系会被一并删除。\n- 每次调用都会记录到账户审计日志，请勿在请求字段中写入敏感信息。",
           "href": "/zh/api-reference/on-call/status-pages/status-page-component-delete",
           "metadata": {
             "sidebarTitle": "删除状态页组件"
@@ -16431,6 +17114,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -16460,12 +17146,12 @@
       "post": {
         "operationId": "statusPageSectionUpsert",
         "summary": "创建或更新状态页区域",
-        "description": "在状态页上创建或更新区域。",
+        "description": "在状态页上批量创建或更新用于组织组件的分组。",
         "tags": [
           "On-call/状态页"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **状态页面管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **状态页面管理**（`on-call`） |\n\n## 使用说明\n\n- 不带 `section_id` 的条目会创建分组；带 `section_id` 的条目更新对应分组。\n- 更新会用请求值覆盖 `name`、`description`、`order_id`、`hide_uptime` 和 `hide_all`，未传字段会被重置。\n- 分组名称在状态页内必须唯一；任一条目无效则整个请求失败。\n- 每次调用都会记录到账户审计日志，请勿在请求字段中写入敏感信息。",
           "href": "/zh/api-reference/on-call/status-pages/status-page-section-upsert",
           "metadata": {
             "sidebarTitle": "创建或更新状态页区域"
@@ -16508,6 +17194,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -16541,12 +17230,12 @@
       "post": {
         "operationId": "statusPageSectionDelete",
         "summary": "删除状态页区域",
-        "description": "从状态页删除区域。",
+        "description": "从状态页批量删除分组，分组内的组件会移到顶层。",
         "tags": [
           "On-call/状态页"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **状态页面管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **状态页面管理**（`on-call`） |\n\n## 使用说明\n\n- `section_ids` 中任一 ID 不存在于该状态页时，不会删除任何分组，但接口仍返回成功。\n- 被删除分组中的组件会保留并移到顶层。\n- 每次调用都会记录到账户审计日志，请勿在请求字段中写入敏感信息。",
           "href": "/zh/api-reference/on-call/status-pages/status-page-section-delete",
           "metadata": {
             "sidebarTitle": "删除状态页区域"
@@ -16585,6 +17274,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -16614,12 +17306,12 @@
       "post": {
         "operationId": "statusPageTemplateUpsert",
         "summary": "创建或更新状态页模板",
-        "description": "创建或更新状态页的事件模板。",
+        "description": "创建或更新状态页的完整状态更新模板或状态描述模板。",
         "tags": [
           "On-call/状态页"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **状态页面管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **状态页面管理**（`on-call`） |\n\n## 使用说明\n\n- 不传 `template.template_id` 时创建模板，传入时更新对应模板。`template_id` 不存在时返回 `InternalError`。\n- 更新时空字段保留原值。完整状态更新模板的 `type` 无法修改，状态描述模板的 `type` 可以修改。\n- 每次调用都会记录到账户审计日志，请勿在请求字段中写入敏感信息。",
           "href": "/zh/api-reference/on-call/status-pages/status-page-template-upsert",
           "metadata": {
             "sidebarTitle": "创建或更新状态页模板"
@@ -16660,6 +17352,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -16693,12 +17388,12 @@
       "post": {
         "operationId": "statusPageTemplateDelete",
         "summary": "删除状态页模板",
-        "description": "删除状态页的事件模板。",
+        "description": "删除状态页的一个完整状态更新模板或状态描述模板。",
         "tags": [
           "On-call/状态页"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **状态页面管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **状态页面管理**（`on-call`） |\n\n## 使用说明\n\n- 删除不存在的模板也返回成功。\n- 每次调用都会记录到账户审计日志，请勿在请求字段中写入敏感信息。",
           "href": "/zh/api-reference/on-call/status-pages/status-page-template-delete",
           "metadata": {
             "sidebarTitle": "删除状态页模板"
@@ -16737,6 +17432,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -16765,7 +17463,7 @@
       "get": {
         "operationId": "statusPageTemplateList",
         "summary": "查询状态页模板列表",
-        "description": "查询状态页的所有事件模板。",
+        "description": "查询状态页的完整状态更新模板或状态描述模板。",
         "tags": [
           "On-call/状态页"
         ],
@@ -16819,6 +17517,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -16922,6 +17623,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -16951,7 +17655,7 @@
           "On-call/故障管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障查看**（`on-call`） |\n\n## 使用说明\n\n- 一次调用返回完整列表，不分页。\n- 每个账户最多可创建 10 个评论类型。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障查看**（`on-call`）或 **评论类型管理**（`on-call`） |\n\n## 使用说明\n\n- 一次返回完整列表，不分页。\n- 每个账户最多可创建 10 个评论类型。",
           "href": "/zh/api-reference/on-call/incidents/incident-comment-type-list",
           "metadata": {
             "sidebarTitle": "查询评论类型列表"
@@ -17015,6 +17719,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -17044,7 +17751,7 @@
           "On-call/故障管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **评论类型管理**（`on-call`） |\n\n## 使用说明\n\n- 新类型追加到展示顺序的末尾。\n- 名称在账户内必须唯一（不区分大小写，忽略首尾空白）。\n- 每个账户最多可创建 10 个评论类型。\n- 该权限默认仅管理员拥有，自定义角色需显式授予。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **评论类型管理**（`on-call`） |\n\n## 使用说明\n\n- 新类型追加到展示顺序的末尾。\n- 名称在账户内必须唯一（不区分大小写，忽略首尾空白）。\n- 每个账户最多可创建 10 个评论类型。\n- 该权限默认仅管理员拥有，自定义角色需显式授予。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/on-call/incidents/incident-comment-type-create",
           "metadata": {
             "sidebarTitle": "创建评论类型"
@@ -17079,11 +17786,11 @@
                       "account_id": 2451002751131,
                       "name": "Key finding",
                       "color": "#30A46C",
-                      "position": 1,
+                      "position": 3,
                       "creator_id": 5068740052131,
                       "updated_by": 5068740052131,
                       "created_at": 1784190422,
-                      "updated_at": 1784207748
+                      "updated_at": 1784190422
                     }
                   }
                 }
@@ -17096,6 +17803,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -17128,7 +17838,7 @@
           "On-call/故障管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **评论类型管理**（`on-call`） |\n\n## 使用说明\n\n- 部分更新 —— 仅修改提供的字段，但 `name` 和 `color` 至少提供一个。\n- 名称在账户内必须保持唯一（不区分大小写，忽略首尾空白）。\n- 该权限默认仅管理员拥有，自定义角色需显式授予。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **评论类型管理**（`on-call`） |\n\n## 使用说明\n\n- 部分更新 —— 只修改提供的字段，但 `name` 和 `color` 至少要提供一个。\n- 名称在账户内必须保持唯一（不区分大小写，忽略首尾空白）。\n- 该权限默认仅管理员拥有，自定义角色需显式授予。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/on-call/incidents/incident-comment-type-update",
           "metadata": {
             "sidebarTitle": "更新评论类型"
@@ -17167,6 +17877,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -17194,12 +17907,12 @@
       "post": {
         "operationId": "incidentCommentTypeDelete",
         "summary": "删除评论类型",
-        "description": "删除评论类型。已使用该类型的评论保留文本内容，但不再显示类型标签。",
+        "description": "永久删除评论类型；使用过它的评论保留内容，但不再显示该类型标签。",
         "tags": [
           "On-call/故障管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **评论类型管理**（`on-call`） |\n\n## 使用说明\n\n- 硬删除 —— 评论类型被永久移除，无法恢复。\n- 已引用该类型的评论会失去类型标签，其他内容不受影响。\n- 该权限默认仅管理员拥有，自定义角色需显式授予。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **评论类型管理**（`on-call`） |\n\n## 使用说明\n\n- 硬删除 —— 评论类型被永久移除，无法恢复。\n- 引用该类型的已有评论会失去类型标签，其他内容不受影响。\n- 该权限默认仅管理员拥有，自定义角色需显式授予。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/on-call/incidents/incident-comment-type-delete",
           "metadata": {
             "sidebarTitle": "删除评论类型"
@@ -17238,6 +17951,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -17269,7 +17985,7 @@
           "On-call/故障管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **评论类型管理**（`on-call`） |\n\n## 使用说明\n\n- 全量排序 —— `comment_type_ids` 必须包含账户的全部评论类型，每个恰好出现一次，按期望顺序排列。\n- 展示位置从 1 开始重新分配：数组中的第一个 ID 即为位置 1。\n- 该权限默认仅管理员拥有，自定义角色需显式授予。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **评论类型管理**（`on-call`） |\n\n## 使用说明\n\n- 全量排序 —— `comment_type_ids` 必须包含账户的全部评论类型，每个恰好出现一次，按期望顺序排列。\n- 位置从 1 开始重新分配：数组中的第一个 ID 位置为 1。\n- 该权限默认仅管理员拥有，自定义角色需显式授予。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/on-call/incidents/incident-comment-type-reorder",
           "metadata": {
             "sidebarTitle": "调整评论类型顺序"
@@ -17308,6 +18024,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -17337,12 +18056,12 @@
       "post": {
         "operationId": "incidentWorkItemList",
         "summary": "查询跟进事项列表",
-        "description": "查询故障跟进事项（行动项与复盘后续行动），使用游标分页。",
+        "description": "以游标分页列出故障的跟进事项（行动项和复盘后续行动）。",
         "tags": [
           "On-call/故障管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障查看**（`on-call`） |\n\n## 使用说明\n\n- `incident_id`、`post_mortem_id`、`assignee_id`，或 `assignee_type` 为 `ai_sre`，至少满足一个。\n- `assignee_type` 为 `ai_sre` 时返回指派给 AI SRE 的事项，可单独作为查询条件。\n- 按 `updated_at_seconds` 倒序的游标分页 —— 将上一次响应的 `next_cursor` 作为 `cursor` 传入，直到 `has_more` 为 false。\n- 按 `incident_id` 查询时，同时包含锚定在该故障复盘上的后续行动。\n- 仅按 `assignee_id` 查询时，须为本人或账户管理员。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- `incident_id`、`post_mortem_id`、`assignee_id` 或 `assignee_type` = `ai_sre` 至少提供一个。\n- 按 `incident_id` 或 `post_mortem_id` 过滤时，须有该故障或复盘的查看权限；按 `incident_id` 查询时，若调用方可查看该故障的复盘，也会返回绑定到该复盘的后续行动。\n- 仅按 `assignee_id` 查询时，调用方须为该成员本人，或账户所有者、管理员。未指定 `incident_id` 和 `post_mortem_id` 时，非所有者或管理员只能看到其有权查看的故障或复盘下的事项。\n- 按 `updated_at_seconds` 降序排列。将上一次响应中的 `next_cursor` 作为 `cursor` 传入，直到 `has_more` 为 false。",
           "href": "/zh/api-reference/on-call/incidents/incident-work-item-list",
           "metadata": {
             "sidebarTitle": "查询跟进事项列表"
@@ -17377,17 +18096,29 @@
                         "item_type": "follow_up",
                         "incident_id": "6a5f1e28807515413b384bce",
                         "post_mortem_id": "51d65cd9525c369379ba471b5512df63",
-                        "title": "Follow-ups assigned to Bowen and Weili",
+                        "title": "Add a saturation alert for the orders database pool",
                         "status": "done",
+                        "priority": "medium",
                         "source_kind": "native",
-                        "version": 2,
+                        "version": 3,
                         "assignee_ids": [
                           3790925372131,
-                          4756301322131,
                           5068740052131
                         ],
-                        "created_by": 5329873302131,
+                        "assignees": [
+                          {
+                            "type": "person",
+                            "id": 3790925372131
+                          },
+                          {
+                            "type": "person",
+                            "id": 5068740052131
+                          }
+                        ],
+                        "created_by": 4756301322131,
                         "updated_by": 3790925372131,
+                        "converted_by": 4756301322131,
+                        "converted_at_seconds": 1785495900,
                         "created_at_seconds": 1785495329,
                         "updated_at_seconds": 1785496384
                       },
@@ -17396,20 +18127,29 @@
                         "item_type": "follow_up",
                         "incident_id": "6a5f1e28807515413b384bce",
                         "post_mortem_id": "51d65cd9525c369379ba471b5512df63",
-                        "title": "Check whether this to-do notifies Bowen",
+                        "title": "Document the cache TTL rollback procedure",
                         "status": "open",
+                        "priority": "low",
                         "source_kind": "native",
-                        "version": 1,
+                        "version": 2,
                         "assignee_ids": [
                           5068740052131
                         ],
+                        "assignees": [
+                          {
+                            "type": "person",
+                            "id": 5068740052131
+                          }
+                        ],
                         "created_by": 3790925372131,
                         "updated_by": 3790925372131,
+                        "converted_by": 3790925372131,
+                        "converted_at_seconds": 1785495200,
                         "created_at_seconds": 1785495164,
-                        "updated_at_seconds": 1785495164
+                        "updated_at_seconds": 1785495200
                       }
                     ],
-                    "next_cursor": "MTc4NTQ5NTE2NHx3aV9kTVJZVGVaSGl2RTV2Zjg3UFFFZUZY",
+                    "next_cursor": "MTc4NTQ5NTIwMHx3aV9kTVJZVGVaSGl2RTV2Zjg3UFFFZUZY",
                     "has_more": true
                   }
                 }
@@ -17422,6 +18162,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -17438,7 +18181,7 @@
               },
               "example": {
                 "incident_id": "6a5f1e28807515413b384bce",
-                "limit": 50
+                "limit": 2
               }
             }
           }
@@ -17449,12 +18192,12 @@
       "post": {
         "operationId": "incidentWorkItemCreate",
         "summary": "创建跟进事项",
-        "description": "在活动故障上创建行动项，或在其故障复盘上创建后续行动。",
+        "description": "在未关闭的故障上创建行动项，或在已关闭的故障上创建后续行动。",
         "tags": [
           "On-call/故障管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障管理**（`on-call`） |\n\n## 使用说明\n\n- 需要 On-call Pro 许可。\n- `action` 锚定活动故障，且不得设置 `post_mortem_id`；`follow_up` 必须设置为关联到 `incident_id` 的故障复盘 ID。\n- 使用 `assignees`（`person` 带 `id`，或 `ai_sre` 不带 `id`），或使用旧版 `assignee_ids`（全部为 `person`）。两者同时出现会报错。\n- 人员负责人须为已能查看锚定故障或复盘的活跃成员 —— 指派不会授予访问权限。\n- 新添加的负责人会收到通知。\n- 以相同的（`creator`、`idempotency_key`）重试时，返回原事项并标记 `idempotent_replay: true`，不会创建重复事项。\n- 已审计 —— 变更会记录到审计日志。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 需要 On-call Pro 许可。\n- `action`：故障不能已关闭，调用方须有该故障的编辑权限，且不得设置 `post_mortem_id`。\n- `follow_up`：故障必须已关闭。传 `post_mortem_id` 时，调用方须有该复盘的编辑权限，且故障须已关联到该复盘；不传时，调用方须有故障的编辑权限，若故障已有复盘则服务端自动绑定，否则事项保持未绑定，直到创建复盘。\n- `assignees`（每项为 `{type, id?}`，`type` 取 `person` 或 `ai_sre`，`ai_sre` 不带 `id`）与旧版 `assignee_ids`（全部为 `person`）二选一，同时传入会报错。\n- 人员负责人须为已能查看该故障或复盘的活跃成员 —— 指派不会授予访问权限。\n- 新添加的人员负责人会收到通知；指派 `ai_sre` 会启动一个 AI SRE 会话来处理该事项。\n- 同一调用方用相同 `idempotency_key` 重试时，返回原事项并标记 `idempotent_replay: true`；若原事项已被删除，返回 `RequestLocked`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/on-call/incidents/incident-work-item-create",
           "metadata": {
             "sidebarTitle": "创建跟进事项"
@@ -17488,12 +18231,20 @@
                       "item_type": "action",
                       "incident_id": "6a5f1e28807515413b384bce",
                       "title": "Roll back the v2.14 deployment on web-server-01",
+                      "description": "CPU saturation started right after the v2.14 rollout; roll back and watch the error rate.",
                       "status": "open",
+                      "priority": "high",
                       "source_kind": "native",
                       "version": 1,
                       "assignee_ids": [
                         3790925372131
                       ],
+                      "assignees": [
+                        {
+                          "type": "person",
+                          "id": 3790925372131
+                        }
+                      ],
                       "created_by": 3790925372131,
                       "updated_by": 3790925372131,
                       "created_at_seconds": 1785496400,
@@ -17513,6 +18264,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -17553,7 +18307,7 @@
           "On-call/故障管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障管理**（`on-call`） |\n\n## 使用说明\n\n- 需要 On-call Pro 许可。\n- 部分更新：未提供的字段保持不变；显式传 `null` 则清空该字段。\n- 乐观锁 —— `version` 必须与事项当前版本一致；不一致返回冲突错误。\n- 负责人、`item_type` 以及故障/复盘锚点不能在此修改 —— 请使用专用接口。\n- 已审计 —— 变更会记录到审计日志。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 需要 On-call Pro 许可。\n- 部分更新：未提供的字段以及传 `null` 的字段均保持不变。传 `\"\"` 可清空 `description` 或 `priority`；`title` 和 `status` 不能为空。\n- 乐观锁 —— `version` 必须等于事项当前版本；不一致时返回 `RequestLocked`（HTTP 423），请重新读取事项后重试。\n- 若没有任何字段发生变化，则直接返回当前事项，不校验也不递增 `version`。\n- 调用方须拥有事项锚点的编辑权限：已绑定复盘时为该复盘，否则为故障。\n- `follow_up` 事项仅在其故障已关闭时可修改。\n- 负责人、`item_type` 以及故障/复盘锚点不能在此修改 —— 请使用专用接口。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/on-call/incidents/incident-work-item-update",
           "metadata": {
             "sidebarTitle": "更新跟进事项"
@@ -17583,23 +18337,28 @@
                   "request_id": "01J8XQ3E5Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "item": {
-                      "work_item_id": "wi_68MHnkWBiyjrh6uhkxUyiZ",
-                      "item_type": "follow_up",
+                      "work_item_id": "wi_9fK2mNqRtVwXyZaBcDeFgH",
+                      "item_type": "action",
                       "incident_id": "6a5f1e28807515413b384bce",
-                      "post_mortem_id": "51d65cd9525c369379ba471b5512df63",
-                      "title": "Follow-ups assigned to Bowen and Weili",
-                      "status": "done",
+                      "title": "Roll back the v2.14 deployment on web-server-01 and web-server-02",
+                      "description": "CPU saturation started right after the v2.14 rollout; roll back and watch the error rate.",
+                      "status": "in_progress",
+                      "priority": "high",
                       "source_kind": "native",
                       "version": 2,
                       "assignee_ids": [
-                        3790925372131,
-                        4756301322131,
-                        5068740052131
+                        3790925372131
+                      ],
+                      "assignees": [
+                        {
+                          "type": "person",
+                          "id": 3790925372131
+                        }
                       ],
-                      "created_by": 5329873302131,
+                      "created_by": 3790925372131,
                       "updated_by": 3790925372131,
-                      "created_at_seconds": 1785495329,
-                      "updated_at_seconds": 1785496384
+                      "created_at_seconds": 1785496400,
+                      "updated_at_seconds": 1785496700
                     }
                   }
                 }
@@ -17612,6 +18371,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -17641,12 +18403,12 @@
       "post": {
         "operationId": "incidentWorkItemDelete",
         "summary": "删除跟进事项",
-        "description": "软删除跟进事项。",
+        "description": "软删除跟进事项，使其不再出现在事项列表中。",
         "tags": [
           "On-call/故障管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障管理**（`on-call`） |\n\n## 使用说明\n\n- 需要 On-call Pro 许可。\n- 软删除 —— 事项不再出现在列表中，但数据仍保留。\n- 乐观锁 —— `version` 必须与事项当前版本一致；不一致返回冲突错误。\n- 已审计 —— 变更会记录到审计日志。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 需要 On-call Pro 许可。\n- 软删除 —— 事项不再出现在列表中，但数据会保留；其创建时使用的 `idempotency_key` 不能再复用。\n- 乐观锁 —— `version` 必须等于事项当前版本；不一致时返回 `RequestLocked`（HTTP 423），请重新读取事项后重试。\n- 调用方须拥有事项锚点的编辑权限：已绑定复盘时为该复盘，否则为故障。\n- `follow_up` 事项仅在其故障已关闭时可修改。\n- 成功时 `data` 为空对象。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/on-call/incidents/incident-work-item-delete",
           "metadata": {
             "sidebarTitle": "删除跟进事项"
@@ -17685,6 +18447,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -17701,7 +18466,7 @@
               },
               "example": {
                 "work_item_id": "wi_9fK2mNqRtVwXyZaBcDeFgH",
-                "version": 2
+                "version": 3
               }
             }
           }
@@ -17712,12 +18477,12 @@
       "post": {
         "operationId": "incidentWorkItemComplete",
         "summary": "完成跟进事项",
-        "description": "通过设置客户端自定义的目标状态，将跟进事项标记为完成。",
+        "description": "将跟进事项标记为已完成；仅当前负责人可以操作。",
         "tags": [
           "On-call/故障管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障管理**（`on-call`） |\n\n## 使用说明\n\n- 需要 On-call Pro 许可。\n- 仅当前负责人可以完成跟进事项。\n- `target_status` 为客户端自定义字符串 —— 没有固定状态机。\n- 相同 `idempotency_key` 搭配相同 `target_status` 会幂等重放；相同键搭配不同 `target_status` 将返回错误。\n- 已审计 —— 变更会记录到审计日志。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 需要 On-call Pro 许可。\n- `target_status` 必须为 `done`。\n- 仅当前人员负责人可以完成事项（账户所有者和管理员不会被视为负责人）；指派给 AI SRE 的事项也可由处理它的 AI SRE 会话完成。调用方还须有该故障或复盘的查看权限。\n- `follow_up` 事项仅在其故障已关闭时可修改。\n- 用相同的 `idempotency_key` 重复调用会返回该事项并标记 `idempotent_replay: true`。\n- 乐观锁 —— `version` 必须等于事项当前版本；不一致时返回 `RequestLocked`（HTTP 423），请重新读取事项后重试。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/on-call/incidents/incident-work-item-complete",
           "metadata": {
             "sidebarTitle": "完成跟进事项"
@@ -17747,23 +18512,28 @@
                   "request_id": "01J8XQ3E5Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "item": {
-                      "work_item_id": "wi_68MHnkWBiyjrh6uhkxUyiZ",
-                      "item_type": "follow_up",
+                      "work_item_id": "wi_9fK2mNqRtVwXyZaBcDeFgH",
+                      "item_type": "action",
                       "incident_id": "6a5f1e28807515413b384bce",
-                      "post_mortem_id": "51d65cd9525c369379ba471b5512df63",
-                      "title": "Follow-ups assigned to Bowen and Weili",
+                      "title": "Roll back the v2.14 deployment on web-server-01 and web-server-02",
+                      "description": "CPU saturation started right after the v2.14 rollout; roll back and watch the error rate.",
                       "status": "done",
+                      "priority": "high",
                       "source_kind": "native",
-                      "version": 2,
+                      "version": 3,
                       "assignee_ids": [
-                        3790925372131,
-                        4756301322131,
-                        5068740052131
+                        3790925372131
                       ],
-                      "created_by": 5329873302131,
+                      "assignees": [
+                        {
+                          "type": "person",
+                          "id": 3790925372131
+                        }
+                      ],
+                      "created_by": 3790925372131,
                       "updated_by": 3790925372131,
-                      "created_at_seconds": 1785495329,
-                      "updated_at_seconds": 1785496384
+                      "created_at_seconds": 1785496400,
+                      "updated_at_seconds": 1785497600
                     }
                   }
                 }
@@ -17776,6 +18546,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -17810,7 +18583,7 @@
           "On-call/故障管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障管理**（`on-call`） |\n\n## 使用说明\n\n- 需要 On-call Pro 许可。\n- 将 `action` 事项原地转化为复盘 `follow_up` —— `work_item_id` 不变。\n- 转化已是 `follow_up` 的事项时返回 `idempotent_replay: true`。\n- 如果故障已存在复盘，转化后的事项会自动绑定到该复盘。\n- 已审计 —— 变更会记录到审计日志。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 需要 On-call Pro 许可。\n- 将 `action` 就地转为复盘 `follow_up` —— `work_item_id` 不变。\n- 对已是 `follow_up` 的事项调用不会做任何修改，并返回 `idempotent_replay: true`。\n- 若故障已有复盘，事项会绑定到该复盘，此时需要该复盘的编辑权限；否则可稍后通过 `POST /incident/work-item/post-mortem/bind` 绑定。\n- 调用方须拥有事项锚点的编辑权限：已绑定复盘时为该复盘，否则为故障。\n- 乐观锁 —— `version` 必须等于事项当前版本；不一致时返回 `RequestLocked`（HTTP 423），请重新读取事项后重试。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/on-call/incidents/incident-work-item-convert",
           "metadata": {
             "sidebarTitle": "转化跟进事项为复盘后续行动"
@@ -17840,23 +18613,31 @@
                   "request_id": "01J8XQ3E5Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "item": {
-                      "work_item_id": "wi_68MHnkWBiyjrh6uhkxUyiZ",
+                      "work_item_id": "wi_9fK2mNqRtVwXyZaBcDeFgH",
                       "item_type": "follow_up",
                       "incident_id": "6a5f1e28807515413b384bce",
                       "post_mortem_id": "51d65cd9525c369379ba471b5512df63",
-                      "title": "Follow-ups assigned to Bowen and Weili",
-                      "status": "done",
+                      "title": "Roll back the v2.14 deployment on web-server-01 and web-server-02",
+                      "description": "CPU saturation started right after the v2.14 rollout; roll back and watch the error rate.",
+                      "status": "open",
+                      "priority": "high",
                       "source_kind": "native",
-                      "version": 2,
+                      "version": 3,
                       "assignee_ids": [
-                        3790925372131,
-                        4756301322131,
-                        5068740052131
+                        3790925372131
+                      ],
+                      "assignees": [
+                        {
+                          "type": "person",
+                          "id": 3790925372131
+                        }
                       ],
-                      "created_by": 5329873302131,
+                      "created_by": 3790925372131,
                       "updated_by": 3790925372131,
-                      "created_at_seconds": 1785495329,
-                      "updated_at_seconds": 1785496384
+                      "converted_by": 3790925372131,
+                      "converted_at_seconds": 1785497600,
+                      "created_at_seconds": 1785496400,
+                      "updated_at_seconds": 1785497600
                     }
                   }
                 }
@@ -17869,6 +18650,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -17903,7 +18687,7 @@
           "On-call/故障管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障管理**（`on-call`） |\n\n## 使用说明\n\n- 需要 On-call Pro 许可。\n- 整体替换负责人集合 —— 空数组表示清空所有负责人。\n- 使用 `assignees` 或旧版 `assignee_ids`。两者同时出现会报错。`ai_sre` 条目不带 `id`。\n- 仅新添加的负责人会收到通知；移除不通知。\n- 已审计 —— 变更会记录到审计日志。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 需要 On-call Pro 许可。\n- 整体替换负责人集合。传 `assignees` 或旧版 `assignee_ids`（二选一）；两者都不传会报错，传 `[]` 或 `null` 会清空所有负责人。\n- 人员负责人须为已能查看该故障或复盘的活跃成员 —— 指派不会授予访问权限。\n- 仅新添加的人员负责人会收到通知，移除不会通知。新指派 `ai_sre` 会为该事项启动一个 AI SRE 会话。\n- 负责人集合未发生变化时，`version` 不会递增。\n- 乐观锁 —— `version` 必须等于事项当前版本；不一致时返回 `RequestLocked`（HTTP 423），请重新读取事项后重试。\n- 调用方须拥有事项锚点的编辑权限：已绑定复盘时为该复盘，否则为故障。\n- `follow_up` 事项仅在其故障已关闭时可修改。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/on-call/incidents/incident-work-item-reset-assignees",
           "metadata": {
             "sidebarTitle": "重置跟进事项负责人"
@@ -17933,29 +18717,36 @@
                   "request_id": "01J8XQ3E5Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "item": {
-                      "work_item_id": "wi_68MHnkWBiyjrh6uhkxUyiZ",
-                      "item_type": "follow_up",
+                      "work_item_id": "wi_9fK2mNqRtVwXyZaBcDeFgH",
+                      "item_type": "action",
                       "incident_id": "6a5f1e28807515413b384bce",
-                      "post_mortem_id": "51d65cd9525c369379ba471b5512df63",
-                      "title": "Follow-ups assigned to Bowen and Weili",
-                      "status": "done",
+                      "title": "Roll back the v2.14 deployment on web-server-01 and web-server-02",
+                      "description": "CPU saturation started right after the v2.14 rollout; roll back and watch the error rate.",
+                      "status": "in_progress",
+                      "priority": "high",
                       "source_kind": "native",
-                      "version": 2,
+                      "version": 3,
                       "assignee_ids": [
                         3790925372131,
-                        4756301322131,
                         5068740052131
                       ],
-                      "created_by": 5329873302131,
+                      "assignees": [
+                        {
+                          "type": "person",
+                          "id": 3790925372131
+                        },
+                        {
+                          "type": "person",
+                          "id": 5068740052131
+                        }
+                      ],
+                      "created_by": 3790925372131,
                       "updated_by": 3790925372131,
-                      "created_at_seconds": 1785495329,
-                      "updated_at_seconds": 1785496384
+                      "created_at_seconds": 1785496400,
+                      "updated_at_seconds": 1785497000
                     },
                     "added_assignee_ids": [
                       5068740052131
-                    ],
-                    "removed_assignee_ids": [
-                      4756301322131
                     ]
                   }
                 }
@@ -17968,6 +18759,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -18004,7 +18798,7 @@
           "On-call/故障管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障管理**（`on-call`） |\n\n## 使用说明\n\n- 需要 On-call Pro 许可。\n- 一次调用将该故障全部已转化但未绑定的后续行动绑定到指定复盘。\n- `items` 为本次新绑定的批次；不设置 `next_cursor` 和 `has_more`。\n- 通过 `idempotency_key` 幂等 —— 以相同键重试时重放原始结果。\n- 已审计 —— 变更会记录到审计日志。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 需要 On-call Pro 许可。\n- 绑定该故障中所有由行动项转换而来、且尚未绑定任何复盘的事项。\n- 调用方须有该复盘的编辑权限，且 `incident_id` 必须已关联到该复盘。\n- `items` 为本次绑定的事项，可能为空；`next_cursor` 不返回，`has_more` 为 false。\n- 用相同的 `idempotency_key` 重试时，返回之前绑定的事项并标记 `idempotent_replay: true`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/on-call/incidents/incident-work-item-bind-post-mortem",
           "metadata": {
             "sidebarTitle": "绑定跟进事项到复盘"
@@ -18039,17 +18833,29 @@
                         "item_type": "follow_up",
                         "incident_id": "6a5f1e28807515413b384bce",
                         "post_mortem_id": "51d65cd9525c369379ba471b5512df63",
-                        "title": "Follow-ups assigned to Bowen and Weili",
+                        "title": "Add a saturation alert for the orders database pool",
                         "status": "done",
+                        "priority": "medium",
                         "source_kind": "native",
-                        "version": 2,
+                        "version": 3,
                         "assignee_ids": [
                           3790925372131,
-                          4756301322131,
                           5068740052131
                         ],
-                        "created_by": 5329873302131,
+                        "assignees": [
+                          {
+                            "type": "person",
+                            "id": 3790925372131
+                          },
+                          {
+                            "type": "person",
+                            "id": 5068740052131
+                          }
+                        ],
+                        "created_by": 4756301322131,
                         "updated_by": 3790925372131,
+                        "converted_by": 4756301322131,
+                        "converted_at_seconds": 1785495900,
                         "created_at_seconds": 1785495329,
                         "updated_at_seconds": 1785496384
                       },
@@ -18058,17 +18864,26 @@
                         "item_type": "follow_up",
                         "incident_id": "6a5f1e28807515413b384bce",
                         "post_mortem_id": "51d65cd9525c369379ba471b5512df63",
-                        "title": "Check whether this to-do notifies Bowen",
+                        "title": "Document the cache TTL rollback procedure",
                         "status": "open",
+                        "priority": "low",
                         "source_kind": "native",
-                        "version": 1,
+                        "version": 2,
                         "assignee_ids": [
                           5068740052131
                         ],
+                        "assignees": [
+                          {
+                            "type": "person",
+                            "id": 5068740052131
+                          }
+                        ],
                         "created_by": 3790925372131,
                         "updated_by": 3790925372131,
+                        "converted_by": 3790925372131,
+                        "converted_at_seconds": 1785495200,
                         "created_at_seconds": 1785495164,
-                        "updated_at_seconds": 1785495164
+                        "updated_at_seconds": 1785495200
                       }
                     ],
                     "has_more": false
@@ -18083,6 +18898,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -18116,7 +18934,7 @@
           "On-call/值班排班"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **值班查看**（`on-call`） 或 **值班管理**（`on-call`） |\n\n## 使用说明\n\n- `current` 为正在值班的班次（含真实开始时间）；`next` 为下一次值班，查询窗口内没有排班时缺省。\n- 已禁用的排班不会出现在列表中。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- `current` 是正在进行的班次（含真实开始时间）；成员同时在多个值班表中值班时，返回结束最晚的那个。`next` 是最早的下一次值班。在当前时刻前后 45 天内找不到时为 `null`。\n- `schedules` 列出成员至少出现在一个未结束分层中的已启用值班表。已禁用的值班表不会列出，也不参与 `current`/`next` 的计算。\n- 可以查询账户内任意成员；`person_id` 可从成员列表获取。",
           "href": "/zh/api-reference/on-call/schedules/schedule-by-person",
           "metadata": {
             "sidebarTitle": "查看成员值班状态"
@@ -18154,8 +18972,7 @@
                     "next": {
                       "schedule_id": 2539108069860,
                       "schedule_name": "Open Source Q&A",
-                      "start_at": 1773532800,
-                      "end_at": 1773619199
+                      "start_at": 1773532800
                     },
                     "schedules": [
                       {
@@ -18174,6 +18991,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -18203,7 +19023,7 @@
         "type": "apiKey",
         "in": "query",
         "name": "app_key",
-        "description": "在 Flashduty 控制台 账户 → APP Key 中签发的 app_key。调用任何公开 API 时都必须携带。它等同于所属账户的身份凭证，请妥善保管。"
+        "description": "在 Flashduty 控制台 我的 → APP Key 中创建的 APP Key。可通过 query 参数 `app_key` 或请求头 `Fd-App-Key` 传入。实际可访问范围是该 APP Key 的权限范围与创建者当前角色权限的交集，请妥善保管。"
       }
     },
     "responses": {
@@ -18250,7 +19070,7 @@
         }
       },
       "Forbidden": {
-        "description": "app_key 有效但没有执行该操作的权限。",
+        "description": "app_key 有效，但其权限范围或创建者角色不允许该操作或该对象。",
         "content": {
           "application/json": {
             "schema": {
@@ -18292,7 +19112,7 @@
         }
       },
       "TooManyRequests": {
-        "description": "命中限流。可能是全局 API 限流、账户级限流或集成级限流。限流按账户聚合。",
+        "description": "触发频率限制（账户级限制或该接口的平台级上限）。请等待响应头 `Flashcat-Request-Rate-Limit-Delay` 给出的秒数后重试。",
         "content": {
           "application/json": {
             "schema": {
@@ -18310,6 +19130,15 @@
               }
             }
           }
+        },
+        "headers": {
+          "Flashcat-Request-Rate-Limit-Delay": {
+            "description": "距当前限流窗口重置的秒数。请求被网关全局保护限流拒绝时不返回该响应头。",
+            "schema": {
+              "type": "integer",
+              "minimum": 0
+            }
+          }
         }
       },
       "ServerError": {
@@ -18461,30 +19290,30 @@
               "type": "integer",
               "format": "int64"
             },
-            "description": "要添加的处理人员成员 ID 列表。"
+            "description": "要添加为处理人的成员 ID。已经是处理人或账户中不存在的 ID 会被跳过。"
           },
           "notify": {
             "type": "object",
-            "description": "通知配置，默认跟随每人的个人通知偏好。",
+            "description": "新加入处理人的通知设置。默认 `{\"follow_preference\": true}`。",
             "properties": {
               "follow_preference": {
                 "type": [
                   "boolean",
                   "null"
                 ],
-                "description": "为 false 时使用 `personal_channels`；为 true 或省略时跟随处理人员的个人偏好。"
+                "description": "`true`：按每个人的个人通知偏好发送。`false`：使用 `personal_channels`，此时该字段不能为空。不传时必须设置 `personal_channels`。"
               },
               "personal_channels": {
                 "type": "array",
                 "items": {
                   "type": "string"
                 },
-                "description": "使用的通知渠道（如 `voice`、`sms`、`email`）。"
+                "description": "`follow_preference` 为 `false` 时使用的通知渠道：`sms`、`voice`、`email`、`push`（手机 App 推送），或写作 `feishu_app:<integration_id>`、`dingtalk_app:<integration_id>`、`wecom_app:<integration_id>`、`slack_app:<integration_id>`、`teams_app:<integration_id>` 的 IM 应用渠道。`follow_preference` 为 `true` 时忽略。"
               },
               "template_id": {
                 "type": "string",
                 "pattern": "^[0-9a-fA-F]{24}$",
-                "description": "通知模板 ID（MongoDB ObjectID）。"
+                "description": "通知模板 ID，取自通知模板相关接口。必须是账户中存在的模板，否则返回 `InvalidParameter`。"
               }
             }
           }
@@ -18616,7 +19445,7 @@
           },
           "severities": {
             "type": "string",
-            "description": "逗号分隔的严重级别过滤，如 `Critical,Warning`。可选值：`Critical`、`Warning`、`Info`、`Ok`。"
+            "description": "按 `event_severity` 过滤，多个值用逗号分隔，如 `Critical,Warning`。有效取值：`Critical`、`Warning`、`Info`。取值不做校验，未知值（或 `Ok`）匹配不到事件。"
           },
           "orderby": {
             "type": "string",
@@ -18673,7 +19502,7 @@
           "account_id": {
             "type": "integer",
             "format": "int64",
-            "description": "账户 ID。"
+            "description": "该记录所属账户的 ID；同一 `app_key` 返回的记录该值都相同。"
           },
           "channel_id": {
             "type": "integer",
@@ -18687,7 +19516,7 @@
           },
           "integration_type": {
             "type": "string",
-            "description": "产生该事件的集成类型/插件键。"
+            "description": "集成的插件类型，例如 `prometheus.alert`、`grafana.alert`、`zabbix.alert`、`monit.alert`、`email.alert`。取值集合是开放的，会随新集成增加；完整列表可通过 `POST /integration/type/list` 获取。"
           },
           "data_source_id": {
             "type": "integer",
@@ -18929,7 +19758,7 @@
           },
           "alt": {
             "type": "string",
-            "description": "替代文本。"
+            "description": "图片无法显示时展示的替代文字；未设置时为空。"
           }
         }
       },
@@ -18986,12 +19815,12 @@
           "channel_id": {
             "type": "integer",
             "format": "int64",
-            "description": "协作空间 ID。"
+            "description": "告警被路由到的协作空间 ID，名称见 `channel_name`。"
           },
           "account_id": {
             "type": "integer",
             "format": "int64",
-            "description": "账号 ID。"
+            "description": "该记录所属账户的 ID；同一 `app_key` 返回的记录该值都相同。"
           },
           "description": {
             "type": "string",
@@ -19045,7 +19874,10 @@
             "description": "告警恢复的 Unix 时间戳（秒），仍活跃时为 0。"
           },
           "labels": {
-            "type": "object",
+            "type": [
+              "object",
+              "null"
+            ],
             "additionalProperties": {
               "type": "string"
             },
@@ -19076,7 +19908,7 @@
           },
           "integration_type": {
             "type": "string",
-            "description": "集成类型。"
+            "description": "集成的插件类型，例如 `prometheus.alert`、`grafana.alert`、`zabbix.alert`、`monit.alert`、`email.alert`。取值集合是开放的，会随新集成增加；完整列表可通过 `POST /integration/type/list` 获取。"
           },
           "integration_ref_id": {
             "type": "string",
@@ -19088,15 +19920,21 @@
           },
           "channel_status": {
             "type": "string",
-            "description": "协作空间状态。"
+            "description": "协作空间状态：`enabled` 启用、`disabled` 禁用、`deleted` 已删除。记录不属于任何协作空间或协作空间已不存在时为空字符串。",
+            "enum": [
+              "enabled",
+              "disabled",
+              "deleted",
+              ""
+            ]
           },
           "responder_name": {
             "type": "string",
-            "description": "主处理人员名称。"
+            "description": "API 响应中恒为空字符串，仅在渲染通知时填充。"
           },
           "responder_email": {
             "type": "string",
-            "description": "主处理人员邮箱。"
+            "description": "API 响应中恒为空字符串，仅在渲染通知时填充。"
           },
           "incident": {
             "$ref": "#/components/schemas/IncidentShort",
@@ -19115,11 +19953,14 @@
             "description": "合并到该告警的原始事件总数。"
           },
           "images": {
-            "type": "array",
+            "type": [
+              "array",
+              "null"
+            ],
             "items": {
               "$ref": "#/components/schemas/Image"
             },
-            "description": "附加图片。"
+            "description": "告警附带的图片；没有时为 `null`。"
           },
           "detail_url": {
             "description": "这条告警的控制台页面（`{控制台}/alert/detail/{alert_id}`）。部署没有配置控制台地址时为空。",
@@ -19131,7 +19972,7 @@
           },
           "data_source_type": {
             "type": "string",
-            "description": "已废弃，请使用 `integration_type`。"
+            "description": "已废弃；与 `integration_type` 取值相同。"
           },
           "data_source_ref_id": {
             "type": "string",
@@ -19179,7 +20020,7 @@
           "account_id": {
             "type": "integer",
             "format": "int64",
-            "description": "账户 ID。"
+            "description": "告警所属账户的 ID。"
           },
           "title": {
             "type": "string",
@@ -19232,11 +20073,14 @@
             "description": "恢复时间，Unix 时间戳（秒）。活跃时为 0。"
           },
           "labels": {
-            "type": "object",
+            "type": [
+              "object",
+              "null"
+            ],
             "additionalProperties": {
               "type": "string"
             },
-            "description": "标签键值对。"
+            "description": "标签键值对；告警没有标签时为 `null`。"
           },
           "ever_muted": {
             "type": "boolean",
@@ -19258,11 +20102,11 @@
           },
           "integration_type": {
             "type": "string",
-            "description": "集成类型/插件键。"
+            "description": "产生该告警的集成类型标识，如 `prometheus.alert`、`zabbix.alert`；取值同 `POST /integration/type/list` 返回的 `plugin_type`。"
           },
           "integration_ref_id": {
             "type": "string",
-            "description": "集成外部参考 ID。"
+            "description": "集成的归属标识：账户级集成为 `a_<account_id>`，协作空间专属集成为 `c_<channel_id>`。"
           },
           "channel_name": {
             "type": "string",
@@ -19301,11 +20145,14 @@
             "description": "告警的原始事件列表。本接口不返回；仅 `POST /incident/alert/list` 填充该字段。"
           },
           "images": {
-            "type": "array",
+            "type": [
+              "array",
+              "null"
+            ],
             "items": {
               "$ref": "#/components/schemas/AlertImage"
             },
-            "description": "告警附加的图片。"
+            "description": "告警附带的图片；没有图片时为 `null`。"
           },
           "detail_url": {
             "description": "这条告警的控制台页面（`{控制台}/alert/detail/{alert_id}`）。部署没有配置控制台地址时为空。",
@@ -19318,7 +20165,7 @@
           },
           "data_source_type": {
             "type": "string",
-            "description": "已废弃：请使用 `integration_type`。为空时不返回。",
+            "description": "已弃用，请使用 `integration_type`（取值相同，如 `prometheus.alert`）。为空时不返回。",
             "deprecated": true
           },
           "data_source_ref_id": {
@@ -19344,8 +20191,7 @@
             "items": {
               "type": "string"
             },
-            "description": "要查询的告警 ID 列表（ObjectID 十六进制字符串）。",
-            "minItems": 1
+            "description": "要查询的告警 ID（ObjectID 十六进制字符串）。格式错误的 ID 会使请求失败；账户中不存在的 ID 不会出现在结果中。"
           }
         }
       },
@@ -19360,12 +20206,12 @@
           "start_time": {
             "type": "integer",
             "format": "int64",
-            "description": "检索窗口开始时间，Unix 时间戳（秒）。"
+            "description": "查询窗口起点，Unix 时间戳（秒），作用于告警的 `start_time`。早于账户数据保留期时会被调整为保留期起点。"
           },
           "end_time": {
             "type": "integer",
             "format": "int64",
-            "description": "查询窗口终点，Unix 时间戳（秒）。必须大于 `start_time`；跨度不超过 31 天，且需在账户数据保留期内。"
+            "description": "查询窗口终点，Unix 时间戳（秒）。必须大于 `start_time`，跨度不超过 31 天（启用 `by_updated_at` 时不超过 7 天）。早于数据保留期起点时返回 `InvalidParameter`。"
           },
           "p": {
             "type": [
@@ -19409,7 +20255,7 @@
           },
           "alert_severity": {
             "type": "string",
-            "description": "逗号分隔的严重程度过滤，如 `Critical,Warning`。可选值：`Critical`、`Warning`、`Info`、`Ok`。"
+            "description": "按 `alert_severity` 过滤，多个值用逗号分隔，如 `Critical,Warning`。允许的取值：`Critical`、`Warning`、`Info`、`Ok`，其他值返回 `InvalidParameter`。`alert_severity` 不会是 `Ok`，因此 `Ok` 匹配不到告警。"
           },
           "channel_ids": {
             "type": "array",
@@ -19447,7 +20293,7 @@
           },
           "by_updated_at": {
             "type": "boolean",
-            "description": "为 true 时，时间范围过滤作用于 `updated_at` 而非 `start_time`。"
+            "description": "为 `true` 时，在按 `start_time` 过滤之外，还要求告警的 `updated_at` 落在 [`start_time`, `end_time`] 内；此时跨度不超过 7 天。"
           }
         }
       },
@@ -19458,15 +20304,15 @@
           "total": {
             "type": "integer",
             "format": "int64",
-            "description": "匹配的告警总数，最多统计 1000 条。"
+            "description": "匹配的告警数量，最多为 1,000。"
           },
           "has_next_page": {
             "type": "boolean",
-            "description": "是否有更多页。"
+            "description": "存在下一页时为 `true`。游标模式（传了 `search_after_ctx`）下结果准确；页码模式下按 `p * limit` 与封顶后的 `total` 比较，超过 1,000 条后即使还有匹配的告警也会返回 `false`，此时请改用 `search_after_ctx` 继续。"
           },
           "search_after_ctx": {
             "type": "string",
-            "description": "下一页游标——本页最后一条告警的 ObjectID 十六进制字符串，请求下一页时作为 `search_after_ctx` 传入。仅在 `has_next_page` 为 true 时返回。"
+            "description": "下一页游标——本页最后一条告警的 ObjectID；请作为 `search_after_ctx` 传回。本页为空时不返回；游标模式下没有下一页时也不返回。"
           },
           "items": {
             "type": "array",
@@ -19489,8 +20335,7 @@
             "items": {
               "type": "string"
             },
-            "description": "要合并的告警 ID 列表（ObjectID 十六进制字符串），可从 `POST /alert/list` 获取。所有 ID 必须属于当前账户。",
-            "minItems": 1
+            "description": "要合并的告警 ID 列表（ObjectID 十六进制字符串），可从 `POST /alert/list` 获取。所有 ID 必须属于当前账户。"
           },
           "incident_id": {
             "type": "string",
@@ -19537,7 +20382,7 @@
             "items": {
               "$ref": "#/components/schemas/FilterCondition"
             },
-            "description": "AND 条件列表——仅当所有条件都匹配时规则生效。为 `null` 或不传表示规则对所有事件生效。"
+            "description": "AND 过滤条件列表——事件满足全部条件时规则才生效。可用的 key：`severity`（别名 `alert_severity`、`event_severity`）、`status`、`title`、`title_rule`、`description`、`alert_key`、`integration_id`（别名 `data_source_id`）以及 `labels.<名称>`；其他 key 返回 `InvalidParameter`。为 `null` 或不传时规则作用于所有事件。"
           },
           "settings": {
             "type": "object",
@@ -19668,27 +20513,26 @@
           "integration_id": {
             "type": "integer",
             "format": "int64",
-            "description": "要配置的集成 ID。"
+            "description": "要配置的集成 ID，账户级集成和协作空间专属集成均可。"
           },
           "rules": {
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/AlertPipeline"
             },
-            "description": "要应用的规则，按数组顺序执行。1 到 50 条。",
-            "maxItems": 50,
-            "minItems": 1
+            "description": "要应用的规则，按数组顺序执行。最多 50 条；传空数组会清空所有规则。",
+            "maxItems": 50
           }
         }
       },
       "ApAlertDrop": {
         "type": "object",
-        "description": "`alert_drop` 规则的配置：无需额外配置，匹配的告警将被静默丢弃。",
+        "description": "`alert_drop` 的配置：无字段，传 `{}` 即可。命中的事件会被丢弃，不会创建或更新告警。",
         "properties": {}
       },
       "ApAlertInhibit": {
         "type": "object",
-        "description": "`alert_inhibit` 规则的配置：当来源告警与当前告警共享相同标签值时，抑制匹配过滤条件的来源告警。",
+        "description": "`alert_inhibit` 的配置：当同一集成中存在一条活跃告警（`alert_key` 不同、在事件前 10 分钟内开始），且它满足 `source_filters`、在每个 `equals` key 上与当前事件取值相同时，当前事件被丢弃。",
         "required": [
           "equals",
           "source_filters"
@@ -19699,33 +20543,33 @@
             "items": {
               "type": "string"
             },
-            "description": "需要在来源告警与当前告警之间值相等的标签键列表。"
+            "description": "源告警与当前事件取值必须相同的 key：`title`、`severity` 或 `labels.<名称>`。列表为空、包含其他 key，或事件缺少该标签时，规则不会抑制任何事件。"
           },
           "source_filters": {
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/FilterCondition"
             },
-            "description": "用于匹配待抑制来源告警的 AND 过滤条件列表，需全部条件匹配。"
+            "description": "源告警须满足的 AND 条件。可用的 key：`severity`、`title` 和 `labels.<名称>`；其他 key 返回 `InvalidParameter`。"
           }
         }
       },
       "ApDescriptionReset": {
         "type": "object",
-        "description": "`description_reset` 规则的配置：使用模板字符串覆盖告警描述。",
+        "description": "`description_reset` 的配置：用渲染后的模板替换事件描述。",
         "required": [
           "description"
         ],
         "properties": {
           "description": {
             "type": "string",
-            "description": "新描述模板。"
+            "description": "描述模板。仅以 `[TPL]` 开头的值生效：其后内容按 Go 模板基于事件渲染并替换描述；不带该前缀时描述保持不变。"
           }
         }
       },
       "ApSeverityReset": {
         "type": "object",
-        "description": "`severity_reset` 规则的配置：将告警严重程度强制设置为固定值。",
+        "description": "`severity_reset` 的配置：把事件的严重程度和状态都设为固定值。",
         "required": [
           "severity"
         ],
@@ -19737,20 +20581,20 @@
               "Warning",
               "Info"
             ],
-            "description": "目标严重程度级别。"
+            "description": "要设置的严重程度：`Critical`、`Warning` 或 `Info`。事件状态会被设为相同的值。"
           }
         }
       },
       "ApTitleReset": {
         "type": "object",
-        "description": "`title_reset` 规则的配置：使用模板字符串覆盖告警标题。",
+        "description": "`title_reset` 的配置：按标题规则重写事件标题。",
         "required": [
           "title"
         ],
         "properties": {
           "title": {
             "type": "string",
-            "description": "新标题模板，支持引用告警字段的 Golang 模板语法。"
+            "description": "标题规则。以 `[TPL]` 开头时按 Go 模板基于事件渲染，如 `[TPL]{{.Labels.service}}`；否则视为以 `::` 分隔的片段列表，`$名称` 片段替换为同名标签的值，其他片段原样保留。"
           }
         }
       },
@@ -19778,13 +20622,13 @@
           },
           "assigned_to": {
             "$ref": "#/components/schemas/AssignedTo",
-            "description": "分派目标，`person_ids` 与 `escalate_rule_id` 至少设置一项。"
+            "description": "分派对象。设置 `person_ids`、`escalate_rule_id` 或 `emails`；都未设置时服务端会重新匹配协作空间的分派策略。"
           }
         }
       },
       "AssignedTo": {
         "type": "object",
-        "description": "故障分派目标。`person_ids` 与 `escalate_rule_id` 至少设置一项。",
+        "description": "分派对象。请求中设置 `person_ids`、`escalate_rule_id` 或 `emails`；都未设置时服务端会重新匹配协作空间的分派策略。响应中该对象始终存在；从未分派过的故障 `type`、`id` 为空，`assigned_at` 为 `0`。",
         "properties": {
           "person_ids": {
             "type": "array",
@@ -19803,16 +20647,17 @@
           },
           "layer_idx": {
             "type": "integer",
-            "description": "当前环节索引。"
+            "description": "`escalate_rule_id` 中的分派层级，从 0 开始（`0` 为第一级）。处理人取自该层级。"
           },
           "type": {
             "type": "string",
-            "description": "指派类型：`assign` 直接指派、`reassign` 重新指派、`escalate` 分派策略驱动、`reopen` 重新打开时自动指派。",
+            "description": "分派方式：`assign` 首次分派；`reassign` 对已分派故障的重新分派；`escalate` 由升级流程触发；`reopen` 故障重开后的重新分派；故障从未分派时响应中为空字符串。请求中可不传，由服务端推断。",
             "enum": [
               "assign",
               "reassign",
               "escalate",
-              "reopen"
+              "reopen",
+              ""
             ]
           },
           "emails": {
@@ -19823,7 +20668,7 @@
             },
             "minItems": 1,
             "maxItems": 100,
-            "description": "邮箱接收人列表，用于 ServiceNow 等外部系统。"
+            "description": "成员邮箱；每个邮箱会解析为成员 ID 并合并到 `person_ids`。找不到对应成员的邮箱会被忽略。"
           },
           "notify": {
             "type": "object",
@@ -19834,14 +20679,14 @@
                   "boolean",
                   "null"
                 ],
-                "description": "为 false 时使用 `personal_channels`；为 true 或省略时跟随处理人员的个人偏好。"
+                "description": "`true`：按每个人的个人通知偏好发送。`false`：使用 `personal_channels`，此时该字段不能为空。不传时必须设置 `personal_channels`。"
               },
               "personal_channels": {
                 "type": "array",
                 "items": {
                   "type": "string"
                 },
-                "description": "使用的通知渠道（如 `voice`、`sms`、`email`）。"
+                "description": "`follow_preference` 为 `false` 时使用的通知渠道：`sms`、`voice`、`email`、`push`（手机 App 推送），或写作 `feishu_app:<integration_id>`、`dingtalk_app:<integration_id>`、`wecom_app:<integration_id>`、`slack_app:<integration_id>`、`teams_app:<integration_id>` 的 IM 应用渠道。`follow_preference` 为 `true` 时忽略。"
               },
               "template_id": {
                 "type": "string",
@@ -19852,16 +20697,24 @@
           },
           "escalate_rule_name": {
             "type": "string",
-            "description": "分派策略名称，由服务端填充。"
+            "description": "分派策略名称，由服务端在响应中填写；请求中传入会被忽略。"
           },
           "assigned_at": {
             "type": "integer",
             "format": "int64",
-            "description": "指派发生的 Unix 时间戳（秒）。"
+            "description": "分派发生的 Unix 时间戳（秒），由服务端设置。"
           },
           "id": {
             "type": "string",
-            "description": "服务端生成的指派 ID。"
+            "description": "服务端为每次分派生成的 ID。"
+          },
+          "effective_person_ids": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "int64"
+            },
+            "description": "实际接收分派的成员 ID：`person_ids` 加上所选分派层级的成员，去重并排序。由服务端设置；为空时省略。"
           }
         }
       },
@@ -19921,7 +20774,7 @@
           },
           "event_id": {
             "type": "string",
-            "description": "事件 ID。"
+            "description": "事件 ID。日历自有事件为 `cale.<id>`，按非工作日生成的条目为 `non_work.YYYYMMDD`，继承自节假日日历的事件为 `<节假日 cal_id>.<id>`。"
           },
           "summary": {
             "type": "string",
@@ -19946,12 +20799,12 @@
           "created_at": {
             "type": "integer",
             "format": "int64",
-            "description": "创建时间（Unix 秒）。"
+            "description": "创建时间（Unix 秒）；生成的 `non_work.*` 条目为 `0`。"
           },
           "updated_at": {
             "type": "integer",
             "format": "int64",
-            "description": "更新时间（Unix 秒）。"
+            "description": "最后更新时间（Unix 秒）；生成的 `non_work.*` 条目为 `0`。"
           }
         }
       },
@@ -20116,7 +20969,7 @@
         "properties": {
           "cal_name": {
             "type": "string",
-            "description": "日历显示名称。",
+            "description": "日历名称，在账户内必须唯一。",
             "minLength": 1,
             "maxLength": 39
           },
@@ -20127,13 +20980,13 @@
           },
           "timezone": {
             "type": "string",
-            "description": "IANA 时区，为空时默认 Asia/Shanghai。",
+            "description": "IANA 时区，如 `America/New_York`。为空时默认 `Asia/Shanghai`；非法名称返回 `InvalidParameter`。",
             "default": "Asia/Shanghai"
           },
           "team_id": {
             "type": "integer",
             "format": "uint64",
-            "description": "所属团队 ID，0 表示不关联团队。"
+            "description": "所属团队 ID；为 `0` 或不传表示不归属团队。非零 ID 必须是账户中的团队。"
           },
           "workdays": {
             "type": "array",
@@ -20142,7 +20995,7 @@
               "minimum": 0,
               "maximum": 6
             },
-            "description": "工作日（0 = 周日，6 = 周六）。"
+            "description": "每周工作日，`0` 表示周日……`6` 表示周六。未列出的日子为非工作日。为空时不把任何一天视为非工作日。"
           },
           "extra_cal_ids": {
             "type": "array",
@@ -20210,7 +21063,7 @@
           "account_id": {
             "type": "integer",
             "format": "uint64",
-            "description": "账户 ID。"
+            "description": "日历所属账户的 ID。"
           },
           "team_id": {
             "type": "integer",
@@ -20249,7 +21102,7 @@
               "minimum": 0,
               "maximum": 6
             },
-            "description": "工作日（0 = 周日，6 = 周六）。为空时省略。"
+            "description": "每周工作日，`0` 表示周日……`6` 表示周六。未列出的日子为非工作日。为空时不把任何一天视为非工作日。 为空时不返回。"
           },
           "extra_cal_ids": {
             "type": "array",
@@ -20344,7 +21197,7 @@
               "string",
               "null"
             ],
-            "description": "新的日历名称。",
+            "description": "新的日历名称，在账户内必须唯一。",
             "minLength": 1,
             "maxLength": 39
           },
@@ -20361,7 +21214,7 @@
               "string",
               "null"
             ],
-            "description": "新的 IANA 时区。"
+            "description": "新的 IANA 时区，如 `Asia/Shanghai`；非法名称返回 `InvalidParameter`。"
           },
           "team_id": {
             "type": [
@@ -20369,7 +21222,7 @@
               "null"
             ],
             "format": "uint64",
-            "description": "新的所属团队 ID，可通过 `POST /team/list` 获取。"
+            "description": "新的所属团队 ID，可从 `POST /team/list` 获取。`0` 表示取消团队归属；非零 ID 必须是账户中的团队。"
           },
           "workdays": {
             "type": "array",
@@ -20378,14 +21231,14 @@
               "minimum": 0,
               "maximum": 6
             },
-            "description": "工作日（0 = 周日，6 = 周六）。"
+            "description": "每周工作日，`0` 表示周日……`6` 表示周六。未列出的日子为非工作日。为空时不把任何一天视为非工作日。 传入时整体替换原列表，不传则保持不变。"
           },
           "extra_cal_ids": {
             "type": "array",
             "items": {
               "type": "string"
             },
-            "description": "需要继承事件的公共节假日日历 ID 列表。"
+            "description": "要继承事件的公共节假日日历 ID（见 `kind` 为 `region.official.holiday` 的 `POST /calendar/list`）。传入时整体替换原列表，空数组即全部移除，不传则保持不变。"
           }
         }
       },
@@ -20420,7 +21273,7 @@
           },
           "external_report_token": {
             "type": "string",
-            "description": "外部上报 token，仅在启用外部上报时返回。"
+            "description": "外部上报令牌。仅当请求中 `is_external_report_enabled` 为 `true` 时返回；之后可通过 `POST /channel/info` 再次读取。"
           }
         }
       },
@@ -20478,7 +21331,7 @@
             "items": {
               "$ref": "#/components/schemas/ChannelShort"
             },
-            "description": "请求的 `channel_ids` 中实际存在的协作空间简要信息；未找到的 ID 会被忽略。"
+            "description": "请求中存在的协作空间（含已删除的），不存在的 ID 被忽略。按协作空间创建顺序排列，而非请求顺序。"
           }
         }
       },
@@ -20489,7 +21342,7 @@
           "channel_id": {
             "type": "integer",
             "format": "int64",
-            "description": "协作空间 ID。"
+            "description": "协作空间 ID，在其他协作空间及策略接口中作为 `channel_id` 传入。"
           },
           "team_id": {
             "type": "integer",
@@ -20498,7 +21351,7 @@
           },
           "team_name": {
             "type": "string",
-            "description": "所属团队名称（由团队目录解析；无法解析时为空）。"
+            "description": "所属团队名称（由团队目录解析）。仅 `POST /channel/list`（非 `is_brief`）返回；解析失败时不返回。"
           },
           "managing_team_ids": {
             "type": "array",
@@ -20515,7 +21368,7 @@
           },
           "creator_name": {
             "type": "string",
-            "description": "创建者成员名称（由成员目录解析；无法解析时为空）。"
+            "description": "创建者成员名称。仅 `POST /channel/list`（非 `is_brief`）返回；解析失败时不返回。"
           },
           "account_id": {
             "type": "integer",
@@ -20524,7 +21377,7 @@
           },
           "channel_name": {
             "type": "string",
-            "description": "协作空间名称。"
+            "description": "协作空间名称，账户内唯一，1–59 个字符。"
           },
           "description": {
             "type": "string",
@@ -20537,7 +21390,7 @@
               "disabled",
               "deleted"
             ],
-            "description": "协作空间状态。`enabled` 正常接收与处理事件；`disabled` 停用，新事件被直接丢弃；`deleted` 已删除，仅按 ID 查询详情时可能返回，列表接口不返回。"
+            "description": "协作空间状态：\n- `enabled`：正常处理新进入的告警事件。\n- `disabled`：新进入的告警事件被丢弃。\n- `deleted`：已删除；只会出现在 `POST /channel/info` 与 `POST /channel/infos` 中，`POST /channel/list` 不返回。"
           },
           "deleted_at": {
             "type": "integer",
@@ -20581,19 +21434,19 @@
           },
           "group": {
             "$ref": "#/components/schemas/Group",
-            "description": "告警聚合配置。"
+            "description": "告警聚合配置。从未设置时返回 `{\"method\": \"n\"}`（不聚合）。"
           },
           "flapping": {
             "$ref": "#/components/schemas/Flapping",
-            "description": "抖动检测配置。"
+            "description": "抖动检测配置。从未设置时返回默认值：开启，60 分钟内 4 次变化，静音 120 分钟。"
           },
           "progress_to_incident_cnts": {
             "$ref": "#/components/schemas/IncProgressCnts",
-            "description": "近 30 天按进度统计的故障数量。"
+            "description": "近 30 天内开始且仍未关闭的故障数，按进度统计。`is_brief` 时不返回。"
           },
           "is_starred": {
             "type": "boolean",
-            "description": "当前用户是否已收藏该协作空间。仅在 `POST /channel/list` 响应中返回。"
+            "description": "当前调用者是否收藏了该协作空间。仅 `POST /channel/list` 返回。"
           },
           "active_incident_highest_severity": {
             "type": "string",
@@ -20615,11 +21468,11 @@
           },
           "external_report_token": {
             "type": "string",
-            "description": "授予外部上报人的 token。仅在协作空间启用外部上报时返回。"
+            "description": "外部上报人向该协作空间提交故障所用的令牌。仅在开启外部上报时返回。"
           },
           "event_group": {
             "$ref": "#/components/schemas/EventGroup",
-            "description": "告警事件合并配置。"
+            "description": "告警事件合并配置。从未设置时为开启合并、窗口 1,440 分钟。"
           }
         }
       },
@@ -20638,7 +21491,7 @@
           "rule_id": {
             "type": "string",
             "pattern": "^[0-9a-fA-F]{24}$",
-            "description": "规则 ID（MongoDB ObjectID）。"
+            "description": "策略 ID（24 位十六进制），即同类策略创建或列表接口返回的 `rule_id`。"
           }
         }
       },
@@ -20651,7 +21504,7 @@
           "channel_id": {
             "type": "integer",
             "format": "int64",
-            "description": "要列出规则的协作空间 ID。"
+            "description": "要查询策略的协作空间 ID，可通过 `POST /channel/list` 获取。"
           }
         }
       },
@@ -20665,11 +21518,11 @@
           "channel_id": {
             "type": "integer",
             "format": "int64",
-            "description": "协作空间 ID。"
+            "description": "协作空间 ID，为请求的 `channel_ids` 之一。"
           },
           "channel_name": {
             "type": "string",
-            "description": "协作空间名称。"
+            "description": "协作空间名称，账户内唯一。"
           },
           "status": {
             "type": "string",
@@ -20678,7 +21531,7 @@
               "disabled",
               "deleted"
             ],
-            "description": "协作空间状态：`enabled` 正常处理事件；`disabled` 丢弃新事件；`deleted` 已删除。"
+            "description": "协作空间状态：\n- `enabled`：正常处理新进入的告警事件。\n- `disabled`：新进入的告警事件被丢弃。\n- `deleted`：已删除。"
           }
         }
       },
@@ -20730,7 +21583,7 @@
           "team_id": {
             "type": "integer",
             "format": "int64",
-            "description": "所属团队 ID，可通过 `POST /team/list` 获取。"
+            "description": "所属团队 ID，可通过 `POST /team/list` 获取。必填且必须存在。"
           },
           "managing_team_ids": {
             "type": "array",
@@ -20745,7 +21598,7 @@
             "type": "string",
             "minLength": 1,
             "maxLength": 59,
-            "description": "协作空间名称,1 到 59 个字符。"
+            "description": "协作空间名称，1–59 个字符，账户内唯一。"
           },
           "description": {
             "type": "string",
@@ -20754,7 +21607,7 @@
           },
           "escalate_rule": {
             "type": "object",
-            "description": "协作空间的默认分派策略,不需要时可省略。",
+            "description": "创建一条名为 `Default` 的已启用分派策略，只有一个环节，对 `target` 通知一次。不传则创建的协作空间没有分派策略。",
             "required": [
               "template_id",
               "target"
@@ -20764,242 +21617,26 @@
                 "type": "integer",
                 "minimum": 0,
                 "maximum": 3600,
-                "description": "延迟窗口,单位秒,0 表示不延迟。"
+                "description": "新分派故障首次通知前的延迟（秒），0–3600；`0` 表示立即通知。"
               },
               "template_id": {
                 "type": "string",
                 "pattern": "^[0-9a-fA-F]{24}$",
-                "description": "通知模板 ID(MongoDB ObjectID)。"
+                "description": "通知模板 ID（24 位十六进制），可通过 `POST /template/list` 获取，必须存在。"
               },
               "target": {
-                "type": "object",
-                "description": "通知目标。`person_ids`、`team_ids`、`schedule_to_role_ids`、`emails` 至少设置一项,且 `by` 与 `webhooks` 至少设置一项。",
-                "properties": {
-                  "person_ids": {
-                    "type": "array",
-                    "items": {
-                      "type": "integer",
-                      "format": "int64"
-                    },
-                    "description": "直接通知的成员 ID 列表，可通过 `POST /member/list` 获取。"
-                  },
-                  "team_ids": {
-                    "type": "array",
-                    "items": {
-                      "type": "integer",
-                      "format": "int64"
-                    },
-                    "description": "通知的团队 ID 列表，可通过 `POST /team/list` 获取。"
-                  },
-                  "schedule_to_role_ids": {
-                    "type": "object",
-                    "additionalProperties": {
-                      "type": "array",
-                      "items": {
-                        "type": "integer",
-                        "format": "int64"
-                      }
-                    },
-                    "description": "值班表 ID 到角色 ID 列表的映射,用于按值班角色通知。"
-                  },
-                  "emails": {
-                    "type": "array",
-                    "items": {
-                      "type": "string",
-                      "format": "email"
-                    },
-                    "description": "邮箱地址列表(推送场景)。"
-                  },
-                  "by": {
-                    "type": "object",
-                    "description": "按告警等级配置的个人通知渠道。未提供 `webhooks` 时必填。",
-                    "properties": {
-                      "follow_preference": {
-                        "type": "boolean",
-                        "description": "为 true 时跟随处理人员的个人偏好,忽略下方列表。"
-                      },
-                      "critical": {
-                        "type": "array",
-                        "items": {
-                          "type": "string"
-                        },
-                        "description": "Critical 级别使用的通知渠道。个人通知渠道：`sms`、`voice`、`email`、`push`；IM 群聊渠道：`feishu_app:<chat_id>`、`dingtalk_app:<chat_id>`、`wecom_app:<chat_id>`、`slack_app:<chat_id>`、`teams_app:<chat_id>`。"
-                      },
-                      "warning": {
-                        "type": "array",
-                        "items": {
-                          "type": "string"
-                        },
-                        "description": "Warning 级别使用的通知渠道。取值同 `critical`。"
-                      },
-                      "info": {
-                        "type": "array",
-                        "items": {
-                          "type": "string"
-                        },
-                        "description": "Info 级别使用的通知渠道。取值同 `critical`。"
-                      }
-                    }
-                  },
-                  "webhooks": {
-                    "type": "array",
-                    "description": "群聊/Webhook 通知目标。未提供 `by` 时必填。",
-                    "items": {
-                      "type": "object",
-                      "required": [
-                        "type",
-                        "settings"
-                      ],
-                      "properties": {
-                        "type": {
-                          "type": "string",
-                          "description": "Webhook 类型，可选值：`feishu`、`feishu_app`、`dingtalk`、`dingtalk_app`、`wecom`、`slack`、`slack_app`、`teams_app`、`telegram`、`zoom`。"
-                        },
-                        "settings": {
-                          "type": "object",
-                          "additionalProperties": true,
-                          "description": "类型相关的配置参数(群聊 ID、URL 等)。"
-                        }
-                      }
-                    }
-                  }
-                }
+                "$ref": "#/components/schemas/EscalateTarget",
+                "description": "通知对象及通知渠道。"
               }
             }
           },
           "group": {
-            "type": "object",
-            "description": "告警聚合配置。",
-            "required": [
-              "method"
-            ],
-            "properties": {
-              "method": {
-                "type": "string",
-                "enum": [
-                  "i",
-                  "p",
-                  "n"
-                ],
-                "description": "聚合方式:`i` 智能、`p` 规则、`n` 不聚合。"
-              },
-              "equals": {
-                "type": "array",
-                "items": {
-                  "type": "array",
-                  "items": {
-                    "type": "string"
-                  }
-                },
-                "maxItems": 5,
-                "description": "用于聚合判定的 label 键分组。"
-              },
-              "cases": {
-                "type": "array",
-                "maxItems": 100,
-                "description": "按过滤条件的聚合策略覆盖。",
-                "items": {
-                  "type": "object",
-                  "description": "条件化聚合覆盖：命中 `if` 的已存告警按 `equals` 键聚合，而不使用顶层聚合键。",
-                  "required": [
-                    "if",
-                    "equals"
-                  ],
-                  "properties": {
-                    "if": {
-                      "type": "array",
-                      "description": "针对已存告警字段的匹配条件，条件之间为 AND 关系。",
-                      "items": {
-                        "$ref": "#/components/schemas/FilterCondition"
-                      }
-                    },
-                    "equals": {
-                      "type": "array",
-                      "items": {
-                        "type": "string"
-                      },
-                      "minItems": 1,
-                      "maxItems": 5,
-                      "description": "命中告警使用的聚合键。可选值：`title`、`description`、`severity` 或任意 `labels.<name>`。"
-                    }
-                  }
-                }
-              },
-              "all_equals_required": {
-                "type": "boolean",
-                "description": "为 true 时要求所有键同时存在才能参与聚合。"
-              },
-              "time_window": {
-                "type": "integer",
-                "minimum": 0,
-                "description": "聚合时间窗口，单位分钟。默认最大值为 1440 分钟（24 小时）；开启扩展功能的账号最大可设置 43200 分钟（30 天）。"
-              },
-              "window_type": {
-                "type": "string",
-                "enum": [
-                  "tumbling",
-                  "sliding"
-                ],
-                "description": "窗口类型,默认 `tumbling`。`tumbling` 为固定窗口，自故障创建时间起算，窗口到期后新告警会开启新故障；`sliding` 为滑动窗口，自故障最近一次告警时间起算，每有新告警并入即向后顺延。"
-              },
-              "storm_threshold": {
-                "type": "integer",
-                "minimum": 0,
-                "maximum": 10000,
-                "description": "告警风暴阈值。"
-              },
-              "storm_thresholds": {
-                "type": "array",
-                "items": {
-                  "type": "integer"
-                },
-                "maxItems": 5,
-                "description": "多级告警风暴阈值。"
-              },
-              "i_keys": {
-                "type": "array",
-                "items": {
-                  "type": "string"
-                },
-                "maxItems": 10,
-                "description": "用于智能聚合向量化的 label 键。"
-              },
-              "i_score_threshold": {
-                "type": "number",
-                "format": "float",
-                "minimum": 0.5,
-                "maximum": 1,
-                "description": "智能聚合相似度阈值。"
-              }
-            }
+            "$ref": "#/components/schemas/Group",
+            "description": "告警聚合配置。不传时不聚合（`method` 为 `n`）。"
           },
           "flapping": {
-            "type": "object",
-            "description": "抖动检测配置。",
-            "properties": {
-              "is_disabled": {
-                "type": "boolean",
-                "description": "禁用抖动检测。"
-              },
-              "max_changes": {
-                "type": "integer",
-                "minimum": 2,
-                "maximum": 100,
-                "description": "`in_mins` 内允许的最大状态变更次数。"
-              },
-              "in_mins": {
-                "type": "integer",
-                "minimum": 1,
-                "maximum": 1440,
-                "description": "观察窗口,单位分钟。"
-              },
-              "mute_mins": {
-                "type": "integer",
-                "minimum": 0,
-                "maximum": 1440,
-                "description": "检测到抖动后的静音时长,单位分钟。"
-              }
-            }
+            "$ref": "#/components/schemas/Flapping",
+            "description": "抖动检测配置。不传时使用默认值。"
           },
           "auto_resolve_timeout": {
             "type": "integer",
@@ -21014,7 +21651,7 @@
               "trigger",
               "update"
             ],
-            "description": "自动恢复计时方式：`trigger` 从故障触发时开始计时，`update` 每次告警更新都重新计时。"
+            "description": "自动恢复的计时方式。`trigger`（默认）在故障触发时开始计时，只计一次；`update` 每当有新告警并入故障时重新计时。"
           },
           "plugin_ids": {
             "type": "array",
@@ -21022,7 +21659,7 @@
               "type": "integer",
               "format": "int64"
             },
-            "description": "订阅该协作空间的集成 ID 列表。"
+            "description": "集成类型 ID（即 `POST /integration/list` 返回的集成上的 `plugin_id`）。每个 ID 会创建一个该类型的协作空间专属集成，名称为该类型名称。ID 不存在时返回 `InvalidParameter`。"
           },
           "is_private": {
             "type": "boolean",
@@ -21038,7 +21675,7 @@
           },
           "is_external_report_enabled": {
             "type": "boolean",
-            "description": "允许外部上报人向该协作空间上报故障。"
+            "description": "为 true 时允许外部上报人向该协作空间提交故障，响应中返回生成的 `external_report_token`。"
           },
           "event_group": {
             "$ref": "#/components/schemas/EventGroup",
@@ -21071,40 +21708,8 @@
             "description": "规则描述,最多 500 个字符。"
           },
           "filters": {
-            "type": "array",
-            "description": "告警事件匹配条件（OR-of-AND 结构）；命中的事件被完全丢弃——不产生告警、故障或通知。不传或为空时，规则不匹配任何事件。",
-            "items": {
-              "type": "array",
-              "items": {
-                "type": "object",
-                "required": [
-                  "key",
-                  "oper",
-                  "vals"
-                ],
-                "properties": {
-                  "key": {
-                    "type": "string",
-                    "description": "字段键(如 `alert_severity`、`labels.service`)。"
-                  },
-                  "oper": {
-                    "type": "string",
-                    "enum": [
-                      "IN",
-                      "NOTIN"
-                    ],
-                    "description": "过滤运算符。"
-                  },
-                  "vals": {
-                    "type": "array",
-                    "items": {
-                      "type": "string"
-                    },
-                    "description": "匹配值列表。"
-                  }
-                }
-              }
-            }
+            "$ref": "#/components/schemas/FilterGroup",
+            "description": "告警事件匹配条件（AND 组之间为 OR）。命中的事件被直接丢弃，不产生告警、故障或通知。可用字段：`title`、`description`、`severity`（别名 `alert_severity`、`event_severity`）、`status`、`alert_key`、`title_rule`、`integration_id`（别名 `data_source_id`），或任意 `labels.<name>`。不传或为空时规则不匹配任何事件。"
           }
         }
       },
@@ -21130,18 +21735,18 @@
             ],
             "minimum": 0,
             "maximum": 200,
-            "description": "匹配优先级,数值越小越优先。"
+            "description": "匹配顺序，取值 `0` 到 `200`，数值越小越先匹配。不传时排在现有策略之后（当前最大优先级 + 1）。"
           },
           "aggr_window": {
             "type": "integer",
             "minimum": 0,
             "maximum": 3600,
-            "description": "延迟窗口,单位秒,0 表示不延迟。"
+            "description": "新分派故障首次通知前的延迟（秒），0–3600；`0` 表示立即通知。"
           },
           "template_id": {
             "type": "string",
             "pattern": "^[0-9a-fA-F]{24}$",
-            "description": "通知模板 ID(MongoDB ObjectID)。"
+            "description": "通知模板 ID（24 位十六进制），可通过 `POST /template/list` 获取，必须存在。"
           },
           "rule_name": {
             "type": "string",
@@ -21156,201 +21761,21 @@
           },
           "layers": {
             "type": "array",
-            "description": "分派环节列表,至少包含一个环节。",
             "items": {
-              "type": "object",
-              "required": [
-                "target"
-              ],
-              "properties": {
-                "max_times": {
-                  "type": "integer",
-                  "minimum": 0,
-                  "maximum": 6,
-                  "description": "当前环节内的最大重复通知次数。"
-                },
-                "notify_step": {
-                  "type": "number",
-                  "format": "float",
-                  "minimum": 0.5,
-                  "maximum": 120,
-                  "description": "重复通知间隔,单位分钟。"
-                },
-                "target": {
-                  "type": "object",
-                  "description": "通知目标。`person_ids`、`team_ids`、`schedule_to_role_ids`、`emails` 至少设置一项,且 `by` 与 `webhooks` 至少设置一项。",
-                  "properties": {
-                    "person_ids": {
-                      "type": "array",
-                      "items": {
-                        "type": "integer",
-                        "format": "int64"
-                      },
-                      "description": "直接通知的成员 ID 列表，可通过 `POST /member/list` 获取。"
-                    },
-                    "team_ids": {
-                      "type": "array",
-                      "items": {
-                        "type": "integer",
-                        "format": "int64"
-                      },
-                      "description": "通知的团队 ID 列表，可通过 `POST /team/list` 获取。"
-                    },
-                    "schedule_to_role_ids": {
-                      "type": "object",
-                      "additionalProperties": {
-                        "type": "array",
-                        "items": {
-                          "type": "integer",
-                          "format": "int64"
-                        }
-                      },
-                      "description": "值班表 ID 到角色 ID 列表的映射,用于按值班角色通知。"
-                    },
-                    "emails": {
-                      "type": "array",
-                      "items": {
-                        "type": "string",
-                        "format": "email"
-                      },
-                      "description": "邮箱地址列表(推送场景)。"
-                    },
-                    "by": {
-                      "type": "object",
-                      "description": "按告警等级配置的个人通知渠道。未提供 `webhooks` 时必填。",
-                      "properties": {
-                        "follow_preference": {
-                          "type": "boolean",
-                          "description": "为 true 时跟随处理人员的个人偏好,忽略下方列表。"
-                        },
-                        "critical": {
-                          "type": "array",
-                          "items": {
-                            "type": "string"
-                          },
-                          "description": "Critical 级别使用的通知渠道。个人通知渠道：`sms`、`voice`、`email`、`push`；IM 群聊渠道：`feishu_app:<chat_id>`、`dingtalk_app:<chat_id>`、`wecom_app:<chat_id>`、`slack_app:<chat_id>`、`teams_app:<chat_id>`。"
-                        },
-                        "warning": {
-                          "type": "array",
-                          "items": {
-                            "type": "string"
-                          },
-                          "description": "Warning 级别使用的通知渠道。取值同 `critical`。"
-                        },
-                        "info": {
-                          "type": "array",
-                          "items": {
-                            "type": "string"
-                          },
-                          "description": "Info 级别使用的通知渠道。取值同 `critical`。"
-                        }
-                      }
-                    },
-                    "webhooks": {
-                      "type": "array",
-                      "description": "群聊/Webhook 通知目标。未提供 `by` 时必填。",
-                      "items": {
-                        "type": "object",
-                        "required": [
-                          "type",
-                          "settings"
-                        ],
-                        "properties": {
-                          "type": {
-                            "type": "string",
-                            "description": "Webhook 类型，可选值：`feishu`、`feishu_app`、`dingtalk`、`dingtalk_app`、`wecom`、`slack`、`slack_app`、`teams_app`、`telegram`、`zoom`。"
-                          },
-                          "settings": {
-                            "type": "object",
-                            "additionalProperties": true,
-                            "description": "类型相关的配置参数(群聊 ID、URL 等)。"
-                          }
-                        }
-                      }
-                    }
-                  }
-                },
-                "escalate_window": {
-                  "type": "integer",
-                  "minimum": 0,
-                  "maximum": 720,
-                  "description": "升级到下一环节前的等待时长,单位分钟。"
-                },
-                "force_escalate": {
-                  "type": "boolean",
-                  "description": "为 true 时,即便未认领也强制升级。"
-                }
-              }
-            }
+              "$ref": "#/components/schemas/EscalateLayer"
+            },
+            "description": "按顺序排列的通知环节，故障从第一个环节开始。"
           },
           "time_filters": {
             "type": "array",
             "items": {
-              "type": "object",
-              "description": "周期性时间窗口。`start`/`end` 使用 24 小时制 `HH:MM` 格式;`repeat` 使用星期索引(0=周日 … 6=周六)。",
-              "properties": {
-                "start": {
-                  "type": "string",
-                  "description": "窗口起始时间,`HH:MM`。"
-                },
-                "end": {
-                  "type": "string",
-                  "description": "窗口结束时间,`HH:MM`。"
-                },
-                "repeat": {
-                  "type": "array",
-                  "items": {
-                    "type": "integer"
-                  },
-                  "description": "生效的星期列表,留空表示每天。"
-                },
-                "cal_id": {
-                  "type": "string",
-                  "description": "可选日历 ID,限制窗口仅在日历匹配的日期生效。"
-                },
-                "is_off": {
-                  "type": "boolean",
-                  "description": "为 true 时匹配日历中的休息日。"
-                }
-              }
+              "$ref": "#/components/schemas/TimeFilter"
             },
-            "description": "可选的周期性生效时间窗口。"
+            "description": "策略可参与匹配的周期时间窗口；不传或为空表示任何时间。"
           },
           "filters": {
-            "type": "array",
-            "description": "故障级匹配条件（OR-of-AND 结构）：策略匹配的是告警聚合而成的故障，而不是告警本身。不传或为空时对空间内所有故障生效。",
-            "items": {
-              "type": "array",
-              "items": {
-                "type": "object",
-                "required": [
-                  "key",
-                  "oper",
-                  "vals"
-                ],
-                "properties": {
-                  "key": {
-                    "type": "string",
-                    "description": "字段键(如 `alert_severity`、`labels.service`)。"
-                  },
-                  "oper": {
-                    "type": "string",
-                    "enum": [
-                      "IN",
-                      "NOTIN"
-                    ],
-                    "description": "过滤运算符。"
-                  },
-                  "vals": {
-                    "type": "array",
-                    "items": {
-                      "type": "string"
-                    },
-                    "description": "匹配值列表。"
-                  }
-                }
-              }
-            }
+            "$ref": "#/components/schemas/FilterGroup",
+            "description": "故障匹配条件（AND 组之间为 OR），匹配的是告警所属的故障而不是告警本身。可用字段：`title`、`description`、`severity`（别名 `incident_severity`、`alert_severity`）、`status`（别名 `incident_status`、`alert_status`）、`dedup_key`、`integration_id`（别名 `data_source_id`），或任意 `labels.<name>`。不传或为空时匹配协作空间内的所有故障。"
           }
         }
       },
@@ -21373,7 +21798,7 @@
           "title": {
             "type": "string",
             "maxLength": 512,
-            "description": "故障标题,最多 512 个字符。"
+            "description": "故障标题，最多 512 个字符。账户配置了创建表单时必填且不能为空。"
           },
           "description": {
             "type": "string",
@@ -21383,11 +21808,11 @@
           "channel_id": {
             "type": "integer",
             "format": "int64",
-            "description": "归属的协作空间 ID,留空表示独立故障。"
+            "description": "故障所属的协作空间，须在账户中存在。除非账户配置了创建表单，否则可不填；不填即为独立故障。"
           },
           "assigned_to": {
             "type": "object",
-            "description": "故障指派目标。可整体省略：省略或为空时按协作空间的默认分派处理；账户的创建表单生效时必填。`person_ids`、`escalate_rule_id`、`emails` 可同时设置，处理人员取并集。",
+            "description": "分派对象。省略或为空时由协作空间的分派策略决定（独立故障不会有处理人员）；账户配置了创建表单时必填。`person_ids`、`escalate_rule_id` 和 `emails` 可同时设置，处理人员取并集。分派在创建之后执行，分派失败不会撤销故障。",
             "properties": {
               "person_ids": {
                 "type": "array",
@@ -21406,7 +21831,7 @@
               },
               "layer_idx": {
                 "type": "integer",
-                "description": "分派策略的起始环节索引，从 0 开始（默认 0，即第一个环节）；超出环节数会报错。仅在设置 `escalate_rule_id` 时有效。"
+                "description": "要分派的分派策略环节，从 0 开始（默认 0，即第一个环节）。仅与 `escalate_rule_id` 一起生效；越界时请求不会失败，但故障不会有处理人员。"
               },
               "type": {
                 "type": "string",
@@ -21416,7 +21841,7 @@
                   "escalate",
                   "reopen"
                 ],
-                "description": "指派类型，由服务端自动推导，调用方无需传值：手动创建为 `assign`，再次指派为 `reassign`，升级触发为 `escalate`。\n| 值 | 含义 |\n|---|---|\n| `assign` | 手动创建故障时的首次指派。 |\n| `reassign` | 对已有故障的再次指派。 |\n| `escalate` | 分派策略升级触发的指派。 |\n| `reopen` | 故障重新打开后从第一环节重新开始的分派。 |"
+                "description": "分派类型。通常无需传：服务端会设为 `assign`，因为手动创建总是首次分派。若传入则按原值保存。\n- `assign`：故障的首次分派。\n- `reassign`：替换之前分派的重新分派。\n- `escalate`：升级到下一环节触发的分派。\n- `reopen`：故障重新打开后从第一个环节重新分派。"
               },
               "emails": {
                 "type": "array",
@@ -21444,7 +21869,7 @@
                     "items": {
                       "type": "string"
                     },
-                    "description": "使用的通知渠道(如 `voice`、`sms`、`email`)。"
+                    "description": "`follow_preference` 为 false 时使用的通知渠道：`sms`、`voice`、`email`、`push`，或以 `feishu_app:`、`dingtalk_app:`、`wecom_app:`、`slack_app:`、`teams_app:` 为前缀的 IM 应用渠道。"
                   },
                   "template_id": {
                     "type": "string",
@@ -21476,7 +21901,7 @@
           },
           "title": {
             "type": "string",
-            "description": "回显请求中传入的故障标题。"
+            "description": "请求中传入的故障标题；请求未传标题时为空。"
           }
         }
       },
@@ -21510,79 +21935,15 @@
             "items": {
               "type": "string"
             },
-            "description": "源（抑制方）告警与目标（被抑制）告警之间必须取值相等的字段键，例如 `data_source_id` 或 `labels.cluster`。"
+            "description": "源告警与新事件取值必须相同的字段。只有 `title`、`severity` 和 `labels.<name>` 有效；其他字段（例如 `data_source_id`）虽能保存，但会导致策略永远不生效。必须传入；空数组同样使策略不生效。"
           },
           "source_filters": {
-            "type": "array",
-            "description": "源告警需要满足的条件，针对已存的活跃告警求值。支持的键：`status`、`incident_status`、`alert_status`、`severity`、`incident_severity`、`alert_severity`、`title`、`description` 或任意 `labels.<name>`。为空时策略不生效。",
-            "items": {
-              "type": "array",
-              "items": {
-                "type": "object",
-                "required": [
-                  "key",
-                  "oper",
-                  "vals"
-                ],
-                "properties": {
-                  "key": {
-                    "type": "string",
-                    "description": "字段键(如 `alert_severity`、`labels.service`)。"
-                  },
-                  "oper": {
-                    "type": "string",
-                    "enum": [
-                      "IN",
-                      "NOTIN"
-                    ],
-                    "description": "过滤运算符。"
-                  },
-                  "vals": {
-                    "type": "array",
-                    "items": {
-                      "type": "string"
-                    },
-                    "description": "匹配值列表。"
-                  }
-                }
-              }
-            }
+            "$ref": "#/components/schemas/FilterGroup",
+            "description": "源告警（起抑制作用的告警）需满足的条件，匹配对象是协作空间内已存储的活跃告警。可用字段：`title`、`description`、`severity`（别名 `incident_severity`、`alert_severity`）、`status`（别名 `incident_status`、`alert_status`），或任意 `labels.<name>`。为空时策略不生效。"
           },
           "target_filters": {
-            "type": "array",
-            "description": "目标（被抑制）告警事件需要满足的条件；为空表示所有事件都是抑制目标。",
-            "items": {
-              "type": "array",
-              "items": {
-                "type": "object",
-                "required": [
-                  "key",
-                  "oper",
-                  "vals"
-                ],
-                "properties": {
-                  "key": {
-                    "type": "string",
-                    "description": "字段键(如 `alert_severity`、`labels.service`)。"
-                  },
-                  "oper": {
-                    "type": "string",
-                    "enum": [
-                      "IN",
-                      "NOTIN"
-                    ],
-                    "description": "过滤运算符。"
-                  },
-                  "vals": {
-                    "type": "array",
-                    "items": {
-                      "type": "string"
-                    },
-                    "description": "匹配值列表。"
-                  }
-                }
-              }
-            }
+            "$ref": "#/components/schemas/FilterGroup",
+            "description": "新进入的告警事件需满足的条件，满足才会被抑制；为空表示所有新事件都是抑制对象。可用字段：`title`、`description`、`severity`（别名 `alert_severity`、`event_severity`）、`status`、`alert_key`、`title_rule`、`integration_id`（别名 `data_source_id`），或任意 `labels.<name>`。"
           },
           "is_directly_discard": {
             "type": "boolean",
@@ -21616,99 +21977,23 @@
           },
           "from_incident_id": {
             "type": "string",
-            "description": "策略关联的故障 ID（ObjectID 十六进制）。可选；设置后每个故障最多存在一条启用中的静默策略。",
+            "description": "创建该策略所依据的故障 ID（24 位十六进制）。故障必须存在，且每个故障只能有一条启用的静默策略。",
             "pattern": "^[0-9a-fA-F]{24}$"
           },
           "time_filters": {
             "type": "array",
             "items": {
-              "type": "object",
-              "description": "周期性时间窗口。`start`/`end` 使用 24 小时制 `HH:MM` 格式;`repeat` 使用星期索引(0=周日 … 6=周六)。",
-              "properties": {
-                "start": {
-                  "type": "string",
-                  "description": "窗口起始时间,`HH:MM`。"
-                },
-                "end": {
-                  "type": "string",
-                  "description": "窗口结束时间,`HH:MM`。"
-                },
-                "repeat": {
-                  "type": "array",
-                  "items": {
-                    "type": "integer"
-                  },
-                  "description": "生效的星期列表,留空表示每天。"
-                },
-                "cal_id": {
-                  "type": "string",
-                  "description": "可选日历 ID,限制窗口仅在日历匹配的日期生效。"
-                },
-                "is_off": {
-                  "type": "boolean",
-                  "description": "为 true 时匹配日历中的休息日。"
-                }
-              }
+              "$ref": "#/components/schemas/TimeFilter"
             },
-            "description": "生效的周期性时间窗口列表,与 `time_filter` 互斥。"
+            "description": "周期静默窗口。`time_filters` 与 `time_filter` 必须且只能设置其一。"
           },
           "time_filter": {
-            "type": "object",
-            "description": "一次性时间窗口,使用 Unix 秒定义。",
-            "required": [
-              "start_time",
-              "end_time"
-            ],
-            "properties": {
-              "start_time": {
-                "type": "integer",
-                "format": "int64",
-                "description": "窗口起始时间，Unix 秒时间戳。必须大于 0 且小于 `end_time`。",
-                "exclusiveMinimum": 0
-              },
-              "end_time": {
-                "type": "integer",
-                "format": "int64",
-                "description": "窗口结束时间，Unix 秒时间戳。必须大于 0。",
-                "exclusiveMinimum": 0
-              }
-            }
+            "$ref": "#/components/schemas/OnceTimeFilter",
+            "description": "一次性静默窗口。`time_filter` 与 `time_filters` 必须且只能设置其一。"
           },
           "filters": {
-            "type": "array",
-            "description": "告警事件匹配条件（OR-of-AND 结构）。必填且至少包含一个条件。",
-            "items": {
-              "type": "array",
-              "items": {
-                "type": "object",
-                "required": [
-                  "key",
-                  "oper",
-                  "vals"
-                ],
-                "properties": {
-                  "key": {
-                    "type": "string",
-                    "description": "字段键(如 `alert_severity`、`labels.service`)。"
-                  },
-                  "oper": {
-                    "type": "string",
-                    "enum": [
-                      "IN",
-                      "NOTIN"
-                    ],
-                    "description": "过滤运算符。"
-                  },
-                  "vals": {
-                    "type": "array",
-                    "items": {
-                      "type": "string"
-                    },
-                    "description": "匹配值列表。"
-                  }
-                }
-              }
-            }
+            "$ref": "#/components/schemas/FilterGroup",
+            "description": "告警事件匹配条件（AND 组之间为 OR），时间窗口内命中的事件被静默。必填，且至少包含一个条件。可用字段：`title`、`description`、`severity`（别名 `alert_severity`、`event_severity`）、`status`、`alert_key`、`title_rule`、`integration_id`（别名 `data_source_id`），或任意 `labels.<name>`。"
           },
           "is_directly_discard": {
             "type": "boolean",
@@ -21716,7 +22001,7 @@
           },
           "is_auto_delete": {
             "type": "boolean",
-            "description": "为 true 时，静默规则在时间窗结束后会被自动删除；默认为 false。"
+            "description": "为 true 时，使用一次性 `time_filter` 的策略在 `end_time`（或最近一次更新时间，取较晚者）约 24 小时后被永久移除。通过 `from_incident_id` 创建的策略同样按此方式清理。使用周期 `time_filters` 的策略不会被自动移除。默认 `false`。"
           }
         }
       },
@@ -21770,7 +22055,7 @@
           "start_at_seconds": {
             "type": "integer",
             "format": "int64",
-            "description": "事件开始时间（Unix 秒）。存储的开始时间始终以第一条更新的 `at_seconds` 为准（该字段缺省时取当前时间）；对于开启 `auto_update_by_schedule` 的维护事件，本字段用于调度自动切换为 `ongoing` 的任务。"
+            "description": "事件开始时间，Unix 时间戳（秒）。维护事件会将其保存为计划开始时间（开启 `auto_update_by_schedule` 时即切换为 `ongoing` 的时间）；省略或为 0 时，以及故障事件，开始时间一律取第一条更新的 `at_seconds`。"
           },
           "responders": {
             "type": "array",
@@ -21790,7 +22075,7 @@
           "close_at_seconds": {
             "type": "integer",
             "format": "int64",
-            "description": "事件结束时间（Unix 秒），必须大于或等于第一条更新的 `at_seconds`。回溯事件用它表示结束时间；对于开启 `auto_update_by_schedule` 的维护事件，它用于调度自动切换为 `completed` 的任务，且距当前时间不能超过 30 天。"
+            "description": "事件结束时间，Unix 时间戳（秒），必须大于或等于第一条更新的 `at_seconds`。维护事件为计划结束时间；开启 `auto_update_by_schedule` 时会在该时间切换为 `completed`，且必须在当前时间起 30 天内。复盘事件处于终态且未传此字段时，取最后一条更新的时间。"
           },
           "updates": {
             "type": "array",
@@ -21860,12 +22145,12 @@
                 }
               }
             },
-            "description": "时间线更新列表。至少传 1 条，且至少有一条必须包含 `component_changes`。即时事件一般只传一条；回溯事件需传入全部历史更新。",
+            "description": "时间线更新，须按 `at_seconds` 非递减排列。至少需要一条更新，且至少一条包含 `component_changes`。即时事件通常传一条；复盘事件至少传两条。",
             "minItems": 1
           },
           "notify_subscribers": {
             "type": "boolean",
-            "description": "是否通知订阅者本事件及其所有更新。"
+            "description": "是否通知订阅者。创建时仅针对最后一条更新发送一次通知；之后发布的时间线更新在该值为 `true` 时也会通知。"
           },
           "auto_update_by_schedule": {
             "type": "boolean",
@@ -21873,7 +22158,11 @@
           },
           "is_retrospective": {
             "type": "boolean",
-            "description": "标记为回溯(历史)事件。"
+            "description": "将事件标记为复盘事件（事后补录的历史事件）。要求 `updates` 至少两条。"
+          },
+          "draft_id": {
+            "type": "string",
+            "description": "随本次创建一并发布的草稿 ID，由 `POST /status-page/draft/create` 返回。草稿须处于待发布状态、指向本 `page_id` 和 `type` 且不带 `change_id`；事件创建成功后草稿标记为已发布。不发布草稿时省略。"
           }
         }
       },
@@ -21900,7 +22189,7 @@
           "at_seconds": {
             "type": "integer",
             "format": "int64",
-            "description": "更新时间戳（Unix 秒），缺省或为 0 时取当前时间。"
+            "description": "更新时间，Unix 时间戳（秒），不能早于事件最新一条时间线更新。省略或为 0 时取当前时间。"
           },
           "status": {
             "type": "string",
@@ -21913,7 +22202,7 @@
               "ongoing",
               "completed"
             ],
-            "description": "更新后的事件状态，需与事件类型匹配。当状态切换为 `resolved` 或 `completed` 时，所有受影响组件必须恢复为 `operational`。\n| 值 | 含义 |\n|---|---|\n| `investigating` | 排查中（incident）。 |\n| `identified` | 已定位原因（incident）。 |\n| `monitoring` | 已修复，观察中（incident）。 |\n| `resolved` | 已解决（incident）。 |\n| `scheduled` | 已计划（maintenance）。 |\n| `ongoing` | 进行中（maintenance）。 |\n| `completed` | 已完成（maintenance）。 |"
+            "description": "本次更新后的事件状态，必须与事件类型匹配。若不改变状态，请传入当前状态。切换为 `resolved` 或 `completed` 时，所有受影响组件必须已恢复为 `operational`。\n| 取值 | 含义 |\n|---|---|\n| `investigating` | 调查中（故障）。 |\n| `identified` | 已定位原因（故障）。 |\n| `monitoring` | 已修复，观察中（故障）。 |\n| `resolved` | 已解决（故障）。 |\n| `scheduled` | 已计划（维护）。 |\n| `ongoing` | 进行中（维护）。 |\n| `completed` | 已完成（维护）。 |"
           },
           "description": {
             "type": "string",
@@ -21946,6 +22235,10 @@
               }
             },
             "description": "本次更新应用的组件状态变更。组件 ID 不能重复。"
+          },
+          "draft_id": {
+            "type": "string",
+            "description": "待发布草稿的 ID（由 `POST /status-page/draft/create` 返回，且其 `change_id` 指向本事件）；更新写入后草稿标记为已发布。不发布草稿时省略。"
           }
         }
       },
@@ -21958,12 +22251,110 @@
         "properties": {
           "draft": {
             "type": "object",
-            "description": "草稿载荷，原样存储，序列化后最大 64 KB。被校验的字段：`page_id`、`type`（`incident` 或 `maintenance`）、`name`、`message`；可选 `change_id`（大于 0 时表示向已有事件追加进展）、`status`、`affected_components`，以及 `start_time`/`end_time`（Unix epoch 秒，仅新建维护窗口时使用）。"
+            "description": "草稿载荷，原样存储（序列化后最大 64 KB）。服务端校验以下字段，其他字段原样保留供控制台使用。",
+            "required": [
+              "page_id",
+              "type",
+              "name",
+              "message"
+            ],
+            "additionalProperties": true,
+            "properties": {
+              "v": {
+                "type": "integer",
+                "description": "由生成方指定的载荷格式版本；仅存储，不解析。"
+              },
+              "page_id": {
+                "type": "integer",
+                "format": "int64",
+                "description": "目标状态页 ID，必须属于调用方账户。"
+              },
+              "page_name": {
+                "type": "string",
+                "description": "供控制台展示的状态页名称，不做校验。"
+              },
+              "type": {
+                "type": "string",
+                "enum": [
+                  "incident",
+                  "maintenance"
+                ],
+                "description": "草稿要创建或更新的事件类型：`incident` 为非计划故障，`maintenance` 为计划维护。"
+              },
+              "name": {
+                "type": "string",
+                "maxLength": 255,
+                "description": "事件标题，1 到 255 个字符。"
+              },
+              "message": {
+                "type": "string",
+                "description": "事件或更新的描述（Markdown），不能为空。"
+              },
+              "change_id": {
+                "type": "integer",
+                "format": "int64",
+                "description": "要追加更新的事件，必须是 `page_id` 上同一 `type` 的事件。省略或传 0 表示起草新事件。"
+              },
+              "status": {
+                "type": "string",
+                "enum": [
+                  "investigating",
+                  "identified",
+                  "monitoring",
+                  "resolved",
+                  "scheduled",
+                  "ongoing",
+                  "completed"
+                ],
+                "description": "建议的事件状态；传入时必须与 `type` 匹配（故障为 `investigating`/`identified`/`monitoring`/`resolved`，维护为 `scheduled`/`ongoing`/`completed`）。"
+              },
+              "affected_components": {
+                "type": "array",
+                "description": "草稿涉及的组件。",
+                "items": {
+                  "type": "object",
+                  "required": [
+                    "component_id"
+                  ],
+                  "properties": {
+                    "component_id": {
+                      "type": "string",
+                      "description": "组件 ID，必须存在于该状态页。"
+                    },
+                    "name": {
+                      "type": "string",
+                      "description": "供展示的组件名称，不做校验。"
+                    },
+                    "status": {
+                      "type": "string",
+                      "enum": [
+                        "operational",
+                        "degraded",
+                        "partial_outage",
+                        "full_outage",
+                        "under_maintenance"
+                      ],
+                      "description": "建议的组件状态；传入时必须与 `type` 匹配（故障为 `operational`/`degraded`/`partial_outage`/`full_outage`，维护为 `operational`/`under_maintenance`）。"
+                    }
+                  }
+                }
+              },
+              "start_time": {
+                "type": "integer",
+                "format": "int64",
+                "description": "新维护事件的计划开始时间，Unix 时间戳（秒）。"
+              },
+              "end_time": {
+                "type": "integer",
+                "format": "int64",
+                "description": "新维护事件的计划结束时间，Unix 时间戳（秒）；与 `start_time` 同时传入时必须大于 `start_time`。"
+              }
+            }
           },
           "source": {
             "type": "string",
             "maxLength": 64,
-            "description": "草稿来源的不透明标记，例如 `ai_sre:sess_xxx`。最长 64 个字符。"
+            "description": "记录草稿来源的自由文本（例如 AI 会话标识），随草稿存储和展示，服务端不解析。最多 64 个字符。"
           }
         }
       },
@@ -21983,7 +22374,7 @@
           "integration_id": {
             "type": "integer",
             "format": "int64",
-            "description": "IM 集成 ID。需开启作战室能力;当前支持飞书、钉钉、企业自建企业微信、Slack 与 Teams。"
+            "description": "已开启作战室功能的 IM 集成 ID，可通过 `POST /datasource/im/war-room-enabled/list` 获取。支持飞书、钉钉、企业微信（仅自建应用）和 Slack。"
           },
           "member_ids": {
             "type": "array",
@@ -21991,11 +22382,11 @@
               "type": "integer",
               "format": "int64"
             },
-            "description": "额外加入作战室的成员 ID 列表。"
+            "description": "要邀请进群的成员 ID；每个 ID 都必须是账户中的有效成员。"
           },
           "add_observers": {
             "type": "boolean",
-            "description": "为 true 时同时将历史处理人员加入作战室作为观察员。"
+            "description": "为 true 时，同时邀请曾被分派或添加为处理人、但当前已不是处理人的成员。"
           }
         }
       },
@@ -22074,6 +22465,14 @@
             "type": "integer",
             "format": "int64",
             "description": "IM 集成 ID，可通过 `POST /datasource/im/war-room-enabled/list` 获取。"
+          },
+          "unlink_only": {
+            "type": "boolean",
+            "description": "为 true 时只解除故障与作战室的关联，不解散群组。仅限账户所有者和管理员，仅在 IM 集成已禁用或已删除时可用，且必须传 `chat_id`。"
+          },
+          "chat_id": {
+            "type": "string",
+            "description": "要解除关联的作战室群 ID，取自 `POST /incident/war-room/list`。`unlink_only` 为 `true` 时必填，且必须与当前作战室一致；其他情况忽略。"
           }
         }
       },
@@ -22203,7 +22602,7 @@
             "items": {
               "$ref": "#/components/schemas/DimensionInsightItem"
             },
-            "description": "按接口维度（账户/团队/协作空间）聚合的洞察指标行；启用 `split_hours` 或 `aggregate_unit` 时会进一步按时段或时间桶拆分。"
+            "description": "指标行，按时间桶从新到旧排列。没有故障的时间桶或维度取值不产生行；空数组表示没有匹配的故障。"
           }
         }
       },
@@ -22246,12 +22645,15 @@
         }
       },
       "DoIncidentCustomActionResponse": {
-        "type": "object",
-        "description": "自定义操作的执行结果。",
+        "type": [
+          "object",
+          "null"
+        ],
+        "description": "操作的 HTTP 请求成功时为 `null`；失败时为包含 `message` 的对象。",
         "properties": {
           "message": {
             "type": "string",
-            "description": "HTTP 调用失败时的错误信息，成功时不返回。"
+            "description": "请求操作地址时返回的错误（例如 2 秒超时）。"
           }
         }
       },
@@ -22264,7 +22666,7 @@
           },
           "message": {
             "type": "string",
-            "description": "用户可读的错误描述，语言会跟随调用方的 Accept-Language。可能包含字段名、ID 等请求上下文。",
+            "description": "按响应语言（query 参数 `locale` / `lang` 或请求头 `Accept-Language`）返回的错误描述，可能包含出错的字段名，请不要解析它。",
             "example": "The specified parameter template_id is not valid."
           }
         },
@@ -22285,7 +22687,7 @@
       },
       "EmptyResponse": {
         "type": "object",
-        "description": "空响应体。成功时服务端返回 `data: null`。",
+        "description": "无返回数据。不同接口的 `data` 可能是 `{}`，也可能不出现在响应中；请只根据 HTTP 200 且没有 `error` 判断成功。",
         "properties": {}
       },
       "EnrichFilter": {
@@ -22299,7 +22701,7 @@
         "properties": {
           "key": {
             "type": "string",
-            "description": "要匹配的事件键（如 `labels.severity`、`title`），不能为空。",
+            "description": "要匹配的事件键：`title`、`description`、`labels.<name>` 或其他告警 / 变更事件键。`labels.<name>` 中的标签名须合法。",
             "minLength": 1
           },
           "oper": {
@@ -22308,14 +22710,14 @@
               "IN",
               "NOTIN"
             ],
-            "description": "匹配操作符。`IN` 表示任一值匹配即通过；`NOTIN` 表示所有值均不匹配时通过。"
+            "description": "匹配操作符。\n- `IN`：键的值匹配 `vals` 中任意一个即命中；事件中不存在该键时不命中。\n- `NOTIN`：键的值不匹配 `vals` 中任何一个即命中；事件中不存在该键时总是命中。"
           },
           "vals": {
             "type": "array",
             "items": {
               "type": "string"
             },
-            "description": "匹配值列表，至少包含 1 个。",
+            "description": "要匹配的值（至少一个）。每个值可以是：精确字符串；`/regex/` 形式的正则表达式；含 `*`、`?` 的通配符；`cidr:<CIDR>`（如 `cidr:203.0.113.0/24`）表示 IP 网段；`num:lt:<n>`、`num:le:<n>`、`num:gt:<n>`、`num:ge:<n>` 表示数值比较。",
             "minItems": 1
           }
         }
@@ -22397,14 +22799,14 @@
           "integration_id": {
             "type": "integer",
             "format": "int64",
-            "description": "集成 ID。"
+            "description": "该规则集所属集成的 ID；每个集成最多一个规则集。"
           },
           "rules": {
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/EnrichRule"
             },
-            "description": "有序富化规则列表。"
+            "description": "按执行顺序排列的规则；后面的规则能看到前面规则写入的标签。"
           },
           "status": {
             "type": "string",
@@ -22499,13 +22901,13 @@
             "items": {
               "$ref": "#/components/schemas/EnrichRule"
             },
-            "description": "富化规则有序列表，将原子替换现有全部规则。"
+            "description": "有序的规则列表，整体替换该集成的规则集；传 `[]` 可删除全部规则。规则按此顺序执行。"
           }
         }
       },
       "ErrorCode": {
         "type": "string",
-        "description": "Flashduty 错误码枚举。每个失败响应的 `error.code` 都是下列稳定值之一，HTTP 状态码仅作参考。\n\n| 错误码 | HTTP | 含义 |\n|---|---|---|\n| `OK` | 200 | 保留值，正常错误响应不会返回。 |\n| `InvalidParameter` | 400 | 必填参数缺失或未通过校验。 |\n| `BadRequest` | 400 | 通用的 400 错误，通常是请求本身不合法。 |\n| `InvalidContentType` | 400 | 请求头 `Content-Type` 不是 `application/json`。 |\n| `ResourceNotFound` | 400 | 目标资源不存在。注意 HTTP 状态码是 400 而非 404（历史设计）。 |\n| `NoLicense` | 400 | 功能需要有效授权，但未找到可用的 license。 |\n| `ReferenceExist` | 400 | 该资源仍被其他实体引用，无法删除。 |\n| `Unauthorized` | 401 | `app_key` 缺失、无效或已过期。 |\n| `BalanceNotEnough` | 402 | 账户余额不足，无法执行需要计费的操作。 |\n| `AccessDenied` | 403 | 身份认证通过，但 RBAC 权限不足以执行该操作。 |\n| `RouteNotFound` | 404 | 请求的 URL 路径不是已知路由。 |\n| `MethodNotAllowed` | 405 | 当前路径不接受所使用的 HTTP 方法。 |\n| `UndonedOrderExist` | 409 | 账户存在未完成的订单，请稍后重试。 |\n| `RequestLocked` | 423 | 因连续失败被临时锁定。 |\n| `EntityTooLarge` | 413 | 请求体超过允许的最大长度。 |\n| `RequestTooFrequently` | 429 | 命中限流（全局、账户级或集成级）。 |\n| `RequestVerifyRequired` | 428 | 操作需要二次验证码，但未提供。 |\n| `DangerousOperation` | 428 | 危险操作，需要进行 MFA 验证。 |\n| `InternalError` | 500 | 服务端未预期错误。反馈问题请附上 `request_id`。 |\n| `ServiceUnavailable` | 503 | 后端依赖不可用，请稍后重试。 |",
+        "description": "错误码。所有失败响应都会把 `error.code` 设为下列稳定字符串之一，请以它而不是 HTTP 状态码做判断。\n\n| 错误码 | HTTP | 含义 |\n|---|---|---|\n| `OK` | 200 | 保留值，失败的请求不会返回。 |\n| `InvalidParameter` | 400 | 参数缺失、类型错误或未通过校验，`message` 通常会指出字段名。 |\n| `BadRequest` | 400 | 请求违反业务规则或与对象当前状态冲突，`message` 会说明原因。 |\n| `InvalidContentType` | 400 | 请求体没有以 `application/json` 发送。 |\n| `ResourceNotFound` | 400 | 引用的对象在本账户中不存在或已删除。注意 HTTP 状态码是 400 而不是 404。 |\n| `NoLicense` | 400 | 账户套餐不包含该功能、套餐配额已用完、套餐已过期或额度不足。 |\n| `ReferenceExist` | 400 | 对象仍被其他对象引用，无法删除。 |\n| `Unauthorized` | 401 | APP Key 缺失、无效或已删除。 |\n| `BalanceNotEnough` | 402 | 仅用于控制台计费流程，Open API 接口不会返回。 |\n| `AccessDenied` | 403 | APP Key 的权限范围或创建者角色不允许该操作或该对象。 |\n| `RouteNotFound` | 404 | 没有与该 HTTP 方法和路径匹配的接口。 |\n| `MethodNotAllowed` | 405 | 路径存在，但不支持该 HTTP 方法。 |\n| `UndonedOrderExist` | 409 | 仅用于控制台计费流程，Open API 接口不会返回。 |\n| `EntityTooLarge` | 413 | 请求体超出大小限制。 |\n| `RequestLocked` | 423 | 仅用于控制台登录保护，Open API 接口不会返回。 |\n| `RequestVerifyRequired` | 428 | 仅用于控制台验证码流程，Open API 接口不会返回。 |\n| `DangerousOperation` | 428 | 仅用于控制台高风险操作的 MFA 校验，Open API 接口不会返回。 |\n| `RequestTooFrequently` | 429 | 触发频率限制；请等待响应头 `Flashcat-Request-Rate-Limit-Delay` 给出的秒数后再重试。 |\n| `InternalError` | 500 | 服务端意外错误；请退避后重试，反馈问题时附上 `request_id`。 |\n| `ServiceUnavailable` | 503 | 后端依赖过载或不可用，请退避后重试。 |",
         "enum": [
           "OK",
           "InvalidParameter",
@@ -22520,35 +22922,35 @@
           "RouteNotFound",
           "MethodNotAllowed",
           "UndonedOrderExist",
-          "RequestLocked",
           "EntityTooLarge",
-          "RequestTooFrequently",
+          "RequestLocked",
           "RequestVerifyRequired",
           "DangerousOperation",
+          "RequestTooFrequently",
           "InternalError",
           "ServiceUnavailable"
         ],
         "x-enumDescriptions": {
-          "OK": "保留值，正常错误响应不会返回。",
-          "InvalidParameter": "必填参数缺失或未通过校验。",
-          "BadRequest": "通用的 400 错误，通常是请求本身不合法。",
-          "InvalidContentType": "请求头 `Content-Type` 不是 `application/json`。",
-          "ResourceNotFound": "目标资源不存在。注意 HTTP 状态码是 400 而非 404（历史设计）。",
-          "NoLicense": "功能需要有效授权，但未找到可用的 license。",
-          "ReferenceExist": "该资源仍被其他实体引用，无法删除。",
-          "Unauthorized": "`app_key` 缺失、无效或已过期。",
-          "BalanceNotEnough": "账户余额不足，无法执行需要计费的操作。",
-          "AccessDenied": "身份认证通过，但 RBAC 权限不足以执行该操作。",
-          "RouteNotFound": "请求的 URL 路径不是已知路由。",
-          "MethodNotAllowed": "当前路径不接受所使用的 HTTP 方法。",
-          "UndonedOrderExist": "账户存在未完成的订单，请稍后重试。",
-          "RequestLocked": "因连续失败被临时锁定。",
-          "EntityTooLarge": "请求体超过允许的最大长度。",
-          "RequestTooFrequently": "命中限流（全局、账户级或集成级）。",
-          "RequestVerifyRequired": "操作需要二次验证码，但未提供。",
-          "DangerousOperation": "危险操作，需要进行 MFA 验证。",
-          "InternalError": "服务端未预期错误。反馈问题请附上 `request_id`。",
-          "ServiceUnavailable": "后端依赖不可用，请稍后重试。"
+          "OK": "保留值，失败的请求不会返回。",
+          "InvalidParameter": "参数缺失、类型错误或未通过校验，`message` 通常会指出字段名。",
+          "BadRequest": "请求违反业务规则或与对象当前状态冲突，`message` 会说明原因。",
+          "InvalidContentType": "请求体没有以 `application/json` 发送。",
+          "ResourceNotFound": "引用的对象在本账户中不存在或已删除。注意 HTTP 状态码是 400 而不是 404。",
+          "NoLicense": "账户套餐不包含该功能、套餐配额已用完、套餐已过期或额度不足。",
+          "ReferenceExist": "对象仍被其他对象引用，无法删除。",
+          "Unauthorized": "APP Key 缺失、无效或已删除。",
+          "BalanceNotEnough": "仅用于控制台计费流程，Open API 接口不会返回。",
+          "AccessDenied": "APP Key 的权限范围或创建者角色不允许该操作或该对象。",
+          "RouteNotFound": "没有与该 HTTP 方法和路径匹配的接口。",
+          "MethodNotAllowed": "路径存在，但不支持该 HTTP 方法。",
+          "UndonedOrderExist": "仅用于控制台计费流程，Open API 接口不会返回。",
+          "EntityTooLarge": "请求体超出大小限制。",
+          "RequestLocked": "仅用于控制台登录保护，Open API 接口不会返回。",
+          "RequestVerifyRequired": "仅用于控制台验证码流程，Open API 接口不会返回。",
+          "DangerousOperation": "仅用于控制台高风险操作的 MFA 校验，Open API 接口不会返回。",
+          "RequestTooFrequently": "触发频率限制；请等待响应头 `Flashcat-Request-Rate-Limit-Delay` 给出的秒数后再重试。",
+          "InternalError": "服务端意外错误；请退避后重试，反馈问题时附上 `request_id`。",
+          "ServiceUnavailable": "后端依赖过载或不可用，请退避后重试。"
         },
         "example": "InvalidParameter"
       },
@@ -22591,7 +22993,7 @@
           },
           "override": {
             "type": "boolean",
-            "description": "为 `true` 时若标签已存在则覆盖，默认为 `false`。"
+            "description": "为 `false`（默认）时，若事件已有 `result_label` 标签则跳过该规则；为 `true` 时覆盖已有值。"
           }
         }
       },
@@ -22607,7 +23009,8 @@
             "items": {
               "type": "string"
             },
-            "description": "待从告警中删除的标签键列表。"
+            "description": "要从事件中删除的标签名（至少一个），不带 `labels.` 前缀。",
+            "minItems": 1
           }
         }
       },
@@ -22630,15 +23033,15 @@
           },
           "pattern": {
             "type": "string",
-            "description": "应用于源值的 RE2 正则表达式，须至少包含一个捕获组；所有捕获组用空格连接后写入 `result_label`。与 `g_json` 互斥。"
+            "description": "作用于来源值的正则表达式（RE2），可以用 `/.../` 包裹。所有捕获组以空格拼接后写入 `result_label`。未匹配、没有捕获组或第一个捕获组为空时不写入。`pattern` 与 `g_json` 必须且只能设置一个。"
           },
           "g_json": {
             "type": "string",
-            "description": "GJson 路径表达式，用于从 JSON 编码的字段中提取值。与 `pattern` 互斥。"
+            "description": "当来源值是 JSON 字符串时使用的 GJSON 路径（开头的 `$.` 会被忽略），如 `host.name`。来源值不是合法 JSON 时跳过该规则；路径不存在时写入空字符串。`pattern` 与 `g_json` 必须且只能设置一个。"
           },
           "override": {
             "type": "boolean",
-            "description": "为 `true` 时若标签已存在则覆盖，默认为 `false`。"
+            "description": "为 `false`（默认）时，若事件已有 `result_label` 标签则跳过该规则；为 `true` 时覆盖已有值。"
           }
         }
       },
@@ -22655,7 +23058,8 @@
               "type": "string",
               "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$"
             },
-            "description": "映射查找结果要填充的标签键名，每个须匹配 `^[a-zA-Z_][a-zA-Z0-9_]*$`。"
+            "description": "要用查找结果填充的标签键（至少一个）。`schema` 方式下通常取映射规则的 `result_labels`；`api` 方式下会作为 `result_label_keys` 发送给 API。",
+            "minItems": 1
           },
           "mapping_type": {
             "type": "string",
@@ -22664,7 +23068,7 @@
               "api"
             ],
             "default": "schema",
-            "description": "映射来源类型。`schema` 使用映射规则表；`api` 调用外部 HTTP API。"
+            "description": "查找来源。\n- `schema`（默认）：用事件中该映射规则 `source_labels` 的值，在映射规则 `schema_id` 中查找数据行；缺少任一来源标签或未匹配到行时不生效。\n- `api`：携带事件调用映射 API `api_id`；只对告警事件生效。"
           },
           "schema_id": {
             "type": "string",
@@ -22676,7 +23080,7 @@
           },
           "override": {
             "type": "boolean",
-            "description": "为 `true` 时若标签已存在则覆盖，默认为 `false`。"
+            "description": "为 `false`（默认）时，若 `result_labels` 中的标签都已存在则跳过该规则，否则只填充缺失的标签；为 `true` 时用查找结果覆盖全部 `result_labels`。"
           }
         }
       },
@@ -22690,14 +23094,14 @@
             "type": "integer",
             "minimum": 0,
             "maximum": 6,
-            "description": "当前环节内的最大重复通知次数。"
+            "description": "本环节的通知总次数（含首次），0–6；`0` 和 `1` 都只通知一次。"
           },
           "notify_step": {
             "type": "number",
             "format": "float",
             "minimum": 0.5,
             "maximum": 120,
-            "description": "重复通知间隔，单位分钟。"
+            "description": "本环节重复通知的间隔（分钟），0.5–120，保留一位小数。仅当 `max_times` 大于 1 时生效。"
           },
           "target": {
             "$ref": "#/components/schemas/EscalateTarget"
@@ -22706,11 +23110,11 @@
             "type": "integer",
             "minimum": 0,
             "maximum": 720,
-            "description": "进入下一环节前的等待时间，单位分钟。"
+            "description": "本环节首次通知后等待多少分钟升级到下一环节，0–720。最后一个环节忽略此值。"
           },
           "force_escalate": {
             "type": "boolean",
-            "description": "为 true 时无论是否认领都强制升级。"
+            "description": "为 true 时，即使故障已被认领（`Processing`）也继续升级；为 false 时故障被认领后停止升级。已关闭或暂缓中的故障不会升级。"
           }
         }
       },
@@ -22746,15 +23150,15 @@
           },
           "priority": {
             "type": "integer",
-            "description": "匹配优先级，数值越小越优先。"
+            "description": "匹配顺序，取值 `0` 到 `200`：数值越小越先匹配，相同时按创建时间。第一条启用且时间窗口与过滤条件都命中新故障的策略负责该故障。"
           },
           "aggr_window": {
             "type": "integer",
-            "description": "延迟窗口，单位秒。"
+            "description": "新分派故障首次通知前的延迟（秒），0–3600；`0` 表示立即通知。"
           },
           "rule_name": {
             "type": "string",
-            "description": "策略名称。"
+            "description": "策略名称，1–39 个字符。"
           },
           "description": {
             "type": "string",
@@ -22772,11 +23176,11 @@
             "items": {
               "$ref": "#/components/schemas/TimeFilter"
             },
-            "description": "策略生效的周期性时间窗口。"
+            "description": "策略可参与匹配的周期时间窗口；为空表示任何时间。"
           },
           "filters": {
             "$ref": "#/components/schemas/FilterGroup",
-            "description": "故障级匹配条件（OR-of-AND 结构）：策略匹配的是告警聚合而成的故障，而不是告警本身。不传或为空时对空间内所有故障生效。"
+            "description": "故障匹配条件（AND 组之间为 OR），匹配的是告警所属的故障。为空表示匹配协作空间内的所有故障。"
           },
           "status": {
             "type": "string",
@@ -22790,7 +23194,7 @@
           "template_id": {
             "type": "string",
             "pattern": "^[0-9a-fA-F]{24}$",
-            "description": "通知模板 ID（MongoDB ObjectID）。"
+            "description": "通知模板 ID（24 位十六进制）；参见 `POST /template/list`。"
           },
           "rule_id": {
             "type": "string",
@@ -22816,10 +23220,6 @@
             "type": "integer",
             "format": "int64",
             "description": "最近更新时间，Unix 秒时间戳。"
-          },
-          "channel_name": {
-            "type": "string",
-            "description": "协作空间名称，跨空间列表响应会填充该字段。"
           }
         }
       },
@@ -22833,7 +23233,7 @@
               "type": "integer",
               "format": "int64"
             },
-            "description": "直接通知的成员 ID 列表。"
+            "description": "直接通知的成员 ID，可通过 `POST /member/list` 获取。每个 ID 都必须存在。"
           },
           "team_ids": {
             "type": "array",
@@ -22841,7 +23241,7 @@
               "type": "integer",
               "format": "int64"
             },
-            "description": "通知的团队 ID 列表。"
+            "description": "通知其成员的团队 ID，可通过 `POST /team/list` 获取。每个团队至少要有一名成员。"
           },
           "schedule_to_role_ids": {
             "type": "object",
@@ -22852,7 +23252,7 @@
                 "format": "int64"
               }
             },
-            "description": "值班表 ID 到角色 ID 列表的映射，用于按值班角色通知。"
+            "description": "通知当前值班人员：键为值班表 ID（来自 `POST /schedule/list`，以字符串形式书写），值为该值班表上的角色 ID 列表，且不能为空。"
           },
           "emails": {
             "type": "array",
@@ -22860,42 +23260,48 @@
               "type": "string",
               "format": "email"
             },
-            "description": "邮箱地址列表（推送场景）。"
+            "description": "账户成员的邮箱地址；环节触发时按邮箱解析为对应成员。"
           },
           "by": {
-            "type": "object",
-            "description": "按告警等级配置的个人通知渠道。未提供 `webhooks` 时必填。",
+            "type": [
+              "object",
+              "null"
+            ],
+            "description": "按故障严重程度为本目标中的人员配置的个人通知渠道。未设置 `webhooks` 时必填；未设置时返回 `null`。",
             "properties": {
               "follow_preference": {
                 "type": "boolean",
-                "description": "为 true 时跟随处理人员的个人偏好，忽略下方列表。"
+                "description": "为 true 时，按每个人在个人通知偏好中为该严重程度配置的渠道通知，忽略 `critical`、`warning`、`info`。"
               },
               "critical": {
                 "type": "array",
                 "items": {
                   "type": "string"
                 },
-                "description": "Critical 级别使用的通知渠道。个人通知渠道：`sms`、`voice`、`email`、`push`；IM 群聊渠道：`feishu_app:<chat_id>`、`dingtalk_app:<chat_id>`、`wecom_app:<chat_id>`、`slack_app:<chat_id>`、`teams_app:<chat_id>`。"
+                "description": "故障严重程度为 `Critical` 时使用的通知渠道：`sms`、`voice`、`email`、`push`，或通过 IM 应用集成发送的单聊消息，写作 `<app>:<integration_id>`，其中 `<app>` 为 `feishu_app`、`dingtalk_app`、`wecom_app`、`slack_app` 或 `teams_app`，`<integration_id>` 为该 IM 集成的 ID。其他取值返回 `InvalidParameter`。"
               },
               "warning": {
                 "type": "array",
                 "items": {
                   "type": "string"
                 },
-                "description": "Warning 级别使用的通知渠道。取值同 `critical`。"
+                "description": "故障严重程度为 `Warning` 时使用的通知渠道，取值同 `critical`。"
               },
               "info": {
                 "type": "array",
                 "items": {
                   "type": "string"
                 },
-                "description": "Info 级别使用的通知渠道。取值同 `critical`。"
+                "description": "故障严重程度为 `Info` 时使用的通知渠道，取值同 `critical`。"
               }
             }
           },
           "webhooks": {
-            "type": "array",
-            "description": "群聊/Webhook 通知目标。未提供 `by` 时必填。",
+            "type": [
+              "array",
+              "null"
+            ],
+            "description": "通过机器人或 IM 应用通知的群聊。未设置 `by` 时必填；未设置时返回 `null`。",
             "items": {
               "type": "object",
               "required": [
@@ -22905,12 +23311,24 @@
               "properties": {
                 "type": {
                   "type": "string",
-                  "description": "Webhook 类型，可选值：`feishu`、`feishu_app`、`dingtalk`、`dingtalk_app`、`wecom`、`slack`、`slack_app`、`teams_app`、`telegram`、`zoom`。"
+                  "description": "投递方式：\n- `feishu`、`dingtalk`、`wecom`、`slack`、`telegram`、`zoom`：对应 IM 的群机器人（Webhook）。\n- `feishu_app`、`dingtalk_app`、`slack_app`、`teams_app`：通过对应 IM 应用集成触达的群聊。",
+                  "enum": [
+                    "feishu",
+                    "dingtalk",
+                    "wecom",
+                    "slack",
+                    "telegram",
+                    "zoom",
+                    "feishu_app",
+                    "dingtalk_app",
+                    "slack_app",
+                    "teams_app"
+                  ]
                 },
                 "settings": {
                   "type": "object",
                   "additionalProperties": true,
-                  "description": "类型相关的配置参数（群聊 ID、URL 等）。"
+                  "description": "与类型相关的配置，例如机器人的 Webhook token 或应用的群聊 ID；`feishu_app` 与 `dingtalk_app` 必须提供。各类型的具体结构可先在控制台配置一次，再通过 `POST /channel/escalate/rule/info` 读取。"
                 }
               }
             }
@@ -22965,7 +23383,7 @@
             "items": {
               "$ref": "#/components/schemas/StatusPageComponentItem"
             },
-            "description": "该订阅者订阅的组件列表。"
+            "description": "订阅者关注的组件，每项只包含 `component_id` 和 `name`。`all` 为 `true` 时为空数组。"
           },
           "all": {
             "type": "boolean",
@@ -23014,7 +23432,10 @@
         "properties": {
           "progress": {
             "type": "string",
-            "description": "认领时记录的处理进展。"
+            "description": "本次认领把故障从 `Triggered` 变为 `Processing` 时为 `Processing`；故障原本已是 `Processing` 时省略。",
+            "enum": [
+              "Processing"
+            ]
           },
           "comment": {
             "type": "string",
@@ -23093,7 +23514,8 @@
             "description": "附加到评论的账户级评论类型 ObjectID。"
           },
           "comment_type": {
-            "$ref": "#/components/schemas/IncidentCommentTypeDisplay"
+            "$ref": "#/components/schemas/IncidentCommentTypeDisplay",
+            "description": "所附评论类型的名称和颜色，读取时解析；未附评论类型或类型已不存在时省略。"
           }
         },
         "title": "i_comm"
@@ -23127,23 +23549,24 @@
             "items": {
               "$ref": "#/components/schemas/IncidentShort"
             },
-            "description": "被合并的源故障列表。"
+            "description": "被合并进目标故障的源故障；出现在目标故障的记录中。"
           },
           "target_incident": {
-            "$ref": "#/components/schemas/IncidentShort"
+            "$ref": "#/components/schemas/IncidentShort",
+            "description": "本故障被合并进的目标故障；出现在源故障的记录中。"
           },
           "owner_id": {
             "type": "integer",
             "format": "int64",
-            "description": "执行合并操作的成员 ID。"
+            "description": "故障合并不会修改负责人，因此不写入此字段；仅可能出现在旧记录中。"
           },
           "title": {
             "type": "string",
-            "description": "合并后的故障标题。"
+            "description": "合并时为目标故障设置的新标题；仅出现在目标故障的记录中，且仅在标题变化时出现。"
           },
           "remove_source_incidents": {
             "type": "boolean",
-            "description": "合并后是否移除源故障。"
+            "description": "合并后源故障被永久删除时为 `true`。"
           },
           "source_responders": {
             "type": "array",
@@ -23151,7 +23574,7 @@
               "type": "integer",
               "format": "int64"
             },
-            "description": "从源故障继承的响应人成员 ID 列表。"
+            "description": "源故障上的处理人成员 ID，仅供参考，不会加入目标故障的处理人。"
           }
         },
         "title": "i_merge"
@@ -23187,7 +23610,8 @@
         "description": "`i_new` 的 detail 载荷。",
         "properties": {
           "severity": {
-            "$ref": "#/components/schemas/FeedSeverity"
+            "$ref": "#/components/schemas/FeedSeverity",
+            "description": "故障创建时的严重程度。"
           },
           "title": {
             "type": "string",
@@ -23270,7 +23694,7 @@
         "properties": {
           "reason": {
             "type": "string",
-            "description": "重新打开故障的原因。"
+            "description": "调用 `POST /incident/reopen` 时传入的 `reason` 原文；未填写时省略。"
           }
         },
         "title": "i_reopen"
@@ -23325,10 +23749,12 @@
         "description": "`i_r_severity` 的 detail 载荷。",
         "properties": {
           "from": {
-            "$ref": "#/components/schemas/FeedSeverity"
+            "$ref": "#/components/schemas/FeedSeverity",
+            "description": "修改前的严重程度。"
           },
           "to": {
-            "$ref": "#/components/schemas/FeedSeverity"
+            "$ref": "#/components/schemas/FeedSeverity",
+            "description": "修改后的严重程度。"
           }
         },
         "title": "i_r_severity"
@@ -23339,11 +23765,11 @@
         "properties": {
           "from": {
             "type": "string",
-            "description": "变更前的标题。"
+            "description": "修改前的标题。"
           },
           "to": {
             "type": "string",
-            "description": "变更后的标题。"
+            "description": "修改后的标题。"
           }
         },
         "title": "i_r_title"
@@ -23412,7 +23838,10 @@
         "properties": {
           "progress": {
             "type": "string",
-            "description": "取消认领时记录的处理进展。"
+            "description": "撤销认领后故障回到 `Triggered`（已无处理人处于认领状态）时为 `Triggered`，否则省略。",
+            "enum": [
+              "Triggered"
+            ]
           }
         },
         "title": "i_unack"
@@ -23424,7 +23853,7 @@
           "snoozedBefore": {
             "type": "integer",
             "format": "int64",
-            "description": "原本计划结束暂停的 Unix 时间戳。"
+            "description": "被取消的暂停原定结束的 Unix 时间戳（秒）。"
           }
         },
         "title": "i_wake"
@@ -23448,7 +23877,13 @@
           },
           "plugin_type": {
             "type": "string",
-            "description": "聊天集成插件类型。"
+            "description": "IM 集成的插件类型：`feishu_app`（飞书）、`dingtalk_app`（钉钉）、`wecom_app`（企业微信）、`slack_app`（Slack）。",
+            "enum": [
+              "feishu_app",
+              "dingtalk_app",
+              "wecom_app",
+              "slack_app"
+            ]
           },
           "integration_name": {
             "type": "string",
@@ -23470,6 +23905,10 @@
             "format": "int64",
             "description": "承载作战室群聊的集成 ID。"
           },
+          "unlink_only": {
+            "type": "boolean",
+            "description": "仅解除关联（`unlink_only` 请求）、未解散群组时为 `true`，否则省略。"
+          },
           "chat_id": {
             "type": "string",
             "description": "群聊 ID。"
@@ -23480,7 +23919,13 @@
           },
           "plugin_type": {
             "type": "string",
-            "description": "聊天集成插件类型。"
+            "description": "IM 集成的插件类型：`feishu_app`（飞书）、`dingtalk_app`（钉钉）、`wecom_app`（企业微信）、`slack_app`（Slack）。",
+            "enum": [
+              "feishu_app",
+              "dingtalk_app",
+              "wecom_app",
+              "slack_app"
+            ]
           },
           "integration_name": {
             "type": "string",
@@ -23563,7 +24008,7 @@
           "account_id": {
             "type": "integer",
             "format": "int64",
-            "description": "账户 ID。"
+            "description": "告警所属账户的 ID。"
           },
           "creator_id": {
             "type": "integer",
@@ -23615,7 +24060,7 @@
         "properties": {
           "key": {
             "type": "string",
-            "description": "过滤字段名。内置告警字段使用字段名（如 `alert_severity`、`alert_key`、`check`、`resource`、`service`、`cluster`），自定义标签使用 `labels.<name>` 前缀（如 `labels.env`、`labels.region`）。"
+            "description": "要匹配的字段。可用的内置字段取决于策略类型，见承载条件的字段说明；任意 `labels.<name>`（如 `labels.env`）始终可用。未知字段返回 `InvalidParameter`。告警或故障缺少该字段时，`IN` 不匹配，`NOTIN` 匹配。"
           },
           "oper": {
             "type": "string",
@@ -23623,14 +24068,14 @@
               "IN",
               "NOTIN"
             ],
-            "description": "过滤操作符。`IN`：值必须匹配 `vals` 中的某一项；`NOTIN`：值不能匹配 `vals` 中任何一项。支持 `/pattern/` 格式的正则表达式。"
+            "description": "匹配操作符，区分大小写。`IN`：字段值匹配 `vals` 中任意一项即命中；`NOTIN`：与 `vals` 中所有项都不匹配才命中。"
           },
           "vals": {
             "type": "array",
             "items": {
               "type": "string"
             },
-            "description": "匹配值列表。每一项为普通字符串或 `/regex/` 正则模式。"
+            "description": "要比较的值，至少一项。每项的匹配方式：普通字符串精确匹配；含 `*` 或 `?` 时按通配符匹配整个值；用斜杠包裹时按正则表达式匹配，如 `/^db-/`（可匹配值的任意位置）；`cidr:<网段>` 匹配 IP 范围，如 `cidr:203.0.113.0/24`；`num:<op>:<数字>` 做数值比较，`op` 为 `lt`、`le`、`gt`、`ge`，如 `num:gt:90`。"
           }
         }
       },
@@ -23643,13 +24088,13 @@
         "properties": {
           "is_disabled": {
             "type": "boolean",
-            "description": "禁用抖动检测。"
+            "description": "为 true 时关闭抖动检测。"
           },
           "max_changes": {
             "type": "integer",
             "minimum": 2,
             "maximum": 100,
-            "description": "`in_mins` 内允许的最大状态变更次数。"
+            "description": "`in_mins` 内允许的最大状态变化次数，2–100。不传或为 `0` 时三个值都使用默认值：4 次、`in_mins` 60、`mute_mins` 120。"
           },
           "in_mins": {
             "type": "integer",
@@ -23694,7 +24139,7 @@
         "properties": {
           "event_id": {
             "type": "string",
-            "description": "由 `ListWebhookHistory` 返回的事件 ID。"
+            "description": "`POST /webhook/history/list` 返回记录中的 `event_id`。它以推送日期（`YYYYMMDD`）开头，缺少该前缀时请求失败。"
           },
           "integration_id": {
             "type": "integer",
@@ -23718,7 +24163,7 @@
               "p",
               "n"
             ],
-            "description": "聚合方式：`i` 智能、`p` 规则、`n` 不聚合。"
+            "description": "聚合方式：\n- `n`：不聚合，每条新告警单独生成故障。\n- `p`：按 `equals` 与 `cases` 中的字段规则聚合，需要 Standard 及以上许可证。\n- `i`：按内容相似度智能聚合（见 `i_keys`、`i_score_threshold`），需要 Pro 许可证。"
           },
           "equals": {
             "type": "array",
@@ -23729,7 +24174,7 @@
               }
             },
             "maxItems": 5,
-            "description": "用于聚合判定的 label 键分组。"
+            "description": "规则聚合（`p`）使用的字段组，最多 5 组。新告警与活跃故障在任意一组的所有字段上取值都相同时并入该故障。可用字段：`title`、`description`、`severity` 或 `labels.<name>`；每组不能为空。`p` 模式下 `equals` 与 `cases` 至少提供其一。"
           },
           "cases": {
             "type": "array",
@@ -23764,7 +24209,7 @@
           },
           "all_equals_required": {
             "type": "boolean",
-            "description": "为 true 时要求所有键同时存在才能参与聚合。"
+            "description": "为 true 时，只有告警上存在该组全部字段才可匹配；为 false 时，缺失字段按空值比较，但该组至少要有一个字段存在。"
           },
           "time_window": {
             "type": "integer",
@@ -23783,7 +24228,7 @@
             "type": "integer",
             "minimum": 0,
             "maximum": 10000,
-            "description": "告警风暴阈值。"
+            "description": "旧版单级风暴阈值；仅当 `storm_thresholds` 为空且取值大于 1 时生效。`0` 表示关闭。"
           },
           "storm_thresholds": {
             "type": "array",
@@ -23791,7 +24236,7 @@
               "type": "integer"
             },
             "maxItems": 5,
-            "description": "多级告警风暴阈值。"
+            "description": "触发故障风暴事件的告警数：并入同一故障的告警数达到某个阈值时发送风暴通知。最多 5 个值，每个至少为 2，自动去重并排序。"
           },
           "i_keys": {
             "type": "array",
@@ -23799,14 +24244,14 @@
               "type": "string"
             },
             "maxItems": 10,
-            "description": "用于智能聚合向量化的 label 键。"
+            "description": "智能聚合（`i`）使用的字段，最多 10 个：`title`、`description`、`severity` 或 `labels.<name>`。为空时使用 `title`、`description`、`labels.service`、`labels.resource`。"
           },
           "i_score_threshold": {
             "type": "number",
             "format": "float",
             "minimum": 0.5,
             "maximum": 1,
-            "description": "智能聚合相似度阈值。"
+            "description": "智能聚合把告警并入已有故障所需的最低相似度，0.5–1。不传或为 `0` 时使用 0.9。"
           }
         }
       },
@@ -23827,7 +24272,7 @@
           },
           "alt": {
             "type": "string",
-            "description": "替代文本。"
+            "description": "图片无法显示时展示的替代文字；未设置时为空。"
           }
         }
       },
@@ -23860,7 +24305,7 @@
           },
           "all": {
             "type": "boolean",
-            "description": "为 true 时订阅所有组件。当 `component_ids` 与 `change_ids` 均为空时必须为 true。"
+            "description": "为 `true` 时订阅者接收全部组件和事件的通知，并忽略 `component_ids`/`change_ids`。两个列表都为空时必须为 `true`。"
           },
           "locale": {
             "type": "string",
@@ -23894,7 +24339,7 @@
             "items": {
               "$ref": "#/components/schemas/ImportStatusPageSubscriberItem"
             },
-            "description": "要导入的订阅者列表。"
+            "description": "要导入的订阅者。每个接收人在该状态页上已有的订阅会被替换；省略或传空数组时不做任何操作。"
           }
         }
       },
@@ -23908,12 +24353,12 @@
           "Triggered": {
             "type": "integer",
             "format": "int64",
-            "description": "近 30 天触发中的故障数量。"
+            "description": "近 30 天内开始、仍处于 `Triggered`（未认领）的故障数。"
           },
           "Processing": {
             "type": "integer",
             "format": "int64",
-            "description": "近 30 天处理中的故障数量。"
+            "description": "近 30 天内开始、处于 `Processing`（已认领、未关闭）的故障数。"
           }
         }
       },
@@ -23933,7 +24378,7 @@
           "ref_id": {
             "type": "string",
             "pattern": "^[0-9a-fA-F]{24}$",
-            "description": "引用对象 ObjectID，根据 type 不同可能指向故障或告警。"
+            "description": "条目所属故障的 ID，等于请求中的 `incident_id`。"
           },
           "type": {
             "$ref": "#/components/schemas/IncidentFeedType"
@@ -24042,6 +24487,35 @@
               },
               {
                 "$ref": "#/components/schemas/FeedDetailAlertMerge"
+              },
+              {
+                "type": "object",
+                "title": "i_wi_auto_converted",
+                "description": "`i_wi_auto_converted` 的详情。",
+                "properties": {
+                  "count": {
+                    "type": "integer",
+                    "description": "被转为后续行动的行动项数量。"
+                  },
+                  "work_item_ids": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    },
+                    "description": "被转换的工作项 ID。"
+                  },
+                  "titles": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    },
+                    "description": "被转换工作项的标题，顺序与 `work_item_ids` 一致。"
+                  },
+                  "post_mortem_id": {
+                    "type": "string",
+                    "description": "后续行动绑定的复盘报告 ID；故障没有复盘报告时为空。"
+                  }
+                }
               }
             ],
             "discriminator": {
@@ -24087,7 +24561,7 @@
           "account_id": {
             "type": "integer",
             "format": "int64",
-            "description": "账号 ID。"
+            "description": "该记录所属账户的 ID；同一 `app_key` 返回的记录该值都相同。"
           },
           "creator_id": {
             "type": "integer",
@@ -24108,12 +24582,23 @@
             "type": "integer",
             "format": "int64",
             "description": "最后更新时间戳（毫秒）。"
+          },
+          "via": {
+            "type": "string",
+            "enum": [
+              "ai_sre"
+            ],
+            "description": "由 AI SRE 代 `creator_id` 执行操作时为 `ai_sre`；直接操作时省略。"
+          },
+          "agent_session_id": {
+            "type": "string",
+            "description": "执行该操作的 AI SRE 会话 ID；仅在 `via` 为 `ai_sre` 且记录了会话时出现。"
           }
         }
       },
       "IncidentFeedType": {
         "type": "string",
-        "description": "故障时间线条目类型。每个值对应一个生命周期事件，其 `detail` 载荷结构由该字段决定。故障级事件前缀为 `i_`；向上冒泡到故障时间线的告警级事件前缀为 `a_`。\n\n| 类型 | 含义 |\n|---|---|\n| `i_new` | 故障创建：系统自动或人工创建了新故障。 |\n| `i_assign` | 分派响应人：故障被分派给指定人员处理。 |\n| `i_a_rspd` | 添加响应人：有新的响应人被加入处理。 |\n| `i_notify` | 通过某个渠道在指定环节发送通知。 |\n| `i_storm` | 故障触发告警风暴阈值。 |\n| `i_snooze` | 暂停通知指定时长。 |\n| `i_wake` | 取消暂停并恢复通知。 |\n| `i_ack` | 确认故障：响应人确认已开始处理故障。 |\n| `i_unack` | 取消认领。 |\n| `i_comm` | 添加评论：响应人记录了处理进展或关键信息。 |\n| `i_rslv` | 解决故障：故障被标记为已解决。 |\n| `i_reopen` | 重新打开：已解决的故障被重新打开，可能问题复发。 |\n| `i_merge` | 合并故障：多个相关故障被合并为一个。 |\n| `i_r_title` | 标题更新。 |\n| `i_r_desc` | 描述更新。 |\n| `i_r_impact` | 影响范围更新。 |\n| `i_r_rc` | 根因更新。 |\n| `i_r_rsltn` | 解决方案更新。 |\n| `i_r_severity` | 严重等级变更：故障的严重程度被调整。 |\n| `i_r_field` | 自定义字段值更新。 |\n| `i_m_flapping` | 因抖动检测被静默。 |\n| `i_m_reply` | 评论静音回复标记。 |\n| `i_custom` | 执行动作：触发了自动化操作或脚本。 |\n| `i_wr_create` | 创建作战室：建立了即时通讯群组用于协作处理。 |\n| `i_wr_delete` | 删除作战室群组。 |\n| `i_auto_refresh` | 卡片自动刷新事件。 |\n| `i_wi_created` | 跟进事项创建：创建了行动项或后续行动。 |\n| `i_wi_updated` | 跟进事项更新：标题、描述、状态或优先级发生变化。 |\n| `i_wi_assignees` | 跟进事项负责人变更：负责人被更新。 |\n| `i_wi_completed` | 跟进事项完成：负责人将跟进事项标记为完成。 |\n| `i_wi_converted` | 跟进事项转化：行动项被转化为后续行动。 |\n| `i_wi_bound` | 跟进事项绑定：已转化的后续行动被绑定到故障复盘。 |\n| `i_wi_deleted` | 跟进事项删除：行动项或后续行动被软删除。 |\n| `a_merge` | 告警合并：一条告警被合并进已有故障。 |",
+        "description": "故障时间线条目类型。每个值对应一个生命周期事件，其 `detail` 载荷结构由该字段决定。故障级事件前缀为 `i_`；向上冒泡到故障时间线的告警级事件前缀为 `a_`。\n\n| 类型 | 含义 |\n|---|---|\n| `i_new` | 故障创建：系统自动或人工创建了新故障。 |\n| `i_assign` | 分派响应人：故障被分派给指定人员处理。 |\n| `i_a_rspd` | 添加响应人：有新的响应人被加入处理。 |\n| `i_notify` | 通过某个渠道在指定环节发送通知。 |\n| `i_storm` | 故障触发告警风暴阈值。 |\n| `i_snooze` | 暂停通知指定时长。 |\n| `i_wake` | 取消暂停并恢复通知。 |\n| `i_ack` | 确认故障：响应人确认已开始处理故障。 |\n| `i_unack` | 取消认领。 |\n| `i_comm` | 添加评论：响应人记录了处理进展或关键信息。 |\n| `i_rslv` | 解决故障：故障被标记为已解决。 |\n| `i_reopen` | 重新打开：已解决的故障被重新打开，可能问题复发。 |\n| `i_merge` | 合并故障：多个相关故障被合并为一个。 |\n| `i_r_title` | 标题更新。 |\n| `i_r_desc` | 描述更新。 |\n| `i_r_impact` | 影响范围更新。 |\n| `i_r_rc` | 根因更新。 |\n| `i_r_rsltn` | 解决方案更新。 |\n| `i_r_severity` | 严重等级变更：故障的严重程度被调整。 |\n| `i_r_field` | 自定义字段值更新。 |\n| `i_m_flapping` | 因抖动检测被静默。 |\n| `i_m_reply` | 评论静音回复标记。 |\n| `i_custom` | 执行动作：触发了自动化操作或脚本。 |\n| `i_wr_create` | 创建作战室：建立了即时通讯群组用于协作处理。 |\n| `i_wr_delete` | 删除作战室群组。 |\n| `i_auto_refresh` | 卡片自动刷新事件。 |\n| `i_wi_created` | 跟进事项创建：创建了行动项或后续行动。 |\n| `i_wi_updated` | 跟进事项更新：标题、描述、状态或优先级发生变化。 |\n| `i_wi_assignees` | 跟进事项负责人变更：负责人被更新。 |\n| `i_wi_completed` | 跟进事项完成：负责人将跟进事项标记为完成。 |\n| `i_wi_converted` | 跟进事项转化：行动项被转化为后续行动。 |\n| `i_wi_bound` | 跟进事项绑定：已转化的后续行动被绑定到故障复盘。 |\n| `i_wi_deleted` | 跟进事项删除：行动项或后续行动被软删除。 |\n| `i_wi_auto_converted` | 工作项自动转换：关闭故障时，未完成的行动项被转为后续行动。 |\n| `a_merge` | 告警合并：一条告警被合并进已有故障。 |",
         "enum": [
           "i_new",
           "i_assign",
@@ -24148,6 +24633,7 @@
           "i_wi_converted",
           "i_wi_bound",
           "i_wi_deleted",
+          "i_wi_auto_converted",
           "a_merge"
         ]
       },
@@ -24203,7 +24689,8 @@
           "silence_url",
           "post_mortem_id",
           "images",
-          "manual_overrides"
+          "manual_overrides",
+          "has_unfinished_work_item"
         ],
         "properties": {
           "incident_id": {
@@ -24232,19 +24719,25 @@
             "description": "故障关联的首个集成 ID。"
           },
           "integration_ids": {
-            "type": "array",
+            "type": [
+              "array",
+              "null"
+            ],
             "items": {
               "type": "integer",
               "format": "int64"
             },
-            "description": "所有为此故障贡献告警的集成 ID。"
+            "description": "为该故障贡献告警的全部集成 ID；没有集成的故障（如手动创建的故障）为 `null`。"
           },
           "integration_types": {
-            "type": "array",
+            "type": [
+              "array",
+              "null"
+            ],
             "items": {
               "type": "string"
             },
-            "description": "所有相关集成的类型。"
+            "description": "全部贡献集成的插件类型（含义见 `integration_type`）；没有时为 `null`。"
           },
           "dedup_key": {
             "type": "string",
@@ -24392,8 +24885,15 @@
             "type": "boolean",
             "description": "该故障是否曾被静默。"
           },
+          "has_unfinished_work_item": {
+            "type": "boolean",
+            "description": "故障仍有至少一个状态既不是 `done` 也不是 `cancelled` 的行动项或后续行动时为 `true`。"
+          },
           "labels": {
-            "type": "object",
+            "type": [
+              "object",
+              "null"
+            ],
             "additionalProperties": {
               "type": "string"
             },
@@ -24406,7 +24906,7 @@
           },
           "assigned_to": {
             "$ref": "#/components/schemas/AssignedTo",
-            "description": "故障当前的指派对象。"
+            "description": "当前分派对象。始终存在；从未分派过的故障 `type`、`id` 为空，`assigned_at` 为 `0`。"
           },
           "reporter_email": {
             "type": "string",
@@ -24432,7 +24932,7 @@
             "items": {
               "$ref": "#/components/schemas/AlertInfo"
             },
-            "description": "关联告警列表，仅在通知模板与自定义动作中填充。"
+            "description": "故障相关接口不返回此字段，仅出现在通知模板和自定义操作的数据中。"
           },
           "closer": {
             "$ref": "#/components/schemas/PersonShort",
@@ -24456,15 +24956,15 @@
           },
           "account_name": {
             "type": "string",
-            "description": "账号名称。"
+            "description": "API 响应中恒为空字符串，仅在渲染通知时填充。"
           },
           "account_locale": {
             "type": "string",
-            "description": "账号语言。"
+            "description": "API 响应中恒为空字符串，仅在渲染通知时填充。"
           },
           "account_time_zone": {
             "type": "string",
-            "description": "账号时区。"
+            "description": "API 响应中恒为空字符串，仅在渲染通知时填充。"
           },
           "channel_name": {
             "type": "string",
@@ -24472,7 +24972,13 @@
           },
           "channel_status": {
             "type": "string",
-            "description": "协作空间状态。"
+            "description": "协作空间状态：`enabled` 启用、`disabled` 禁用、`deleted` 已删除。记录不属于任何协作空间或协作空间已不存在时为空字符串。",
+            "enum": [
+              "enabled",
+              "disabled",
+              "deleted",
+              ""
+            ]
           },
           "detail_url": {
             "type": "string",
@@ -24491,25 +24997,36 @@
           },
           "integration_type": {
             "type": "string",
-            "description": "首个告警的集成类型，详情页用于标签映射。"
+            "description": "故障第一个集成的插件类型（全部类型见 `integration_types`）。取值集合开放，例如 `prometheus.alert`、`monit.alert`；完整列表可通过 `POST /integration/type/list` 获取。故障没有集成或接口不填充时省略。"
           },
           "post_mortem_id": {
             "type": "string",
             "description": "关联的复盘报告 ID，一条故障只能关联一份复盘报告。"
           },
           "images": {
-            "type": "array",
+            "type": [
+              "array",
+              "null"
+            ],
             "items": {
               "$ref": "#/components/schemas/Image"
             },
-            "description": "附加图片。"
+            "description": "故障附带的图片；没有时为 `null`。以 `img_` 开头的令牌会以下载地址返回。"
           },
           "manual_overrides": {
-            "type": "array",
+            "type": [
+              "array",
+              "null"
+            ],
             "items": {
-              "type": "string"
+              "type": "string",
+              "enum": [
+                "title",
+                "description",
+                "incident_severity"
+              ]
             },
-            "description": "被手工覆盖过的字段名列表。"
+            "description": "被手动修改过、因此不再被合并告警覆盖的字段：`title`、`description`、`incident_severity`。没有时为 `null`。"
           },
           "data_source_id": {
             "type": "integer",
@@ -24518,7 +25035,10 @@
             "deprecated": true
           },
           "data_source_ids": {
-            "type": "array",
+            "type": [
+              "array",
+              "null"
+            ],
             "items": {
               "type": "integer",
               "format": "int64"
@@ -24528,11 +25048,14 @@
           },
           "data_source_type": {
             "type": "string",
-            "description": "已废弃。请使用 `integration_type`。",
+            "description": "已废弃；与 `integration_type` 取值相同。",
             "deprecated": true
           },
           "data_source_types": {
-            "type": "array",
+            "type": [
+              "array",
+              "null"
+            ],
             "items": {
               "type": "string"
             },
@@ -24575,15 +25098,15 @@
           "total": {
             "type": "integer",
             "format": "int64",
-            "description": "命中总数。"
+            "description": "匹配的故障数量，最多为 1,000。对于 `POST /incident/list-by-ids`，为实际找到的故障数。"
           },
           "has_next_page": {
             "type": "boolean",
-            "description": "是否还有更多页。"
+            "description": "是否还有下一页。按 `p`/`limit` 分页时根据封顶后的 `total` 计算，超过 1,000 条后即使还有数据也为 `false`；按 `search_after_ctx` 分页时如实反映。`POST /incident/list-by-ids` 恒为 `false`。"
           },
           "search_after_ctx": {
             "type": "string",
-            "description": "下一页翻页游标。"
+            "description": "指向本页最后一条记录的游标；在下一次请求中作为 `search_after_ctx` 传入，即可越过 1,000 条的分页上限继续读取。`p`/`limit` 模式下每个非空页都会返回，游标模式下仅在 `has_next_page` 为 `true` 时返回。`POST /incident/list-by-ids` 不返回。"
           }
         }
       },
@@ -24891,7 +25414,12 @@
           },
           "progress": {
             "type": "string",
-            "description": "故障处理进度——`Triggered`、`Processing`、`Closed` 之一。"
+            "description": "故障处理进度：`Triggered` 未认领；`Processing` 已认领处理中；`Closed` 已关闭。",
+            "enum": [
+              "Triggered",
+              "Processing",
+              "Closed"
+            ]
           }
         }
       },
@@ -24925,7 +25453,7 @@
           },
           "rule_name": {
             "type": "string",
-            "description": "规则名称。"
+            "description": "抑制策略名称，1–39 个字符。"
           },
           "description": {
             "type": "string",
@@ -24937,14 +25465,14 @@
           },
           "target_filters": {
             "$ref": "#/components/schemas/FilterGroup",
-            "description": "目标（被抑制）告警事件需要满足的条件；为空表示所有事件都是抑制目标。"
+            "description": "新进入的告警事件需满足的条件，满足才会被抑制；为空表示所有新事件都是抑制对象。可用字段：`title`、`description`、`severity`（别名 `alert_severity`、`event_severity`）、`status`、`alert_key`、`title_rule`、`integration_id`（别名 `data_source_id`），或任意 `labels.<name>`。"
           },
           "equals": {
             "type": "array",
             "items": {
               "type": "string"
             },
-            "description": "源（抑制方）告警与目标（被抑制）告警之间必须取值相等的字段键，例如 `data_source_id` 或 `labels.cluster`。"
+            "description": "源告警与新事件取值必须相同的字段。只有 `title`、`severity` 和 `labels.<name>` 有效；包含其他字段时策略永远不生效。"
           },
           "is_directly_discard": {
             "type": "boolean",
@@ -25068,7 +25596,7 @@
               "type": "integer",
               "format": "int64"
             },
-            "description": "按处理人员 ID 过滤，至多 100 项。",
+            "description": "按响应人成员 ID 过滤。用于 `/insight/responder`（返回哪些响应人）以及故障列表/导出（任一指定成员参与响应的故障）；账户、团队、协作空间维度和 Top-K 接口忽略该字段。最多 100 个。",
             "maxItems": 100
           },
           "severities": {
@@ -25082,7 +25610,7 @@
                 "Ok"
               ]
             },
-            "description": "按严重程度过滤，至多 3 项。",
+            "description": "按严重程度过滤：`Critical`、`Warning`、`Info` 或 `Ok`。最多 3 个。",
             "maxItems": 3
           },
           "incident_ids": {
@@ -25091,7 +25619,7 @@
               "type": "string",
               "pattern": "^[0-9a-fA-F]{24}$"
             },
-            "description": "按故障 ID（MongoDB ObjectID）过滤，至多 100 项。",
+            "description": "按故障 ID（24 位十六进制）过滤。仅用于故障列表和故障导出。最多 100 个。",
             "maxItems": 100
           },
           "query": {
@@ -25115,19 +25643,19 @@
             "enum": [
               "created_at"
             ],
-            "description": "故障列表的排序字段，目前仅支持 `created_at`（故障创建时间）。仅 `/insight/incident/list` 使用。"
+            "description": "故障列表的排序字段；仅支持 `created_at`（故障创建时间，默认）。用于 `/insight/incident/list` 和 `/insight/incident/export`。"
           },
           "asc": {
             "type": "boolean",
-            "description": "为 `true` 时升序，否则降序。仅 `/insight/incident/list` 使用。"
+            "description": "为 `true` 时升序，否则降序（默认）。用于故障列表和故障导出；`/insight/alert/topk-by-label` 有自己的 `asc`。"
           },
           "is_my_team": {
             "type": "boolean",
-            "description": "是否仅返回调用者所属团队的数据。若调用者无任何团队，返回空集合。"
+            "description": "只看调用者所在团队的数据（同时传 `team_ids` 时取交集）。调用者不属于任何团队时结果为空。"
           },
           "time_zone": {
             "type": "string",
-            "description": "用于划分 日/周/月 聚合桶的 IANA 时区名（如 `Asia/Shanghai`）。可选，默认 UTC；仅 `/insight/incident/export` 例外：缺省时依次回退到账户时区、`Asia/Shanghai`。"
+            "description": "用于切分 `aggregate_unit` 时间桶的 IANA 时区（如 `Asia/Shanghai`、`UTC`）；`EST` 之类的缩写以及 `Etc/GMT±N` 会被拒绝。默认 UTC。`/insight/incident/export` 用它渲染时间，未传时依次回退到账户时区、`Asia/Shanghai`。"
           },
           "seconds_to_close_from": {
             "type": "integer",
@@ -25219,7 +25747,7 @@
           "total": {
             "type": "integer",
             "format": "int64",
-            "description": "匹配的故障总数。"
+            "description": "匹配的故障数。请求带 `search_after_ctx` 时只统计游标之后的故障。"
           },
           "has_next_page": {
             "type": "boolean",
@@ -25234,7 +25762,7 @@
             "items": {
               "$ref": "#/components/schemas/IncidentRawItem"
             },
-            "description": "故障明细列表。"
+            "description": "本页的故障；无匹配时为空数组。"
           }
         }
       },
@@ -25249,7 +25777,7 @@
             "properties": {
               "split_hours": {
                 "type": "boolean",
-                "description": "为 `true` 时将指标拆分为 `work`/`sleep`/`off` 时段。"
+                "description": "为 `true` 时，每个时间桶再按 `work`、`sleep`、`off` 拆分，分别作为带 `hours` 的独立行返回。"
               },
               "aggregate_unit": {
                 "type": "string",
@@ -25258,7 +25786,7 @@
                   "week",
                   "month"
                 ],
-                "description": "将指标按时间粒度聚合。设置后时间范围须不少于 24 小时；`day` 粒度时范围不得超过 31 天。`day` 按自然日、`week` 按自然周、`month` 按自然月切分聚合桶，边界按 `time_zone` 对齐。"
+                "description": "将时间范围切分为时间桶；不传则整个范围作为一个桶。要求时间范围至少 24 小时，`day` 最多 31 天。\n- `day`：按 `time_zone` 的自然日切分（第一个桶从 `start_time` 到下一个零点）。\n- `week`：从 `start_time` 起每 7 天一个桶（不对齐到周一）。\n- `month`：按 `time_zone` 的自然月切分（第一个桶从 `start_time` 到下个月 1 日）。"
               }
             }
           }
@@ -25285,7 +25813,7 @@
               },
               "k": {
                 "type": "integer",
-                "description": "返回的前 K 条记录数，1 到 100，默认 20。",
+                "description": "返回的标签值个数，1–100（默认 20）。设置 `split_hours` 时按每个小时桶分别生效。",
                 "minimum": 1,
                 "maximum": 100,
                 "default": 20
@@ -25339,7 +25867,7 @@
           "p": {
             "type": "integer",
             "minimum": 1,
-            "description": "页码，从 1 开始。"
+            "description": "页码，从 1 开始。请始终传入：不传时返回第一页，但 `has_next_page` 不可靠。"
           },
           "limit": {
             "type": "integer",
@@ -25357,7 +25885,7 @@
               "channel_name",
               "last_incident_at"
             ],
-            "description": "排序字段。默认为 `created_at`。"
+            "description": "排序字段，默认 `created_at`。`ranking` 按调用者在控制台保存的自定义顺序排序，未保存时按创建顺序；`channel_name` 不区分大小写排序。"
           },
           "asc": {
             "type": "boolean",
@@ -25365,19 +25893,19 @@
           },
           "is_my_managed": {
             "type": "boolean",
-            "description": "为 true 时仅返回当前用户可管理的协作空间。"
+            "description": "为 true 时只返回所属团队为调用者所在团队、或由调用者创建的协作空间。优先于 `is_my_team` 与 `is_my_starred`。"
           },
           "is_my_starred": {
             "type": "boolean",
-            "description": "为 true 时仅返回当前用户收藏的协作空间，与 `is_my_team` 互斥。"
+            "description": "为 true 时只返回调用者收藏的协作空间。不能与 `is_my_team` 同时为 true。"
           },
           "is_brief": {
             "type": "boolean",
-            "description": "为 true 时仅返回 `channel_id`、`channel_name`、`description` 和 `status` 字段，且不分页，一次返回全部匹配结果。"
+            "description": "为 true 时每项只返回 `channel_id`、`channel_name`、`description`、`status`、`is_starred`，并一次返回全部结果。"
           },
           "is_my_team": {
             "type": "boolean",
-            "description": "为 true 时仅返回当前用户所在团队持有的协作空间，与 `is_my_starred` 互斥。"
+            "description": "为 true 时只返回所属团队为调用者所在团队的协作空间。不能与 `is_my_starred` 同时为 true。"
           },
           "team_ids": {
             "type": "array",
@@ -25385,7 +25913,7 @@
               "type": "integer",
               "format": "int64"
             },
-            "description": "按团队 ID 过滤。"
+            "description": "只返回所属团队在列表中的协作空间。`is_my_managed` 或 `is_my_team` 为 true 时忽略。"
           },
           "query": {
             "type": "string",
@@ -25423,11 +25951,11 @@
           "total": {
             "type": "integer",
             "format": "int64",
-            "description": "匹配到的协作空间总数。"
+            "description": "所有页中匹配的协作空间总数。"
           },
           "has_next_page": {
             "type": "boolean",
-            "description": "是否还有下一页。"
+            "description": "是否还有下一页。仅在传入 `p` 时可靠。"
           }
         }
       },
@@ -25457,7 +25985,7 @@
             "items": {
               "$ref": "#/components/schemas/EscalateRuleItem"
             },
-            "description": "该协作空间下的全部升级规则（不含已删除），按优先级升序。"
+            "description": "协作空间的分派策略（不含已删除），按匹配顺序排列：先按 `priority` 升序，再按创建时间。"
           }
         }
       },
@@ -25514,7 +26042,7 @@
             "items": {
               "$ref": "#/components/schemas/AlertInfo"
             },
-            "description": "告警列表。"
+            "description": "当前页的告警；没有匹配告警时为空数组。"
           },
           "total": {
             "type": "integer",
@@ -25539,7 +26067,8 @@
             "type": "integer",
             "format": "int64",
             "minimum": 1,
-            "description": "页码，从 1 开始。"
+            "description": "页码，从 1 开始。",
+            "default": 1
           },
           "limit": {
             "type": "integer",
@@ -25558,7 +26087,7 @@
             "items": {
               "$ref": "#/components/schemas/IncidentFeedType"
             },
-            "description": "可选类型过滤，仅返回指定类型的时间线条目。"
+            "description": "只返回这些类型的条目；不传时返回全部类型。"
           }
         }
       },
@@ -25642,9 +26171,13 @@
             "type": "boolean",
             "description": "true 时仅返回新奇故障。"
           },
+          "has_unfinished_work_item": {
+            "type": "boolean",
+            "description": "为 true 时只返回仍有状态既不是 `done` 也不是 `cancelled` 的行动项或后续行动的故障。`false` 不做过滤。"
+          },
           "progress": {
             "type": "string",
-            "description": "进展状态过滤，逗号分隔（如 `Triggered,Processing`）。"
+            "description": "要匹配的处理进度，多个值用英文逗号分隔，例如 `Triggered,Processing`。取值：`Triggered` 未认领；`Processing` 已认领处理中；`Closed` 已关闭。不传时匹配全部进度。"
           },
           "query": {
             "type": "string",
@@ -25652,7 +26185,7 @@
           },
           "incident_severity": {
             "type": "string",
-            "description": "严重程度过滤，逗号分隔（`Critical,Warning,Info`）。"
+            "description": "要匹配的严重程度，多个值用英文逗号分隔，例如 `Critical,Warning`。取值：`Critical` 严重、`Warning` 警告、`Info` 提醒。"
           },
           "channel_ids": {
             "type": "array",
@@ -25732,7 +26265,7 @@
           },
           "search_after_ctx": {
             "type": "string",
-            "description": "上一次响应返回的翻页游标。"
+            "description": "上次响应返回的 `search_after_ctx` 游标；设置后忽略 `p`。"
           }
         }
       },
@@ -25838,7 +26371,8 @@
               "created_at_seconds",
               "updated_at_seconds"
             ],
-            "description": "排序字段。"
+            "description": "排序字段：`created_at_seconds` 按创建时间，`updated_at_seconds` 按最后更新时间。",
+            "default": "created_at_seconds"
           },
           "asc": {
             "type": "boolean",
@@ -25908,7 +26442,7 @@
               "type": "integer",
               "format": "int64"
             },
-            "description": "需要查询路由规则的集成 ID 列表。",
+            "description": "要查询路由规则的共享集成 ID，至少一个，可通过 `POST /integration/list` 获取。",
             "minItems": 1
           }
         }
@@ -25996,7 +26530,7 @@
             "type": "integer",
             "minimum": 1,
             "maximum": 100,
-            "description": "每页数量。"
+            "description": "每页记录数，1–100。"
           },
           "asc": {
             "type": "boolean",
@@ -26018,7 +26552,7 @@
             "type": "integer",
             "format": "int64",
             "minimum": 0,
-            "description": "按 Webhook 集成 ID 过滤。"
+            "description": "按 Webhook 集成 ID 过滤；为 `0` 或不传时返回全部集成。"
           },
           "event_types": {
             "type": "array",
@@ -26069,7 +26603,7 @@
           },
           "total": {
             "type": "integer",
-            "description": "匹配记录总数。",
+            "description": "满足过滤条件的记录总数，不设上限。",
             "format": "int64"
           },
           "search_after_ctx": {
@@ -26088,7 +26622,7 @@
           "api_name": {
             "type": "string",
             "maxLength": 199,
-            "description": "唯一的 API 名称（最多 199 个字符）。"
+            "description": "映射 API 名称，在未删除的映射 API 中唯一（最长 199 字符）。"
           },
           "description": {
             "type": "string",
@@ -26098,7 +26632,7 @@
             "type": "string",
             "format": "uri",
             "maxLength": 500,
-            "description": "HTTP/HTTPS 端点 URL（最多 500 个字符）。"
+            "description": "以 `POST` 调用的地址。须为 `http` 或 `https` URL，最长 500 字符；SaaS 环境下主机名不得解析到内网 IP。"
           },
           "insecure_skip_verify": {
             "type": "boolean",
@@ -26113,20 +26647,22 @@
           },
           "timeout": {
             "type": "integer",
-            "description": "请求超时秒数（1–3），默认 2。",
+            "description": "整个请求的超时时间，单位秒（1–3）。不传或传 0 时为 2。",
             "minimum": 1,
-            "maximum": 3
+            "maximum": 3,
+            "default": 2
           },
           "retry_count": {
             "type": "integer",
-            "description": "失败重试次数（0–1），默认 0。",
+            "description": "调用失败后的重试次数（0–1），默认 0。",
             "minimum": 0,
-            "maximum": 1
+            "maximum": 1,
+            "default": 0
           },
           "team_id": {
             "type": "integer",
             "format": "int64",
-            "description": "所属团队 ID，可通过 `POST /team/list` 获取。"
+            "description": "所属团队 ID，可通过 `POST /team/list` 获取。不传或传 `0` 表示不属于任何团队；非 0 时须为已存在的团队。"
           }
         }
       },
@@ -26139,7 +26675,7 @@
           },
           "api_name": {
             "type": "string",
-            "description": "API 名称。"
+            "description": "新建映射 API 的名称，与请求一致。"
           }
         },
         "required": [
@@ -26169,11 +26705,11 @@
           },
           "api_name": {
             "type": "string",
-            "description": "API 名称。"
+            "description": "映射 API 名称，在未删除的映射 API 中唯一。"
           },
           "description": {
             "type": "string",
-            "description": "描述。"
+            "description": "描述文字（最多 500 字符），未填写时为空字符串。"
           },
           "url": {
             "type": "string",
@@ -26187,15 +26723,15 @@
             "additionalProperties": {
               "type": "string"
             },
-            "description": "自定义请求头，未配置时为 `null`。"
+            "description": "每次调用都会携带的请求头，以明文返回。未配置时为 `null`。"
           },
           "timeout": {
             "type": "integer",
-            "description": "请求超时秒数。"
+            "description": "整个请求的超时时间，单位秒（1–3）。"
           },
           "retry_count": {
             "type": "integer",
-            "description": "重试次数。"
+            "description": "调用失败后的重试次数：`0` 或 `1`。"
           },
           "insecure_skip_verify": {
             "type": "boolean",
@@ -26260,7 +26796,7 @@
         "properties": {
           "total": {
             "type": "integer",
-            "description": "映射 API 总数。"
+            "description": "返回的条目数；该列表不分页。"
           },
           "items": {
             "type": "array",
@@ -26291,14 +26827,14 @@
               "null"
             ],
             "maxLength": 199,
-            "description": "新 API 名称（最多 199 个字符）。"
+            "description": "新名称，在未删除的映射 API 中唯一（最长 199 字符）。不传则保持不变。"
           },
           "description": {
             "type": [
               "string",
               "null"
             ],
-            "description": "新描述。"
+            "description": "新描述，超过 500 字符会被截断。不传则保持不变，传 `\"\"` 清空。"
           },
           "url": {
             "type": [
@@ -26307,28 +26843,28 @@
             ],
             "format": "uri",
             "maxLength": 500,
-            "description": "新端点 URL（最多 500 个字符）。"
+            "description": "新的 `http`/`https` 地址（最长 500 字符）；SaaS 环境下主机名不得解析到内网 IP。不传则保持不变。"
           },
           "insecure_skip_verify": {
             "type": [
               "boolean",
               "null"
             ],
-            "description": "新 TLS 跳过验证设置。"
+            "description": "新的跳过 TLS 证书校验设置。不传则保持不变。"
           },
           "headers": {
             "type": "object",
             "additionalProperties": {
               "type": "string"
             },
-            "description": "自定义 HTTP 请求头。SaaS 模式下安全敏感的请求头名（`authorization`、`cookie`、`x-forwarded-for` 等）会被拒绝；键须为 RFC 7230 token 字符（最长 1024），值最长 4096 字符。"
+            "description": "传入时整体替换请求头，传 `{}` 清空全部请求头；不传则保持不变。SaaS 环境下会拒绝敏感请求头（见 `/enrichment/mapping/api/create`）；键最长 1,024 字符，值最长 4,096 字符。"
           },
           "timeout": {
             "type": [
               "integer",
               "null"
             ],
-            "description": "新超时秒数。",
+            "description": "新的整个请求超时时间，单位秒（1–3）。不传则保持不变。",
             "minimum": 1,
             "maximum": 3
           },
@@ -26337,7 +26873,7 @@
               "integer",
               "null"
             ],
-            "description": "新重试次数。",
+            "description": "新的重试次数（0–1）。不传则保持不变。",
             "minimum": 0,
             "maximum": 1
           },
@@ -26347,7 +26883,7 @@
               "null"
             ],
             "format": "int64",
-            "description": "新所属团队 ID，可通过 `POST /team/list` 获取。"
+            "description": "新的所属团队 ID，可通过 `POST /team/list` 获取；传 `0` 解除团队关联。不传则保持不变。"
           }
         }
       },
@@ -26368,7 +26904,7 @@
               "type": "string"
             },
             "maxItems": 100,
-            "description": "待删除的数据行键名列表。"
+            "description": "要删除的行 key（最多 100 个），取自 `/enrichment/mapping/data/list` 返回的 `key` 或 `/enrichment/mapping/data/upsert` 返回的 `keys`。匹配不到行的 key 会被忽略。"
           }
         }
       },
@@ -26390,7 +26926,7 @@
           "created_at": {
             "type": "integer",
             "format": "int64",
-            "description": "创建时间，Unix 时间戳（秒），为 0 时省略。"
+            "description": "该行最近一次写入的时间，Unix 秒；被替换的行会得到新值。为 0 时省略。"
           },
           "updated_at": {
             "type": "integer",
@@ -26426,7 +26962,8 @@
           },
           "asc": {
             "type": "boolean",
-            "description": "为 `true` 时升序排列。"
+            "description": "为 `true` 时正序；默认 `false`（最新的在前）。",
+            "default": false
           },
           "p": {
             "type": [
@@ -26464,16 +27001,21 @@
             "items": {
               "$ref": "#/components/schemas/MappingDataItem"
             },
-            "description": "数据行列表。"
+            "description": "本页的数据行，按 `orderby`/`asc` 排序；无匹配时为空数组。"
           },
           "total": {
             "type": "integer",
             "format": "int64",
-            "description": "匹配的总行数。"
+            "description": "匹配 `query` 的行数，最多统计到 1,000；值为 1,000 表示至少 1,000 行。"
           },
           "has_next_page": {
             "type": "boolean",
-            "description": "是否存在更多页。"
+            "description": "为 `true` 表示本页之后还有数据。"
+          },
+          "used_cnt": {
+            "type": "integer",
+            "format": "int64",
+            "description": "该映射规则中存储的总行数，不受 `query` 影响，可用于对照行数上限（默认 10,000 行）。"
           },
           "search_after_ctx": {
             "type": "string",
@@ -26483,7 +27025,8 @@
         "required": [
           "items",
           "total",
-          "has_next_page"
+          "has_next_page",
+          "used_cnt"
         ]
       },
       "MappingDataUpsertRequest": {
@@ -26506,7 +27049,7 @@
               }
             },
             "maxItems": 1000,
-            "description": "待插入或更新的数据行。每行须包含所有来源标签和结果标签；未知标签会被静默丢弃；单个值超过 2048 字符将被拒绝。"
+            "description": "要写入或替换的数据行（最多 1,000 行）。每行是标签名到值的映射，须包含全部来源标签和结果标签；其他键会被丢弃；值超过 2,048 字节会被拒绝。来源标签值与已有行相同的行会替换该行。"
           }
         }
       },
@@ -26518,7 +27061,7 @@
             "items": {
               "type": "string"
             },
-            "description": "已 Upsert 数据行的组合键列表。"
+            "description": "已写入行的 key（每个不同的行一个，顺序不固定），可用于 `/enrichment/mapping/data/delete`。"
           }
         },
         "required": [
@@ -26536,7 +27079,7 @@
           "schema_name": {
             "type": "string",
             "maxLength": 39,
-            "description": "唯一的映射规则名称（最多 39 个字符）。"
+            "description": "映射规则名称，在账户未删除的映射规则中唯一（最长 39 字符）。"
           },
           "description": {
             "type": "string",
@@ -26546,7 +27089,7 @@
           "team_id": {
             "type": "integer",
             "format": "int64",
-            "description": "所属团队 ID，`0` 表示无团队。"
+            "description": "所属团队 ID，可通过 `POST /team/list` 获取。不传或传 `0` 表示不属于任何团队；非 0 时须为已存在的团队。"
           },
           "source_labels": {
             "type": "array",
@@ -26556,7 +27099,8 @@
             },
             "maxItems": 3,
             "description": "查找键标签名（1–3 个）。每个须匹配 `^[a-zA-Z_][a-zA-Z0-9_]*$`；列表内不得重复，且不得与 `result_labels` 重叠。",
-            "uniqueItems": true
+            "uniqueItems": true,
+            "minItems": 1
           },
           "result_labels": {
             "type": "array",
@@ -26566,7 +27110,8 @@
             },
             "maxItems": 10,
             "description": "匹配后写入的输出标签名（1–10 个）。每个须匹配 `^[a-zA-Z_][a-zA-Z0-9_]*$`；列表内不得重复，且不得与 `source_labels` 重叠。",
-            "uniqueItems": true
+            "uniqueItems": true,
+            "minItems": 1
           }
         }
       },
@@ -26579,7 +27124,7 @@
           },
           "schema_name": {
             "type": "string",
-            "description": "映射规则名称。"
+            "description": "新建映射规则的名称，与请求一致。"
           }
         },
         "required": [
@@ -26609,7 +27154,7 @@
           },
           "schema_name": {
             "type": "string",
-            "description": "映射规则名称。"
+            "description": "映射规则名称，在账户未删除的映射规则中唯一。"
           },
           "description": {
             "type": "string",
@@ -26620,14 +27165,14 @@
             "items": {
               "type": "string"
             },
-            "description": "查找键标签名。"
+            "description": "其值组成数据行查找键的标签名（1–3 个），创建后不可修改。"
           },
           "result_labels": {
             "type": "array",
             "items": {
               "type": "string"
             },
-            "description": "输出标签名。"
+            "description": "匹配到行时写入事件的标签名（1–10 个），创建后不可修改。"
           },
           "status": {
             "type": "string",
@@ -26640,7 +27185,7 @@
           "team_id": {
             "type": "integer",
             "format": "int64",
-            "description": "所属团队 ID。"
+            "description": "所属团队 ID；不属于任何团队时为 `0`。"
           },
           "creator_id": {
             "type": "integer",
@@ -26685,7 +27230,7 @@
         "properties": {
           "total": {
             "type": "integer",
-            "description": "映射规则总数。"
+            "description": "返回的条目数；该列表不分页。"
           },
           "items": {
             "type": "array",
@@ -26716,7 +27261,7 @@
               "null"
             ],
             "maxLength": 39,
-            "description": "新的映射规则名称（最多 39 个字符）。"
+            "description": "新名称，在未删除的映射规则中唯一（最长 39 字符）。不传则保持不变。"
           },
           "description": {
             "type": [
@@ -26724,7 +27269,7 @@
               "null"
             ],
             "maxLength": 500,
-            "description": "新的描述（最多 500 个字符）。"
+            "description": "新描述（最长 500 字符）。不传则保持不变，传 `\"\"` 清空。"
           },
           "team_id": {
             "type": [
@@ -26732,7 +27277,7 @@
               "null"
             ],
             "format": "int64",
-            "description": "新的所属团队 ID，`0` 表示移除团队关联。"
+            "description": "新的所属团队 ID，可通过 `POST /team/list` 获取；传 `0` 解除团队关联。不传则保持不变。"
           }
         }
       },
@@ -26776,7 +27321,7 @@
           },
           "remove_source_incidents": {
             "type": "boolean",
-            "description": "为 true 时合并后软删除源故障，否则将源故障关闭。"
+            "description": "为 true 时，源故障的告警转移到目标故障后永久删除源故障；为 false 时源故障被关闭并保留。"
           }
         }
       },
@@ -26796,7 +27341,7 @@
           "ts": {
             "type": "integer",
             "format": "int64",
-            "description": "聚合桶的起始时间，Unix 时间戳（秒）。未使用 `aggregate_unit` 时等于 `start_time`。"
+            "description": "时间桶的开始时间（Unix 秒）。未设置 `aggregate_unit` 时等于 `start_time`。"
           },
           "channel_id": {
             "type": "integer",
@@ -26806,7 +27351,7 @@
           "team_id": {
             "type": "integer",
             "format": "int64",
-            "description": "团队 ID，仅在按团队聚合（`/insight/team`）时返回。"
+            "description": "团队 ID，仅 `/insight/team` 返回。汇总未归属团队故障的那一行不含该字段。"
           },
           "responder_id": {
             "type": "integer",
@@ -26842,7 +27387,7 @@
           },
           "source_page_id": {
             "type": "string",
-            "description": "Atlassian Statuspage 源状态页 ID。"
+            "description": "Atlassian Statuspage 源页面 ID，只能包含字母、数字、`_` 和 `-`。"
           },
           "target_page_id": {
             "type": "integer",
@@ -26865,7 +27410,7 @@
           },
           "source_page_id": {
             "type": "string",
-            "description": "Atlassian Statuspage 源状态页 ID。"
+            "description": "Atlassian Statuspage 源页面 ID，只能包含字母、数字、`_` 和 `-`。"
           },
           "url_name": {
             "type": [
@@ -26896,7 +27441,7 @@
           },
           "failed_reason": {
             "type": "string",
-            "description": "投递失败原因。"
+            "description": "投递渠道上报的本地化失败原因；投递成功或未上报失败时省略。该文本不是固定的错误码集合。"
           }
         }
       },
@@ -26911,7 +27456,7 @@
           },
           "failed_reason": {
             "type": "string",
-            "description": "投递失败原因。"
+            "description": "投递渠道上报的本地化失败原因；投递成功或未上报失败时省略。该文本不是固定的错误码集合。"
           },
           "sms_content": {
             "type": "string",
@@ -26933,7 +27478,7 @@
           },
           "failed_reason": {
             "type": "string",
-            "description": "投递失败原因。"
+            "description": "投递渠道上报的本地化失败原因；投递成功或未上报失败时省略。该文本不是固定的错误码集合。"
           }
         }
       },
@@ -26997,7 +27542,7 @@
           "person_id": {
             "type": "integer",
             "format": "int64",
-            "description": "成员 ID。"
+            "description": "成员 ID，与 `POST /member/list` 返回的 ID 相同。"
           },
           "person_name": {
             "type": "string",
@@ -27069,7 +27614,8 @@
           "meta",
           "basics",
           "content",
-          "follow_ups"
+          "follow_ups",
+          "has_active_incident"
         ],
         "properties": {
           "meta": {
@@ -27087,22 +27633,28 @@
             "properties": {
               "incidents_highest_severity": {
                 "type": "string",
-                "description": "关联故障的最高严重程度。"
+                "description": "关联故障中最高的严重程度：`Critical`、`Warning` 或 `Info`；仅在手动设置时可能为 `Ok`。",
+                "enum": [
+                  "Critical",
+                  "Warning",
+                  "Info",
+                  "Ok"
+                ]
               },
               "incidents_earliest_start_seconds": {
                 "type": "integer",
                 "format": "int64",
-                "description": "关联故障中最早的开始时间（秒）。"
+                "description": "关联故障中最早的开始时间（Unix 秒）。"
               },
               "incidents_latest_close_seconds": {
                 "type": "integer",
                 "format": "int64",
-                "description": "关联故障中最晚的关闭时间（秒）。"
+                "description": "关联故障中最晚的关闭时间（Unix 秒）；尚未关闭的故障取其 `end_time`。"
               },
               "incidents_total_duration_seconds": {
                 "type": "integer",
                 "format": "int64",
-                "description": "累计持续时长（秒）。"
+                "description": "从关联故障最早开始到最晚关闭的秒数（不是各故障时长之和）。"
               },
               "responders": {
                 "type": "array",
@@ -27130,6 +27682,10 @@
           "follow_ups": {
             "type": "string",
             "description": "跟进行动项，单字符串表示。"
+          },
+          "has_active_incident": {
+            "type": "boolean",
+            "description": "至少有一个关联故障尚未关闭时为 `true`；全部关闭前后续行动保持锁定。每次请求实时计算。"
           }
         }
       },
@@ -27158,7 +27714,7 @@
           "account_id": {
             "type": "integer",
             "format": "int64",
-            "description": "账号 ID。"
+            "description": "该记录所属账户的 ID；同一 `app_key` 返回的记录该值都相同。"
           },
           "title": {
             "type": "string",
@@ -27174,7 +27730,7 @@
           },
           "post_mortem_id": {
             "type": "string",
-            "description": "按账号和故障 ID 确定性派生的复盘报告 ID。"
+            "description": "复盘报告 ID：由账户 ID 和关联故障 ID 计算出的 32 位十六进制字符串。"
           },
           "template_id": {
             "type": "string",
@@ -27278,7 +27834,7 @@
           "reason": {
             "type": "string",
             "maxLength": 1024,
-            "description": "可选，记录到时间线的重开原因。"
+            "description": "可选的重开原因（自由文本），会记录在 `i_reopen` 时间线条目中。最多 1,024 个字符。"
           }
         }
       },
@@ -27297,10 +27853,10 @@
           },
           "field_name": {
             "type": "string",
-            "description": "自定义字段名称，必须与账号下定义的字段匹配。"
+            "description": "自定义字段名（字段的 `field_name`，而非显示名称）。字段必须存在且处于启用状态；可通过 `POST /field/list` 查询。"
           },
           "field_value": {
-            "description": "字段新值，类型需与字段定义一致。"
+            "description": "新值，类型须与字段匹配：`checkbox` 传布尔值，`single_select` 传一个选项，`multi_select` 传选项数组，`text` 传字符串。省略或传 `null` 表示清空该字段。"
           }
         }
       },
@@ -27482,7 +28038,7 @@
             "items": {
               "$ref": "#/components/schemas/ResponderInsightItem"
             },
-            "description": "按处理人员聚合的故障响应指标行；启用 `split_hours` 或 `aggregate_unit` 时会进一步按时段或时间桶拆分。"
+            "description": "按响应人的指标行，按时间桶从新到旧排列。某时间桶内没有故障的响应人不产生行。"
           }
         }
       },
@@ -27495,7 +28051,7 @@
         "properties": {
           "if": {
             "type": "array",
-            "description": "匹配条件列表,条件之间为 AND 关系。",
+            "description": "条件之间为 AND 关系；空列表匹配所有事件。必填。",
             "items": {
               "$ref": "#/components/schemas/RouteMatchCondition"
             }
@@ -27513,7 +28069,7 @@
           },
           "fallthrough": {
             "type": "boolean",
-            "description": "为 `true` 时,本 case 命中后继续向下匹配;为 `false` 则在首次命中后停止。"
+            "description": "为 `true` 时，本 case 命中后继续匹配后续 case，所有命中 case 的协作空间合并；为 `false` 时在本 case 停止。"
           },
           "routing_mode": {
             "type": "string",
@@ -27521,11 +28077,11 @@
               "standard",
               "name_mapping"
             ],
-            "description": "路由模式。`standard`（默认，留空时亦按此处理）按固定的协作空间 ID 路由；`name_mapping` 通过读取告警事件中某个标签的值来动态匹配协作空间名称。"
+            "description": "路由模式。`standard` 路由到固定的 `channel_ids`；`name_mapping` 路由到名称与事件中 `name_mapping_label` 字段值相同的已启用协作空间。留空按 `standard` 处理，响应中不返回该字段。"
           },
           "name_mapping_label": {
             "type": "string",
-            "description": "用作目标协作空间名的标签键。当 `routing_mode` 为 `name_mapping` 时必填。"
+            "description": "其取值用作目标协作空间名称的事件字段，例如 `labels.service`。`routing_mode` 为 `name_mapping` 时必填；没有同名的已启用协作空间时，该 case 不产生协作空间。"
           }
         }
       },
@@ -27539,7 +28095,7 @@
               "type": "integer",
               "format": "int64"
             },
-            "description": "兜底使用的协作空间 ID 列表。"
+            "description": "没有任何 case 得到协作空间时使用的协作空间。空列表视为没有默认分支。"
           }
         }
       },
@@ -27553,14 +28109,14 @@
           "integration_id": {
             "type": "integer",
             "format": "int64",
-            "description": "集成 ID,必须大于 0。",
+            "description": "共享集成 ID，大于 0，可通过 `POST /integration/list` 获取。",
             "exclusiveMinimum": 0
           }
         }
       },
       "RouteItem": {
         "type": "object",
-        "description": "集成的路由规则。告警按 `cases` 顺序依次匹配，未命中的将进入 `default` 分支。当集成未配置规则时返回 `null`。",
+        "description": "共享集成的路由规则。告警按顺序匹配 `cases`；没有任何 case 得到协作空间时使用 `default`。",
         "required": [
           "version",
           "updated_by",
@@ -27595,12 +28151,12 @@
               "enabled",
               "deleted"
             ],
-            "description": "规则状态。`enabled` 生效中；`deleted` 已删除，仅在历史版本中可见。"
+            "description": "规则状态。这些接口只返回 `enabled` 的规则，`deleted` 的规则（例如集成已删除）不会返回。"
           },
           "version": {
             "type": "integer",
             "format": "int64",
-            "description": "单调递增的版本号,每次更新加 1,可用于乐观并发控制。"
+            "description": "版本号，每次 `POST /route/upsert` 递增。服务端不会用它做并发校验。"
           },
           "updated_by": {
             "type": "integer",
@@ -27615,7 +28171,7 @@
           "deleted_at": {
             "type": "integer",
             "format": "int64",
-            "description": "软删除时间戳（Unix 秒）。规则有效时不返回此字段。"
+            "description": "软删除时间，Unix 秒级时间戳。这些接口只返回有效规则，因此不会返回此字段。"
           },
           "created_at": {
             "type": "integer",
@@ -27640,7 +28196,7 @@
         "properties": {
           "key": {
             "type": "string",
-            "description": "用于与告警事件比对的字段键(如 `alert_severity`、`labels.service`)。"
+            "description": "要匹配的告警或变更事件字段：`title`、`description`、`severity`（别名 `alert_severity`、`event_severity`）、`status`、`alert_key`、`change_key`、`title_rule`、`integration_id`（别名 `data_source_id`），或任意 `labels.<name>`。未知字段返回 `InvalidParameter`。"
           },
           "oper": {
             "type": "string",
@@ -27648,14 +28204,14 @@
               "IN",
               "NOTIN"
             ],
-            "description": "匹配运算符。`IN` 表示字段值命中 `vals` 中任一项;`NOTIN` 表示均不命中。"
+            "description": "匹配操作符。`IN`：字段值匹配 `vals` 中任意一项即命中；`NOTIN`：与所有项都不匹配才命中。字段缺失时 `IN` 不命中，`NOTIN` 命中。"
           },
           "vals": {
             "type": "array",
             "items": {
               "type": "string"
             },
-            "description": "用于比对的值列表。每项支持字面量、通配符（`*`、`?`）、以斜杠包裹的正则表达式（`/pattern/`）、CIDR（`cidr:10.0.0.0/8`）以及数值比较（`num:lt:100`）。"
+            "description": "要比较的值，至少一项。每项的匹配方式：普通字符串精确匹配；含 `*` 或 `?` 时按通配符匹配整个值；用斜杠包裹时按正则表达式匹配，如 `/^db-/`（可匹配值的任意位置）；`cidr:<网段>` 匹配 IP 范围，如 `cidr:203.0.113.0/24`；`num:<op>:<数字>` 做数值比较，`op` 为 `lt`、`le`、`gt`、`ge`，如 `num:gt:90`。"
           }
         }
       },
@@ -27707,15 +28263,19 @@
         "properties": {
           "layer_name": {
             "type": "string",
-            "description": "分层显示名称。"
+            "description": "分层名称；`final_schedule` 中为空字符串。"
           },
           "name": {
             "type": "string",
-            "description": "分层内部名称。"
+            "description": "与 `layer_name` 相同。"
           },
           "mode": {
             "type": "integer",
-            "description": "分层模式：0 = 普通轮转，1 = 覆盖。"
+            "enum": [
+              0,
+              1
+            ],
+            "description": "来源分层的类型：`0` = 轮转分层，`1` = 覆盖分层。`final_schedule` 中恒为 `0`。"
           },
           "schedules": {
             "type": [
@@ -27750,12 +28310,19 @@
             "description": "时段结束时间（Unix 秒）。"
           },
           "group": {
-            "$ref": "#/components/schemas/ScheduleGroup",
-            "description": "覆盖该班次的值班组；null 表示覆盖空档。"
+            "oneOf": [
+              {
+                "$ref": "#/components/schemas/ScheduleGroup"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "该班次的值班组；为 `null` 表示该时段无人值班。"
           },
           "index": {
             "type": "integer",
-            "description": "轮转内索引。"
+            "description": "该班次来源分层在值班表分层列表中的位置（从 0 开始）。"
           }
         }
       },
@@ -27773,7 +28340,7 @@
               "minimum": 0,
               "maximum": 6
             },
-            "description": "参与轮转的星期数（0 = 周日）。与 restrict_mode = 2（按周）互斥。"
+            "description": "分层值班的星期：`0` = 周日 … `6` = 周六，按值班表时区计算。为空或包含全部 7 天表示每天。不能与 `restrict_mode` 为 2 同时使用。"
           }
         }
       },
@@ -27845,12 +28412,12 @@
           "start": {
             "type": "integer",
             "format": "int64",
-            "description": "值班组开始时间（Unix 秒）。"
+            "description": "计算结果中该组班次的开始时间（Unix 秒）；在分层定义中为 `0`，作为输入时忽略。"
           },
           "end": {
             "type": "integer",
             "format": "int64",
-            "description": "值班组结束时间（Unix 秒）。"
+            "description": "计算结果中该组班次的结束时间（Unix 秒）；在分层定义中为 `0`，作为输入时忽略。"
           }
         }
       },
@@ -27870,7 +28437,7 @@
       },
       "ScheduleIDsBodyRequest": {
         "type": "object",
-        "description": "携带值班表 ID 列表的请求体（删除/启用/禁用使用）。",
+        "description": "携带值班表 ID 列表的请求。",
         "required": [
           "schedule_ids"
         ],
@@ -27912,7 +28479,19 @@
         "properties": {
           "type": {
             "type": "string",
-            "description": "IM 提供方类型（如 feishu_app、dingtalk_app、wecom_app、teams_app、slack_app）。"
+            "enum": [
+              "feishu",
+              "dingtalk",
+              "wecom",
+              "slack",
+              "telegram",
+              "zoom",
+              "feishu_app",
+              "dingtalk_app",
+              "slack_app",
+              "teams_app"
+            ],
+            "description": "通知发送目标：\n- `feishu`、`dingtalk`、`wecom`、`slack`：由 `settings.token` 指定的群机器人 webhook。\n- `telegram`：使用 `settings.token` 的机器人，发送到 `settings.chat_ids`。\n- `zoom`：使用 `settings.token` 和 `settings.verify_token` 的 Zoom 机器人。\n- `feishu_app`、`dingtalk_app`、`slack_app`、`teams_app`：通过 IM 集成（`settings.data_source_id`）发送到 `settings.chat_ids` 中的群聊。\n其他取值会被保存但不会发送。"
           },
           "settings": {
             "$ref": "#/components/schemas/ScheduleImNotifySettings",
@@ -27934,37 +28513,37 @@
         "properties": {
           "token": {
             "type": "string",
-            "description": "Webhook token。"
+            "description": "`feishu`、`dingtalk`、`wecom`、`slack`、`telegram`、`zoom` 类型使用的机器人 webhook token；`*_app` 类型为空。"
           },
           "alias": {
             "type": "string",
-            "description": "通道别名。"
+            "description": "该条目的显示别名；发送时不使用。"
           },
           "data_source_id": {
             "type": "integer",
             "format": "int64",
-            "description": "数据源 ID。"
+            "description": "`*_app` 类型使用的 IM 集成 ID；机器人类型为 `0`。"
           },
           "chat_ids": {
             "type": "array",
             "items": {
               "type": "string"
             },
-            "description": "会话 ID 列表。"
+            "description": "目标会话 ID：`*_app` 类型为 IM 集成中的群聊 ID，`telegram` 类型为 Telegram chat ID。"
           },
           "verify_token": {
             "type": "string",
-            "description": "验签 token。"
+            "description": "校验 token，`zoom` 类型使用。"
           },
           "sign_secret": {
             "type": "string",
-            "description": "签名密钥。"
+            "description": "机器人签名密钥，随条目保存。"
           }
         }
       },
       "ScheduleInfoRequest": {
         "type": "object",
-        "description": "值班表详情请求。start/end 指定计算值班分层的时间窗口，跨度必须小于 45 天。",
+        "description": "值班表详情请求。`start`/`end` 指定计算班次的窗口，相差不超过 45 天。",
         "required": [
           "schedule_id",
           "start",
@@ -27990,12 +28569,13 @@
       },
       "ScheduleItem": {
         "type": "object",
-        "description": "/schedule/info、/schedule/preview、/schedule/list 返回的完整值班表详情。",
+        "description": "info、list、infos、self、preview 接口返回的值班表。哪些计算字段有值取决于具体接口，见各接口说明。",
         "required": [
           "id",
           "name",
           "account_id",
           "group_id",
+          "time_zone",
           "disabled",
           "create_at",
           "create_by",
@@ -28033,7 +28613,7 @@
           "account_id": {
             "type": "integer",
             "format": "int64",
-            "description": "账户 ID。"
+            "description": "值班表所属账户的 ID。"
           },
           "group_id": {
             "type": [
@@ -28043,12 +28623,21 @@
             "format": "int64",
             "description": "旧版团队/组 ID。/schedule/preview 返回时为 null。"
           },
+          "time_zone": {
+            "type": "string",
+            "description": "值班表的 IANA 时区（如 `Asia/Shanghai`），交接时间、限制时段、星期和定时通知都按该时区计算。创建时设置，之后不可修改。空字符串表示未设置，按 `Asia/Shanghai` 计算。"
+          },
           "disabled": {
             "type": [
               "integer",
               "null"
             ],
-            "description": "禁用标记（0 = 启用，1 = 禁用），已废弃。/schedule/preview 返回时为 null。"
+            "enum": [
+              0,
+              1,
+              null
+            ],
+            "description": "值班表是否禁用：`0` = 启用，`1` = 禁用（禁用的值班表不发送换班通知，并会被 `/schedule/self`、`/schedule/by-person` 跳过）。与 `status` 取值相同。`/schedule/preview` 中除非请求传入，否则为 `null`。"
           },
           "create_at": {
             "type": "integer",
@@ -28080,10 +28669,6 @@
             },
             "description": "值班表定义的轮转层。未加载层信息时为 null（例如 `/schedule/infos`，或未传 start/end 的 `/schedule/list`）。"
           },
-          "field": {
-            "type": "string",
-            "description": "旧版字段更新接口使用的字段名。"
-          },
           "schedule_layers": {
             "type": [
               "array",
@@ -28092,25 +28677,32 @@
             "items": {
               "$ref": "#/components/schemas/ScheduleCalculatedLayer"
             },
-            "description": "按请求时间窗口计算出的各层排班，未计算时为 null。"
+            "description": "请求窗口内各个未隐藏分层的班次。未计算窗口时为 `null`（`/schedule/infos`、`/schedule/self`、未传 `start`/`end` 的 `/schedule/list`）。"
           },
           "final_schedule": {
             "$ref": "#/components/schemas/ScheduleCalculatedLayer",
-            "description": "所有分层合并后的最终值班结果。"
+            "description": "窗口内所有分层合并后的时间线：分层重叠时，覆盖分层优先于轮转分层，靠后的分层优先于靠前的分层。在 `/schedule/self` 中只保留调用者本人的班次。未计算时为空（`schedules` 为 `null`）。"
           },
           "start": {
             "type": "integer",
             "format": "int64",
-            "description": "时间窗口开始（Unix 秒）。为 0（未请求窗口）时省略。"
+            "description": "窗口开始时间（Unix 秒）。仅 `/schedule/preview` 回显，其他接口省略。"
           },
           "end": {
             "type": "integer",
             "format": "int64",
-            "description": "时间窗口结束（Unix 秒）。为 0（未请求窗口）时省略。"
+            "description": "窗口结束时间（Unix 秒）。仅 `/schedule/preview` 回显，其他接口省略。"
           },
           "notify": {
-            "$ref": "#/components/schemas/ScheduleNotify",
-            "description": "通知配置，未配置时为 null。"
+            "oneOf": [
+              {
+                "$ref": "#/components/schemas/ScheduleNotify"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "换班通知配置；未配置时为 `null`。"
           },
           "schedule_id": {
             "type": [
@@ -28150,28 +28742,47 @@
             "items": {
               "$ref": "#/components/schemas/ScheduleCalculatedLayer"
             },
-            "description": "schedule_layers 的兼容别名，未计算时为 null。"
+            "description": "与 `schedule_layers` 内容相同，仅 `/schedule/info` 和 `/schedule/preview` 填充；其他接口为 `null`。"
           },
           "status": {
             "type": [
               "integer",
               "null"
             ],
-            "description": "旧版状态字段，已废弃。/schedule/preview 返回时为 null。"
+            "enum": [
+              0,
+              1,
+              null
+            ],
+            "description": "`disabled` 的镜像：`0` = 启用，`1` = 禁用。在 `/schedule/update` 中通过该字段启用或禁用值班表。`/schedule/preview` 中除非请求传入，否则为 `null`。"
           },
           "cur_oncall": {
-            "$ref": "#/components/schemas/ScheduleOncallGroup",
-            "description": "当前正在值班的组，无人值班时为 null。"
+            "oneOf": [
+              {
+                "$ref": "#/components/schemas/ScheduleOncallGroup"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "此刻正在进行的班次；无人值班或接口不计算时（`/schedule/infos`、`/schedule/self`、未传窗口的 `/schedule/list`）为 `null`。"
           },
           "next_oncall": {
-            "$ref": "#/components/schemas/ScheduleOncallGroup",
-            "description": "下一次值班的组，未知时为 null。"
+            "oneOf": [
+              {
+                "$ref": "#/components/schemas/ScheduleOncallGroup"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "当前班次之后第一个有人值班的班次；45 天内找不到或接口不计算时为 `null`。"
           }
         }
       },
       "ScheduleLayer": {
         "type": "object",
-        "description": "值班表中的单个分层。",
+        "description": "值班表中的一个分层。轮转分层（`mode` 为 0）在 `groups` 之间依次轮换；覆盖分层（`mode` 为 1）在 `layer_start` 到 `layer_end` 期间由第一个值班组值班。仅响应字段（`account_id`、`schedule_id`、`create_*`、`update_*`）在请求中会被忽略。",
         "required": [
           "account_id",
           "name",
@@ -28202,24 +28813,28 @@
           "account_id": {
             "type": "integer",
             "format": "int64",
-            "description": "账户 ID。"
+            "description": "分层所属账户的 ID，由服务端填写。"
           },
           "name": {
             "type": "string",
-            "description": "分层内部名称。"
+            "description": "分层名称。`name` 与 `layer_name` 至少提供一个；都提供时以 `layer_name` 为准。"
           },
           "schedule_id": {
             "type": "integer",
             "format": "int64",
-            "description": "所属值班表 ID。"
+            "description": "分层所属值班表的 ID，由服务端填写。"
           },
           "hidden": {
             "type": "integer",
-            "description": "是否在页面上隐藏（0 = 否，1 = 是）。"
+            "enum": [
+              0,
+              1
+            ],
+            "description": "为 `1` 时该分层不出现在 `schedule_layers` 中，但其班次仍参与 `final_schedule` 的合并。`0`（默认）正常显示。"
           },
           "mode": {
             "type": "integer",
-            "description": "分层模式：0 = 普通轮转，1 = 覆盖。",
+            "description": "分层类型：\n- `0`：轮转分层——各值班组按 `rotation_unit`/`rotation_value` 依次轮换。\n- `1`：覆盖分层——`groups` 中第一个值班组在 `layer_start` 至 `layer_end` 整段时间值班，优先于轮转分层。",
             "enum": [
               0,
               1
@@ -28227,7 +28842,7 @@
           },
           "weight": {
             "type": "integer",
-            "description": "分层权重，用于排序。"
+            "description": "按传入值保存；计算班次时不使用。"
           },
           "groups": {
             "type": [
@@ -28237,31 +28852,31 @@
             "items": {
               "$ref": "#/components/schemas/ScheduleGroup"
             },
-            "description": "参与轮转的值班组，未设置时为 null。"
+            "description": "分层的值班组，按轮换顺序排列。每个组需要 `group_name`（或 `name`），且每个成员槽位至少包含一人。`start`/`end` 作为输入时忽略。"
           },
           "rotation_duration": {
             "type": "integer",
             "format": "int64",
-            "description": "轮转周期（秒）。"
+            "description": "轮转时长（秒），是 `rotation_unit` + `rotation_value` 的旧版替代写法：只传该字段时服务端据此推算单位和数量（按整周、整天或整小时），只传后两者时服务端回填该字段（一个月按 30 天计）。"
           },
           "handoff_time": {
             "type": "integer",
             "format": "int64",
-            "description": "轮转交接时间，以一周内的秒数偏移表示（星期 x 86400 + 当日秒数），不是 Unix 绝对时间戳。"
+            "description": "按周轮转的交接时刻，表示自周一 00:00（值班表时区）起的秒数（`星期 × 86400 + 当日秒数`，周一 = 0 … 周日 = 6），不是 Unix 时间戳。用 `handoff` 设置更方便。"
           },
           "enable_time": {
             "type": "integer",
             "format": "int64",
-            "description": "分层生效时间（Unix 秒）。"
+            "description": "分层生效时间（Unix 秒）。对轮转分层，其时分同时也是每天的交接时刻。传了 `layer_start` 时以其为准。"
           },
           "expire_time": {
             "type": "integer",
             "format": "int64",
-            "description": "分层失效时间（Unix 秒，0 表示永不过期）。"
+            "description": "分层失效时间（Unix 秒）；`0` 表示永不失效。不能早于 `enable_time`。传了 `layer_end` 时以其为准。"
           },
           "restrict_mode": {
             "type": "integer",
-            "description": "限制模式：0 = 不限制，1 = day，2 = week。",
+            "description": "将分层限制在 `restrict_periods` 给出的时间窗口内：\n- `0`：不限制。\n- `1`：按天限制；偏移量为自 00:00 起的秒数（0–86400）。\n- `2`：按周限制；偏移量为自周一 00:00 起的秒数（0–604800）。不能与 `day_mask` 同时使用。\n窗口按值班表时区计算。",
             "enum": [
               0,
               1,
@@ -28271,12 +28886,12 @@
           "restrict_start": {
             "type": "integer",
             "format": "int64",
-            "description": "旧版限制区间开始偏移（秒）。"
+            "description": "旧版单窗口的开始偏移（秒）；请改用 `restrict_periods`。"
           },
           "restrict_end": {
             "type": "integer",
             "format": "int64",
-            "description": "旧版限制区间结束偏移（秒）。"
+            "description": "旧版单窗口的结束偏移（秒）；请改用 `restrict_periods`。"
           },
           "restrict_periods": {
             "type": [
@@ -28286,11 +28901,11 @@
             "items": {
               "$ref": "#/components/schemas/ScheduleRestrictPeriod"
             },
-            "description": "每个轮转周期内的限制时段，未设置时为 null。"
+            "description": "分层值班的时间窗口，含义由 `restrict_mode` 决定。窗口之外该分层无人值班。未设置时为 `null`。"
           },
           "day_mask": {
             "$ref": "#/components/schemas/ScheduleDayMask",
-            "description": "星期掩码。"
+            "description": "轮转分层值班的星期。"
           },
           "create_at": {
             "type": "integer",
@@ -28317,11 +28932,11 @@
               "string",
               "null"
             ],
-            "description": "面向用户的层名称，未设置时为 null。"
+            "description": "控制台显示的分层名称；响应中与 `name` 相同。"
           },
           "fair_rotation": {
             "type": "boolean",
-            "description": "是否启用公平轮转。"
+            "description": "为 `true` 时，每一整轮的起始组依次后移一位，避免总由同一组开头。`false`（默认）每轮都从第一组开始。"
           },
           "layer_start": {
             "type": [
@@ -28329,7 +28944,7 @@
               "null"
             ],
             "format": "int64",
-            "description": "层生效时间（Unix 秒），未设置时为 null。"
+            "description": "与 `enable_time` 相同；请求中优先于 `enable_time`。`enable_time` 为 0 时为 `null`。"
           },
           "layer_end": {
             "type": [
@@ -28337,7 +28952,7 @@
               "null"
             ],
             "format": "int64",
-            "description": "分层结束时间（Unix 秒）。null 表示无结束时间。"
+            "description": "与 `expire_time` 相同；请求中优先于 `expire_time`。`null` 表示永不结束。"
           },
           "rotation_unit": {
             "type": "string",
@@ -28352,22 +28967,106 @@
           "rotation_value": {
             "type": "integer",
             "format": "int64",
-            "description": "轮转数量（每周期的 rotation_unit 个数）。",
+            "description": "每个值班组连续值班多少个 `rotation_unit` 后交接。轮转分层需要提供该字段（配合 `rotation_unit`）或 `rotation_duration`。",
             "minimum": 0
           },
           "mask_continuous_enabled": {
             "type": "boolean",
-            "description": "是否启用连续掩码。"
+            "description": "仅当 `day_mask` 选择了 1–6 个星期时生效。为 `true` 时，每个值班日从分层生效时刻的钟点起，到次日同一钟点止，而不是从零点到零点。"
+          },
+          "starts_at": {
+            "type": "object",
+            "writeOnly": true,
+            "description": "仅用于请求。以值班表时区的墙钟日期和时刻表示分层开始时间，覆盖 `layer_start`/`enable_time`。",
+            "required": [
+              "date"
+            ],
+            "properties": {
+              "date": {
+                "type": "string",
+                "description": "日期，格式 `YYYY-MM-DD`。"
+              },
+              "time": {
+                "type": "string",
+                "description": "时刻，格式 `HH:MM`（24 小时制），默认 `00:00`。"
+              }
+            }
+          },
+          "ends_at": {
+            "type": "object",
+            "writeOnly": true,
+            "description": "仅用于请求。以值班表时区的墙钟日期和时刻表示分层结束时间，覆盖 `layer_end`/`expire_time`。传 `{\"date\": \"\"}` 表示永不结束。",
+            "properties": {
+              "date": {
+                "type": "string",
+                "description": "日期，格式 `YYYY-MM-DD`。"
+              },
+              "time": {
+                "type": "string",
+                "description": "时刻，格式 `HH:MM`（24 小时制），默认 `00:00`。"
+              }
+            }
+          },
+          "handoff": {
+            "type": "object",
+            "writeOnly": true,
+            "required": [
+              "weekday",
+              "time"
+            ],
+            "description": "仅用于请求。以值班表时区表示的交接星期和时刻；会设置 `handoff_time` 以及 `enable_time` 的时分。",
+            "properties": {
+              "weekday": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 7,
+                "description": "ISO 星期：`1` = 周一 … `7` = 周日。"
+              },
+              "time": {
+                "type": "string",
+                "description": "时刻，格式 `HH:MM`（24 小时制）。"
+              }
+            }
+          },
+          "restricts_wall": {
+            "type": "array",
+            "writeOnly": true,
+            "description": "仅用于请求。以值班表时区墙钟时间表示的限制窗口，会替换 `restrict_periods`。`restrict_mode` 为 1 时使用 `from`/`to`（`to` 为 `00:00` 表示到当天结束）；为 2 时还需设置 `from_day`/`to_day`。`restrict_mode` 为 0 时会被拒绝。",
+            "items": {
+              "type": "object",
+              "properties": {
+                "from_day": {
+                  "type": "integer",
+                  "minimum": 1,
+                  "maximum": 7,
+                  "description": "窗口开始的 ISO 星期（仅 `restrict_mode` 为 2 时）：`1` = 周一 … `7` = 周日。"
+                },
+                "from": {
+                  "type": "string",
+                  "description": "窗口开始时刻，`HH:MM`。"
+                },
+                "to_day": {
+                  "type": "integer",
+                  "minimum": 1,
+                  "maximum": 7,
+                  "description": "窗口结束的 ISO 星期（仅 `restrict_mode` 为 2 时）。"
+                },
+                "to": {
+                  "type": "string",
+                  "description": "窗口结束时刻，`HH:MM`。"
+                }
+              }
+            }
           }
         }
       },
       "ScheduleListRequest": {
         "type": "object",
-        "description": "值班表列表请求。limit 默认 10、最大 100，p 默认 1。is_my_team 与 is_my_manage 不能同时为 true。",
+        "description": "值班表列表过滤条件。`limit` 默认 10，最大 100；`p` 默认 1。`is_my_team` 与 `is_my_manage` 不能同时为 true。",
         "properties": {
           "query": {
             "type": "string",
-            "description": "按值班表名称或描述匹配的关键字。"
+            "description": "对值班表名称或描述做子串匹配。"
           },
           "p": {
             "type": "integer",
@@ -28376,17 +29075,17 @@
           },
           "limit": {
             "type": "integer",
-            "description": "每页条数，默认 10、最大 100。",
+            "description": "每页条数。默认 10；超过 100 按 100 处理。",
             "default": 10,
             "maximum": 100
           },
           "is_my_team": {
             "type": "boolean",
-            "description": "仅返回当前用户所在团队的值班表。"
+            "description": "只返回调用者所在团队的值班表。调用者不属于任何团队时返回空列表。"
           },
           "is_my_manage": {
             "type": "boolean",
-            "description": "仅返回当前用户在其团队内创建的值班表。"
+            "description": "只返回调用者所在团队的值班表以及调用者创建的值班表。"
           },
           "team_ids": {
             "type": "array",
@@ -28394,17 +29093,17 @@
               "type": "integer",
               "format": "int64"
             },
-            "description": "按团队 ID 过滤。"
+            "description": "只返回这些团队的值班表；同时设置 `is_my_team`/`is_my_manage` 时取交集。"
           },
           "start": {
             "type": "integer",
             "format": "int64",
-            "description": "与 end 同时传入时，响应会包含计算后的分层值班结果；跨度必须小于 45 天。"
+            "description": "窗口开始时间，10 位 Unix 秒。与 `end` 同时传入时计算分层和班次。"
           },
           "end": {
             "type": "integer",
             "format": "int64",
-            "description": "窗口结束时间（Unix 秒）。"
+            "description": "窗口结束时间，10 位 Unix 秒，晚于 `start` 且相差不超过 45 天。只传 `end` 不传 `start` 会被拒绝。"
           }
         }
       },
@@ -28417,14 +29116,11 @@
         ],
         "properties": {
           "items": {
-            "type": [
-              "array",
-              "null"
-            ],
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/ScheduleItem"
             },
-            "description": "当前页的值班表；无匹配时为 null。"
+            "description": "本页的值班表；无匹配时为空数组。"
           },
           "total": {
             "type": "integer",
@@ -28444,7 +29140,7 @@
           "role_id": {
             "type": "integer",
             "format": "int64",
-            "description": "值班角色 ID。",
+            "description": "该槽位人员的值班角色 ID；`0` 表示不指定角色。",
             "minimum": 0
           },
           "person_ids": {
@@ -28453,7 +29149,7 @@
               "type": "integer",
               "format": "int64"
             },
-            "description": "该角色下的用户 ID 列表。",
+            "description": "该槽位的成员 ID，至少一个。",
             "minItems": 1
           }
         }
@@ -28473,22 +29169,36 @@
               "null"
             ],
             "format": "int64",
-            "description": "提前通知时间（秒）；为 `0` 时在排班开始时通知；不传则不发送提前通知。"
+            "description": "换班通知提前量（秒）：`0` 在班次开始时通知，`300` 提前 5 分钟。不传或为 `null` 则不发送换班通知。"
           },
           "fixed_time": {
-            "$ref": "#/components/schemas/ScheduleFixedTimeNotifyInfo",
-            "description": "定时通知配置，未配置时为 null。"
+            "oneOf": [
+              {
+                "$ref": "#/components/schemas/ScheduleFixedTimeNotifyInfo"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "在固定时间发送值班信息；未配置时为 `null`。"
           },
           "by": {
-            "$ref": "#/components/schemas/ScheduleNotifyBy",
-            "description": "接收人通知偏好，未配置时为 null。"
+            "oneOf": [
+              {
+                "$ref": "#/components/schemas/ScheduleNotifyBy"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "发给值班人员本人的个人通知；未配置时为 `null`。"
           },
           "im": {
             "type": "object",
             "additionalProperties": {
               "type": "string"
             },
-            "description": "旧版 IM 类型到 token 的映射。"
+            "description": "旧版的机器人类型到 webhook token 的映射。读取时会把 `webhooks` 中没有的条目并入 `webhooks`；请改用 `webhooks`。"
           },
           "webhooks": {
             "type": [
@@ -28498,7 +29208,7 @@
             "items": {
               "$ref": "#/components/schemas/ScheduleImNotify"
             },
-            "description": "IM Webhook 通知渠道，未配置时为 null。"
+            "description": "接收换班通知的群聊或机器人；未配置时为 `null`。"
           }
         }
       },
@@ -28512,14 +29222,17 @@
         "properties": {
           "follow_preference": {
             "type": "boolean",
-            "description": "是否跟随个人通知偏好。"
+            "description": "`true`：按每个人自己设置的换班通知偏好渠道发送，忽略 `personal_channels`。`false`：使用 `personal_channels`。"
           },
           "personal_channels": {
-            "type": "array",
+            "type": [
+              "array",
+              "null"
+            ],
             "items": {
               "type": "string"
             },
-            "description": "个人通知通道列表。"
+            "description": "`follow_preference` 为 `false` 时使用的渠道：`email`、`sms`、`push`（移动端推送），以及 IM 应用 `feishu_app`、`dingtalk_app`、`wecom_app`、`teams_app`、`slack_app`。IM 应用可写成 `<类型>:<集成 ID>` 指定集成（如 `feishu_app:5427276014131`）。未知取值会被保存但不会使用。未设置时为 `null`。"
           }
         }
       },
@@ -28552,21 +29265,21 @@
           "update_at": {
             "type": "integer",
             "format": "int64",
-            "description": "更新时间（Unix 秒）。"
+            "description": "更新时间（Unix 秒级时间戳）；在这些响应中恒为 `0`。"
           },
           "weight": {
             "type": "integer",
-            "description": "来源分层权重。"
+            "description": "在这些响应中恒为 `0`。"
           },
           "index": {
             "type": "integer",
-            "description": "轮转内索引。"
+            "description": "在这些响应中恒为 `0`。"
           }
         }
       },
       "ScheduleRestrictPeriod": {
         "type": "object",
-        "description": "轮转周期内的限制时段。restrict_start 与 restrict_end 为秒级偏移，除非都为 0，否则不能相等。",
+        "description": "一天或一周内的一个值班窗口（见 `restrict_mode`）。开始晚于结束时表示跨越午夜（或跨越周末）。`{0, 0}` 表示全天或全周。除此之外开始和结束不能相等。",
         "required": [
           "restrict_start",
           "restrict_end"
@@ -28575,12 +29288,12 @@
           "restrict_start": {
             "type": "integer",
             "format": "int64",
-            "description": "限制区间开始偏移。"
+            "description": "窗口开始偏移（秒）：`restrict_mode` 为 1 时自 00:00 起算，为 2 时自周一 00:00 起算。"
           },
           "restrict_end": {
             "type": "integer",
             "format": "int64",
-            "description": "限制区间结束偏移。"
+            "description": "窗口结束偏移（秒），起算点与 `restrict_start` 相同。"
           }
         }
       },
@@ -28606,26 +29319,23 @@
       },
       "ScheduleSelfResponse": {
         "type": "object",
-        "description": "/schedule/self 与 /schedule/infos 的响应，仅返回 items。",
+        "description": "`/schedule/self` 和 `/schedule/infos` 的响应。",
         "required": [
           "items"
         ],
         "properties": {
           "items": {
-            "type": [
-              "array",
-              "null"
-            ],
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/ScheduleItem"
             },
-            "description": "分配给当前用户的值班表（或匹配请求 ID 的值班表）；无时为 null。"
+            "description": "匹配的值班表；无匹配时为空数组。"
           }
         }
       },
       "ScheduleUpsertRequest": {
         "type": "object",
-        "description": "值班表创建/更新/预览请求体。服务端接受与值班表详情模型相同的结构，此处仅列出关键字段。创建时必填 `schedule_name`（或旧字段 `name`），更新时必填 `schedule_id`，预览时必填 `start` 和 `end`。",
+        "description": "`/schedule/create`、`/schedule/update`、`/schedule/preview` 的请求体。创建时必须提供 `schedule_name`（或旧字段 `name`），更新时必须提供 `schedule_id`，预览时必须提供 `start`/`end`。",
         "properties": {
           "schedule_id": {
             "type": [
@@ -28640,7 +29350,7 @@
               "string",
               "null"
             ],
-            "description": "值班表显示名称，最长 40 字符。",
+            "description": "值班表名称，最长 40 个字符，账户内唯一。更新时不传则保持原名称。",
             "maxLength": 40
           },
           "name": {
@@ -28648,7 +29358,7 @@
               "string",
               "null"
             ],
-            "description": "旧版名称字段，当 schedule_name 为空时使用。",
+            "description": "旧版名称字段，仅在创建且 `schedule_name` 为空时使用。更新时忽略。",
             "maxLength": 40
           },
           "description": {
@@ -28656,7 +29366,7 @@
               "string",
               "null"
             ],
-            "description": "值班表描述，最长 500 字符。",
+            "description": "值班表描述，最长 500 个字符。更新时不传保持原值，传空字符串则清空。",
             "maxLength": 500
           },
           "team_id": {
@@ -28665,35 +29375,63 @@
               "null"
             ],
             "format": "int64",
-            "description": "所属团队 ID，可通过 `POST /team/list` 获取。"
+            "description": "所属团队 ID，可通过 `POST /team/list` 获取。创建时不传则不归属任何团队（`0`）；更新时不传保持原团队。"
+          },
+          "time_zone": {
+            "type": "string",
+            "description": "值班表墙钟规则所用的 IANA 时区，如 `Asia/Shanghai`、`UTC`；`EST` 之类的缩写以及 `Etc/GMT±N` 会被拒绝。创建时设置（不传则按 `Asia/Shanghai` 计算），之后不可修改——更新时不传或传当前值。预览时用于指定计算时区。"
           },
           "layers": {
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/ScheduleLayer"
             },
-            "description": "轮转分层。"
+            "description": "轮转分层。更新时该列表会替换全部已有分层，不传即删除所有分层。"
           },
           "notify": {
-            "$ref": "#/components/schemas/ScheduleNotify",
-            "description": "值班轮换通知配置。"
+            "oneOf": [
+              {
+                "$ref": "#/components/schemas/ScheduleNotify"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "换班通知配置。更新时不传保持原配置；传入则整体替换。"
           },
           "start": {
             "type": "integer",
             "format": "int64",
-            "description": "预览窗口开始时间（Unix 秒，10 位），/schedule/preview 必填。"
+            "description": "预览窗口开始时间，10 位 Unix 秒。`/schedule/preview` 必填；创建和更新时忽略。"
           },
           "end": {
             "type": "integer",
             "format": "int64",
-            "description": "预览窗口结束时间（Unix 秒，10 位），/schedule/preview 必填，且距 start 不超过 45 天。"
+            "description": "预览窗口结束时间，10 位 Unix 秒，晚于 `start` 且相差不超过 45 天。`/schedule/preview` 必填；创建和更新时忽略。"
           },
           "disabled": {
             "type": [
               "integer",
               "null"
             ],
-            "description": "0 = 启用，1 = 禁用。缺省时为启用。"
+            "enum": [
+              0,
+              1,
+              null
+            ],
+            "description": "仅创建时生效：`0` = 启用（默认），`1` = 禁用。更新时忽略，请改用 `status`。"
+          },
+          "status": {
+            "type": [
+              "integer",
+              "null"
+            ],
+            "enum": [
+              0,
+              1,
+              null
+            ],
+            "description": "`0` = 启用，`1` = 禁用。更新时不传保持当前状态。创建时优先于 `disabled`。"
           }
         }
       },
@@ -28728,7 +29466,7 @@
           },
           "rule_name": {
             "type": "string",
-            "description": "规则名称。"
+            "description": "静默策略名称，1–39 个字符。"
           },
           "description": {
             "type": "string",
@@ -28752,11 +29490,11 @@
           },
           "filters": {
             "$ref": "#/components/schemas/FilterGroup",
-            "description": "告警事件匹配条件；命中的事件在时间窗口内被静默。"
+            "description": "告警事件匹配条件（AND 组之间为 OR），时间窗口内命中的事件被静默。"
           },
           "is_directly_discard": {
             "type": "boolean",
-            "description": "为 true 时静默的告警直接丢弃，不会生成故障。"
+            "description": "为 true 时，命中的告警事件被直接丢弃；为 false 时，告警仍会记录，但标记为被该策略静默。"
           },
           "status": {
             "type": "string",
@@ -28792,7 +29530,7 @@
           },
           "is_auto_delete": {
             "type": "boolean",
-            "description": "为 true 时，静默规则在时间窗结束后会被自动删除；默认为 false。"
+            "description": "为 true 时，策略在一次性窗口结束约 24 小时后被永久移除；周期窗口的策略不会被移除。仅在为 `true` 时返回。"
           },
           "deleted_at": {
             "type": "integer",
@@ -28859,7 +29597,7 @@
           "change_id": {
             "type": "integer",
             "format": "int64",
-            "description": "事件 ID。"
+            "description": "事件 ID，由 `POST /status-page/change/create` 返回；调用其他事件接口时作为 `change_id` 传入。"
           },
           "page_id": {
             "type": "integer",
@@ -28920,7 +29658,7 @@
           "start_at_seconds": {
             "type": "integer",
             "format": "int64",
-            "description": "事件开始时间（Unix 秒），取自第一条时间线更新。为 0 时不返回。"
+            "description": "事件开始时间，Unix 时间戳（秒）。故障为第一条时间线更新的时间；维护为创建时指定的计划开始时间，未指定时取第一条更新的时间。为 0 时省略。"
           },
           "close_at_seconds": {
             "type": "integer",
@@ -28987,7 +29725,7 @@
         "properties": {
           "update_id": {
             "type": "string",
-            "description": "更新 ID。"
+            "description": "时间线更新 ID（ULID 字符串），由服务端生成；修改或删除该更新时作为 `update_id` 传入。"
           },
           "at_seconds": {
             "type": "integer",
@@ -29030,7 +29768,7 @@
         "properties": {
           "component_id": {
             "type": "string",
-            "description": "组件 ID。"
+            "description": "状态发生变化的组件 ID，对应 `GET /status-page/info` 中的 `component_id`。"
           },
           "component_name": {
             "type": "string",
@@ -29102,7 +29840,7 @@
         "properties": {
           "draft_id": {
             "type": "string",
-            "description": "草稿 ID，格式为 `draft_[A-Za-z0-9]{22}`；控制台审核链接会携带它。"
+            "description": "草稿 ID，格式为 `draft_[A-Za-z0-9]{22}`；发布时作为 `draft_id` 传给 `POST /status-page/change/create` 或 `POST /status-page/change/timeline/create`。"
           },
           "created_at": {
             "type": "integer",
@@ -29142,7 +29880,7 @@
           "target_page_id": {
             "type": "integer",
             "format": "int64",
-            "description": "Flashduty 目标状态页 ID。任务产出后设置，或由订阅者迁移接口上游传入。"
+            "description": "Flashduty 目标状态页 ID。结构迁移在状态页创建或复用前为 0；订阅者迁移为请求中的 `target_page_id`。"
           },
           "phase": {
             "type": "string",
@@ -29200,7 +29938,7 @@
         "properties": {
           "total_steps": {
             "type": "integer",
-            "description": "任务包含的总步骤数。"
+            "description": "任务总步数：结构迁移为 5（状态页、分组、组件、故障与维护、模板），订阅者迁移为 1。"
           },
           "completed_steps": {
             "type": "integer",
@@ -29232,7 +29970,7 @@
           },
           "subscribers_skipped": {
             "type": "integer",
-            "description": "跳过的订阅者数量（例如重复）。"
+            "description": "因非邮件订阅、无邮箱地址或已被隔离而跳过的源订阅者数量。目标页上已存在的接收人不计入此数。"
           },
           "warnings": {
             "type": "array",
@@ -29298,12 +30036,11 @@
             "example": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
           },
           "data": {
-            "description": "每个接口自己的业务 payload，详见各接口的 200 响应 schema。"
+            "description": "接口返回的数据，格式见各接口的 200 响应。没有返回数据的接口会返回 `{}` 或完全不带 `data`。"
           }
         },
         "required": [
-          "request_id",
-          "data"
+          "request_id"
         ]
       },
       "TemplateCreateRequest": {
@@ -29316,14 +30053,14 @@
           "team_id": {
             "type": "integer",
             "format": "int64",
-            "description": "团队归属。0 表示账户全局共享。",
+            "description": "所属团队 ID，可通过 `POST /team/list` 获取；`0`（默认）表示账户级。非 0 时须为已存在的团队。",
             "default": 0
           },
           "template_name": {
             "type": "string",
             "minLength": 1,
             "maxLength": 39,
-            "description": "模板名称，同一账户内唯一，长度 1–39 个字符。",
+            "description": "模板名称，1–39 个字符，在账户未删除的模板中唯一，且不能与内置预设模板在任一支持语言下的名称相同。",
             "example": "Prod incident default"
           },
           "description": {
@@ -29353,7 +30090,7 @@
           },
           "wecom_markdown_v2_enabled": {
             "type": "boolean",
-            "description": "企业微信群机器人通知使用 `markdown_v2` 消息格式，而非普通 markdown。"
+            "description": "企业微信机器人通知使用 `markdown_v2` 消息格式而非普通 markdown。开启时 `wecom` 渲染结果不得超过 4,096 字节。"
           },
           "feishu": {
             "type": "string",
@@ -29366,7 +30103,7 @@
           "feishu_app_card_v2_table_enabled": {
             "type": "boolean",
             "default": false,
-            "description": "是否在飞书应用卡片中以表格渲染告警标签，默认关闭。"
+            "description": "将 `feishu_app` 内容中的 Markdown 表格渲染为飞书卡片原生表格。"
           },
           "feishu_app_card_v2_preserve_blank_lines": {
             "type": "boolean",
@@ -29428,7 +30165,7 @@
           },
           "incident_card_hidden_fields": {
             "$ref": "#/components/schemas/IncidentCardHiddenFields",
-            "description": "按 IM 应用类型隐藏的故障卡片字段。"
+            "description": "按 IM 应用类型配置要隐藏的故障卡片字段。"
           }
         }
       },
@@ -29519,7 +30256,7 @@
           "template_id": {
             "type": "string",
             "pattern": "^[0-9a-fA-F]{24}$",
-            "description": "模板 ID。",
+            "description": "模板 ID（24 位十六进制）。内置预设模板的 ID 固定为 `6321aad26c12104586a88916`。",
             "example": "6605a1b2c3d4e5f6a7b8c9d0"
           },
           "template_name": {
@@ -29528,7 +30265,7 @@
           },
           "description": {
             "type": "string",
-            "description": "自定义描述。"
+            "description": "描述文字（最多 500 字符），未填写时为空字符串。"
           },
           "email": {
             "type": "string",
@@ -29564,7 +30301,7 @@
           },
           "feishu_app_card_v2_table_enabled": {
             "type": "boolean",
-            "description": "是否在飞书应用卡片中以表格渲染告警标签。"
+            "description": "`feishu_app` 内容中的 Markdown 表格是否渲染为飞书卡片原生表格。"
           },
           "feishu_app_card_v2_preserve_blank_lines": {
             "type": "boolean",
@@ -29611,7 +30348,10 @@
             "description": "Zoom 机器人消息模板源。"
           },
           "incident_card_closed_action_apps": {
-            "type": "array",
+            "type": [
+              "array",
+              "null"
+            ],
             "items": {
               "type": "string",
               "enum": [
@@ -29622,7 +30362,7 @@
                 "teams_app"
               ]
             },
-            "description": "已关闭故障的卡片仍保留自定义操作按钮的 IM 应用。可选值：`feishu_app`、`dingtalk_app`、`wecom_app`、`slack_app`、`teams_app`；空列表表示所有应用都隐藏这些按钮。"
+            "description": "对已关闭故障的卡片仍保留自定义操作按钮的 IM 应用（未关闭的故障总会显示）。取值：`feishu_app`、`dingtalk_app`、`wecom_app`、`slack_app`、`teams_app`。为空或 `null` 时，所有应用的已关闭故障卡片都隐藏这些按钮。"
           },
           "incident_card_hidden_fields": {
             "$ref": "#/components/schemas/IncidentCardHiddenFields",
@@ -29630,7 +30370,7 @@
           },
           "status": {
             "type": "string",
-            "description": "模板生命周期状态。`enabled` 启用中，可被分派策略引用发送通知；`disabled` 停用，不再用于新通知；`deleted` 已删除，列表接口不返回。",
+            "description": "模板状态。\n- `enabled`：可被分派策略使用。\n- `disabled`：不再用于新通知；无法通过本 API 设置。\n- `deleted`：已被 `/template/delete` 软删除；不出现在 `/template/list` 中，但 `/template/info` 仍会返回。",
             "enum": [
               "enabled",
               "disabled",
@@ -29685,7 +30425,7 @@
           },
           "orderby": {
             "type": "string",
-            "description": "排序字段。",
+            "description": "排序字段：`created_at`（默认，创建时间）或 `updated_at`（最后更新时间）。",
             "enum": [
               "created_at",
               "updated_at"
@@ -29693,12 +30433,12 @@
           },
           "asc": {
             "type": "boolean",
-            "description": "升序排序。",
+            "description": "为 `true` 时正序；默认最新的在前。",
             "default": false
           },
           "is_my_team": {
             "type": "boolean",
-            "description": "为 true 时只返回当前成员所属团队范围内的模板。",
+            "description": "为 `true` 时只返回调用方所在团队的模板。同时传了 `team_ids` 时只保留两者共有的团队；两者没有共同团队时不按团队过滤，返回所有团队的模板。调用方不属于任何团队时返回空结果。",
             "default": false
           },
           "team_ids": {
@@ -29707,7 +30447,7 @@
               "type": "integer",
               "format": "int64"
             },
-            "description": "按团队 ID 列表过滤。"
+            "description": "只返回这些团队 ID（可通过 `POST /team/list` 获取）的模板；`0` 表示账户级模板。为空或不传时不按团队过滤。与 `is_my_team` 的组合方式见该字段说明。"
           },
           "creator_id": {
             "type": [
@@ -29719,7 +30459,7 @@
           },
           "query": {
             "type": "string",
-            "description": "按模板名称做正则或子串匹配。"
+            "description": "对 `template_name` 做不区分大小写的正则匹配；不合法的正则按普通文本匹配。"
           }
         }
       },
@@ -29778,7 +30518,7 @@
             "type": "string",
             "minLength": 1,
             "maxLength": 39,
-            "description": "模板名称，长度 1–39 个字符。"
+            "description": "模板名称，1–39 个字符。每次调用都必填且会被写入；不能与其他模板重名。"
           },
           "description": {
             "type": [
@@ -29828,7 +30568,7 @@
               "boolean",
               "null"
             ],
-            "description": "设置后切换企业微信群机器人通知的 `markdown_v2` / 普通 markdown 格式；省略时保持当前设置。"
+            "description": "企业微信机器人通知使用 `markdown_v2` 消息格式而非普通 markdown。开启时 `wecom` 渲染结果不得超过 4,096 字节。不传则保持不变。"
           },
           "feishu": {
             "type": [
@@ -29849,7 +30589,7 @@
               "boolean",
               "null"
             ],
-            "description": "设置后开启或关闭飞书应用卡片中的告警标签表格渲染；省略时保持当前设置。"
+            "description": "将 `feishu_app` 内容中的 Markdown 表格渲染为飞书卡片原生表格。不传则保持不变。"
           },
           "feishu_app_card_v2_preserve_blank_lines": {
             "type": [
@@ -29944,21 +30684,21 @@
           },
           "incident_card_hidden_fields": {
             "$ref": "#/components/schemas/IncidentCardHiddenFields",
-            "description": "按 IM 应用类型隐藏的故障卡片字段。"
+            "description": "按 IM 应用类型配置要隐藏的故障卡片字段。传入时整体替换已存的值；不传则保持不变。"
           }
         }
       },
       "TimeFilter": {
         "type": "object",
-        "description": "周期性时间窗口。`start`/`end` 采用 24 小时制 `HH:MM`；`repeat` 采用 ISO 风格的星期索引（0=周日 … 6=周六）。",
+        "description": "周期时间窗口。`start`、`end` 为 24 小时制 `HH:MM`，`start` 不得晚于 `end`（窗口不能跨零点）；`00:00`–`00:00` 表示全天。",
         "properties": {
           "start": {
             "type": "string",
-            "description": "窗口开始时间（`HH:MM`）。"
+            "description": "窗口开始时间，`HH:MM`，包含该分钟。"
           },
           "end": {
             "type": "string",
-            "description": "窗口结束时间（`HH:MM`）。"
+            "description": "窗口结束时间，`HH:MM`，包含该分钟（`23:59` 持续到午夜）。"
           },
           "repeat": {
             "type": "array",
@@ -29967,15 +30707,15 @@
               "minimum": 0,
               "maximum": 6
             },
-            "description": "窗口每周生效的日期，空表示每天。"
+            "description": "窗口生效的星期：`0` 为周日 … `6` 为周六。为空表示每天。"
           },
           "cal_id": {
             "type": "string",
-            "description": "可选日历 ID，将窗口限制为日历中的匹配日期。"
+            "description": "服务日历 ID，来自 `POST /calendar/list`（如 `cal.xxxx`）。设置后，窗口只在该日历的工作日或休息日生效，由 `is_off` 决定。"
           },
           "is_off": {
             "type": "boolean",
-            "description": "为 true 时匹配日历中标记为休息日的日期。"
+            "description": "与 `cal_id` 搭配使用：`true` 仅在日历的休息日生效，`false` 仅在工作日生效。"
           }
         }
       },
@@ -30026,7 +30766,7 @@
           },
           "rule_name": {
             "type": "string",
-            "description": "规则名称。"
+            "description": "排除规则名称，1–39 个字符。"
           },
           "description": {
             "type": "string",
@@ -30034,7 +30774,7 @@
           },
           "filters": {
             "$ref": "#/components/schemas/FilterGroup",
-            "description": "告警事件匹配条件（OR-of-AND 结构）；命中的事件被完全丢弃。为空时规则不匹配任何事件。"
+            "description": "告警事件匹配条件（AND 组之间为 OR），命中的事件被直接丢弃。为空表示不匹配任何事件；若最近一次更新未传 `filters`，此处为 `null`。"
           },
           "status": {
             "type": "string",
@@ -30089,7 +30829,7 @@
               "null"
             ],
             "format": "int64",
-            "description": "新的所属团队 ID，可通过 `POST /team/list` 获取。"
+            "description": "新的所属团队 ID，可通过 `POST /team/list` 获取，必须存在。不传或传 `null` 保持原值。"
           },
           "managing_team_ids": {
             "type": "array",
@@ -30098,7 +30838,7 @@
               "format": "int64"
             },
             "maxItems": 3,
-            "description": "可管理该协作空间的其他团队 ID，最多 3 个。"
+            "description": "替换可管理该协作空间的其他团队，最多 3 个，每个 ID 都必须存在。传 `[]` 清空；不传保持原值。"
           },
           "channel_name": {
             "type": [
@@ -30107,7 +30847,7 @@
             ],
             "minLength": 1,
             "maxLength": 59,
-            "description": "新的协作空间名称，1 到 59 个字符。"
+            "description": "新的协作空间名称，1–59 个字符，账户内唯一。不传或传 `null` 保持原值。"
           },
           "description": {
             "type": [
@@ -30133,7 +30873,7 @@
               "trigger",
               "update"
             ],
-            "description": "自动恢复计时模式：`trigger` 在故障触发时启动计时，`update` 在每次告警更新时重新计时。仅在请求同时携带 `auto_resolve_timeout` 时生效。"
+            "description": "自动恢复的计时方式：`trigger` 在故障触发时开始计时，只计一次；`update` 每当有新告警并入时重新计时。只有与 `auto_resolve_timeout` 一起传入才生效；只传 `auto_resolve_timeout` 时模式重置为 `trigger`。"
           },
           "is_private": {
             "type": [
@@ -30144,11 +30884,11 @@
           },
           "group": {
             "$ref": "#/components/schemas/Group",
-            "description": "告警聚合配置。"
+            "description": "告警聚合配置；传入时整体替换原配置。"
           },
           "flapping": {
             "$ref": "#/components/schemas/Flapping",
-            "description": "抖动检测配置。"
+            "description": "抖动检测配置；传入时整体替换原配置。"
           },
           "disable_outlier_detection": {
             "type": [
@@ -30169,21 +30909,21 @@
               "boolean",
               "null"
             ],
-            "description": "允许外部上报人向该协作空间上报故障。"
+            "description": "`true` 开启外部上报并生成新令牌，在响应中返回（旧令牌随即失效）；`false` 关闭外部上报并清空令牌。"
           },
           "event_group": {
             "$ref": "#/components/schemas/EventGroup",
-            "description": "告警事件合并配置。仅在传入时更新。"
+            "description": "告警事件合并配置；传入时整体替换原配置。"
           }
         }
       },
       "UpdateChannelResponse": {
         "type": "object",
-        "description": "更新协作空间的响应。仅在请求中将 `is_external_report_enabled` 设为 `true` 时返回有效字段，否则所有字段为空。",
+        "description": "仅当请求中 `is_external_report_enabled` 为 `true` 时包含 `external_report_token`，否则 `data` 为空对象。",
         "properties": {
           "external_report_token": {
             "type": "string",
-            "description": "新生成的外部上报令牌。仅在请求中将 `is_external_report_enabled` 设为 `true` 时返回。调用方应保存此值，之后无法再次获取。"
+            "description": "新生成的外部上报令牌，旧令牌随即失效。之后可通过 `POST /channel/info` 返回的 `external_report_token` 再次读取。"
           }
         }
       },
@@ -30215,11 +30955,11 @@
           "description": {
             "type": "string",
             "maxLength": 500,
-            "description": "规则描述，最多 500 个字符。"
+            "description": "规则描述，最多 500 个字符。不传会清空原描述。"
           },
           "filters": {
             "$ref": "#/components/schemas/FilterGroup",
-            "description": "告警事件匹配条件（OR-of-AND 结构）；命中的事件被完全丢弃。为空时规则不匹配任何事件。"
+            "description": "告警事件匹配条件（AND 组之间为 OR），命中的事件被直接丢弃。可用字段：`title`、`description`、`severity`（别名 `alert_severity`、`event_severity`）、`status`、`alert_key`、`title_rule`、`integration_id`（别名 `data_source_id`），或任意 `labels.<name>`。会整体替换原条件；不传则清空条件，规则不再匹配任何事件。"
           }
         }
       },
@@ -30249,16 +30989,16 @@
               "integer",
               "null"
             ],
-            "description": "匹配优先级，数值越小越优先。"
+            "description": "匹配顺序，数值越小越先匹配。不传或传 `null` 时保持原值。"
           },
           "aggr_window": {
             "type": "integer",
-            "description": "延迟窗口，单位秒，0 表示不延迟。"
+            "description": "新分派故障首次通知前的延迟（秒），`0` 表示立即通知。不传会重置为 `0`。"
           },
           "template_id": {
             "type": "string",
             "pattern": "^[0-9a-fA-F]{24}$",
-            "description": "通知模板 ID（MongoDB ObjectID）。"
+            "description": "通知模板 ID（24 位十六进制），可通过 `POST /template/list` 获取，必须存在。"
           },
           "rule_name": {
             "type": "string",
@@ -30269,7 +31009,7 @@
           "description": {
             "type": "string",
             "maxLength": 500,
-            "description": "策略描述，最多 500 个字符。"
+            "description": "策略描述，最多 500 个字符。不传会清空原描述。"
           },
           "layers": {
             "type": "array",
@@ -30283,17 +31023,17 @@
             "items": {
               "$ref": "#/components/schemas/TimeFilter"
             },
-            "description": "可选的周期性生效时间窗口。"
+            "description": "策略可参与匹配的周期时间窗口。会整体替换原窗口；不传或为空表示任何时间。"
           },
           "filters": {
             "$ref": "#/components/schemas/FilterGroup",
-            "description": "故障级匹配条件（OR-of-AND 结构）：策略匹配的是告警聚合而成的故障，而不是告警本身。不传或为空时对空间内所有故障生效。"
+            "description": "故障匹配条件（AND 组之间为 OR），匹配的是告警所属的故障而不是告警本身。可用字段：`title`、`description`、`severity`（别名 `incident_severity`、`alert_severity`）、`status`（别名 `incident_status`、`alert_status`）、`dedup_key`、`integration_id`（别名 `data_source_id`），或任意 `labels.<name>`。会整体替换原条件；不传或为空时匹配协作空间内的所有故障。"
           }
         }
       },
       "UpdateIncidentFieldsRequest": {
         "type": "object",
-        "description": "更新故障可编辑字段的参数。至少需要提供一个字段；handler 只会更新显式传入的字段。",
+        "description": "要更新的故障字段。除 `incident_id` 外至少要有一个非空字段；未传或为空的字段保持原值。",
         "required": [
           "incident_id"
         ],
@@ -30373,26 +31113,26 @@
           "description": {
             "type": "string",
             "maxLength": 500,
-            "description": "策略描述，最多 500 个字符。"
+            "description": "策略描述，最多 500 个字符。不传会清空原描述。"
           },
           "equals": {
             "type": "array",
             "items": {
               "type": "string"
             },
-            "description": "源（抑制方）告警与目标（被抑制）告警之间必须取值相等的字段键，例如 `data_source_id` 或 `labels.cluster`。"
+            "description": "源告警与新事件取值必须相同的字段。只有 `title`、`severity` 和 `labels.<name>` 有效；其他字段（例如 `data_source_id`）虽能保存，但会导致策略永远不生效。必须传入；空数组同样使策略不生效。"
           },
           "source_filters": {
             "$ref": "#/components/schemas/FilterGroup",
-            "description": "源告警需要满足的条件，针对已存的活跃告警求值。支持的键：`status`、`incident_status`、`alert_status`、`severity`、`incident_severity`、`alert_severity`、`title`、`description` 或任意 `labels.<name>`。为空时策略不生效。"
+            "description": "源告警（起抑制作用的告警）需满足的条件，匹配对象是协作空间内已存储的活跃告警。可用字段：`title`、`description`、`severity`（别名 `incident_severity`、`alert_severity`）、`status`（别名 `incident_status`、`alert_status`），或任意 `labels.<name>`。为空时策略不生效。不传会清空原条件。"
           },
           "target_filters": {
             "$ref": "#/components/schemas/FilterGroup",
-            "description": "目标（被抑制）告警事件需要满足的条件；为空表示所有事件都是抑制目标。"
+            "description": "新进入的告警事件需满足的条件，满足才会被抑制；为空表示所有新事件都是抑制对象。可用字段：`title`、`description`、`severity`（别名 `alert_severity`、`event_severity`）、`status`、`alert_key`、`title_rule`、`integration_id`（别名 `data_source_id`），或任意 `labels.<name>`。不传会清空原条件。"
           },
           "is_directly_discard": {
             "type": "boolean",
-            "description": "为 true 时，命中的告警事件被完全丢弃；为 false 时，告警仍会被记录，但标记为被本策略静默。"
+            "description": "为 true 时，命中的告警事件被直接丢弃；为 false 时，告警仍会记录，但标记为被该策略抑制。不传会设为 `false`。"
           }
         }
       },
@@ -30424,7 +31164,7 @@
           "description": {
             "type": "string",
             "maxLength": 500,
-            "description": "策略描述，最多 500 个字符。"
+            "description": "策略描述，最多 500 个字符。不传会清空原描述。"
           },
           "time_filters": {
             "type": "array",
@@ -30439,15 +31179,15 @@
           },
           "filters": {
             "$ref": "#/components/schemas/FilterGroup",
-            "description": "要静默的告警匹配条件，必填且不能为空。"
+            "description": "告警事件匹配条件（AND 组之间为 OR），时间窗口内命中的事件被静默。必填，且至少包含一个条件。可用字段：`title`、`description`、`severity`（别名 `alert_severity`、`event_severity`）、`status`、`alert_key`、`title_rule`、`integration_id`（别名 `data_source_id`），或任意 `labels.<name>`。"
           },
           "is_directly_discard": {
             "type": "boolean",
-            "description": "为 true 时，命中的告警事件被完全丢弃；为 false 时，告警仍会被记录，但标记为被本策略静默。"
+            "description": "为 true 时，命中的告警事件被直接丢弃；为 false 时，告警仍会记录，但标记为被该策略静默。不传会设为 `false`。"
           },
           "is_auto_delete": {
             "type": "boolean",
-            "description": "为 true 时，静默规则在时间窗结束后会被自动删除；默认为 false。"
+            "description": "为 true 时，使用一次性 `time_filter` 的策略在 `end_time`（或最近一次更新时间，取较晚者）约 24 小时后被永久移除。通过 `from_incident_id` 创建的策略同样按此方式清理。使用周期 `time_filters` 的策略不会被自动移除。不传会设为 `false`。"
           }
         }
       },
@@ -30483,14 +31223,14 @@
               "type": "integer",
               "format": "int64"
             },
-            "description": "事件负责成员 ID 列表。传入完整替换列表。"
+            "description": "该事件的负责人成员 ID，整体替换原列表。省略或传空数组时保留原列表。"
           },
           "linked_changes": {
             "type": "array",
             "items": {
               "type": "string"
             },
-            "description": "关联的事件 ID 列表。传入完整替换列表。"
+            "description": "关联事件 ID，整体替换原列表。省略或传空数组时保留原列表。"
           }
         }
       },
@@ -30520,17 +31260,17 @@
           "at_seconds": {
             "type": "integer",
             "format": "int64",
-            "description": "新的更新时间戳（Unix 秒）。"
+            "description": "新的更新时间，Unix 时间戳（秒），不能早于前一条更新、也不能晚于后一条更新。省略或传 0 时保持不变。"
           },
           "description": {
             "type": "string",
-            "description": "新的更新说明（Markdown）。"
+            "description": "新的更新描述（Markdown）。省略或传空字符串时保持不变；修改最新一条更新时会同步更新事件描述。"
           }
         }
       },
       "UpsertRouteRequest": {
         "type": "object",
-        "description": "创建或更新集成路由规则的参数。当指定集成尚无规则时执行创建,否则覆盖原有规则。`cases` 与 `default` 至少需要提供其一。",
+        "description": "创建集成的路由规则；已存在时整体替换。`cases` 与 `default` 至少提供其一。",
         "required": [
           "integration_id"
         ],
@@ -30538,7 +31278,7 @@
           "integration_id": {
             "type": "integer",
             "format": "int64",
-            "description": "所属集成 ID。"
+            "description": "共享集成 ID，可通过 `POST /integration/list` 获取。协作空间专属集成会返回 `InvalidParameter`。"
           },
           "cases": {
             "type": "array",
@@ -30556,12 +31296,12 @@
           },
           "default": {
             "$ref": "#/components/schemas/RouteDefault",
-            "description": "兜底分支，所有 case 均未命中时使用。"
+            "description": "没有任何 case 得到协作空间时使用的兜底分支。不传会删除已有的默认分支。"
           },
           "version": {
             "type": "integer",
             "format": "int64",
-            "description": "预留给乐观并发控制使用；当前服务端忽略该字段——每次 upsert 时服务端会自动递增 `version`。"
+            "description": "会被忽略。服务端每次写入都会递增 `version`，不会与此值比较。"
           }
         }
       },
@@ -30586,7 +31326,7 @@
       },
       "WarRoom": {
         "type": "object",
-        "description": "从 IM 侧拉取的战情室实时详情。若群组已在 IM 侧被删除则返回空对象。",
+        "description": "从 IM 平台读取的作战室群组信息。IM 查询失败时（例如群组已在 Flashduty 之外解散），所有字段均为空字符串。",
         "required": [
           "chat_id",
           "chat_name",
@@ -30625,7 +31365,7 @@
           "account_id": {
             "type": "integer",
             "format": "int64",
-            "description": "账号 ID。"
+            "description": "该记录所属账户的 ID；同一 `app_key` 返回的记录该值都相同。"
           },
           "integration_id": {
             "type": "integer",
@@ -30648,20 +31388,26 @@
           },
           "status": {
             "type": "string",
-            "description": "作战室记录状态：`enabled` 生效中，`deleted` 已解散。",
+            "description": "记录状态。列表中恒为 `enabled`，已删除的作战室不会返回。",
             "enum": [
-              "enabled",
-              "deleted"
+              "enabled"
             ]
           },
           "created_at": {
             "type": "integer",
             "format": "int64",
-            "description": "创建时间戳（秒）。"
+            "description": "作战室创建的 Unix 时间戳（秒）。"
           },
           "plugin_type": {
             "type": "string",
-            "description": "IM 插件类型（如 `feishu`、`dingtalk`、`wecom`、`slack`）。"
+            "description": "IM 集成的插件类型：`feishu_app`（飞书）、`dingtalk_app`（钉钉）、`wecom_app`（企业微信）、`slack_app`（Slack）。集成已不存在时为空字符串。",
+            "enum": [
+              "feishu_app",
+              "dingtalk_app",
+              "wecom_app",
+              "slack_app",
+              ""
+            ]
           },
           "chat_name": {
             "type": "string",
@@ -30692,11 +31438,11 @@
           "integration_id": {
             "type": "integer",
             "format": "int64",
-            "description": "集成 ID。"
+            "description": "发出该请求的 Webhook 集成 ID。"
           },
           "event_id": {
             "type": "string",
-            "description": "事件 ID。"
+            "description": "本条推送记录的 ID：推送日期（`YYYYMMDD`）加随机后缀。可传给 `POST /webhook/history/detail`。"
           },
           "webhook_type": {
             "type": "string",
@@ -30725,7 +31471,7 @@
           },
           "request_body": {
             "type": "string",
-            "description": "出站请求体。"
+            "description": "发送给目标地址的 JSON 请求体，超过存储上限的部分被截断。"
           },
           "endpoint": {
             "type": "string",
@@ -30733,11 +31479,11 @@
           },
           "attempt": {
             "type": "integer",
-            "description": "尝试次数。"
+            "description": "本次推送的 HTTP 尝试次数；仅在连接错误时重试。"
           },
           "duration": {
             "type": "integer",
-            "description": "整次尝试耗时（毫秒）。"
+            "description": "本次推送（含重试）的总耗时，单位毫秒。"
           },
           "status": {
             "type": "string",
@@ -30745,15 +31491,15 @@
               "success",
               "failed"
             ],
-            "description": "投递结果。"
+            "description": "推送结果：目标地址返回 HTTP 200 时为 `success`；连接错误或返回其他状态码时为 `failed`。"
           },
           "status_code": {
             "type": "integer",
-            "description": "HTTP 状态码。"
+            "description": "目标地址返回的 HTTP 状态码；未收到响应时为 `0`。"
           },
           "error_message": {
             "type": "string",
-            "description": "投递失败时的错误信息。"
+            "description": "推送失败时的错误信息（连接错误或非预期状态码），会被截断。成功时不返回。"
           },
           "response_headers": {
             "type": "string",
@@ -30761,7 +31507,7 @@
           },
           "response_body": {
             "type": "string",
-            "description": "响应体。"
+            "description": "目标地址返回的响应体，超过存储上限的部分被截断。为空或未收到响应时不返回。"
           },
           "event_time": {
             "type": "string",
@@ -30796,11 +31542,11 @@
           "integration_id": {
             "type": "integer",
             "format": "int64",
-            "description": "触发 Webhook 的集成 ID。"
+            "description": "发出该请求的 Webhook 集成 ID。"
           },
           "event_id": {
             "type": "string",
-            "description": "本次投递的唯一事件 ID。"
+            "description": "本条推送记录的 ID：推送日期（`YYYYMMDD`）加随机后缀。可传给 `POST /webhook/history/detail`。"
           },
           "webhook_type": {
             "type": "string",
@@ -30829,7 +31575,7 @@
           },
           "request_body": {
             "type": "string",
-            "description": "出站请求体。"
+            "description": "发送给目标地址的 JSON 请求体，超过存储上限的部分被截断。"
           },
           "endpoint": {
             "type": "string",
@@ -30837,11 +31583,11 @@
           },
           "attempt": {
             "type": "integer",
-            "description": "尝试次数。"
+            "description": "本次推送的 HTTP 尝试次数；仅在连接错误时重试。"
           },
           "duration": {
             "type": "integer",
-            "description": "整次尝试耗时（毫秒）。"
+            "description": "本次推送（含重试）的总耗时，单位毫秒。"
           },
           "status": {
             "type": "string",
@@ -30849,15 +31595,15 @@
               "success",
               "failed"
             ],
-            "description": "投递结果。"
+            "description": "推送结果：目标地址返回 HTTP 200 时为 `success`；连接错误或返回其他状态码时为 `failed`。"
           },
           "status_code": {
             "type": "integer",
-            "description": "目标返回的 HTTP 状态码。"
+            "description": "目标地址返回的 HTTP 状态码；未收到响应时为 `0`。"
           },
           "error_message": {
             "type": "string",
-            "description": "投递失败时的错误信息。"
+            "description": "推送失败时的错误信息（连接错误或非预期状态码），会被截断。成功时不返回。"
           },
           "response_headers": {
             "type": "string",
@@ -30865,7 +31611,7 @@
           },
           "response_body": {
             "type": "string",
-            "description": "目标返回的响应体。"
+            "description": "目标地址返回的响应体，超过存储上限的部分被截断。为空或未收到响应时不返回。"
           },
           "event_time": {
             "type": "string",
@@ -31074,7 +31820,7 @@
             "type": "string",
             "pattern": "^[a-zA-Z_][a-zA-Z0-9_]{0,39}$",
             "maxLength": 39,
-            "description": "机器名。必须以字母或下划线开头，长度 1–40，由 `[a-zA-Z0-9_]` 组成；创建后不可更改。"
+            "description": "字段标识：1–39 个 `[a-zA-Z0-9_]` 字符，以字母或下划线开头，创建后不可修改。"
           },
           "display_name": {
             "type": "string",
@@ -31148,11 +31894,11 @@
           "display_name": {
             "type": "string",
             "maxLength": 39,
-            "description": "新的展示名，账号内仍须唯一。"
+            "description": "新的显示名称（最长 39 字符），须在未删除字段中保持唯一。每次都会写入。"
           },
           "description": {
             "type": "string",
-            "description": "新描述。"
+            "description": "新描述。每次都会写入：不传即清空描述。"
           },
           "options": {
             "type": "array",
@@ -31162,7 +31908,7 @@
             "description": "替换后的选项列表，规则与创建时相同。注意：更新接口总是用提交的值覆盖 `display_name`、`description`、`options` 和 `default_value`，因此 `single_select`/`multi_select` 字段每次更新都必须传非空 `options`。"
           },
           "default_value": {
-            "description": "替换后的默认值，类型须与字段当前 `field_type` 匹配。",
+            "description": "新的默认值，类型须与字段的 `field_type` 一致。每次都会写入：不传即清空默认值。",
             "oneOf": [
               {
                 "type": "boolean"
@@ -31270,7 +32016,10 @@
             "description": "变更事件发生时的 Unix 时间戳（秒）。"
           },
           "labels": {
-            "type": "object",
+            "type": [
+              "object",
+              "null"
+            ],
             "additionalProperties": {
               "type": "string"
             },
@@ -31291,7 +32040,22 @@
             "format": "int64",
             "description": "变更事件的删除时间，Unix 时间戳（秒）。未删除时不返回该字段。"
           }
-        }
+        },
+        "required": [
+          "event_id",
+          "account_id",
+          "channel_id",
+          "integration_id",
+          "title",
+          "description",
+          "change_key",
+          "change_status",
+          "link",
+          "event_time",
+          "labels",
+          "created_at",
+          "updated_at"
+        ]
       },
       "ChangeItem": {
         "type": "object",
@@ -31312,14 +32076,15 @@
           },
           "channel_name": {
             "type": "string",
-            "description": "协作通道名称。"
+            "description": "协作空间名称；变更未关联到现有协作空间时为空字符串。"
           },
           "channel_status": {
             "type": "string",
-            "description": "协作空间状态：`enabled`（启用）或 `disabled`（禁用）。",
+            "description": "协作空间状态：`enabled` 或 `disabled`；变更未关联到现有协作空间时为空字符串。",
             "enum": [
               "enabled",
-              "disabled"
+              "disabled",
+              ""
             ]
           },
           "integration_id": {
@@ -31371,11 +32136,14 @@
             "description": "变更结束时的 Unix 时间戳（秒）。"
           },
           "labels": {
-            "type": "object",
+            "type": [
+              "object",
+              "null"
+            ],
             "additionalProperties": {
               "type": "string"
             },
-            "description": "附加到变更上的键值标签。"
+            "description": "变更附带的键值标签；没有标签时为 `null`。"
           },
           "link": {
             "type": "string",
@@ -31386,9 +32154,27 @@
             "items": {
               "$ref": "#/components/schemas/ChangeEventItem"
             },
-            "description": "底层变更事件，仅在 include_events 为 true 时返回。"
+            "description": "构成该变更的、由集成上报的原始变更事件。仅在 `include_events` 为 `true` 时返回。"
           }
-        }
+        },
+        "required": [
+          "change_id",
+          "account_id",
+          "channel_id",
+          "channel_name",
+          "channel_status",
+          "integration_id",
+          "integration_name",
+          "title",
+          "description",
+          "change_key",
+          "change_status",
+          "start_time",
+          "last_time",
+          "end_time",
+          "labels",
+          "link"
+        ]
       },
       "ListChangeRequest": {
         "type": "object",
@@ -31396,24 +32182,25 @@
           "start_time": {
             "type": "integer",
             "format": "int64",
-            "description": "查询窗口起点，Unix 时间戳（秒）。可选——`start_time` 和 `end_time` 都不传或为 0 时，默认查询最近一小时。必须小于 `end_time`，跨度不超过 31 天。当变更的 [start_time, last_time] 区间与查询窗口重叠时命中。",
+            "description": "查询时间窗起点，Unix 时间戳（秒）。实际为必填：必须小于 `end_time`，时间跨度不超过 31 天。变更的 [start_time, last_time] 区间与时间窗有重叠即匹配。",
             "minimum": 0
           },
           "end_time": {
             "type": "integer",
             "format": "int64",
-            "description": "查询窗口终点，Unix 时间戳（秒）。默认值与约束见 `start_time`。",
+            "description": "查询时间窗终点，Unix 时间戳（秒）。实际为必填，约束见 `start_time`。",
             "minimum": 0
           },
           "p": {
             "type": "integer",
-            "description": "页码，从 1 开始。",
+            "description": "页码，从 1 开始，默认 1。",
             "format": "int64",
-            "minimum": 1
+            "minimum": 1,
+            "default": 1
           },
           "limit": {
             "type": "integer",
-            "description": "每页条数。",
+            "description": "每页条数，1-100，默认 10。",
             "format": "int64",
             "minimum": 1,
             "maximum": 100,
@@ -31423,7 +32210,7 @@
             "type": "array",
             "items": {
               "type": "integer",
-              "description": "",
+              "description": "协作空间 ID。",
               "format": "int64"
             },
             "description": "按协作空间 ID 过滤。"
@@ -31432,7 +32219,7 @@
             "type": "array",
             "items": {
               "type": "integer",
-              "description": "",
+              "description": "集成 ID。",
               "format": "int64"
             },
             "description": "按上报集成 ID 过滤。提供时至少 1 个。",
@@ -31490,7 +32277,11 @@
             "deprecated": true,
             "description": "已废弃：请使用 `integration_ids`。按单个集成 ID 过滤。"
           }
-        }
+        },
+        "required": [
+          "start_time",
+          "end_time"
+        ]
       },
       "ListChangeResponse": {
         "type": "object",
@@ -31511,7 +32302,12 @@
             },
             "description": "当前页的变更列表。"
           }
-        }
+        },
+        "required": [
+          "total",
+          "has_next_page",
+          "items"
+        ]
       },
       "WarRoomPersonItem": {
         "type": "object",
@@ -31523,7 +32319,7 @@
           },
           "person_id": {
             "type": "integer",
-            "description": "人员 ID。",
+            "description": "人员 ID：成员 ID；若为账户所有者（`as` = `account`）则为账户 ID。",
             "format": "int64"
           },
           "person_name": {
@@ -31536,27 +32332,36 @@
           },
           "email": {
             "type": "string",
-            "description": "人员邮箱地址。"
+            "description": "邮箱地址；成员未验证时不返回。"
           },
           "phone": {
             "type": "string",
-            "description": "人员电话号码。"
+            "description": "手机号；成员未验证时不返回。"
           },
           "locale": {
             "type": "string",
-            "description": "人员偏好的语言区域。"
+            "description": "偏好语言，例如 `zh-CN` 或 `en-US`。"
           },
           "time_zone": {
             "type": "string",
-            "description": "人员所在时区。"
+            "description": "IANA 时区名，例如 `Asia/Shanghai`。"
           },
           "as": {
             "type": "string",
-            "description": "人员在相关上下文中担任的角色。"
+            "enum": [
+              "account",
+              "member"
+            ],
+            "description": "人员身份类型。\n- `account`：账户所有者。\n- `member`：账户内的普通成员。"
           },
           "status": {
             "type": "string",
-            "description": "人员当前状态。"
+            "enum": [
+              "enabled",
+              "pending",
+              "deleted"
+            ],
+            "description": "成员状态。\n- `enabled`：正常。\n- `pending`：已邀请但尚未加入。\n- `deleted`：已从账户移除。"
           }
         },
         "required": [
@@ -31569,7 +32374,8 @@
         "properties": {
           "incident_id": {
             "type": "string",
-            "description": "故障 ID，MongoDB ObjectID 十六进制字符串。"
+            "pattern": "^[0-9a-fA-F]{24}$",
+            "description": "故障 ID（MongoDB ObjectID）。"
           }
         },
         "required": [
@@ -31584,9 +32390,12 @@
             "items": {
               "$ref": "#/components/schemas/WarRoomPersonItem"
             },
-            "description": "建议作为作战室默认观察者的历史响应人。"
+            "description": "建议的观察者，按时间线顺序排列。没有时为空数组。"
           }
-        }
+        },
+        "required": [
+          "observers"
+        ]
       },
       "AddWarRoomMemberRequest": {
         "type": "object",
@@ -31598,15 +32407,16 @@
           },
           "chat_id": {
             "type": "string",
-            "description": "IM 平台中作战室的群聊 ID。"
+            "description": "作战室群在 IM 平台上的会话 ID，可从 `POST /incident/war-room/list` 返回的作战室信息中获取。"
           },
           "member_ids": {
             "type": "array",
+            "minItems": 1,
             "items": {
               "type": "integer",
               "format": "int64"
             },
-            "description": "要加入作战室的人员 ID 列表。"
+            "description": "要添加的人员 ID（成员 ID；账户所有者为账户 ID）。不能为空。"
           }
         },
         "required": [
@@ -31620,32 +32430,54 @@
         "properties": {
           "content": {
             "type": "string",
-            "description": "要渲染的模板内容。"
+            "description": "按通道 `type` 渲染的模板内容。为空或不传时预览该通道的内置预设内容；`push` 类型忽略此字段。"
           },
           "type": {
             "type": "string",
-            "description": "模板渠道类型，用于选择渲染引擎。`email` 按 Go html/template 渲染，其他渠道按 text/template 渲染。取值与模板渠道字段一致，如 `email`、`sms`、`voice`、`dingtalk`、`wecom`、`feishu`、`feishu_app`、`dingtalk_app`、`wecom_app`、`slack_app`、`teams_app`、`telegram`、`slack`、`zoom`。"
+            "description": "要预览的通道，其他取值返回 `InvalidParameter`。\n- `email`：邮件正文（HTML 模板）。\n- `sms`、`voice`：短信文本和语音电话话术。\n- `push`：移动 App 推送（内容固定，忽略 `content`）。\n- `dingtalk`、`wecom`、`feishu`、`zoom`、`telegram`、`slack`：机器人（Webhook）消息。\n- `feishu_app`、`dingtalk_app`、`wecom_app`、`slack_app`、`teams_app`：IM 应用卡片。",
+            "enum": [
+              "email",
+              "sms",
+              "voice",
+              "push",
+              "dingtalk",
+              "wecom",
+              "feishu",
+              "zoom",
+              "telegram",
+              "slack",
+              "feishu_app",
+              "dingtalk_app",
+              "wecom_app",
+              "slack_app",
+              "teams_app"
+            ]
           },
           "incident_id": {
             "type": "string",
-            "description": "用于渲染模板的故障 ID，省略时使用模拟数据。MongoDB ObjectID 十六进制字符串。",
+            "description": "用于渲染的故障 ID（24 位十六进制，可通过 `/incident/list` 获取），须为账户内存在的故障，否则返回 `InvalidParameter`。不传时使用模拟故障。",
             "pattern": "^[0-9a-fA-F]{24}$"
           },
           "incident_card_hidden_fields": {
             "$ref": "#/components/schemas/IncidentCardHiddenFields",
             "description": "预览时按 IM 应用隐藏的故障卡片字段。"
           },
-          "feishu_app_card_v2_enabled": {
+          "feishu_app_card_v2_table_enabled": {
             "type": "boolean",
-            "description": "按飞书应用卡片 v2 消息渲染预览。"
+            "default": false,
+            "description": "将 `feishu_app` 内容中的 Markdown 表格渲染为飞书卡片原生表格，与模板的同名设置一致。"
           },
           "feishu_app_card_v2_preserve_blank_lines": {
             "type": "boolean",
             "description": "飞书应用卡片 v2 预览保留正文中的空行。"
+          },
+          "wecom_markdown_v2_enabled": {
+            "type": "boolean",
+            "default": false,
+            "description": "按 `markdown_v2` 消息预览 `wecom` 内容，与模板的同名设置一致（大小上限 4,096 字节）。"
           }
         },
         "required": [
-          "content",
           "type"
         ],
         "description": "模板预览请求。"
@@ -31659,24 +32491,166 @@
           },
           "content": {
             "type": "string",
-            "description": "渲染后的模板输出，success 为 true 时返回。"
+            "description": "渲染后的模板内容；`success` 为 `false` 时为空字符串。"
           },
           "message": {
             "type": "string",
-            "description": "渲染失败的错误说明，success 为 false 时返回。"
+            "description": "渲染失败的原因（调用方语言）；`success` 为 `true` 时为空字符串。"
           },
-          "fixed_fields": {
+          "card": {
+            "type": "object",
+            "description": "渲染结果外层的消息框架，使用账户语言。仅 `email`、`feishu_app`、`dingtalk_app`、`wecom_app`、`slack_app`、`teams_app` 返回，其他类型省略。",
+            "required": [
+              "title",
+              "elements"
+            ],
+            "properties": {
+              "title": {
+                "type": "string",
+                "description": "邮件主题或卡片标题。"
+              },
+              "elements": {
+                "type": "array",
+                "description": "按显示顺序排列的卡片元素。",
+                "items": {
+                  "type": "object",
+                  "required": [
+                    "type"
+                  ],
+                  "properties": {
+                    "type": {
+                      "type": "string",
+                      "enum": [
+                        "template",
+                        "markdown",
+                        "divider",
+                        "actions"
+                      ],
+                      "description": "元素类型。\n- `template`：渲染后的模板（`content`）所在位置。\n- `markdown`：通道 Markdown 格式的固定文本，见 `content`。\n- `divider`：分隔线。\n- `actions`：一排按钮，见 `actions`。"
+                    },
+                    "content": {
+                      "type": "string",
+                      "description": "`markdown` 元素的文本；其他类型省略。"
+                    },
+                    "actions": {
+                      "type": "array",
+                      "description": "`actions` 元素的按钮；其他类型省略。",
+                      "items": {
+                        "type": "object",
+                        "required": [
+                          "text"
+                        ],
+                        "properties": {
+                          "text": {
+                            "type": "string",
+                            "description": "按钮文字。"
+                          },
+                          "style": {
+                            "type": "string",
+                            "enum": [
+                              "primary",
+                              "danger",
+                              "select"
+                            ],
+                            "description": "按钮样式：`primary`（主按钮）、`danger`（危险操作）、`select`（下拉菜单）。普通按钮省略。"
+                          }
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "blocks": {
             "type": "array",
+            "description": "收件端如何展示 `content`，按块拆分。对原样显示文本的通道省略。",
             "items": {
-              "$ref": "#/components/schemas/PreviewIncidentCardFixedField"
-            },
-            "description": "已应用隐藏规则后，为受支持 IM 预览返回的固定故障卡片字段。"
+              "type": "object",
+              "required": [
+                "type"
+              ],
+              "properties": {
+                "type": {
+                  "type": "string",
+                  "enum": [
+                    "markdown",
+                    "table"
+                  ],
+                  "description": "块类型：`markdown`（文本，见 `content`）或 `table`（表格，见 `columns`/`rows`）。"
+                },
+                "content": {
+                  "type": "string",
+                  "description": "`markdown` 块的文本。"
+                },
+                "native": {
+                  "type": "boolean",
+                  "description": "`table` 块以卡片原生表格展示时为 `true`，否则省略。"
+                },
+                "columns": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  },
+                  "description": "`table` 块的列名。"
+                },
+                "rows": {
+                  "type": "array",
+                  "items": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    }
+                  },
+                  "description": "`table` 块的单元格值，每行一个数组。"
+                },
+                "page_size": {
+                  "type": "integer",
+                  "description": "原生表格每页显示的行数；未设置时省略。"
+                }
+              }
+            }
+          },
+          "notices": {
+            "type": "array",
+            "description": "关于内容实际投递方式的提示；没有时省略。",
+            "items": {
+              "type": "object",
+              "required": [
+                "code"
+              ],
+              "properties": {
+                "code": {
+                  "type": "string",
+                  "enum": [
+                    "table_not_rendered",
+                    "native_table_fallback",
+                    "content_too_large"
+                  ],
+                  "description": "提示类型。\n- `table_not_rendered`：该通道不支持 Markdown 表格，表格按文本发送。\n- `native_table_fallback`：表格无法渲染为卡片原生表格，改用 Markdown 发送；`reason` 说明原因（`too_many_tables`、`too_many_columns`、`too_many_rows`、`cell_too_long`、`unsupported_cell`、`card_too_large`）。\n- `content_too_large`：内容超过 `size_limit_bytes`；`reason` 为 `truncated`（截断后发送）、`compact_fallback`（改用精简格式发送）或 `rejected`（通道会拒收）。"
+                },
+                "reason": {
+                  "type": "string",
+                  "description": "`code` 的具体原因，取值见 `code` 说明；`table_not_rendered` 时省略。"
+                }
+              }
+            }
+          },
+          "size_bytes": {
+            "type": "integer",
+            "description": "渲染结果的字节数，在任何截断之前统计。"
+          },
+          "size_limit_bytes": {
+            "type": "integer",
+            "description": "通道的大小上限（字节）：机器人通道（以及未开启 `markdown_v2` 的 `wecom`）为 4,000，开启 `markdown_v2` 的 `wecom` 为 4,096，`slack_app` 为 15,000，`feishu_app` 为 30,720；无上限的通道为 `0`。"
           }
         },
         "required": [
           "success",
           "content",
-          "message"
+          "message",
+          "size_bytes",
+          "size_limit_bytes"
         ],
         "description": "模板预览结果。"
       },
@@ -31717,11 +32691,21 @@
           },
           "category": {
             "type": "string",
-            "description": "插件类别；本接口返回的 IM 集成固定为 `im`。"
+            "description": "插件类别。本接口只返回 IM 集成，因此固定为 `im`。",
+            "enum": [
+              "im"
+            ]
           },
           "plugin_type": {
             "type": "string",
-            "description": "IM 集成插件类型标识，如 `feishu_app`、`dingtalk_app`、`wecom_app`、`slack_app`、`teams_app`。"
+            "description": "IM 集成类型：`feishu_app` 飞书，`dingtalk_app` 钉钉，`wecom_app` 企业微信，`slack_app` Slack，`teams_app` Microsoft Teams。",
+            "enum": [
+              "feishu_app",
+              "dingtalk_app",
+              "wecom_app",
+              "slack_app",
+              "teams_app"
+            ]
           },
           "plugin_type_name": {
             "type": "string",
@@ -31742,7 +32726,7 @@
           "settings": {
             "type": "object",
             "additionalProperties": true,
-            "description": "集成的插件特定配置。"
+            "description": "集成的插件配置，包含 `war_room_enabled: true`；密钥类字段掩码为 `******`。"
           },
           "no_editable": {
             "type": "boolean",
@@ -31775,12 +32759,12 @@
           },
           "exclusive_data_source_id": {
             "type": "integer",
-            "description": "历史遗留的独占集成关联 ID，已废弃。",
+            "description": "已废弃，本接口中恒为 `0`。",
             "format": "int64"
           },
           "integration_id": {
             "type": "integer",
-            "description": "集成 ID，data_source_id 的别名。",
+            "description": "集成 ID，与 `data_source_id` 相同。",
             "format": "int64"
           }
         },
@@ -31892,7 +32876,7 @@
           },
           "url_name": {
             "type": "string",
-            "description": "URL 安全的别名，在账户内唯一。"
+            "description": "状态页的 URL 安全 slug，在账户内同类型状态页中唯一。"
           },
           "type": {
             "type": "string",
@@ -31951,6 +32935,16 @@
             "type": "array",
             "items": {
               "type": "object",
+              "properties": {
+                "key": {
+                  "type": "string",
+                  "description": "页面上显示的链接文字。"
+                },
+                "value": {
+                  "type": "string",
+                  "description": "链接文字指向的地址，例如 `https://www.example.com`。"
+                }
+              },
               "additionalProperties": {
                 "type": "string"
               }
@@ -31981,7 +32975,11 @@
           },
           "template_preference": {
             "type": "string",
-            "description": "偏好的事件模板类型：`pre_defined` 或 `message`。从未设置时不返回。"
+            "description": "控制台发布事件时使用的模板模式：`message`（状态描述：按状态预设的描述文字）或 `pre_defined`（完整状态更新：包含标题、状态和描述的完整示例）。从未设置时省略，控制台此时按 `message` 处理。",
+            "enum": [
+              "pre_defined",
+              "message"
+            ]
           }
         },
         "required": [
@@ -32018,7 +33016,7 @@
         "properties": {
           "template_id": {
             "type": "string",
-            "description": "模板 ID，可通过 `POST /incident/post-mortem/template/list` 获取。"
+            "description": "要删除的自定义模板 ID，可从 `POST /incident/post-mortem/template/list` 获取。"
           }
         }
       },
@@ -32035,13 +33033,14 @@
             "minItems": 1,
             "maxItems": 10,
             "items": {
-              "type": "string"
+              "type": "string",
+              "pattern": "^[0-9a-fA-F]{24}$"
             },
-            "description": "要关联到复盘报告的故障 ID，1-10 个。"
+            "description": "要关联到报告的故障 ID（MongoDB ObjectID），1–10 个，须均在本账户中存在。同一组故障总是对应同一份报告。"
           },
           "template_id": {
             "type": "string",
-            "description": "用于初始化报告的模板 ID。"
+            "description": "模板 ID，可从 `POST /incident/post-mortem/template/list` 获取，例如内置的 `post_mortem_default_tmpl_en-us`、`post_mortem_default_tmpl_zh-cn`，或自定义模板 ID。"
           }
         }
       },
@@ -32054,17 +33053,17 @@
             "enum": [
               "created_at_seconds"
             ],
-            "description": "排序字段。"
+            "description": "自定义模板的排序字段。仅支持 `created_at_seconds`，也是默认值。"
           },
           "asc": {
             "type": "boolean",
-            "description": "为 true 时按升序排序。"
+            "description": "为 true 时自定义模板升序排列；默认 false（最新在前）。"
           },
           "p": {
             "type": "integer",
             "format": "int64",
             "minimum": 0,
-            "description": "页码，从 1 开始。"
+            "description": "页码，从 1 开始；0 或省略表示 1。"
           },
           "limit": {
             "type": "integer",
@@ -32072,11 +33071,11 @@
             "minimum": 0,
             "maximum": 100,
             "default": 20,
-            "description": "每页数量，最多 100。"
+            "description": "每页条数，1–100；0 或省略表示 20。"
           },
           "search_after_ctx": {
             "type": "string",
-            "description": "上一页响应返回的向后分页游标。"
+            "description": "本接口不支持游标分页，请勿设置，使用 `p` 分页。若传入则必须是整数字符串，且此时 `p` 被忽略（结果从第一页开始）。"
           }
         }
       },
@@ -32094,20 +33093,16 @@
             "items": {
               "$ref": "#/components/schemas/PostMortemTemplate"
             },
-            "description": "当前页的模板。"
+            "description": "当前页的模板；第 1 页的第一项为内置模板。"
           },
           "total": {
             "type": "integer",
             "format": "int64",
-            "description": "匹配的模板总数。"
+            "description": "模板总数，包含内置模板。"
           },
           "has_next_page": {
             "type": "boolean",
-            "description": "为 true 表示还有下一页。"
-          },
-          "search_after_ctx": {
-            "type": "string",
-            "description": "向后分页游标。"
+            "description": "还有下一页时为 true。"
           }
         }
       },
@@ -32129,11 +33124,11 @@
           "account_id": {
             "type": "integer",
             "format": "int64",
-            "description": "模板所属账号 ID。内置模板为 0。"
+            "description": "模板所属账户 ID；内置模板为 0。"
           },
           "template_id": {
             "type": "string",
-            "description": "模板 ID。内置模板使用稳定的 `post_mortem_default_tmpl_*` ID。"
+            "description": "模板 ID：内置模板为 `post_mortem_default_tmpl_zh-cn` 或 `post_mortem_default_tmpl_en-us`，自定义模板为服务端生成的 ID。"
           },
           "name": {
             "type": "string",
@@ -32145,7 +33140,7 @@
           },
           "content": {
             "type": "string",
-            "description": "用于初始化复盘正文的 BlockNote JSON 内容。"
+            "description": "模板正文，为序列化成字符串的 BlockNote 编辑器 JSON（块数组）。"
           },
           "content_markdown": {
             "type": "string",
@@ -32154,17 +33149,17 @@
           "team_id": {
             "type": "integer",
             "format": "int64",
-            "description": "管理团队 ID。内置模板为 0。"
+            "description": "管理团队 ID；内置模板为 0。"
           },
           "created_at_seconds": {
             "type": "integer",
             "format": "int64",
-            "description": "模板创建时间的 Unix 秒级时间戳。"
+            "description": "创建时间，Unix 秒级时间戳；内置模板为 0。"
           },
           "updated_at_seconds": {
             "type": "integer",
             "format": "int64",
-            "description": "模板最近更新时间的 Unix 秒级时间戳。"
+            "description": "最后更新时间，Unix 秒级时间戳；内置模板为 0。"
           }
         }
       },
@@ -32183,7 +33178,7 @@
           },
           "incidents_highest_severity": {
             "type": "string",
-            "description": "关联故障中的最高严重级别：`Critical`、`Warning`、`Info` 或 `Ok`。",
+            "description": "关联故障中的最高严重程度。\n- `Critical`：严重。\n- `Warning`：警告。\n- `Info`：提醒。\n- `Ok`：已恢复。",
             "enum": [
               "Critical",
               "Warning",
@@ -32201,13 +33196,13 @@
             "type": "integer",
             "format": "int64",
             "minimum": 0,
-            "description": "最晚关联故障关闭时间的 Unix 秒级时间戳；仍未关闭时为 0。"
+            "description": "关联故障中最晚的关闭时间，Unix 秒级时间戳。0（省略时也为 0）表示尚未关闭。"
           },
           "incidents_total_duration_seconds": {
             "type": "integer",
             "format": "int64",
             "minimum": 0,
-            "description": "故障总持续时间，单位秒。"
+            "description": "故障总时长（秒）；省略时为 0。"
           },
           "responder_ids": {
             "type": "array",
@@ -32215,7 +33210,7 @@
               "type": "integer",
               "format": "int64"
             },
-            "description": "写入报告的响应人成员 ID。"
+            "description": "作为报告处理人员保存的成员 ID。会替换已保存的列表；省略或传 `[]` 表示清空。无法解析为人员的 ID 会被丢弃。"
           }
         }
       },
@@ -32267,7 +33262,7 @@
           },
           "follow_ups": {
             "type": "string",
-            "description": "自由文本格式的后续行动项。"
+            "description": "后续行动文本，会替换已保存的内容。若为控制台后续行动格式的 JSON 数组（元素含 `title`、`status`、`priority`、`assignee_ids` 等），还会同步为结构化的后续行动事项。"
           }
         }
       },
@@ -32289,7 +33284,7 @@
               "drafting",
               "published"
             ],
-            "description": "目标报告状态：`drafting` 草稿，`published` 已发布。"
+            "description": "目标报告状态。\n- `drafting`：编辑中，仍可通过正文重置替换正文。\n- `published`：已发布；正文不再引用的媒体文件会被删除。"
           }
         }
       },
@@ -32307,7 +33302,8 @@
           },
           "title": {
             "type": "string",
-            "description": "新的报告标题。"
+            "maxLength": 256,
+            "description": "新的报告标题，最多 256 个字符。"
           }
         }
       },
@@ -32327,9 +33323,11 @@
       },
       "TryLinkPersonResponse": {
         "type": "object",
-        "description": "本次调用新关联的人员。如果没有成员可关联，响应中的 `new_linked_person_ids` 可能为空数组，或整个 `data` 字段被省略。",
+        "description": "本次关联尝试的结果。",
         "required": [
-          "new_linked_person_ids"
+          "new_linked_person_ids",
+          "unmatched_count",
+          "no_contact_count"
         ],
         "properties": {
           "new_linked_person_ids": {
@@ -32338,7 +33336,15 @@
               "type": "integer",
               "format": "int64"
             },
-            "description": "本次调用中新关联成功的人员 ID。"
+            "description": "本次调用中新关联到该 IM 应用的成员 ID，没有新关联时为空数组。"
+          },
+          "unmatched_count": {
+            "type": "integer",
+            "description": "有邮箱或手机号、已查询但未新关联的成员数：IM 平台中未找到、该 IM 账号已关联其他成员，或查询失败。"
+          },
+          "no_contact_count": {
+            "type": "integer",
+            "description": "因既无邮箱也无手机号而被跳过的未关联成员数。"
           }
         }
       },
@@ -32352,28 +33358,28 @@
         "properties": {
           "template_id": {
             "type": "string",
-            "description": "模板 ID。创建新模板时省略；更新已有模板时传入。"
+            "description": "要替换的自定义模板 ID。省略表示创建新模板（ID 由服务端生成）。"
           },
           "team_id": {
             "type": "integer",
             "format": "int64",
-            "description": "管理团队 ID。创建自定义模板时必填。"
+            "description": "管理团队 ID。创建时必填，且团队必须存在。更新时传入不同的团队 ID 会迁移模板；省略或传 0 保持当前团队。"
           },
           "name": {
             "type": "string",
-            "description": "模板名称。"
+            "description": "控制台中显示的模板名称。"
           },
           "description": {
             "type": "string",
-            "description": "模板描述。"
+            "description": "模板描述；省略时为空。"
           },
           "content": {
             "type": "string",
-            "description": "BlockNote JSON 模板内容。"
+            "description": "模板正文，为序列化成字符串的 BlockNote 编辑器 JSON（块数组）。基于该模板创建的报告以此为初始正文。"
           },
           "content_markdown": {
             "type": "string",
-            "description": "模板内容的 Markdown 版本。"
+            "description": "正文的 Markdown 版本，AI 生成报告时作为提纲使用。省略时为空。"
           }
         }
       },
@@ -32479,11 +33485,11 @@
                 },
                 "section_id": {
                   "type": "string",
-                  "description": "所属区域 ID。省略则将组件置于顶层。"
+                  "description": "所属分组 ID，必须是该状态页已有的分组。省略时组件位于顶层（更新时同样生效）。"
                 },
                 "name": {
                   "type": "string",
-                  "description": "组件显示名称。"
+                  "description": "组件显示名称，在状态页内必须唯一。"
                 },
                 "description": {
                   "type": "string",
@@ -32492,7 +33498,7 @@
                 "order_id": {
                   "type": "integer",
                   "format": "int64",
-                  "description": "在所属区域中的显示顺序。"
+                  "description": "在所属分组内的显示顺序；更新时未传则重置为 0。"
                 },
                 "hide_uptime": {
                   "type": "boolean",
@@ -32505,7 +33511,7 @@
                 "available_since_seconds": {
                   "type": "integer",
                   "format": "int64",
-                  "description": "组件可用起始时间（Unix 秒）。创建时缺省取当前时间；更新时覆盖原值。"
+                  "description": "组件开始可用的时间，Unix 时间戳（秒），作为可用率统计的起点。仅创建时生效，默认取当前时间；更新时忽略。"
                 }
               }
             },
@@ -32557,7 +33563,7 @@
                 },
                 "name": {
                   "type": "string",
-                  "description": "区域显示名称。"
+                  "description": "分组显示名称，在状态页内必须唯一。"
                 },
                 "description": {
                   "type": "string",
@@ -32566,7 +33572,7 @@
                 "order_id": {
                   "type": "integer",
                   "format": "int64",
-                  "description": "显示顺序。"
+                  "description": "分组的显示顺序；更新时未传则重置为 0。"
                 },
                 "hide_uptime": {
                   "type": "boolean",
@@ -32656,7 +33662,7 @@
           },
           "url_name": {
             "type": "string",
-            "description": "URL 安全的状态页路径，在账户和状态页类型内唯一。",
+            "description": "URL 安全 slug；会规范化为小写，非字母数字字符替换为连字符，且在账户内同类型状态页中必须唯一。",
             "maxLength": 255
           },
           "type": {
@@ -32669,12 +33675,12 @@
           },
           "custom_domain": {
             "type": "string",
-            "description": "公开状态页使用的自定义域名。",
+            "description": "自定义域名，仅公开页可设置，且不能被其他状态页占用。",
             "maxLength": 255
           },
           "page_title": {
             "type": "string",
-            "description": "状态页浏览器标题。"
+            "description": "为兼容保留的字段，服务端不会存储，传入无效果。"
           },
           "page_header": {
             "type": "string",
@@ -32706,6 +33712,16 @@
             "description": "状态页展示的自定义导航链接。",
             "items": {
               "type": "object",
+              "properties": {
+                "key": {
+                  "type": "string",
+                  "description": "页面上显示的链接文字。"
+                },
+                "value": {
+                  "type": "string",
+                  "description": "链接文字指向的地址，例如 `https://www.example.com`。"
+                }
+              },
               "additionalProperties": {
                 "type": "string"
               }
@@ -32717,7 +33733,7 @@
           },
           "subscription": {
             "$ref": "#/components/schemas/StatusPageSubscriptionItem",
-            "description": "订阅渠道开关。"
+            "description": "订阅渠道开关，默认均为 `false`。公开页只能开启 `email`，内部页只能开启 `im`。"
           }
         },
         "required": [
@@ -32776,7 +33792,7 @@
               "string",
               "null"
             ],
-            "description": "URL 安全的状态页路径，在账户和状态页类型内唯一。省略或传 null 表示保持原值。",
+            "description": "URL 安全 slug；会规范化为小写，非字母数字字符替换为连字符，且在账户内同类型状态页中必须唯一。省略或传 null 时保持不变。",
             "maxLength": 255
           },
           "custom_domain": {
@@ -32784,7 +33800,7 @@
               "string",
               "null"
             ],
-            "description": "公开状态页使用的自定义域名。省略或传 null 表示保持原值。",
+            "description": "公开状态页的自定义域名，不能被其他状态页占用；内部页不可设置。省略或传 null 时保持不变；传空字符串会移除域名。",
             "maxLength": 255
           },
           "page_title": {
@@ -32792,7 +33808,7 @@
               "string",
               "null"
             ],
-            "description": "状态页浏览器标题。省略或传 null 表示保持原值。"
+            "description": "为兼容保留的字段，服务端不会存储，传入无效果。"
           },
           "logo": {
             "type": [
@@ -32842,10 +33858,12 @@
               "string",
               "null"
             ],
-            "description": "事件日期展示方式。省略或传 null 表示保持原值。`calendar` 为日历视图；`list` 为列表视图。",
+            "description": "事件日期的展示方式：`calendar` 为日历视图，`list` 为列表视图。省略或传 null 时保持不变；传空字符串会清空该设置。",
             "enum": [
               "calendar",
-              "list"
+              "list",
+              "",
+              null
             ]
           },
           "display_uptime_mode": {
@@ -32853,11 +33871,13 @@
               "string",
               "null"
             ],
-            "description": "可用率展示方式。省略或传 null 表示保持原值。`chart_and_percentage` 同时展示图表与百分比；`chart` 仅展示图表；`none` 不展示。",
+            "description": "可用率的展示方式：`chart_and_percentage` 同时显示图表和百分比，`chart` 只显示图表，`none` 不显示。省略或传 null 时保持不变；传空字符串会清空该设置。",
             "enum": [
               "chart_and_percentage",
               "chart",
-              "none"
+              "none",
+              "",
+              null
             ]
           },
           "custom_links": {
@@ -32865,6 +33885,16 @@
             "description": "状态页展示的自定义导航链接。省略或传空数组表示保持当前链接。",
             "items": {
               "type": "object",
+              "properties": {
+                "key": {
+                  "type": "string",
+                  "description": "页面上显示的链接文字。"
+                },
+                "value": {
+                  "type": "string",
+                  "description": "链接文字指向的地址，例如 `https://www.example.com`。"
+                }
+              },
               "additionalProperties": {
                 "type": "string"
               }
@@ -32879,14 +33909,19 @@
           },
           "subscription": {
             "$ref": "#/components/schemas/StatusPageSubscriptionItem",
-            "description": "订阅渠道开关。省略或传 null 表示保持原值。"
+            "description": "订阅渠道开关。公开页只能开启 `email`，内部页只能开启 `im`。省略或传 null 时保持不变。"
           },
           "template_preference": {
             "type": [
               "string",
               "null"
             ],
-            "description": "偏好的事件模板类型：`pre_defined` 或 `message`。省略或传 null 表示保持原值。"
+            "description": "控制台发布事件时使用的模板模式：`message`（状态描述：按状态预设的描述文字）或 `pre_defined`（完整状态更新：包含标题、状态和描述的完整示例）。省略或传 null 时保持不变；服务端不校验取值。",
+            "enum": [
+              "pre_defined",
+              "message",
+              null
+            ]
           }
         }
       },
@@ -32945,7 +33980,7 @@
         },
         "additionalProperties": {
           "type": "array",
-          "description": "要为该 IM 应用隐藏的故障卡片字段名。",
+          "description": "要在该应用故障卡片上隐藏的字段：`channel`（协作空间名称）、`snoozed_before`（暂停截止时间）、`severity`（严重程度）、`responders`（处理人）、`aggregate_alert_count`（合并的告警数）、`detail`（详情按钮）、`ai_analysis`（AI 分析按钮）。",
           "items": {
             "type": "string",
             "enum": [
@@ -32960,31 +33995,6 @@
           }
         }
       },
-      "PreviewIncidentCardFixedField": {
-        "type": "object",
-        "description": "已应用隐藏规则后，为受支持 IM 预览返回的固定故障卡片字段。",
-        "required": [
-          "field",
-          "value"
-        ],
-        "properties": {
-          "field": {
-            "type": "string",
-            "enum": [
-              "channel",
-              "snoozed_before",
-              "severity",
-              "responders",
-              "aggregate_alert_count"
-            ],
-            "description": "故障卡片字段名。\n\n| 值 | 含义 |\n|---|---|\n| `channel` | 触发该故障的告警来源通道名称；仅当通道名非空时返回。 |\n| `snoozed_before` | 故障暂缓（Snooze）截止时间，格式为 `YYYY-MM-DD HH:MM:SS`；仅当故障处于暂缓状态时返回。 |\n| `severity` | 故障等级标签；仅当等级非空时返回。 |\n| `responders` | 当前处理人姓名列表，以空格分隔；仅当存在处理人时返回。 |\n| `aggregate_alert_count` | 聚合到该故障的告警数量；仅当数量大于 1 时返回。 |"
-          },
-          "value": {
-            "type": "string",
-            "description": "固定字段的渲染显示值。"
-          }
-        }
-      },
       "FieldDeleteReference": {
         "type": "object",
         "description": "仍引用该字段的自定义表单。",
@@ -32996,8 +34006,10 @@
         "properties": {
           "kind": {
             "type": "string",
-            "const": "custom_form",
-            "description": "被引用资源类型。在此响应中始终为 `custom_form`。"
+            "description": "被引用资源类型。在此响应中始终为 `custom_form`。",
+            "enum": [
+              "custom_form"
+            ]
           },
           "name": {
             "type": "string",
@@ -33100,7 +34112,7 @@
             "type": "integer",
             "format": "int64",
             "minimum": 0,
-            "description": "页码，从 1 开始。使用 `search_after_ctx` 时忽略。"
+            "description": "不支持；本接口只通过 `search_after_ctx` 翻页，该值会被忽略。"
           },
           "limit": {
             "type": "integer",
@@ -33289,7 +34301,10 @@
             },
             "description": "账户的全部评论类型，按展示位置排序。"
           }
-        }
+        },
+        "required": [
+          "items"
+        ]
       },
       "CreateIncidentCommentTypeRequest": {
         "type": "object",
@@ -33302,7 +34317,7 @@
           "name": {
             "type": "string",
             "maxLength": 40,
-            "description": "展示名称。存储前去除首尾空白；账户内唯一（不区分大小写）。最多 40 个字符。"
+            "description": "展示名称。存储前去除首尾空白；账户内唯一（不区分大小写）。最多 40 个字符。不得包含控制字符或文字方向控制字符。"
           },
           "color": {
             "type": "string",
@@ -33344,7 +34359,7 @@
           "name": {
             "type": "string",
             "maxLength": 40,
-            "description": "新的展示名称。存储前去除首尾空白；账户内唯一（不区分大小写）。最多 40 个字符。"
+            "description": "新的展示名称。存储前去除首尾空白；账户内唯一（不区分大小写）。最多 40 个字符。不得包含控制字符或文字方向控制字符。"
           },
           "color": {
             "type": "string",
@@ -33415,7 +34430,7 @@
               "action",
               "follow_up"
             ],
-            "description": "`action` 表示锚定在活动故障上的行动项；`follow_up` 表示复盘后续行动。"
+            "description": "事项类型。\n- `action`：未关闭故障上的待办。\n- `follow_up`：复盘后续行动，在已关闭故障上创建或由行动项转换而来。"
           },
           "incident_id": {
             "type": "string",
@@ -33424,7 +34439,7 @@
           },
           "post_mortem_id": {
             "type": "string",
-            "description": "故障复盘 ID（32 位十六进制字符串）。后续行动绑定复盘后返回。"
+            "description": "复盘 ID（32 位十六进制字符串）。仅绑定了复盘的后续行动返回；否则不返回。"
           },
           "title": {
             "type": "string",
@@ -33439,12 +34454,12 @@
           "status": {
             "type": "string",
             "maxLength": 64,
-            "description": "客户端自定义状态（最长 64 字符），没有固定状态机。"
+            "description": "事项状态：`open`（未开始）、`in_progress`（处理中）、`done`（已完成）或 `cancelled`（已取消）。`done` 和 `cancelled` 视为已结束。较早的事项可能仍保存其他自由文本，此类值视为未结束。"
           },
           "priority": {
             "type": "string",
             "maxLength": 64,
-            "description": "可选的客户端自定义优先级（最长 64 字符）。"
+            "description": "优先级（自由文本），最多 64 个字符；为空时不返回。控制台使用 `high`、`medium`、`low`，但通过 API 设置的任意字符串都会原样返回。"
           },
           "source_kind": {
             "type": "string",
@@ -33538,7 +34553,7 @@
               "type": "integer",
               "format": "int64"
             },
-            "description": "新添加（并已通知）的负责人成员 ID。"
+            "description": "本次新增（并已通知）的人员负责人成员 ID；不含 AI SRE。没有时不返回。"
           },
           "idempotent_replay": {
             "type": "boolean",
@@ -33548,7 +34563,7 @@
       },
       "WorkItemMutationResult": {
         "type": "object",
-        "description": "变更跟进事项的结果。",
+        "description": "跟进事项变更结果。删除操作不返回 `item`。",
         "properties": {
           "item": {
             "$ref": "#/components/schemas/WorkItemItem"
@@ -33559,7 +34574,7 @@
               "type": "integer",
               "format": "int64"
             },
-            "description": "新添加（并已通知）的负责人成员 ID。"
+            "description": "本次新增（并已通知）的人员负责人成员 ID；不含 AI SRE。没有时不返回。"
           },
           "removed_assignee_ids": {
             "type": "array",
@@ -33567,7 +34582,7 @@
               "type": "integer",
               "format": "int64"
             },
-            "description": "被移除（不通知）的负责人成员 ID。"
+            "description": "本次移除的人员负责人成员 ID（不会通知）。没有时不返回。"
           },
           "idempotent_replay": {
             "type": "boolean",
@@ -33628,7 +34643,7 @@
           "assignee_id": {
             "type": "integer",
             "format": "int64",
-            "description": "按负责人成员 ID 过滤结果。仅按负责人查询时，须为本人或账户管理员。`assignee_type` 为 `ai_sre` 时忽略本字段。"
+            "description": "只返回指派给该成员 ID 的事项。仅按负责人查询时，调用方须为该成员本人，或账户所有者、管理员。`assignee_type` 为 `ai_sre` 时忽略。"
           },
           "assignee_type": {
             "description": "按负责人类型过滤：`person` 或 `ai_sre`。`ai_sre` 返回指派给 AI SRE 的事项（AI 用它查询自己的任务），不需要 `assignee_id`。`person` 与 `assignee_id` 一起使用时，只返回该成员负责的事项。省略本字段且 `assignee_id` 为正数时，按 `person` 过滤。",
@@ -33640,15 +34655,13 @@
           },
           "cursor": {
             "type": "string",
-            "description": "分页游标，取自上一次响应的 `next_cursor`。"
+            "description": "上一次响应中的 `next_cursor`，内容不透明。游标无效时返回 `InvalidParameter`。"
           },
           "limit": {
             "type": "integer",
             "format": "int64",
-            "minimum": 0,
-            "maximum": 200,
             "default": 50,
-            "description": "每页条数，最多 200，默认 50。"
+            "description": "每页条数。0、负数或省略表示 50；大于 200 时按 200 处理。"
           }
         }
       },
@@ -33668,12 +34681,12 @@
               "action",
               "follow_up"
             ],
-            "description": "`action` 锚定活动故障，不得设置 `post_mortem_id`；`follow_up` 必须设置 `post_mortem_id`。"
+            "description": "事项类型。\n- `action`：未关闭故障上的待办，不得设置 `post_mortem_id`。\n- `follow_up`：已关闭故障上的复盘后续行动，`post_mortem_id` 可选。"
           },
           "title": {
             "type": "string",
             "maxLength": 512,
-            "description": "事项标题（最长 512 字符）。"
+            "description": "事项标题，最多 512 个字符；首尾空白会被去除，且不能为空。"
           },
           "description": {
             "type": "string",
@@ -33694,7 +34707,7 @@
           "priority": {
             "type": "string",
             "maxLength": 64,
-            "description": "可选的客户端自定义优先级（最长 64 字符）。"
+            "description": "可选的优先级，自由文本，最多 64 个字符。控制台使用 `high`、`medium`、`low`；其他字符串会原样保存。"
           },
           "incident_id": {
             "type": "string",
@@ -33703,7 +34716,7 @@
           },
           "post_mortem_id": {
             "type": "string",
-            "description": "故障复盘 ID（32 位十六进制字符串）。`follow_up` 必填，`action` 禁止填写。该复盘必须关联到 `incident_id`。"
+            "description": "复盘 ID（32 位十六进制字符串）。`action` 不得设置。`follow_up` 可选：设置时故障须已关联到该复盘；省略时若故障已有复盘则自动使用。"
           },
           "assignee_ids": {
             "type": "array",
@@ -33731,7 +34744,7 @@
       },
       "UpdateWorkItemRequest": {
         "type": "object",
-        "description": "跟进事项的部分更新。未提供的字段保持不变；显式传 `null` 则清空该字段。",
+        "description": "跟进事项的部分更新。未提供的字段以及传 `null` 的字段均保持不变。",
         "required": [
           "work_item_id",
           "version"
@@ -33745,14 +34758,14 @@
           "version": {
             "type": "integer",
             "format": "int64",
-            "description": "事项当前版本号，用于乐观锁。必须与存储的版本一致。"
+            "description": "事项当前的 `version`（≥ 1），用于乐观锁。"
           },
           "title": {
             "type": [
               "string",
               "null"
             ],
-            "description": "新标题（最长 512 字符）。",
+            "description": "新标题，最多 512 个字符；首尾空白会被去除且不能为空。传 `null` 或省略则保持不变。",
             "maxLength": 512
           },
           "description": {
@@ -33760,7 +34773,7 @@
               "string",
               "null"
             ],
-            "description": "新描述（最长 65,535 字符）。",
+            "description": "新描述，最多 65,535 个字符；传 `\"\"` 表示清空。传 `null` 或省略则保持不变。",
             "maxLength": 65535
           },
           "status": {
@@ -33772,17 +34785,17 @@
               "open",
               "in_progress",
               "done",
-              "cancelled"
+              "cancelled",
+              null
             ],
-            "description": "新的客户端自定义状态，取 `open`、`in_progress`、`done`、`cancelled` 之一。",
-            "maxLength": 64
+            "description": "新状态。传 `null` 或省略则保持不变。\n- `open`：未开始。\n- `in_progress`：处理中。\n- `done`：已完成。\n- `cancelled`：已取消。"
           },
           "priority": {
             "type": [
               "string",
               "null"
             ],
-            "description": "新的客户端自定义优先级（最长 64 字符）。",
+            "description": "新的优先级（自由文本），最多 64 个字符；传 `\"\"` 表示清空。传 `null` 或省略则保持不变。",
             "maxLength": 64
           }
         }
@@ -33803,7 +34816,7 @@
           "version": {
             "type": "integer",
             "format": "int64",
-            "description": "事项当前版本号，用于乐观锁。必须与存储的版本一致。"
+            "description": "事项当前的 `version`（≥ 1），用于乐观锁。"
           }
         }
       },
@@ -33860,7 +34873,7 @@
           "version": {
             "type": "integer",
             "format": "int64",
-            "description": "事项当前版本号，用于乐观锁。必须与存储的版本一致。"
+            "description": "事项当前的 `version`（≥ 1），用于乐观锁。"
           },
           "target_status": {
             "type": [
@@ -33871,10 +34884,11 @@
               "open",
               "in_progress",
               "done",
-              "cancelled"
+              "cancelled",
+              null
             ],
-            "description": "可选，设置在转化后后续行动上的状态，取 `open`、`in_progress`、`done`、`cancelled` 之一。",
-            "maxLength": 64
+            "maxLength": 64,
+            "description": "可选，转换后的后续行动要设置的状态；省略或传 `null` 保持当前状态。取值：`open`（未开始）、`in_progress`（处理中）、`done`（已完成）、`cancelled`（已取消）。"
           },
           "idempotency_key": {
             "type": "string",
@@ -33886,7 +34900,7 @@
       },
       "ResetWorkItemAssigneesRequest": {
         "type": "object",
-        "description": "整体替换跟进事项的负责人集合。",
+        "description": "整体替换跟进事项的负责人集合。`assignees` 与 `assignee_ids` 必须且只能传一个。",
         "required": [
           "work_item_id",
           "version"
@@ -33900,7 +34914,7 @@
           "version": {
             "type": "integer",
             "format": "int64",
-            "description": "事项当前版本号，用于乐观锁。必须与存储的版本一致。"
+            "description": "事项当前的 `version`（≥ 1），用于乐观锁。"
           },
           "assignee_ids": {
             "type": "array",
@@ -33936,7 +34950,7 @@
           "incident_id": {
             "type": "string",
             "pattern": "^[0-9a-fA-F]{24}$",
-            "description": "故障 ID（MongoDB ObjectID），其已转化但未绑定的后续行动将被绑定。"
+            "description": "故障 ID（MongoDB ObjectID），其已转换且未绑定的事项会被绑定。该故障须已关联到 `post_mortem_id`。"
           },
           "idempotency_key": {
             "type": "string",
@@ -33978,7 +34992,7 @@
         "properties": {
           "work_item_id": {
             "type": "string",
-            "description": "跟进事项 ID。"
+            "description": "工作项 ID（`wi_` 加随机字符串），可用于 `/incident/work-item/*` 系列接口。"
           },
           "item_type": {
             "type": "string",
@@ -33994,7 +35008,13 @@
           },
           "status": {
             "type": "string",
-            "description": "跟进事项状态标签（如 `open`、`done`）。"
+            "description": "创建时的工作项状态：`open` 未开始；`in_progress` 进行中；`done` 已完成；`cancelled` 已取消。",
+            "enum": [
+              "open",
+              "in_progress",
+              "done",
+              "cancelled"
+            ]
           },
           "assignee_ids": {
             "type": "array",
@@ -34024,7 +35044,7 @@
         "properties": {
           "work_item_id": {
             "type": "string",
-            "description": "跟进事项 ID。"
+            "description": "工作项 ID（`wi_` 加随机字符串），可用于 `/incident/work-item/*` 系列接口。"
           },
           "item_type": {
             "type": "string",
@@ -34044,19 +35064,25 @@
           },
           "from_status": {
             "type": "string",
-            "description": "更新前的状态标签。"
+            "description": "更新前的状态，仅在状态变化时出现。通常为 `open`、`in_progress`、`done`、`cancelled` 之一；这些状态引入前创建的工作项可能是其他文本。"
           },
           "to_status": {
             "type": "string",
-            "description": "更新后的状态标签。"
+            "description": "更新后的状态，仅在状态变化时出现。`open` 未开始；`in_progress` 进行中；`done` 已完成；`cancelled` 已取消。",
+            "enum": [
+              "open",
+              "in_progress",
+              "done",
+              "cancelled"
+            ]
           },
           "from_priority": {
             "type": "string",
-            "description": "更新前的优先级标签。"
+            "description": "更新前的优先级。由客户端自定义的优先级文本（最多 64 个字符），仅在优先级变化时出现。"
           },
           "to_priority": {
             "type": "string",
-            "description": "更新后的优先级标签。"
+            "description": "更新后的优先级。由客户端自定义的优先级文本（最多 64 个字符），仅在优先级变化时出现。"
           },
           "from_description": {
             "type": "string",
@@ -34075,7 +35101,7 @@
         "properties": {
           "work_item_id": {
             "type": "string",
-            "description": "跟进事项 ID。"
+            "description": "工作项 ID（`wi_` 加随机字符串），可用于 `/incident/work-item/*` 系列接口。"
           },
           "item_type": {
             "type": "string",
@@ -34143,7 +35169,7 @@
         "properties": {
           "work_item_id": {
             "type": "string",
-            "description": "跟进事项 ID。"
+            "description": "工作项 ID（`wi_` 加随机字符串），可用于 `/incident/work-item/*` 系列接口。"
           },
           "item_type": {
             "type": "string",
@@ -34159,11 +35185,14 @@
           },
           "from_status": {
             "type": "string",
-            "description": "完成前的状态标签。"
+            "description": "完成前的状态，通常为 `open` 或 `in_progress`；这些状态引入前创建的工作项可能是其他文本。"
           },
           "to_status": {
             "type": "string",
-            "description": "完成后的状态标签。"
+            "description": "完成后的状态，恒为 `done`。",
+            "enum": [
+              "done"
+            ]
           },
           "post_mortem_id": {
             "type": "string",
@@ -34178,7 +35207,7 @@
         "properties": {
           "work_item_id": {
             "type": "string",
-            "description": "跟进事项 ID。"
+            "description": "工作项 ID（`wi_` 加随机字符串），可用于 `/incident/work-item/*` 系列接口。"
           },
           "title": {
             "type": "string",
@@ -34206,7 +35235,7 @@
           },
           "status": {
             "type": "string",
-            "description": "转化后的事项状态标签。"
+            "description": "转换后的工作项状态，通常为 `open` 或 `in_progress`（转换不改变状态）。"
           }
         },
         "title": "i_wi_converted"
@@ -34217,7 +35246,7 @@
         "properties": {
           "work_item_id": {
             "type": "string",
-            "description": "跟进事项 ID。"
+            "description": "工作项 ID（`wi_` 加随机字符串），可用于 `/incident/work-item/*` 系列接口。"
           },
           "item_type": {
             "type": "string",
@@ -34244,7 +35273,7 @@
         "properties": {
           "work_item_id": {
             "type": "string",
-            "description": "跟进事项 ID。"
+            "description": "工作项 ID（`wi_` 加随机字符串），可用于 `/incident/work-item/*` 系列接口。"
           },
           "item_type": {
             "type": "string",
@@ -34317,12 +35346,12 @@
         "properties": {
           "is_enabled": {
             "type": "boolean",
-            "description": "为 true 时，重复事件并入已有告警；为 false 时，每个事件都单独生成告警。默认为 true。"
+            "description": "为 true 时，同一告警的重复事件并入已有告警；为 false 时每个事件单独生成告警。传入 `event_group` 时请显式设置此字段，不传即为 `false`。创建时完全不传 `event_group` 则默认开启合并。"
           },
           "time_window": {
             "type": "integer",
             "minimum": 1,
-            "description": "合并窗口，单位分钟，范围 1-1440（24 小时）；开通扩展额度的账号最大可设 10080（7 天）。默认 1440。"
+            "description": "合并窗口（分钟），`is_enabled` 为 true 时必填。默认取值范围 1–1440；开通了扩展合并窗口的账户最大可设 10080（7 天）。关闭合并时忽略。"
           }
         }
       },
@@ -34365,7 +35394,7 @@
               "incident",
               "maintenance"
             ],
-            "description": "模板适用的事件类型：`incident` 故障，`maintenance` 计划维护。"
+            "description": "模板适用的事件类型：`incident` 为非计划故障，`maintenance` 为计划维护。仅创建时设置，更新时忽略。"
           },
           "status": {
             "type": "string",
@@ -34542,10 +35571,26 @@
         "description": "成员的值班状态：正在值班的班次、下一次值班，以及其参与的全部启用排班。",
         "properties": {
           "current": {
-            "$ref": "#/components/schemas/MemberOncallInterval"
+            "oneOf": [
+              {
+                "$ref": "#/components/schemas/MemberOncallInterval"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "正在进行的班次；成员当前不在班时为 `null`。"
           },
           "next": {
-            "$ref": "#/components/schemas/MemberOncallInterval"
+            "oneOf": [
+              {
+                "$ref": "#/components/schemas/MemberOncallInterval"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "下一次值班（不含 `end_at`）；45 天内没有时为 `null`。"
           },
           "schedules": {
             "type": "array",
@@ -34565,12 +35610,12 @@
         "properties": {
           "schedule_id": {
             "type": "integer",
-            "description": "排班 ID。",
+            "description": "成员参与的值班表 ID，可传给 `/schedule/info`。",
             "format": "int64"
           },
           "schedule_name": {
             "type": "string",
-            "description": "排班名称。"
+            "description": "该值班表的名称。"
           }
         }
       },
@@ -34594,7 +35639,7 @@
           },
           "end_at": {
             "type": "integer",
-            "description": "Unix 时间戳（秒）—— 班次结束时间。值班进行中时缺省。",
+            "description": "班次结束时间（Unix 秒）。`current` 中返回；`next` 中省略。",
             "format": "int64"
           }
         }
@@ -34629,7 +35674,7 @@
           },
           "category": {
             "type": "string",
-            "description": "按分类过滤，支持逗号分隔多个值，例如 `event.alert,event.change`。"
+            "description": "按大类过滤，多个值用逗号分隔。取值：`event.alert`（告警事件）、`event.change`（变更事件）、`im`（IM 机器人）、`webhook`（自定义 Webhook）。未知值不会报错，但匹配不到结果。"
           },
           "asc": {
             "type": [
@@ -34655,7 +35700,7 @@
         "properties": {
           "plugin_type": {
             "type": "string",
-            "description": "创建集成时作为 `plugin_type` 传入的类型标识。",
+            "description": "创建集成时作为 `plugin_type` 传入的类型标识，如 `standard.alert`、`prometheus.alert`、`zabbix.alert`、`feishu`。类型会随新集成增加，完整列表以本接口返回为准。",
             "example": "standard.alert"
           },
           "plugin_type_name": {
@@ -34679,7 +35724,11 @@
           },
           "status": {
             "type": "string",
-            "description": "该类型在平台侧的状态。"
+            "description": "该类型的平台状态：`enabled` 可正常使用；`disabled` 表示平台已停用该类型，`POST /integration/create` 与 `POST /integration/update` 会返回 `InvalidParameter`。",
+            "enum": [
+              "enabled",
+              "disabled"
+            ]
           },
           "supports_api_create": {
             "type": "boolean",
@@ -34749,23 +35798,23 @@
           },
           "category": {
             "type": "string",
-            "description": "按分类过滤，支持逗号分隔多个值。"
+            "description": "按大类过滤，多个值用逗号分隔。取值：`event.alert`（告警事件）、`event.change`（变更事件）、`im`（IM 机器人）、`webhook`（自定义 Webhook）。未知值不会报错，但匹配不到结果。"
           },
           "type": {
             "type": "string",
-            "description": "已废弃；与 `plugin_type` 同时传入时会合并生效。"
+            "description": "已弃用，等同于 `plugin_type`（逗号分隔的类型标识，如 `prometheus.alert`、`zabbix.alert`）。同时传入 `plugin_type` 时忽略本字段。"
           },
           "plugin_type": {
             "type": "string",
-            "description": "按集成类型过滤，支持逗号分隔多个值。"
+            "description": "按集成类型过滤，多个值用逗号分隔，如 `standard.alert,prometheus.alert`；取值为 `POST /integration/type/list` 返回的 `plugin_type`。"
           },
           "status": {
             "type": "string",
-            "description": "按状态过滤，支持逗号分隔多个值。"
+            "description": "按状态过滤，多个值用逗号分隔：`enabled`（接收事件）、`disabled`（已暂停）。"
           },
           "name": {
             "type": "string",
-            "description": "按集成名称过滤。"
+            "description": "按集成名称过滤，名称包含该文本即匹配。"
           },
           "ref_ids": {
             "type": "array",
@@ -34823,7 +35872,7 @@
           "integration_id": {
             "type": "integer",
             "format": "int64",
-            "description": "集成 ID。"
+            "description": "集成 ID，可作为 `integration_id` 传给其他 `/integration/*` 接口。"
           },
           "team_id": {
             "type": "integer",
@@ -34975,7 +36024,7 @@
             "type": "integer",
             "format": "int64",
             "minimum": 1,
-            "description": "集成 ID。",
+            "description": "公共集成 ID，可从 `POST /integration/list` 获取。ID 不存在或属于协作空间专属集成时返回 `ResourceNotFound`。",
             "example": 6113996590131
           }
         }
@@ -35008,7 +36057,7 @@
           "integration_id": {
             "type": "integer",
             "format": "int64",
-            "description": "集成 ID。"
+            "description": "集成 ID，可作为 `integration_id` 传给其他 `/integration/*` 接口。"
           },
           "team_id": {
             "type": "integer",
@@ -35220,7 +36269,7 @@
             "type": "integer",
             "format": "int64",
             "minimum": 1,
-            "description": "集成 ID。",
+            "description": "公共集成 ID，可从 `POST /integration/list` 获取。ID 不存在或属于协作空间专属集成时返回 `ResourceNotFound`。",
             "example": 6113996590131
           },
           "name": {
@@ -35271,7 +36320,7 @@
             "type": "integer",
             "format": "int64",
             "minimum": 1,
-            "description": "集成 ID。",
+            "description": "公共集成 ID，可从 `POST /integration/list` 获取。ID 不存在或属于协作空间专属集成时返回 `ResourceNotFound`。",
             "example": 6113996590131
           }
         }
diff --git a/api-reference/openapi.en.json b/api-reference/openapi.en.json
index f01cc75bc..72a55d5c3 100644
--- a/api-reference/openapi.en.json
+++ b/api-reference/openapi.en.json
@@ -23,25 +23,25 @@
         "description": "Invalid request — usually a missing or malformed parameter."
       },
       "Forbidden": {
+        "description": "The app_key is valid, but its permission scope or the creator's role does not allow this operation or object.",
         "content": {
           "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/ErrorResponse"
+            },
             "examples": {
               "noEditPermission": {
                 "value": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "error": {
                     "code": "AccessDenied",
                     "message": "Access Denied."
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
+                  }
                 }
               }
-            },
-            "schema": {
-              "$ref": "#/components/schemas/ErrorResponse"
             }
           }
-        },
-        "description": "The app_key is valid but lacks permission for this operation."
+        }
       },
       "NotFound": {
         "content": {
@@ -107,25 +107,34 @@
         "description": "The service is temporarily unavailable. Include the request_id when reporting."
       },
       "TooManyRequests": {
+        "description": "Rate limit hit (per-account limit or the operation's platform-wide limit). Wait for the number of seconds in `Flashcat-Request-Rate-Limit-Delay`, then retry.",
         "content": {
           "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/ErrorResponse"
+            },
             "examples": {
               "rateLimited": {
                 "value": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "error": {
                     "code": "RequestTooFrequently",
                     "message": "Request too frequently."
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
+                  }
                 }
               }
-            },
-            "schema": {
-              "$ref": "#/components/schemas/ErrorResponse"
             }
           }
         },
-        "description": "Rate limit hit. Either the global API limit, a per-account limit, or a per-integration limit."
+        "headers": {
+          "Flashcat-Request-Rate-Limit-Delay": {
+            "description": "Seconds until the current rate-limit window resets. Absent when the request was rejected by the gateway's global protection limit.",
+            "schema": {
+              "type": "integer",
+              "minimum": 0
+            }
+          }
+        }
       },
       "Unauthorized": {
         "content": {
@@ -151,81 +160,87 @@
     },
     "schemas": {
       "A2AAgentCreateRequest": {
+        "type": "object",
         "description": "Registration parameters for a new A2A agent.",
         "properties": {
           "agent_name": {
-            "description": "Agent display name.",
-            "maxLength": 128,
-            "type": "string"
-          },
-          "allow_insecure_oauth_http": {
-            "description": "Allow non-loopback HTTP OAuth discovery/metadata endpoints for this agent instead of requiring HTTPS. Defaults to false.",
-            "type": "boolean"
-          },
-          "allow_insecure_tls_skip_verify": {
-            "description": "Skip TLS certificate verification when connecting to this agent's endpoint (self-signed/private certs). Defaults to false.",
-            "type": "boolean"
+            "type": "string",
+            "description": "Agent display name, used to address the agent in sessions. Must not contain `@`, must not be `general` or `explore`, and must be unique within its scope (account-wide or one team).",
+            "maxLength": 128
           },
-          "auth_config": {
-            "additionalProperties": {
-              "type": "string"
-            },
-            "description": "Authentication config key-values, e.g. the API key or bearer token. Values under credential-looking keys (name containing KEY, SECRET, TOKEN, PASSWORD, etc.) are masked back in responses.",
-            "type": "object"
+          "instructions": {
+            "type": "string",
+            "description": "Natural-language instructions for the remote agent: a Markdown document with optional `summary` frontmatter and a non-empty body, at most 50 KiB (51200 bytes). Required — a deprecated `description` field is still accepted for legacy clients and, if both are sent, must exactly match `instructions`.",
+            "maxLength": 51200
           },
-          "auth_mode": {
-            "description": "Authentication mode: `shared` (default) shares one credential across all users; `per_user_secret` requires `secret_schema.header_name`; `per_user_oauth` runs per-user OAuth.",
-            "type": "string"
+          "card_url": {
+            "type": "string",
+            "description": "URL of the remote agent card. Must be an absolute `http` or `https` URL with a non-empty host; a URL with no path is resolved to `/.well-known/agent-card.json`. If an execution environment is online, the card is fetched and must declare an A2A 1.x `JSONRPC` or `HTTP+JSON` interface."
           },
           "auth_type": {
-            "description": "Authentication type for reaching the remote agent: `none` (default when omitted), `api_key`, or `bearer`.",
+            "type": "string",
+            "description": "Authentication used to reach the remote agent with a shared credential:\n- `none`: no credential header.\n- `api_key`: sends `auth_config.api_key` in the header named by `auth_config.header`.\n- `bearer`: sends `Authorization: Bearer <auth_config.token>`.\n\nWhen omitted the value is stored as an empty string, which behaves like `none`.",
             "enum": [
               "none",
               "api_key",
               "bearer"
-            ],
-            "type": "string"
+            ]
           },
-          "card_url": {
-            "description": "URL of the remote agent card. Must be an absolute `http` or `https` URL with a non-empty host; reachability is enforced by the execution environment, not at creation time.",
-            "type": "string"
+          "auth_config": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "string"
+            },
+            "description": "Shared credential key-values: `header` and `api_key` for `auth_type=api_key`, `token` for `auth_type=bearer`. Values of `api_key`, `token`, and `client_secret` are encrypted at rest and masked in responses."
+          },
+          "streaming": {
+            "type": "boolean",
+            "description": "Whether the remote agent supports streaming."
+          },
+          "team_id": {
+            "type": "integer",
+            "description": "Team scope: 0 = account-wide; >0 = team. Creating at account scope requires the owner/admin role; creating into a team requires actual membership in that team.",
+            "format": "int64"
           },
           "environments": {
-            "description": "Execution environments this agent is callable from: `cloud` and/or BYOC runner environment IDs. Omitted or empty means all environments.",
+            "type": "array",
             "items": {
               "type": "string"
             },
-            "type": "array"
-          },
-          "instructions": {
-            "description": "Natural-language instructions for the remote agent: a Markdown document with optional `summary` frontmatter and a non-empty body, at most 50 KiB (51200 bytes). Required — a deprecated `description` field is still accepted for legacy clients and, if both are sent, must exactly match `instructions`.",
-            "maxLength": 51200,
-            "type": "string"
+            "description": "Execution environments this agent is callable from: `cloud` and/or BYOC runner environment IDs. Omitted or empty means all environments."
           },
-          "oauth_metadata": {
-            "description": "JSON-encoded OAuth metadata; populated by the OAuth discovery flow for `per_user_oauth` mode.",
-            "type": "string"
+          "auth_mode": {
+            "type": "string",
+            "description": "Who supplies the credential:\n- `shared` (default; an empty value behaves the same): one credential stored on the agent (`auth_type` + `auth_config`) is used for every caller.\n- `per_user_secret`: each user stores their own secret, sent in the header named by `secret_schema.header_name`.\n- `per_user_oauth`: each user completes their own OAuth authorization; discovery and client registration run on first use.\n\n`per_user_secret` requires `secret_schema` with a non-empty `header_name`; any other value returns `InvalidParameter`.",
+            "enum": [
+              "shared",
+              "per_user_secret",
+              "per_user_oauth"
+            ],
+            "default": "shared"
           },
           "secret_schema": {
-            "description": "JSON-encoded secret schema, e.g. `{\"header_name\":\"X-Api-Key\"}`; required when `auth_mode=per_user_secret`.",
-            "type": "string"
+            "type": "string",
+            "description": "JSON-encoded secret schema, e.g. `{\"header_name\":\"X-Api-Key\"}`; required when `auth_mode=per_user_secret`."
           },
-          "streaming": {
-            "description": "Whether the remote agent supports streaming.",
-            "type": "boolean"
+          "oauth_metadata": {
+            "type": "string",
+            "description": "JSON-encoded OAuth metadata; populated by the OAuth discovery flow for `per_user_oauth` mode."
           },
-          "team_id": {
-            "description": "Team scope: 0 = account-wide; >0 = team. Creating at account scope requires the owner/admin role; creating into a team requires actual membership in that team.",
-            "format": "int64",
-            "type": "integer"
+          "allow_insecure_oauth_http": {
+            "type": "boolean",
+            "description": "Allow non-loopback HTTP OAuth discovery/metadata endpoints for this agent instead of requiring HTTPS. Defaults to false."
+          },
+          "allow_insecure_tls_skip_verify": {
+            "type": "boolean",
+            "description": "Skip TLS certificate verification when connecting to this agent's endpoint (self-signed/private certs). Defaults to false."
           }
         },
         "required": [
           "agent_name",
           "instructions",
           "card_url"
-        ],
-        "type": "object"
+        ]
       },
       "A2AAgentCreateResponse": {
         "description": "Result of registering an A2A agent.",
@@ -254,133 +269,134 @@
         "type": "object"
       },
       "A2AAgentItem": {
+        "type": "object",
         "description": "A registered A2A (agent-to-agent) remote agent.",
         "properties": {
+          "agent_id": {
+            "type": "string",
+            "description": "Unique A2A agent ID (prefix `a2a_`)."
+          },
           "account_id": {
+            "type": "integer",
             "description": "Owning account ID.",
-            "format": "int64",
-            "type": "integer"
+            "format": "int64"
           },
-          "agent_card_name": {
-            "description": "Agent name resolved from the remote card. Omitted until the card has been fetched.",
-            "type": "string"
+          "team_id": {
+            "type": "integer",
+            "description": "Team scope: 0 = account-wide; >0 = the owning team.",
+            "format": "int64"
           },
-          "agent_card_skills": {
-            "description": "Skills advertised by the remote card. Omitted until the card has been fetched.",
+          "can_edit": {
+            "type": "boolean",
+            "description": "Whether the caller may update, enable, disable, or delete this agent: `true` for an account-scoped agent only for the account owner or an admin, for a team agent only for members of that team."
+          },
+          "environments": {
+            "type": "array",
             "items": {
               "type": "string"
             },
-            "type": "array"
-          },
-          "agent_id": {
-            "description": "Unique A2A agent ID (prefix `a2a_`).",
-            "type": "string"
+            "description": "Execution environments this agent is callable from (`cloud` and/or BYOC runner environment IDs). Always present; `[]` means all environments (also the value on legacy rows created before this field)."
           },
           "agent_name": {
-            "description": "Agent display name.",
-            "type": "string"
-          },
-          "allow_insecure_oauth_http": {
-            "description": "Allow non-loopback HTTP OAuth discovery/metadata endpoints for this agent instead of requiring HTTPS.",
-            "type": "boolean"
-          },
-          "allow_insecure_tls_skip_verify": {
-            "description": "Skip TLS certificate verification when connecting to this agent's endpoint.",
-            "type": "boolean"
+            "type": "string",
+            "description": "Agent display name."
           },
-          "auth_config": {
-            "additionalProperties": {
-              "type": "string"
-            },
-            "description": "Authentication config key-values. Values under credential-looking keys (name containing KEY, SECRET, TOKEN, PASSWORD, etc.) are masked. Omitted when empty.",
-            "type": "object"
+          "instructions": {
+            "type": "string",
+            "description": "Natural-language instructions for the remote agent (formerly named `description`).",
+            "maxLength": 51200
           },
-          "auth_mode": {
-            "description": "Authentication mode. One of: `shared` (a single static credential saved on the resource and shared by all callers in the account; the default — an empty value behaves the same), `per_user_secret` (each user stores their own secret per `secret_schema`, injected per user at runtime), `per_user_oauth` (each user completes their own OAuth grant; discovery and registration run lazily on first use).",
-            "enum": [
-              "shared",
-              "per_user_secret",
-              "per_user_oauth"
-            ],
-            "type": "string"
+          "card_url": {
+            "type": "string",
+            "description": "URL of the remote agent card."
           },
           "auth_type": {
-            "description": "Authentication type for reaching the remote agent: `none`, `api_key`, or `bearer`. Rows created before validation was tightened may return an empty string, equivalent to `none`.",
+            "type": "string",
+            "description": "Authentication used to reach the remote agent with a shared credential:\n- `none`: no credential header.\n- `api_key`: sends `auth_config.api_key` in the header named by `auth_config.header`.\n- `bearer`: sends `Authorization: Bearer <auth_config.token>`.\n\nAn empty string means `auth_type` was omitted at creation and behaves like `none`.",
             "enum": [
               "",
               "none",
               "api_key",
               "bearer"
-            ],
-            "type": "string"
-          },
-          "can_edit": {
-            "description": "Whether the caller may edit this agent.",
-            "type": "boolean"
+            ]
           },
-          "card_resolve_timeout": {
-            "description": "Card-resolution timeout in seconds. Always 0 today — the API does not yet expose a way to set it.",
-            "type": "integer"
+          "auth_config": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "string"
+            },
+            "description": "Shared credential key-values (`header`, `api_key`, `token`, …). Values of `api_key`, `token`, `client_secret`, and any other value stored encrypted are masked: longer than 8 characters shows the first and last 4 characters around `****`, otherwise `****`. Omitted when empty."
           },
-          "card_url": {
-            "description": "URL of the remote agent card.",
-            "type": "string"
+          "streaming": {
+            "type": "boolean",
+            "description": "Whether the remote agent supports streaming responses."
           },
-          "created_at": {
-            "description": "Creation time. Unix timestamp in milliseconds.",
-            "format": "int64",
-            "type": "integer"
+          "status": {
+            "type": "string",
+            "description": "Whether the agent is offered to AI SRE sessions:\n- `enabled`: available for dispatch (the state after create).\n- `disabled`: kept but not offered; re-enable with `POST /safari/a2a-agent/enable`.",
+            "enum": [
+              "enabled",
+              "disabled"
+            ]
           },
-          "created_by": {
-            "description": "Member ID that created the agent.",
-            "format": "int64",
-            "type": "integer"
+          "agent_card_name": {
+            "type": "string",
+            "description": "Agent name read from the remote card on older records. The server no longer fills this in, so it is omitted for new agents."
           },
-          "environments": {
-            "description": "Execution environments this agent is callable from (`cloud` and/or BYOC runner environment IDs). Always present; `[]` means all environments (also the value on legacy rows created before this field).",
+          "agent_card_skills": {
+            "type": "array",
             "items": {
               "type": "string"
             },
-            "type": "array"
+            "description": "Skill names read from the remote card on older records. The server no longer fills this in, so it is omitted for new agents."
           },
-          "instructions": {
-            "description": "Natural-language instructions for the remote agent (formerly named `description`).",
-            "maxLength": 51200,
-            "type": "string"
+          "card_resolve_timeout": {
+            "type": "integer",
+            "description": "Card-resolution timeout in seconds. Always 0 today — the API does not yet expose a way to set it."
           },
-          "oauth_metadata": {
-            "description": "JSON-encoded OAuth metadata (per_user_oauth mode).",
-            "type": "string"
+          "task_timeout": {
+            "type": "integer",
+            "description": "Single-task execution timeout in seconds. Always 0 today — the API does not yet expose a way to set it."
+          },
+          "auth_mode": {
+            "type": "string",
+            "description": "Who supplies the credential; omitted when empty, which behaves like `shared`:\n- `shared`: one credential stored on the agent (`auth_type` + `auth_config`) is used for every caller.\n- `per_user_secret`: each user stores their own secret, sent in the header named by `secret_schema.header_name`.\n- `per_user_oauth`: each user completes their own OAuth authorization; discovery and client registration run on first use.",
+            "enum": [
+              "shared",
+              "per_user_secret",
+              "per_user_oauth"
+            ]
           },
           "secret_schema": {
-            "description": "JSON-encoded secret schema (per_user_secret mode).",
-            "type": "string"
+            "type": "string",
+            "description": "JSON-encoded secret schema (per_user_secret mode)."
           },
-          "status": {
-            "description": "Agent status.",
-            "enum": [
-              "enabled",
-              "disabled"
-            ],
-            "type": "string"
+          "oauth_metadata": {
+            "type": "string",
+            "description": "JSON-encoded OAuth metadata (per_user_oauth mode)."
           },
-          "streaming": {
-            "description": "Whether the remote agent supports streaming responses.",
-            "type": "boolean"
+          "allow_insecure_oauth_http": {
+            "type": "boolean",
+            "description": "Allow non-loopback HTTP OAuth discovery/metadata endpoints for this agent instead of requiring HTTPS."
           },
-          "task_timeout": {
-            "description": "Single-task execution timeout in seconds. Always 0 today — the API does not yet expose a way to set it.",
-            "type": "integer"
+          "allow_insecure_tls_skip_verify": {
+            "type": "boolean",
+            "description": "Skip TLS certificate verification when connecting to this agent's endpoint."
           },
-          "team_id": {
-            "description": "Team scope: 0 = account-wide; >0 = the owning team.",
+          "created_by": {
+            "type": "integer",
+            "description": "Member ID that created the agent.",
+            "format": "int64"
+          },
+          "created_at": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Creation time. Unix timestamp in milliseconds."
           },
           "updated_at": {
-            "description": "Last update time. Unix timestamp in milliseconds.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Last update time. Unix timestamp in milliseconds."
           }
         },
         "required": [
@@ -400,54 +416,53 @@
           "created_at",
           "updated_at",
           "environments"
-        ],
-        "type": "object"
+        ]
       },
       "A2AAgentListRequest": {
+        "type": "object",
         "description": "Pagination, scope, and search filter for listing A2A agents.",
         "properties": {
-          "include_account": {
-            "description": "Include account-scoped (team_id=0) rows. Defaults to true.",
-            "type": [
-              "boolean",
-              "null"
-            ]
-          },
-          "limit": {
-            "default": 20,
-            "description": "Page size.",
-            "type": "integer"
-          },
           "offset": {
-            "default": 0,
+            "type": "integer",
             "description": "Pagination offset — number of rows to skip, starting from 0.",
-            "type": "integer"
+            "default": 0
           },
-          "query": {
-            "description": "Case-insensitive substring search across agent name, instructions, card URL, agent ID, and the resolved card name.",
-            "maxLength": 128,
-            "type": "string"
+          "limit": {
+            "type": "integer",
+            "description": "Page size; 0 or less falls back to 20. No upper bound is enforced.",
+            "default": 20
           },
           "scope": {
-            "default": "all",
-            "description": "Visibility scope: `all` (account-scope plus the caller's visible teams), `account` (account-scope only), or `team` (team-scoped rows across the caller's visible teams).",
+            "type": "string",
             "enum": [
               "all",
               "account",
               "team"
             ],
-            "type": "string"
+            "default": "all",
+            "description": "Visibility scope: `all` (account-scope plus the caller's visible teams), `account` (account-scope only), or `team` (team-scoped rows across the caller's visible teams)."
+          },
+          "query": {
+            "type": "string",
+            "description": "Case-insensitive substring search across agent name, instructions, card URL, agent ID, and the resolved card name.",
+            "maxLength": 128
           },
           "team_ids": {
-            "description": "Filter to these team IDs; empty = the caller's visible set.",
+            "type": "array",
             "items": {
-              "format": "int64",
-              "type": "integer"
+              "type": "integer",
+              "format": "int64"
             },
-            "type": "array"
+            "description": "Restrict to these team IDs. IDs of teams the caller does not belong to are ignored; empty means all of the caller's teams."
+          },
+          "include_account": {
+            "type": [
+              "boolean",
+              "null"
+            ],
+            "description": "Include account-scoped (`team_id=0`) rows. Defaults to `true`; ignored when `scope` is `account` (always included) or `team` (never included)."
           }
-        },
-        "type": "object"
+        }
       },
       "A2AAgentListResponse": {
         "description": "Paginated A2A agent list.",
@@ -472,202 +487,217 @@
         "type": "object"
       },
       "A2AAgentUpdateRequest": {
+        "type": "object",
         "description": "Partial update of an A2A agent. A null/omitted field is left unchanged.",
         "properties": {
           "agent_id": {
-            "description": "Target agent ID, from the list returned by `POST /safari/a2a-agent/list`.",
-            "type": "string"
+            "type": "string",
+            "description": "Target agent ID, from the list returned by `POST /safari/a2a-agent/list`."
           },
           "agent_name": {
-            "description": "New display name. Omit to leave unchanged.",
-            "maxLength": 128,
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "New display name; omit to leave unchanged. Same rules as create: no `@`, not `general` / `explore`, unique within the scope.",
+            "maxLength": 128
           },
-          "allow_insecure_oauth_http": {
-            "description": "Toggle non-loopback HTTP OAuth discovery for this agent. Omit to leave unchanged.",
+          "instructions": {
             "type": [
-              "boolean",
+              "string",
               "null"
-            ]
+            ],
+            "description": "New instructions document (same contract as create: optional `summary` frontmatter, non-empty body, at most 50 KiB). Omit to leave unchanged. A deprecated `description` field is also accepted; if both are sent they must match.",
+            "maxLength": 51200
           },
-          "allow_insecure_tls_skip_verify": {
-            "description": "Toggle TLS certificate verification skipping for this agent. Omit to leave unchanged.",
+          "card_url": {
             "type": [
-              "boolean",
+              "string",
               "null"
-            ]
-          },
-          "auth_config": {
-            "additionalProperties": {
-              "type": "string"
-            },
-            "description": "Replace the whole auth config; omit to leave unchanged. Keys missing from the map are dropped. For a sensitive key, sending back the masked value keeps the stored secret, while sending an empty string clears it.",
-            "type": "object"
+            ],
+            "description": "New card URL; omit to leave unchanged. Validated and compatibility-checked the same way as on create; a real change also clears `oauth_metadata` unless a new one is sent."
           },
-          "auth_mode": {
-            "description": "New auth mode: shared, per_user_secret, or per_user_oauth. Changing it always rewrites secret_schema together with it.",
+          "auth_type": {
             "type": [
               "string",
               "null"
-            ]
-          },
-          "auth_type": {
-            "description": "New auth type: `none`, `api_key`, or `bearer`. Omit to leave unchanged.",
+            ],
+            "description": "New auth type; omit to leave unchanged.\n- `none`: no credential header.\n- `api_key`: sends `auth_config.api_key` in the header named by `auth_config.header`.\n- `bearer`: sends `Authorization: Bearer <auth_config.token>`.",
             "enum": [
               "none",
               "api_key",
               "bearer"
-            ],
+            ]
+          },
+          "auth_config": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "string"
+            },
+            "description": "Replace the whole auth config; omit to leave unchanged. Keys missing from the map are dropped. For a sensitive key, sending back the masked value keeps the stored secret, while sending an empty string clears it."
+          },
+          "streaming": {
             "type": [
-              "string",
+              "boolean",
               "null"
-            ]
+            ],
+            "description": "Toggle streaming support. Omit to leave unchanged."
           },
-          "card_url": {
-            "description": "New card URL. Omit to leave unchanged.",
+          "team_id": {
             "type": [
-              "string",
+              "integer",
               "null"
-            ]
+            ],
+            "description": "Reassign team scope; omit to leave unchanged. Moving to a team requires membership in it; moving to account scope (`0`) requires the account owner or an admin. If the team changes without `environments` in the same request, the current runner entries must stay selectable by the caller or the update is rejected.",
+            "format": "int64"
           },
           "environments": {
-            "description": "Execution environments this agent is callable from: `cloud` and/or BYOC runner environment IDs. Omit (null) to leave unchanged; send a list to set it — an empty list clears the restriction back to all environments.",
-            "items": {
-              "type": "string"
-            },
             "type": [
               "array",
               "null"
-            ]
+            ],
+            "items": {
+              "type": "string"
+            },
+            "description": "Execution environments this agent is callable from: `cloud` and/or BYOC runner environment IDs. Omit (null) to leave unchanged; send a list to set it — an empty list clears the restriction back to all environments."
           },
-          "instructions": {
-            "description": "New instructions document (same contract as create: optional `summary` frontmatter, non-empty body, at most 50 KiB). Omit to leave unchanged. A deprecated `description` field is also accepted; if both are sent they must match.",
-            "maxLength": 51200,
+          "auth_mode": {
             "type": [
               "string",
               "null"
+            ],
+            "description": "New auth mode; omit to leave unchanged. Values (who supplies the credential):\n- `shared` (default; an empty value behaves the same): one credential stored on the agent (`auth_type` + `auth_config`) is used for every caller.\n- `per_user_secret`: each user stores their own secret, sent in the header named by `secret_schema.header_name`.\n- `per_user_oauth`: each user completes their own OAuth authorization; discovery and client registration run on first use.\n\nWhen sent, `secret_schema` is overwritten with the value in the same request.",
+            "enum": [
+              "shared",
+              "per_user_secret",
+              "per_user_oauth"
             ]
           },
-          "oauth_metadata": {
-            "description": "New JSON OAuth metadata. If omitted while auth_mode changes, it is cleared to empty.",
+          "secret_schema": {
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "New JSON secret schema, e.g. `{\"header_name\":\"X-Api-Key\"}`. Applied only together with `auth_mode`; sent alone it is ignored."
           },
-          "secret_schema": {
-            "description": "New JSON secret schema.",
+          "oauth_metadata": {
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "New JSON OAuth metadata. A non-empty value is stored as sent. When omitted or empty, the stored value is kept unless `auth_mode` or `card_url` changes, in which case it is cleared."
           },
-          "streaming": {
-            "description": "Toggle streaming support. Omit to leave unchanged.",
+          "allow_insecure_oauth_http": {
             "type": [
               "boolean",
               "null"
-            ]
+            ],
+            "description": "Toggle non-loopback HTTP OAuth discovery for this agent. Omit to leave unchanged."
           },
-          "team_id": {
-            "description": "Reassign team scope. Omit to leave unchanged. Reassigning requires rights on the destination team; if the team changes without also sending a new environment binding, the existing runner binding must remain selectable by the caller or the update is rejected.",
-            "format": "int64",
+          "allow_insecure_tls_skip_verify": {
             "type": [
-              "integer",
+              "boolean",
               "null"
-            ]
+            ],
+            "description": "Toggle TLS certificate verification skipping for this agent. Omit to leave unchanged."
           }
         },
         "required": [
           "agent_id"
-        ],
-        "type": "object"
+        ]
       },
       "AccountInfo": {
+        "type": "object",
         "properties": {
           "account_id": {
+            "type": "integer",
             "description": "Account identifier.",
-            "format": "uint64",
-            "type": "integer"
+            "format": "uint64"
           },
           "account_name": {
-            "description": "Account name.",
-            "type": "string"
-          },
-          "avatar": {
-            "description": "Account avatar URL.",
-            "type": "string"
-          },
-          "country_code": {
-            "description": "ISO 3166-1 alpha-2 region code of the contact phone (e.g. \"CN\", \"US\", \"HK\").",
-            "type": "string"
-          },
-          "created_at": {
-            "description": "Account creation time, Unix timestamp in seconds.",
-            "format": "int64",
-            "type": "integer"
+            "type": "string",
+            "description": "Account (organization) name shown in the console."
           },
           "domain": {
-            "description": "Primary account domain (login subdomain).",
-            "type": "string"
-          },
-          "email": {
-            "description": "Account contact email.",
-            "type": "string"
+            "type": "string",
+            "description": "Primary account domain (login subdomain)."
           },
           "extra_domains": {
-            "description": "Additional account domains.",
+            "type": "array",
             "items": {
               "type": "string"
             },
-            "type": "array"
+            "description": "Additional account domains."
           },
-          "locale": {
-            "description": "Account language preference (e.g. zh-CN, en-US).",
-            "type": "string"
+          "phone": {
+            "type": "string",
+            "description": "Account contact phone, masked for privacy."
           },
-          "mp_account_id": {
-            "description": "Account identifier on the marketplace platform. Omitted together with `mp_plat`.",
-            "type": "string"
+          "country_code": {
+            "type": "string",
+            "description": "ISO 3166-1 alpha-2 region code of the contact phone (e.g. \"CN\", \"US\", \"HK\")."
           },
-          "mp_plat": {
-            "description": "Cloud marketplace platform the account was provisioned from. Omitted when the account did not come from a marketplace.",
-            "type": "string"
+          "email": {
+            "type": "string",
+            "description": "Account contact email."
           },
-          "phone": {
-            "description": "Account contact phone, masked for privacy.",
-            "type": "string"
+          "avatar": {
+            "type": "string",
+            "description": "Account avatar URL."
+          },
+          "locale": {
+            "type": "string",
+            "description": "Account language preference (`zh-CN` or `en-US`); empty string when not set."
+          },
+          "time_zone": {
+            "type": "string",
+            "description": "Account default time zone (IANA name, e.g. `Asia/Shanghai`); members without their own setting follow it. Empty string when not set."
+          },
+          "created_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Account creation time, Unix timestamp in seconds."
           },
           "restrictions": {
+            "type": "object",
             "description": "Account access restrictions. Omitted when none are configured.",
             "properties": {
-              "allow_subdomain": {
-                "description": "Whether subdomains of the allowed email domains are also accepted.",
-                "type": "boolean"
-              },
-              "email_domains": {
-                "description": "Allowed login email domains.",
+              "ips": {
+                "type": [
+                  "array",
+                  "null"
+                ],
                 "items": {
                   "type": "string"
                 },
-                "type": "array"
+                "description": "Source IP addresses or CIDR ranges allowed to call the console and API for this account; `null` or empty when unrestricted."
               },
-              "ips": {
-                "description": "Allowed source IP/CIDR whitelist.",
+              "email_domains": {
+                "type": [
+                  "array",
+                  "null"
+                ],
                 "items": {
                   "type": "string"
                 },
-                "type": "array"
+                "description": "Email domains allowed for new members; invitations to other domains are rejected. `null` or empty when unrestricted."
+              },
+              "allow_subdomain": {
+                "type": "boolean",
+                "description": "Whether subdomains of the allowed email domains are also accepted."
               }
-            },
-            "type": "object"
+            }
           },
-          "time_zone": {
-            "description": "Account default timezone (IANA name, e.g. Asia/Shanghai).",
-            "type": "string"
+          "mp_plat": {
+            "type": "string",
+            "description": "Cloud marketplace the account was provisioned from: `aws` — AWS Marketplace. Omitted when the account did not come from a marketplace.",
+            "enum": [
+              "aws"
+            ]
+          },
+          "mp_account_id": {
+            "type": "string",
+            "description": "Account identifier on the marketplace platform. Omitted together with `mp_plat`."
           }
         },
         "required": [
@@ -682,8 +712,7 @@
           "locale",
           "time_zone",
           "created_at"
-        ],
-        "type": "object"
+        ]
       },
       "AckIncidentRequest": {
         "description": "Parameters for acknowledging one or more incidents.",
@@ -720,79 +749,80 @@
         "type": "object"
       },
       "AddIncidentResponderRequest": {
+        "type": "object",
         "description": "Parameters for adding responders to an existing incident.",
+        "required": [
+          "incident_id",
+          "person_ids"
+        ],
         "properties": {
           "incident_id": {
-            "description": "Incident ID (MongoDB ObjectID).",
+            "type": "string",
             "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
+            "description": "Incident ID (MongoDB ObjectID)."
+          },
+          "person_ids": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "int64"
+            },
+            "description": "Member IDs to add as responders. IDs that are already responders, or that do not exist in the account, are skipped."
           },
           "notify": {
-            "description": "Optional notification override. Defaults to following each person's personal preference.",
+            "type": "object",
+            "description": "Notification settings for the newly added responders. Defaults to `{\"follow_preference\": true}`.",
             "properties": {
               "follow_preference": {
-                "description": "When false, use `personal_channels`; when true or omitted, use each responder's personal preference.",
                 "type": [
                   "boolean",
                   "null"
-                ]
+                ],
+                "description": "`true`: notify each person through their personal notification preference. `false`: use `personal_channels`, which must then be non-empty. When omitted, `personal_channels` must be set."
               },
               "personal_channels": {
-                "description": "Channels to use (e.g. `voice`, `sms`, `email`).",
+                "type": "array",
                 "items": {
                   "type": "string"
                 },
-                "type": "array"
+                "description": "Channels used when `follow_preference` is `false`: `sms`, `voice`, `email`, `push` (mobile app push), or an IM app channel written as `feishu_app:<integration_id>`, `dingtalk_app:<integration_id>`, `wecom_app:<integration_id>`, `slack_app:<integration_id>`, or `teams_app:<integration_id>`. Ignored when `follow_preference` is `true`."
               },
               "template_id": {
-                "description": "Notification template ID (MongoDB ObjectID).",
+                "type": "string",
                 "pattern": "^[0-9a-fA-F]{24}$",
-                "type": "string"
+                "description": "Notification template ID, as returned by the notification template endpoints. Must exist in the account; otherwise the call fails with `InvalidParameter`."
               }
-            },
-            "type": "object"
-          },
-          "person_ids": {
-            "description": "Member IDs to add as responders.",
-            "items": {
-              "format": "int64",
-              "type": "integer"
-            },
-            "type": "array"
+            }
           }
-        },
-        "required": [
-          "incident_id",
-          "person_ids"
-        ],
-        "type": "object"
+        }
       },
       "AddWarRoomMemberRequest": {
+        "type": "object",
         "properties": {
-          "chat_id": {
-            "description": "Chat ID of the war room within the IM platform.",
-            "type": "string"
-          },
           "integration_id": {
+            "type": "integer",
             "description": "ID of the IM integration hosting the war room; obtain it from `POST /datasource/im/war-room-enabled/list`.",
-            "format": "int64",
-            "type": "integer"
+            "format": "int64"
+          },
+          "chat_id": {
+            "type": "string",
+            "description": "Chat ID of the war-room group on the IM platform, as returned for the war room by `POST /incident/war-room/list`."
           },
           "member_ids": {
-            "description": "Person IDs to add to the war room.",
+            "type": "array",
+            "minItems": 1,
             "items": {
-              "format": "int64",
-              "type": "integer"
+              "type": "integer",
+              "format": "int64"
             },
-            "type": "array"
+            "description": "Person IDs (member IDs, or the account ID for the owner) to add. Must not be empty."
           }
         },
         "required": [
           "integration_id",
           "chat_id",
           "member_ids"
-        ],
-        "type": "object"
+        ]
       },
       "AffectedStatusPageComponentItem": {
         "description": "A status page component currently affected by an event, embedding component metadata plus its resulting status.",
@@ -850,90 +880,90 @@
         "type": "object"
       },
       "AlertEventGlobalListRequest": {
+        "type": "object",
         "description": "Filter and pagination criteria for the global raw event list. Time range is required.",
+        "required": [
+          "start_time",
+          "end_time"
+        ],
         "properties": {
-          "asc": {
-            "description": "Sort ascending when `true`.",
-            "type": "boolean"
-          },
-          "channel_ids": {
-            "description": "Filter by channel IDs. At most 100 entries.",
-            "items": {
-              "format": "int64",
-              "type": "integer"
-            },
-            "maxItems": 100,
-            "type": "array"
+          "start_time": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Start of the search window, Unix epoch seconds. Must be greater than 0.",
+            "exclusiveMinimum": 0
           },
           "end_time": {
-            "description": "End of the search window, Unix epoch seconds. Must be greater than `start_time`; the span must not exceed 31 days.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
-          },
-          "integration_ids": {
-            "description": "Filter by integration IDs.",
-            "items": {
-              "format": "int64",
-              "type": "integer"
-            },
-            "type": "array"
+            "description": "End of the search window, Unix epoch seconds. Must be greater than `start_time`; the span must not exceed 31 days."
           },
-          "integration_types": {
-            "description": "Filter by integration types (plugin keys).",
-            "items": {
-              "type": "string"
-            },
-            "type": "array"
-          },
-          "limit": {
-            "description": "Page size, max 100, default 20.",
-            "format": "int64",
-            "maximum": 100,
-            "minimum": 0,
+          "p": {
             "type": [
               "integer",
               "null"
-            ]
-          },
-          "orderby": {
-            "description": "Sort field; only `event_time` is supported.",
-            "enum": [
-              "event_time"
             ],
-            "type": "string"
-          },
-          "p": {
-            "description": "Page number, starting at 1. Used when `search_after_ctx` is not provided.",
             "format": "int64",
-            "minimum": 0,
+            "description": "Page number, starting at 1. Used when `search_after_ctx` is not provided.",
+            "minimum": 0
+          },
+          "limit": {
             "type": [
               "integer",
               "null"
-            ]
+            ],
+            "format": "int64",
+            "description": "Page size, max 100, default 20.",
+            "minimum": 0,
+            "maximum": 100
           },
           "search_after_ctx": {
-            "description": "Pagination cursor: leave empty for the first page, then pass the `search_after_ctx` returned by the previous response.",
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "Pagination cursor: leave empty for the first page, then pass the `search_after_ctx` returned by the previous response."
+          },
+          "integration_ids": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "int64"
+            },
+            "description": "Filter by integration IDs."
+          },
+          "integration_types": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Filter by integration types (plugin keys)."
+          },
+          "channel_ids": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "int64"
+            },
+            "description": "Filter by channel IDs. At most 100 entries.",
+            "maxItems": 100
           },
           "severities": {
-            "description": "Comma-separated severity filter, e.g. `Critical,Warning`. Accepted values: `Critical`, `Warning`, `Info`, `Ok`.",
-            "type": "string"
+            "type": "string",
+            "description": "Comma-separated filter on `event_severity`, e.g. `Critical,Warning`. Meaningful values: `Critical`, `Warning`, `Info`. Values are not validated; an unknown value (or `Ok`) matches nothing."
           },
-          "start_time": {
-            "description": "Start of the search window, Unix epoch seconds. Must be greater than 0.",
-            "exclusiveMinimum": 0,
-            "format": "int64",
-            "type": "integer"
+          "orderby": {
+            "type": "string",
+            "description": "Sort field; only `event_time` is supported.",
+            "enum": [
+              "event_time"
+            ]
+          },
+          "asc": {
+            "type": "boolean",
+            "description": "Sort ascending when `true`."
           }
-        },
-        "required": [
-          "start_time",
-          "end_time"
-        ],
-        "type": "object"
+        }
       },
       "AlertEventGlobalListResponse": {
         "properties": {
@@ -961,113 +991,113 @@
         "type": "object"
       },
       "AlertEventItem": {
+        "type": "object",
         "description": "A raw alert event.",
         "properties": {
-          "account_id": {
-            "description": "Account ID.",
-            "format": "int64",
-            "type": "integer"
+          "event_id": {
+            "type": "string",
+            "pattern": "^[0-9a-fA-F]{24}$",
+            "description": "Event ID (MongoDB ObjectID)."
           },
           "alert_id": {
-            "description": "Parent alert ID (MongoDB ObjectID).",
+            "type": "string",
             "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
+            "description": "Parent alert ID (MongoDB ObjectID)."
           },
-          "alert_key": {
-            "description": "Deduplication key used to merge events into an alert.",
-            "type": "string"
+          "account_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "ID of the account that owns this record; the same for every record returned to one `app_key`."
           },
           "channel_id": {
-            "description": "Channel ID the event is routed to.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Channel ID the event is routed to."
           },
-          "created_at": {
-            "description": "Record creation time, Unix epoch seconds.",
+          "integration_id": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Integration that produced this event."
+          },
+          "integration_type": {
+            "type": "string",
+            "description": "Plugin type of the integration, such as `prometheus.alert`, `grafana.alert`, `zabbix.alert`, `monit.alert`, or `email.alert`. The set is open and grows with new integrations; `POST /integration/type/list` returns the full list."
           },
           "data_source_id": {
-            "description": "Deprecated. Use `integration_id` instead.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Deprecated. Use `integration_id` instead."
           },
-          "deleted_at": {
-            "description": "Soft-delete time, Unix epoch seconds. Omitted when the event is not deleted.",
-            "format": "int64",
-            "type": "integer"
+          "title": {
+            "type": "string",
+            "description": "Event title."
+          },
+          "title_rule": {
+            "type": "string",
+            "description": "Title template used to derive `title` from labels."
           },
           "description": {
-            "description": "Event description.",
-            "type": "string"
+            "type": "string",
+            "description": "Event description."
           },
-          "event_id": {
-            "description": "Event ID (MongoDB ObjectID).",
-            "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
+          "alert_key": {
+            "type": "string",
+            "description": "Deduplication key used to merge events into an alert."
           },
           "event_severity": {
-            "description": "Severity of this event: `Critical`, `Warning`, or `Info`. An event never carries `Ok` as severity — `Ok` appears only as `event_status`.",
+            "type": "string",
             "enum": [
               "Critical",
               "Warning",
               "Info"
             ],
-            "type": "string"
+            "description": "Severity of this event: `Critical`, `Warning`, or `Info`. An event never carries `Ok` as severity — `Ok` appears only as `event_status`."
           },
           "event_status": {
-            "description": "Status carried by this event: `Critical`/`Warning`/`Info` for a firing event, `Ok` for a recovery event.",
+            "type": "string",
             "enum": [
               "Critical",
               "Warning",
               "Info",
               "Ok"
             ],
-            "type": "string"
+            "description": "Status carried by this event: `Critical`/`Warning`/`Info` for a firing event, `Ok` for a recovery event."
           },
           "event_time": {
-            "description": "Event timestamp, Unix epoch seconds.",
-            "format": "int64",
-            "type": "integer"
-          },
-          "images": {
-            "description": "Images attached to the event.",
-            "items": {
-              "$ref": "#/components/schemas/AlertImage"
-            },
-            "type": "array"
-          },
-          "integration_id": {
-            "description": "Integration that produced this event.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
-          },
-          "integration_type": {
-            "description": "Type/plugin key of the integration that produced this event.",
-            "type": "string"
+            "description": "Event timestamp, Unix epoch seconds."
           },
           "labels": {
+            "type": "object",
             "additionalProperties": {
               "type": "string"
             },
-            "description": "Label key-value pairs.",
-            "type": "object"
+            "description": "Label key-value pairs."
           },
-          "title": {
-            "description": "Event title.",
-            "type": "string"
+          "images": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/AlertImage"
+            },
+            "description": "Images attached to the event."
           },
-          "title_rule": {
-            "description": "Title template used to derive `title` from labels.",
-            "type": "string"
+          "created_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Record creation time, Unix epoch seconds."
           },
           "updated_at": {
-            "description": "Record update time, Unix epoch seconds.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Record update time, Unix epoch seconds."
+          },
+          "deleted_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Soft-delete time, Unix epoch seconds. Omitted when the event is not deleted."
           }
-        },
-        "type": "object"
+        }
       },
       "AlertEventListRequest": {
         "properties": {
@@ -1217,231 +1247,243 @@
         "type": "string"
       },
       "AlertImage": {
+        "type": "object",
         "description": "An image attachment on an alert or event.",
+        "required": [
+          "src"
+        ],
         "properties": {
-          "alt": {
-            "description": "Alt text.",
-            "type": "string"
-          },
           "href": {
-            "description": "Optional link URL when the image is clicked.",
-            "type": "string"
+            "type": "string",
+            "description": "Optional link URL when the image is clicked."
           },
           "src": {
-            "description": "Image source URL or internal image reference (starts with `img_` or `http`).",
-            "type": "string"
+            "type": "string",
+            "description": "Image source URL or internal image reference (starts with `img_` or `http`)."
+          },
+          "alt": {
+            "type": "string",
+            "description": "Alternative text shown when the image cannot be displayed; empty when not set."
           }
-        },
-        "required": [
-          "src"
-        ],
-        "type": "object"
+        }
       },
       "AlertInfo": {
+        "type": "object",
         "description": "Detailed alert item.",
+        "required": [
+          "alert_id",
+          "integration_id",
+          "data_source_id",
+          "channel_id",
+          "account_id",
+          "description",
+          "title",
+          "title_rule",
+          "alert_key",
+          "alert_severity",
+          "alert_status",
+          "start_time",
+          "last_time",
+          "end_time",
+          "labels",
+          "ever_muted",
+          "created_at",
+          "updated_at",
+          "integration_name",
+          "integration_type",
+          "integration_ref_id",
+          "channel_name",
+          "channel_status",
+          "responder_name",
+          "responder_email",
+          "event_cnt",
+          "images",
+          "data_source_name",
+          "data_source_ref_id"
+        ],
         "properties": {
+          "alert_id": {
+            "type": "string",
+            "pattern": "^[0-9a-fA-F]{24}$",
+            "description": "Alert ID (MongoDB ObjectID)."
+          },
+          "integration_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Integration ID that produced the alert."
+          },
+          "data_source_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Deprecated. Use `integration_id` instead."
+          },
+          "channel_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "ID of the channel the alert was routed to; its name is in `channel_name`."
+          },
           "account_id": {
-            "description": "Account ID.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "ID of the account that owns this record; the same for every record returned to one `app_key`."
           },
-          "alert_id": {
-            "description": "Alert ID (MongoDB ObjectID).",
-            "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
+          "description": {
+            "type": "string",
+            "description": "Alert description."
+          },
+          "title": {
+            "type": "string",
+            "description": "Alert title."
+          },
+          "title_rule": {
+            "type": "string",
+            "description": "Title rendering rule."
           },
           "alert_key": {
-            "description": "Deduplication key used to merge events into the alert.",
-            "type": "string"
+            "type": "string",
+            "description": "Deduplication key used to merge events into the alert."
           },
           "alert_severity": {
-            "description": "Current severity.",
+            "type": "string",
             "enum": [
               "Critical",
               "Warning",
               "Info",
               "Ok"
             ],
-            "type": "string"
+            "description": "Current severity."
           },
           "alert_status": {
-            "description": "Current status.",
+            "type": "string",
             "enum": [
               "Critical",
               "Warning",
               "Info",
               "Ok"
             ],
-            "type": "string"
+            "description": "Current status."
           },
-          "channel_id": {
-            "description": "Channel ID.",
+          "start_time": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
-          },
-          "channel_name": {
-            "description": "Channel display name.",
-            "type": "string"
-          },
-          "channel_status": {
-            "description": "Channel status.",
-            "type": "string"
+            "description": "Unix timestamp (seconds) when the alert first fired."
           },
-          "created_at": {
-            "description": "Creation timestamp (seconds).",
+          "last_time": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Unix timestamp (seconds) of the most recent event."
           },
-          "data_source_id": {
-            "description": "Deprecated. Use `integration_id` instead.",
+          "end_time": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
-          },
-          "data_source_name": {
-            "description": "Deprecated. Use `integration_name`.",
-            "type": "string"
+            "description": "Unix timestamp (seconds) when the alert recovered. 0 if still active."
           },
-          "data_source_ref_id": {
-            "description": "Deprecated. Use `integration_ref_id`.",
-            "type": "string"
+          "labels": {
+            "type": [
+              "object",
+              "null"
+            ],
+            "additionalProperties": {
+              "type": "string"
+            },
+            "description": "Alert labels."
           },
-          "data_source_type": {
-            "description": "Deprecated. Use `integration_type`.",
-            "type": "string"
+          "ever_muted": {
+            "type": "boolean",
+            "description": "Whether this alert has ever been silenced."
           },
           "deleted_at": {
-            "description": "Soft-delete timestamp (seconds). Zero if not deleted.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Soft-delete timestamp (seconds). Zero if not deleted."
           },
-          "description": {
-            "description": "Alert description.",
-            "type": "string"
-          },
-          "detail_url": {
-            "description": "Console URL of this alert (`{console}/alert/detail/{alert_id}`). Empty when the deployment has no console base configured.",
-            "type": "string"
-          },
-          "end_time": {
-            "description": "Unix timestamp (seconds) when the alert recovered. 0 if still active.",
+          "created_at": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Creation timestamp (seconds)."
           },
-          "event_cnt": {
-            "description": "Total number of raw events merged into this alert.",
+          "updated_at": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Last update timestamp (seconds)."
           },
-          "events": {
-            "description": "Raw alert event preview, populated only when requested. Capped at the 20 newest events per alert.",
-            "items": {
-              "$ref": "#/components/schemas/AlertEventItem"
-            },
-            "type": "array"
+          "integration_name": {
+            "type": "string",
+            "description": "Integration display name."
           },
-          "ever_muted": {
-            "description": "Whether this alert has ever been silenced.",
-            "type": "boolean"
+          "integration_type": {
+            "type": "string",
+            "description": "Plugin type of the integration, such as `prometheus.alert`, `grafana.alert`, `zabbix.alert`, `monit.alert`, or `email.alert`. The set is open and grows with new integrations; `POST /integration/type/list` returns the full list."
           },
-          "images": {
-            "description": "Attached images.",
-            "items": {
-              "$ref": "#/components/schemas/Image"
-            },
-            "type": "array"
+          "integration_ref_id": {
+            "type": "string",
+            "description": "Integration reference ID."
           },
-          "incident": {
-            "$ref": "#/components/schemas/IncidentShort",
-            "description": "Parent incident reference, if the alert has been merged into one."
+          "channel_name": {
+            "type": "string",
+            "description": "Channel display name."
           },
-          "integration_id": {
-            "description": "Integration ID that produced the alert.",
-            "format": "int64",
-            "type": "integer"
+          "channel_status": {
+            "type": "string",
+            "description": "Status of the channel: `enabled`, `disabled`, or `deleted`. Empty string when the record has no channel or the channel no longer exists.",
+            "enum": [
+              "enabled",
+              "disabled",
+              "deleted",
+              ""
+            ]
           },
-          "integration_name": {
-            "description": "Integration display name.",
-            "type": "string"
+          "responder_name": {
+            "type": "string",
+            "description": "Always an empty string in API responses; filled only when the alert is rendered for notifications."
           },
-          "integration_ref_id": {
-            "description": "Integration reference ID.",
-            "type": "string"
+          "responder_email": {
+            "type": "string",
+            "description": "Always an empty string in API responses; filled only when the alert is rendered for notifications."
           },
-          "integration_type": {
-            "description": "Integration type string.",
-            "type": "string"
+          "incident": {
+            "$ref": "#/components/schemas/IncidentShort",
+            "description": "Parent incident reference, if the alert has been merged into one."
           },
-          "labels": {
-            "additionalProperties": {
-              "type": "string"
+          "events": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/AlertEventItem"
             },
-            "description": "Alert labels.",
-            "type": "object"
+            "description": "Raw alert event preview, populated only when requested. Capped at the 20 newest events per alert."
           },
-          "last_time": {
-            "description": "Unix timestamp (seconds) of the most recent event.",
+          "event_cnt": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Total number of raw events merged into this alert."
           },
-          "responder_email": {
-            "description": "Primary responder email, if any.",
-            "type": "string"
+          "images": {
+            "type": [
+              "array",
+              "null"
+            ],
+            "items": {
+              "$ref": "#/components/schemas/Image"
+            },
+            "description": "Images attached to the alert; `null` when there are none."
           },
-          "responder_name": {
-            "description": "Primary responder name, if any.",
+          "detail_url": {
+            "description": "Console URL of this alert (`{console}/alert/detail/{alert_id}`). Empty when the deployment has no console base configured.",
             "type": "string"
           },
-          "start_time": {
-            "description": "Unix timestamp (seconds) when the alert first fired.",
-            "format": "int64",
-            "type": "integer"
-          },
-          "title": {
-            "description": "Alert title.",
-            "type": "string"
+          "data_source_name": {
+            "type": "string",
+            "description": "Deprecated. Use `integration_name`."
           },
-          "title_rule": {
-            "description": "Title rendering rule.",
-            "type": "string"
+          "data_source_type": {
+            "type": "string",
+            "description": "Deprecated; same value as `integration_type`."
           },
-          "updated_at": {
-            "description": "Last update timestamp (seconds).",
-            "format": "int64",
-            "type": "integer"
+          "data_source_ref_id": {
+            "type": "string",
+            "description": "Deprecated. Use `integration_ref_id`."
           }
-        },
-        "required": [
-          "alert_id",
-          "integration_id",
-          "data_source_id",
-          "channel_id",
-          "account_id",
-          "description",
-          "title",
-          "title_rule",
-          "alert_key",
-          "alert_severity",
-          "alert_status",
-          "start_time",
-          "last_time",
-          "end_time",
-          "labels",
-          "ever_muted",
-          "created_at",
-          "updated_at",
-          "integration_name",
-          "integration_type",
-          "integration_ref_id",
-          "channel_name",
-          "channel_status",
-          "responder_name",
-          "responder_email",
-          "event_cnt",
-          "images",
-          "data_source_name",
-          "data_source_ref_id"
-        ],
-        "type": "object"
+        }
       },
       "AlertInfoRequest": {
         "properties": {
@@ -1457,382 +1499,377 @@
         "type": "object"
       },
       "AlertItem": {
+        "type": "object",
         "description": "A single alert with full detail.",
         "properties": {
+          "alert_id": {
+            "type": "string",
+            "description": "Unique alert ID (ObjectID hex string)."
+          },
+          "integration_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "ID of the integration that produced this alert."
+          },
+          "data_source_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Deprecated: use `integration_id` instead.",
+            "deprecated": true
+          },
+          "channel_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "ID of the channel the alert belongs to."
+          },
           "account_id": {
-            "description": "Account ID.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "ID of the account that owns the alert."
           },
-          "alert_id": {
-            "description": "Unique alert ID (ObjectID hex string).",
-            "type": "string"
+          "title": {
+            "type": "string",
+            "description": "Alert title."
           },
-          "alert_key": {
-            "description": "Deduplication key.",
-            "type": "string"
+          "title_rule": {
+            "type": "string",
+            "description": "Title template used to derive `title` from the event labels (e.g. `$service::$cluster`)."
+          },
+          "description": {
+            "type": "string",
+            "description": "Alert description."
           },
           "alert_severity": {
-            "description": "Current severity — the highest severity ever seen on this alert: `Critical`, `Warning`, or `Info`.",
+            "type": "string",
             "enum": [
               "Critical",
               "Warning",
               "Info"
             ],
-            "type": "string"
+            "description": "Current severity — the highest severity ever seen on this alert: `Critical`, `Warning`, or `Info`."
           },
           "alert_status": {
-            "description": "Current status: `Critical`/`Warning`/`Info` while firing, `Ok` once recovered.",
+            "type": "string",
             "enum": [
               "Critical",
               "Warning",
               "Info",
               "Ok"
             ],
-            "type": "string"
-          },
-          "channel_id": {
-            "description": "ID of the channel the alert belongs to.",
-            "format": "int64",
-            "type": "integer"
+            "description": "Current status: `Critical`/`Warning`/`Info` while firing, `Ok` once recovered."
           },
-          "channel_name": {
-            "description": "Display name of the channel.",
-            "type": "string"
-          },
-          "channel_status": {
-            "description": "Status of the channel: `enabled` or `disabled`.",
-            "enum": [
-              "enabled",
-              "disabled"
-            ],
-            "type": "string"
+          "alert_key": {
+            "type": "string",
+            "description": "Deduplication key."
           },
-          "created_at": {
-            "description": "Creation timestamp, Unix epoch seconds.",
+          "start_time": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "First-seen time, Unix epoch seconds."
           },
-          "data_source_id": {
-            "deprecated": true,
-            "description": "Deprecated: use `integration_id` instead.",
+          "last_time": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Last-event time, Unix epoch seconds."
           },
-          "data_source_name": {
-            "deprecated": true,
-            "description": "Deprecated: use `integration_name` instead.",
-            "type": "string"
+          "end_time": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Resolution time, Unix epoch seconds. 0 if still active."
           },
-          "data_source_ref_id": {
-            "deprecated": true,
-            "description": "Deprecated: use `integration_ref_id` instead.",
-            "type": "string"
+          "labels": {
+            "type": [
+              "object",
+              "null"
+            ],
+            "additionalProperties": {
+              "type": "string"
+            },
+            "description": "Label key-value pairs; `null` when the alert has no labels."
           },
-          "data_source_type": {
-            "deprecated": true,
-            "description": "Deprecated: use `integration_type` instead. Omitted when empty.",
-            "type": "string"
+          "ever_muted": {
+            "type": "boolean",
+            "description": "True if this alert has ever been silenced."
           },
-          "deleted_at": {
-            "description": "Soft-delete time, Unix epoch seconds. Omitted when the alert is not deleted.",
+          "created_at": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Creation timestamp, Unix epoch seconds."
           },
-          "description": {
-            "description": "Alert description.",
-            "type": "string"
+          "updated_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Last update timestamp, Unix epoch seconds."
           },
-          "detail_url": {
-            "description": "Console URL of this alert (`{console}/alert/detail/{alert_id}`). Empty when the deployment has no console base configured.",
-            "type": "string"
+          "integration_name": {
+            "type": "string",
+            "description": "Display name of the integration."
           },
-          "end_time": {
-            "description": "Resolution time, Unix epoch seconds. 0 if still active.",
-            "format": "int64",
-            "type": "integer"
+          "integration_type": {
+            "type": "string",
+            "description": "Type key of the integration that produced the alert, e.g. `prometheus.alert` or `zabbix.alert`; same values as `plugin_type` from `POST /integration/type/list`."
+          },
+          "integration_ref_id": {
+            "type": "string",
+            "description": "Owner reference of the integration: `a_<account_id>` for an account-level integration, `c_<channel_id>` for a channel-owned one."
+          },
+          "channel_name": {
+            "type": "string",
+            "description": "Display name of the channel."
+          },
+          "channel_status": {
+            "type": "string",
+            "description": "Status of the channel: `enabled` or `disabled`.",
+            "enum": [
+              "enabled",
+              "disabled"
+            ]
+          },
+          "responder_name": {
+            "type": "string",
+            "description": "Responder display name. Always empty in this response — responder tracking lives on the associated incident."
+          },
+          "responder_email": {
+            "type": "string",
+            "description": "Responder email. Always empty in this response — responder tracking lives on the associated incident."
           },
           "event_cnt": {
-            "description": "Total number of raw events received by this alert.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Total number of raw events received by this alert."
+          },
+          "incident": {
+            "$ref": "#/components/schemas/IncidentShort",
+            "description": "Associated incident, if any."
           },
           "events": {
-            "description": "Raw events of this alert. Omitted here; populated only by `POST /incident/alert/list`.",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/AlertEventItem"
             },
-            "type": "array"
-          },
-          "ever_muted": {
-            "description": "True if this alert has ever been silenced.",
-            "type": "boolean"
+            "description": "Raw events of this alert. Omitted here; populated only by `POST /incident/alert/list`."
           },
           "images": {
-            "description": "Images attached to the alert.",
+            "type": [
+              "array",
+              "null"
+            ],
             "items": {
               "$ref": "#/components/schemas/AlertImage"
             },
-            "type": "array"
-          },
-          "incident": {
-            "$ref": "#/components/schemas/IncidentShort",
-            "description": "Associated incident, if any."
-          },
-          "integration_id": {
-            "description": "ID of the integration that produced this alert.",
-            "format": "int64",
-            "type": "integer"
-          },
-          "integration_name": {
-            "description": "Display name of the integration.",
-            "type": "string"
-          },
-          "integration_ref_id": {
-            "description": "External reference ID of the integration.",
-            "type": "string"
-          },
-          "integration_type": {
-            "description": "Type/plugin key of the integration.",
-            "type": "string"
-          },
-          "labels": {
-            "additionalProperties": {
-              "type": "string"
-            },
-            "description": "Label key-value pairs.",
-            "type": "object"
-          },
-          "last_time": {
-            "description": "Last-event time, Unix epoch seconds.",
-            "format": "int64",
-            "type": "integer"
-          },
-          "responder_email": {
-            "description": "Responder email. Always empty in this response — responder tracking lives on the associated incident.",
-            "type": "string"
+            "description": "Images attached to the alert; `null` when there are none."
           },
-          "responder_name": {
-            "description": "Responder display name. Always empty in this response — responder tracking lives on the associated incident.",
+          "detail_url": {
+            "description": "Console URL of this alert (`{console}/alert/detail/{alert_id}`). Empty when the deployment has no console base configured.",
             "type": "string"
           },
-          "start_time": {
-            "description": "First-seen time, Unix epoch seconds.",
-            "format": "int64",
-            "type": "integer"
+          "data_source_name": {
+            "type": "string",
+            "description": "Deprecated: use `integration_name` instead.",
+            "deprecated": true
           },
-          "title": {
-            "description": "Alert title.",
-            "type": "string"
+          "data_source_type": {
+            "type": "string",
+            "description": "Deprecated: use `integration_type` instead (same value, e.g. `prometheus.alert`). Omitted when empty.",
+            "deprecated": true
           },
-          "title_rule": {
-            "description": "Title template used to derive `title` from the event labels (e.g. `$service::$cluster`).",
-            "type": "string"
+          "data_source_ref_id": {
+            "type": "string",
+            "description": "Deprecated: use `integration_ref_id` instead.",
+            "deprecated": true
           },
-          "updated_at": {
-            "description": "Last update timestamp, Unix epoch seconds.",
+          "deleted_at": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Soft-delete time, Unix epoch seconds. Omitted when the alert is not deleted."
           }
-        },
-        "type": "object"
+        }
       },
       "AlertListByIDsRequest": {
+        "type": "object",
+        "required": [
+          "alert_ids"
+        ],
         "properties": {
           "alert_ids": {
-            "description": "Alert IDs (ObjectID hex strings) to fetch.",
+            "type": "array",
             "items": {
               "type": "string"
             },
-            "minItems": 1,
-            "type": "array"
+            "description": "Alert IDs (ObjectID hex strings) to fetch. A malformed ID fails the request; IDs not found in the account are left out of the result."
           }
-        },
-        "required": [
-          "alert_ids"
-        ],
-        "type": "object"
+        }
       },
       "AlertListRequest": {
+        "type": "object",
         "description": "Filter and pagination criteria for alert list queries. Time range is required.",
+        "required": [
+          "start_time",
+          "end_time"
+        ],
         "properties": {
-          "alert_ids": {
-            "description": "Filter to specific alert IDs (ObjectID hex strings). Invalid IDs are ignored; if none are valid, the result is empty.",
-            "items": {
-              "type": "string"
-            },
-            "type": "array"
-          },
-          "alert_keys": {
-            "description": "Filter by alert deduplication keys.",
-            "items": {
-              "type": "string"
-            },
-            "type": "array"
-          },
-          "alert_severity": {
-            "description": "Comma-separated severity filter, e.g. `Critical,Warning`. Allowed values: `Critical`, `Warning`, `Info`, `Ok`.",
-            "type": "string"
-          },
-          "asc": {
-            "description": "Sort ascending by `start_time` when `true`; default is descending.",
-            "type": "boolean"
-          },
-          "by_updated_at": {
-            "description": "When `true`, the time range filter is applied on `updated_at` rather than `start_time`.",
-            "type": "boolean"
-          },
-          "channel_ids": {
-            "description": "Filter by channel IDs.",
-            "items": {
-              "format": "int64",
-              "type": "integer"
-            },
-            "type": "array"
+          "start_time": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Start of the search window, Unix epoch seconds, applied to the alert's `start_time`. A value earlier than the account's data retention period is moved up to the retention start."
           },
           "end_time": {
-            "description": "End of the search window, Unix epoch seconds. Must be greater than `start_time`; the span must not exceed 31 days and must lie within the account's data retention period.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "End of the search window, Unix epoch seconds. Must be greater than `start_time`; the span must not exceed 31 days (7 days with `by_updated_at`). A value before the start of the data retention period returns `InvalidParameter`."
           },
-          "ever_muted": {
-            "description": "Filter by whether the alert has ever been silenced.",
+          "p": {
             "type": [
-              "boolean",
+              "integer",
               "null"
-            ]
-          },
-          "integration_ids": {
-            "description": "Filter by integration IDs.",
-            "items": {
-              "format": "int64",
-              "type": "integer"
-            },
-            "type": "array"
+            ],
+            "format": "int64",
+            "description": "Page number, starting at 1. Used when `search_after_ctx` is not provided; `p * limit` must stay within 10,000 records.",
+            "minimum": 0
           },
-          "is_active": {
-            "description": "Filter by lifecycle: `true` returns only firing alerts (status `Critical`/`Warning`/`Info`), `false` returns only recovered alerts (status `Ok`). Omit or pass `null` to return both.",
+          "limit": {
             "type": [
-              "boolean",
+              "integer",
               "null"
-            ]
-          },
-          "limit": {
-            "description": "Page size. Max 100, default 20.",
+            ],
             "format": "int64",
-            "maximum": 100,
+            "description": "Page size. Max 100, default 20.",
             "minimum": 0,
+            "maximum": 100
+          },
+          "search_after_ctx": {
             "type": [
-              "integer",
+              "string",
               "null"
-            ]
+            ],
+            "description": "Opaque cursor from the previous response for the next page."
           },
-          "p": {
-            "description": "Page number, starting at 1. Used when `search_after_ctx` is not provided; `p * limit` must stay within 10,000 records.",
-            "format": "int64",
-            "minimum": 0,
+          "is_active": {
             "type": [
-              "integer",
+              "boolean",
               "null"
-            ]
+            ],
+            "description": "Filter by lifecycle: `true` returns only firing alerts (status `Critical`/`Warning`/`Info`), `false` returns only recovered alerts (status `Ok`). Omit or pass `null` to return both."
           },
-          "search_after_ctx": {
-            "description": "Opaque cursor from the previous response for the next page.",
+          "ever_muted": {
             "type": [
-              "string",
+              "boolean",
               "null"
-            ]
+            ],
+            "description": "Filter by whether the alert has ever been silenced."
           },
-          "start_time": {
-            "description": "Start of the search window, Unix epoch seconds.",
-            "format": "int64",
-            "type": "integer"
+          "alert_severity": {
+            "type": "string",
+            "description": "Comma-separated filter on `alert_severity`, e.g. `Critical,Warning`. Allowed values: `Critical`, `Warning`, `Info`, `Ok`; other values return `InvalidParameter`. `Ok` matches nothing because `alert_severity` is never `Ok`."
+          },
+          "channel_ids": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "int64"
+            },
+            "description": "Filter by channel IDs."
+          },
+          "integration_ids": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "int64"
+            },
+            "description": "Filter by integration IDs."
+          },
+          "alert_ids": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Filter to specific alert IDs (ObjectID hex strings). Invalid IDs are ignored; if none are valid, the result is empty."
+          },
+          "alert_keys": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Filter by alert deduplication keys."
+          },
+          "asc": {
+            "type": "boolean",
+            "description": "Sort ascending by `start_time` when `true`; default is descending."
+          },
+          "by_updated_at": {
+            "type": "boolean",
+            "description": "When `true`, also require the alert's `updated_at` to fall within [`start_time`, `end_time`], in addition to the `start_time` filter; the span must then not exceed 7 days."
           }
-        },
-        "required": [
-          "start_time",
-          "end_time"
-        ],
-        "type": "object"
+        }
       },
       "AlertListResponse": {
+        "type": "object",
         "description": "Paginated list of alerts.",
         "properties": {
+          "total": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Number of matching alerts, capped at 1,000."
+          },
           "has_next_page": {
-            "description": "True if more pages are available.",
-            "type": "boolean"
+            "type": "boolean",
+            "description": "`true` when another page exists. In cursor mode (`search_after_ctx` sent) it is exact. In page-number mode it compares `p * limit` with the capped `total`, so it is `false` past 1,000 alerts even when more match; continue with `search_after_ctx` instead."
+          },
+          "search_after_ctx": {
+            "type": "string",
+            "description": "Cursor for the next page — the ObjectID hex of the last alert on this page; pass it back as `search_after_ctx`. Omitted when the page is empty; in cursor mode also omitted when there is no next page."
           },
           "items": {
-            "description": "Alerts on the current page.",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/AlertItem"
             },
-            "type": "array"
-          },
-          "search_after_ctx": {
-            "description": "Cursor for the next page — the ObjectID hex of the last alert on this page; pass it back as `search_after_ctx`. Present only when `has_next_page` is true.",
-            "type": "string"
-          },
-          "total": {
-            "description": "Total matching alerts, capped at 1000.",
-            "format": "int64",
-            "type": "integer"
+            "description": "Alerts on the current page."
           }
-        },
-        "type": "object"
+        }
       },
       "AlertMergeRequest": {
+        "type": "object",
+        "required": [
+          "alert_ids",
+          "incident_id"
+        ],
         "properties": {
           "alert_ids": {
-            "description": "Alert IDs to merge (ObjectID hex strings); obtain them from `POST /alert/list`. Every ID must belong to the caller's account.",
+            "type": "array",
             "items": {
               "type": "string"
             },
-            "minItems": 1,
-            "type": "array"
-          },
-          "comment": {
-            "description": "Optional comment recorded on the merge feed entry. At most 1024 characters.",
-            "maxLength": 1024,
-            "type": "string"
+            "description": "Alert IDs to merge (ObjectID hex strings); obtain them from `POST /alert/list`. Every ID must belong to the caller's account."
           },
           "incident_id": {
+            "type": "string",
             "description": "Target incident ID (ObjectID hex string); obtain it from `POST /incident/list`.",
-            "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
+            "pattern": "^[0-9a-fA-F]{24}$"
           },
-          "owner_id": {
-            "description": "Member ID of the new owner for the target incident; obtain it from `POST /member/list`.",
-            "format": "int64",
-            "type": "integer"
+          "comment": {
+            "type": "string",
+            "description": "Optional comment recorded on the merge feed entry. At most 1024 characters.",
+            "maxLength": 1024
           },
           "title": {
+            "type": "string",
             "description": "Optional new title for the target incident. At most 512 characters.",
-            "maxLength": 512,
-            "type": "string"
+            "maxLength": 512
+          },
+          "owner_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Member ID of the new owner for the target incident; obtain it from `POST /member/list`."
           }
-        },
-        "required": [
-          "alert_ids",
-          "incident_id"
-        ],
-        "type": "object"
+        }
       },
       "AlertPipeline": {
+        "type": "object",
         "description": "A single alert processing rule.",
         "properties": {
-          "if": {
-            "description": "AND-filter list — the rule applies only when every condition matches. `null` or omitted means the rule applies to all events.",
-            "items": {
-              "$ref": "#/components/schemas/FilterCondition"
-            },
-            "type": [
-              "array",
-              "null"
-            ]
-          },
           "kind": {
-            "description": "Rule type. Rules run in array order; when the `if` condition matches, the event is processed according to `kind`.\n| Value | Meaning |\n|---|---|\n| `title_reset` | Rewrites the event title from the `settings.title` template. |\n| `description_reset` | Rewrites the event description from the `settings.description` template. |\n| `severity_reset` | Resets the event severity and status to `settings.severity` (`Critical`/`Warning`/`Info`). |\n| `alert_drop` | Discards the matching event outright; no alert is created. |\n| `alert_inhibit` | Discards the event (inhibition) when an active source alert matching `settings.source_filters` and correlated via `settings.equals` exists. |",
+            "type": "string",
             "enum": [
               "title_reset",
               "description_reset",
@@ -1840,9 +1877,20 @@
               "alert_drop",
               "alert_inhibit"
             ],
-            "type": "string"
+            "description": "Rule type. Rules run in array order; when the `if` condition matches, the event is processed according to `kind`.\n| Value | Meaning |\n|---|---|\n| `title_reset` | Rewrites the event title from the `settings.title` template. |\n| `description_reset` | Rewrites the event description from the `settings.description` template. |\n| `severity_reset` | Resets the event severity and status to `settings.severity` (`Critical`/`Warning`/`Info`). |\n| `alert_drop` | Discards the matching event outright; no alert is created. |\n| `alert_inhibit` | Discards the event (inhibition) when an active source alert matching `settings.source_filters` and correlated via `settings.equals` exists. |"
+          },
+          "if": {
+            "type": [
+              "array",
+              "null"
+            ],
+            "items": {
+              "$ref": "#/components/schemas/FilterCondition"
+            },
+            "description": "AND-filter list — the rule applies only when every condition matches the incoming event. Keys: `severity` (aliases `alert_severity`, `event_severity`), `status`, `title`, `title_rule`, `description`, `alert_key`, `integration_id` (alias `data_source_id`), and `labels.<name>`; other keys return `InvalidParameter`. `null` or omitted means the rule applies to all events."
           },
           "settings": {
+            "type": "object",
             "description": "Kind-specific settings. Shape depends on `kind`:\n- `title_reset`: `{ \"title\": \"<string>\" }`\n- `description_reset`: `{ \"description\": \"<string>\" }`\n- `severity_reset`: `{ \"severity\": \"Critical\"|\"Warning\"|\"Info\" }`\n- `alert_drop`: `{}` (empty object)\n- `alert_inhibit`: `{ \"equals\": [\"<label_key>\", ...], \"source_filters\": <OrFilterGroup> }`",
             "oneOf": [
               {
@@ -1860,14 +1908,12 @@
               {
                 "$ref": "#/components/schemas/ApAlertInhibit"
               }
-            ],
-            "type": "object"
+            ]
           }
         },
         "required": [
           "kind"
-        ],
-        "type": "object"
+        ]
       },
       "AlertPipelineInfoRequest": {
         "properties": {
@@ -1963,27 +2009,26 @@
         "type": "object"
       },
       "AlertPipelineUpsertRequest": {
+        "type": "object",
+        "required": [
+          "integration_id",
+          "rules"
+        ],
         "properties": {
           "integration_id": {
-            "description": "Integration ID to configure.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "ID of the integration to configure; account-level and channel-owned integrations are both accepted."
           },
           "rules": {
-            "description": "Rules to apply, evaluated in array order. Between 1 and 50 entries.",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/AlertPipeline"
             },
-            "maxItems": 50,
-            "minItems": 1,
-            "type": "array"
+            "description": "Rules to apply, evaluated in array order. At most 50 entries; an empty array removes all rules.",
+            "maxItems": 50
           }
-        },
-        "required": [
-          "integration_id",
-          "rules"
-        ],
-        "type": "object"
+        }
       },
       "AlertRule": {
         "description": "Full alert rule configuration.",
@@ -2174,131 +2219,179 @@
         "type": "object"
       },
       "AlertRuleAudit": {
+        "type": "object",
         "description": "An audit record capturing a rule snapshot at a point in time.",
+        "required": [
+          "id",
+          "account_id",
+          "alert_rule_id",
+          "action",
+          "creator_id",
+          "creator_name",
+          "created_at"
+        ],
         "properties": {
+          "id": {
+            "type": "integer",
+            "format": "uint64",
+            "description": "Audit record ID."
+          },
           "account_id": {
-            "description": "ID of the account that owns the rule.",
+            "type": "integer",
             "format": "uint64",
-            "type": "integer"
+            "description": "ID of the account that owns the rule."
+          },
+          "alert_rule_id": {
+            "type": "integer",
+            "format": "uint64",
+            "description": "ID of the alert rule this record belongs to."
           },
           "action": {
+            "type": "string",
             "description": "Action performed: `create` = rule created; `update` = rule updated (covers full updates, field-batch updates, imports and moves).",
             "enum": [
               "create",
               "update"
-            ],
-            "type": "string"
-          },
-          "alert_rule_id": {
-            "description": "ID of the alert rule this record belongs to.",
-            "format": "uint64",
-            "type": "integer"
+            ]
           },
           "content": {
-            "description": "JSON string of the full rule snapshot at audit time. Populated on `/monit/rule/audit/detail`, omitted on list responses.",
-            "type": "string"
-          },
-          "created_at": {
-            "description": "When this audit record was produced, as a Unix timestamp in seconds; equals the rule's `updated_at` at change time.",
-            "format": "int64",
-            "type": "integer"
+            "type": "string",
+            "description": "JSON string of the full rule right after the change. Populated on `/monit/rule/audit/detail`, omitted on list responses. Records written by `/monit/rule/v2/create` and `/monit/rule/v2/update` use the `AlertRuleV2` shape; records written by `/monit/rule/update/fields` and `/monit/rule/move` use the stored rule shape, whose checker configs carry legacy recovery settings instead of `recovery_mode` / `end_mode`."
           },
           "creator_id": {
-            "description": "ID of the user who made this change (taken from the rule's `updater_id` at change time).",
+            "type": "integer",
             "format": "uint64",
-            "type": "integer"
+            "description": "ID of the user who made this change (taken from the rule's `updater_id` at change time)."
           },
           "creator_name": {
-            "description": "Name of the user who made this change (taken from the rule's `updater_name` at change time).",
-            "type": "string"
+            "type": "string",
+            "description": "Name of the user who made this change (taken from the rule's `updater_name` at change time)."
           },
-          "id": {
-            "description": "Audit record ID.",
-            "format": "uint64",
-            "type": "integer"
+          "created_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "When this audit record was produced, as a Unix timestamp in seconds; equals the rule's `updated_at` at change time."
           }
-        },
+        }
+      },
+      "AlertRuleBasic": {
+        "type": "object",
+        "description": "Basic alert rule information for list views. In `include_descendants: true` listings only `id`, `folder_id` and `name` are filled; the other fields carry zero values.",
         "required": [
           "id",
           "account_id",
-          "alert_rule_id",
-          "action",
+          "folder_id",
+          "name",
+          "ds_type",
+          "enabled",
+          "debug_log_enabled",
+          "cron_pattern",
+          "delay_seconds",
           "creator_id",
           "creator_name",
-          "created_at"
+          "updater_id",
+          "updater_name",
+          "created_at",
+          "updated_at",
+          "triggered",
+          "labels",
+          "timezone",
+          "active_alert_count"
         ],
-        "type": "object"
-      },
-      "AlertRuleBasic": {
-        "description": "Basic alert rule information for list views.",
         "properties": {
+          "id": {
+            "type": "integer",
+            "format": "uint64",
+            "description": "Unique rule ID."
+          },
           "account_id": {
-            "description": "Account ID.",
+            "type": "integer",
             "format": "uint64",
-            "type": "integer"
+            "description": "ID of the account that owns the rule; `0` in `include_descendants: true` listings."
           },
-          "active_alert_count": {
-            "description": "Number of currently active (unrecovered) alerts fired by this rule. `triggered` equals `active_alert_count > 0`.",
-            "format": "int64",
-            "type": "integer"
+          "folder_id": {
+            "type": "integer",
+            "format": "uint64",
+            "description": "ID of the folder that directly contains the rule; in `include_descendants: true` listings it can be a descendant of the requested folder."
           },
-          "created_at": {
-            "description": "Creation time, as a Unix timestamp in seconds.",
-            "format": "int64",
-            "type": "integer"
+          "name": {
+            "type": "string",
+            "description": "Rule name, unique within its folder (at most 128 characters)."
           },
-          "creator_id": {
-            "description": "ID of the user who created the rule.",
-            "format": "uint64",
-            "type": "integer"
+          "labels": {
+            "type": [
+              "object",
+              "null"
+            ],
+            "additionalProperties": {
+              "type": "string"
+            },
+            "description": "Custom labels the rule adds to its alert events; `null` in `include_descendants: true` listings."
           },
-          "creator_name": {
-            "description": "Name of the user who created the rule.",
-            "type": "string"
+          "ds_type": {
+            "type": "string",
+            "description": "Datasource type the rule queries. Types that support alerting: `prometheus`, `elasticsearch`, `loki`, `clickhouse`, `mysql`, `oracle`, `postgres`, `sls`, `tencent_cls`, `victorialogs`. Only enabled rules are checked against this list, so a disabled rule may carry another value; empty in `include_descendants: true` listings."
           },
-          "cron_pattern": {
-            "description": "Schedule expression: a 6-field cron with seconds, e.g. `0 * * * * *`, or an `@every 30s` interval descriptor. Must not start with `CRON_TZ=` or `TZ=`; use the `timezone` field instead.",
-            "type": "string"
+          "enabled": {
+            "type": "boolean",
+            "description": "Whether the rule is enabled."
           },
           "debug_log_enabled": {
-            "description": "Whether debug logging is enabled.",
-            "type": "boolean"
+            "type": "boolean",
+            "description": "Whether debug logging is on; when `true` the edge writes detailed evaluation logs for this rule."
           },
-          "delay_seconds": {
-            "description": "Evaluation delay in seconds.",
-            "type": "integer"
+          "cron_pattern": {
+            "type": "string",
+            "description": "Schedule expression: a 6-field cron with seconds, e.g. `0 * * * * *`, or an `@every 30s` interval descriptor. Must not start with `CRON_TZ=` or `TZ=`; use the `timezone` field instead."
           },
-          "ds_type": {
-            "description": "Data source type, e.g. `prometheus`.",
-            "type": "string"
+          "timezone": {
+            "type": "string",
+            "description": "Timezone in which the rule executes. Determines how the cron schedule and effective time windows are interpreted. Only IANA timezone names are accepted (e.g. `Asia/Shanghai`, `UTC`, `Europe/London`); shortcuts and offsets such as `Local`, `UTC+8`, or `CST` are rejected. Treated as `Asia/Shanghai` if empty.",
+            "default": "Asia/Shanghai"
           },
-          "enabled": {
-            "description": "Whether the rule is enabled.",
-            "type": "boolean"
+          "delay_seconds": {
+            "type": "integer",
+            "description": "Seconds the evaluation query window is shifted back to allow for data ingestion latency."
           },
-          "folder_id": {
-            "description": "Folder ID.",
+          "creator_id": {
+            "type": "integer",
             "format": "uint64",
-            "type": "integer"
+            "description": "ID of the user who created the rule."
           },
-          "id": {
-            "description": "Unique rule ID.",
-            "format": "uint64",
-            "type": "integer"
+          "creator_name": {
+            "type": "string",
+            "description": "Name of the user who created the rule."
           },
-          "labels": {
-            "additionalProperties": {
-              "type": "string"
-            },
-            "description": "Custom labels.",
-            "type": "object"
+          "updater_id": {
+            "type": "integer",
+            "format": "uint64",
+            "description": "ID of the user who last modified the rule."
           },
-          "name": {
-            "description": "Rule name.",
-            "type": "string"
+          "updater_name": {
+            "type": "string",
+            "description": "Name of the user who last modified the rule."
+          },
+          "created_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Creation time, as a Unix timestamp in seconds."
+          },
+          "updated_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Last modification time, as a Unix timestamp in seconds."
+          },
+          "triggered": {
+            "type": "boolean",
+            "description": "True if the rule currently has active alerts."
+          },
+          "active_alert_count": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Number of currently active (unrecovered) alerts fired by this rule. `triggered` equals `active_alert_count > 0`."
           },
           "runtime_state": {
-            "description": "Runtime evaluation state, derived from edge heartbeats and the edge-reported rule status. Omitted when the state is unavailable.\n\n| Value | Meaning |\n|---|---|\n| `disabled` | The rule is disabled. |\n| `offline` | The edge instance or cluster owning this rule is offline. |\n| `abnormal` | The edge reports evaluation errors. |\n| `stale` | The edge's runtime status report is outdated. |\n| `no_datasource` | No datasource currently matches the rule's `ds_list` / `ds_ids`. |\n| `config_pending` | The latest rule config has not been delivered to the edge yet. |\n| `waiting` | Enabled, but the edge has not reported runtime status yet. |\n| `normal` | Evaluating normally. |",
+            "type": "string",
             "enum": [
               "disabled",
               "offline",
@@ -2309,54 +2402,9 @@
               "waiting",
               "normal"
             ],
-            "type": "string"
-          },
-          "timezone": {
-            "default": "Asia/Shanghai",
-            "description": "Timezone in which the rule executes. Determines how the cron schedule and effective time windows are interpreted. Only IANA timezone names are accepted (e.g. `Asia/Shanghai`, `UTC`, `Europe/London`); shortcuts and offsets such as `Local`, `UTC+8`, or `CST` are rejected. Treated as `Asia/Shanghai` if empty.",
-            "type": "string"
-          },
-          "triggered": {
-            "description": "True if the rule currently has active alerts.",
-            "type": "boolean"
-          },
-          "updated_at": {
-            "description": "Last modification time, as a Unix timestamp in seconds.",
-            "format": "int64",
-            "type": "integer"
-          },
-          "updater_id": {
-            "description": "ID of the user who last modified the rule.",
-            "format": "uint64",
-            "type": "integer"
-          },
-          "updater_name": {
-            "description": "Name of the user who last modified the rule.",
-            "type": "string"
+            "description": "Runtime evaluation state, derived from edge heartbeats and the edge-reported rule status. Omitted when the state is unavailable.\n\n| Value | Meaning |\n|---|---|\n| `disabled` | The rule is disabled. |\n| `offline` | The edge instance or cluster owning this rule is offline. |\n| `abnormal` | The edge reports evaluation errors. |\n| `stale` | The edge's runtime status report is outdated. |\n| `no_datasource` | No datasource currently matches the rule's `ds_list` / `ds_ids`. |\n| `config_pending` | The latest rule config has not been delivered to the edge yet. |\n| `waiting` | Enabled, but the edge has not reported runtime status yet. |\n| `normal` | Evaluating normally. |"
           }
-        },
-        "required": [
-          "id",
-          "account_id",
-          "folder_id",
-          "name",
-          "ds_type",
-          "enabled",
-          "debug_log_enabled",
-          "cron_pattern",
-          "delay_seconds",
-          "creator_id",
-          "creator_name",
-          "updater_id",
-          "updater_name",
-          "created_at",
-          "updated_at",
-          "triggered",
-          "labels",
-          "timezone",
-          "active_alert_count"
-        ],
-        "type": "object"
+        }
       },
       "AlertRuleCounter": {
         "description": "One historical snapshot of the account's alert rule total.",
@@ -2516,96 +2564,97 @@
         "type": "object"
       },
       "ApAlertDrop": {
-        "description": "Settings for `alert_drop` rule: no additional settings required. Matched alerts are silently discarded.",
-        "properties": {},
-        "type": "object"
+        "type": "object",
+        "description": "Settings for `alert_drop`: no fields; send `{}`. A matching event is discarded and no alert is created or updated.",
+        "properties": {}
       },
       "ApAlertInhibit": {
-        "description": "Settings for `alert_inhibit` rule: suppresses source alerts that match the filter when they share the same label values as the current alert.",
+        "type": "object",
+        "description": "Settings for `alert_inhibit`: the current event is discarded when an active alert of the same integration, with a different `alert_key` and started within the 10 minutes before the event, matches `source_filters` and has the same value as the event for every `equals` key.",
+        "required": [
+          "equals",
+          "source_filters"
+        ],
         "properties": {
           "equals": {
-            "description": "Label keys whose values must be equal between the source and current alert for inhibition to apply.",
+            "type": "array",
             "items": {
               "type": "string"
             },
-            "type": "array"
+            "description": "Keys whose values must be equal on the source alert and the current event: `title`, `severity`, or `labels.<name>`. An empty list, any other key, or a label missing on the event means the rule never inhibits."
           },
           "source_filters": {
-            "description": "AND-filter list identifying the source alerts to inhibit — every condition must match.",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/FilterCondition"
             },
-            "type": "array"
+            "description": "AND-conditions a source alert must meet. Allowed keys: `severity`, `title`, and `labels.<name>`; other keys return `InvalidParameter`."
           }
-        },
-        "required": [
-          "equals",
-          "source_filters"
-        ],
-        "type": "object"
+        }
       },
       "ApDescriptionReset": {
-        "description": "Settings for `description_reset` rule: overrides the alert description.",
-        "properties": {
-          "description": {
-            "description": "New description template.",
-            "type": "string"
-          }
-        },
+        "type": "object",
+        "description": "Settings for `description_reset`: replaces the event description with a rendered template.",
         "required": [
           "description"
         ],
-        "type": "object"
+        "properties": {
+          "description": {
+            "type": "string",
+            "description": "Description template. Only a value starting with `[TPL]` takes effect: the rest is rendered as a Go template against the event and replaces the description. A value without the prefix leaves the description unchanged."
+          }
+        }
       },
       "ApSeverityReset": {
-        "description": "Settings for `severity_reset` rule: forces the alert severity to a fixed value.",
+        "type": "object",
+        "description": "Settings for `severity_reset`: sets the event severity, and its status, to a fixed value.",
+        "required": [
+          "severity"
+        ],
         "properties": {
           "severity": {
-            "description": "Target severity level.",
+            "type": "string",
             "enum": [
               "Critical",
               "Warning",
               "Info"
             ],
-            "type": "string"
+            "description": "Severity to set: `Critical`, `Warning` or `Info`. The event status is set to the same value."
           }
-        },
-        "required": [
-          "severity"
-        ],
-        "type": "object"
+        }
       },
       "ApTitleReset": {
-        "description": "Settings for `title_reset` rule: overrides the alert title with a template string.",
-        "properties": {
-          "title": {
-            "description": "New title template. Supports Golang template syntax referencing alert fields.",
-            "type": "string"
-          }
-        },
+        "type": "object",
+        "description": "Settings for `title_reset`: replaces the event title using a title rule.",
         "required": [
           "title"
         ],
-        "type": "object"
+        "properties": {
+          "title": {
+            "type": "string",
+            "description": "Title rule. A value starting with `[TPL]` is a Go template rendered against the event, e.g. `[TPL]{{.Labels.service}}`. Otherwise it is a `::`-separated list in which each `$name` part is replaced by the value of label `name` and other parts are kept as written."
+          }
+        }
       },
       "ArtifactFileStateItem": {
-        "description": "Live publish state of one presented file. Returned only for files that have a live published artifact.",
+        "type": "object",
+        "description": "Live gallery state of one presented file. Matched by the file's source session and workspace path, so an older version of a republished file also reports the current artifact.",
         "properties": {
-          "artifact_id": {
-            "description": "Artifact ID (`art_` prefix). Also the key of the public-share link.",
-            "type": "string"
-          },
           "file_id": {
-            "description": "Echoes the requested presented-file ID.",
-            "type": "string"
+            "type": "string",
+            "description": "The requested presented-file ID this entry answers for."
           },
-          "gallery_path": {
-            "description": "Console-relative path of the artifact page: `/ai-sre/artifacts/<artifact_id>`.",
-            "type": "string"
+          "artifact_id": {
+            "type": "string",
+            "description": "Artifact ID (`art_` prefix). Also the key of the public-share link."
           },
           "title": {
-            "description": "Gallery display title of the published artifact.",
-            "type": "string"
+            "type": "string",
+            "description": "Gallery display title of the published artifact."
+          },
+          "gallery_path": {
+            "type": "string",
+            "description": "Console-relative path of the artifact page: `/ai-sre/artifacts/<artifact_id>`."
           }
         },
         "required": [
@@ -2613,42 +2662,41 @@
           "artifact_id",
           "title",
           "gallery_path"
-        ],
-        "type": "object"
+        ]
       },
       "ArtifactFileStateRequest": {
+        "type": "object",
         "description": "Probe publish state for a batch of presented files.",
         "properties": {
           "file_ids": {
-            "description": "Presented-file IDs (`pf_` prefix) to probe. At most 50 per call; duplicates and empty strings are ignored.",
+            "type": "array",
             "items": {
               "type": "string"
             },
             "maxItems": 50,
             "minItems": 1,
-            "type": "array"
+            "description": "Presented-file IDs (`pf_` prefix) to check. At most 50 entries per call, counted before duplicates and empty strings are removed; more fails with `InvalidParameter`."
           }
         },
         "required": [
           "file_ids"
-        ],
-        "type": "object"
+        ]
       },
       "ArtifactFileStateResponse": {
+        "type": "object",
         "description": "Publish states keyed by file.",
         "properties": {
           "items": {
-            "description": "One entry per requested file that has a live published artifact; files without one are omitted.",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/ArtifactFileStateItem"
             },
-            "type": "array"
+            "description": "One entry per requested file whose session file path currently has a live gallery artifact; files without one, and unknown IDs, are omitted. An empty array when none match."
           }
         },
         "required": [
           "items"
-        ],
-        "type": "object"
+        ]
       },
       "ArtifactIdRequest": {
         "description": "Identify one gallery artifact.",
@@ -2664,74 +2712,76 @@
         "type": "object"
       },
       "ArtifactListRequest": {
+        "type": "object",
         "description": "Filter and paginate the artifact gallery.",
         "properties": {
-          "asc": {
-            "description": "Sort ascending when true, descending when false. Applies only when `orderby` is set.",
-            "type": "boolean"
-          },
-          "limit": {
-            "default": 20,
-            "description": "Page size. Defaults to 20; capped at 100.",
-            "maximum": 100,
-            "type": "integer"
-          },
-          "orderby": {
-            "description": "Sort field: `created_at` or `updated_at`. Empty means `updated_at` descending.",
-            "enum": [
-              "created_at",
-              "updated_at"
-            ],
-            "type": "string"
-          },
-          "page": {
-            "default": 1,
-            "description": "Page number, 1-based.",
-            "minimum": 1,
-            "type": "integer"
-          },
-          "query": {
-            "description": "Case-insensitive substring match on the artifact title.",
-            "type": "string"
-          },
           "scope": {
-            "default": "all",
-            "description": "Visibility scope. `all` (default) lists the caller's own personal artifacts plus artifacts of every team the caller belongs to; `personal` lists only the caller's own; `team` lists only team-owned artifacts of the caller's teams.",
+            "type": "string",
             "enum": [
               "all",
               "personal",
               "team"
             ],
-            "type": "string"
+            "default": "all",
+            "description": "Visibility scope. `all` (default) lists the caller's own personal artifacts plus artifacts of every team the caller belongs to; `personal` lists only the caller's own; `team` lists only team-owned artifacts of the caller's teams."
           },
           "team_ids": {
-            "description": "Restrict to artifacts owned by these team IDs, intersected with the caller's visibility — teams the caller does not belong to silently return nothing.",
+            "type": "array",
             "items": {
-              "format": "int64",
-              "type": "integer"
+              "type": "integer",
+              "format": "int64"
             },
-            "type": "array"
+            "description": "Restrict to artifacts owned by these team IDs, intersected with the `scope` filter. Non-positive IDs are ignored; teams the caller does not belong to return nothing, and personal artifacts are excluded whenever this is set."
+          },
+          "query": {
+            "type": "string",
+            "description": "Case-insensitive substring match on the artifact title."
+          },
+          "page": {
+            "type": "integer",
+            "default": 1,
+            "description": "Page number, 1-based. Values below 1 are treated as 1."
+          },
+          "limit": {
+            "type": "integer",
+            "default": 20,
+            "description": "Number of artifacts per page. Values below 1 fall back to 20; values above 100 are capped at 100 (not rejected)."
+          },
+          "orderby": {
+            "type": "string",
+            "enum": [
+              "created_at",
+              "updated_at"
+            ],
+            "description": "Sort field: `created_at` (publish time) or `updated_at` (last change). Empty sorts by `updated_at` descending. In every case the caller's pinned artifacts come first, and `artifact_id` breaks ties."
+          },
+          "asc": {
+            "type": "boolean",
+            "description": "Sort ascending when true, descending when false. Applies only when `orderby` is set."
           }
-        },
-        "type": "object"
+        }
       },
       "ArtifactListResponse": {
+        "type": "object",
         "description": "A page of gallery artifacts.",
         "properties": {
           "items": {
-            "description": "Artifacts on this page.",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/PublishedArtifactItem"
             },
-            "type": "array"
+            "description": "Artifacts on this page; the caller's pinned artifacts come first. An empty array when nothing matches."
           },
           "total": {
-            "description": "Total number of artifacts matching the filter across all pages.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Total number of artifacts matching the filter across all pages."
           }
         },
-        "type": "object"
+        "required": [
+          "items",
+          "total"
+        ]
       },
       "ArtifactPublishFromFileRequest": {
         "description": "Publish a session-produced file to the artifact gallery.",
@@ -2775,29 +2825,30 @@
         "type": "object"
       },
       "ArtifactShareState": {
+        "type": "object",
         "description": "Public-share state of an artifact.",
         "properties": {
           "artifact_id": {
-            "description": "Artifact ID (`art_` prefix). Also the key of the public-share link.",
-            "type": "string"
-          },
-          "public_url": {
-            "description": "Anonymous public link served entirely from CDN. Anyone with the link can view the content, no login required.",
-            "type": "string"
+            "type": "string",
+            "description": "Artifact ID (`art_` prefix). Also the key of the public-share link."
           },
           "share_enabled": {
-            "description": "Always `true` in this response.",
-            "type": "boolean"
+            "type": "boolean",
+            "description": "Always `true` in this response."
           },
-          "shared_at": {
-            "description": "Unix timestamp in milliseconds of the last share enable or snapshot sync.",
-            "format": "int64",
-            "type": "integer"
+          "public_url": {
+            "type": "string",
+            "description": "Anonymous public link, `<console origin>/share/artifact/<artifact_id>`. Anyone with the link can view the content without signing in. The link is the same on every enable."
           },
           "shared_by": {
-            "description": "Person ID of the member who enabled sharing.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Person ID of the member who enabled sharing. A snapshot sync keeps the original value."
+          },
+          "shared_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Unix timestamp in milliseconds of the last share enable or snapshot sync."
           }
         },
         "required": [
@@ -2806,8 +2857,7 @@
           "public_url",
           "shared_by",
           "shared_at"
-        ],
-        "type": "object"
+        ]
       },
       "ArtifactSignRequest": {
         "description": "Request signed download/preview URLs for a presented file.",
@@ -2827,247 +2877,259 @@
         "type": "object"
       },
       "ArtifactUpdateRequest": {
+        "type": "object",
         "description": "Partial update of a gallery artifact. Only provided fields change.",
         "properties": {
           "artifact_id": {
-            "description": "Artifact ID (`art_` prefix). Also the key of the public-share link.",
-            "type": "string"
+            "type": "string",
+            "description": "Artifact ID (`art_` prefix). Also the key of the public-share link."
           },
-          "team_id": {
-            "description": "Transfer target scope. `0` moves the artifact to personal scope (only the creator can manage it); a positive value moves it to a team the caller must belong to. Omit to leave unchanged.",
-            "format": "int64",
+          "title": {
             "type": [
-              "integer",
+              "string",
               "null"
-            ]
+            ],
+            "description": "New title. Leading and trailing spaces are trimmed; a blank value fails with `InvalidParameter`. Omit or send `null` to keep the current title."
           },
-          "title": {
-            "description": "New title. Trimmed; must be non-empty when provided. Omit to leave unchanged.",
+          "team_id": {
             "type": [
-              "string",
+              "integer",
               "null"
-            ]
+            ],
+            "format": "int64",
+            "description": "Transfer target. `0` moves the artifact to personal scope and only its creator may do that; a positive value moves it to that team, and the caller must be a member of the team; a negative value fails with `InvalidParameter`. Omit or send `null` to keep the current scope. The creator (`person_id`) never changes."
           }
         },
         "required": [
           "artifact_id"
-        ],
-        "type": "object"
+        ]
       },
       "AssignIncidentRequest": {
+        "type": "object",
         "description": "Parameters for dispatching one or more incidents to a target. Provide `incident_id` or `incident_ids` but not both.",
+        "required": [
+          "assigned_to"
+        ],
         "properties": {
-          "assigned_to": {
-            "$ref": "#/components/schemas/AssignedTo",
-            "description": "Assign target; at least one of `person_ids` and `escalate_rule_id` must be set."
-          },
           "incident_id": {
-            "description": "Single incident ID. Ignored when `incident_ids` is also provided.",
+            "type": "string",
             "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
+            "description": "Single incident ID. Ignored when `incident_ids` is also provided."
           },
           "incident_ids": {
-            "description": "Incident IDs to assign in bulk; obtain them from `POST /incident/list`.",
+            "type": "array",
             "items": {
-              "pattern": "^[0-9a-fA-F]{24}$",
-              "type": "string"
+              "type": "string",
+              "pattern": "^[0-9a-fA-F]{24}$"
             },
-            "maxItems": 100,
             "minItems": 1,
-            "type": "array"
+            "maxItems": 100,
+            "description": "Incident IDs to assign in bulk; obtain them from `POST /incident/list`."
+          },
+          "assigned_to": {
+            "$ref": "#/components/schemas/AssignedTo",
+            "description": "Assignment target. Set `person_ids`, `escalate_rule_id`, or `emails`; when none is set, the server re-runs the channel's escalation rule matching."
           }
-        },
-        "required": [
-          "assigned_to"
-        ],
-        "type": "object"
+        }
       },
       "AssignedTo": {
-        "description": "Incident assignment target. Either `person_ids` or `escalate_rule_id` must be provided.",
+        "type": "object",
+        "description": "Assignment target. In requests, set `person_ids`, `escalate_rule_id`, or `emails`; when none is set the server re-runs the channel's escalation rule matching. In responses the object is always present; an incident that was never assigned has empty `type`, `id`, and `assigned_at` of `0`.",
         "properties": {
-          "assigned_at": {
-            "description": "Unix timestamp (seconds) when the assignment was made.",
-            "format": "int64",
-            "type": "integer"
-          },
-          "emails": {
-            "description": "Email recipients, used by integrations such as ServiceNow.",
+          "person_ids": {
+            "type": "array",
             "items": {
-              "format": "email",
-              "type": "string"
+              "type": "integer",
+              "format": "int64"
             },
-            "maxItems": 100,
             "minItems": 1,
-            "type": "array"
+            "maxItems": 100,
+            "description": "Member IDs to assign directly."
           },
           "escalate_rule_id": {
-            "description": "Escalation rule ID (MongoDB ObjectID) to drive assignment.",
+            "type": "string",
             "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
+            "description": "Escalation rule ID (MongoDB ObjectID) to drive assignment."
           },
-          "escalate_rule_name": {
-            "description": "Escalation rule display name, filled by the server.",
-            "type": "string"
+          "layer_idx": {
+            "type": "integer",
+            "description": "Zero-based escalation level within `escalate_rule_id` (`0` = first level). Responders are taken from this level."
           },
-          "id": {
-            "description": "Opaque assignment ID generated by the server.",
-            "type": "string"
+          "type": {
+            "type": "string",
+            "description": "How the assignment happened: `assign` first assignment; `reassign` reassignment of an already assigned incident; `escalate` moved by the escalation flow; `reopen` reassignment after the incident was reopened; empty string in responses when the incident was never assigned. Omit it in requests and the server derives it.",
+            "enum": [
+              "assign",
+              "reassign",
+              "escalate",
+              "reopen",
+              ""
+            ]
           },
-          "layer_idx": {
-            "description": "Current level index within the escalation rule.",
-            "type": "integer"
+          "emails": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "format": "email"
+            },
+            "minItems": 1,
+            "maxItems": 100,
+            "description": "Member emails; each is resolved to a member ID and merged into `person_ids`. Emails without a matching member are ignored."
           },
           "notify": {
+            "type": "object",
             "description": "Override the notification channels used for this assignment.",
             "properties": {
               "follow_preference": {
-                "description": "When false, use `personal_channels`; when true or omitted, use each responder's personal preference.",
                 "type": [
                   "boolean",
                   "null"
-                ]
+                ],
+                "description": "`true`: notify each person through their personal notification preference. `false`: use `personal_channels`, which must then be non-empty. When omitted, `personal_channels` must be set."
               },
               "personal_channels": {
-                "description": "Channels to use (e.g. `voice`, `sms`, `email`).",
+                "type": "array",
                 "items": {
                   "type": "string"
                 },
-                "type": "array"
+                "description": "Channels used when `follow_preference` is `false`: `sms`, `voice`, `email`, `push` (mobile app push), or an IM app channel written as `feishu_app:<integration_id>`, `dingtalk_app:<integration_id>`, `wecom_app:<integration_id>`, `slack_app:<integration_id>`, or `teams_app:<integration_id>`. Ignored when `follow_preference` is `true`."
               },
               "template_id": {
-                "description": "Notification template ID (MongoDB ObjectID).",
+                "type": "string",
                 "pattern": "^[0-9a-fA-F]{24}$",
-                "type": "string"
+                "description": "Notification template ID (MongoDB ObjectID)."
               }
-            },
-            "type": "object"
+            }
           },
-          "person_ids": {
-            "description": "Member IDs to assign directly.",
+          "escalate_rule_name": {
+            "type": "string",
+            "description": "Escalation rule name, filled by the server in responses; ignored in requests."
+          },
+          "assigned_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Unix timestamp (seconds) when the assignment was made; set by the server."
+          },
+          "id": {
+            "type": "string",
+            "description": "Assignment ID generated by the server for each assignment; set by the server."
+          },
+          "effective_person_ids": {
+            "type": "array",
             "items": {
-              "format": "int64",
-              "type": "integer"
+              "type": "integer",
+              "format": "int64"
             },
-            "maxItems": 100,
-            "minItems": 1,
-            "type": "array"
-          },
-          "type": {
-            "description": "Assignment type: `assign` direct assignment, `reassign` reassignment, `escalate` escalation-rule driven, `reopen` automatic reassignment on reopen.",
-            "enum": [
-              "assign",
-              "reassign",
-              "escalate",
-              "reopen"
-            ],
-            "type": "string"
+            "description": "Member IDs that actually received the assignment: `person_ids` plus the members of the selected escalation level, deduplicated and sorted. Set by the server; omitted when empty."
           }
-        },
-        "type": "object"
+        }
       },
       "AuditLog": {
+        "type": "object",
         "description": "A single audit log entry.",
+        "required": [
+          "created_at",
+          "account_id",
+          "member_id",
+          "member_name",
+          "request_id",
+          "ip",
+          "operation",
+          "operation_name",
+          "body",
+          "params",
+          "is_dangerous",
+          "is_write",
+          "principal_kind",
+          "credential_type",
+          "credential_id"
+        ],
         "properties": {
-          "account_id": {
-            "description": "ID of the account.",
-            "format": "uint64",
-            "type": "integer"
-          },
-          "body": {
-            "description": "JSON-encoded request body. Bodies containing sensitive fields are base64url-encoded instead; bodies over 10 KB are replaced by a truncation placeholder.",
-            "type": "string"
-          },
           "created_at": {
-            "description": "Timestamp of the operation in Unix epoch milliseconds.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Timestamp of the operation in Unix epoch milliseconds."
           },
-          "credential_id": {
-            "description": "ID of the credential (the app key ID) when `credential_type` is `app_key`; 0 otherwise.",
+          "account_id": {
+            "type": "integer",
             "format": "uint64",
-            "type": "integer"
-          },
-          "credential_type": {
-            "description": "Credential type used for the call. `app_key` for a long-lived console app key, `ephemeral_app_key` for a short-lived key issued to AI SRE, and an empty string for member sessions.",
-            "type": "string"
-          },
-          "ip": {
-            "description": "Client IP address of the caller.",
-            "type": "string"
-          },
-          "is_dangerous": {
-            "description": "True if this is flagged as a high-risk operation.",
-            "type": "boolean"
-          },
-          "is_write": {
-            "description": "True for mutating operations; false for read-only ones.",
-            "type": "boolean"
+            "description": "ID of the account the entry belongs to."
           },
           "member_id": {
-            "description": "ID of the member who performed the action. 0 when the action was performed by the account principal itself.",
+            "type": "integer",
             "format": "uint64",
-            "type": "integer"
+            "description": "ID of the member who performed the action. 0 when the action was performed by the account principal itself."
           },
           "member_name": {
-            "description": "Display name of the member. Empty when `member_id` is 0.",
-            "type": "string"
+            "type": "string",
+            "description": "Display name of the member. Empty when `member_id` is 0."
+          },
+          "request_id": {
+            "type": "string",
+            "description": "Unique request ID for correlation."
+          },
+          "ip": {
+            "type": "string",
+            "description": "Client IP address of the caller."
           },
           "operation": {
-            "description": "Stable machine-readable operation name, e.g. `template:write:create`.",
-            "type": "string"
+            "type": "string",
+            "description": "Stable machine-readable operation name, e.g. `template:write:create`."
           },
           "operation_name": {
-            "description": "Human-readable Chinese label of the operation (e.g. `创建模板`).",
-            "type": "string"
+            "type": "string",
+            "description": "Human-readable Chinese label of the operation (e.g. `创建模板`)."
+          },
+          "body": {
+            "type": "string",
+            "description": "JSON-encoded request body. Bodies containing sensitive fields are base64url-encoded instead; bodies over 10 KB are replaced by a truncation placeholder."
           },
           "params": {
-            "description": "URL path parameters as an array of key-value pairs, or an empty array when none.",
+            "type": [
+              "array",
+              "string"
+            ],
             "items": {
+              "type": "object",
               "properties": {
                 "Key": {
-                  "description": "Name of a URL path parameter (the `:xxx` placeholder in the route).",
-                  "type": "string"
+                  "type": "string",
+                  "description": "Name of a URL path parameter (the `:xxx` placeholder in the route)."
                 },
                 "Value": {
-                  "description": "The actual value of that path parameter in this request.",
-                  "type": "string"
+                  "type": "string",
+                  "description": "The actual value of that path parameter in this request."
                 }
-              },
-              "type": "object"
+              }
             },
-            "type": "array"
+            "description": "URL path parameters as an array of `Key`/`Value` pairs (an empty array when none). Some deployments return the same array as a JSON-encoded string."
+          },
+          "is_dangerous": {
+            "type": "boolean",
+            "description": "True if this is flagged as a high-risk operation."
+          },
+          "is_write": {
+            "type": "boolean",
+            "description": "True for mutating operations; false for read-only ones."
           },
           "principal_kind": {
-            "description": "Kind of the caller. `member` — an interactive member session; `service` — an app key credential.",
+            "type": "string",
             "enum": [
               "member",
               "service"
             ],
-            "type": "string"
+            "description": "Kind of the caller. `member` — a member or account-owner session; `service` — an app key or a short-lived key issued to AI SRE."
           },
-          "request_id": {
-            "description": "Unique request ID for correlation.",
-            "type": "string"
+          "credential_type": {
+            "type": "string",
+            "description": "Credential type used for the call. `app_key` for a long-lived console app key, `ephemeral_app_key` for a short-lived key issued to AI SRE, and an empty string for member sessions."
+          },
+          "credential_id": {
+            "type": "integer",
+            "format": "uint64",
+            "description": "ID of the credential (the app key ID) when `credential_type` is `app_key`; 0 otherwise."
           }
-        },
-        "required": [
-          "created_at",
-          "account_id",
-          "member_id",
-          "member_name",
-          "request_id",
-          "ip",
-          "operation",
-          "operation_name",
-          "body",
-          "params",
-          "is_dangerous",
-          "is_write",
-          "principal_kind",
-          "credential_type",
-          "credential_id"
-        ],
-        "type": "object"
+        }
       },
       "AuditOperationListRequest": {
         "additionalProperties": false,
@@ -3111,82 +3173,82 @@
         "type": "object"
       },
       "AuditRecordIDRequest": {
+        "type": "object",
+        "required": [
+          "id"
+        ],
         "properties": {
           "id": {
-            "description": "Audit record ID — the `id` of an audit row returned by `POST /monit/rule/audits`, NOT the rule ID. Passing a rule ID returns HTTP 400.",
+            "type": "integer",
             "format": "uint64",
-            "type": "integer"
+            "description": "Audit record ID — the `id` of a row returned by `POST /monit/rule/audits`, not the rule ID. A rule ID is looked up as an audit record ID, which usually returns `InvalidParameter` (`alert rule audit not found`) or an unrelated record."
           }
-        },
-        "required": [
-          "id"
-        ],
-        "type": "object"
+        }
       },
       "AuditSearchRequest": {
+        "type": "object",
         "description": "Filter criteria for audit log search. Time range is required.",
+        "required": [
+          "start_time",
+          "end_time"
+        ],
         "properties": {
+          "start_time": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Start of the search window, Unix epoch seconds. Exclusive — entries at exactly this second are not included.",
+            "example": 1712620800,
+            "minimum": 1
+          },
           "end_time": {
+            "type": "integer",
+            "format": "int64",
             "description": "End of the search window, Unix epoch seconds. Inclusive. Must be after `start_time`; maximum span 90 days.",
             "example": 1712707200,
-            "format": "int64",
-            "minimum": 1,
-            "type": "integer"
-          },
-          "is_dangerous": {
-            "description": "When true, return only high-risk (dangerous) operations.",
-            "type": [
-              "boolean",
-              "null"
-            ]
-          },
-          "is_write": {
-            "description": "When true, return only write operations; when false, return only read operations.",
-            "type": [
-              "boolean",
-              "null"
-            ]
+            "minimum": 1
           },
           "limit": {
-            "description": "Page size, 0–99. Omit or set to 0 for no page-size cap — all matching rows in the window are returned.",
-            "example": 20,
-            "maximum": 99,
+            "type": "integer",
+            "description": "Page size, 0–99. Omit or set to 0 to let the server choose the page size (it may return every matching entry).",
             "minimum": 0,
-            "type": "integer"
+            "maximum": 99,
+            "example": 20
+          },
+          "request_id": {
+            "type": "string",
+            "description": "Filter to a single request by its unique request ID."
+          },
+          "search_after_ctx": {
+            "type": "string",
+            "description": "Opaque pagination cursor returned by the previous response. Leave empty for the first page."
           },
           "operations": {
-            "description": "Filter to specific operation names. Use `POST /audit/operation/list` to get the valid set.",
+            "type": "array",
             "items": {
               "type": "string"
             },
-            "type": "array"
+            "description": "Filter to specific operation names. Use `POST /audit/operation/list` to get the valid set."
           },
           "person_id": {
-            "description": "Filter by the operator's member ID (get IDs from `POST /member/list`). Pass the account ID to match actions performed by the account principal itself.",
+            "type": "integer",
             "format": "uint64",
-            "type": "integer"
+            "description": "Filter by the operator's member ID (get IDs from `POST /member/list`). Pass the account ID to match actions performed by the account principal itself."
           },
-          "request_id": {
-            "description": "Filter to a single request by its unique request ID.",
-            "type": "string"
-          },
-          "search_after_ctx": {
-            "description": "Opaque pagination cursor returned by the previous response. Leave empty for the first page.",
-            "type": "string"
+          "is_dangerous": {
+            "type": [
+              "boolean",
+              "null"
+            ],
+            "description": "When true, return only high-risk (dangerous) operations."
           },
-          "start_time": {
-            "description": "Start of the search window, Unix epoch seconds. Exclusive — entries at exactly this second are not included.",
-            "example": 1712620800,
-            "format": "int64",
-            "minimum": 1,
-            "type": "integer"
+          "is_write": {
+            "type": [
+              "boolean",
+              "null"
+            ],
+            "description": "When true, return only write operations; when false, return only read operations."
           }
-        },
-        "required": [
-          "start_time",
-          "end_time"
-        ],
-        "type": "object"
+        }
       },
       "AuditSearchResponse": {
         "description": "Cursor-paginated audit log search result.",
@@ -3216,94 +3278,134 @@
         "type": "object"
       },
       "AutomationRuleCreateRequest": {
+        "type": "object",
         "description": "Create an Automation rule.",
         "properties": {
-          "cron_expr": {
-            "description": "Run cadence. Supports 4 fields (`hour day month weekday`, minute defaults to 0) and 5 fields (`minute hour day month weekday`). The minute must be one fixed integer; 6-field seconds are not supported. A cron that sets both day-of-month and day-of-week is rejected. The create API currently requires this field even for HTTP-POST-only rules; send a valid cron and set `schedule_trigger_enabled=false`.",
-            "example": "15 9 * * *",
-            "type": "string"
+          "name": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 255,
+            "description": "Display name of the rule, 1–255 characters; leading and trailing spaces are trimmed."
+          },
+          "team_id": {
+            "type": "integer",
+            "format": "int64",
+            "minimum": 0,
+            "description": "Scope of the rule. `0` or omitted: a personal rule owned by the caller. `>0`: a team rule; the caller must be a member of that team. The scope cannot be changed after creation."
+          },
+          "run_in": {
+            "type": "string",
+            "enum": [
+              "web",
+              "current-chat"
+            ],
+            "description": "Where the rule's runs execute. `web` (default): in a web console session. `current-chat`: in the IM chat the rule is created from; accepted only from a live IM conversation with the AI SRE agent, so API calls that send it get `400`."
           },
           "enabled": {
-            "description": "Whether the rule is enabled after creation. Omitted API value is false; Chat/CLI create sends true by default unless the user asks for disabled.",
-            "type": "boolean"
+            "type": "boolean",
+            "description": "Whether the rule's automatic triggers (schedule, HTTP POST, On-call incident, war room) are armed after creation. Defaults to `false`. Manual runs work either way."
           },
-          "environment_id": {
-            "description": "BYOC Runner ID. Used only when `environment_kind=byoc`.",
-            "type": "string"
+          "cron_expr": {
+            "type": "string",
+            "description": "Schedule in local time of `timezone`. Accepts 4 fields (`hour day month weekday`, minute defaults to 0) or 5 fields (`minute hour day month weekday`). The minute must be one fixed integer; seconds (6 fields) are not supported; setting both day-of-month and day-of-week is rejected. Required even for rules that use only other triggers: send a valid expression with `schedule_trigger_enabled=false`.",
+            "example": "15 9 * * *"
+          },
+          "timezone": {
+            "type": "string",
+            "description": "IANA time zone name used to evaluate `cron_expr`, e.g. `Asia/Shanghai`. Ambiguous names such as `Local`, `CST`, `UTC+8`, and `GMT+8` are rejected. When omitted: the caller's member time zone, then the account time zone, then `Asia/Shanghai`."
+          },
+          "schedule_trigger_enabled": {
+            "type": [
+              "boolean",
+              "null"
+            ],
+            "description": "Whether the schedule trigger is enabled. Defaults to `true` when omitted; send `false` for rules that should fire only from other triggers."
+          },
+          "prompt": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Task instruction sent to the AI SRE agent on every run. Must not be empty after trimming spaces."
           },
           "environment_kind": {
+            "type": "string",
             "description": "Runtime environment kind. Omit or send an empty value for automatic selection. One of: `cloud` (platform-hosted cloud sandbox), `byoc` (a self-hosted BYOC runner in the account, used with `environment_id`); automatic selection prefers an online BYOC runner and falls back to the cloud sandbox.",
             "enum": [
               "",
               "cloud",
               "byoc"
-            ],
-            "type": "string"
+            ]
+          },
+          "environment_id": {
+            "type": "string",
+            "description": "BYOC runner ID. Required when `environment_kind=byoc` and rejected for other kinds. A personal rule can only use account-scope runners; a team rule can use account-scope runners or runners of its own team."
           },
           "http_post_trigger_enabled": {
-            "description": "Whether to create and enable an HTTP POST trigger. When enabled, the response includes a one-time token.",
-            "type": "boolean"
+            "type": "boolean",
+            "description": "Whether to create an enabled HTTP POST trigger. When `true`, the response carries `http_post_trigger_url` and the one-time `http_post_token`."
           },
-          "name": {
-            "description": "Rule name.",
-            "maxLength": 255,
-            "minLength": 1,
-            "type": "string"
+          "oncall_incident_trigger_enabled": {
+            "type": "boolean",
+            "description": "Whether the On-call incident trigger is enabled. When the trigger is created (this is `true`, or channel IDs or severities are sent), both `oncall_incident_channel_ids` and `oncall_incident_severities` must be non-empty."
           },
           "oncall_incident_channel_ids": {
-            "description": "On-call integration IDs to watch. Creating or enabling this trigger requires at least one valid ID.",
+            "type": "array",
             "items": {
+              "type": "integer",
               "format": "int64",
-              "minimum": 1,
-              "type": "integer"
+              "minimum": 1
             },
-            "type": "array"
+            "description": "Channel IDs to watch; incidents in these channels can start a run. Each ID must be positive."
           },
           "oncall_incident_severities": {
-            "description": "Incident severities to watch. Supported values are Critical, Warning, and Info; creating or enabling this trigger requires at least one value.",
+            "type": "array",
             "items": {
+              "type": "string",
               "enum": [
                 "Critical",
                 "Warning",
                 "Info"
-              ],
-              "type": "string"
+              ]
             },
-            "type": "array"
-          },
-          "oncall_incident_trigger_enabled": {
-            "description": "Whether the On-call incident trigger is enabled.",
-            "type": "boolean"
-          },
-          "prompt": {
-            "description": "Task prompt sent to the AI SRE agent on each run.",
-            "minLength": 1,
-            "type": "string"
+            "description": "Incident severities to watch: `Critical` (most severe), `Warning`, or `Info` (least severe) — the On-call incident severity levels."
           },
-          "schedule_trigger_enabled": {
-            "description": "Whether the schedule trigger is enabled. Defaults to true when omitted; HTTP-POST-only rules should send false.",
+          "oncall_incident_merge_similar": {
             "type": [
               "boolean",
               "null"
-            ]
+            ],
+            "description": "Whether to merge similar incidents into one analysis. When `true` (default), an incident that closely resembles one already being analyzed by this rule (a run in progress or finished within the last 10 minutes) joins that run's session instead of starting a new one; its own run is recorded as `skipped` with `joined_session_id` set. When `false`, every matching incident starts its own run."
           },
-          "team_id": {
-            "description": "Scope team ID. 0 or omitted means a personal rule; >0 means a team in the account. Can be reassigned later via update (converting a team rule to personal is owner-only; moving into a team requires the caller to belong to it).",
-            "format": "int64",
-            "minimum": 0,
-            "type": "integer"
+          "war_room_trigger_enabled": {
+            "type": "boolean",
+            "description": "Whether the war room trigger is enabled. It fires when a war room (IM group chat) is created for an incident in one of `war_room_channel_ids` with a severity in `war_room_severities`; the agent then runs inside that group chat. When the trigger is created (this is `true`, or `war_room_channel_ids` is sent), both lists must be non-empty."
           },
-          "timezone": {
-            "description": "IANA timezone `cron_expr` is evaluated in, e.g. `Asia/Shanghai`. Must be a timezone name loadable by the server; an invalid value is rejected. Defaults to the caller's member timezone, then the account timezone, then the server default (Asia/Shanghai) when omitted.",
-            "type": "string"
+          "war_room_channel_ids": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "int64",
+              "minimum": 1
+            },
+            "description": "Channel IDs whose war rooms start a run. Each ID must be positive."
+          },
+          "war_room_severities": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "enum": [
+                "Critical",
+                "Warning",
+                "Info"
+              ]
+            },
+            "description": "Incident severities that start a run when their war room is created: `Critical` (most severe), `Warning`, or `Info` (least severe) — the On-call incident severity levels."
           }
         },
         "required": [
           "name",
           "cron_expr",
           "prompt"
-        ],
-        "type": "object"
+        ]
       },
       "AutomationRuleIDRequest": {
         "properties": {
@@ -3318,139 +3420,278 @@
         "type": "object"
       },
       "AutomationRuleItem": {
+        "type": "object",
         "description": "Automation rule.",
         "properties": {
+          "rule_id": {
+            "type": "string",
+            "description": "Rule ID (prefix `arule_`). Pass it as `rule_id` to get, update, delete, run, and list-runs calls."
+          },
           "account_id": {
-            "description": "Account ID.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "ID of the account that owns the rule."
           },
-          "can_edit": {
-            "description": "True when the caller can manage this rule: the personal rule owner; for team rules, an account admin or a member of the rule's team.",
-            "type": "boolean"
+          "team_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Scope team ID; `0` means a personal rule. Fixed at creation."
           },
-          "created_at": {
-            "description": "Creation time, Unix milliseconds.",
+          "owner_id": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Person ID of the member who created the rule. For a personal rule, the only person who can manage it."
           },
-          "cron_expr": {
-            "description": "Normalized 5-field cron expression.",
-            "type": "string"
+          "name": {
+            "type": "string",
+            "description": "Display name of the rule."
           },
           "enabled": {
-            "description": "Whether the rule is enabled.",
-            "type": "boolean"
+            "type": "boolean",
+            "description": "Whether the rule's automatic triggers are armed. A disabled rule can still be run manually. A personal rule is disabled automatically when its owner leaves the account."
           },
-          "environment_id": {
-            "description": "BYOC Runner ID.",
-            "type": "string"
+          "run_scope": {
+            "type": "string",
+            "enum": [
+              "person",
+              "team"
+            ],
+            "description": "Hidden session run scope. One of: `person` (personal rule, team_id=0, runs as the creator; disabled when the creator leaves the account), `team` (team rule, team_id>0, owned by the team and shared with its members; survives the creator leaving). Derived from the rule's team_id."
+          },
+          "cron_expr": {
+            "type": "string",
+            "description": "Normalized 5-field cron expression (`minute hour day month weekday`), evaluated in `timezone`."
+          },
+          "timezone": {
+            "type": "string",
+            "description": "IANA timezone `cron_expr` is evaluated in. Always populated for rules created after this field shipped; empty on legacy rows created before it, which still resolve to UTC when scheduled."
+          },
+          "prompt": {
+            "type": "string",
+            "description": "Task instruction sent to the AI SRE agent on every run."
           },
           "environment_kind": {
+            "type": "string",
             "description": "Runtime environment kind. Omit or send an empty value for automatic selection. One of: `cloud` (platform-hosted cloud sandbox), `byoc` (self-hosted BYOC runner in the account); an empty value means automatic selection (prefers an online BYOC runner, falls back to the cloud sandbox).",
             "enum": [
               "",
               "cloud",
               "byoc"
-            ],
-            "type": "string"
+            ]
           },
-          "http_post_token": {
-            "description": "HTTP POST trigger token. Returned only on create or token rotation; save it immediately.",
-            "type": "string"
+          "environment_id": {
+            "type": "string",
+            "description": "BYOC runner ID when `environment_kind=byoc`; empty string otherwise."
           },
-          "http_post_trigger_enabled": {
-            "description": "Whether the HTTP POST trigger is enabled.",
-            "type": "boolean"
+          "schedule_trigger_id": {
+            "type": "string",
+            "description": "Schedule trigger ID. Omitted if the rule has no schedule trigger."
+          },
+          "schedule_trigger_enabled": {
+            "type": "boolean",
+            "description": "Whether the schedule trigger is enabled."
           },
           "http_post_trigger_id": {
-            "description": "HTTP POST trigger ID. Omitted when the rule has no HTTP POST trigger.",
-            "type": "string"
+            "type": "string",
+            "description": "HTTP POST trigger ID. Omitted when the rule has no HTTP POST trigger."
           },
           "http_post_trigger_url": {
-            "description": "HTTP POST trigger path. Omitted when the rule has no HTTP POST trigger.",
-            "type": "string"
+            "type": "string",
+            "description": "Path to fire the HTTP POST trigger, `/safari/automation/triggers/{trigger_id}/fire`, relative to the API base URL. Send `POST` with `Authorization: Bearer <http_post_token>`. Omitted when the rule has no HTTP POST trigger."
           },
-          "name": {
-            "description": "Rule name.",
-            "type": "string"
+          "http_post_trigger_enabled": {
+            "type": "boolean",
+            "description": "Whether the HTTP POST trigger is enabled."
+          },
+          "oncall_incident_trigger_id": {
+            "type": "string",
+            "description": "On-call incident trigger ID. Omitted when the rule has no On-call incident trigger."
+          },
+          "oncall_incident_trigger_enabled": {
+            "type": "boolean",
+            "description": "Whether the On-call incident trigger is enabled."
           },
           "oncall_incident_channel_ids": {
-            "description": "On-call integration IDs to watch. Creating or enabling this trigger requires at least one valid ID. Omitted when no On-call incident trigger is configured.",
+            "type": "array",
             "items": {
+              "type": "integer",
               "format": "int64",
-              "minimum": 1,
-              "type": "integer"
+              "minimum": 1
             },
-            "type": "array"
+            "description": "Channel IDs the On-call incident trigger watches. Omitted when the rule has no such trigger."
           },
           "oncall_incident_severities": {
-            "description": "Incident severities to watch. Supported values are Critical, Warning, and Info; creating or enabling this trigger requires at least one value. Omitted when no On-call incident trigger is configured.",
+            "type": "array",
             "items": {
+              "type": "string",
               "enum": [
                 "Critical",
                 "Warning",
                 "Info"
-              ],
-              "type": "string"
+              ]
             },
-            "type": "array"
+            "description": "Incident severities the On-call incident trigger watches: `Critical` (most severe), `Warning`, or `Info` (least severe) — the On-call incident severity levels. Omitted when the rule has no such trigger."
           },
-          "oncall_incident_trigger_enabled": {
-            "description": "Whether the On-call incident trigger is enabled.",
-            "type": "boolean"
+          "oncall_incident_merge_similar": {
+            "type": "boolean",
+            "description": "Whether similar incidents are merged into one analysis (see the create request). `true` when the rule has no On-call incident trigger."
           },
-          "oncall_incident_trigger_id": {
-            "description": "On-call incident trigger ID. Omitted when the rule has no On-call incident trigger.",
-            "type": "string"
+          "war_room_trigger_id": {
+            "type": "string",
+            "description": "War room trigger ID. Omitted when the rule has no war room trigger."
           },
-          "owner_id": {
-            "description": "Creator person ID.",
-            "format": "int64",
-            "type": "integer"
+          "war_room_trigger_enabled": {
+            "type": "boolean",
+            "description": "Whether the war room trigger is enabled."
           },
-          "prompt": {
-            "description": "Task prompt.",
-            "type": "string"
+          "war_room_channel_ids": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "int64",
+              "minimum": 1
+            },
+            "description": "Channel IDs whose war rooms start a run. Omitted when the rule has no war room trigger."
           },
-          "rule_id": {
-            "description": "Rule ID.",
-            "type": "string"
+          "war_room_severities": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "enum": [
+                "Critical",
+                "Warning",
+                "Info"
+              ]
+            },
+            "description": "Incident severities whose war rooms start a run: `Critical` (most severe), `Warning`, or `Info` (least severe) — the On-call incident severity levels. Omitted when the rule has no war room trigger."
           },
-          "run_scope": {
-            "description": "Hidden session run scope. One of: `person` (personal rule, team_id=0, runs as the creator; disabled when the creator leaves the account), `team` (team rule, team_id>0, owned by the team and shared with its members; survives the creator leaving). Derived from the rule's team_id.",
+          "execution_place": {
+            "type": "string",
             "enum": [
-              "person",
-              "team"
+              "web_console",
+              "im"
             ],
-            "type": "string"
+            "description": "Where runs started by the schedule, HTTP POST, On-call incident, and manual triggers execute: `web_console` (a web console session) or `im` (the IM chat the rule was created from). War room runs always execute in the war room's group chat. Fixed at creation."
           },
-          "schedule_next_fire_at_ms": {
-            "description": "Next scheduled fire time, Unix milliseconds. 0 means no future scheduled fire is available.",
-            "format": "int64",
-            "type": "integer"
+          "execution_location": {
+            "type": "object",
+            "description": "Read-only description of where the rule runs.",
+            "properties": {
+              "place": {
+                "type": "string",
+                "enum": [
+                  "web_console",
+                  "im"
+                ],
+                "description": "Same as the rule's `execution_place`: `web_console` runs in a web console session, `im` runs in the bound IM chat."
+              },
+              "run_scope": {
+                "type": "string",
+                "enum": [
+                  "person",
+                  "team"
+                ],
+                "description": "`person`: runs as the owner; `team`: runs under the team in `team_id`."
+              },
+              "team_id": {
+                "type": "integer",
+                "format": "int64",
+                "description": "Team the runs belong to; `0` for a personal rule."
+              },
+              "platform": {
+                "type": "string",
+                "enum": [
+                  "feishu",
+                  "dingtalk",
+                  "wecom",
+                  "slack",
+                  "teams"
+                ],
+                "description": "IM platform of the bound chat: `feishu` (Feishu/Lark), `dingtalk` (DingTalk), `wecom` (WeCom), `slack` (Slack), `teams` (Microsoft Teams). Present only when `place=im`."
+              },
+              "conversation_mode": {
+                "type": "string",
+                "enum": [
+                  "direct",
+                  "group_chat",
+                  "group_thread",
+                  "war_room_chat"
+                ],
+                "description": "Conversation type of the bound chat: `direct` (one-to-one chat with the bot), `group_chat` (a group chat), `group_thread` (a thread in a group chat), `war_room_chat` (an incident war room). Present only when `place=im`."
+              },
+              "chat_name": {
+                "type": "string",
+                "description": "Name of the bound chat. Present only when `place=im` and the name is known."
+              },
+              "description": {
+                "type": "string",
+                "description": "Human-readable destination label: `Web console` for web console rules, otherwise the chat name or platform and conversation type."
+              }
+            },
+            "required": [
+              "place",
+              "run_scope",
+              "team_id",
+              "description"
+            ]
           },
-          "schedule_trigger_enabled": {
-            "description": "Whether the schedule trigger is enabled.",
-            "type": "boolean"
+          "last_run": {
+            "type": "object",
+            "description": "The rule's most recent run. Returned only by List Automation rules, and only when the rule has run at least once.",
+            "properties": {
+              "run_id": {
+                "type": "string",
+                "description": "Run ID, as in List Automation runs."
+              },
+              "status": {
+                "type": "string",
+                "enum": [
+                  "queued",
+                  "running",
+                  "retrying",
+                  "succeeded",
+                  "partial",
+                  "failed",
+                  "skipped",
+                  "abandoned",
+                  "blocked"
+                ],
+                "description": "Run status, same meanings as `status` in List Automation runs: `queued`, `running`, `retrying` (in progress); `succeeded`, `partial`, `failed`, `skipped` (did not execute or merged into another run), `abandoned` (never completed), `blocked` (ended waiting on a connector authorization)."
+              },
+              "started_at": {
+                "type": "integer",
+                "format": "int64",
+                "description": "Start time, Unix milliseconds."
+              }
+            },
+            "required": [
+              "run_id",
+              "status",
+              "started_at"
+            ]
           },
-          "schedule_trigger_id": {
-            "description": "Schedule trigger ID. Omitted if the rule has no schedule trigger.",
-            "type": "string"
+          "http_post_token": {
+            "type": "string",
+            "description": "HTTP POST trigger token. Returned only in the response that issues it: create with `http_post_trigger_enabled=true`, an update that creates the trigger, or an update with `rotate_http_post_trigger_token=true`. Save it; it cannot be read again."
           },
-          "team_id": {
-            "description": "Scope team ID; 0 means personal rule.",
-            "format": "int64",
-            "type": "integer"
+          "can_edit": {
+            "type": "boolean",
+            "description": "`true` when the caller can manage (get, update, delete, run) this rule: the owner of a personal rule, or a member of a team rule's team. Account owners and admins get no exemption."
           },
-          "timezone": {
-            "description": "IANA timezone `cron_expr` is evaluated in. Always populated for rules created after this field shipped; empty on legacy rows created before it, which still resolve to UTC when scheduled.",
-            "type": "string"
+          "created_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Creation time, Unix milliseconds."
           },
           "updated_at": {
-            "description": "Last update time, Unix milliseconds.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Last update time, Unix milliseconds."
+          },
+          "schedule_next_fire_at_ms": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Next scheduled fire time, Unix milliseconds. 0 means no future scheduled fire is available."
           }
         },
         "required": [
@@ -3472,292 +3713,310 @@
           "created_at",
           "updated_at",
           "schedule_next_fire_at_ms",
-          "oncall_incident_trigger_enabled"
-        ],
-        "type": "object"
+          "oncall_incident_trigger_enabled",
+          "oncall_incident_merge_similar",
+          "war_room_trigger_enabled",
+          "execution_place"
+        ]
       },
       "AutomationRuleListRequest": {
-        "description": "List Automation rules visible to the caller. `all` includes the caller's personal rules plus accessible team rules; account admins do not see other users' personal rules in list results.",
+        "type": "object",
+        "description": "List Automation rules visible to the caller: their own personal rules plus rules of teams they belong to. Account owners and admins are bounded the same way.",
         "properties": {
-          "enabled": {
-            "description": "Filter by enabled state: `true` returns only enabled rules, `false` only disabled; omit or pass null for no filter.",
-            "type": [
-              "boolean",
-              "null"
-            ]
-          },
-          "include_person": {
-            "description": "Compatibility field; when scope is empty and this is false, behaves like team scope.",
-            "type": [
-              "boolean",
-              "null"
-            ]
-          },
-          "keyword": {
-            "description": "Filter by name keyword.",
-            "maxLength": 64,
-            "type": "string"
+          "p": {
+            "type": "integer",
+            "default": 1,
+            "description": "Page number, 1-based."
           },
           "limit": {
+            "type": "integer",
             "default": 20,
             "description": "Page size. Values below 1 fall back to 20; values above 200 are capped at 200.",
-            "maximum": 200,
-            "type": "integer"
-          },
-          "p": {
-            "default": 1,
-            "description": "Page number, 1-based.",
-            "type": "integer"
+            "maximum": 200
           },
           "scope": {
-            "description": "Scope filter: `all` (own personal + accessible team rules), `personal`, or `team`; default `all`.",
+            "type": "string",
             "enum": [
               "all",
               "personal",
               "team"
             ],
-            "type": "string"
+            "description": "Scope filter: `all` (default) your personal rules plus rules of your teams; `personal` only your personal rules; `team` only rules of your teams."
           },
           "team_ids": {
-            "description": "Filter to these team IDs; this narrows results and does not expand access.",
+            "type": "array",
             "items": {
-              "format": "int64",
-              "type": "integer"
+              "type": "integer",
+              "format": "int64"
             },
-            "type": "array"
+            "description": "Filter to these team IDs; this narrows results and does not expand access."
+          },
+          "include_person": {
+            "type": [
+              "boolean",
+              "null"
+            ],
+            "description": "Legacy switch. Only read when `scope` is empty: `false` behaves like `scope=team`; otherwise ignored."
+          },
+          "enabled": {
+            "type": [
+              "boolean",
+              "null"
+            ],
+            "description": "Filter by enabled state: `true` returns only enabled rules, `false` only disabled; omit or pass null for no filter."
+          },
+          "keyword": {
+            "type": "string",
+            "maxLength": 64,
+            "description": "Returns rules whose name contains this text. At most 64 characters."
           }
-        },
-        "type": "object"
+        }
       },
       "AutomationRuleListResponse": {
+        "type": "object",
         "properties": {
+          "total": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Number of rules matching the filters across all pages."
+          },
           "rules": {
-            "description": "Array of automation rules for the current page, used with `total` for pagination.",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/AutomationRuleItem"
             },
-            "type": "array"
-          },
-          "total": {
-            "description": "Total count.",
-            "format": "int64",
-            "type": "integer"
+            "description": "Array of automation rules for the current page, used with `total` for pagination."
           }
         },
         "required": [
           "total",
           "rules"
-        ],
-        "type": "object"
+        ]
       },
       "AutomationRuleUpdateRequest": {
+        "type": "object",
         "description": "Update an Automation rule. Omit or send null on a field to leave it unchanged.",
         "properties": {
-          "cron_expr": {
-            "description": "Run cadence. Supports 4 fields (`hour day month weekday`, minute defaults to 0) and 5 fields (`minute hour day month weekday`). The minute must be one fixed integer; 6-field seconds are not supported.",
-            "example": "15 9 * * *",
+          "rule_id": {
+            "type": "string",
+            "description": "Target rule ID, from the list returned by `POST /safari/automation/rule/list`."
+          },
+          "name": {
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "maxLength": 255,
+            "description": "New display name, at most 255 characters. An empty string after trimming is rejected."
+          },
+          "team_id": {
+            "type": [
+              "integer",
+              "null"
+            ],
+            "format": "int64",
+            "minimum": 0,
+            "description": "The rule's scope cannot be changed. Omit this field, or send the current value; any other value returns `400`."
           },
           "enabled": {
-            "description": "Whether the rule is enabled.",
             "type": [
               "boolean",
               "null"
-            ]
+            ],
+            "description": "Whether the rule's automatic triggers are armed. Omit to keep the current value."
           },
-          "environment_id": {
-            "description": "BYOC Runner ID.",
+          "cron_expr": {
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "New schedule, same format as on create: 4 fields (`hour day month weekday`) or 5 fields (`minute hour day month weekday`), fixed-integer minute, no seconds, not both day-of-month and day-of-week. Omit to keep the current expression.",
+            "example": "15 9 * * *"
+          },
+          "timezone": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "New IANA time zone for `cron_expr`. An empty string stores `UTC`. Omit or send `null` to keep the current time zone."
+          },
+          "schedule_trigger_enabled": {
+            "type": [
+              "boolean",
+              "null"
+            ],
+            "description": "Whether the schedule trigger is enabled. Omit to keep the current value."
+          },
+          "prompt": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "New task instruction for the agent. Omit to keep the current one."
           },
           "environment_kind": {
-            "description": "Runtime environment kind. Omit or send an empty value for automatic selection.",
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "New runtime environment: `\"\"` automatic selection (prefers an online BYOC runner, falls back to the cloud sandbox), `cloud` platform-hosted cloud sandbox, `byoc` the runner in `environment_id`. Sending this without `environment_id` clears the stored `environment_id`.",
             "enum": [
               "",
               "cloud",
               "byoc"
-            ],
+            ]
+          },
+          "environment_id": {
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "BYOC runner ID; required when the resulting `environment_kind` is `byoc`, rejected otherwise."
           },
           "http_post_trigger_enabled": {
-            "description": "Whether the HTTP POST trigger is enabled. Sending true creates one when missing.",
             "type": [
               "boolean",
               "null"
-            ]
+            ],
+            "description": "Enable or disable the HTTP POST trigger. `true` on a rule without one creates it and returns its token in this response."
           },
-          "name": {
-            "description": "New rule name.",
-            "maxLength": 255,
+          "oncall_incident_trigger_enabled": {
             "type": [
-              "string",
+              "boolean",
               "null"
-            ]
+            ],
+            "description": "Enable or disable the On-call incident trigger. Creating it on a rule that has none also needs `oncall_incident_channel_ids` and `oncall_incident_severities`."
           },
           "oncall_incident_channel_ids": {
-            "description": "On-call integration IDs to watch. Creating or enabling this trigger requires at least one valid ID.",
+            "type": "array",
             "items": {
+              "type": "integer",
               "format": "int64",
-              "minimum": 1,
-              "type": "integer"
+              "minimum": 1
             },
-            "type": "array"
+            "description": "Replaces the watched channel IDs when non-empty; an empty or omitted list keeps the stored IDs."
           },
           "oncall_incident_severities": {
-            "description": "Incident severities to watch. Supported values are Critical, Warning, and Info; creating or enabling this trigger requires at least one value.",
+            "type": "array",
             "items": {
+              "type": "string",
               "enum": [
                 "Critical",
                 "Warning",
                 "Info"
-              ],
-              "type": "string"
+              ]
             },
-            "type": "array"
+            "description": "Replaces the watched severities when non-empty (`Critical` (most severe), `Warning`, or `Info` (least severe) — the On-call incident severity levels); an empty or omitted list keeps the stored values."
           },
-          "oncall_incident_trigger_enabled": {
-            "description": "Whether the On-call incident trigger is enabled.",
+          "oncall_incident_merge_similar": {
             "type": [
               "boolean",
               "null"
-            ]
-          },
-          "prompt": {
-            "description": "New task prompt.",
-            "type": [
-              "string",
-              "null"
-            ]
-          },
-          "rotate_http_post_trigger_token": {
-            "description": "Whether to rotate the HTTP POST trigger token. The new token is returned only in this response.",
-            "type": "boolean"
-          },
-          "rule_id": {
-            "description": "Target rule ID, from the list returned by `POST /safari/automation/rule/list`.",
-            "type": "string"
+            ],
+            "description": "Whether to merge similar incidents into one analysis (see the create request). Omit to keep the current value."
           },
-          "schedule_trigger_enabled": {
-            "description": "Whether the schedule trigger is enabled.",
+          "war_room_trigger_enabled": {
             "type": [
               "boolean",
               "null"
-            ]
+            ],
+            "description": "Enable or disable the war room trigger. Creating it on a rule that has none also needs `war_room_channel_ids` and `war_room_severities`. Omit to keep the current value."
           },
-          "team_id": {
-            "description": "Reassign the rule's scope: 0 converts to a personal rule (only the rule owner may convert a team rule); >0 moves it into a team the caller belongs to. Omit to leave unchanged.",
-            "format": "int64",
-            "minimum": 0,
-            "type": [
-              "integer",
-              "null"
-            ]
+          "war_room_channel_ids": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "int64",
+              "minimum": 1
+            },
+            "description": "Replaces the channel IDs whose war rooms start a run when non-empty; an empty or omitted list keeps the stored IDs."
           },
-          "timezone": {
-            "description": "New IANA timezone for evaluating `cron_expr`. Omit or send null to leave the current timezone unchanged.",
-            "type": [
-              "string",
-              "null"
-            ]
-          }
-        },
-        "required": [
-          "rule_id"
-        ],
-        "type": "object"
+          "war_room_severities": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "enum": [
+                "Critical",
+                "Warning",
+                "Info"
+              ]
+            },
+            "description": "Replaces the war room severities when non-empty (`Critical` (most severe), `Warning`, or `Info` (least severe) — the On-call incident severity levels); an empty or omitted list keeps the stored values."
+          },
+          "rotate_http_post_trigger_token": {
+            "type": "boolean",
+            "description": "When `true`, issues a new HTTP POST trigger token and invalidates the old one. The trigger must exist and be enabled. The new token is returned only in this response."
+          }
+        },
+        "required": [
+          "rule_id"
+        ]
       },
       "AutomationRunItem": {
+        "type": "object",
         "properties": {
-          "account_id": {
-            "description": "Account ID.",
-            "format": "int64",
-            "type": "integer"
-          },
-          "attempts": {
-            "description": "Attempt count.",
-            "type": "integer"
-          },
-          "completed_at": {
-            "description": "Completion time, Unix milliseconds. 0 means not completed.",
-            "format": "int64",
-            "type": "integer"
+          "run_id": {
+            "type": "string",
+            "description": "Run ID (prefix `trun_`)."
           },
-          "created_at": {
-            "description": "Creation time, Unix milliseconds.",
-            "format": "int64",
-            "type": "integer"
+          "session_id": {
+            "type": "string",
+            "description": "AI SRE session the run executed in. Omitted when the run has not started a session, when it joined another run (see `joined_session_id`), or when it executed in an IM chat."
           },
-          "duration_ms": {
-            "description": "Duration in milliseconds.",
-            "format": "int64",
-            "type": "integer"
+          "session_name": {
+            "type": "string",
+            "description": "Display name of the run's session, stamped via a batch lookup. Omitted when empty or when the lookup fails."
           },
-          "error_code": {
-            "description": "Error code; empty when the run did not fail.",
-            "type": "string"
+          "joined_session_id": {
+            "type": "string",
+            "description": "For an On-call incident run merged into a similar incident's analysis (`status=skipped`): the session it joined. Omitted otherwise."
           },
-          "error_message": {
-            "description": "Error message; empty when the run did not fail.",
-            "type": "string"
+          "joined_session_name": {
+            "type": "string",
+            "description": "Display name of `joined_session_id`. Omitted when empty or when the name lookup fails."
           },
           "kind": {
+            "type": "string",
             "description": "Run kind; runs listed for a rule are always `automation_rule`.",
             "enum": [
               "automation_rule"
-            ],
-            "type": "string"
-          },
-          "occurrence_key": {
-            "description": "Idempotency key for this occurrence.",
-            "type": "string"
-          },
-          "result_json": {
-            "additionalProperties": true,
-            "description": "Raw run result JSON (carries the run's `session_id` once started); null when empty.",
-            "type": [
-              "object",
-              "null"
             ]
           },
-          "rule_id": {
-            "description": "Rule ID.",
-            "type": "string"
-          },
-          "run_id": {
-            "description": "Run ID.",
-            "type": "string"
+          "account_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "ID of the account that owns the run."
           },
-          "session_id": {
-            "description": "Session created for this run, extracted from `result_json`. Omitted when the run has not (yet) started a session.",
-            "type": "string"
+          "rule_id": {
+            "type": "string",
+            "description": "ID of the rule this run belongs to."
           },
-          "session_name": {
-            "description": "Display name of the run's session, stamped via a batch lookup. Omitted when empty or when the lookup fails.",
-            "type": "string"
+          "trigger_kind": {
+            "type": "string",
+            "enum": [
+              "schedule",
+              "debug",
+              "manual",
+              "http_post",
+              "oncall_incident",
+              "war_room_created"
+            ],
+            "description": "Trigger kind. One of:\n| Value | Meaning |\n| --- | --- |\n| `schedule` | Fired by the rule's schedule trigger |\n| `debug` | Debug run (reserved; current rule runs never carry this kind) |\n| `manual` | Started with Run Automation rule |\n| `http_post` | Fired via the rule's HTTP POST trigger |\n| `oncall_incident` | Fired by a matching On-call incident |\n| `war_room_created` | Fired when a war room was created for a matching incident; runs in that group chat |"
           },
-          "started_at": {
-            "description": "Start time, Unix milliseconds.",
-            "format": "int64",
-            "type": "integer"
+          "execution_place": {
+            "type": "string",
+            "enum": [
+              "web_console",
+              "im"
+            ],
+            "description": "Where this run executed: `web_console` (a web console session; `session_id` links to it) or `im` (an IM chat; session details are withheld). `war_room_created` runs are always `im`."
           },
-          "stats_json": {
-            "additionalProperties": true,
-            "description": "Raw run statistics JSON; null when empty.",
-            "type": [
-              "object",
-              "null"
-            ]
+          "occurrence_key": {
+            "type": "string",
+            "description": "Idempotency key of this occurrence: `manual:<run_id>` for manual runs, `<trigger_id>:<scheduled fire time in Unix ms>` for schedule runs, `oncall_incident:<trigger_id>:<incident_id>` for On-call incident runs."
           },
           "status": {
-            "description": "Run status. One of (the first three are in-flight, the rest terminal):\n| Value | Meaning |\n| --- | --- |\n| `queued` | Enqueued, waiting for a worker |\n| `running` | Executing |\n| `retrying` | An attempt failed and a retry is scheduled |\n| `succeeded` | Completed successfully |\n| `partial` | Partially succeeded (currently only produced by memory-consolidation runs; rule runs never reach it) |\n| `failed` | Terminal failure, no further retries |\n| `skipped` | Not executed (e.g. grace period expired, trigger or rule invalid); the reason is kept on the run record |\n| `abandoned` | Still in-flight past the stale threshold and swept as never-completed (e.g. worker died) |\n| `blocked` | Terminal: the run produced output but ended with a connector waiting on a human to complete authorization (distinct from `failed`) |",
+            "type": "string",
             "enum": [
               "queued",
               "running",
@@ -3769,23 +4028,60 @@
               "abandoned",
               "blocked"
             ],
-            "type": "string"
+            "description": "Run status. One of (the first three are in-flight, the rest terminal):\n| Value | Meaning |\n| --- | --- |\n| `queued` | Enqueued, waiting for a worker |\n| `running` | Executing |\n| `retrying` | An attempt failed and a retry is scheduled |\n| `succeeded` | Completed successfully |\n| `partial` | Partially succeeded (currently only produced by memory-consolidation runs; rule runs never reach it) |\n| `failed` | Terminal failure, no further retries |\n| `skipped` | Not executed (e.g. grace period expired, trigger or rule invalid); the reason is kept on the run record. Also used for an On-call incident run merged into a similar incident's analysis (see `joined_session_id`) |\n| `abandoned` | Still in-flight past the stale threshold and swept as never-completed (e.g. worker died) |\n| `blocked` | Terminal: the run produced output but ended with a connector waiting on a human to complete authorization (distinct from `failed`) |"
           },
-          "trigger_kind": {
-            "description": "Trigger kind. One of:\n| Value | Meaning |\n| --- | --- |\n| `schedule` | Fired by the rule's schedule trigger |\n| `debug` | Debug run (reserved; current rule runs never carry this kind) |\n| `manual` | Triggered manually by a user |\n| `http_post` | Fired via the rule's HTTP POST webhook |\n| `oncall_incident` | Fired by an on-call incident event |",
-            "enum": [
-              "schedule",
-              "debug",
-              "manual",
-              "http_post",
-              "oncall_incident"
+          "attempts": {
+            "type": "integer",
+            "description": "Number of execution attempts made for this run."
+          },
+          "started_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Start time, Unix milliseconds."
+          },
+          "completed_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Completion time, Unix milliseconds. 0 means not completed."
+          },
+          "duration_ms": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Duration in milliseconds."
+          },
+          "error_code": {
+            "type": "string",
+            "description": "Error code; empty when the run did not fail."
+          },
+          "error_message": {
+            "type": "string",
+            "description": "Error message; empty when the run did not fail."
+          },
+          "stats_json": {
+            "type": [
+              "object",
+              "null"
             ],
-            "type": "string"
+            "additionalProperties": true,
+            "description": "Raw run statistics JSON; null when empty."
+          },
+          "result_json": {
+            "type": [
+              "object",
+              "null"
+            ],
+            "additionalProperties": true,
+            "description": "Raw run result JSON (carries `session_id` once a session started). `null` when empty or when the run executed in an IM chat."
+          },
+          "created_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Creation time, Unix milliseconds."
           },
           "updated_at": {
-            "description": "Last update time, Unix milliseconds.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Last update time, Unix milliseconds."
           }
         },
         "required": [
@@ -3794,6 +4090,7 @@
           "account_id",
           "rule_id",
           "trigger_kind",
+          "execution_place",
           "occurrence_key",
           "status",
           "attempts",
@@ -3806,39 +4103,27 @@
           "error_message",
           "stats_json",
           "result_json"
-        ],
-        "type": "object"
+        ]
       },
       "AutomationRunListRequest": {
+        "type": "object",
         "properties": {
-          "limit": {
-            "default": 20,
-            "description": "Page size.",
-            "type": "integer"
+          "rule_id": {
+            "type": "string",
+            "description": "Target rule ID, from the list returned by `POST /safari/automation/rule/list`."
           },
           "p": {
+            "type": "integer",
             "default": 1,
-            "description": "Page number, 1-based.",
-            "type": "integer"
-          },
-          "rule_id": {
-            "description": "Target rule ID, from the list returned by `POST /safari/automation/rule/list`.",
-            "type": "string"
-          },
-          "started_after_ms": {
-            "description": "Start-time lower bound, Unix milliseconds. Values below the 180-day run-history retention floor are clamped to it (that floor is also the default when omitted).",
-            "format": "int64",
-            "minimum": 0,
-            "type": "integer"
+            "description": "Page number, 1-based."
           },
-          "started_before_ms": {
-            "description": "Start-time upper bound, Unix milliseconds. Must be greater than or equal to the effective `started_after_ms`; a value below the retention floor yields an empty result.",
-            "format": "int64",
-            "minimum": 0,
-            "type": "integer"
+          "limit": {
+            "type": "integer",
+            "default": 20,
+            "description": "Page size. Values below 1 fall back to 20."
           },
           "status": {
-            "description": "Run status filter: `queued`, `running`, `retrying`, `succeeded`, `partial` (partially succeeded), `failed`, `skipped` (e.g. rule or trigger no longer valid), `abandoned` (stale run terminated by the system), `blocked` (terminal; produced output but a connector is waiting on a human authorization); omit for no filter.",
+            "type": "string",
             "enum": [
               "queued",
               "running",
@@ -3850,145 +4135,214 @@
               "abandoned",
               "blocked"
             ],
-            "type": "string"
+            "description": "Run status filter: `queued`, `running`, `retrying`, `succeeded`, `partial` (partially succeeded), `failed`, `skipped` (e.g. rule or trigger no longer valid), `abandoned` (stale run terminated by the system), `blocked` (terminal; produced output but a connector is waiting on a human authorization); omit for no filter."
           },
           "trigger_kind": {
-            "description": "Trigger source filter: `schedule` cron trigger, `debug` debug run, `manual` manual run, `http_post` HTTP POST trigger, `oncall_incident` on-call incident trigger; omit for no filter.",
+            "type": "string",
             "enum": [
               "schedule",
               "debug",
               "manual",
               "http_post",
-              "oncall_incident"
+              "oncall_incident",
+              "war_room_created"
             ],
-            "type": "string"
+            "description": "Trigger filter: `schedule` schedule trigger, `debug` debug run, `manual` manual run, `http_post` HTTP POST trigger, `oncall_incident` On-call incident trigger, `war_room_created` war room trigger; omit for no filter."
+          },
+          "started_after_ms": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Start-time lower bound, Unix milliseconds. Values below the 180-day run-history retention floor are clamped to it (that floor is also the default when omitted).",
+            "minimum": 0
+          },
+          "started_before_ms": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Start-time upper bound, Unix milliseconds. Must be greater than or equal to the effective `started_after_ms`; a value below the retention floor yields an empty result.",
+            "minimum": 0
           }
         },
         "required": [
           "rule_id"
-        ],
-        "type": "object"
+        ]
       },
       "AutomationRunListResponse": {
+        "type": "object",
         "properties": {
+          "total": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Number of runs matching the filters across all pages."
+          },
           "runs": {
-            "description": "Array of run records for the given `rule_id`, filtered by the request's status/trigger-kind/time-range and paginated.",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/AutomationRunItem"
             },
-            "type": "array"
-          },
-          "total": {
-            "description": "Total count.",
-            "format": "int64",
-            "type": "integer"
+            "description": "Array of run records for the given `rule_id`, filtered by the request's status/trigger-kind/time-range and paginated."
           }
         },
         "required": [
           "total",
           "runs"
-        ],
-        "type": "object"
+        ]
       },
       "AutomationRunView": {
+        "type": "object",
         "description": "Reference to the run started by a manual trigger.",
         "properties": {
           "run_id": {
-            "description": "Run ID, always populated once a run is created.",
-            "type": "string"
+            "type": "string",
+            "description": "Run ID, always populated once a run is created."
           },
           "session_id": {
-            "description": "AI SRE session ID for this run. Always populated in a 200 response, since the call only returns after the session has started.",
-            "type": "string"
+            "type": "string",
+            "description": "AI SRE session started for this run. Omitted when the rule executes in an IM chat (`execution_place=im`)."
           }
         },
         "required": [
           "run_id"
-        ],
-        "type": "object"
+        ]
       },
       "AutomationTemplateItem": {
+        "type": "object",
         "properties": {
-          "description": {
-            "description": "Template description.",
-            "type": "string"
+          "name": {
+            "type": "string",
+            "description": "Localized template name; use it as the rule `name`."
           },
-          "enabled": {
-            "description": "Whether a rule created from this template starts out enabled (prefill value).",
-            "type": "boolean"
+          "key": {
+            "type": "string",
+            "description": "Stable, locale-independent template ID (lowercase letters, digits, underscores). Present only on templates that other console pages link to directly; omitted otherwise."
+          },
+          "description": {
+            "type": "string",
+            "description": "Localized explanation of what a rule created from this template does."
           },
           "icon": {
-            "description": "Icon identifier.",
-            "type": "string"
+            "type": "string",
+            "description": "Icon identifier the console displays for the template, e.g. `siren`."
           },
-          "name": {
-            "description": "Template name.",
-            "type": "string"
+          "category": {
+            "type": "string",
+            "description": "Free-text, localized name of the group the template is shown under in the console, e.g. `Incident Response`. Groups appear in the order of their first template."
+          },
+          "enabled": {
+            "type": "boolean",
+            "description": "Prefill for the create request's `enabled`."
           },
           "prompt": {
-            "description": "Template prompt.",
-            "type": "string"
+            "type": "string",
+            "description": "Prefill for the create request's `prompt`."
+          },
+          "schedule_trigger_enabled": {
+            "type": "boolean",
+            "description": "Prefill for `schedule_trigger_enabled`; `true` exactly when `cron_expr` is present."
+          },
+          "cron_expr": {
+            "type": "string",
+            "description": "Prefill for `cron_expr`. Omitted when the template does not use the schedule trigger; the create request still needs a valid `cron_expr`."
+          },
+          "http_post_trigger_enabled": {
+            "type": "boolean",
+            "description": "Prefill for `http_post_trigger_enabled`."
+          },
+          "oncall_incident_trigger_enabled": {
+            "type": "boolean",
+            "description": "Prefill for `oncall_incident_trigger_enabled`; when `true`, add `oncall_incident_channel_ids` before creating."
+          },
+          "oncall_incident_severities": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "enum": [
+                "Critical",
+                "Warning",
+                "Info"
+              ]
+            },
+            "description": "Prefill for `oncall_incident_severities` (`Critical` (most severe), `Warning`, or `Info` (least severe) — the On-call incident severity levels). Omitted when the template does not use the On-call incident trigger."
+          },
+          "war_room_trigger_enabled": {
+            "type": "boolean",
+            "description": "Prefill for `war_room_trigger_enabled`; when `true`, add `war_room_channel_ids` before creating."
+          },
+          "war_room_severities": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "enum": [
+                "Critical",
+                "Warning",
+                "Info"
+              ]
+            },
+            "description": "Prefill for `war_room_severities` (`Critical` (most severe), `Warning`, or `Info` (least severe) — the On-call incident severity levels). Omitted when the template does not use the war room trigger."
           }
         },
         "required": [
           "name",
           "description",
           "icon",
+          "category",
           "enabled",
-          "prompt"
-        ],
-        "type": "object"
+          "prompt",
+          "schedule_trigger_enabled",
+          "http_post_trigger_enabled",
+          "oncall_incident_trigger_enabled",
+          "war_room_trigger_enabled"
+        ]
       },
       "AutomationTemplateListRequest": {
+        "type": "object",
         "properties": {
           "locale": {
-            "description": "Template locale such as zh-CN or en-US. Omit to detect from the request locale.",
+            "type": "string",
             "maxLength": 16,
-            "type": "string"
+            "description": "Template language. A value containing `zh` returns Chinese, one containing `en` returns English, any other non-empty value returns Chinese. When omitted, the `locale`/`lang` query parameter or the `Accept-Language` header decides, defaulting to Chinese."
           }
-        },
-        "type": "object"
+        }
       },
       "AutomationTemplateListResponse": {
+        "type": "object",
         "properties": {
           "templates": {
-            "description": "Array of built-in automation templates, with display text localized by the request `locale` (falling back to request headers).",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/AutomationTemplateItem"
             },
-            "type": "array"
+            "description": "Built-in templates in the resolved language, in display order."
           }
         },
         "required": [
           "templates"
-        ],
-        "type": "object"
+        ]
       },
       "BindWorkItemPostMortemRequest": {
+        "type": "object",
         "description": "Parameters for bulk-binding an incident's unbound follow-ups to a post-mortem.",
+        "required": [
+          "post_mortem_id",
+          "incident_id",
+          "idempotency_key"
+        ],
         "properties": {
-          "idempotency_key": {
-            "description": "Client-generated idempotency key (max 128 characters; letters, digits, `_`, `-`, `.`, `:` only).",
-            "maxLength": 128,
-            "pattern": "^[A-Za-z0-9_\\-.:]+$",
-            "type": "string"
+          "post_mortem_id": {
+            "type": "string",
+            "description": "Post-mortem ID (32-character hex string) to bind the follow-ups to."
           },
           "incident_id": {
-            "description": "Incident ID (MongoDB ObjectID) whose converted-but-unbound follow-ups are bound.",
+            "type": "string",
             "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
+            "description": "Incident ID (MongoDB ObjectID) whose converted, unbound items are bound. It must be linked to `post_mortem_id`."
           },
-          "post_mortem_id": {
-            "description": "Post-mortem ID (32-character hex string) to bind the follow-ups to.",
-            "type": "string"
+          "idempotency_key": {
+            "type": "string",
+            "maxLength": 128,
+            "pattern": "^[A-Za-z0-9_\\-.:]+$",
+            "description": "Client-generated idempotency key (max 128 characters; letters, digits, `_`, `-`, `.`, `:` only)."
           }
-        },
-        "required": [
-          "post_mortem_id",
-          "incident_id",
-          "idempotency_key"
-        ],
-        "type": "object"
+        }
       },
       "CalEventIDRequest": {
         "description": "Calendar event delete request. Provide event_id, or both start_at and end_at.",
@@ -4016,69 +4370,69 @@
         "type": "object"
       },
       "CalEventItem": {
+        "type": "object",
         "description": "Calendar event entry.",
+        "required": [
+          "cal_id",
+          "event_id",
+          "summary",
+          "description",
+          "start_at",
+          "end_at",
+          "is_off",
+          "created_at",
+          "updated_at"
+        ],
         "properties": {
           "account_id": {
-            "description": "Account ID. Only present for private events.",
+            "type": "integer",
             "format": "uint64",
-            "type": "integer"
+            "description": "Account ID. Only present for private events."
+          },
+          "creator_id": {
+            "type": "integer",
+            "format": "uint64",
+            "description": "Creator person ID. Only present for private events."
           },
           "cal_id": {
-            "description": "Calendar ID. For public events this is a locale key such as zh-cn.china.official.",
-            "type": "string"
+            "type": "string",
+            "description": "Calendar ID. For public events this is a locale key such as zh-cn.china.official."
           },
-          "created_at": {
-            "description": "Creation timestamp (Unix seconds).",
-            "format": "int64",
-            "type": "integer"
+          "event_id": {
+            "type": "string",
+            "description": "Event ID. `cale.<id>` for the calendar's own events, `non_work.YYYYMMDD` for generated non-working weekdays, and `<holiday cal_id>.<id>` for events inherited from a holiday calendar."
           },
-          "creator_id": {
-            "description": "Creator person ID. Only present for private events.",
-            "format": "uint64",
-            "type": "integer"
+          "summary": {
+            "type": "string",
+            "description": "Event summary."
           },
           "description": {
-            "description": "Event description.",
-            "type": "string"
+            "type": "string",
+            "description": "Event description."
           },
-          "end_at": {
-            "description": "Event end date (YYYY-MM-DD, exclusive).",
-            "type": "string"
+          "start_at": {
+            "type": "string",
+            "description": "Event start date (YYYY-MM-DD)."
           },
-          "event_id": {
-            "description": "Event ID.",
-            "type": "string"
+          "end_at": {
+            "type": "string",
+            "description": "Event end date (YYYY-MM-DD, exclusive)."
           },
           "is_off": {
-            "description": "Whether the event marks a non-working day.",
-            "type": "boolean"
-          },
-          "start_at": {
-            "description": "Event start date (YYYY-MM-DD).",
-            "type": "string"
+            "type": "boolean",
+            "description": "Whether the event marks a non-working day."
           },
-          "summary": {
-            "description": "Event summary.",
-            "type": "string"
+          "created_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Creation timestamp (Unix seconds); `0` for generated `non_work.*` entries."
           },
           "updated_at": {
-            "description": "Last update timestamp (Unix seconds).",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Last update timestamp (Unix seconds); `0` for generated `non_work.*` entries."
           }
-        },
-        "required": [
-          "cal_id",
-          "event_id",
-          "summary",
-          "description",
-          "start_at",
-          "end_at",
-          "is_off",
-          "created_at",
-          "updated_at"
-        ],
-        "type": "object"
+        }
       },
       "CalEventListRequest": {
         "description": "Calendar event list request. When day > 0 month must also be specified. month and day accept 0 to mean \"not filtered\".",
@@ -4233,50 +4587,50 @@
         "type": "object"
       },
       "CalendarCreateRequest": {
+        "type": "object",
         "description": "Create calendar request. cal_name is required.",
+        "required": [
+          "cal_name"
+        ],
         "properties": {
           "cal_name": {
-            "description": "Calendar display name.",
-            "maxLength": 39,
+            "type": "string",
+            "description": "Calendar display name; must be unique within the account.",
             "minLength": 1,
-            "type": "string"
+            "maxLength": 39
           },
           "description": {
+            "type": "string",
             "description": "Calendar description.",
-            "maxLength": 499,
-            "type": "string"
+            "maxLength": 499
           },
-          "extra_cal_ids": {
-            "description": "Additional public-holiday calendar IDs to inherit events from (for example zh-cn.china.official).",
-            "items": {
-              "type": "string"
-            },
-            "type": "array"
+          "timezone": {
+            "type": "string",
+            "description": "IANA timezone, e.g. `America/New_York`. Defaults to `Asia/Shanghai` when empty; an invalid name returns `InvalidParameter`.",
+            "default": "Asia/Shanghai"
           },
           "team_id": {
-            "description": "Owning team ID. 0 means no team.",
+            "type": "integer",
             "format": "uint64",
-            "type": "integer"
-          },
-          "timezone": {
-            "default": "Asia/Shanghai",
-            "description": "IANA timezone. Defaults to Asia/Shanghai when empty.",
-            "type": "string"
+            "description": "Owning team ID; `0` or omitted means no team. A nonzero ID must be a team of the account."
           },
           "workdays": {
-            "description": "Workday numbers (0 = Sunday, 6 = Saturday).",
+            "type": "array",
             "items": {
-              "maximum": 6,
+              "type": "integer",
               "minimum": 0,
-              "type": "integer"
+              "maximum": 6
             },
-            "type": "array"
+            "description": "Weekly working days, `0` = Sunday … `6` = Saturday. Days not listed are non-working days. When empty, no weekday is treated as non-working."
+          },
+          "extra_cal_ids": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Additional public-holiday calendar IDs to inherit events from (for example zh-cn.china.official)."
           }
-        },
-        "required": [
-          "cal_name"
-        ],
-        "type": "object"
+        }
       },
       "CalendarCreateResponse": {
         "description": "Create calendar response.",
@@ -4315,103 +4669,103 @@
         "type": "object"
       },
       "CalendarItem": {
+        "type": "object",
         "description": "Service calendar detail.",
+        "required": [
+          "account_id",
+          "team_id",
+          "cal_id",
+          "cal_name",
+          "description",
+          "timezone",
+          "kind",
+          "created_at",
+          "updated_at",
+          "creator_id",
+          "updated_by",
+          "status"
+        ],
         "properties": {
           "account_id": {
-            "description": "Account ID.",
+            "type": "integer",
             "format": "uint64",
-            "type": "integer"
+            "description": "ID of the account that owns the calendar."
+          },
+          "team_id": {
+            "type": "integer",
+            "format": "uint64",
+            "description": "Owning team ID (0 when not assigned)."
           },
           "cal_id": {
-            "description": "Calendar ID.",
-            "type": "string"
+            "type": "string",
+            "description": "Calendar ID."
           },
           "cal_name": {
-            "description": "Calendar display name.",
-            "type": "string"
-          },
-          "created_at": {
-            "description": "Creation timestamp (Unix seconds).",
-            "format": "int64",
-            "type": "integer"
-          },
-          "creator_id": {
-            "description": "Creator person ID.",
-            "format": "uint64",
-            "type": "integer"
+            "type": "string",
+            "description": "Calendar display name."
           },
           "description": {
-            "description": "Calendar description.",
-            "type": "string"
+            "type": "string",
+            "description": "Calendar description."
           },
-          "extra_cal_ids": {
-            "description": "Inherited public-holiday calendar IDs. Omitted when empty.",
-            "items": {
-              "type": "string"
-            },
-            "type": "array"
+          "timezone": {
+            "type": "string",
+            "description": "IANA timezone."
           },
           "kind": {
+            "type": "string",
             "description": "Calendar kind. `region.official.holiday` is a public regional holiday calendar (served by the central holiday service), `religion.holiday` is a public religious holiday calendar (reserved, currently no data), and `personal` is an account-created personal/team calendar.",
             "enum": [
               "region.official.holiday",
               "religion.holiday",
               "personal"
-            ],
-            "type": "string"
+            ]
           },
-          "status": {
-            "description": "Calendar status. `enabled` means usable; `deleted` means removed and never returned by list endpoints.",
-            "enum": [
-              "enabled",
-              "deleted"
-            ],
-            "type": "string"
+          "workdays": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "minimum": 0,
+              "maximum": 6
+            },
+            "description": "Weekly working days, `0` = Sunday … `6` = Saturday. Days not listed are non-working days. When empty, no weekday is treated as non-working. Omitted when empty."
           },
-          "team_id": {
-            "description": "Owning team ID (0 when not assigned).",
-            "format": "uint64",
-            "type": "integer"
+          "extra_cal_ids": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Inherited public-holiday calendar IDs. Omitted when empty."
           },
-          "timezone": {
-            "description": "IANA timezone.",
-            "type": "string"
+          "created_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Creation timestamp (Unix seconds)."
           },
           "updated_at": {
-            "description": "Last update timestamp (Unix seconds).",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Last update timestamp (Unix seconds)."
           },
-          "updated_by": {
-            "description": "Last updater person ID.",
+          "creator_id": {
+            "type": "integer",
             "format": "uint64",
-            "type": "integer"
+            "description": "Creator person ID."
           },
-          "workdays": {
-            "description": "Workday numbers (0 = Sunday, 6 = Saturday). Omitted when empty.",
-            "items": {
-              "maximum": 6,
-              "minimum": 0,
-              "type": "integer"
-            },
-            "type": "array"
+          "updated_by": {
+            "type": "integer",
+            "format": "uint64",
+            "description": "Last updater person ID."
+          },
+          "status": {
+            "type": "string",
+            "description": "Calendar status. `enabled` means usable; `deleted` means removed and never returned by list endpoints.",
+            "enum": [
+              "enabled",
+              "deleted"
+            ]
           }
-        },
-        "required": [
-          "account_id",
-          "team_id",
-          "cal_id",
-          "cal_name",
-          "description",
-          "timezone",
-          "kind",
-          "created_at",
-          "updated_at",
-          "creator_id",
-          "updated_by",
-          "status"
-        ],
-        "type": "object"
+        }
       },
       "CalendarListRequest": {
         "description": "Calendar list request. kind filters by calendar kind; no_locale disables locale filtering for public holiday calendars.",
@@ -4454,65 +4808,65 @@
         "type": "object"
       },
       "CalendarUpdateRequest": {
+        "type": "object",
         "description": "Update calendar request. cal_id is required; all other fields are optional and only applied when provided.",
+        "required": [
+          "cal_id"
+        ],
         "properties": {
           "cal_id": {
-            "description": "Calendar ID; obtain it from `POST /calendar/list`.",
-            "type": "string"
+            "type": "string",
+            "description": "Calendar ID; obtain it from `POST /calendar/list`."
           },
           "cal_name": {
-            "description": "New calendar name.",
-            "maxLength": 39,
-            "minLength": 1,
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "New calendar name; must be unique within the account.",
+            "minLength": 1,
+            "maxLength": 39
           },
           "description": {
-            "description": "New description.",
-            "maxLength": 499,
             "type": [
               "string",
               "null"
-            ]
-          },
-          "extra_cal_ids": {
-            "description": "Additional public-holiday calendar IDs to inherit events from.",
-            "items": {
-              "type": "string"
-            },
-            "type": "array"
+            ],
+            "description": "New description.",
+            "maxLength": 499
           },
-          "team_id": {
-            "description": "New owning team ID; obtain it from `POST /team/list`.",
-            "format": "uint64",
+          "timezone": {
             "type": [
-              "integer",
+              "string",
               "null"
-            ]
+            ],
+            "description": "New IANA timezone, e.g. `Asia/Shanghai`; an invalid name returns `InvalidParameter`."
           },
-          "timezone": {
-            "description": "New IANA timezone.",
+          "team_id": {
             "type": [
-              "string",
+              "integer",
               "null"
-            ]
+            ],
+            "format": "uint64",
+            "description": "New owning team ID; obtain it from `POST /team/list`. `0` removes the team; a nonzero ID must be a team of the account."
           },
           "workdays": {
-            "description": "Workday numbers (0 = Sunday, 6 = Saturday).",
+            "type": "array",
             "items": {
-              "maximum": 6,
+              "type": "integer",
               "minimum": 0,
-              "type": "integer"
+              "maximum": 6
             },
-            "type": "array"
+            "description": "Weekly working days, `0` = Sunday … `6` = Saturday. Days not listed are non-working days. When empty, no weekday is treated as non-working. When sent, replaces the stored list; omit to keep it."
+          },
+          "extra_cal_ids": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Public holiday calendar IDs to inherit events from (see `POST /calendar/list` with `kind` = `region.official.holiday`). When sent, replaces the stored list; an empty array removes them all; omit to keep it."
           }
-        },
-        "required": [
-          "cal_id"
-        ],
-        "type": "object"
+        }
       },
       "CancelStatusPageMigrationRequest": {
         "description": "Parameters for cancelling an in-progress migration job.",
@@ -4528,17 +4882,41 @@
         "type": "object"
       },
       "ChangeEventItem": {
+        "type": "object",
         "properties": {
+          "event_id": {
+            "type": "string",
+            "description": "Change event ID, a MongoDB ObjectID hex string."
+          },
           "account_id": {
+            "type": "integer",
             "description": "Account this change event belongs to.",
-            "format": "int64",
-            "type": "integer"
+            "format": "int64"
+          },
+          "channel_id": {
+            "type": "integer",
+            "description": "Collaboration channel this change event is routed to.",
+            "format": "int64"
+          },
+          "integration_id": {
+            "type": "integer",
+            "description": "Integration that reported this change event.",
+            "format": "int64"
+          },
+          "title": {
+            "type": "string",
+            "description": "Change event title."
+          },
+          "description": {
+            "type": "string",
+            "description": "Change event description."
           },
           "change_key": {
-            "description": "Stable key that groups events belonging to the same change.",
-            "type": "string"
+            "type": "string",
+            "description": "Stable key that groups events belonging to the same change."
           },
           "change_status": {
+            "type": "string",
             "description": "Lifecycle status of the change event, reported by the change source as execution progresses.\n| Value | Meaning |\n|---|---|\n| `Planned` | Planned, not started. |\n| `Ready` | Ready for execution. |\n| `Processing` | Being executed. |\n| `Canceled` | Canceled. |\n| `Done` | Completed. |\n| `Failed` | Failed. |",
             "enum": [
               "Planned",
@@ -4547,81 +4925,112 @@
               "Canceled",
               "Done",
               "Failed"
-            ],
-            "type": "string"
-          },
-          "channel_id": {
-            "description": "Collaboration channel this change event is routed to.",
-            "format": "int64",
-            "type": "integer"
-          },
-          "created_at": {
-            "description": "Unix timestamp in seconds when the change event was created.",
-            "format": "int64",
-            "type": "integer"
-          },
-          "deleted_at": {
-            "description": "Unix timestamp in seconds when the change event was deleted. Omitted when not deleted.",
-            "format": "int64",
-            "type": "integer"
-          },
-          "description": {
-            "description": "Change event description.",
-            "type": "string"
+            ]
           },
-          "event_id": {
-            "description": "Change event ID, a MongoDB ObjectID hex string.",
-            "type": "string"
+          "link": {
+            "type": "string",
+            "description": "External link to the source change record."
           },
           "event_time": {
-            "description": "Unix timestamp in seconds when the change event occurred.",
-            "format": "int64",
-            "type": "integer"
-          },
-          "integration_id": {
-            "description": "Integration that reported this change event.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Unix timestamp in seconds when the change event occurred."
           },
           "labels": {
+            "type": [
+              "object",
+              "null"
+            ],
             "additionalProperties": {
               "type": "string"
             },
-            "description": "Key-value labels attached to the change event.",
-            "type": "object"
-          },
-          "link": {
-            "description": "External link to the source change record.",
-            "type": "string"
+            "description": "Key-value labels attached to the change event."
           },
-          "title": {
-            "description": "Change event title.",
-            "type": "string"
+          "created_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Unix timestamp in seconds when the change event was created."
           },
           "updated_at": {
-            "description": "Unix timestamp in seconds when the change event was last updated.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Unix timestamp in seconds when the change event was last updated."
+          },
+          "deleted_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Unix timestamp in seconds when the change event was deleted. Omitted when not deleted."
           }
         },
-        "type": "object"
+        "required": [
+          "event_id",
+          "account_id",
+          "channel_id",
+          "integration_id",
+          "title",
+          "description",
+          "change_key",
+          "change_status",
+          "link",
+          "event_time",
+          "labels",
+          "created_at",
+          "updated_at"
+        ]
       },
       "ChangeItem": {
+        "type": "object",
         "properties": {
+          "change_id": {
+            "type": "string",
+            "description": "Change ID, a MongoDB ObjectID hex string."
+          },
           "account_id": {
+            "type": "integer",
             "description": "Account this change belongs to.",
-            "format": "int64",
-            "type": "integer"
+            "format": "int64"
           },
-          "change_id": {
-            "description": "Change ID, a MongoDB ObjectID hex string.",
-            "type": "string"
+          "channel_id": {
+            "type": "integer",
+            "description": "Collaboration channel this change is routed to.",
+            "format": "int64"
+          },
+          "channel_name": {
+            "type": "string",
+            "description": "Name of the collaboration channel; an empty string when the change is not routed to an existing channel."
+          },
+          "channel_status": {
+            "type": "string",
+            "description": "Status of the collaboration channel: `enabled` or `disabled`; an empty string when the change is not routed to an existing channel.",
+            "enum": [
+              "enabled",
+              "disabled",
+              ""
+            ]
+          },
+          "integration_id": {
+            "type": "integer",
+            "description": "Integration that reported this change.",
+            "format": "int64"
+          },
+          "integration_name": {
+            "type": "string",
+            "description": "Name of the reporting integration."
+          },
+          "title": {
+            "type": "string",
+            "description": "Change title."
+          },
+          "description": {
+            "type": "string",
+            "description": "Change description."
           },
           "change_key": {
-            "description": "Stable key that groups events belonging to the same change.",
-            "type": "string"
+            "type": "string",
+            "description": "Stable key that groups events belonging to the same change."
           },
           "change_status": {
+            "type": "string",
             "description": "Current lifecycle status of the change.\n| Value | Meaning |\n|---|---|\n| `Planned` | Planned, not started. |\n| `Ready` | Ready for execution. |\n| `Processing` | Being executed. |\n| `Canceled` | Canceled. |\n| `Done` | Completed. |\n| `Failed` | Failed. |",
             "enum": [
               "Planned",
@@ -4630,100 +5039,85 @@
               "Canceled",
               "Done",
               "Failed"
-            ],
-            "type": "string"
+            ]
           },
-          "channel_id": {
-            "description": "Collaboration channel this change is routed to.",
+          "start_time": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
-          },
-          "channel_name": {
-            "description": "Name of the collaboration channel.",
-            "type": "string"
-          },
-          "channel_status": {
-            "description": "Status of the collaboration channel: `enabled` or `disabled`.",
-            "enum": [
-              "enabled",
-              "disabled"
-            ],
-            "type": "string"
+            "description": "Unix timestamp in seconds when the change started."
           },
-          "description": {
-            "description": "Change description.",
-            "type": "string"
-          },
-          "end_time": {
-            "description": "Unix timestamp in seconds when the change ended.",
+          "last_time": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
-          },
-          "events": {
-            "description": "Underlying change events, returned only when include_events is true.",
-            "items": {
-              "$ref": "#/components/schemas/ChangeEventItem"
-            },
-            "type": "array"
+            "description": "Unix timestamp in seconds of the most recent change activity."
           },
-          "integration_id": {
-            "description": "Integration that reported this change.",
+          "end_time": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
-          },
-          "integration_name": {
-            "description": "Name of the reporting integration.",
-            "type": "string"
+            "description": "Unix timestamp in seconds when the change ended."
           },
           "labels": {
+            "type": [
+              "object",
+              "null"
+            ],
             "additionalProperties": {
               "type": "string"
             },
-            "description": "Key-value labels attached to the change.",
-            "type": "object"
-          },
-          "last_time": {
-            "description": "Unix timestamp in seconds of the most recent change activity.",
-            "format": "int64",
-            "type": "integer"
+            "description": "Key-value labels attached to the change; `null` when it has none."
           },
           "link": {
-            "description": "External link to the source change record.",
-            "type": "string"
-          },
-          "start_time": {
-            "description": "Unix timestamp in seconds when the change started.",
-            "format": "int64",
-            "type": "integer"
+            "type": "string",
+            "description": "External link to the source change record."
           },
-          "title": {
-            "description": "Change title.",
-            "type": "string"
+          "events": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/ChangeEventItem"
+            },
+            "description": "Raw change events reported by the integration that make up this change. Present only when `include_events` is `true`."
           }
         },
-        "type": "object"
+        "required": [
+          "change_id",
+          "account_id",
+          "channel_id",
+          "channel_name",
+          "channel_status",
+          "integration_id",
+          "integration_name",
+          "title",
+          "description",
+          "change_key",
+          "change_status",
+          "start_time",
+          "last_time",
+          "end_time",
+          "labels",
+          "link"
+        ]
       },
       "ChannelCreateResponse": {
+        "type": "object",
+        "required": [
+          "channel_id",
+          "channel_name"
+        ],
         "properties": {
           "channel_id": {
-            "description": "Newly created channel ID.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Newly created channel ID."
           },
           "channel_name": {
-            "description": "Channel name echoed back from the request.",
-            "type": "string"
+            "type": "string",
+            "description": "Channel name echoed back from the request."
           },
           "external_report_token": {
-            "description": "External report token. Emitted only when external reporting is enabled.",
-            "type": "string"
+            "type": "string",
+            "description": "Token for external reporters. Returned only when the request set `is_external_report_enabled` to `true`; it can be read again later from `POST /channel/info`."
           }
-        },
-        "required": [
-          "channel_id",
-          "channel_name"
-        ],
-        "type": "object"
+        }
       },
       "ChannelIDRequest": {
         "properties": {
@@ -4769,219 +5163,219 @@
         "type": "object"
       },
       "ChannelInfosResponse": {
+        "type": "object",
+        "required": [
+          "items"
+        ],
         "properties": {
           "items": {
-            "description": "Brief info for the requested `channel_ids` that actually exist; IDs not found are ignored.",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/ChannelShort"
             },
-            "type": "array"
+            "description": "Requested channels that exist, including deleted ones; unknown IDs are skipped. Ordered by channel creation, not by request order."
           }
-        },
-        "required": [
-          "items"
-        ],
-        "type": "object"
+        }
       },
       "ChannelItem": {
+        "type": "object",
         "description": "Channel detail record. All fields are optional; they are emitted only when populated.",
         "properties": {
-          "account_id": {
-            "description": "Owning account ID.",
-            "format": "int64",
-            "type": "integer"
-          },
-          "active_incident_highest_severity": {
-            "description": "Highest severity among the channel's active (triggered or processing) incidents: `Critical`, `Warning` or `Info`. Omitted when there are no active incidents.",
-            "enum": [
-              "Critical",
-              "Warning",
-              "Info"
-            ],
-            "type": "string"
-          },
-          "auto_resolve_mode": {
-            "description": "How the auto-resolve timer is reset. `trigger` (default) starts the timer once when the incident is triggered — later merged alerts do not affect it; `update` restarts the timer from the latest alert time whenever a new alert merges into the incident.",
-            "enum": [
-              "trigger",
-              "update"
-            ],
-            "type": "string"
-          },
-          "auto_resolve_timeout": {
-            "description": "Auto-resolve timeout in seconds. 0 disables auto-resolve.",
+          "channel_id": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Channel ID; pass it as `channel_id` to the other channel and rule endpoints."
           },
-          "channel_id": {
-            "description": "Channel ID.",
+          "team_id": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Owning team ID."
           },
-          "channel_name": {
-            "description": "Channel name.",
-            "type": "string"
+          "team_name": {
+            "type": "string",
+            "description": "Owning team name, resolved from the team directory. Returned only by `POST /channel/list` without `is_brief`; omitted when the lookup fails."
           },
-          "created_at": {
-            "description": "Creation time, Unix timestamp in seconds.",
-            "format": "int64",
-            "type": "integer"
+          "managing_team_ids": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "int64"
+            },
+            "description": "Additional teams that can manage the channel."
           },
           "creator_id": {
-            "description": "Member ID who created the channel.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Member ID who created the channel."
           },
           "creator_name": {
-            "description": "Name of the member who created the channel (resolved from the member directory; empty when unavailable).",
-            "type": "string"
+            "type": "string",
+            "description": "Name of the member who created the channel. Returned only by `POST /channel/list` without `is_brief`; omitted when the lookup fails."
           },
-          "deleted_at": {
-            "description": "Deletion time, Unix timestamp in seconds. Non-zero only for soft-deleted channels.",
+          "account_id": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Owning account ID."
           },
-          "description": {
-            "description": "Free-form description.",
-            "type": "string"
+          "channel_name": {
+            "type": "string",
+            "description": "Channel name, unique within the account, 1–59 characters."
           },
-          "disable_auto_close": {
-            "description": "When true, automatic incident closing is disabled.",
-            "type": "boolean"
+          "description": {
+            "type": "string",
+            "description": "Free-form description."
           },
-          "disable_outlier_detection": {
-            "description": "When true, outlier incident detection is disabled.",
-            "type": "boolean"
+          "status": {
+            "type": "string",
+            "enum": [
+              "enabled",
+              "disabled",
+              "deleted"
+            ],
+            "description": "Channel status:\n- `enabled`: incoming alert events are processed.\n- `disabled`: incoming alert events are discarded.\n- `deleted`: the channel was deleted; returned only by `POST /channel/info` and `POST /channel/infos`, never by `POST /channel/list`."
           },
-          "event_group": {
-            "$ref": "#/components/schemas/EventGroup",
-            "description": "Alert event merge configuration."
+          "deleted_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Deletion time, Unix timestamp in seconds. Non-zero only for soft-deleted channels."
           },
-          "external_report_token": {
-            "description": "Token granted to external reporters. Omitted unless external reporting is enabled on the channel.",
-            "type": "string"
+          "created_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Creation time, Unix timestamp in seconds."
           },
-          "flapping": {
-            "$ref": "#/components/schemas/Flapping",
-            "description": "Flapping detection configuration."
+          "updated_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Last update time, Unix timestamp in seconds."
           },
-          "group": {
-            "$ref": "#/components/schemas/Group",
-            "description": "Alert grouping configuration."
+          "auto_resolve_timeout": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Auto-resolve timeout in seconds. 0 disables auto-resolve."
           },
-          "is_external_report_enabled": {
-            "description": "Whether external reporters can file incidents into this channel.",
-            "type": "boolean"
+          "auto_resolve_mode": {
+            "type": "string",
+            "enum": [
+              "trigger",
+              "update"
+            ],
+            "description": "How the auto-resolve timer is reset. `trigger` (default) starts the timer once when the incident is triggered — later merged alerts do not affect it; `update` restarts the timer from the latest alert time whenever a new alert merges into the incident."
           },
           "is_private": {
-            "description": "When true, the channel is visible only to its managing teams.",
-            "type": "boolean"
+            "type": "boolean",
+            "description": "When true, the channel is visible only to its managing teams."
           },
-          "is_starred": {
-            "description": "Whether the current user has starred this channel. Present only in `POST /channel/list` responses.",
-            "type": "boolean"
+          "disable_outlier_detection": {
+            "type": "boolean",
+            "description": "When true, outlier incident detection is disabled."
           },
-          "last_incident_at": {
-            "description": "Time of the most recent incident, Unix timestamp in seconds.",
-            "format": "int64",
-            "type": "integer"
+          "disable_auto_close": {
+            "type": "boolean",
+            "description": "When true, automatic incident closing is disabled."
           },
-          "managing_team_ids": {
-            "description": "Additional teams that can manage the channel.",
-            "items": {
-              "format": "int64",
-              "type": "integer"
-            },
-            "type": "array"
+          "group": {
+            "$ref": "#/components/schemas/Group",
+            "description": "Alert grouping configuration. When never set, `{\"method\": \"n\"}` (no grouping) is returned."
+          },
+          "flapping": {
+            "$ref": "#/components/schemas/Flapping",
+            "description": "Flapping detection configuration. When never set, the defaults are returned: enabled, 4 changes within 60 minutes, muted for 120 minutes."
           },
           "progress_to_incident_cnts": {
             "$ref": "#/components/schemas/IncProgressCnts",
-            "description": "Incident counts by progress over the last 30 days."
+            "description": "Counts of incidents started in the last 30 days that are still open, by progress. Not returned with `is_brief`."
           },
-          "status": {
-            "description": "Channel status. `enabled` receives and processes events normally; `disabled` drops incoming events outright; `deleted` is returned only when fetching a channel by ID — list endpoints never return it.",
+          "is_starred": {
+            "type": "boolean",
+            "description": "Whether the caller has starred this channel. Returned only by `POST /channel/list`."
+          },
+          "active_incident_highest_severity": {
+            "type": "string",
             "enum": [
-              "enabled",
-              "disabled",
-              "deleted"
+              "Critical",
+              "Warning",
+              "Info"
             ],
-            "type": "string"
+            "description": "Highest severity among the channel's active (triggered or processing) incidents: `Critical`, `Warning` or `Info`. Omitted when there are no active incidents."
           },
-          "team_id": {
-            "description": "Owning team ID.",
+          "last_incident_at": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Time of the most recent incident, Unix timestamp in seconds."
           },
-          "team_name": {
-            "description": "Owning team name (resolved from the team directory; empty when unavailable).",
-            "type": "string"
+          "is_external_report_enabled": {
+            "type": "boolean",
+            "description": "Whether external reporters can file incidents into this channel."
           },
-          "updated_at": {
-            "description": "Last update time, Unix timestamp in seconds.",
-            "format": "int64",
-            "type": "integer"
+          "external_report_token": {
+            "type": "string",
+            "description": "Token external reporters use to file incidents into this channel. Returned only when external reporting is enabled."
+          },
+          "event_group": {
+            "$ref": "#/components/schemas/EventGroup",
+            "description": "Alert event merge configuration. When never set, merging is enabled with a 1,440-minute window."
           }
-        },
-        "type": "object"
+        }
       },
       "ChannelRuleIDRequest": {
+        "type": "object",
+        "required": [
+          "channel_id",
+          "rule_id"
+        ],
         "properties": {
           "channel_id": {
-            "description": "Owning channel ID; obtain it from `POST /channel/list`.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Owning channel ID; obtain it from `POST /channel/list`."
           },
           "rule_id": {
-            "description": "Rule ID (MongoDB ObjectID).",
+            "type": "string",
             "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
+            "description": "Rule ID (24-character hex), as returned in `rule_id` by the create or list endpoint of the same rule type."
           }
-        },
-        "required": [
-          "channel_id",
-          "rule_id"
-        ],
-        "type": "object"
+        }
       },
       "ChannelScopedListRequest": {
+        "type": "object",
+        "required": [
+          "channel_id"
+        ],
         "properties": {
           "channel_id": {
-            "description": "Channel to list rules for.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Channel whose rules to list; obtain it from `POST /channel/list`."
           }
-        },
-        "required": [
-          "channel_id"
-        ],
-        "type": "object"
+        }
       },
       "ChannelShort": {
+        "type": "object",
+        "required": [
+          "channel_id",
+          "channel_name"
+        ],
         "properties": {
           "channel_id": {
-            "description": "Channel ID.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Channel ID, one of the requested `channel_ids`."
           },
           "channel_name": {
-            "description": "Channel name.",
-            "type": "string"
+            "type": "string",
+            "description": "Channel name, unique within the account."
           },
           "status": {
-            "description": "Channel status: `enabled` processes events normally; `disabled` discards incoming events; `deleted` is soft-deleted.",
+            "type": "string",
             "enum": [
               "enabled",
               "disabled",
               "deleted"
             ],
-            "type": "string"
+            "description": "Channel status:\n- `enabled`: incoming alert events are processed.\n- `disabled`: incoming alert events are discarded.\n- `deleted`: the channel was deleted."
           }
-        },
-        "required": [
-          "channel_id",
-          "channel_name"
-        ],
-        "type": "object"
+        }
       },
       "CommentIncidentRequest": {
         "description": "Parameters for adding a comment to one or more incidents.",
@@ -5057,716 +5451,338 @@
         "type": "object"
       },
       "ContextResolvedItem": {
-        "description": "Snapshot of the three-tier knowledge resolution for this session.",
+        "type": "object",
+        "description": "Knowledge versions the session's context resolved. In `POST /safari/session/get` only `versions` is filled (with `resolved_at_ms` = 0); the object is omitted until the agent has resolved knowledge at least once.",
         "properties": {
           "account_pack_id": {
-            "description": "Resolved account-scope knowledge ID.",
-            "type": "string"
+            "type": "string",
+            "description": "Resolved account-scope knowledge ID."
+          },
+          "team_pack_id": {
+            "type": "string",
+            "description": "Resolved team-scope knowledge ID."
           },
           "incident_id": {
-            "description": "Bound incident id, when war-room originated.",
-            "type": "string"
+            "type": "string",
+            "description": "Bound incident id, when war-room originated."
           },
           "resolved_at_ms": {
-            "description": "Unix timestamp in milliseconds when the knowledge was resolved.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
-          },
-          "team_pack_id": {
-            "description": "Resolved team-scope knowledge ID.",
-            "type": "string"
+            "description": "Unix timestamp in milliseconds when the knowledge was resolved."
           },
           "versions": {
+            "type": "object",
             "additionalProperties": {
               "type": "integer"
             },
-            "description": "Resolved version map, one entry per knowledge.",
-            "type": "object"
+            "description": "Map from knowledge ID to the version the agent last loaded."
           }
         },
         "required": [
           "resolved_at_ms"
-        ],
-        "type": "object"
+        ]
       },
       "ConvertWorkItemRequest": {
+        "type": "object",
         "description": "Parameters for converting an action item into a post-mortem follow-up in place.",
+        "required": [
+          "work_item_id",
+          "version",
+          "idempotency_key"
+        ],
         "properties": {
-          "idempotency_key": {
-            "description": "Client-generated idempotency key (max 128 characters; letters, digits, `_`, `-`, `.`, `:` only).",
+          "work_item_id": {
+            "type": "string",
             "maxLength": 128,
-            "pattern": "^[A-Za-z0-9_\\-.:]+$",
-            "type": "string"
+            "description": "Work item ID (opaque string, max 128 characters)."
+          },
+          "version": {
+            "type": "integer",
+            "format": "int64",
+            "description": "The item's current `version` (≥ 1) for optimistic locking."
           },
           "target_status": {
-            "description": "Optional status to set on the converted follow-up. One of `open`, `in_progress`, `done`, `cancelled`.",
+            "type": [
+              "string",
+              "null"
+            ],
             "enum": [
               "open",
               "in_progress",
               "done",
-              "cancelled"
+              "cancelled",
+              null
             ],
             "maxLength": 64,
-            "type": [
-              "string",
-              "null"
-            ]
-          },
-          "version": {
-            "description": "Current item version for optimistic locking. Must match the stored version.",
-            "format": "int64",
-            "type": "integer"
+            "description": "Optional status to set on the converted follow-up; omitted or `null` keeps the current status. Values: `open` (not started), `in_progress` (being worked on), `done` (finished), `cancelled` (no longer needed)."
           },
-          "work_item_id": {
-            "description": "Work item ID (opaque string, max 128 characters).",
+          "idempotency_key": {
+            "type": "string",
             "maxLength": 128,
-            "type": "string"
+            "pattern": "^[A-Za-z0-9_\\-.:]+$",
+            "description": "Client-generated idempotency key (max 128 characters; letters, digits, `_`, `-`, `.`, `:` only)."
           }
-        },
-        "required": [
-          "work_item_id",
-          "version",
-          "idempotency_key"
-        ],
-        "type": "object"
+        }
       },
       "CreateChannelRequest": {
+        "type": "object",
         "description": "Parameters for creating a channel.",
+        "required": [
+          "team_id",
+          "channel_name"
+        ],
         "properties": {
-          "auto_resolve_mode": {
-            "description": "Auto-resolve timing mode: `trigger` starts the timer when the incident triggers, `update` restarts it on every alert update.",
-            "enum": [
-              "trigger",
-              "update"
-            ],
-            "type": "string"
-          },
-          "auto_resolve_timeout": {
-            "description": "Auto-resolve timeout in seconds. 0 disables auto-resolve. Max 30 days.",
+          "team_id": {
+            "type": "integer",
             "format": "int64",
-            "maximum": 2592000,
-            "minimum": 0,
-            "type": "integer"
+            "description": "Owning team ID; obtain it from `POST /team/list`. Required and must exist."
+          },
+          "managing_team_ids": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "int64"
+            },
+            "maxItems": 3,
+            "description": "Additional teams that can manage the channel. Up to 3 entries."
           },
           "channel_name": {
-            "description": "Channel name. 1 to 59 characters.",
-            "maxLength": 59,
+            "type": "string",
             "minLength": 1,
-            "type": "string"
+            "maxLength": 59,
+            "description": "Channel name, 1–59 characters, unique within the account."
           },
           "description": {
-            "description": "Free-form description. Up to 500 characters.",
+            "type": "string",
             "maxLength": 500,
-            "type": "string"
-          },
-          "disable_auto_close": {
-            "description": "Disable automatic incident closing.",
-            "type": "boolean"
-          },
-          "disable_outlier_detection": {
-            "description": "Disable outlier incident detection.",
-            "type": "boolean"
+            "description": "Free-form description. Up to 500 characters."
           },
           "escalate_rule": {
-            "description": "Default escalation rule applied to the channel. Omit to skip default escalation.",
-            "properties": {
-              "aggr_window": {
-                "description": "Delay window in seconds. 0 disables delay.",
-                "maximum": 3600,
-                "minimum": 0,
-                "type": "integer"
-              },
-              "target": {
-                "description": "Notification target. At least one of `person_ids`, `team_ids`, `schedule_to_role_ids`, or `emails` must be set, together with either `by` or `webhooks`.",
-                "properties": {
-                  "by": {
-                    "description": "Per-severity personal notification channels. Required unless `webhooks` is provided.",
-                    "properties": {
-                      "critical": {
-                        "description": "Notify channels used for Critical severity. Personal channels: `sms`, `voice`, `email`, `push`; IM group-chat channels: `feishu_app:<chat_id>`, `dingtalk_app:<chat_id>`, `wecom_app:<chat_id>`, `slack_app:<chat_id>`, `teams_app:<chat_id>`.",
-                        "items": {
-                          "type": "string"
-                        },
-                        "type": "array"
-                      },
-                      "follow_preference": {
-                        "description": "When true, use each responder's personal preference instead of the lists below.",
-                        "type": "boolean"
-                      },
-                      "info": {
-                        "description": "Notify channels used for Info severity. Values as for `critical`.",
-                        "items": {
-                          "type": "string"
-                        },
-                        "type": "array"
-                      },
-                      "warning": {
-                        "description": "Notify channels used for Warning severity. Values as for `critical`.",
-                        "items": {
-                          "type": "string"
-                        },
-                        "type": "array"
-                      }
-                    },
-                    "type": "object"
-                  },
-                  "emails": {
-                    "description": "Email addresses to notify (push-only scenarios).",
-                    "items": {
-                      "format": "email",
-                      "type": "string"
-                    },
-                    "type": "array"
-                  },
-                  "person_ids": {
-                    "description": "Member IDs to notify directly; obtain member IDs from `POST /member/list`.",
-                    "items": {
-                      "format": "int64",
-                      "type": "integer"
-                    },
-                    "type": "array"
-                  },
-                  "schedule_to_role_ids": {
-                    "additionalProperties": {
-                      "items": {
-                        "format": "int64",
-                        "type": "integer"
-                      },
-                      "type": "array"
-                    },
-                    "description": "Map of schedule ID to the role IDs on that schedule to notify.",
-                    "type": "object"
-                  },
-                  "team_ids": {
-                    "description": "Team IDs to notify; obtain team IDs from `POST /team/list`.",
-                    "items": {
-                      "format": "int64",
-                      "type": "integer"
-                    },
-                    "type": "array"
-                  },
-                  "webhooks": {
-                    "description": "Group chat / webhook targets. Required unless `by` is provided.",
-                    "items": {
-                      "properties": {
-                        "settings": {
-                          "additionalProperties": true,
-                          "description": "Type-specific settings (chat IDs, URLs, etc.).",
-                          "type": "object"
-                        },
-                        "type": {
-                          "description": "Webhook type, one of `feishu`, `feishu_app`, `dingtalk`, `dingtalk_app`, `wecom`, `slack`, `slack_app`, `teams_app`, `telegram`, `zoom`.",
-                          "type": "string"
-                        }
-                      },
-                      "required": [
-                        "type",
-                        "settings"
-                      ],
-                      "type": "object"
-                    },
-                    "type": "array"
-                  }
-                },
-                "type": "object"
-              },
-              "template_id": {
-                "description": "Notification template ID (MongoDB ObjectID).",
-                "pattern": "^[0-9a-fA-F]{24}$",
-                "type": "string"
-              }
-            },
+            "type": "object",
+            "description": "Creates an enabled escalation rule named `Default` with a single level that notifies `target` once. Omit to create the channel without escalation rules.",
             "required": [
               "template_id",
               "target"
             ],
-            "type": "object"
-          },
-          "event_group": {
-            "$ref": "#/components/schemas/EventGroup",
-            "description": "Alert event merge configuration. Omit to use the default (merge enabled, 1440-minute window)."
-          },
-          "flapping": {
-            "description": "Flapping detection configuration.",
             "properties": {
-              "in_mins": {
-                "description": "Observation window in minutes.",
-                "maximum": 1440,
-                "minimum": 1,
-                "type": "integer"
-              },
-              "is_disabled": {
-                "description": "Disable flapping detection.",
-                "type": "boolean"
+              "aggr_window": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 3600,
+                "description": "Delay in seconds, 0–3600, before the first notification for a newly assigned incident; `0` notifies immediately."
               },
-              "max_changes": {
-                "description": "Max state changes allowed within `in_mins`.",
-                "maximum": 100,
-                "minimum": 2,
-                "type": "integer"
+              "template_id": {
+                "type": "string",
+                "pattern": "^[0-9a-fA-F]{24}$",
+                "description": "Notification template ID (24-character hex); obtain it from `POST /template/list`. Must exist."
               },
-              "mute_mins": {
-                "description": "Mute duration in minutes after flapping is detected.",
-                "maximum": 1440,
-                "minimum": 0,
-                "type": "integer"
+              "target": {
+                "$ref": "#/components/schemas/EscalateTarget",
+                "description": "Who to notify and through which channels."
               }
-            },
-            "type": "object"
+            }
           },
           "group": {
-            "description": "Alert grouping configuration.",
-            "properties": {
-              "all_equals_required": {
-                "description": "When true, all listed keys must be present for grouping.",
-                "type": "boolean"
-              },
-              "cases": {
-                "description": "Per-filter grouping overrides.",
-                "items": {
-                  "description": "Conditional grouping override: stored alerts matching `if` are grouped by `equals` instead of the top-level grouping keys.",
-                  "properties": {
-                    "equals": {
-                      "description": "Grouping keys for matching alerts. Supported values: `title`, `description`, `severity`, or any `labels.<name>`.",
-                      "items": {
-                        "type": "string"
-                      },
-                      "maxItems": 5,
-                      "minItems": 1,
-                      "type": "array"
-                    },
-                    "if": {
-                      "description": "AND-ed match conditions evaluated against stored alert fields.",
-                      "items": {
-                        "$ref": "#/components/schemas/FilterCondition"
-                      },
-                      "type": "array"
-                    }
-                  },
-                  "required": [
-                    "if",
-                    "equals"
-                  ],
-                  "type": "object"
-                },
-                "maxItems": 100,
-                "type": "array"
-              },
-              "equals": {
-                "description": "Groups of label keys whose equality defines a bucket.",
-                "items": {
-                  "items": {
-                    "type": "string"
-                  },
-                  "type": "array"
-                },
-                "maxItems": 5,
-                "type": "array"
-              },
-              "i_keys": {
-                "description": "Label keys used for intelligent grouping embeddings.",
-                "items": {
-                  "type": "string"
-                },
-                "maxItems": 10,
-                "type": "array"
-              },
-              "i_score_threshold": {
-                "description": "Intelligent grouping similarity threshold.",
-                "format": "float",
-                "maximum": 1,
-                "minimum": 0.5,
-                "type": "number"
-              },
-              "method": {
-                "description": "Grouping method: `i` intelligent, `p` pattern, `n` none.",
-                "enum": [
-                  "i",
-                  "p",
-                  "n"
-                ],
-                "type": "string"
-              },
-              "storm_threshold": {
-                "description": "Alert storm threshold.",
-                "maximum": 10000,
-                "minimum": 0,
-                "type": "integer"
-              },
-              "storm_thresholds": {
-                "description": "Multi-level storm thresholds.",
-                "items": {
-                  "type": "integer"
-                },
-                "maxItems": 5,
-                "type": "array"
-              },
-              "time_window": {
-                "description": "Grouping time window in minutes. Default max is 1440 minutes (24 h); extended accounts may allow up to 43200 minutes (30 days).",
-                "minimum": 0,
-                "type": "integer"
-              },
-              "window_type": {
-                "description": "Window type, default `tumbling`. `tumbling` is a fixed window counted from incident creation — once it expires, new alerts open a new incident; `sliding` is a sliding window counted from the incident's most recent alert, extended each time a new alert merges in.",
-                "enum": [
-                  "tumbling",
-                  "sliding"
-                ],
-                "type": "string"
-              }
-            },
-            "required": [
-              "method"
-            ],
-            "type": "object"
+            "$ref": "#/components/schemas/Group",
+            "description": "Alert grouping configuration. Omit for no grouping (`method` `n`)."
           },
-          "is_external_report_enabled": {
-            "description": "Allow external reporters to file incidents into this channel.",
-            "type": "boolean"
+          "flapping": {
+            "$ref": "#/components/schemas/Flapping",
+            "description": "Flapping detection configuration. Omit to use the defaults."
           },
-          "is_private": {
-            "description": "When true, the channel is visible only to its managing teams.",
-            "type": "boolean"
+          "auto_resolve_timeout": {
+            "type": "integer",
+            "format": "int64",
+            "minimum": 0,
+            "maximum": 2592000,
+            "description": "Auto-resolve timeout in seconds. 0 disables auto-resolve. Max 30 days."
           },
-          "managing_team_ids": {
-            "description": "Additional teams that can manage the channel. Up to 3 entries.",
-            "items": {
-              "format": "int64",
-              "type": "integer"
-            },
-            "maxItems": 3,
-            "type": "array"
+          "auto_resolve_mode": {
+            "type": "string",
+            "enum": [
+              "trigger",
+              "update"
+            ],
+            "description": "How the auto-resolve timer runs. `trigger` (default) starts the timer once when the incident is triggered; `update` restarts it whenever a new alert merges into the incident."
           },
           "plugin_ids": {
-            "description": "IDs of plugins (integrations) subscribed to this channel.",
+            "type": "array",
             "items": {
-              "format": "int64",
-              "type": "integer"
+              "type": "integer",
+              "format": "int64"
             },
-            "type": "array"
+            "description": "Integration type IDs (the `plugin_id` shown on integrations returned by `POST /integration/list`). For each ID, a channel-exclusive integration of that type is created, named after the type. An unknown ID returns `InvalidParameter`."
           },
-          "team_id": {
-            "description": "Owning team ID; obtain it from `POST /team/list`.",
-            "format": "int64",
-            "type": "integer"
+          "is_private": {
+            "type": "boolean",
+            "description": "When true, the channel is visible only to its managing teams."
+          },
+          "disable_outlier_detection": {
+            "type": "boolean",
+            "description": "Disable outlier incident detection."
+          },
+          "disable_auto_close": {
+            "type": "boolean",
+            "description": "Disable automatic incident closing."
+          },
+          "is_external_report_enabled": {
+            "type": "boolean",
+            "description": "When true, external reporters can file incidents into this channel, and the response carries the generated `external_report_token`."
+          },
+          "event_group": {
+            "$ref": "#/components/schemas/EventGroup",
+            "description": "Alert event merge configuration. Omit to use the default (merge enabled, 1440-minute window)."
           }
-        },
-        "required": [
-          "team_id",
-          "channel_name"
-        ],
-        "type": "object"
+        }
       },
       "CreateDropRuleRequest": {
+        "type": "object",
         "description": "Parameters for creating a channel drop rule.",
+        "required": [
+          "channel_id",
+          "rule_name"
+        ],
         "properties": {
           "channel_id": {
-            "description": "Owning channel ID; obtain it from `POST /channel/list`.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Owning channel ID; obtain it from `POST /channel/list`."
+          },
+          "rule_name": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 39,
+            "description": "Rule name, 1 to 39 characters."
           },
           "description": {
-            "description": "Rule description, up to 500 characters.",
+            "type": "string",
             "maxLength": 500,
-            "type": "string"
+            "description": "Rule description, up to 500 characters."
           },
           "filters": {
-            "description": "Alert event match conditions (OR-of-AND); matching events are discarded entirely — no alert, incident, or notification is produced. When omitted or empty, the rule matches nothing.",
-            "items": {
-              "items": {
-                "properties": {
-                  "key": {
-                    "description": "Field key (e.g. `alert_severity`, `labels.service`).",
-                    "type": "string"
-                  },
-                  "oper": {
-                    "description": "Filter operator.",
-                    "enum": [
-                      "IN",
-                      "NOTIN"
-                    ],
-                    "type": "string"
-                  },
-                  "vals": {
-                    "description": "Values to match.",
-                    "items": {
-                      "type": "string"
-                    },
-                    "type": "array"
-                  }
-                },
-                "required": [
-                  "key",
-                  "oper",
-                  "vals"
-                ],
-                "type": "object"
-              },
-              "type": "array"
-            },
-            "type": "array"
-          },
-          "rule_name": {
-            "description": "Rule name, 1 to 39 characters.",
-            "maxLength": 39,
-            "minLength": 1,
-            "type": "string"
+            "$ref": "#/components/schemas/FilterGroup",
+            "description": "Alert event conditions (OR of AND groups). A matching event is discarded entirely: no alert, incident or notification. Keys: `title`, `description`, `severity` (alias `alert_severity`, `event_severity`), `status`, `alert_key`, `title_rule`, `integration_id` (alias `data_source_id`), or any `labels.<name>`. When omitted or empty, the rule matches nothing."
           }
-        },
-        "required": [
-          "channel_id",
-          "rule_name"
-        ],
-        "type": "object"
+        }
       },
       "CreateEscalationRuleRequest": {
+        "type": "object",
         "description": "Parameters for creating an escalation rule.",
+        "required": [
+          "channel_id",
+          "template_id",
+          "rule_name",
+          "layers"
+        ],
         "properties": {
+          "channel_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Owning channel ID; obtain it from `POST /channel/list`."
+          },
+          "priority": {
+            "type": [
+              "integer",
+              "null"
+            ],
+            "minimum": 0,
+            "maximum": 200,
+            "description": "Evaluation order from `0` to `200`; lower values are evaluated first. Omit to place the rule after all existing rules (current highest priority + 1)."
+          },
           "aggr_window": {
-            "description": "Delay window in seconds. 0 disables delay.",
-            "maximum": 3600,
+            "type": "integer",
             "minimum": 0,
-            "type": "integer"
+            "maximum": 3600,
+            "description": "Delay in seconds, 0–3600, before the first notification for a newly assigned incident; `0` notifies immediately."
           },
-          "channel_id": {
-            "description": "Owning channel ID; obtain it from `POST /channel/list`.",
-            "format": "int64",
-            "type": "integer"
+          "template_id": {
+            "type": "string",
+            "pattern": "^[0-9a-fA-F]{24}$",
+            "description": "Notification template ID (24-character hex); obtain it from `POST /template/list`. Must exist."
+          },
+          "rule_name": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 39,
+            "description": "Rule name, 1 to 39 characters."
           },
           "description": {
-            "description": "Rule description, up to 500 characters.",
+            "type": "string",
             "maxLength": 500,
-            "type": "string"
+            "description": "Rule description, up to 500 characters."
           },
-          "filters": {
-            "description": "Incident-level match conditions (OR-of-AND tree): the rule is matched against the incident the alert was grouped into, not against the alert itself. Omit or leave empty to apply the rule to all incidents in the channel.",
+          "layers": {
+            "type": "array",
             "items": {
-              "items": {
-                "properties": {
-                  "key": {
-                    "description": "Field key (e.g. `alert_severity`, `labels.service`).",
-                    "type": "string"
-                  },
-                  "oper": {
-                    "description": "Filter operator.",
-                    "enum": [
-                      "IN",
-                      "NOTIN"
-                    ],
-                    "type": "string"
-                  },
-                  "vals": {
-                    "description": "Values to match.",
-                    "items": {
-                      "type": "string"
-                    },
-                    "type": "array"
-                  }
-                },
-                "required": [
-                  "key",
-                  "oper",
-                  "vals"
-                ],
-                "type": "object"
-              },
-              "type": "array"
+              "$ref": "#/components/schemas/EscalateLayer"
             },
-            "type": "array"
+            "description": "Escalation levels in order; the incident starts at the first level."
           },
-          "layers": {
-            "description": "Escalation levels in order. At least one level is required.",
+          "time_filters": {
+            "type": "array",
             "items": {
-              "properties": {
-                "escalate_window": {
-                  "description": "Wait before moving to the next level, in minutes.",
-                  "maximum": 720,
-                  "minimum": 0,
-                  "type": "integer"
-                },
-                "force_escalate": {
-                  "description": "When true, always escalate regardless of acknowledgement.",
-                  "type": "boolean"
-                },
-                "max_times": {
-                  "description": "Max repeat notifications within the level.",
-                  "maximum": 6,
-                  "minimum": 0,
-                  "type": "integer"
-                },
-                "notify_step": {
-                  "description": "Repeat interval in minutes.",
-                  "format": "float",
-                  "maximum": 120,
-                  "minimum": 0.5,
-                  "type": "number"
-                },
-                "target": {
-                  "description": "Notification target. At least one of `person_ids`, `team_ids`, `schedule_to_role_ids`, or `emails` must be set, together with either `by` or `webhooks`.",
-                  "properties": {
-                    "by": {
-                      "description": "Per-severity personal notification channels. Required unless `webhooks` is provided.",
-                      "properties": {
-                        "critical": {
-                          "description": "Notify channels used for Critical severity. Personal channels: `sms`, `voice`, `email`, `push`; IM group-chat channels: `feishu_app:<chat_id>`, `dingtalk_app:<chat_id>`, `wecom_app:<chat_id>`, `slack_app:<chat_id>`, `teams_app:<chat_id>`.",
-                          "items": {
-                            "type": "string"
-                          },
-                          "type": "array"
-                        },
-                        "follow_preference": {
-                          "description": "When true, use each responder's personal preference instead of the lists below.",
-                          "type": "boolean"
-                        },
-                        "info": {
-                          "description": "Notify channels used for Info severity. Values as for `critical`.",
-                          "items": {
-                            "type": "string"
-                          },
-                          "type": "array"
-                        },
-                        "warning": {
-                          "description": "Notify channels used for Warning severity. Values as for `critical`.",
-                          "items": {
-                            "type": "string"
-                          },
-                          "type": "array"
-                        }
-                      },
-                      "type": "object"
-                    },
-                    "emails": {
-                      "description": "Email addresses to notify (push-only scenarios).",
-                      "items": {
-                        "format": "email",
-                        "type": "string"
-                      },
-                      "type": "array"
-                    },
-                    "person_ids": {
-                      "description": "Member IDs to notify directly; obtain member IDs from `POST /member/list`.",
-                      "items": {
-                        "format": "int64",
-                        "type": "integer"
-                      },
-                      "type": "array"
-                    },
-                    "schedule_to_role_ids": {
-                      "additionalProperties": {
-                        "items": {
-                          "format": "int64",
-                          "type": "integer"
-                        },
-                        "type": "array"
-                      },
-                      "description": "Map of schedule ID to the role IDs on that schedule to notify.",
-                      "type": "object"
-                    },
-                    "team_ids": {
-                      "description": "Team IDs to notify; obtain team IDs from `POST /team/list`.",
-                      "items": {
-                        "format": "int64",
-                        "type": "integer"
-                      },
-                      "type": "array"
-                    },
-                    "webhooks": {
-                      "description": "Group chat / webhook targets. Required unless `by` is provided.",
-                      "items": {
-                        "properties": {
-                          "settings": {
-                            "additionalProperties": true,
-                            "description": "Type-specific settings (chat IDs, URLs, etc.).",
-                            "type": "object"
-                          },
-                          "type": {
-                            "description": "Webhook type, one of `feishu`, `feishu_app`, `dingtalk`, `dingtalk_app`, `wecom`, `slack`, `slack_app`, `teams_app`, `telegram`, `zoom`.",
-                            "type": "string"
-                          }
-                        },
-                        "required": [
-                          "type",
-                          "settings"
-                        ],
-                        "type": "object"
-                      },
-                      "type": "array"
-                    }
-                  },
-                  "type": "object"
-                }
-              },
-              "required": [
-                "target"
-              ],
-              "type": "object"
+              "$ref": "#/components/schemas/TimeFilter"
             },
-            "type": "array"
+            "description": "Recurring time windows during which the rule can match; omit or leave empty to match at any time."
           },
-          "priority": {
-            "description": "Evaluation priority. Lower runs first.",
-            "maximum": 200,
-            "minimum": 0,
-            "type": [
-              "integer",
-              "null"
-            ]
+          "filters": {
+            "$ref": "#/components/schemas/FilterGroup",
+            "description": "Incident conditions (OR of AND groups), matched against the incident the alert was grouped into, not against the alert. Keys: `title`, `description`, `severity` (alias `incident_severity`, `alert_severity`), `status` (alias `incident_status`, `alert_status`), `dedup_key`, `integration_id` (alias `data_source_id`), or any `labels.<name>`. Omit or leave empty to match every incident in the channel."
+          }
+        }
+      },
+      "CreateFieldRequest": {
+        "type": "object",
+        "required": [
+          "field_name",
+          "display_name",
+          "field_type",
+          "value_type"
+        ],
+        "properties": {
+          "field_name": {
+            "type": "string",
+            "pattern": "^[a-zA-Z_][a-zA-Z0-9_]{0,39}$",
+            "maxLength": 39,
+            "description": "Machine name: 1–39 characters of `[a-zA-Z0-9_]`, starting with a letter or underscore. Immutable after creation."
           },
-          "rule_name": {
-            "description": "Rule name, 1 to 39 characters.",
+          "display_name": {
+            "type": "string",
             "maxLength": 39,
-            "minLength": 1,
-            "type": "string"
+            "description": "Human-readable name. Must be unique within the account."
           },
-          "template_id": {
-            "description": "Notification template ID (MongoDB ObjectID).",
-            "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
+          "description": {
+            "type": "string",
+            "maxLength": 499,
+            "description": "Optional free-text description."
           },
-          "time_filters": {
-            "description": "Optional recurring time windows during which the rule applies.",
+          "field_type": {
+            "type": "string",
+            "enum": [
+              "checkbox",
+              "multi_select",
+              "single_select",
+              "text"
+            ],
+            "description": "Field type, immutable after creation.\n| Value | Meaning |\n|---|---|\n| `text` | Free text; `value_type` must be `string`, no `options`. |\n| `single_select` | Single choice from `options`; `value_type` must be `string`. |\n| `multi_select` | Multiple choices from `options`; `value_type` must be `string`. |\n| `checkbox` | Boolean checkbox; `value_type` must be `bool`, no `options`. |"
+          },
+          "value_type": {
+            "type": "string",
+            "enum": [
+              "string",
+              "bool",
+              "float"
+            ],
+            "description": "Value type. `checkbox` requires `bool`; all other types require `string`. Immutable after creation. `float` is a reserved value currently rejected for every `field_type`."
+          },
+          "options": {
+            "type": "array",
             "items": {
-              "description": "Recurring time window. `start`/`end` use 24-hour `HH:MM` format; `repeat` uses ISO-style weekday indices (0=Sunday … 6=Saturday).",
-              "properties": {
-                "cal_id": {
-                  "description": "Optional calendar ID; restricts the window to days matching the calendar.",
-                  "type": "string"
-                },
-                "end": {
-                  "description": "End of the window in `HH:MM`.",
-                  "type": "string"
-                },
-                "is_off": {
-                  "description": "When true, match days marked as days-off in the calendar.",
-                  "type": "boolean"
-                },
-                "repeat": {
-                  "description": "Days of the week this window repeats on. Empty means every day.",
-                  "items": {
-                    "type": "integer"
-                  },
-                  "type": "array"
-                },
-                "start": {
-                  "description": "Start of the window in `HH:MM`.",
-                  "type": "string"
-                }
-              },
-              "type": "object"
+              "type": "string"
             },
-            "type": "array"
-          }
-        },
-        "required": [
-          "channel_id",
-          "template_id",
-          "rule_name",
-          "layers"
-        ],
-        "type": "object"
-      },
-      "CreateFieldRequest": {
-        "properties": {
+            "description": "Required and non-empty for `single_select`/`multi_select` (unique strings, each 1–200 chars). Must be omitted or empty for `checkbox`/`text`."
+          },
           "default_value": {
             "description": "Optional default value. Type must match `field_type`: `bool` for checkbox; one of `options` for single_select; subset of `options` for multi_select; string ≤3000 chars for text.",
             "oneOf": [
@@ -5777,66 +5793,17 @@
                 "type": "string"
               },
               {
+                "type": "array",
                 "items": {
                   "type": "string"
-                },
-                "type": "array"
+                }
               },
               {
                 "type": "null"
               }
             ]
-          },
-          "description": {
-            "description": "Optional free-text description.",
-            "maxLength": 499,
-            "type": "string"
-          },
-          "display_name": {
-            "description": "Human-readable name. Must be unique within the account.",
-            "maxLength": 39,
-            "type": "string"
-          },
-          "field_name": {
-            "description": "Machine name. Must start with a letter or underscore; 1–40 chars of `[a-zA-Z0-9_]`. Immutable after creation.",
-            "maxLength": 39,
-            "pattern": "^[a-zA-Z_][a-zA-Z0-9_]{0,39}$",
-            "type": "string"
-          },
-          "field_type": {
-            "description": "Field type, immutable after creation.\n| Value | Meaning |\n|---|---|\n| `text` | Free text; `value_type` must be `string`, no `options`. |\n| `single_select` | Single choice from `options`; `value_type` must be `string`. |\n| `multi_select` | Multiple choices from `options`; `value_type` must be `string`. |\n| `checkbox` | Boolean checkbox; `value_type` must be `bool`, no `options`. |",
-            "enum": [
-              "checkbox",
-              "multi_select",
-              "single_select",
-              "text"
-            ],
-            "type": "string"
-          },
-          "options": {
-            "description": "Required and non-empty for `single_select`/`multi_select` (unique strings, each 1–200 chars). Must be omitted or empty for `checkbox`/`text`.",
-            "items": {
-              "type": "string"
-            },
-            "type": "array"
-          },
-          "value_type": {
-            "description": "Value type. `checkbox` requires `bool`; all other types require `string`. Immutable after creation. `float` is a reserved value currently rejected for every `field_type`.",
-            "enum": [
-              "string",
-              "bool",
-              "float"
-            ],
-            "type": "string"
           }
-        },
-        "required": [
-          "field_name",
-          "display_name",
-          "field_type",
-          "value_type"
-        ],
-        "type": "object"
+        }
       },
       "CreateFieldResponse": {
         "properties": {
@@ -5857,24 +5824,24 @@
         "type": "object"
       },
       "CreateIncidentCommentTypeRequest": {
+        "type": "object",
         "description": "Parameters for creating a comment type. At most 10 comment types per account.",
-        "properties": {
-          "color": {
-            "description": "Label color as a hex value in #RRGGBB format. Normalized to uppercase.",
-            "pattern": "^#[0-9A-Fa-f]{6}$",
-            "type": "string"
-          },
-          "name": {
-            "description": "Display name. Trimmed before storing; must be unique within the account (case-insensitive). At most 40 characters.",
-            "maxLength": 40,
-            "type": "string"
-          }
-        },
         "required": [
           "name",
           "color"
         ],
-        "type": "object"
+        "properties": {
+          "name": {
+            "type": "string",
+            "maxLength": 40,
+            "description": "Display name. Trimmed before storing; must be unique within the account (case-insensitive). At most 40 characters. Must not contain control or text-direction characters."
+          },
+          "color": {
+            "type": "string",
+            "pattern": "^#[0-9A-Fa-f]{6}$",
+            "description": "Label color as a hex value in #RRGGBB format. Normalized to uppercase."
+          }
+        }
       },
       "CreateIncidentCommentTypeResponse": {
         "description": "Result of creating a comment type.",
@@ -5895,422 +5862,267 @@
         "type": "object"
       },
       "CreateIncidentRequest": {
+        "type": "object",
         "description": "Parameters for manually creating an incident.",
+        "required": [
+          "incident_severity"
+        ],
         "properties": {
+          "incident_severity": {
+            "type": "string",
+            "enum": [
+              "Info",
+              "Warning",
+              "Critical"
+            ],
+            "description": "Incident severity: `Info`, `Warning` or `Critical` (most severe)."
+          },
+          "title": {
+            "type": "string",
+            "maxLength": 512,
+            "description": "Incident title, up to 512 characters. Required (non-blank) when the account has a create form."
+          },
+          "description": {
+            "type": "string",
+            "maxLength": 1024,
+            "description": "Incident description, up to 1024 characters."
+          },
+          "channel_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Channel to file the incident into; must exist in the account. Optional unless the account has a create form; leave it unset for a standalone incident."
+          },
           "assigned_to": {
-            "description": "Incident assignment target. May be omitted entirely: when unset or empty, the channel's default assignment applies; required when the account's create form is in effect. `person_ids`, `escalate_rule_id`, and `emails` can be combined — responders are the union.",
+            "type": "object",
+            "description": "Who to assign. When omitted or empty, the channel's escalation rules decide (a standalone incident gets no responders); required when the account has a create form. `person_ids`, `escalate_rule_id` and `emails` can be combined — responders are the union. Assignment runs after creation, and its failure does not undo the incident.",
             "properties": {
-              "emails": {
-                "description": "Recipients to assign by email (1–100): resolved to account members and merged into `person_ids`; emails with no matching member are ignored.",
+              "person_ids": {
+                "type": "array",
                 "items": {
-                  "format": "email",
-                  "type": "string"
+                  "type": "integer",
+                  "format": "int64"
                 },
-                "maxItems": 100,
                 "minItems": 1,
-                "type": "array"
+                "maxItems": 100,
+                "description": "Member IDs to assign directly (1–100). Can be combined with `escalate_rule_id`."
               },
               "escalate_rule_id": {
-                "description": "Escalation rule ID (MongoDB ObjectID); assigns the people at the rule's `layer_idx` layer.",
+                "type": "string",
                 "pattern": "^[0-9a-fA-F]{24}$",
-                "type": "string"
+                "description": "Escalation rule ID (MongoDB ObjectID); assigns the people at the rule's `layer_idx` layer."
               },
               "layer_idx": {
-                "description": "Zero-based starting layer index of the escalation rule (default 0, the first layer); an out-of-range value returns an error. Only takes effect with `escalate_rule_id`.",
-                "type": "integer"
+                "type": "integer",
+                "description": "Zero-based escalation-rule layer to assign (default 0, the first layer). Used only with `escalate_rule_id`; an out-of-range value leaves the incident without responders instead of failing the request."
+              },
+              "type": {
+                "type": "string",
+                "enum": [
+                  "assign",
+                  "reassign",
+                  "escalate",
+                  "reopen"
+                ],
+                "description": "Assignment type. Normally omitted: the server then sets `assign`, because a manual create is always a first assignment. A value you send is stored as-is.\n- `assign`: first assignment of the incident.\n- `reassign`: assignment replacing an earlier one.\n- `escalate`: assignment triggered by escalation to the next layer.\n- `reopen`: assignment restarted from the first layer after the incident is reopened."
+              },
+              "emails": {
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "format": "email"
+                },
+                "minItems": 1,
+                "maxItems": 100,
+                "description": "Recipients to assign by email (1–100): resolved to account members and merged into `person_ids`; emails with no matching member are ignored."
               },
               "notify": {
+                "type": "object",
                 "description": "Override the notification channels used for this assignment.",
                 "properties": {
                   "follow_preference": {
-                    "description": "When false, use `personal_channels`; when true or omitted, use each responder's personal preference.",
                     "type": [
                       "boolean",
                       "null"
-                    ]
+                    ],
+                    "description": "When false, use `personal_channels`; when true or omitted, use each responder's personal preference."
                   },
                   "personal_channels": {
-                    "description": "Channels to use (e.g. `voice`, `sms`, `email`).",
+                    "type": "array",
                     "items": {
                       "type": "string"
                     },
-                    "type": "array"
+                    "description": "Channels to use when `follow_preference` is false: `sms`, `voice`, `email`, `push`, or an IM app channel prefixed `feishu_app:`, `dingtalk_app:`, `wecom_app:`, `slack_app:` or `teams_app:`."
                   },
                   "template_id": {
-                    "description": "Notification template ID (MongoDB ObjectID).",
+                    "type": "string",
                     "pattern": "^[0-9a-fA-F]{24}$",
-                    "type": "string"
+                    "description": "Notification template ID (MongoDB ObjectID)."
                   }
-                },
-                "type": "object"
-              },
-              "person_ids": {
-                "description": "Member IDs to assign directly (1–100). Can be combined with `escalate_rule_id`.",
-                "items": {
-                  "format": "int64",
-                  "type": "integer"
-                },
-                "maxItems": 100,
-                "minItems": 1,
-                "type": "array"
-              },
-              "type": {
-                "description": "Assignment type, derived server-side — callers do not set it: `assign` for manual creation, `reassign` for re-assignment, `escalate` for escalation-driven assignment.\n| Value | Meaning |\n|---|---|\n| `assign` | Initial assignment when the incident is created manually. |\n| `reassign` | Re-assignment of an existing incident. |\n| `escalate` | Assignment triggered by escalation policy advancement. |\n| `reopen` | Assignment restarted from the first layer after the incident is reopened. |",
-                "enum": [
-                  "assign",
-                  "reassign",
-                  "escalate",
-                  "reopen"
-                ],
-                "type": "string"
+                }
               }
-            },
-            "type": "object"
-          },
-          "channel_id": {
-            "description": "Channel to file the incident into. Optional; leave unset for a standalone incident.",
-            "format": "int64",
-            "type": "integer"
-          },
-          "description": {
-            "description": "Incident description, up to 1024 characters.",
-            "maxLength": 1024,
-            "type": "string"
+            }
           },
           "fields": {
             "$ref": "#/components/schemas/CustomFieldValues",
             "description": "Custom field values keyed by field name. When a create form applies, only its visible fields are accepted."
-          },
-          "incident_severity": {
-            "description": "Incident severity: `Info`, `Warning` or `Critical` (most severe).",
-            "enum": [
-              "Info",
-              "Warning",
-              "Critical"
-            ],
-            "type": "string"
-          },
-          "title": {
-            "description": "Incident title, up to 512 characters.",
-            "maxLength": 512,
-            "type": "string"
           }
-        },
-        "required": [
-          "incident_severity"
-        ],
-        "type": "object"
+        }
       },
       "CreateIncidentResponse": {
+        "type": "object",
         "description": "Result of manually creating an incident.",
+        "required": [
+          "incident_id",
+          "title"
+        ],
         "properties": {
           "incident_id": {
-            "description": "Newly created incident ID (MongoDB ObjectID).",
+            "type": "string",
             "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
+            "description": "Newly created incident ID (MongoDB ObjectID)."
           },
           "title": {
-            "description": "Echoes the incident title from the request.",
-            "type": "string"
+            "type": "string",
+            "description": "Incident title as sent in the request; empty when the request had no title."
           }
-        },
-        "required": [
-          "incident_id",
-          "title"
-        ],
-        "type": "object"
+        }
       },
       "CreateInhibitRuleRequest": {
+        "type": "object",
         "description": "Parameters for creating an inhibit rule.",
+        "required": [
+          "channel_id",
+          "rule_name",
+          "equals"
+        ],
         "properties": {
           "channel_id": {
-            "description": "Owning channel ID; obtain it from `POST /channel/list`.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Owning channel ID; obtain it from `POST /channel/list`."
+          },
+          "rule_name": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 39,
+            "description": "Rule name, 1 to 39 characters."
           },
           "description": {
-            "description": "Rule description, up to 500 characters.",
+            "type": "string",
             "maxLength": 500,
-            "type": "string"
+            "description": "Rule description, up to 500 characters."
           },
           "equals": {
-            "description": "Field keys whose values must be equal between the source (inhibiting) alert and the target (suppressed) alert, e.g. `data_source_id` or `labels.cluster`.",
+            "type": "array",
             "items": {
               "type": "string"
             },
-            "type": "array"
-          },
-          "is_directly_discard": {
-            "description": "When true, matching alert events are discarded entirely; when false, alerts are still recorded but marked as muted by this rule.",
-            "type": "boolean"
-          },
-          "rule_name": {
-            "description": "Rule name, 1 to 39 characters.",
-            "maxLength": 39,
-            "minLength": 1,
-            "type": "string"
+            "description": "Keys whose values must be equal on the source alert and the incoming event. Only `title`, `severity` and `labels.<name>` take effect; any other key (for example `data_source_id`) is accepted but makes the rule never fire. Must be present; an empty array also makes the rule inert."
           },
           "source_filters": {
-            "description": "Conditions the source alert must match, evaluated against stored active alerts. Supported keys: `status`, `incident_status`, `alert_status`, `severity`, `incident_severity`, `alert_severity`, `title`, `description`, or any `labels.<name>`. Empty makes the rule inert.",
-            "items": {
-              "items": {
-                "properties": {
-                  "key": {
-                    "description": "Field key (e.g. `alert_severity`, `labels.service`).",
-                    "type": "string"
-                  },
-                  "oper": {
-                    "description": "Filter operator.",
-                    "enum": [
-                      "IN",
-                      "NOTIN"
-                    ],
-                    "type": "string"
-                  },
-                  "vals": {
-                    "description": "Values to match.",
-                    "items": {
-                      "type": "string"
-                    },
-                    "type": "array"
-                  }
-                },
-                "required": [
-                  "key",
-                  "oper",
-                  "vals"
-                ],
-                "type": "object"
-              },
-              "type": "array"
-            },
-            "type": "array"
+            "$ref": "#/components/schemas/FilterGroup",
+            "description": "Conditions the source (inhibiting) alert must match, evaluated against active alerts already stored in the channel. Keys: `title`, `description`, `severity` (alias `incident_severity`, `alert_severity`), `status` (alias `incident_status`, `alert_status`), or any `labels.<name>`. Empty makes the rule inert."
           },
           "target_filters": {
-            "description": "Conditions the incoming target alert event must match to be suppressed; empty means every event is a target.",
-            "items": {
-              "items": {
-                "properties": {
-                  "key": {
-                    "description": "Field key (e.g. `alert_severity`, `labels.service`).",
-                    "type": "string"
-                  },
-                  "oper": {
-                    "description": "Filter operator.",
-                    "enum": [
-                      "IN",
-                      "NOTIN"
-                    ],
-                    "type": "string"
-                  },
-                  "vals": {
-                    "description": "Values to match.",
-                    "items": {
-                      "type": "string"
-                    },
-                    "type": "array"
-                  }
-                },
-                "required": [
-                  "key",
-                  "oper",
-                  "vals"
-                ],
-                "type": "object"
-              },
-              "type": "array"
-            },
-            "type": "array"
+            "$ref": "#/components/schemas/FilterGroup",
+            "description": "Conditions the incoming target alert event must match to be inhibited; empty means every incoming event is a target. Keys: `title`, `description`, `severity` (alias `alert_severity`, `event_severity`), `status`, `alert_key`, `title_rule`, `integration_id` (alias `data_source_id`), or any `labels.<name>`."
+          },
+          "is_directly_discard": {
+            "type": "boolean",
+            "description": "When true, matching alert events are discarded entirely; when false, alerts are still recorded but marked as muted by this rule."
           }
-        },
-        "required": [
-          "channel_id",
-          "rule_name",
-          "equals"
-        ],
-        "type": "object"
+        }
       },
       "CreateSilenceRuleRequest": {
+        "type": "object",
         "description": "Parameters for creating a silence rule. Exactly one of `time_filter` or `time_filters` must be provided, and `filters` must be non-empty.",
+        "required": [
+          "channel_id",
+          "rule_name"
+        ],
         "properties": {
           "channel_id": {
-            "description": "Owning channel ID; obtain it from `POST /channel/list`.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Owning channel ID; obtain it from `POST /channel/list`."
+          },
+          "rule_name": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 39,
+            "description": "Rule name, 1 to 39 characters."
           },
           "description": {
-            "description": "Rule description, up to 500 characters.",
+            "type": "string",
             "maxLength": 500,
-            "type": "string"
+            "description": "Rule description, up to 500 characters."
           },
-          "filters": {
-            "description": "Alert event match conditions (OR-of-AND). Required and must contain at least one condition.",
+          "from_incident_id": {
+            "type": "string",
+            "description": "ID of the incident this rule is created from (24-character hex). The incident must exist, and only one enabled silence rule may exist per incident.",
+            "pattern": "^[0-9a-fA-F]{24}$"
+          },
+          "time_filters": {
+            "type": "array",
             "items": {
-              "items": {
-                "properties": {
-                  "key": {
-                    "description": "Field key (e.g. `alert_severity`, `labels.service`).",
-                    "type": "string"
-                  },
-                  "oper": {
-                    "description": "Filter operator.",
-                    "enum": [
-                      "IN",
-                      "NOTIN"
-                    ],
-                    "type": "string"
-                  },
-                  "vals": {
-                    "description": "Values to match.",
-                    "items": {
-                      "type": "string"
-                    },
-                    "type": "array"
-                  }
-                },
-                "required": [
-                  "key",
-                  "oper",
-                  "vals"
-                ],
-                "type": "object"
-              },
-              "type": "array"
+              "$ref": "#/components/schemas/TimeFilter"
             },
-            "type": "array"
+            "description": "Recurring silence windows. Set exactly one of `time_filters` or `time_filter`."
           },
-          "from_incident_id": {
-            "description": "Incident ID (ObjectID hex) to attach the rule to. Optional; when set, only one enabled silence rule may exist per incident.",
-            "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
+          "time_filter": {
+            "$ref": "#/components/schemas/OnceTimeFilter",
+            "description": "One-off silence window. Set exactly one of `time_filter` or `time_filters`."
           },
-          "is_auto_delete": {
-            "description": "When true, the silence rule is automatically deleted after its time window expires. Defaults to false.",
-            "type": "boolean"
+          "filters": {
+            "$ref": "#/components/schemas/FilterGroup",
+            "description": "Alert event conditions (OR of AND groups); matching events are silenced while the time window is active. Required, with at least one condition. Keys: `title`, `description`, `severity` (alias `alert_severity`, `event_severity`), `status`, `alert_key`, `title_rule`, `integration_id` (alias `data_source_id`), or any `labels.<name>`."
           },
           "is_directly_discard": {
-            "description": "When true, matching alert events are discarded entirely; when false, alerts are still recorded but marked as muted by this rule.",
-            "type": "boolean"
-          },
-          "rule_name": {
-            "description": "Rule name, 1 to 39 characters.",
-            "maxLength": 39,
-            "minLength": 1,
-            "type": "string"
-          },
-          "time_filter": {
-            "description": "One-off time window defined by unix seconds.",
-            "properties": {
-              "end_time": {
-                "description": "Window end, Unix timestamp in seconds. Must be greater than 0.",
-                "exclusiveMinimum": 0,
-                "format": "int64",
-                "type": "integer"
-              },
-              "start_time": {
-                "description": "Window start, Unix timestamp in seconds. Must be greater than 0 and less than `end_time`.",
-                "exclusiveMinimum": 0,
-                "format": "int64",
-                "type": "integer"
-              }
-            },
-            "required": [
-              "start_time",
-              "end_time"
-            ],
-            "type": "object"
+            "type": "boolean",
+            "description": "When true, matching alert events are discarded entirely; when false, alerts are still recorded but marked as muted by this rule."
           },
-          "time_filters": {
-            "description": "Recurring time windows during which silencing applies. Mutually exclusive with `time_filter`.",
-            "items": {
-              "description": "Recurring time window. `start`/`end` use 24-hour `HH:MM` format; `repeat` uses ISO-style weekday indices (0=Sunday … 6=Saturday).",
-              "properties": {
-                "cal_id": {
-                  "description": "Optional calendar ID; restricts the window to days matching the calendar.",
-                  "type": "string"
-                },
-                "end": {
-                  "description": "End of the window in `HH:MM`.",
-                  "type": "string"
-                },
-                "is_off": {
-                  "description": "When true, match days marked as days-off in the calendar.",
-                  "type": "boolean"
-                },
-                "repeat": {
-                  "description": "Days of the week this window repeats on. Empty means every day.",
-                  "items": {
-                    "type": "integer"
-                  },
-                  "type": "array"
-                },
-                "start": {
-                  "description": "Start of the window in `HH:MM`.",
-                  "type": "string"
-                }
-              },
-              "type": "object"
-            },
-            "type": "array"
+          "is_auto_delete": {
+            "type": "boolean",
+            "description": "When true, a rule with a one-off `time_filter` is permanently removed about 24 hours after `end_time` (or after its last update, whichever is later). Rules created with `from_incident_id` are cleaned up the same way. Rules with recurring `time_filters` are never removed automatically. Defaults to `false`."
           }
-        },
-        "required": [
-          "channel_id",
-          "rule_name"
-        ],
-        "type": "object"
+        }
       },
       "CreateStatusPageChangeRequest": {
+        "type": "object",
         "description": "Parameters for creating a status page incident or maintenance event. The first update must contain `component_changes` to define affected components; retrospective events require at least 2 updates.",
+        "required": [
+          "page_id",
+          "type",
+          "title",
+          "description",
+          "status",
+          "updates"
+        ],
         "properties": {
-          "auto_update_by_schedule": {
-            "description": "Maintenance only: automatically advance the status based on the scheduled window.",
-            "type": "boolean"
-          },
-          "close_at_seconds": {
-            "description": "Event close time in Unix seconds. Must be greater than or equal to the first update's `at_seconds`. For retrospective events this is the time the event ended; for maintenances with `auto_update_by_schedule` it schedules the automatic transition to `completed` and must be within 30 days from now.",
-            "format": "int64",
-            "type": "integer"
-          },
-          "description": {
-            "description": "Event description (Markdown). Must not be empty.",
-            "type": "string"
-          },
-          "is_retrospective": {
-            "description": "Mark this event as a retrospective (historical) one.",
-            "type": "boolean"
-          },
-          "linked_changes": {
-            "description": "Linked change IDs (related incidents, deployments, etc.).",
-            "items": {
-              "type": "string"
-            },
-            "type": "array"
-          },
-          "notify_subscribers": {
-            "description": "Notify subscribers about this event and all its updates.",
-            "type": "boolean"
-          },
           "page_id": {
-            "description": "Status page ID; obtain it from `GET /status-page/list`.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Status page ID; obtain it from `GET /status-page/list`."
           },
-          "responders": {
-            "description": "Member IDs responsible for the event.",
-            "items": {
-              "format": "int64",
-              "type": "integer"
-            },
-            "type": "array"
+          "type": {
+            "type": "string",
+            "enum": [
+              "incident",
+              "maintenance"
+            ],
+            "description": "Change type: `incident` unplanned incident, `maintenance` planned maintenance."
           },
-          "start_at_seconds": {
-            "description": "Event start time in Unix seconds. The stored start time is always derived from the first update's `at_seconds` (which defaults to the current time when omitted); for maintenances with `auto_update_by_schedule`, this value schedules the automatic transition to `ongoing`.",
-            "format": "int64",
-            "type": "integer"
+          "title": {
+            "type": "string",
+            "maxLength": 255,
+            "description": "Event title, up to 255 characters."
+          },
+          "description": {
+            "type": "string",
+            "description": "Event description (Markdown). Must not be empty."
           },
           "status": {
-            "description": "Initial event status. `investigating`/`identified`/`monitoring`/`resolved` apply to incidents; `scheduled`/`ongoing`/`completed` apply to maintenances.",
+            "type": "string",
             "enum": [
               "investigating",
               "identified",
@@ -6320,68 +6132,53 @@
               "ongoing",
               "completed"
             ],
-            "type": "string"
+            "description": "Initial event status. `investigating`/`identified`/`monitoring`/`resolved` apply to incidents; `scheduled`/`ongoing`/`completed` apply to maintenances."
           },
-          "title": {
-            "description": "Event title, up to 255 characters.",
-            "maxLength": 255,
-            "type": "string"
+          "start_at_seconds": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Event start time in Unix seconds. Maintenances store this value as the scheduled start (with `auto_update_by_schedule`, the time the event switches to `ongoing`); when it is omitted or 0, and always for incidents, the start time is the first update's `at_seconds`."
           },
-          "type": {
-            "description": "Change type: `incident` unplanned incident, `maintenance` planned maintenance.",
-            "enum": [
-              "incident",
-              "maintenance"
-            ],
-            "type": "string"
+          "responders": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "int64"
+            },
+            "description": "Member IDs responsible for the event."
+          },
+          "linked_changes": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Linked change IDs (related incidents, deployments, etc.)."
+          },
+          "close_at_seconds": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Event close time in Unix seconds; must be greater than or equal to the first update's `at_seconds`. For maintenances this is the scheduled end; with `auto_update_by_schedule` the event switches to `completed` at this time, which must be within 30 days from now. For a retrospective event in a terminal status, omitting it uses the latest update's time."
           },
           "updates": {
-            "description": "Timeline updates. At least one update is required, and at least one of them must contain `component_changes`. Immediate events normally pass one update; retrospective events must pass all historical updates.",
+            "type": "array",
             "items": {
+              "type": "object",
               "description": "One timeline update entry.",
               "properties": {
+                "update_id": {
+                  "type": "string",
+                  "description": "Update ID. Server-assigned on create; supply when replaying historical updates."
+                },
                 "at_seconds": {
-                  "description": "Update timestamp in Unix seconds. When omitted or 0 on the first update, defaults to the current time.",
+                  "type": "integer",
                   "format": "int64",
-                  "type": "integer"
-                },
-                "component_changes": {
-                  "description": "Component status transitions applied by this update.",
-                  "items": {
-                    "properties": {
-                      "component_id": {
-                        "description": "Component ID; obtain it from `GET /status-page/info`.",
-                        "type": "string"
-                      },
-                      "status": {
-                        "description": "New component status. `operational`/`degraded`/`partial_outage`/`full_outage` apply to incidents; `operational`/`under_maintenance` apply to maintenances.",
-                        "enum": [
-                          "operational",
-                          "degraded",
-                          "partial_outage",
-                          "full_outage",
-                          "under_maintenance"
-                        ],
-                        "type": "string"
-                      }
-                    },
-                    "required": [
-                      "component_id",
-                      "status"
-                    ],
-                    "type": "object"
-                  },
-                  "type": "array"
+                  "description": "Update timestamp in Unix seconds. When omitted or 0 on the first update, defaults to the current time."
                 },
-                "description": {
-                  "description": "Update description (Markdown).",
+                "status": {
                   "type": [
                     "string",
                     "null"
-                  ]
-                },
-                "status": {
-                  "description": "Change status after this update. May be omitted (or null) when the overall status does not change. The first four values apply to incident-type changes, the last three to maintenance-type changes.\n| Value | Meaning |\n|---|---|\n| `investigating` | Investigating (incident). |\n| `identified` | Root cause identified (incident). |\n| `monitoring` | Fix deployed, monitoring (incident). |\n| `resolved` | Resolved (incident). |\n| `scheduled` | Scheduled (maintenance). |\n| `ongoing` | In progress (maintenance). |\n| `completed` | Completed (maintenance). |",
+                  ],
                   "enum": [
                     "investigating",
                     "identified",
@@ -6391,55 +6188,123 @@
                     "ongoing",
                     "completed"
                   ],
+                  "description": "Change status after this update. May be omitted (or null) when the overall status does not change. The first four values apply to incident-type changes, the last three to maintenance-type changes.\n| Value | Meaning |\n|---|---|\n| `investigating` | Investigating (incident). |\n| `identified` | Root cause identified (incident). |\n| `monitoring` | Fix deployed, monitoring (incident). |\n| `resolved` | Resolved (incident). |\n| `scheduled` | Scheduled (maintenance). |\n| `ongoing` | In progress (maintenance). |\n| `completed` | Completed (maintenance). |"
+                },
+                "description": {
                   "type": [
                     "string",
                     "null"
-                  ]
+                  ],
+                  "description": "Update description (Markdown)."
                 },
-                "update_id": {
-                  "description": "Update ID. Server-assigned on create; supply when replaying historical updates.",
-                  "type": "string"
+                "component_changes": {
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "required": [
+                      "component_id",
+                      "status"
+                    ],
+                    "properties": {
+                      "component_id": {
+                        "type": "string",
+                        "description": "Component ID; obtain it from `GET /status-page/info`."
+                      },
+                      "status": {
+                        "type": "string",
+                        "enum": [
+                          "operational",
+                          "degraded",
+                          "partial_outage",
+                          "full_outage",
+                          "under_maintenance"
+                        ],
+                        "description": "New component status. `operational`/`degraded`/`partial_outage`/`full_outage` apply to incidents; `operational`/`under_maintenance` apply to maintenances."
+                      }
+                    }
+                  },
+                  "description": "Component status transitions applied by this update."
                 }
-              },
-              "type": "object"
+              }
             },
-            "minItems": 1,
-            "type": "array"
+            "description": "Timeline updates in non-decreasing `at_seconds` order. At least one update is required, and at least one of them must contain `component_changes`. Immediate events normally pass one update; retrospective events must pass at least 2.",
+            "minItems": 1
+          },
+          "notify_subscribers": {
+            "type": "boolean",
+            "description": "Notify subscribers about this event. On creation one notification is sent for the last update; later timeline entries also notify while this is `true`."
+          },
+          "auto_update_by_schedule": {
+            "type": "boolean",
+            "description": "Maintenance only: automatically advance the status based on the scheduled window."
+          },
+          "is_retrospective": {
+            "type": "boolean",
+            "description": "Mark the event as retrospective (a past event recorded afterwards). Requires at least 2 entries in `updates`."
+          },
+          "draft_id": {
+            "type": "string",
+            "description": "ID of a draft created by `POST /status-page/draft/create` to publish with this event. The draft must be pending, target this `page_id` and `type`, and have no `change_id`; it is marked published once the event is created. Omit when not publishing a draft."
           }
-        },
+        }
+      },
+      "CreateStatusPageChangeTimelineRequest": {
+        "type": "object",
+        "description": "Parameters for appending an update to a status page event timeline.",
         "required": [
           "page_id",
-          "type",
-          "title",
-          "description",
+          "change_id",
           "status",
-          "updates"
+          "description"
         ],
-        "type": "object"
-      },
-      "CreateStatusPageChangeTimelineRequest": {
-        "description": "Parameters for appending an update to a status page event timeline.",
         "properties": {
-          "at_seconds": {
-            "description": "Update timestamp in Unix seconds. Defaults to the current time when omitted or 0.",
+          "page_id": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Status page ID; obtain it from `GET /status-page/list`."
           },
           "change_id": {
-            "description": "Target change ID; obtain it from `GET /status-page/change/list`.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Target change ID; obtain it from `GET /status-page/change/list`."
+          },
+          "at_seconds": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Update time in Unix seconds; must not be earlier than the event's latest timeline entry. Defaults to the current time when omitted or 0."
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "investigating",
+              "identified",
+              "monitoring",
+              "resolved",
+              "scheduled",
+              "ongoing",
+              "completed"
+            ],
+            "description": "Event status after this update; must be valid for the event type. Pass the current status to post an update without a status change. When moving to `resolved` or `completed`, all affected components must be back to `operational`.\n| Value | Meaning |\n|---|---|\n| `investigating` | Investigating (incident). |\n| `identified` | Root cause identified (incident). |\n| `monitoring` | Fix deployed, monitoring (incident). |\n| `resolved` | Resolved (incident). |\n| `scheduled` | Scheduled (maintenance). |\n| `ongoing` | In progress (maintenance). |\n| `completed` | Completed (maintenance). |"
+          },
+          "description": {
+            "type": "string",
+            "description": "Update description (Markdown). Must not be empty."
           },
           "component_changes": {
-            "description": "Component status transitions applied by this update. Component IDs must be unique.",
+            "type": "array",
             "items": {
+              "type": "object",
+              "required": [
+                "component_id",
+                "status"
+              ],
               "properties": {
                 "component_id": {
-                  "description": "Component ID; obtain it from `GET /status-page/info`.",
-                  "type": "string"
+                  "type": "string",
+                  "description": "Component ID; obtain it from `GET /status-page/info`."
                 },
                 "status": {
-                  "description": "New component status. `operational`/`degraded`/`partial_outage`/`full_outage` apply to incidents; `operational`/`under_maintenance` apply to maintenances.",
+                  "type": "string",
                   "enum": [
                     "operational",
                     "degraded",
@@ -6447,137 +6312,216 @@
                     "full_outage",
                     "under_maintenance"
                   ],
-                  "type": "string"
+                  "description": "New component status. `operational`/`degraded`/`partial_outage`/`full_outage` apply to incidents; `operational`/`under_maintenance` apply to maintenances."
                 }
-              },
-              "required": [
-                "component_id",
-                "status"
-              ],
-              "type": "object"
+              }
             },
-            "type": "array"
-          },
-          "description": {
-            "description": "Update description (Markdown). Must not be empty.",
-            "type": "string"
-          },
-          "page_id": {
-            "description": "Status page ID; obtain it from `GET /status-page/list`.",
-            "format": "int64",
-            "type": "integer"
+            "description": "Component status transitions applied by this update. Component IDs must be unique."
           },
-          "status": {
-            "description": "Change status after this update; must be valid for the change type. When transitioning to `resolved` or `completed`, all affected components must be back to `operational`.\n| Value | Meaning |\n|---|---|\n| `investigating` | Investigating (incident). |\n| `identified` | Root cause identified (incident). |\n| `monitoring` | Fix deployed, monitoring (incident). |\n| `resolved` | Resolved (incident). |\n| `scheduled` | Scheduled (maintenance). |\n| `ongoing` | In progress (maintenance). |\n| `completed` | Completed (maintenance). |",
-            "enum": [
-              "investigating",
-              "identified",
-              "monitoring",
-              "resolved",
-              "scheduled",
-              "ongoing",
-              "completed"
-            ],
-            "type": "string"
+          "draft_id": {
+            "type": "string",
+            "description": "ID of a pending draft created by `POST /status-page/draft/create` whose `change_id` is this event; it is marked published when the update is stored. Omit when not publishing a draft."
           }
-        },
-        "required": [
-          "page_id",
-          "change_id",
-          "status",
-          "description"
-        ],
-        "type": "object"
+        }
       },
       "CreateStatusPageDraftRequest": {
+        "type": "object",
         "description": "Parameters for storing a status page draft. The `draft` payload is stored verbatim; only the validated fields listed below are interpreted.",
+        "required": [
+          "draft"
+        ],
         "properties": {
           "draft": {
-            "description": "Draft payload, stored verbatim, up to 64 KB serialized. Validated fields: `page_id`, `type` (`incident` or `maintenance`), `name`, `message`; optional `change_id` (append an update to an existing event when > 0), `status`, `affected_components`, and `start_time`/`end_time` (Unix epoch seconds, new maintenance only).",
-            "type": "object"
+            "type": "object",
+            "description": "Draft payload, stored verbatim (at most 64 KB serialized). The server validates the fields below and keeps any other fields unchanged for the console.",
+            "required": [
+              "page_id",
+              "type",
+              "name",
+              "message"
+            ],
+            "additionalProperties": true,
+            "properties": {
+              "v": {
+                "type": "integer",
+                "description": "Payload format version chosen by the producer; stored, not interpreted."
+              },
+              "page_id": {
+                "type": "integer",
+                "format": "int64",
+                "description": "Target status page ID; must belong to the caller's account."
+              },
+              "page_name": {
+                "type": "string",
+                "description": "Page name for display in the console; not validated."
+              },
+              "type": {
+                "type": "string",
+                "enum": [
+                  "incident",
+                  "maintenance"
+                ],
+                "description": "Event type the draft creates or updates: `incident` unplanned incident, `maintenance` planned maintenance."
+              },
+              "name": {
+                "type": "string",
+                "maxLength": 255,
+                "description": "Event title, 1 to 255 characters."
+              },
+              "message": {
+                "type": "string",
+                "description": "Event or update description (Markdown). Must not be empty."
+              },
+              "change_id": {
+                "type": "integer",
+                "format": "int64",
+                "description": "Event to append an update to; it must be an event of the same `type` on `page_id`. Omit or pass 0 to draft a new event."
+              },
+              "status": {
+                "type": "string",
+                "enum": [
+                  "investigating",
+                  "identified",
+                  "monitoring",
+                  "resolved",
+                  "scheduled",
+                  "ongoing",
+                  "completed"
+                ],
+                "description": "Proposed event status; when set, it must be valid for `type` (`investigating`/`identified`/`monitoring`/`resolved` for incidents, `scheduled`/`ongoing`/`completed` for maintenances)."
+              },
+              "affected_components": {
+                "type": "array",
+                "description": "Components the draft affects.",
+                "items": {
+                  "type": "object",
+                  "required": [
+                    "component_id"
+                  ],
+                  "properties": {
+                    "component_id": {
+                      "type": "string",
+                      "description": "Component ID; must exist on the page."
+                    },
+                    "name": {
+                      "type": "string",
+                      "description": "Component name for display; not validated."
+                    },
+                    "status": {
+                      "type": "string",
+                      "enum": [
+                        "operational",
+                        "degraded",
+                        "partial_outage",
+                        "full_outage",
+                        "under_maintenance"
+                      ],
+                      "description": "Proposed component status; when set, it must be valid for `type` (`operational`/`degraded`/`partial_outage`/`full_outage` for incidents, `operational`/`under_maintenance` for maintenances)."
+                    }
+                  }
+                }
+              },
+              "start_time": {
+                "type": "integer",
+                "format": "int64",
+                "description": "Scheduled start in Unix seconds, for a new maintenance."
+              },
+              "end_time": {
+                "type": "integer",
+                "format": "int64",
+                "description": "Scheduled end in Unix seconds, for a new maintenance; must be greater than `start_time` when both are set."
+              }
+            }
           },
           "source": {
-            "description": "Opaque marker of the drafting origin, e.g. `ai_sre:sess_xxx`. Up to 64 characters.",
+            "type": "string",
             "maxLength": 64,
-            "type": "string"
+            "description": "Free-form text recording where the draft came from, such as an AI session reference; stored and shown with the draft, not interpreted. Up to 64 characters."
           }
-        },
-        "required": [
-          "draft"
-        ],
-        "type": "object"
+        }
       },
       "CreateStatusPageRequest": {
+        "type": "object",
         "properties": {
-          "contact_info": {
-            "description": "Get-in-touch contact, such as a mailto or website URL.",
-            "type": "string"
+          "name": {
+            "type": "string",
+            "description": "Display name of the status page.",
+            "maxLength": 255
+          },
+          "url_name": {
+            "type": "string",
+            "description": "URL-safe slug; normalized to lowercase with non-alphanumeric characters replaced by hyphens, and must be unique among the account's pages of the same type.",
+            "maxLength": 255
+          },
+          "type": {
+            "type": "string",
+            "description": "Visibility type: `public` accessible to anyone, `internal` restricted to logged-in members of this account.",
+            "enum": [
+              "public",
+              "internal"
+            ]
           },
           "custom_domain": {
-            "description": "Custom domain for a public status page.",
-            "maxLength": 255,
-            "type": "string"
+            "type": "string",
+            "description": "Custom domain; allowed only for public pages and must not be used by another status page.",
+            "maxLength": 255
           },
-          "custom_links": {
-            "description": "Custom navigation links shown on the status page.",
-            "items": {
-              "additionalProperties": {
-                "type": "string"
-              },
-              "type": "object"
-            },
-            "type": "array"
+          "page_title": {
+            "type": "string",
+            "description": "Accepted for compatibility but not stored; it has no effect."
+          },
+          "page_header": {
+            "type": "string",
+            "description": "Header content shown on the status page."
+          },
+          "page_footer": {
+            "type": "string",
+            "description": "Footer content shown on the status page."
           },
           "date_view": {
+            "type": "string",
             "description": "How change dates are displayed: `calendar` calendar view, `list` list view.",
             "enum": [
               "calendar",
               "list"
-            ],
-            "type": "string"
+            ]
           },
           "display_uptime_mode": {
+            "type": "string",
             "description": "Uptime display mode: `chart_and_percentage` chart plus percentage, `chart` chart only, `none` hidden.",
             "enum": [
               "chart_and_percentage",
               "chart",
               "none"
-            ],
-            "type": "string"
-          },
-          "name": {
-            "description": "Display name of the status page.",
-            "maxLength": 255,
-            "type": "string"
-          },
-          "page_footer": {
-            "description": "Footer content shown on the status page.",
-            "type": "string"
+            ]
           },
-          "page_header": {
-            "description": "Header content shown on the status page.",
-            "type": "string"
+          "custom_links": {
+            "type": "array",
+            "description": "Custom navigation links shown on the status page.",
+            "items": {
+              "type": "object",
+              "properties": {
+                "key": {
+                  "type": "string",
+                  "description": "Link text shown on the page."
+                },
+                "value": {
+                  "type": "string",
+                  "description": "URL the link text points to, such as `https://www.example.com`."
+                }
+              },
+              "additionalProperties": {
+                "type": "string"
+              }
+            }
           },
-          "page_title": {
-            "description": "Browser title shown for the status page.",
-            "type": "string"
+          "contact_info": {
+            "type": "string",
+            "description": "Get-in-touch contact, such as a mailto or website URL."
           },
           "subscription": {
             "$ref": "#/components/schemas/StatusPageSubscriptionItem",
-            "description": "Subscription channel toggles."
-          },
-          "type": {
-            "description": "Visibility type: `public` accessible to anyone, `internal` restricted to logged-in members of this account.",
-            "enum": [
-              "public",
-              "internal"
-            ],
-            "type": "string"
-          },
-          "url_name": {
-            "description": "URL-safe slug, unique per account and page type.",
-            "maxLength": 255,
-            "type": "string"
+            "description": "Subscription channel toggles; both default to `false`. A public page can enable only `email` and an internal page only `im`."
           }
         },
         "required": [
@@ -6586,8 +6530,7 @@
           "type",
           "date_view",
           "display_uptime_mode"
-        ],
-        "type": "object"
+        ]
       },
       "CreateStatusPageResponse": {
         "properties": {
@@ -6613,91 +6556,67 @@
         "type": "object"
       },
       "CreateWarRoomRequest": {
+        "type": "object",
         "description": "Parameters for opening an incident war room in an IM integration.",
+        "required": [
+          "incident_id",
+          "integration_id"
+        ],
         "properties": {
-          "add_observers": {
-            "description": "When true, also add historical responders of the incident as observers.",
-            "type": "boolean"
-          },
           "incident_id": {
-            "description": "Incident ID (MongoDB ObjectID).",
+            "type": "string",
             "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
+            "description": "Incident ID (MongoDB ObjectID)."
           },
           "integration_id": {
-            "description": "IM integration ID. Must have war room enabled; Feishu, DingTalk, WeCom (self-built), Slack and Teams are supported.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "IM integration ID with war room enabled; obtain it from `POST /datasource/im/war-room-enabled/list`. Feishu, DingTalk, WeCom (self-built app only), and Slack are supported."
           },
           "member_ids": {
-            "description": "Additional member IDs to add to the war room.",
+            "type": "array",
             "items": {
-              "format": "int64",
-              "type": "integer"
+              "type": "integer",
+              "format": "int64"
             },
-            "type": "array"
+            "description": "Member IDs to invite into the group; every ID must be a valid member of the account."
+          },
+          "add_observers": {
+            "type": "boolean",
+            "description": "When true, also invite members who were assigned or added as responders earlier but are no longer current responders."
           }
-        },
-        "required": [
-          "incident_id",
-          "integration_id"
-        ],
-        "type": "object"
+        }
       },
       "CreateWorkItemRequest": {
+        "type": "object",
         "description": "Parameters for creating an incident work item.",
+        "required": [
+          "item_type",
+          "title",
+          "incident_id",
+          "idempotency_key"
+        ],
         "properties": {
-          "assignee_ids": {
-            "description": "Legacy alias for the initial assignees. Equivalent to `assignees` with every entry `type` `person`. Mutually exclusive with `assignees`: sending both returns an error. Assignees must be active members who can already read the anchor; assignment never grants access.",
-            "items": {
-              "format": "int64",
-              "type": "integer"
-            },
-            "type": "array"
-          },
-          "assignees": {
-            "description": "Initial assignees. Each entry is `{type, id?}`. `type` is `person` or `ai_sre`; an `ai_sre` entry omits `id`. Mutually exclusive with `assignee_ids`: sending both returns an error. `assignee_ids` is the legacy alias and is equivalent to an all-`person` list. At most 20 entries. Person assignees must be active members who can already read the anchor; assignment never grants access.",
-            "items": {
-              "$ref": "#/components/schemas/WorkItemAssignee"
-            },
-            "maxItems": 20,
-            "type": "array"
-          },
-          "description": {
-            "description": "Optional longer description (max 65,535 characters).",
-            "maxLength": 65535,
-            "type": "string"
-          },
-          "idempotency_key": {
-            "description": "Client-generated idempotency key (max 128 characters; letters, digits, `_`, `-`, `.`, `:` only).",
-            "maxLength": 128,
-            "pattern": "^[A-Za-z0-9_\\-.:]+$",
-            "type": "string"
-          },
-          "incident_id": {
-            "description": "Incident ID (MongoDB ObjectID) the item is anchored to.",
-            "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
-          },
           "item_type": {
-            "description": "`action` anchors to an active incident and must not set `post_mortem_id`; `follow_up` requires `post_mortem_id`.",
+            "type": "string",
             "enum": [
               "action",
               "follow_up"
             ],
-            "type": "string"
+            "description": "Work item type.\n- `action`: a to-do on an incident that is not closed yet; must not set `post_mortem_id`.\n- `follow_up`: a post-mortem follow-up on a closed incident; `post_mortem_id` is optional."
           },
-          "post_mortem_id": {
-            "description": "Post-mortem ID (32-character hex string). Required for `follow_up`, forbidden for `action`. The post-mortem must be linked to `incident_id`.",
-            "type": "string"
+          "title": {
+            "type": "string",
+            "maxLength": 512,
+            "description": "Item title, at most 512 characters; leading and trailing spaces are trimmed and it must not be blank."
           },
-          "priority": {
-            "description": "Optional client-defined priority (max 64 characters).",
-            "maxLength": 64,
-            "type": "string"
+          "description": {
+            "type": "string",
+            "maxLength": 65535,
+            "description": "Optional longer description (max 65,535 characters)."
           },
           "status": {
-            "description": "Initial status. One of `open`, `in_progress`, `done`, `cancelled`; defaults to `open` when omitted or blank.",
+            "type": "string",
             "enum": [
               "open",
               "in_progress",
@@ -6705,21 +6624,45 @@
               "cancelled"
             ],
             "maxLength": 64,
-            "type": "string"
+            "description": "Initial status. One of `open`, `in_progress`, `done`, `cancelled`; defaults to `open` when omitted or blank."
           },
-          "title": {
-            "description": "Item title (max 512 characters).",
-            "maxLength": 512,
-            "type": "string"
+          "priority": {
+            "type": "string",
+            "maxLength": 64,
+            "description": "Optional free-form priority, at most 64 characters. The console uses `high`, `medium` and `low`; any other string is stored as-is."
+          },
+          "incident_id": {
+            "type": "string",
+            "pattern": "^[0-9a-fA-F]{24}$",
+            "description": "Incident ID (MongoDB ObjectID) the item is anchored to."
+          },
+          "post_mortem_id": {
+            "type": "string",
+            "description": "Post-mortem ID (32-character hex string). Forbidden for `action`. Optional for `follow_up`: when set, the incident must be linked to that report; when omitted, the incident's post-mortem is used if it exists."
+          },
+          "assignee_ids": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "int64"
+            },
+            "description": "Legacy alias for the initial assignees. Equivalent to `assignees` with every entry `type` `person`. Mutually exclusive with `assignees`: sending both returns an error. Assignees must be active members who can already read the anchor; assignment never grants access."
+          },
+          "assignees": {
+            "description": "Initial assignees. Each entry is `{type, id?}`. `type` is `person` or `ai_sre`; an `ai_sre` entry omits `id`. Mutually exclusive with `assignee_ids`: sending both returns an error. `assignee_ids` is the legacy alias and is equivalent to an all-`person` list. At most 20 entries. Person assignees must be active members who can already read the anchor; assignment never grants access.",
+            "items": {
+              "$ref": "#/components/schemas/WorkItemAssignee"
+            },
+            "maxItems": 20,
+            "type": "array"
+          },
+          "idempotency_key": {
+            "type": "string",
+            "maxLength": 128,
+            "pattern": "^[A-Za-z0-9_\\-.:]+$",
+            "description": "Client-generated idempotency key (max 128 characters; letters, digits, `_`, `-`, `.`, `:` only)."
           }
-        },
-        "required": [
-          "item_type",
-          "title",
-          "incident_id",
-          "idempotency_key"
-        ],
-        "type": "object"
+        }
       },
       "CustomFieldValues": {
         "additionalProperties": true,
@@ -6805,64 +6748,64 @@
         "type": "object"
       },
       "DSElasticSearchConfig": {
+        "type": "object",
         "description": "Elasticsearch datasource configuration.",
         "properties": {
-          "api_key": {
-            "description": "Elastic Cloud API key. Only for `cloud` deployment.",
-            "type": "string"
-          },
-          "certificate_fingerprint": {
-            "description": "SHA-256 fingerprint of the Elasticsearch CA certificate, used to verify the server chain (the recommended check for ES 8 default security).",
-            "type": "string"
-          },
-          "cloud_id": {
-            "description": "Elastic Cloud deployment ID. Only for `cloud` deployment.",
-            "type": "string"
-          },
           "deployment": {
-            "description": "Deployment type. `cloud` uses Elastic Cloud; `self-managed` uses a self-hosted cluster.",
+            "type": "string",
             "enum": [
               "cloud",
               "self-managed"
             ],
-            "type": "string"
+            "description": "Deployment type; required. `cloud` uses Elastic Cloud (`address` is not needed); `self-managed` uses a self-hosted cluster (`address` is required)."
           },
-          "headers": {
-            "description": "Custom HTTP headers added to every request, each entry formatted as `Key: Value`.",
-            "items": {
-              "type": "string"
-            },
-            "type": "array"
+          "timeout_mills": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Per-query timeout in milliseconds; `0` or omitted uses the default of 10000 (10 seconds)."
+          },
+          "cloud_id": {
+            "type": "string",
+            "description": "Elastic Cloud deployment ID. Only for `cloud` deployment."
+          },
+          "api_key": {
+            "type": "string",
+            "description": "Elastic Cloud API key. Only for `cloud` deployment."
+          },
+          "username": {
+            "type": "string",
+            "description": "Username for `self-managed` deployment."
           },
           "password": {
-            "description": "Authentication password for self-managed clusters; ignored when `service_token` is set.",
-            "type": "string"
+            "type": "string",
+            "description": "Authentication password for self-managed clusters; ignored when `service_token` is set."
           },
           "service_token": {
-            "description": "Service token; overrides username/password if set.",
-            "type": "string"
-          },
-          "timeout_mills": {
-            "description": "Per-query timeout in milliseconds; `0` or omitted uses the default of 10000 (10 seconds).",
-            "format": "int64",
-            "type": "integer"
+            "type": "string",
+            "description": "Service token; overrides username/password if set."
           },
           "tls_ca": {
-            "description": "PEM-encoded CA certificate used to verify the Elasticsearch server certificate.",
-            "type": "string"
+            "type": "string",
+            "description": "PEM-encoded CA certificate used to verify the Elasticsearch server certificate."
           },
-          "username": {
-            "description": "Username for `self-managed` deployment.",
-            "type": "string"
+          "certificate_fingerprint": {
+            "type": "string",
+            "description": "SHA-256 fingerprint of the Elasticsearch CA certificate, used to verify the server chain (the recommended check for ES 8 default security)."
+          },
+          "headers": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Custom HTTP headers added to every request, each entry formatted as `Key: Value`."
           }
-        },
-        "type": "object"
+        }
       },
       "DSKafkaConfig": {
         "description": "Diagnostic datasource connection configuration.",
         "properties": {
           "password": {
-            "description": "Authentication password; supports ${env:NAME}. Omit on update to preserve; explicitly send an empty string to clear. Literal passwords are omitted from responses.",
+            "description": "Authentication password; supports ${env:NAME}. Required with `username` for SASL authentication and must be empty when `sasl_mechanism` is `none`. On update, omit to keep the stored password; explicitly send an empty string to clear. Literal passwords are omitted from responses.",
             "type": "string",
             "x-flashduty-preserve-absence": true
           },
@@ -6894,7 +6837,7 @@
           },
           "tls_enabled": {
             "default": false,
-            "description": "Whether TLS is enabled; defaults to false.",
+            "description": "Whether TLS is enabled; defaults to false. When false, all `tls_*` fields are cleared on save.",
             "type": "boolean"
           },
           "tls_key": {
@@ -6919,7 +6862,7 @@
             "type": "boolean"
           },
           "username": {
-            "description": "Authentication username; an ${env:NAME} reference is supported.",
+            "description": "Authentication username; an ${env:NAME} reference is supported. Required when `sasl_mechanism` is `plain`, `scram-sha-256` or `scram-sha-512`; must be empty when it is `none`.",
             "type": "string"
           }
         },
@@ -7011,7 +6954,7 @@
           },
           "tls_enabled": {
             "default": false,
-            "description": "Whether TLS is enabled; defaults to false.",
+            "description": "Whether TLS is enabled; defaults to false. When false, all `tls_*` fields are cleared on save.",
             "type": "boolean"
           },
           "tls_max_version": {
@@ -7031,7 +6974,7 @@
             "type": "boolean"
           },
           "username": {
-            "description": "Authentication username; an ${env:NAME} reference is supported.",
+            "description": "Authentication username; an ${env:NAME} reference is supported. Must be configured together with `password`.",
             "type": "string"
           }
         },
@@ -7146,61 +7089,75 @@
         "type": "object"
       },
       "DSPayload": {
+        "type": "object",
         "description": "Type-specific datasource configuration. Include only the block matching `type_ident`.",
         "properties": {
-          "clickhouse": {
-            "$ref": "#/components/schemas/DSClickHouseConfig"
+          "prometheus": {
+            "$ref": "#/components/schemas/DSPrometheusConfig",
+            "description": "Settings for `type_ident` `prometheus`."
           },
-          "elasticsearch": {
-            "$ref": "#/components/schemas/DSElasticSearchConfig"
+          "loki": {
+            "$ref": "#/components/schemas/DSLokiConfig",
+            "description": "Settings for `type_ident` `loki`."
           },
-          "kafka": {
-            "$ref": "#/components/schemas/DSKafkaConfig",
-            "x-flashduty-preserve-absence": true
+          "mysql": {
+            "$ref": "#/components/schemas/DSMySQLConfig",
+            "description": "Settings for `type_ident` `mysql`."
           },
-          "loki": {
-            "$ref": "#/components/schemas/DSLokiConfig"
+          "oracle": {
+            "$ref": "#/components/schemas/DSOracleConfig",
+            "description": "Settings for `type_ident` `oracle`."
           },
-          "mongodb_mongod": {
-            "$ref": "#/components/schemas/DSMongoDBConfig",
-            "x-flashduty-preserve-absence": true
+          "postgres": {
+            "$ref": "#/components/schemas/DSPostgresConfig",
+            "description": "Settings for `type_ident` `postgres`."
           },
-          "mongodb_mongos": {
-            "$ref": "#/components/schemas/DSMongoDBConfig",
-            "x-flashduty-preserve-absence": true
+          "clickhouse": {
+            "$ref": "#/components/schemas/DSClickHouseConfig",
+            "description": "Settings for `type_ident` `clickhouse`."
           },
-          "mysql": {
-            "$ref": "#/components/schemas/DSMySQLConfig"
+          "elasticsearch": {
+            "$ref": "#/components/schemas/DSElasticSearchConfig",
+            "description": "Settings for `type_ident` `elasticsearch`."
           },
-          "oracle": {
-            "$ref": "#/components/schemas/DSOracleConfig"
+          "sls": {
+            "$ref": "#/components/schemas/DSSLSConfig",
+            "description": "Settings for `type_ident` `sls`."
           },
-          "postgres": {
-            "$ref": "#/components/schemas/DSPostgresConfig"
+          "victorialogs": {
+            "$ref": "#/components/schemas/DSVictoriaLogsConfig",
+            "description": "Settings for `type_ident` `victorialogs`."
           },
-          "prometheus": {
-            "$ref": "#/components/schemas/DSPrometheusConfig"
+          "tencent_cls": {
+            "$ref": "#/components/schemas/DSTencentCLSConfig",
+            "description": "Tencent CLS credentials. Required when `type_ident` is `tencent_cls`."
+          },
+          "kafka": {
+            "$ref": "#/components/schemas/DSKafkaConfig",
+            "x-flashduty-preserve-absence": true,
+            "description": "Settings for `type_ident` `kafka` (diagnostic-only)."
+          },
+          "mongodb_mongod": {
+            "$ref": "#/components/schemas/DSMongoDBConfig",
+            "x-flashduty-preserve-absence": true,
+            "description": "Settings for `type_ident` `mongodb_mongod` (diagnostic-only); same fields as `mongodb_mongos`."
+          },
+          "mongodb_mongos": {
+            "$ref": "#/components/schemas/DSMongoDBConfig",
+            "x-flashduty-preserve-absence": true,
+            "description": "Settings for `type_ident` `mongodb_mongos` (diagnostic-only); same fields as `mongodb_mongod`."
           },
           "redis_node": {
             "$ref": "#/components/schemas/DSRedisNodeConfig",
-            "x-flashduty-preserve-absence": true
+            "x-flashduty-preserve-absence": true,
+            "description": "Settings for `type_ident` `redis_node` (diagnostic-only)."
           },
           "redis_sentinel": {
             "$ref": "#/components/schemas/DSRedisSentinelConfig",
-            "x-flashduty-preserve-absence": true
-          },
-          "sls": {
-            "$ref": "#/components/schemas/DSSLSConfig"
-          },
-          "tencent_cls": {
-            "$ref": "#/components/schemas/DSTencentCLSConfig",
-            "description": "Tencent CLS credentials. Required when `type_ident` is `tencent_cls`."
-          },
-          "victorialogs": {
-            "$ref": "#/components/schemas/DSVictoriaLogsConfig"
+            "x-flashduty-preserve-absence": true,
+            "description": "Settings for `type_ident` `redis_sentinel` (diagnostic-only)."
           }
-        },
-        "type": "object"
+        }
       },
       "DSPostgresConfig": {
         "description": "PostgreSQL datasource configuration.",
@@ -7257,64 +7214,64 @@
         "type": "object"
       },
       "DSPrometheusConfig": {
+        "type": "object",
         "description": "Prometheus datasource configuration. TLS fields are inherited from TLSClientConfig.",
         "properties": {
           "basic_auth_enabled": {
-            "description": "Enable HTTP Basic Auth.",
-            "type": "boolean"
-          },
-          "basic_auth_password": {
-            "description": "Basic auth password.",
-            "type": "string"
+            "type": "boolean",
+            "description": "Enable HTTP Basic Auth."
           },
           "basic_auth_username": {
-            "description": "Basic auth username.",
-            "type": "string"
+            "type": "string",
+            "description": "Basic Auth username, effective when `basic_auth_enabled` is `true`."
+          },
+          "basic_auth_password": {
+            "type": "string",
+            "description": "Basic Auth password, effective when `basic_auth_enabled` is `true`. Returned as stored in create, update and info responses."
           },
           "headers": {
-            "description": "Custom HTTP headers in `Key: Value` format.",
+            "type": "array",
             "items": {
               "type": "string"
             },
-            "type": "array"
+            "description": "Custom HTTP headers in `Key: Value` format."
           },
           "params": {
-            "description": "Custom query parameters in `key=value` format.",
+            "type": "array",
             "items": {
               "type": "string"
             },
-            "type": "array"
+            "description": "Custom query parameters in `key=value` format."
           },
           "tls_ca": {
-            "description": "PEM-encoded CA certificate used to verify the server certificate.",
-            "type": "string"
+            "type": "string",
+            "description": "PEM-encoded CA certificate used to verify the server certificate."
           },
           "tls_cert": {
-            "description": "PEM-encoded client certificate for mutual TLS; must be configured together with `tls_key`.",
-            "type": "string"
+            "type": "string",
+            "description": "PEM-encoded client certificate for mutual TLS; must be configured together with `tls_key`."
           },
           "tls_key": {
-            "description": "PEM-encoded client private key; must be configured together with `tls_cert`.",
-            "type": "string"
-          },
-          "tls_max_version": {
-            "description": "Maximum TLS version, one of `1.0`, `1.1`, `1.2`, `1.3`; empty means no constraint.",
-            "type": "string"
+            "type": "string",
+            "description": "PEM-encoded client private key; must be configured together with `tls_cert`."
           },
-          "tls_min_version": {
-            "description": "Minimum TLS version, one of `1.0`, `1.1`, `1.2`, `1.3`; empty means no constraint and it must not exceed `tls_max_version`.",
-            "type": "string"
+          "tls_skip_verify": {
+            "type": "boolean",
+            "description": "Whether to skip server certificate verification (insecure, for self-signed setups only)."
           },
           "tls_server_name": {
-            "description": "Server name used for TLS SNI and certificate verification; defaults to the host from the connection address when empty.",
-            "type": "string"
+            "type": "string",
+            "description": "Server name used for TLS SNI and certificate verification; defaults to the host from the connection address when empty."
           },
-          "tls_skip_verify": {
-            "description": "Whether to skip server certificate verification (insecure, for self-signed setups only).",
-            "type": "boolean"
+          "tls_min_version": {
+            "type": "string",
+            "description": "Minimum TLS version, one of `1.0`, `1.1`, `1.2`, `1.3`; empty means no constraint and it must not exceed `tls_max_version`."
+          },
+          "tls_max_version": {
+            "type": "string",
+            "description": "Maximum TLS version, one of `1.0`, `1.1`, `1.2`, `1.3`; empty means no constraint."
           }
-        },
-        "type": "object"
+        }
       },
       "DSRedisNodeConfig": {
         "description": "Diagnostic datasource connection configuration.",
@@ -7338,7 +7295,7 @@
             "type": "integer"
           },
           "username": {
-            "description": "Authentication username; an ${env:NAME} reference is supported.",
+            "description": "Authentication username; an ${env:NAME} reference is supported. When set, `password` is required (on update, omit `password` to keep the stored one).",
             "type": "string"
           }
         },
@@ -7360,7 +7317,7 @@
             "type": "integer"
           },
           "username": {
-            "description": "Authentication username; an ${env:NAME} reference is supported.",
+            "description": "Authentication username; an ${env:NAME} reference is supported. When set, `password` is required (on update, omit `password` to keep the stored one).",
             "type": "string"
           }
         },
@@ -7465,42 +7422,72 @@
         "type": "object"
       },
       "DataSourceItem": {
+        "type": "object",
         "description": "A monitoring datasource.",
+        "required": [
+          "id",
+          "account_id",
+          "type_ident",
+          "name",
+          "enabled",
+          "note",
+          "address",
+          "edge_cluster_name",
+          "updated_at",
+          "payload",
+          "alerting_enabled",
+          "manage_team_id",
+          "readonly_team_ids",
+          "creator_id"
+        ],
         "properties": {
-          "account_id": {
-            "description": "Account ID.",
+          "id": {
+            "type": "integer",
             "format": "uint64",
-            "type": "integer"
+            "description": "Unique datasource ID. Pass it as `id` to update, delete and info, and as `datasource_id` to tool invocation."
           },
-          "address": {
-            "description": "Connection address. For Prometheus/Loki/VictoriaLogs: HTTP URL. For MySQL/Oracle/Postgres/ClickHouse: `host:port`. For SLS: endpoint without http/https prefix. Redis/MongoDB diagnostic types: one host:port, bracket IPv6; no URI, userinfo or query. Kafka: 1–32 unique comma-separated host:port bootstrap addresses; payload has no broker list. At most 4096 characters after normalization.",
-            "maxLength": 4096,
-            "type": "string"
+          "account_id": {
+            "type": "integer",
+            "format": "uint64",
+            "description": "ID of the account that owns the datasource; always the caller's account."
           },
-          "alerting_enabled": {
-            "description": "Whether alert evaluation is allowed. Alerting also requires enabled=true and an alerting-capable type. Always false for diagnostic-only types; false does not block non-alerting queries or tools.",
-            "type": "boolean"
+          "type_ident": {
+            "type": "string",
+            "enum": [
+              "prometheus",
+              "loki",
+              "mysql",
+              "oracle",
+              "postgres",
+              "clickhouse",
+              "elasticsearch",
+              "sls",
+              "tencent_cls",
+              "victorialogs",
+              "redis_node",
+              "redis_sentinel",
+              "mongodb_mongod",
+              "mongodb_mongos",
+              "kafka"
+            ],
+            "description": "Datasource type.\n\nAlerting types (can evaluate alert rules):\n- `prometheus`: Prometheus-compatible metrics.\n- `loki`: Grafana Loki logs.\n- `mysql`: MySQL.\n- `oracle`: Oracle Database.\n- `postgres`: PostgreSQL.\n- `clickhouse`: ClickHouse.\n- `elasticsearch`: Elasticsearch.\n- `sls`: Alibaba Cloud Simple Log Service.\n- `tencent_cls`: Tencent Cloud Log Service (CLS).\n- `victorialogs`: VictoriaLogs.\n\nDiagnostic-only types (cannot evaluate alerts, `alerting_enabled` is always `false`):\n- `redis_node`: a single Redis node.\n- `redis_sentinel`: Redis Sentinel.\n- `mongodb_mongod`: a MongoDB mongod instance.\n- `mongodb_mongos`: a MongoDB mongos router.\n- `kafka`: a Kafka cluster.\n\nThe `payload` key that holds the type-specific settings has the same name as the type."
           },
-          "edge_cluster_name": {
-            "description": "Monitors edge cluster name responsible for evaluating rules using this datasource.",
-            "type": "string"
+          "name": {
+            "type": "string",
+            "description": "Datasource name, unique within the account across all types."
           },
           "enabled": {
-            "description": "Whether business execution is enabled. Disabled datasources reject business queries and tools; enabling does not change alerting_enabled.",
-            "type": "boolean"
-          },
-          "id": {
-            "description": "Unique datasource ID.",
-            "format": "uint64",
-            "type": "integer"
-          },
-          "name": {
-            "description": "Datasource display name.",
-            "type": "string"
+            "type": "boolean",
+            "description": "Whether business execution is enabled. Disabled datasources reject business queries and tools; enabling does not change alerting_enabled."
           },
           "note": {
-            "description": "Optional description.",
-            "type": "string"
+            "type": "string",
+            "description": "Free-text note; an empty string when not set."
+          },
+          "address": {
+            "type": "string",
+            "description": "Connection address as stored, after normalization. The format depends on `type_ident`; see the `address` field of the create request for each type. At most 4096 characters.",
+            "maxLength": 4096
           },
           "payload": {
             "anyOf": [
@@ -7513,99 +7500,183 @@
             ],
             "description": "Type-specific configuration block; must contain the key matching `type_ident`. Always `null` in `/monit/datasource/list` responses (the list query does not read the payload column); populated in create/update/info responses. For `tencent_cls`, `secret_key` is masked to an empty string unless it is an `${env:...}` reference. For diagnostic types, password and Kafka tls_key are omitted from responses unless they are ${env:...} references. On update, omit those fields to preserve stored secrets; explicitly send an empty string to clear. Other configuration fields retain their existing behavior."
           },
-          "type_ident": {
-            "description": "Datasource type identifier. Allowed: `prometheus`, `loki`, `mysql`, `oracle`, `postgres`, `clickhouse`, `elasticsearch`, `sls`, `tencent_cls`, `victorialogs`, `redis_node`, `redis_sentinel`, `mongodb_mongod`, `mongodb_mongos`, `kafka`。",
-            "type": "string"
+          "edge_cluster_name": {
+            "type": "string",
+            "description": "Monitors edge cluster name responsible for evaluating rules using this datasource."
           },
           "updated_at": {
-            "description": "Last update timestamp, Unix epoch seconds.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Last update timestamp, Unix epoch seconds."
+          },
+          "alerting_enabled": {
+            "description": "Whether alert evaluation is allowed. Alerting also requires enabled=true and an alerting-capable type. Always false for diagnostic-only types; false does not block non-alerting queries or tools.",
+            "type": "boolean"
+          },
+          "manage_team_id": {
+            "type": [
+              "integer",
+              "null"
+            ],
+            "format": "uint64",
+            "description": "ID of the managing team. Its members can edit, delete, enable or disable the datasource and view its full configuration. `null` means no managing team: any caller with the Datasources Manage permission can manage it. The creator, the account owner and Admin members can always manage."
+          },
+          "readonly_team_ids": {
+            "type": [
+              "array",
+              "null"
+            ],
+            "items": {
+              "type": "integer",
+              "format": "uint64"
+            },
+            "description": "IDs of the teams allowed to query and reference the datasource, in addition to the managing team, the creator, the account owner and Admin members. `null` or an empty array means every member of the account can query it."
+          },
+          "creator_id": {
+            "type": [
+              "integer",
+              "null"
+            ],
+            "format": "uint64",
+            "description": "ID of the member who created the datasource; `null` when not recorded. The creator can always manage the datasource."
+          },
+          "my_perm": {
+            "type": "string",
+            "enum": [
+              "manage",
+              "readonly"
+            ],
+            "description": "The caller's access level on this datasource. Only present in list responses.\n- `manage`: can edit, delete, enable or disable the datasource, view its configuration and query it.\n- `readonly`: can query and reference the datasource but not change it or read its configuration."
           }
-        },
-        "required": [
-          "id",
-          "account_id",
-          "type_ident",
-          "name",
-          "enabled",
-          "note",
-          "address",
-          "edge_cluster_name",
-          "updated_at",
-          "payload",
-          "alerting_enabled"
-        ],
-        "type": "object"
+        }
       },
       "DataSourceListRequest": {
+        "type": "object",
         "description": "Filter parameters for listing datasources.",
         "properties": {
           "type": {
-            "description": "Datasource type identifier. Omit to return all types. Allowed: `prometheus`, `loki`, `mysql`, `oracle`, `postgres`, `clickhouse`, `elasticsearch`, `sls`, `tencent_cls`, `victorialogs`, `redis_node`, `redis_sentinel`, `mongodb_mongod`, `mongodb_mongos`, `kafka`。",
-            "type": "string"
+            "type": "string",
+            "description": "Return only datasources of this type; omit or leave empty to return all types. An unrecognized value matches nothing and returns an empty array.\n\nAlerting types (can evaluate alert rules):\n- `prometheus`: Prometheus-compatible metrics.\n- `loki`: Grafana Loki logs.\n- `mysql`: MySQL.\n- `oracle`: Oracle Database.\n- `postgres`: PostgreSQL.\n- `clickhouse`: ClickHouse.\n- `elasticsearch`: Elasticsearch.\n- `sls`: Alibaba Cloud Simple Log Service.\n- `tencent_cls`: Tencent Cloud Log Service (CLS).\n- `victorialogs`: VictoriaLogs.\n\nDiagnostic-only types (cannot evaluate alerts, `alerting_enabled` is always `false`):\n- `redis_node`: a single Redis node.\n- `redis_sentinel`: Redis Sentinel.\n- `mongodb_mongod`: a MongoDB mongod instance.\n- `mongodb_mongos`: a MongoDB mongos router.\n- `kafka`: a Kafka cluster.",
+            "enum": [
+              "prometheus",
+              "loki",
+              "mysql",
+              "oracle",
+              "postgres",
+              "clickhouse",
+              "elasticsearch",
+              "sls",
+              "tencent_cls",
+              "victorialogs",
+              "redis_node",
+              "redis_sentinel",
+              "mongodb_mongod",
+              "mongodb_mongos",
+              "kafka"
+            ]
+          },
+          "name": {
+            "type": "string",
+            "description": "Return only the datasource whose name equals this value exactly (names are unique within the account, so at most one item). Omit or leave empty for no name filter."
           }
-        },
-        "type": "object"
+        }
       },
       "DataSourceListResponse": {
-        "description": "List of datasources. The `payload` column is not read by this endpoint, so `payload` is `null` in every item.",
+        "type": "array",
+        "description": "Datasources of the account that the caller can query, sorted by name; an empty array when nothing matches. `payload` is `null` in every item because the list does not read it; each item also carries `my_perm`.",
         "items": {
           "$ref": "#/components/schemas/DataSourceItem"
-        },
-        "type": "array"
+        }
       },
       "DataSourceUpsertRequest": {
-        "description": "Request body for creating or updating a datasource. `id` is required only for update. `address` is required for all types except Elasticsearch with `deployment=cloud`.",
+        "type": "object",
+        "description": "Request body for creating or updating a datasource. `id` is required for update and ignored on create. An update replaces `type_ident`, `name`, `note`, `address`, `payload` and `edge_cluster_name` with the values sent, so resend them all; only `enabled`, `alerting_enabled`, `manage_team_id` and `readonly_team_ids` keep their current value when omitted. `address` is required for all types except Elasticsearch with `deployment=cloud`.",
+        "required": [
+          "type_ident",
+          "name",
+          "edge_cluster_name",
+          "payload"
+        ],
         "properties": {
+          "id": {
+            "type": "integer",
+            "format": "uint64",
+            "description": "Datasource ID. Required for update (an unknown ID, or one in another account, fails with `ResourceNotFound`); ignored on create."
+          },
+          "type_ident": {
+            "type": "string",
+            "enum": [
+              "prometheus",
+              "loki",
+              "mysql",
+              "oracle",
+              "postgres",
+              "clickhouse",
+              "elasticsearch",
+              "sls",
+              "tencent_cls",
+              "victorialogs",
+              "redis_node",
+              "redis_sentinel",
+              "mongodb_mongod",
+              "mongodb_mongos",
+              "kafka"
+            ],
+            "description": "Datasource type.\n\nAlerting types (can evaluate alert rules):\n- `prometheus`: Prometheus-compatible metrics.\n- `loki`: Grafana Loki logs.\n- `mysql`: MySQL.\n- `oracle`: Oracle Database.\n- `postgres`: PostgreSQL.\n- `clickhouse`: ClickHouse.\n- `elasticsearch`: Elasticsearch.\n- `sls`: Alibaba Cloud Simple Log Service.\n- `tencent_cls`: Tencent Cloud Log Service (CLS).\n- `victorialogs`: VictoriaLogs.\n\nDiagnostic-only types (cannot evaluate alerts, `alerting_enabled` is always `false`):\n- `redis_node`: a single Redis node.\n- `redis_sentinel`: Redis Sentinel.\n- `mongodb_mongod`: a MongoDB mongod instance.\n- `mongodb_mongos`: a MongoDB mongos router.\n- `kafka`: a Kafka cluster.\n\nThe `payload` key that holds the type-specific settings has the same name as the type."
+          },
+          "name": {
+            "type": "string",
+            "description": "Datasource name; required and unique within the account across all types. This is the name referenced as `ds_name` in query APIs. Duplicates fail with `InvalidParameter`."
+          },
+          "note": {
+            "type": "string",
+            "description": "Free-text note. On update, an omitted or empty value clears the stored note."
+          },
           "address": {
-            "description": "Connection address. Required for every type except `elasticsearch` with `deployment: cloud`. Prometheus/Loki/VictoriaLogs: HTTP URL; MySQL/Oracle/Postgres/ClickHouse: `host:port`; SLS: endpoint without the `http(s)://` prefix; `tencent_cls`: must be `cls.tencentcloudapi.com` or `cls.internal.tencentcloudapi.com` (requires Monitors edge >= v0.66.0). Redis/MongoDB diagnostic types: one host:port, bracket IPv6; no URI, userinfo or query. Kafka: 1–32 unique comma-separated host:port bootstrap addresses; payload has no broker list. At most 4096 characters after normalization.",
-            "maxLength": 4096,
-            "type": "string"
+            "type": "string",
+            "description": "Connection address, required for every type except `elasticsearch` with `deployment: cloud`. At most 4096 characters after normalization. Format by type:\n- `prometheus`, `loki`, `victorialogs`: HTTP URL; `http://` is prepended when the value does not start with `http`.\n- `mysql`, `oracle`, `postgres`: `host:port`.\n- `clickhouse`: one or more comma-separated `host:port` endpoints; duplicates are rejected.\n- `elasticsearch` with `self-managed`: one or more comma-separated HTTP(S) URLs (scheme defaults to `http://`) that share identical query parameters; duplicates are rejected. Not needed for `cloud`.\n- `sls`: endpoint without the `http://` or `https://` prefix.\n- `tencent_cls`: exactly `cls.tencentcloudapi.com` or `cls.internal.tencentcloudapi.com` (requires Monitors edge >= v0.66.0).\n- `redis_node`, `redis_sentinel`, `mongodb_mongod`, `mongodb_mongos`: a single `host:port` (bracket IPv6) with no URI, userinfo or query.\n- `kafka`: 1-32 unique comma-separated `host:port` bootstrap addresses (the payload has no broker list).",
+            "maxLength": 4096
           },
-          "alerting_enabled": {
-            "description": "Whether this datasource may evaluate alerts. Omitted on create: true for alerting types, false for diagnostic-only types; omitted on update: preserve current value. null is invalid. redis_node, redis_sentinel, mongodb_mongod, mongodb_mongos and kafka reject true. Disabling is rejected with conflict when enabled rules reference the datasource.",
-            "type": "boolean",
-            "x-flashduty-preserve-absence": true
+          "payload": {
+            "$ref": "#/components/schemas/DSPayload",
+            "description": "Type-specific configuration block; must include the key named by `type_ident`. An update replaces the whole payload, so resend every setting you want to keep (including credentials of non-diagnostic types, which the info endpoint returns). Exceptions: for the diagnostic types, omit the password (and the Kafka `tls_key`) to keep the stored value or send an empty string to clear it; for `tencent_cls`, an omitted or empty `secret_key` keeps the stored key. Stored secrets are not carried over when `type_ident` changes."
           },
           "edge_cluster_name": {
-            "description": "Monitors edge cluster name responsible for evaluating rules using this datasource.",
-            "type": "string"
+            "type": "string",
+            "description": "Name of the Monitors edge cluster that evaluates rules and runs queries for this datasource. It must be an existing edge cluster of the account, otherwise the call fails with `InvalidParameter`. Changing it on update closes open alerts of rules that use this datasource."
           },
           "enabled": {
+            "type": "boolean",
             "description": "Whether business execution is enabled. Omitted on create: true; omitted on update: preserve the current value. Explicit false disables execution; null is invalid. Does not change alerting_enabled.",
+            "x-flashduty-preserve-absence": true
+          },
+          "alerting_enabled": {
+            "description": "Whether this datasource may evaluate alerts. Omitted on create: true for alerting types, false for diagnostic-only types; omitted on update: preserve current value. null is invalid. redis_node, redis_sentinel, mongodb_mongod, mongodb_mongos and kafka reject true. Disabling is rejected with conflict when enabled rules reference the datasource.",
             "type": "boolean",
             "x-flashduty-preserve-absence": true
           },
-          "id": {
-            "description": "Datasource ID. Required for update; omit for create.",
+          "manage_team_id": {
+            "type": [
+              "integer",
+              "null"
+            ],
             "format": "uint64",
-            "type": "integer"
-          },
-          "name": {
-            "description": "Datasource display name. This is the name referenced as `ds_name` in query APIs.",
-            "type": "string"
-          },
-          "note": {
-            "description": "Optional description.",
-            "type": "string"
-          },
-          "payload": {
-            "$ref": "#/components/schemas/DSPayload",
-            "description": "Type-specific configuration block. Must include the key matching `type_ident`. For diagnostic types, password and Kafka tls_key are omitted from responses unless they are ${env:...} references. On update, omit those fields to preserve stored secrets; explicitly send an empty string to clear. Other configuration fields retain their existing behavior."
+            "description": "ID of the managing team (see the response field of the same name). On create, omitted means no managing team. On update, omitted keeps the current value, while `null` or `0` clears it. Required whenever `readonly_team_ids` is non-empty.",
+            "x-flashduty-preserve-absence": true
           },
-          "type_ident": {
-            "description": "Datasource type identifier. Allowed: `prometheus`, `loki`, `mysql`, `oracle`, `postgres`, `clickhouse`, `elasticsearch`, `sls`, `tencent_cls`, `victorialogs`, `redis_node`, `redis_sentinel`, `mongodb_mongod`, `mongodb_mongos`, `kafka`。",
-            "type": "string"
+          "readonly_team_ids": {
+            "type": [
+              "array",
+              "null"
+            ],
+            "items": {
+              "type": "integer",
+              "format": "uint64"
+            },
+            "description": "IDs of the teams allowed to query and reference the datasource (see the response field of the same name). On create, omitted means unrestricted. On update, omitted keeps the current value, while `null` or an empty array clears it (everyone can query). Duplicates and `0` are dropped. Requires `manage_team_id`: a non-empty list without a managing team fails with `InvalidParameter`.",
+            "x-flashduty-preserve-absence": true
           }
-        },
-        "required": [
-          "type_ident",
-          "name",
-          "edge_cluster_name",
-          "payload"
-        ],
-        "type": "object"
+        }
       },
       "DatasourceQueryExecution": {
         "type": "object",
@@ -7967,7 +8038,7 @@
             "type": "integer"
           },
           "datasource_id": {
-            "description": "Datasource ID from /monit/datasource/list.",
+            "description": "ID of the datasource to run the tool against, from `/monit/datasource/list`. The caller needs query access to it. For query tools (`<type>.query`) the ID must not exceed 9007199254740991.",
             "format": "uint64",
             "minimum": 1,
             "type": "integer"
@@ -8030,7 +8101,7 @@
       "DatasourceToolTruncation": {
         "properties": {
           "reason": {
-            "description": "Why the result was truncated. Presence of this object indicates truncation.",
+            "description": "Why the result was truncated, as reported by the executing Edge; treat it as an opaque string. The object is present only when the result was truncated.",
             "type": "string"
           }
         },
@@ -8080,17 +8151,17 @@
         "type": "object"
       },
       "DeletePostMortemTemplateRequest": {
+        "type": "object",
         "description": "Parameters for deleting a post-mortem template.",
-        "properties": {
-          "template_id": {
-            "description": "Template ID; obtain it from `POST /incident/post-mortem/template/list`.",
-            "type": "string"
-          }
-        },
         "required": [
           "template_id"
         ],
-        "type": "object"
+        "properties": {
+          "template_id": {
+            "type": "string",
+            "description": "ID of the custom template to delete; obtain it from `POST /incident/post-mortem/template/list`."
+          }
+        }
       },
       "DeleteStatusPageChangeRequest": {
         "description": "Parameters for deleting a status page event.",
@@ -8226,44 +8297,52 @@
         "type": "object"
       },
       "DeleteWarRoomRequest": {
+        "type": "object",
         "description": "Parameters for deleting an incident war room.",
+        "required": [
+          "incident_id",
+          "integration_id"
+        ],
         "properties": {
           "incident_id": {
-            "description": "Incident ID (MongoDB ObjectID).",
+            "type": "string",
             "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
+            "description": "Incident ID (MongoDB ObjectID)."
           },
           "integration_id": {
-            "description": "IM integration ID; obtain it from `POST /datasource/im/war-room-enabled/list`.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "IM integration ID; obtain it from `POST /datasource/im/war-room-enabled/list`."
+          },
+          "unlink_only": {
+            "type": "boolean",
+            "description": "When true, only remove the link between the incident and the war room without dissolving the group. Allowed only for account owners and admins, only when the IM integration is disabled or deleted, and requires `chat_id`."
+          },
+          "chat_id": {
+            "type": "string",
+            "description": "Chat ID of the war room to unlink, from `POST /incident/war-room/list`. Required when `unlink_only` is `true` and must match the current war room; ignored otherwise."
           }
-        },
-        "required": [
-          "incident_id",
-          "integration_id"
-        ],
-        "type": "object"
+        }
       },
       "DeleteWorkItemRequest": {
+        "type": "object",
         "description": "Parameters for soft-deleting a work item.",
-        "properties": {
-          "version": {
-            "description": "Current item version for optimistic locking. Must match the stored version.",
-            "format": "int64",
-            "type": "integer"
-          },
-          "work_item_id": {
-            "description": "Work item ID (opaque string, max 128 characters).",
-            "maxLength": 128,
-            "type": "string"
-          }
-        },
         "required": [
           "work_item_id",
           "version"
         ],
-        "type": "object"
+        "properties": {
+          "work_item_id": {
+            "type": "string",
+            "maxLength": 128,
+            "description": "Work item ID (opaque string, max 128 characters)."
+          },
+          "version": {
+            "type": "integer",
+            "format": "int64",
+            "description": "The item's current `version` (≥ 1) for optimistic locking."
+          }
+        }
       },
       "DimensionInsightItem": {
         "allOf": [
@@ -8384,16 +8463,16 @@
         ]
       },
       "DimensionInsightResponse": {
+        "type": "object",
         "properties": {
           "items": {
-            "description": "Insight metric rows aggregated by the endpoint's dimension (account/team/channel); further split by hour bucket or time bucket when `split_hours` or `aggregate_unit` is enabled.",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/DimensionInsightItem"
             },
-            "type": "array"
+            "description": "Metric rows, newest bucket first. Buckets or dimension values without incidents produce no row; an empty array means no incidents matched."
           }
-        },
-        "type": "object"
+        }
       },
       "DisableIncidentMergeRequest": {
         "description": "Parameters for disabling automatic merging on incidents.",
@@ -8434,25 +8513,29 @@
         "type": "object"
       },
       "DoIncidentCustomActionResponse": {
-        "description": "Result of a custom action dispatch.",
+        "type": [
+          "object",
+          "null"
+        ],
+        "description": "`null` when the action's HTTP request succeeded; an object with `message` when it failed.",
         "properties": {
           "message": {
-            "description": "Error message if the action's HTTP call failed; omitted on success.",
-            "type": "string"
+            "type": "string",
+            "description": "Error returned by the HTTP request to the action's URL (for example, a timeout after 2 seconds)."
           }
-        },
-        "type": "object"
+        }
       },
       "DutyError": {
+        "type": "object",
         "description": "Error payload inside the response envelope. Present only on non-2xx responses.",
         "properties": {
           "code": {
             "$ref": "#/components/schemas/ErrorCode"
           },
           "message": {
-            "description": "Human-readable error message, localized by the caller's Accept-Language. May contain field names, IDs, or other context from the failing request.",
-            "example": "The specified parameter template_id is not valid.",
-            "type": "string"
+            "type": "string",
+            "description": "Human-readable error message in the response language (`locale` / `lang` query parameter or `Accept-Language` header). May name the offending field; do not parse it.",
+            "example": "The specified parameter template_id is not valid."
           },
           "reason": {
             "description": "Optional machine-readable rejection reason, including datasource tool failures. Inspect alongside HTTP status and code.",
@@ -8463,8 +8546,7 @@
         "required": [
           "code",
           "message"
-        ],
-        "type": "object"
+        ]
       },
       "EmptyObject": {
         "additionalProperties": false,
@@ -8477,62 +8559,62 @@
         "type": "object"
       },
       "EmptyResponse": {
-        "description": "Empty response body. The server returns `data: null` on success.",
-        "properties": {},
-        "type": "object"
+        "type": "object",
+        "description": "No payload. Depending on the operation, `data` is `{}` or omitted from the envelope; rely only on the HTTP 200 status and the absence of `error`.",
+        "properties": {}
       },
       "EnabledTime": {
+        "type": "object",
         "description": "Time window in which the rule is active.",
         "properties": {
           "days": {
-            "description": "Days of week, 0 = Sunday.",
+            "type": "array",
             "items": {
               "type": "integer"
             },
-            "type": "array"
-          },
-          "etime": {
-            "description": "End time, e.g. `18:00`.",
-            "type": "string"
+            "description": "Days of week the window applies to, `0` = Sunday through `6` = Saturday; non-empty, no duplicates."
           },
           "stime": {
-            "description": "Start time, e.g. `09:00`.",
-            "type": "string"
+            "type": "string",
+            "description": "Start time in 24-hour `HH:MM` format, e.g. `09:00`."
+          },
+          "etime": {
+            "type": "string",
+            "description": "End time in 24-hour `HH:MM` format, e.g. `18:00`."
           }
-        },
-        "type": "object"
+        }
       },
       "EnrichFilter": {
+        "type": "object",
+        "required": [
+          "key",
+          "oper",
+          "vals"
+        ],
         "description": "A single label filter condition.",
         "properties": {
           "key": {
-            "description": "Event key to match on (e.g. `labels.severity`, `title`). Must be non-empty.",
-            "minLength": 1,
-            "type": "string"
+            "type": "string",
+            "description": "Event key to match on: `title`, `description`, `labels.<name>` or another alert/change event key. A `labels.<name>` key must use a valid label name.",
+            "minLength": 1
           },
           "oper": {
-            "description": "Match operator. `IN` matches when any value matches; `NOTIN` matches when none of the values match.",
+            "type": "string",
             "enum": [
               "IN",
               "NOTIN"
             ],
-            "type": "string"
+            "description": "Match operator.\n- `IN`: matches when the key's value matches any of `vals`. A key missing from the event never matches.\n- `NOTIN`: matches when the value matches none of `vals`. A key missing from the event always matches."
           },
           "vals": {
-            "description": "Values to match against. Must contain at least one value.",
+            "type": "array",
             "items": {
               "type": "string"
             },
-            "minItems": 1,
-            "type": "array"
+            "description": "Values to match (at least one). Each value is one of: an exact string; `/regex/` for a regular expression; a wildcard pattern with `*` and `?`; `cidr:<CIDR>` (e.g. `cidr:203.0.113.0/24`) for an IP range; `num:lt:<n>`, `num:le:<n>`, `num:gt:<n>` or `num:ge:<n>` for a numeric comparison.",
+            "minItems": 1
           }
-        },
-        "required": [
-          "key",
-          "oper",
-          "vals"
-        ],
-        "type": "object"
+        }
       },
       "EnrichRule": {
         "description": "An enrichment rule with an optional condition and type-specific settings.",
@@ -8605,52 +8687,53 @@
         "type": "object"
       },
       "EnrichmentItem": {
+        "type": "object",
         "description": "Enrichment rule set for an integration.",
         "properties": {
-          "created_at": {
-            "description": "Creation timestamp, Unix seconds.",
-            "format": "int64",
-            "type": "integer"
-          },
-          "creator_id": {
-            "description": "Creator member ID.",
-            "format": "int64",
-            "type": "integer"
-          },
-          "deleted_at": {
-            "description": "Deletion time, Unix seconds. Omitted when the rule set is not deleted; read endpoints never return soft-deleted rule sets, so this is effectively always omitted.",
-            "format": "int64",
-            "type": "integer"
-          },
           "integration_id": {
-            "description": "Integration ID.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "ID of the integration this rule set belongs to; one integration has at most one rule set."
           },
           "rules": {
-            "description": "Ordered enrichment rules.",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/EnrichRule"
             },
-            "type": "array"
+            "description": "Rules in execution order; each rule sees the labels written by the rules before it."
           },
           "status": {
-            "description": "Rule set status: `enabled` (active) or `deleted` (soft-deleted). Read endpoints exclude soft-deleted rule sets, so responses always carry `enabled`.",
+            "type": "string",
             "enum": [
               "enabled",
               "deleted"
             ],
-            "type": "string"
+            "description": "Rule set status: `enabled` (active) or `deleted` (soft-deleted). Read endpoints exclude soft-deleted rule sets, so responses always carry `enabled`."
+          },
+          "updated_by": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Last updater member ID."
+          },
+          "creator_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Creator member ID."
+          },
+          "created_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Creation timestamp, Unix seconds."
           },
           "updated_at": {
-            "description": "Last update timestamp, Unix seconds.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Last update timestamp, Unix seconds."
           },
-          "updated_by": {
-            "description": "Last updater member ID.",
+          "deleted_at": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Deletion time, Unix seconds. Omitted when the rule set is not deleted; read endpoints never return soft-deleted rule sets, so this is effectively always omitted."
           }
         },
         "required": [
@@ -8661,8 +8744,7 @@
           "creator_id",
           "created_at",
           "updated_at"
-        ],
-        "type": "object"
+        ]
       },
       "EnrichmentListRequest": {
         "properties": {
@@ -8697,67 +8779,74 @@
         "type": "object"
       },
       "EnrichmentUpsertRequest": {
+        "type": "object",
+        "required": [
+          "integration_id",
+          "rules"
+        ],
         "properties": {
           "integration_id": {
-            "description": "Integration ID to configure enrichment rules for.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Integration ID to configure enrichment rules for."
           },
           "rules": {
-            "description": "Ordered list of enrichment rules. Replaces all existing rules.",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/EnrichRule"
             },
-            "type": "array"
+            "description": "Ordered rule list that replaces the integration's whole rule set; send `[]` to remove all rules. Rules run in this order."
           }
-        },
-        "required": [
-          "integration_id",
-          "rules"
-        ],
-        "type": "object"
+        }
       },
       "EnvironmentBinding": {
-        "description": "The runner or cloud sandbox the session is bound to. Null until the first message.",
+        "type": "object",
+        "description": "The runner or cloud sandbox the session is bound to. Returned by `POST /safari/session/get` only; omitted until the session has been bound (after its first message).",
         "properties": {
-          "id": {
-            "description": "Environment identifier: a cloud sandbox ID for `cloud` bindings, a runner/environment ID for `byoc` bindings.",
-            "type": "string"
-          },
           "kind": {
+            "type": "string",
             "description": "Environment kind bound to the session: `cloud` (managed sandbox) or `byoc` (self-hosted runner).",
             "enum": [
               "cloud",
               "byoc"
-            ],
-            "type": "string"
+            ]
+          },
+          "id": {
+            "type": "string",
+            "description": "Environment identifier: a cloud sandbox ID for `cloud` bindings, a runner/environment ID for `byoc` bindings."
           },
           "name": {
-            "description": "Human-readable environment name; empty for cloud bindings using the default allowlist.",
-            "type": "string"
+            "type": "string",
+            "description": "Human-readable environment name; empty for cloud bindings using the default allowlist."
+          },
+          "team_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Team that owns the bound environment; 0 for account-scope environments."
           },
           "status": {
-            "description": "Live binding health, namespaced by kind: BYOC uses online/pending/offline/deleted; cloud uses available/rebuilding/expired.",
+            "type": "string",
+            "description": "Live health of the binding. Omitted when unknown.\n\nFor `byoc`:\n- `online`: runner connected and ready\n- `degraded`: runner connected but its executor is unhealthy; messages are still accepted\n- `pending`: runner has never connected\n- `offline`: runner heartbeat lost; messages cannot be served\n- `deleted`: the environment no longer exists; choose another\n\nFor `cloud`:\n- `available`: the sandbox can serve the next message (paused or starting sandboxes resume automatically)\n- `rebuilding`: the sandbox is being resumed or recreated\n- `expired`: the sandbox failed permanently and cannot recover by itself\n- `deleted`: the selected cloud environment template was deleted",
             "enum": [
               "online",
+              "degraded",
               "pending",
               "offline",
               "deleted",
               "available",
               "rebuilding",
               "expired"
-            ],
-            "type": "string"
+            ]
           }
         },
         "required": [
           "kind",
           "id"
-        ],
-        "type": "object"
+        ]
       },
       "ErrorCode": {
-        "description": "Flashduty error code enum. Every failed API response sets `error.code` to one of these stable wire strings. HTTP status is informational — the authoritative signal is the enum value.\n\n| Code | HTTP | Meaning |\n|---|---|---|\n| `OK` | 200 | Reserved — not returned on real errors. |\n| `InvalidParameter` | 400 | A required parameter is missing or failed validation. |\n| `BadRequest` | 400 | Generic 400 used when no more specific code fits. |\n| `InvalidContentType` | 400 | The `Content-Type` header is not `application/json`. |\n| `ResourceNotFound` | 400 | The referenced resource does not exist. Note: returned as HTTP 400, not 404 (historical choice). |\n| `NoLicense` | 400 | The feature is license-gated and no active license was found. |\n| `ReferenceExist` | 400 | Deletion blocked — other entities still reference this resource. |\n| `Unauthorized` | 401 | `app_key` is missing, invalid, or expired. |\n| `BalanceNotEnough` | 402 | Billing-gated operation with insufficient account balance. |\n| `AccessDenied` | 403 | Authenticated but lacking the permission required for this operation. |\n| `RouteNotFound` | 404 | The request URL path is not a known route. |\n| `MethodNotAllowed` | 405 | The HTTP method is not allowed on this otherwise-known path. |\n| `UndonedOrderExist` | 409 | An outstanding billing order blocks this new one. Wait and retry. |\n| `RequestLocked` | 423 | Operation temporarily locked due to repeated failures. |\n| `EntityTooLarge` | 413 | Request body exceeds the configured max size. |\n| `RequestTooFrequently` | 429 | Rate limit hit — API-global, per-account, or per-integration. |\n| `RequestVerifyRequired` | 428 | Second-factor verification required but not supplied. |\n| `DangerousOperation` | 428 | High-risk operation requires MFA verification. |\n| `InternalError` | 500 | Unhandled server-side error. Include `request_id` in the bug report. |\n| `ServiceUnavailable` | 503 | A backend dependency is unavailable. Try again later. |",
+        "type": "string",
+        "description": "Error code. Every failed response sets `error.code` to one of these stable strings; branch on it rather than on the HTTP status.\n\n| Code | HTTP | Meaning |\n|---|---|---|\n| `OK` | 200 | Reserved; never returned on a failed request. |\n| `InvalidParameter` | 400 | A parameter is missing, has the wrong type, or failed validation; `message` usually names the field. |\n| `BadRequest` | 400 | The request breaks a business rule or conflicts with the current state of an object; `message` says which. |\n| `InvalidContentType` | 400 | The body is not sent as `application/json`. |\n| `ResourceNotFound` | 400 | The referenced object does not exist in this account or was deleted. Returned as HTTP 400, not 404. |\n| `NoLicense` | 400 | The account's plan does not include the feature, a plan quota is used up, the plan has expired, or credits are insufficient. |\n| `ReferenceExist` | 400 | The object is still referenced by other objects, so it cannot be deleted. |\n| `Unauthorized` | 401 | The APP Key is missing, invalid, or deleted. |\n| `BalanceNotEnough` | 402 | Console-only (billing); not returned by Open API operations. |\n| `AccessDenied` | 403 | The APP Key's permission scope or the creator's role does not allow this operation or object. |\n| `RouteNotFound` | 404 | No operation matches the HTTP method and path. |\n| `MethodNotAllowed` | 405 | The path exists but not for this HTTP method. |\n| `UndonedOrderExist` | 409 | Console-only (billing); not returned by Open API operations. |\n| `EntityTooLarge` | 413 | The request body exceeds the size limit. |\n| `RequestLocked` | 423 | Console-only (sign-in protection); not returned by Open API operations. |\n| `RequestVerifyRequired` | 428 | Console-only (verification code); not returned by Open API operations. |\n| `DangerousOperation` | 428 | Console-only (MFA for high-risk actions); not returned by Open API operations. |\n| `RequestTooFrequently` | 429 | A rate limit was hit; wait for the `Flashcat-Request-Rate-Limit-Delay` response header (seconds) before retrying. |\n| `InternalError` | 500 | Unexpected server error; retry with backoff and include `request_id` when reporting. |\n| `ServiceUnavailable` | 503 | A backend dependency is overloaded or unavailable; retry with backoff. |",
         "enum": [
           "OK",
           "InvalidParameter",
@@ -8772,38 +8861,37 @@
           "RouteNotFound",
           "MethodNotAllowed",
           "UndonedOrderExist",
-          "RequestLocked",
           "EntityTooLarge",
-          "RequestTooFrequently",
+          "RequestLocked",
           "RequestVerifyRequired",
           "DangerousOperation",
+          "RequestTooFrequently",
           "InternalError",
           "ServiceUnavailable"
         ],
-        "example": "InvalidParameter",
-        "type": "string",
         "x-enumDescriptions": {
-          "AccessDenied": "Authenticated but lacking the permission required for this operation.",
-          "BadRequest": "Generic 400 used when no more specific code fits.",
-          "BalanceNotEnough": "Billing-gated operation with insufficient account balance.",
-          "DangerousOperation": "High-risk operation requires MFA verification.",
-          "EntityTooLarge": "Request body exceeds the configured max size.",
-          "InternalError": "Unhandled server-side error. Include `request_id` in the bug report.",
-          "InvalidContentType": "The `Content-Type` header is not `application/json`.",
-          "InvalidParameter": "A required parameter is missing or failed validation.",
-          "MethodNotAllowed": "The HTTP method is not allowed on this otherwise-known path.",
-          "NoLicense": "The feature is license-gated and no active license was found.",
-          "OK": "Reserved — not returned on real errors.",
-          "ReferenceExist": "Deletion blocked — other entities still reference this resource.",
-          "RequestLocked": "Operation temporarily locked due to repeated failures.",
-          "RequestTooFrequently": "Rate limit hit — API-global, per-account, or per-integration.",
-          "RequestVerifyRequired": "Second-factor verification required but not supplied.",
-          "ResourceNotFound": "The referenced resource does not exist. Note: returned as HTTP 400, not 404 (historical choice).",
-          "RouteNotFound": "The request URL path is not a known route.",
-          "ServiceUnavailable": "A backend dependency is unavailable. Try again later.",
-          "Unauthorized": "`app_key` is missing, invalid, or expired.",
-          "UndonedOrderExist": "An outstanding billing order blocks this new one. Wait and retry."
-        }
+          "OK": "Reserved; never returned on a failed request.",
+          "InvalidParameter": "A parameter is missing, has the wrong type, or failed validation; `message` usually names the field.",
+          "BadRequest": "The request breaks a business rule or conflicts with the current state of an object; `message` says which.",
+          "InvalidContentType": "The body is not sent as `application/json`.",
+          "ResourceNotFound": "The referenced object does not exist in this account or was deleted. Returned as HTTP 400, not 404.",
+          "NoLicense": "The account's plan does not include the feature, a plan quota is used up, the plan has expired, or credits are insufficient.",
+          "ReferenceExist": "The object is still referenced by other objects, so it cannot be deleted.",
+          "Unauthorized": "The APP Key is missing, invalid, or deleted.",
+          "BalanceNotEnough": "Console-only (billing); not returned by Open API operations.",
+          "AccessDenied": "The APP Key's permission scope or the creator's role does not allow this operation or object.",
+          "RouteNotFound": "No operation matches the HTTP method and path.",
+          "MethodNotAllowed": "The path exists but not for this HTTP method.",
+          "UndonedOrderExist": "Console-only (billing); not returned by Open API operations.",
+          "EntityTooLarge": "The request body exceeds the size limit.",
+          "RequestLocked": "Console-only (sign-in protection); not returned by Open API operations.",
+          "RequestVerifyRequired": "Console-only (verification code); not returned by Open API operations.",
+          "DangerousOperation": "Console-only (MFA for high-risk actions); not returned by Open API operations.",
+          "RequestTooFrequently": "A rate limit was hit; wait for the `Flashcat-Request-Rate-Limit-Delay` response header (seconds) before retrying.",
+          "InternalError": "Unexpected server error; retry with backoff and include `request_id` when reporting.",
+          "ServiceUnavailable": "A backend dependency is overloaded or unavailable; retry with backoff."
+        },
+        "example": "InvalidParameter"
       },
       "ErrorResponse": {
         "description": "Response envelope for errors. `error` is required; `data` is absent.",
@@ -8824,433 +8912,470 @@
         "type": "object"
       },
       "ErsComposition": {
+        "type": "object",
+        "title": "composition",
+        "required": [
+          "result_label",
+          "template"
+        ],
         "properties": {
-          "override": {
-            "description": "When `true`, overwrite the label if it already exists. Defaults to `false`.",
-            "type": "boolean"
-          },
           "result_label": {
+            "type": "string",
             "description": "Destination label key the composed value is written to. Must match `^[a-zA-Z_][a-zA-Z0-9_]*$`.",
-            "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$",
-            "type": "string"
+            "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$"
           },
           "template": {
-            "description": "Go `text/template` string (1–500 characters) rendered against the event struct — e.g. `{{.Title}}`, `{{.Description}}`, `{{.Labels.key}}`. Example: `{{.Labels.region}}-{{.Labels.env}}`.",
+            "type": "string",
             "maxLength": 500,
-            "minLength": 1,
-            "type": "string"
+            "description": "Go `text/template` string (1–500 characters) rendered against the event struct — e.g. `{{.Title}}`, `{{.Description}}`, `{{.Labels.key}}`. Example: `{{.Labels.region}}-{{.Labels.env}}`.",
+            "minLength": 1
+          },
+          "override": {
+            "type": "boolean",
+            "description": "When `false` (default) the rule is skipped if `result_label` already exists on the event; when `true` the existing value is overwritten."
           }
-        },
-        "required": [
-          "result_label",
-          "template"
-        ],
-        "title": "composition",
-        "type": "object"
+        }
       },
       "ErsDrop": {
+        "type": "object",
+        "title": "drop",
+        "required": [
+          "drop_labels"
+        ],
         "properties": {
           "drop_labels": {
-            "description": "List of label keys to remove from the alert.",
+            "type": "array",
             "items": {
               "type": "string"
             },
-            "type": "array"
+            "description": "Label names to remove from the event (at least one), given without the `labels.` prefix.",
+            "minItems": 1
           }
-        },
-        "required": [
-          "drop_labels"
-        ],
-        "title": "drop",
-        "type": "object"
+        }
       },
       "ErsExtraction": {
+        "type": "object",
+        "title": "extraction",
+        "required": [
+          "source_field",
+          "result_label"
+        ],
         "properties": {
-          "g_json": {
-            "description": "GJson path expression used to extract a value from a JSON-encoded field. Mutually exclusive with `pattern`.",
-            "type": "string"
+          "source_field": {
+            "type": "string",
+            "description": "Source field to extract from. Must be `title`, `description`, or a label key prefixed with `labels.` (e.g. `labels.env`)."
           },
-          "override": {
-            "description": "When `true`, overwrite the label if it already exists. Defaults to `false`.",
-            "type": "boolean"
+          "result_label": {
+            "type": "string",
+            "description": "Destination label key the extracted value is written to. Must match `^[a-zA-Z_][a-zA-Z0-9_]*$`.",
+            "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$"
           },
           "pattern": {
-            "description": "RE2 regular expression applied to the source value. Must contain at least one capture group; the captured groups are joined with a space and written to `result_label`. Mutually exclusive with `g_json`.",
-            "type": "string"
+            "type": "string",
+            "description": "Regular expression (RE2) applied to the source value; may be wrapped in `/.../`. All capture groups are joined with a space and written to `result_label`. Nothing is written when the expression does not match, has no capture group, or the first group is empty. Exactly one of `pattern` and `g_json` must be set."
           },
-          "result_label": {
-            "description": "Destination label key the extracted value is written to. Must match `^[a-zA-Z_][a-zA-Z0-9_]*$`.",
-            "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$",
-            "type": "string"
+          "g_json": {
+            "type": "string",
+            "description": "GJSON path (a leading `$.` is ignored) used when the source value is a JSON string, e.g. `host.name`. If the source value is not valid JSON the rule is skipped; if the path does not exist an empty string is written. Exactly one of `pattern` and `g_json` must be set."
           },
-          "source_field": {
-            "description": "Source field to extract from. Must be `title`, `description`, or a label key prefixed with `labels.` (e.g. `labels.env`).",
-            "type": "string"
+          "override": {
+            "type": "boolean",
+            "description": "When `false` (default) the rule is skipped if `result_label` already exists on the event; when `true` the existing value is overwritten."
           }
-        },
-        "required": [
-          "source_field",
-          "result_label"
-        ],
-        "title": "extraction",
-        "type": "object"
+        }
       },
       "ErsMapping": {
+        "type": "object",
+        "title": "mapping",
+        "required": [
+          "result_labels"
+        ],
         "properties": {
-          "api_id": {
-            "description": "Mapping API ID (MongoDB ObjectID hex). Required when `mapping_type` is `api`.",
-            "type": "string"
+          "result_labels": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$"
+            },
+            "description": "Label keys to fill from the lookup result (at least one). For `schema` they are normally the schema's `result_labels`; for `api` they are sent to the API as `result_label_keys`.",
+            "minItems": 1
           },
           "mapping_type": {
-            "default": "schema",
-            "description": "Mapping source type. `schema` uses a mapping schema table; `api` calls an external HTTP API.",
+            "type": "string",
             "enum": [
               "schema",
               "api"
             ],
-            "type": "string"
+            "default": "schema",
+            "description": "Lookup source.\n- `schema` (default): look up a row in the mapping schema `schema_id` using the event's values of the schema's `source_labels`; the rule does nothing if any source label is missing or no row matches.\n- `api`: call the mapping API `api_id` with the event; runs for alert events only."
           },
-          "override": {
-            "description": "When `true`, overwrite labels that already exist. Defaults to `false`.",
-            "type": "boolean"
+          "schema_id": {
+            "type": "string",
+            "description": "Mapping schema ID (MongoDB ObjectID hex). Required when `mapping_type` is `schema`."
           },
-          "result_labels": {
-            "description": "Label keys to populate from the mapping lookup result. Each must match `^[a-zA-Z_][a-zA-Z0-9_]*$`.",
-            "items": {
-              "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$",
-              "type": "string"
-            },
-            "type": "array"
+          "api_id": {
+            "type": "string",
+            "description": "Mapping API ID (MongoDB ObjectID hex). Required when `mapping_type` is `api`."
           },
-          "schema_id": {
-            "description": "Mapping schema ID (MongoDB ObjectID hex). Required when `mapping_type` is `schema`.",
-            "type": "string"
+          "override": {
+            "type": "boolean",
+            "description": "When `false` (default) the rule is skipped if every label in `result_labels` already exists, and otherwise only the missing labels are filled. When `true` all `result_labels` are overwritten with the lookup result."
           }
-        },
-        "required": [
-          "result_labels"
-        ],
-        "title": "mapping",
-        "type": "object"
+        }
       },
       "EscalateLayer": {
+        "type": "object",
+        "required": [
+          "target"
+        ],
         "properties": {
-          "escalate_window": {
-            "description": "Wait before moving to the next level, in minutes.",
-            "maximum": 720,
-            "minimum": 0,
-            "type": "integer"
-          },
-          "force_escalate": {
-            "description": "When true, always escalate regardless of acknowledgement.",
-            "type": "boolean"
-          },
           "max_times": {
-            "description": "Max repeat notifications within the level.",
-            "maximum": 6,
+            "type": "integer",
             "minimum": 0,
-            "type": "integer"
+            "maximum": 6,
+            "description": "Total notifications sent in this level, including the first, 0–6; `0` and `1` both notify once."
           },
           "notify_step": {
-            "description": "Repeat interval in minutes.",
+            "type": "number",
             "format": "float",
-            "maximum": 120,
             "minimum": 0.5,
-            "type": "number"
+            "maximum": 120,
+            "description": "Minutes between repeat notifications in this level, 0.5–120, kept to one decimal place. Used only when `max_times` is greater than 1."
           },
           "target": {
             "$ref": "#/components/schemas/EscalateTarget"
+          },
+          "escalate_window": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 720,
+            "description": "Minutes to wait after this level's first notification before escalating to the next level, 0–720. Ignored on the last level."
+          },
+          "force_escalate": {
+            "type": "boolean",
+            "description": "When true, escalate even after the incident has been acknowledged (`Processing`). When false, escalation stops once the incident is acknowledged. Closed or snoozed incidents never escalate."
           }
-        },
-        "required": [
-          "target"
-        ],
-        "type": "object"
+        }
       },
       "EscalateRuleItem": {
+        "type": "object",
+        "required": [
+          "account_id",
+          "channel_id",
+          "priority",
+          "aggr_window",
+          "rule_name",
+          "description",
+          "layers",
+          "time_filters",
+          "filters",
+          "status",
+          "template_id",
+          "rule_id",
+          "updated_by",
+          "created_at",
+          "updated_at"
+        ],
         "properties": {
           "account_id": {
-            "description": "Owning account ID.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
-          },
-          "aggr_window": {
-            "description": "Delay window in seconds.",
-            "type": "integer"
+            "description": "Owning account ID."
           },
           "channel_id": {
-            "description": "Channel the rule belongs to.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Channel the rule belongs to."
           },
-          "channel_name": {
-            "description": "Channel name, populated for cross-channel listing responses.",
-            "type": "string"
+          "priority": {
+            "type": "integer",
+            "description": "Evaluation order from `0` to `200`: lower values are evaluated first, ties broken by creation time. The first enabled rule whose time windows and filters match a new incident takes it."
           },
-          "created_at": {
-            "description": "Creation time, Unix timestamp in seconds.",
-            "format": "int64",
-            "type": "integer"
+          "aggr_window": {
+            "type": "integer",
+            "description": "Delay in seconds, 0–3600, before the first notification for a newly assigned incident is sent; `0` notifies immediately."
           },
-          "deleted_at": {
-            "description": "Deletion time, Unix timestamp in seconds. Omitted unless the rule is soft-deleted; deleted rules are excluded from list responses.",
-            "format": "int64",
-            "type": "integer"
+          "rule_name": {
+            "type": "string",
+            "description": "Rule name, 1–39 characters."
           },
           "description": {
-            "description": "Rule description.",
-            "type": "string"
-          },
-          "filters": {
-            "$ref": "#/components/schemas/FilterGroup",
-            "description": "Incident-level match conditions (OR-of-AND tree): the rule is matched against the incident the alert was grouped into, not against the alert itself. Omit or leave empty to apply the rule to all incidents in the channel."
+            "type": "string",
+            "description": "Rule description."
           },
           "layers": {
-            "description": "Escalation levels in order.",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/EscalateLayer"
             },
-            "type": "array"
-          },
-          "priority": {
-            "description": "Evaluation priority. Lower runs first.",
-            "type": "integer"
+            "description": "Escalation levels in order."
           },
-          "rule_id": {
-            "description": "Escalation rule ID (MongoDB ObjectID).",
-            "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
+          "time_filters": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/TimeFilter"
+            },
+            "description": "Recurring time windows during which the rule can match; empty means at any time."
           },
-          "rule_name": {
-            "description": "Rule name.",
-            "type": "string"
+          "filters": {
+            "$ref": "#/components/schemas/FilterGroup",
+            "description": "Incident conditions (OR of AND groups), matched against the incident the alert was grouped into. Empty means the rule matches every incident in the channel."
           },
           "status": {
-            "description": "Rule status: `enabled` means active, `disabled` means paused, `deleted` is soft-deleted (possible only from the detail endpoint; lists never return deleted rules).",
+            "type": "string",
             "enum": [
               "enabled",
               "disabled",
               "deleted"
             ],
-            "type": "string"
+            "description": "Rule status: `enabled` means active, `disabled` means paused, `deleted` is soft-deleted (possible only from the detail endpoint; lists never return deleted rules)."
           },
           "template_id": {
-            "description": "Notification template ID (MongoDB ObjectID).",
+            "type": "string",
             "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
+            "description": "Notification template ID (24-character hex); see `POST /template/list`."
           },
-          "time_filters": {
-            "description": "Recurring time windows during which the rule applies.",
-            "items": {
-              "$ref": "#/components/schemas/TimeFilter"
-            },
-            "type": "array"
+          "rule_id": {
+            "type": "string",
+            "pattern": "^[0-9a-fA-F]{24}$",
+            "description": "Escalation rule ID (MongoDB ObjectID)."
           },
-          "updated_at": {
-            "description": "Last update time, Unix timestamp in seconds.",
+          "updated_by": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Member ID that last updated the rule."
           },
-          "updated_by": {
-            "description": "Member ID that last updated the rule.",
+          "deleted_at": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Deletion time, Unix timestamp in seconds. Omitted unless the rule is soft-deleted; deleted rules are excluded from list responses."
+          },
+          "created_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Creation time, Unix timestamp in seconds."
+          },
+          "updated_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Last update time, Unix timestamp in seconds."
           }
-        },
-        "required": [
-          "account_id",
-          "channel_id",
-          "priority",
-          "aggr_window",
-          "rule_name",
-          "description",
-          "layers",
-          "time_filters",
-          "filters",
-          "status",
-          "template_id",
-          "rule_id",
-          "updated_by",
-          "created_at",
-          "updated_at"
-        ],
-        "type": "object"
+        }
       },
       "EscalateTarget": {
+        "type": "object",
         "description": "Notification target. At least one of `person_ids`, `team_ids`, `schedule_to_role_ids`, or `emails` must be set, together with either `by` or `webhooks`.",
         "properties": {
+          "person_ids": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "int64"
+            },
+            "description": "Member IDs to notify directly; obtain them from `POST /member/list`. Every ID must exist."
+          },
+          "team_ids": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "int64"
+            },
+            "description": "Team IDs whose members are notified; obtain them from `POST /team/list`. Each team must have at least one member."
+          },
+          "schedule_to_role_ids": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "array",
+              "items": {
+                "type": "integer",
+                "format": "int64"
+              }
+            },
+            "description": "Notify whoever is on call: keys are schedule IDs (from `POST /schedule/list`) written as strings, values are the role IDs on that schedule. Each value must be non-empty."
+          },
+          "emails": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "format": "email"
+            },
+            "description": "Email addresses of account members; each address is resolved to the member who owns it when the level fires."
+          },
           "by": {
-            "description": "Per-severity personal notification channels. Required unless `webhooks` is provided.",
+            "type": [
+              "object",
+              "null"
+            ],
+            "description": "Personal notification channels for the people in this target, per incident severity. Required unless `webhooks` is set; returned as `null` when not set.",
             "properties": {
+              "follow_preference": {
+                "type": "boolean",
+                "description": "When true, each person is notified through the channels in their own notification preferences for the incident's severity, and `critical`, `warning` and `info` are ignored."
+              },
               "critical": {
-                "description": "Notify channels used for Critical severity. Personal channels: `sms`, `voice`, `email`, `push`; IM group-chat channels: `feishu_app:<chat_id>`, `dingtalk_app:<chat_id>`, `wecom_app:<chat_id>`, `slack_app:<chat_id>`, `teams_app:<chat_id>`.",
+                "type": "array",
                 "items": {
                   "type": "string"
                 },
-                "type": "array"
+                "description": "Channels used when the incident severity is `Critical`: `sms`, `voice`, `email`, `push`, or a direct message through an IM app integration written as `<app>:<integration_id>`, where `<app>` is `feishu_app`, `dingtalk_app`, `wecom_app`, `slack_app` or `teams_app` and `<integration_id>` is the ID of that IM integration. Other values return `InvalidParameter`."
               },
-              "follow_preference": {
-                "description": "When true, use each responder's personal preference instead of the lists below.",
-                "type": "boolean"
+              "warning": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "description": "Channels used when the incident severity is `Warning`; same values as `critical`."
               },
               "info": {
-                "description": "Notify channels used for Info severity. Values as for `critical`.",
+                "type": "array",
                 "items": {
                   "type": "string"
                 },
-                "type": "array"
-              },
-              "warning": {
-                "description": "Notify channels used for Warning severity. Values as for `critical`.",
-                "items": {
-                  "type": "string"
-                },
-                "type": "array"
+                "description": "Channels used when the incident severity is `Info`; same values as `critical`."
               }
-            },
-            "type": "object"
-          },
-          "emails": {
-            "description": "Email addresses to notify (push-only scenarios).",
-            "items": {
-              "format": "email",
-              "type": "string"
-            },
-            "type": "array"
-          },
-          "person_ids": {
-            "description": "Member IDs to notify directly.",
-            "items": {
-              "format": "int64",
-              "type": "integer"
-            },
-            "type": "array"
-          },
-          "schedule_to_role_ids": {
-            "additionalProperties": {
-              "items": {
-                "format": "int64",
-                "type": "integer"
-              },
-              "type": "array"
-            },
-            "description": "Map of schedule ID to the role IDs on that schedule to notify.",
-            "type": "object"
-          },
-          "team_ids": {
-            "description": "Team IDs to notify.",
-            "items": {
-              "format": "int64",
-              "type": "integer"
-            },
-            "type": "array"
+            }
           },
           "webhooks": {
-            "description": "Group chat / webhook targets. Required unless `by` is provided.",
+            "type": [
+              "array",
+              "null"
+            ],
+            "description": "Group chats to notify through robots or IM apps. Required unless `by` is set; returned as `null` when not set.",
             "items": {
-              "properties": {
-                "settings": {
-                  "additionalProperties": true,
-                  "description": "Type-specific settings (chat IDs, URLs, etc.).",
-                  "type": "object"
-                },
-                "type": {
-                  "description": "Webhook type, one of `feishu`, `feishu_app`, `dingtalk`, `dingtalk_app`, `wecom`, `slack`, `slack_app`, `teams_app`, `telegram`, `zoom`.",
-                  "type": "string"
-                }
-              },
+              "type": "object",
               "required": [
                 "type",
                 "settings"
               ],
-              "type": "object"
-            },
-            "type": "array"
+              "properties": {
+                "type": {
+                  "type": "string",
+                  "description": "Delivery type:\n- `feishu`, `dingtalk`, `wecom`, `slack`, `telegram`, `zoom`: a group robot (incoming webhook) of that IM.\n- `feishu_app`, `dingtalk_app`, `slack_app`, `teams_app`: group chats reached through the corresponding IM app integration.",
+                  "enum": [
+                    "feishu",
+                    "dingtalk",
+                    "wecom",
+                    "slack",
+                    "telegram",
+                    "zoom",
+                    "feishu_app",
+                    "dingtalk_app",
+                    "slack_app",
+                    "teams_app"
+                  ]
+                },
+                "settings": {
+                  "type": "object",
+                  "additionalProperties": true,
+                  "description": "Type-specific settings, such as the robot's webhook token or the app's chat IDs; `feishu_app` and `dingtalk_app` require it. To see the exact shape for a type, configure one in the console and read it back with `POST /channel/escalate/rule/info`."
+                }
+              }
+            }
           }
-        },
-        "type": "object"
+        }
       },
       "EventGroup": {
+        "type": "object",
         "description": "Alert event merge configuration. When enabled, repeated incoming events of the same alert are merged into the existing alert within the time window instead of creating new alerts.",
         "properties": {
           "is_enabled": {
-            "description": "When true, repeated events merge into the existing alert; when false, every event creates a separate alert. Defaults to true.",
-            "type": "boolean"
+            "type": "boolean",
+            "description": "When true, repeated events of the same alert merge into the existing alert; when false, every event creates a separate alert. If you send `event_group`, set this explicitly: an omitted value means `false`. When the whole `event_group` is omitted on create, merging is enabled."
           },
           "time_window": {
-            "description": "Merge window in minutes, 1-1440 (24 h); accounts with the extended limit may use up to 10080 (7 days). Defaults to 1440.",
+            "type": "integer",
             "minimum": 1,
-            "type": "integer"
+            "description": "Merge window in minutes, required when `is_enabled` is true. The range is 1–1440 by default; accounts with the extended merge window enabled can set up to 10080 (7 days). Ignored when merging is disabled."
           }
-        },
-        "type": "object"
+        }
       },
       "EventItem": {
+        "type": "object",
         "description": "One persisted session event. content/actions/usage_metadata carry the raw ADK envelope; treat them as opaque structured payloads.",
         "properties": {
-          "actions": {
-            "additionalProperties": true,
-            "description": "ADK actions envelope (state deltas, transfers, escalation).",
-            "type": "object"
+          "event_id": {
+            "type": "string",
+            "description": "Event identifier."
+          },
+          "session_id": {
+            "type": "string",
+            "description": "Owning session id."
+          },
+          "invocation_id": {
+            "type": "string",
+            "description": "ID of the invocation (one agent turn) that wrote this event. Omitted when empty."
+          },
+          "root_invocation_id": {
+            "type": "string",
+            "description": "Invocation ID of the top-level user turn this event belongs to, linking events written by nested subagent invocations back to it. Omitted when empty."
+          },
+          "delivery_mode": {
+            "type": "string",
+            "enum": [
+              "reply_only"
+            ],
+            "description": "Delivery mode negotiated for the IM request that produced this event. `reply_only`: the IM client shows only explicit replies, not the agent's final text. Omitted for normal delivery."
+          },
+          "is_error": {
+            "type": "boolean",
+            "description": "True when this is an assistant event recording a runtime failure whose message is safe to show to users. Omitted when false."
           },
           "author": {
-            "description": "Event author (e.g. user, the agent name).",
-            "type": "string"
+            "type": "string",
+            "description": "Event author (e.g. user, the agent name)."
+          },
+          "person_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Member ID of the person who sent this user message. Omitted on assistant and tool events and when no member is recorded (automation runs, some IM turns)."
           },
           "branch": {
-            "description": "ADK branch path for nested agents.",
-            "type": "string"
+            "type": "string",
+            "description": "ADK branch path for nested agents."
           },
           "content": {
+            "type": "object",
             "additionalProperties": true,
-            "description": "ADK content envelope {role, parts:[...]}.",
-            "type": "object"
+            "description": "ADK content envelope {role, parts:[...]}."
           },
-          "created_at": {
-            "description": "Unix timestamp in milliseconds when the event was written.",
-            "format": "int64",
-            "type": "integer"
-          },
-          "error_code": {
-            "description": "Error code when the event represents a failure.",
-            "type": "string"
+          "actions": {
+            "type": "object",
+            "additionalProperties": true,
+            "description": "ADK actions envelope (state deltas, transfers, escalation)."
           },
-          "error_message": {
-            "description": "Human-readable error message, when present.",
-            "type": "string"
+          "usage_metadata": {
+            "type": "object",
+            "additionalProperties": true,
+            "description": "Per-turn token usage metadata."
           },
-          "event_id": {
-            "description": "Event identifier.",
-            "type": "string"
+          "partial": {
+            "type": "boolean",
+            "description": "True for a streaming partial chunk."
           },
-          "invocation_id": {
-            "description": "ADK invocation id grouping a turn.",
-            "type": "string"
+          "turn_complete": {
+            "type": "boolean",
+            "description": "True on the terminal event of a turn."
           },
-          "partial": {
-            "description": "True for a streaming partial chunk.",
-            "type": "boolean"
+          "error_code": {
+            "type": "string",
+            "description": "Error code when the event represents a failure."
           },
-          "session_id": {
-            "description": "Owning session id.",
-            "type": "string"
+          "error_message": {
+            "type": "string",
+            "description": "Human-readable error message, when present."
           },
           "status": {
+            "type": "string",
             "description": "Event status. One of: `normal` (a live event included in the context fed to the model), `compressed` (folded into a compaction summary boundary event; no longer loaded for the model, kept as history only).",
             "enum": [
               "normal",
               "compressed"
-            ],
-            "type": "string"
-          },
-          "turn_complete": {
-            "description": "True on the terminal event of a turn.",
-            "type": "boolean"
+            ]
           },
-          "usage_metadata": {
-            "additionalProperties": true,
-            "description": "Per-turn token usage metadata.",
-            "type": "object"
+          "created_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Unix timestamp in milliseconds when the event was written."
           }
         },
         "required": [
@@ -9259,8 +9384,7 @@
           "partial",
           "turn_complete",
           "created_at"
-        ],
-        "type": "object"
+        ]
       },
       "ExploreData": {
         "description": "Explore query result payload.",
@@ -9286,67 +9410,78 @@
         "type": "object"
       },
       "ExploreField": {
+        "type": "object",
         "description": "One column of a frame. Values are columnar and may contain nulls.",
+        "required": [
+          "name",
+          "type",
+          "values"
+        ],
         "properties": {
-          "labels": {
-            "additionalProperties": {
-              "type": "string"
-            },
-            "description": "Label set of this column. Only `time_series` value fields may carry labels; a `table` field must not.",
-            "type": "object"
-          },
           "name": {
-            "description": "Column name, at most 1 MiB of UTF-8.",
-            "type": "string"
+            "type": "string",
+            "description": "Column name, at most 1 MiB of UTF-8."
           },
           "type": {
-            "description": "Column type. `string` is rejected inside a `time_series` frame; `float` holds numbers and `time` holds UTC RFC3339Nano strings.",
+            "type": "string",
             "enum": [
               "string",
               "float",
               "time"
             ],
-            "type": "string"
+            "description": "Column type. `string` is rejected inside a `time_series` frame; `float` holds numbers and `time` holds UTC RFC3339Nano strings."
+          },
+          "labels": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "string"
+            },
+            "description": "Label set of this column. Only `time_series` value fields may carry labels; a `table` field must not."
           },
           "values": {
-            "description": "Column values in row order.",
+            "type": "array",
             "items": {
+              "oneOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "number"
+                },
+                {
+                  "type": "null"
+                }
+              ],
               "description": "One cell. `time` cells are UTC RFC3339Nano strings; `float` cells may be the strings `NaN`, `+Inf`, and `-Inf`; any cell may be null except a time value inside a `time_series` frame."
             },
-            "type": "array"
+            "description": "Column values in row order."
           }
-        },
-        "required": [
-          "name",
-          "type",
-          "values"
-        ],
-        "type": "object"
+        }
       },
       "ExploreFrame": {
+        "type": "object",
         "description": "One columnar frame. Every field in the frame has the same number of values.",
+        "required": [
+          "kind",
+          "fields"
+        ],
         "properties": {
-          "fields": {
-            "description": "Columns of the frame.",
-            "items": {
-              "$ref": "#/components/schemas/ExploreField"
-            },
-            "type": "array"
-          },
           "kind": {
-            "description": "Frame shape. `table` is an unlabeled table, while `time_series` carries exactly one time field and one float field.",
+            "type": "string",
             "enum": [
               "table",
               "time_series"
             ],
-            "type": "string"
+            "description": "Frame shape. `table` is an unlabeled table. `time_series` carries exactly one time field and one float field; its time values are strictly increasing and never null."
+          },
+          "fields": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/ExploreField"
+            },
+            "description": "Columns of the frame."
           }
-        },
-        "required": [
-          "kind",
-          "fields"
-        ],
-        "type": "object"
+        }
       },
       "ExploreLogEntry": {
         "description": "One log entry.",
@@ -9390,71 +9525,79 @@
         "type": "object"
       },
       "ExploreResult": {
+        "type": "object",
         "description": "Result body. Exactly one of `frames`, `samples`, or `entries` is present and matches `kind`.",
+        "required": [
+          "kind"
+        ],
         "properties": {
-          "applied_limit": {
-            "description": "Entry limit applied to a logs result; at most 1000.",
-            "type": "integer"
-          },
-          "entries": {
-            "description": "Log entries. Present when `kind` is `logs`; never longer than `applied_limit`.",
-            "items": {
-              "$ref": "#/components/schemas/ExploreLogEntry"
-            },
-            "type": "array"
-          },
-          "frames": {
-            "description": "Columnar frames. Present when `kind` is `frames`; at most 1,000 frames.",
-            "items": {
-              "$ref": "#/components/schemas/ExploreFrame"
-            },
-            "type": "array"
-          },
-          "has_more": {
-            "description": "Whether a logs result was truncated by `applied_limit`.",
-            "type": "boolean"
-          },
           "kind": {
-            "description": "Result shape. `frames` returns columnar tables or time series, `samples` returns instant values with labels, and `logs` returns log entries.",
+            "type": "string",
             "enum": [
               "frames",
               "samples",
               "logs"
             ],
-            "type": "string"
+            "description": "Result shape. `frames` returns columnar tables or time series, `samples` returns instant values with labels, and `logs` returns log entries."
+          },
+          "frames": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/ExploreFrame"
+            },
+            "description": "Columnar frames. Present when `kind` is `frames`; at most 1,000 frames, 1,000 table rows in total, and 100,000 values in total."
           },
           "samples": {
-            "description": "Instant samples. Present when `kind` is `samples`; at most 1,000 samples.",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/ExploreSample"
             },
-            "type": "array"
+            "description": "Instant samples. Present when `kind` is `samples`; at most 1,000 samples."
+          },
+          "entries": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/ExploreLogEntry"
+            },
+            "description": "Log entries. Present when `kind` is `logs`; never longer than `applied_limit`."
+          },
+          "applied_limit": {
+            "type": "integer",
+            "description": "Entry limit applied to a logs result: 1 to 1000 (1 to 100 for `sls` data sources). Present only when `kind` is `logs`."
+          },
+          "has_more": {
+            "type": "boolean",
+            "description": "Whether a logs result was truncated by `applied_limit`."
           }
-        },
-        "required": [
-          "kind"
-        ],
-        "type": "object"
+        }
       },
       "ExploreSample": {
+        "type": "object",
         "description": "One instant sample.",
+        "required": [
+          "labels",
+          "value"
+        ],
         "properties": {
           "labels": {
+            "type": "object",
             "additionalProperties": {
               "type": "string"
             },
-            "description": "Label set of the sample. May be empty but never null.",
-            "type": "object"
+            "description": "Label set of the sample. May be empty but never null."
           },
           "value": {
+            "oneOf": [
+              {
+                "type": "number"
+              },
+              {
+                "type": "string"
+              }
+            ],
             "description": "Sample value: a number, or one of the strings `NaN`, `+Inf`, and `-Inf`. Never null."
           }
-        },
-        "required": [
-          "labels",
-          "value"
-        ],
-        "type": "object"
+        }
       },
       "PrometheusLabelValuesResponse": {
         "description": "Native Prometheus HTTP API response returned by the queried data source. This endpoint does not wrap the payload in the Flashduty response envelope.",
@@ -9490,80 +9633,82 @@
         "type": "object"
       },
       "QueryExploreExecution": {
-        "description": "Time semantics of the query. The accepted companion fields depend on `kind`: `instant` takes only `to_ms` (plus optional `from_ms`), `range` requires `from_ms`, `to_ms`, and `max_data_points`, and `window` takes only `from_ms` and `to_ms`. `step_seconds` is never accepted over HTTP.",
+        "type": "object",
+        "description": "Time semantics of the query. The accepted companion fields depend on `kind`: `instant` takes `to_ms` (and optionally `from_ms`), `range` requires `from_ms`, `to_ms`, and `max_data_points`, and `window` takes only `from_ms` and `to_ms`. When both times are present, `from_ms` must be less than `to_ms`. `step_seconds` is never accepted over HTTP.",
+        "required": [
+          "kind"
+        ],
         "properties": {
-          "from_ms": {
-            "description": "Unix timestamp in milliseconds for the start of the range. Required for `range` and `window`; optional for `instant`.",
-            "format": "int64",
-            "type": "integer"
-          },
           "kind": {
-            "description": "Execution kind. `instant` evaluates at a single point in time, `range` evaluates a series over a range, and `window` returns raw rows inside a time window.",
+            "type": "string",
             "enum": [
               "instant",
               "range",
               "window"
             ],
-            "type": "string"
+            "description": "Execution kind.\n\n- `instant`: evaluate at a single point in time.\n- `range`: evaluate a series over `from_ms` to `to_ms`, with a step derived from `max_data_points` and `min_step_seconds`.\n- `window`: query the interval from `from_ms` to `to_ms` with no step."
+          },
+          "from_ms": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Start of the interval as a Unix timestamp in milliseconds; non-negative and less than `to_ms`. Required for `range` and `window`; optional for `instant`.",
+            "minimum": 0
+          },
+          "to_ms": {
+            "type": "integer",
+            "format": "int64",
+            "description": "End of the interval (or the evaluation time for `instant`) as a Unix timestamp in milliseconds; non-negative. Required for every execution kind.",
+            "minimum": 0
           },
           "max_data_points": {
-            "description": "Maximum number of points to return. Required for `range` and rejected for `instant` and `window`.",
+            "type": "integer",
             "format": "int64",
-            "maximum": 5000,
             "minimum": 2,
-            "type": "integer"
+            "maximum": 5000,
+            "description": "Maximum number of points to return. Required for `range` and rejected for `instant` and `window`."
           },
           "min_step_seconds": {
-            "description": "Lower bound, in seconds, for the step derived from `max_data_points`. Optional and only accepted for `range`.",
+            "type": "integer",
             "format": "int64",
             "minimum": 1,
-            "type": "integer"
-          },
-          "to_ms": {
-            "description": "Unix timestamp in milliseconds for the end of the range. Required for every execution kind.",
-            "format": "int64",
-            "type": "integer"
+            "description": "Lower bound, in seconds, for the step derived from `max_data_points`. Optional and only accepted for `range`."
           }
-        },
-        "required": [
-          "kind"
-        ],
-        "type": "object"
+        }
       },
       "QueryExploreRequest": {
+        "type": "object",
         "description": "Explore query request. All four top-level fields are required and unknown fields are rejected.",
+        "required": [
+          "datasource_id",
+          "expr",
+          "args",
+          "execution"
+        ],
         "properties": {
+          "datasource_id": {
+            "type": "integer",
+            "format": "int64",
+            "minimum": 1,
+            "maximum": 9007199254740991,
+            "description": "Data source ID from `/monit/datasource/list`. Must be a positive JavaScript-safe integer for an enabled data source of the authenticated account that the caller may query."
+          },
+          "expr": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Query expression in the data source's native language (PromQL, LogsQL, SQL, and so on). Non-empty UTF-8 of at most 64 KiB; `mysql` allows at most 16 KiB and `tencent_cls` at most 12 KiB."
+          },
           "args": {
+            "type": "object",
             "additionalProperties": {
               "type": "string"
             },
-            "description": "Macro substitutions keyed by variable name, used for Grafana-style variables. Keys are at most 256 bytes, values at most 64 KiB, with a 128 KiB total budget.",
             "maxProperties": 128,
-            "type": "object"
-          },
-          "datasource_id": {
-            "description": "Data source ID from `/monit/datasource/list`. Must be a positive JavaScript-safe integer and belong to the authenticated account.",
-            "format": "int64",
-            "maximum": 9007199254740991,
-            "minimum": 1,
-            "type": "integer"
+            "description": "Macro substitutions keyed by variable name, used for Grafana-style variables. Keys are at most 256 bytes, values at most 64 KiB, with a 128 KiB total budget."
           },
           "execution": {
             "$ref": "#/components/schemas/QueryExploreExecution"
-          },
-          "expr": {
-            "description": "Query expression in the data source's native language (PromQL, LogsQL, SQL, and so on). Non-empty UTF-8 of at most 64 KiB; some data source types enforce a lower limit.",
-            "minLength": 1,
-            "type": "string"
           }
-        },
-        "required": [
-          "datasource_id",
-          "expr",
-          "args",
-          "execution"
-        ],
-        "type": "object"
+        }
       },
       "ExportStatusPageSubscribersRequest": {
         "description": "Parameters for exporting a status page subscriber list.",
@@ -9587,43 +9732,43 @@
         "type": "object"
       },
       "ExportedStatusPageSubscriberItem": {
+        "type": "object",
         "description": "A status page subscriber, as returned by the subscriber list and export endpoints.",
+        "required": [
+          "recipient",
+          "method",
+          "components",
+          "all"
+        ],
         "properties": {
-          "all": {
-            "description": "Whether the subscriber is subscribed to all components.",
-            "type": "boolean"
-          },
-          "components": {
-            "description": "Components this subscriber has subscribed to.",
-            "items": {
-              "$ref": "#/components/schemas/StatusPageComponentItem"
-            },
-            "type": "array"
-          },
-          "locale": {
-            "description": "Preferred locale for notifications. Omitted when empty.",
-            "type": "string"
+          "recipient": {
+            "type": "string",
+            "description": "Subscriber recipient: email address for public pages, user ID for internal pages."
           },
           "method": {
-            "description": "Subscription notification method. `email` is email subscription (public pages); `im` is IM subscription (internal pages). Determined by the page type.",
+            "type": "string",
             "enum": [
               "email",
               "im"
             ],
-            "type": "string"
+            "description": "Subscription notification method. `email` is email subscription (public pages); `im` is IM subscription (internal pages). Determined by the page type."
           },
-          "recipient": {
-            "description": "Subscriber recipient: email address for public pages, user ID for internal pages.",
-            "type": "string"
+          "components": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/StatusPageComponentItem"
+            },
+            "description": "Components the subscriber follows; each item carries only `component_id` and `name`. Empty when `all` is `true`."
+          },
+          "all": {
+            "type": "boolean",
+            "description": "Whether the subscriber is subscribed to all components."
+          },
+          "locale": {
+            "type": "string",
+            "description": "Preferred locale for notifications. Omitted when empty."
           }
-        },
-        "required": [
-          "recipient",
-          "method",
-          "components",
-          "all"
-        ],
-        "type": "object"
+        }
       },
       "FacetCountItem": {
         "description": "A facet value and its occurrence count.",
@@ -9792,26 +9937,29 @@
         "type": "object"
       },
       "FeedDetailIncidentAck": {
+        "type": "object",
         "description": "Detail payload for `i_ack`.",
         "properties": {
+          "progress": {
+            "type": "string",
+            "description": "`Processing` when this acknowledgement moved the incident from `Triggered` to `Processing`; omitted when the incident was already `Processing`.",
+            "enum": [
+              "Processing"
+            ]
+          },
           "comment": {
-            "description": "Form summary recorded as a timeline comment. Omitted when no acknowledgement form summary was submitted.",
-            "type": "string"
+            "type": "string",
+            "description": "Form summary recorded as a timeline comment. Omitted when no acknowledgement form summary was submitted."
           },
           "images": {
-            "description": "Images from the acknowledgement form, recorded on the timeline entry only. Omitted when none were submitted.",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/Image"
             },
-            "type": "array"
-          },
-          "progress": {
-            "description": "Progress note entered at acknowledgement.",
-            "type": "string"
+            "description": "Images from the acknowledgement form, recorded on the timeline entry only. Omitted when none were submitted."
           }
         },
-        "title": "i_ack",
-        "type": "object"
+        "title": "i_ack"
       },
       "FeedDetailIncidentAddRspd": {
         "description": "Detail payload for `i_a_rspd`.",
@@ -9859,27 +10007,28 @@
         "type": "object"
       },
       "FeedDetailIncidentComment": {
+        "type": "object",
         "description": "Detail payload for `i_comm`.",
         "properties": {
           "comment": {
-            "description": "Comment body.",
-            "type": "string"
+            "type": "string",
+            "description": "Comment body."
           },
-          "comment_type": {
-            "$ref": "#/components/schemas/IncidentCommentTypeDisplay"
+          "mute_reply": {
+            "type": "boolean",
+            "description": "Whether replies to this comment are muted."
           },
           "comment_type_id": {
-            "description": "ObjectID of the account-level comment type attached to the comment.",
+            "type": "string",
             "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
+            "description": "ObjectID of the account-level comment type attached to the comment."
           },
-          "mute_reply": {
-            "description": "Whether replies to this comment are muted.",
-            "type": "boolean"
+          "comment_type": {
+            "$ref": "#/components/schemas/IncidentCommentTypeDisplay",
+            "description": "Name and color of the attached comment type, resolved at read time; omitted when no comment type is attached or it no longer exists."
           }
         },
-        "title": "i_comm",
-        "type": "object"
+        "title": "i_comm"
       },
       "FeedDetailIncidentCustomAction": {
         "description": "Detail payload for `i_custom`.",
@@ -9898,46 +10047,47 @@
         "type": "object"
       },
       "FeedDetailIncidentMerge": {
+        "type": "object",
         "description": "Detail payload for `i_merge`.",
         "properties": {
           "comment": {
-            "description": "Merge comment.",
-            "type": "string"
-          },
-          "owner_id": {
-            "description": "Member ID that performed the merge.",
-            "format": "int64",
-            "type": "integer"
-          },
-          "remove_source_incidents": {
-            "description": "True if the source incidents were removed after merging.",
-            "type": "boolean"
+            "type": "string",
+            "description": "Merge comment."
           },
           "source_incidents": {
-            "description": "Source incidents that were merged.",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/IncidentShort"
             },
-            "type": "array"
-          },
-          "source_responders": {
-            "description": "Responder member IDs carried over from the source incidents.",
-            "items": {
-              "format": "int64",
-              "type": "integer"
-            },
-            "type": "array"
+            "description": "Incidents merged into the target; present on the target incident's entry."
           },
           "target_incident": {
-            "$ref": "#/components/schemas/IncidentShort"
+            "$ref": "#/components/schemas/IncidentShort",
+            "description": "Incident this incident was merged into; present on each source incident's entry."
+          },
+          "owner_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Not set by incident merges, which never change the owner; present only on older entries."
           },
           "title": {
-            "description": "Resulting incident title.",
-            "type": "string"
+            "type": "string",
+            "description": "New title the merge set on the target incident; present only on the target's entry and only when the title changed."
+          },
+          "remove_source_incidents": {
+            "type": "boolean",
+            "description": "`true` when the source incidents were permanently deleted after the merge."
+          },
+          "source_responders": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "int64"
+            },
+            "description": "Member IDs that were responders on the source incidents, for reference; they are not added to the target's responders."
           }
         },
-        "title": "i_merge",
-        "type": "object"
+        "title": "i_merge"
       },
       "FeedDetailIncidentMuteByFlapping": {
         "description": "Detail payload for `i_m_flapping`.",
@@ -9966,22 +10116,23 @@
         "type": "object"
       },
       "FeedDetailIncidentNew": {
+        "type": "object",
         "description": "Detail payload for `i_new`.",
         "properties": {
-          "reporter_email": {
-            "description": "Email of the reporter when the incident was created externally.",
-            "type": "string"
-          },
           "severity": {
-            "$ref": "#/components/schemas/FeedSeverity"
+            "$ref": "#/components/schemas/FeedSeverity",
+            "description": "Severity of the incident when it was created."
           },
           "title": {
-            "description": "Initial incident title.",
-            "type": "string"
+            "type": "string",
+            "description": "Initial incident title."
+          },
+          "reporter_email": {
+            "type": "string",
+            "description": "Email of the reporter when the incident was created externally."
           }
         },
-        "title": "i_new",
-        "type": "object"
+        "title": "i_new"
       },
       "FeedDetailIncidentNotify": {
         "description": "Detail payload for `i_notify`.",
@@ -10048,15 +10199,15 @@
         "type": "object"
       },
       "FeedDetailIncidentReopen": {
+        "type": "object",
         "description": "Detail payload for `i_reopen`.",
         "properties": {
           "reason": {
-            "description": "Reason why the incident was reopened.",
-            "type": "string"
+            "type": "string",
+            "description": "Free-text reason passed as `reason` to `POST /incident/reopen`; omitted when none was given."
           }
         },
-        "title": "i_reopen",
-        "type": "object"
+        "title": "i_reopen"
       },
       "FeedDetailIncidentResetDescription": {
         "additionalProperties": false,
@@ -10104,32 +10255,34 @@
         "type": "object"
       },
       "FeedDetailIncidentResetSeverity": {
+        "type": "object",
         "description": "Detail payload for `i_r_severity`.",
         "properties": {
           "from": {
-            "$ref": "#/components/schemas/FeedSeverity"
+            "$ref": "#/components/schemas/FeedSeverity",
+            "description": "Severity before the change."
           },
           "to": {
-            "$ref": "#/components/schemas/FeedSeverity"
+            "$ref": "#/components/schemas/FeedSeverity",
+            "description": "Severity after the change."
           }
         },
-        "title": "i_r_severity",
-        "type": "object"
+        "title": "i_r_severity"
       },
       "FeedDetailIncidentResetTitle": {
+        "type": "object",
         "description": "Detail payload for `i_r_title`.",
         "properties": {
           "from": {
-            "description": "Previous title.",
-            "type": "string"
+            "type": "string",
+            "description": "Title before the change."
           },
           "to": {
-            "description": "New title.",
-            "type": "string"
+            "type": "string",
+            "description": "Title after the change."
           }
         },
-        "title": "i_r_title",
-        "type": "object"
+        "title": "i_r_title"
       },
       "FeedDetailIncidentResolve": {
         "description": "Detail payload for `i_rslv`.",
@@ -10190,113 +10343,150 @@
         "type": "object"
       },
       "FeedDetailIncidentUnack": {
+        "type": "object",
         "description": "Detail payload for `i_unack`.",
         "properties": {
           "progress": {
-            "description": "Progress note entered when acknowledgement was removed.",
-            "type": "string"
+            "type": "string",
+            "description": "`Triggered` when removing this acknowledgement returned the incident to `Triggered` (no responder still acknowledged); omitted otherwise.",
+            "enum": [
+              "Triggered"
+            ]
           }
         },
-        "title": "i_unack",
-        "type": "object"
+        "title": "i_unack"
       },
       "FeedDetailIncidentWake": {
+        "type": "object",
         "description": "Detail payload for `i_wake`.",
         "properties": {
           "snoozedBefore": {
-            "description": "Unix timestamp at which the prior snooze was scheduled to end.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Unix timestamp (seconds) at which the cancelled snooze would have ended."
           }
         },
-        "title": "i_wake",
-        "type": "object"
+        "title": "i_wake"
       },
       "FeedDetailIncidentWarRoomCreate": {
+        "type": "object",
         "description": "Detail payload for `i_wr_create`.",
         "properties": {
+          "integration_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Integration ID that hosts the war room chat group."
+          },
           "chat_id": {
-            "description": "Chat group identifier.",
-            "type": "string"
+            "type": "string",
+            "description": "Chat group identifier."
           },
           "chat_name": {
-            "description": "Chat group display name.",
-            "type": "string"
+            "type": "string",
+            "description": "Chat group display name."
           },
-          "integration_id": {
-            "description": "Integration ID that hosts the war room chat group.",
-            "format": "int64",
-            "type": "integer"
+          "plugin_type": {
+            "type": "string",
+            "description": "Plugin type of the IM integration: `feishu_app` (Feishu), `dingtalk_app` (DingTalk), `wecom_app` (WeCom), or `slack_app` (Slack).",
+            "enum": [
+              "feishu_app",
+              "dingtalk_app",
+              "wecom_app",
+              "slack_app"
+            ]
           },
           "integration_name": {
-            "description": "Integration display name.",
-            "type": "string"
-          },
-          "plugin_type": {
-            "description": "Chat integration plugin type.",
-            "type": "string"
+            "type": "string",
+            "description": "Integration display name."
           },
           "share_link": {
-            "description": "Shareable join link for the war room.",
-            "type": "string"
+            "type": "string",
+            "description": "Shareable join link for the war room."
           }
         },
-        "title": "i_wr_create",
-        "type": "object"
+        "title": "i_wr_create"
       },
       "FeedDetailIncidentWarRoomDelete": {
+        "type": "object",
         "description": "Detail payload for `i_wr_delete`.",
         "properties": {
+          "integration_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Integration ID that hosted the war room chat group."
+          },
+          "unlink_only": {
+            "type": "boolean",
+            "description": "`true` when the war room was only unlinked from the incident (`unlink_only` request) and the group was not dissolved. Omitted otherwise."
+          },
           "chat_id": {
-            "description": "Chat group identifier.",
-            "type": "string"
+            "type": "string",
+            "description": "Chat group identifier."
           },
           "chat_name": {
-            "description": "Chat group display name.",
-            "type": "string"
+            "type": "string",
+            "description": "Chat group display name."
           },
-          "integration_id": {
-            "description": "Integration ID that hosted the war room chat group.",
-            "format": "int64",
-            "type": "integer"
+          "plugin_type": {
+            "type": "string",
+            "description": "Plugin type of the IM integration: `feishu_app` (Feishu), `dingtalk_app` (DingTalk), `wecom_app` (WeCom), or `slack_app` (Slack).",
+            "enum": [
+              "feishu_app",
+              "dingtalk_app",
+              "wecom_app",
+              "slack_app"
+            ]
           },
           "integration_name": {
-            "description": "Integration display name.",
-            "type": "string"
-          },
-          "plugin_type": {
-            "description": "Chat integration plugin type.",
-            "type": "string"
+            "type": "string",
+            "description": "Integration display name."
           }
         },
-        "title": "i_wr_delete",
-        "type": "object"
+        "title": "i_wr_delete"
       },
       "FeedDetailWorkItemAssigneesChanged": {
+        "type": "object",
         "description": "Detail payload for `i_wi_assignees`.",
         "properties": {
-          "added_assignee_ids": {
-            "description": "Member IDs added as assignees.",
+          "work_item_id": {
+            "type": "string",
+            "description": "Work item ID (`wi_` followed by a random string); use it with the `/incident/work-item/*` endpoints."
+          },
+          "item_type": {
+            "type": "string",
+            "enum": [
+              "action",
+              "follow_up"
+            ],
+            "description": "Work item type. `action`: an action item anchored to the incident itself; `follow_up`: an improvement item anchored to a post-mortem."
+          },
+          "title": {
+            "type": "string",
+            "description": "Work item title."
+          },
+          "assignee_ids": {
+            "type": "array",
             "items": {
-              "format": "int64",
-              "type": "integer"
+              "type": "integer",
+              "format": "int64"
             },
-            "type": "array"
+            "description": "Assignee member IDs after the change."
           },
-          "added_assignees": {
+          "added_assignee_ids": {
             "type": "array",
             "items": {
-              "$ref": "#/components/schemas/WorkItemAssignee"
+              "type": "integer",
+              "format": "int64"
             },
-            "description": "Assignees added by this change, in submitted order. `added_assignee_ids` is the person-only subset. Omitted when nothing was added."
+            "description": "Member IDs added as assignees."
           },
-          "assignee_ids": {
-            "description": "Assignee member IDs after the change.",
+          "removed_assignee_ids": {
+            "type": "array",
             "items": {
-              "format": "int64",
-              "type": "integer"
+              "type": "integer",
+              "format": "int64"
             },
-            "type": "array"
+            "description": "Member IDs removed from assignees."
           },
           "assignees": {
             "type": "array",
@@ -10305,21 +10495,12 @@
             },
             "description": "Assignees of the work item. Each entry is `{type, id?}`; an `ai_sre` entry omits `id`. Omitted when there is no assignee."
           },
-          "item_type": {
-            "description": "Work item type. `action`: an action item anchored to the incident itself; `follow_up`: an improvement item anchored to a post-mortem.",
-            "enum": [
-              "action",
-              "follow_up"
-            ],
-            "type": "string"
-          },
-          "removed_assignee_ids": {
-            "description": "Member IDs removed from assignees.",
+          "added_assignees": {
+            "type": "array",
             "items": {
-              "format": "int64",
-              "type": "integer"
+              "$ref": "#/components/schemas/WorkItemAssignee"
             },
-            "type": "array"
+            "description": "Assignees added by this change, in submitted order. `added_assignee_ids` is the person-only subset. Omitted when nothing was added."
           },
           "removed_assignees": {
             "type": "array",
@@ -10327,130 +10508,151 @@
               "$ref": "#/components/schemas/WorkItemAssignee"
             },
             "description": "Assignees removed by this change. `removed_assignee_ids` is the person-only subset. Omitted when nothing was removed."
-          },
-          "title": {
-            "description": "Work item title.",
-            "type": "string"
-          },
-          "work_item_id": {
-            "description": "Work item ID.",
-            "type": "string"
           }
         },
-        "title": "i_wi_assignees",
-        "type": "object"
+        "title": "i_wi_assignees"
       },
       "FeedDetailWorkItemBound": {
+        "type": "object",
         "description": "Detail payload for `i_wi_bound`.",
         "properties": {
+          "work_item_id": {
+            "type": "string",
+            "description": "Work item ID (`wi_` followed by a random string); use it with the `/incident/work-item/*` endpoints."
+          },
           "item_type": {
-            "description": "Work item type. `action`: an action item anchored to the incident itself; `follow_up`: an improvement item anchored to a post-mortem.",
+            "type": "string",
             "enum": [
               "action",
               "follow_up"
             ],
-            "type": "string"
-          },
-          "post_mortem_id": {
-            "description": "ID of the post-mortem the work item is bound to.",
-            "type": "string"
+            "description": "Work item type. `action`: an action item anchored to the incident itself; `follow_up`: an improvement item anchored to a post-mortem."
           },
           "title": {
-            "description": "Work item title.",
-            "type": "string"
+            "type": "string",
+            "description": "Work item title."
           },
-          "work_item_id": {
-            "description": "Work item ID.",
-            "type": "string"
+          "post_mortem_id": {
+            "type": "string",
+            "description": "ID of the post-mortem the work item is bound to."
           }
         },
-        "title": "i_wi_bound",
-        "type": "object"
+        "title": "i_wi_bound"
       },
       "FeedDetailWorkItemCompleted": {
+        "type": "object",
         "description": "Detail payload for `i_wi_completed`.",
         "properties": {
-          "from_status": {
-            "description": "Status label before completion.",
-            "type": "string"
+          "work_item_id": {
+            "type": "string",
+            "description": "Work item ID (`wi_` followed by a random string); use it with the `/incident/work-item/*` endpoints."
           },
           "item_type": {
-            "description": "Work item type. `action`: an action item anchored to the incident itself; `follow_up`: an improvement item anchored to a post-mortem.",
+            "type": "string",
             "enum": [
               "action",
               "follow_up"
             ],
-            "type": "string"
-          },
-          "post_mortem_id": {
-            "description": "ID of the post-mortem the work item is bound to.",
-            "type": "string"
+            "description": "Work item type. `action`: an action item anchored to the incident itself; `follow_up`: an improvement item anchored to a post-mortem."
           },
           "title": {
-            "description": "Work item title.",
-            "type": "string"
+            "type": "string",
+            "description": "Work item title."
+          },
+          "from_status": {
+            "type": "string",
+            "description": "Status before completion, usually `open` or `in_progress`; items created before these statuses existed may carry other text."
           },
           "to_status": {
-            "description": "Status label after completion.",
-            "type": "string"
+            "type": "string",
+            "description": "Status after completion; always `done`.",
+            "enum": [
+              "done"
+            ]
           },
-          "work_item_id": {
-            "description": "Work item ID.",
-            "type": "string"
+          "post_mortem_id": {
+            "type": "string",
+            "description": "ID of the post-mortem the work item is bound to."
           }
         },
-        "title": "i_wi_completed",
-        "type": "object"
+        "title": "i_wi_completed"
       },
       "FeedDetailWorkItemConverted": {
+        "type": "object",
         "description": "Detail payload for `i_wi_converted`.",
         "properties": {
+          "work_item_id": {
+            "type": "string",
+            "description": "Work item ID (`wi_` followed by a random string); use it with the `/incident/work-item/*` endpoints."
+          },
+          "title": {
+            "type": "string",
+            "description": "Work item title."
+          },
           "from_type": {
-            "description": "Work item type before the conversion. `action`: an action item anchored to the incident itself; `follow_up`: an improvement item anchored to a post-mortem. Conversion currently only supports `action` → `follow_up`, so `from_type` is always `action` in this event.",
+            "type": "string",
             "enum": [
               "action",
               "follow_up"
             ],
-            "type": "string"
-          },
-          "post_mortem_id": {
-            "description": "ID of the post-mortem the work item is bound to.",
-            "type": "string"
-          },
-          "status": {
-            "description": "Work item status label after the conversion.",
-            "type": "string"
-          },
-          "title": {
-            "description": "Work item title.",
-            "type": "string"
+            "description": "Work item type before the conversion. `action`: an action item anchored to the incident itself; `follow_up`: an improvement item anchored to a post-mortem. Conversion currently only supports `action` → `follow_up`, so `from_type` is always `action` in this event."
           },
           "to_type": {
-            "description": "Work item type after the conversion. `action`: an action item anchored to the incident itself; `follow_up`: an improvement item anchored to a post-mortem. Conversion currently only supports `action` → `follow_up`, so `to_type` is always `follow_up` in this event, and a successful conversion immediately tries to bind the incident's post-mortem.",
+            "type": "string",
             "enum": [
               "action",
               "follow_up"
             ],
-            "type": "string"
+            "description": "Work item type after the conversion. `action`: an action item anchored to the incident itself; `follow_up`: an improvement item anchored to a post-mortem. Conversion currently only supports `action` → `follow_up`, so `to_type` is always `follow_up` in this event, and a successful conversion immediately tries to bind the incident's post-mortem."
           },
-          "work_item_id": {
-            "description": "Work item ID.",
-            "type": "string"
+          "post_mortem_id": {
+            "type": "string",
+            "description": "ID of the post-mortem the work item is bound to."
+          },
+          "status": {
+            "type": "string",
+            "description": "Work item status after the conversion, usually `open` or `in_progress` (conversion keeps the status)."
           }
         },
-        "title": "i_wi_converted",
-        "type": "object"
+        "title": "i_wi_converted"
       },
       "FeedDetailWorkItemCreated": {
+        "type": "object",
         "description": "Detail payload for `i_wi_created`.",
         "properties": {
+          "work_item_id": {
+            "type": "string",
+            "description": "Work item ID (`wi_` followed by a random string); use it with the `/incident/work-item/*` endpoints."
+          },
+          "item_type": {
+            "type": "string",
+            "enum": [
+              "action",
+              "follow_up"
+            ],
+            "description": "Work item type. `action`: an action item anchored to the incident itself, convertible to `follow_up` later; `follow_up`: an improvement item anchored to a post-mortem, requiring the incident to be linked to that post-mortem at creation."
+          },
+          "title": {
+            "type": "string",
+            "description": "Work item title."
+          },
+          "status": {
+            "type": "string",
+            "description": "Work item status at creation: `open` not started; `in_progress` being worked on; `done` completed; `cancelled` no longer needed.",
+            "enum": [
+              "open",
+              "in_progress",
+              "done",
+              "cancelled"
+            ]
+          },
           "assignee_ids": {
-            "description": "Assignee member IDs.",
+            "type": "array",
             "items": {
-              "format": "int64",
-              "type": "integer"
+              "type": "integer",
+              "format": "int64"
             },
-            "type": "array"
+            "description": "Assignee member IDs."
           },
           "assignees": {
             "type": "array",
@@ -10459,152 +10661,120 @@
             },
             "description": "Assignees of the work item. Each entry is `{type, id?}`; an `ai_sre` entry omits `id`. Omitted when there is no assignee."
           },
-          "item_type": {
-            "description": "Work item type. `action`: an action item anchored to the incident itself, convertible to `follow_up` later; `follow_up`: an improvement item anchored to a post-mortem, requiring the incident to be linked to that post-mortem at creation.",
-            "enum": [
-              "action",
-              "follow_up"
-            ],
-            "type": "string"
-          },
           "post_mortem_id": {
-            "description": "ID of the post-mortem the work item is bound to.",
-            "type": "string"
-          },
-          "status": {
-            "description": "Work item status label (e.g. `open`, `done`).",
-            "type": "string"
-          },
-          "title": {
-            "description": "Work item title.",
-            "type": "string"
-          },
-          "work_item_id": {
-            "description": "Work item ID.",
-            "type": "string"
+            "type": "string",
+            "description": "ID of the post-mortem the work item is bound to."
           }
         },
-        "title": "i_wi_created",
-        "type": "object"
+        "title": "i_wi_created"
       },
       "FeedDetailWorkItemDeleted": {
+        "type": "object",
         "description": "Detail payload for `i_wi_deleted`.",
         "properties": {
+          "work_item_id": {
+            "type": "string",
+            "description": "Work item ID (`wi_` followed by a random string); use it with the `/incident/work-item/*` endpoints."
+          },
           "item_type": {
-            "description": "Work item type. `action`: an action item anchored to the incident itself; `follow_up`: an improvement item anchored to a post-mortem.",
+            "type": "string",
             "enum": [
               "action",
               "follow_up"
             ],
-            "type": "string"
-          },
-          "post_mortem_id": {
-            "description": "ID of the post-mortem the work item is bound to.",
-            "type": "string"
+            "description": "Work item type. `action`: an action item anchored to the incident itself; `follow_up`: an improvement item anchored to a post-mortem."
           },
           "title": {
-            "description": "Work item title.",
-            "type": "string"
+            "type": "string",
+            "description": "Work item title."
           },
-          "work_item_id": {
-            "description": "Work item ID.",
-            "type": "string"
+          "post_mortem_id": {
+            "type": "string",
+            "description": "ID of the post-mortem the work item is bound to."
           }
         },
-        "title": "i_wi_deleted",
-        "type": "object"
+        "title": "i_wi_deleted"
       },
       "FeedDetailWorkItemUpdated": {
+        "type": "object",
         "description": "Detail payload for `i_wi_updated`. Only the fields that changed carry `from_*`/`to_*` values.",
         "properties": {
-          "from_description": {
-            "description": "Description before the update.",
-            "type": "string"
-          },
-          "from_priority": {
-            "description": "Priority label before the update.",
-            "type": "string"
-          },
-          "from_status": {
-            "description": "Status label before the update.",
-            "type": "string"
-          },
-          "from_title": {
-            "description": "Title before the update.",
-            "type": "string"
+          "work_item_id": {
+            "type": "string",
+            "description": "Work item ID (`wi_` followed by a random string); use it with the `/incident/work-item/*` endpoints."
           },
           "item_type": {
-            "description": "Work item type. `action`: an action item anchored to the incident itself; `follow_up`: an improvement item anchored to a post-mortem.",
+            "type": "string",
             "enum": [
               "action",
               "follow_up"
             ],
-            "type": "string"
+            "description": "Work item type. `action`: an action item anchored to the incident itself; `follow_up`: an improvement item anchored to a post-mortem."
           },
           "title": {
-            "description": "Work item title.",
-            "type": "string"
+            "type": "string",
+            "description": "Work item title."
           },
-          "to_description": {
-            "description": "Description after the update.",
-            "type": "string"
+          "from_title": {
+            "type": "string",
+            "description": "Title before the update."
           },
-          "to_priority": {
-            "description": "Priority label after the update.",
-            "type": "string"
+          "from_status": {
+            "type": "string",
+            "description": "Status before the update; present only when the status changed. Usually one of `open`, `in_progress`, `done`, `cancelled`; items created before these statuses existed may carry other text."
           },
           "to_status": {
-            "description": "Status label after the update.",
-            "type": "string"
+            "type": "string",
+            "description": "Status after the update; present only when the status changed. `open` not started; `in_progress` being worked on; `done` completed; `cancelled` no longer needed.",
+            "enum": [
+              "open",
+              "in_progress",
+              "done",
+              "cancelled"
+            ]
           },
-          "work_item_id": {
-            "description": "Work item ID.",
-            "type": "string"
+          "from_priority": {
+            "type": "string",
+            "description": "Priority before the update. Free-text priority label defined by the client (up to 64 characters); present only when the priority changed."
+          },
+          "to_priority": {
+            "type": "string",
+            "description": "Priority after the update. Free-text priority label defined by the client (up to 64 characters); present only when the priority changed."
+          },
+          "from_description": {
+            "type": "string",
+            "description": "Description before the update."
+          },
+          "to_description": {
+            "type": "string",
+            "description": "Description after the update."
           }
         },
-        "title": "i_wi_updated",
-        "type": "object"
+        "title": "i_wi_updated"
       },
       "FeedItem": {
+        "type": "object",
         "description": "A single alert activity feed entry. The `detail` field is discriminated by `type`; see the per-type `FeedDetailAlert*` schemas.",
+        "required": [
+          "ref_id",
+          "type",
+          "detail",
+          "account_id",
+          "creator_id",
+          "created_at",
+          "updated_at"
+        ],
         "properties": {
-          "account_id": {
-            "description": "Account ID.",
-            "format": "int64",
-            "type": "integer"
-          },
-          "created_at": {
-            "description": "Creation timestamp in Unix epoch milliseconds.",
-            "format": "int64",
-            "type": "integer"
-          },
-          "creator_id": {
-            "description": "Member ID of the creator. 0 for system-generated entries.",
-            "format": "int64",
-            "type": "integer"
+          "ref_id": {
+            "type": "string",
+            "pattern": "^[0-9a-fA-F]{24}$",
+            "description": "ObjectID of the alert this entry references."
           },
-          "deleted_at": {
-            "description": "Soft-delete time, Unix epoch milliseconds. Omitted when not deleted.",
-            "format": "int64",
-            "type": "integer"
+          "type": {
+            "$ref": "#/components/schemas/AlertFeedType"
           },
           "detail": {
             "description": "Type-specific payload; the concrete shape is determined by `type`. May be `null` for entries stored without detail.",
-            "discriminator": {
-              "mapping": {
-                "a_ack": "#/components/schemas/FeedDetailAlertAck",
-                "a_close": "#/components/schemas/FeedDetailAlertClose",
-                "a_comm": "#/components/schemas/FeedDetailAlertComment",
-                "a_m_flapping": "#/components/schemas/FeedDetailAlertMuteByFlapping",
-                "a_m_inhibit": "#/components/schemas/FeedDetailAlertMuteByInhibit",
-                "a_m_silence": "#/components/schemas/FeedDetailAlertMuteBySilence",
-                "a_merge": "#/components/schemas/FeedDetailAlertMerge",
-                "a_new": "#/components/schemas/FeedDetailAlertTrigger",
-                "a_unack": "#/components/schemas/FeedDetailAlertUnack",
-                "a_update": "#/components/schemas/FeedDetailAlertUpdate"
-              },
-              "propertyName": "type"
-            },
             "oneOf": [
               {
                 "$ref": "#/components/schemas/FeedDetailAlertTrigger"
@@ -10636,20 +10806,47 @@
               {
                 "$ref": "#/components/schemas/FeedDetailAlertClose"
               }
-            ]
+            ],
+            "discriminator": {
+              "propertyName": "type",
+              "mapping": {
+                "a_new": "#/components/schemas/FeedDetailAlertTrigger",
+                "a_update": "#/components/schemas/FeedDetailAlertUpdate",
+                "a_comm": "#/components/schemas/FeedDetailAlertComment",
+                "a_merge": "#/components/schemas/FeedDetailAlertMerge",
+                "a_m_silence": "#/components/schemas/FeedDetailAlertMuteBySilence",
+                "a_m_inhibit": "#/components/schemas/FeedDetailAlertMuteByInhibit",
+                "a_m_flapping": "#/components/schemas/FeedDetailAlertMuteByFlapping",
+                "a_ack": "#/components/schemas/FeedDetailAlertAck",
+                "a_unack": "#/components/schemas/FeedDetailAlertUnack",
+                "a_close": "#/components/schemas/FeedDetailAlertClose"
+              }
+            }
           },
-          "ref_id": {
-            "description": "ObjectID of the alert this entry references.",
-            "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
+          "account_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "ID of the account that owns the alert."
           },
-          "type": {
-            "$ref": "#/components/schemas/AlertFeedType"
+          "creator_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Member ID of the creator. 0 for system-generated entries."
+          },
+          "created_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Creation timestamp in Unix epoch milliseconds."
           },
           "updated_at": {
-            "description": "Last update timestamp in Unix epoch milliseconds.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Last update timestamp in Unix epoch milliseconds."
+          },
+          "deleted_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Soft-delete time, Unix epoch milliseconds. Omitted when not deleted."
           },
           "via": {
             "type": "string",
@@ -10659,17 +10856,7 @@
             "type": "string",
             "description": "AI SRE session that produced the entry. Omitted when no agent wrote it."
           }
-        },
-        "required": [
-          "ref_id",
-          "type",
-          "detail",
-          "account_id",
-          "creator_id",
-          "created_at",
-          "updated_at"
-        ],
-        "type": "object"
+        }
       },
       "FeedSeverity": {
         "description": "Severity level.",
@@ -10682,28 +10869,30 @@
         "type": "string"
       },
       "FieldDeleteReference": {
+        "type": "object",
         "description": "Custom form that still references the field.",
+        "required": [
+          "kind",
+          "name",
+          "href"
+        ],
         "properties": {
-          "href": {
-            "description": "Console URL for the referencing custom form.",
-            "type": "string"
-          },
           "kind": {
-            "const": "custom_form",
+            "type": "string",
             "description": "Referenced resource kind. Always `custom_form` for this response.",
-            "type": "string"
+            "enum": [
+              "custom_form"
+            ]
           },
           "name": {
-            "description": "Human label of the referencing custom form's type (a Chinese label, e.g. `解决故障` for the resolve form).",
-            "type": "string"
+            "type": "string",
+            "description": "Human label of the referencing custom form's type (a Chinese label, e.g. `解决故障` for the resolve form)."
+          },
+          "href": {
+            "type": "string",
+            "description": "Console URL for the referencing custom form."
           }
-        },
-        "required": [
-          "kind",
-          "name",
-          "href"
-        ],
-        "type": "object"
+        }
       },
       "FieldDeleteReferenceError": {
         "description": "Error response returned when a custom form still references the field.",
@@ -10929,70 +11118,70 @@
         "type": "object"
       },
       "FilterCondition": {
+        "type": "object",
+        "required": [
+          "key",
+          "oper",
+          "vals"
+        ],
         "properties": {
           "key": {
-            "description": "Field name to filter on. Use plain names for built-in alert fields (e.g. `alert_severity`, `alert_key`, `check`, `resource`, `service`, `cluster`) or the `labels.<name>` prefix for custom alert labels (e.g. `labels.env`, `labels.region`).",
-            "type": "string"
+            "type": "string",
+            "description": "Field to match. Which built-in keys are allowed depends on the rule type and is listed on the field that holds the conditions; any `labels.<name>` key (for example `labels.env`) is always accepted. An unknown key returns `InvalidParameter`. When the alert or incident has no value for the key, `IN` does not match and `NOTIN` matches."
           },
           "oper": {
-            "description": "Filter operator. `IN` — value must match one of `vals`; `NOTIN` — value must not match any of `vals`. Supports regex patterns wrapped in `/pattern/`.",
+            "type": "string",
             "enum": [
               "IN",
               "NOTIN"
             ],
-            "type": "string"
+            "description": "Match operator, case-sensitive. `IN`: matches when the field value matches any entry in `vals`. `NOTIN`: matches when it matches none of them."
           },
           "vals": {
-            "description": "List of values to match against. Each entry is a plain string or a `/regex/` pattern.",
+            "type": "array",
             "items": {
               "type": "string"
             },
-            "type": "array"
+            "description": "Values to compare, at least one. Each entry is matched as: an exact string; a wildcard pattern when it contains `*` or `?` (must match the whole value); a regular expression when wrapped in slashes, such as `/^db-/` (may match anywhere in the value); an IP range written `cidr:<network>`, such as `cidr:203.0.113.0/24`; or a numeric comparison `num:<op>:<number>` with `lt`, `le`, `gt` or `ge`, such as `num:gt:90`."
           }
-        },
-        "required": [
-          "key",
-          "oper",
-          "vals"
-        ],
-        "type": "object"
+        }
       },
       "FilterGroup": {
         "$ref": "#/components/schemas/OrFilterGroup"
       },
       "Flapping": {
+        "type": "object",
         "description": "Flapping detection configuration.",
         "properties": {
-          "in_mins": {
-            "description": "Observation window in minutes.",
-            "maximum": 1440,
-            "minimum": 1,
-            "type": "integer"
-          },
           "is_disabled": {
-            "description": "Disable flapping detection.",
-            "type": "boolean"
+            "type": "boolean",
+            "description": "When true, flapping detection is turned off."
           },
           "max_changes": {
-            "description": "Max state changes allowed within `in_mins`.",
-            "maximum": 100,
+            "type": "integer",
             "minimum": 2,
-            "type": "integer"
+            "maximum": 100,
+            "description": "Max state changes allowed within `in_mins`, 2–100. When omitted or `0`, all three values fall back to the defaults: 4 changes, `in_mins` 60, `mute_mins` 120."
           },
-          "mute_mins": {
-            "description": "Mute duration in minutes after flapping is detected.",
+          "in_mins": {
+            "type": "integer",
+            "minimum": 1,
             "maximum": 1440,
+            "description": "Observation window in minutes."
+          },
+          "mute_mins": {
+            "type": "integer",
             "minimum": 0,
-            "type": "integer"
+            "maximum": 1440,
+            "description": "Mute duration in minutes after flapping is detected."
           }
-        },
-        "type": "object"
+        }
       },
       "GetRemoteConfigRequest": {
         "description": "Get remote config request",
         "properties": {
           "application_id": {
-            "description": "RUM application ID.",
+            "description": "RUM application ID. Get application IDs via `POST /rum/application/list`.",
             "type": "string"
           }
         },
@@ -11005,7 +11194,15 @@
         "description": "Live remote configuration and its version.",
         "properties": {
           "config": {
-            "$ref": "#/components/schemas/RemoteConfig"
+            "anyOf": [
+              {
+                "$ref": "#/components/schemas/RemoteConfig"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "The live configuration (the newest published version). `null` when the application has never been configured."
           },
           "updated_at": {
             "description": "Unix timestamp in milliseconds - when the current version was published. 0 when never configured.",
@@ -11017,31 +11214,40 @@
             "type": "integer"
           }
         },
-        "type": "object"
+        "type": "object",
+        "required": [
+          "config",
+          "version",
+          "updated_at"
+        ]
       },
       "GetWarRoomDefaultObserversRequest": {
+        "type": "object",
         "properties": {
           "incident_id": {
-            "description": "Incident ID, a MongoDB ObjectID hex string.",
-            "type": "string"
+            "type": "string",
+            "pattern": "^[0-9a-fA-F]{24}$",
+            "description": "Incident ID (MongoDB ObjectID)."
           }
         },
         "required": [
           "incident_id"
-        ],
-        "type": "object"
+        ]
       },
       "GetWarRoomDefaultObserversResponse": {
+        "type": "object",
         "properties": {
           "observers": {
-            "description": "Historical responders suggested as default war-room observers.",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/WarRoomPersonItem"
             },
-            "type": "array"
+            "description": "Suggested observers, in timeline order. Empty array when there are none."
           }
         },
-        "type": "object"
+        "required": [
+          "observers"
+        ]
       },
       "GetWarRoomDetailRequest": {
         "description": "Parameters for retrieving a war room's live detail.",
@@ -11063,130 +11269,130 @@
         "type": "object"
       },
       "GetWebhookHistoryDetailRequest": {
+        "type": "object",
         "description": "Lookup parameters for a single webhook delivery record.",
+        "required": [
+          "event_id",
+          "integration_id"
+        ],
         "properties": {
           "event_id": {
-            "description": "Event ID returned by `ListWebhookHistory`.",
-            "type": "string"
+            "type": "string",
+            "description": "`event_id` of a record returned by `POST /webhook/history/list`. It starts with the delivery date (`YYYYMMDD`); an ID without that prefix fails the request."
           },
           "integration_id": {
-            "description": "Integration ID the event belongs to; available in the items returned by `POST /webhook/history/list`.",
+            "type": "integer",
             "format": "int64",
             "minimum": 1,
-            "type": "integer"
+            "description": "Integration ID the event belongs to; available in the items returned by `POST /webhook/history/list`."
           }
-        },
-        "required": [
-          "event_id",
-          "integration_id"
-        ],
-        "type": "object"
+        }
       },
       "Group": {
+        "type": "object",
         "description": "Alert grouping configuration.",
+        "required": [
+          "method"
+        ],
         "properties": {
-          "all_equals_required": {
-            "description": "When true, all listed keys must be present for grouping.",
-            "type": "boolean"
-          },
-          "cases": {
-            "description": "Per-filter grouping overrides.",
-            "items": {
-              "description": "Conditional grouping override: stored alerts matching `if` are grouped by `equals` instead of the top-level grouping keys.",
-              "properties": {
-                "equals": {
-                  "description": "Grouping keys for matching alerts. Supported values: `title`, `description`, `severity`, or any `labels.<name>`.",
-                  "items": {
-                    "type": "string"
-                  },
-                  "maxItems": 5,
-                  "minItems": 1,
-                  "type": "array"
-                },
-                "if": {
-                  "description": "AND-ed match conditions evaluated against stored alert fields.",
-                  "items": {
-                    "$ref": "#/components/schemas/FilterCondition"
-                  },
-                  "type": "array"
-                }
-              },
-              "required": [
-                "if",
-                "equals"
-              ],
-              "type": "object"
-            },
-            "maxItems": 100,
-            "type": "array"
+          "method": {
+            "type": "string",
+            "enum": [
+              "i",
+              "p",
+              "n"
+            ],
+            "description": "Grouping method:\n- `n`: no grouping; every new alert opens its own incident.\n- `p`: rule-based grouping by the keys in `equals` and `cases`; requires the Standard license or higher.\n- `i`: intelligent grouping by content similarity (see `i_keys`, `i_score_threshold`); requires the Pro license."
           },
           "equals": {
-            "description": "Groups of label keys whose equality defines a bucket.",
+            "type": "array",
             "items": {
+              "type": "array",
               "items": {
                 "type": "string"
-              },
-              "type": "array"
+              }
             },
             "maxItems": 5,
-            "type": "array"
+            "description": "Key sets for rule-based (`p`) grouping, up to 5 sets. A new alert joins an active incident when every key of any one set has the same value on both. Keys: `title`, `description`, `severity`, or `labels.<name>`; each set must be non-empty. With `p`, at least one of `equals` or `cases` is required."
           },
-          "i_keys": {
-            "description": "Label keys used for intelligent grouping embeddings.",
+          "cases": {
+            "type": "array",
+            "maxItems": 100,
+            "description": "Per-filter grouping overrides.",
             "items": {
-              "type": "string"
-            },
-            "maxItems": 10,
-            "type": "array"
+              "type": "object",
+              "description": "Conditional grouping override: stored alerts matching `if` are grouped by `equals` instead of the top-level grouping keys.",
+              "required": [
+                "if",
+                "equals"
+              ],
+              "properties": {
+                "if": {
+                  "type": "array",
+                  "description": "AND-ed match conditions evaluated against stored alert fields.",
+                  "items": {
+                    "$ref": "#/components/schemas/FilterCondition"
+                  }
+                },
+                "equals": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  },
+                  "minItems": 1,
+                  "maxItems": 5,
+                  "description": "Grouping keys for matching alerts. Supported values: `title`, `description`, `severity`, or any `labels.<name>`."
+                }
+              }
+            }
           },
-          "i_score_threshold": {
-            "description": "Intelligent grouping similarity threshold.",
-            "format": "float",
-            "maximum": 1,
-            "minimum": 0.5,
-            "type": "number"
+          "all_equals_required": {
+            "type": "boolean",
+            "description": "When true, a key set matches only if every key in it is present on the alert. When false, missing keys compare as empty, but at least one key of the set must be present."
           },
-          "method": {
-            "description": "Grouping method: `i` intelligent, `p` pattern, `n` none.",
+          "time_window": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "Grouping time window in minutes. Default max is 1440 minutes (24 h); extended accounts may allow up to 43200 minutes (30 days)."
+          },
+          "window_type": {
+            "type": "string",
             "enum": [
-              "i",
-              "p",
-              "n"
+              "tumbling",
+              "sliding"
             ],
-            "type": "string"
+            "description": "Window type, default `tumbling`. `tumbling` is a fixed window counted from incident creation — once it expires, new alerts open a new incident; `sliding` is a sliding window counted from the incident's most recent alert, extended each time a new alert merges in."
           },
           "storm_threshold": {
-            "description": "Alert storm threshold.",
-            "maximum": 10000,
+            "type": "integer",
             "minimum": 0,
-            "type": "integer"
+            "maximum": 10000,
+            "description": "Legacy single storm threshold; used only when `storm_thresholds` is empty and the value is greater than 1. `0` disables it."
           },
           "storm_thresholds": {
-            "description": "Multi-level storm thresholds.",
+            "type": "array",
             "items": {
               "type": "integer"
             },
             "maxItems": 5,
-            "type": "array"
+            "description": "Alert counts at which an incident storm event fires: when the number of alerts merged into one incident reaches a threshold, a storm notification is sent. Up to 5 values, each at least 2; duplicates are removed and values are sorted."
           },
-          "time_window": {
-            "description": "Grouping time window in minutes. Default max is 1440 minutes (24 h); extended accounts may allow up to 43200 minutes (30 days).",
-            "minimum": 0,
-            "type": "integer"
+          "i_keys": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "maxItems": 10,
+            "description": "Fields used by intelligent (`i`) grouping, up to 10: `title`, `description`, `severity`, or `labels.<name>`. Empty uses `title`, `description`, `labels.service` and `labels.resource`."
           },
-          "window_type": {
-            "description": "Window type, default `tumbling`. `tumbling` is a fixed window counted from incident creation — once it expires, new alerts open a new incident; `sliding` is a sliding window counted from the incident's most recent alert, extended each time a new alert merges in.",
-            "enum": [
-              "tumbling",
-              "sliding"
-            ],
-            "type": "string"
+          "i_score_threshold": {
+            "type": "number",
+            "format": "float",
+            "minimum": 0.5,
+            "maximum": 1,
+            "description": "Minimum similarity, 0.5–1, for intelligent grouping to merge an alert into an existing incident. Omitted or `0` uses 0.9."
           }
-        },
-        "required": [
-          "method"
-        ],
-        "type": "object"
+        }
       },
       "IDRequest": {
         "description": "Request with a single numeric ID.",
@@ -11203,111 +11409,111 @@
         "type": "object"
       },
       "Image": {
+        "type": "object",
         "description": "Image or attachment reference.",
+        "required": [
+          "src"
+        ],
         "properties": {
-          "alt": {
-            "description": "Alt text.",
-            "type": "string"
+          "src": {
+            "type": "string",
+            "description": "Image source. Either an `img_` upload token or an `http(s)` URL."
           },
           "href": {
-            "description": "Optional link the image points to.",
-            "type": "string"
+            "type": "string",
+            "description": "Optional link the image points to."
           },
-          "src": {
-            "description": "Image source. Either an `img_` upload token or an `http(s)` URL.",
-            "type": "string"
+          "alt": {
+            "type": "string",
+            "description": "Alternative text shown when the image cannot be displayed; empty when not set."
           }
-        },
-        "required": [
-          "src"
-        ],
-        "type": "object"
+        }
       },
       "ImportStatusPageSubscriberItem": {
+        "type": "object",
         "description": "A single subscriber to import.",
+        "required": [
+          "recipient"
+        ],
         "properties": {
-          "all": {
-            "description": "When true, the subscriber receives notifications for all components. Must be true when `component_ids` and `change_ids` are both empty.",
-            "type": "boolean"
+          "recipient": {
+            "type": "string",
+            "maxLength": 255,
+            "description": "Email address (for public pages) or user ID (for internal pages)."
           },
-          "change_ids": {
-            "description": "Specific event IDs the subscriber should receive notifications for.",
+          "component_ids": {
+            "type": "array",
             "items": {
-              "format": "int64",
-              "type": "integer"
+              "type": "string"
             },
-            "type": "array"
+            "description": "Component IDs the subscriber should receive notifications for."
           },
-          "component_ids": {
-            "description": "Component IDs the subscriber should receive notifications for.",
+          "change_ids": {
+            "type": "array",
             "items": {
-              "type": "string"
+              "type": "integer",
+              "format": "int64"
             },
-            "type": "array"
+            "description": "Specific event IDs the subscriber should receive notifications for."
           },
-          "locale": {
-            "description": "Preferred locale for notifications. Defaults to the request locale when omitted.",
-            "type": "string"
+          "all": {
+            "type": "boolean",
+            "description": "When `true`, the subscriber receives notifications for all components and events, and `component_ids`/`change_ids` are ignored. Must be `true` when both lists are empty."
           },
-          "recipient": {
-            "description": "Email address (for public pages) or user ID (for internal pages).",
-            "maxLength": 255,
-            "type": "string"
+          "locale": {
+            "type": "string",
+            "description": "Preferred locale for notifications. Defaults to the request locale when omitted."
           }
-        },
-        "required": [
-          "recipient"
-        ],
-        "type": "object"
+        }
       },
       "ImportStatusPageSubscribersRequest": {
+        "type": "object",
         "description": "Parameters for bulk-importing subscribers. Each subscriber must have a non-empty `recipient` (≤255 chars) and subscribe to at least one component, change, or set `all: true`.",
+        "required": [
+          "page_id",
+          "method"
+        ],
         "properties": {
+          "page_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Target status page ID; obtain it from `GET /status-page/list`."
+          },
           "method": {
-            "description": "Subscription method. `email` is only valid for public pages; `im` is only valid for internal pages.",
+            "type": "string",
             "enum": [
               "email",
               "im"
             ],
-            "type": "string"
-          },
-          "page_id": {
-            "description": "Target status page ID; obtain it from `GET /status-page/list`.",
-            "format": "int64",
-            "type": "integer"
+            "description": "Subscription method. `email` is only valid for public pages; `im` is only valid for internal pages."
           },
           "subscribers": {
-            "description": "Subscribers to import.",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/ImportStatusPageSubscriberItem"
             },
-            "type": "array"
+            "description": "Subscribers to import. Each recipient's existing subscriptions on this page are replaced; an empty or omitted list does nothing."
           }
-        },
-        "required": [
-          "page_id",
-          "method"
-        ],
-        "type": "object"
+        }
       },
       "IncProgressCnts": {
+        "type": "object",
+        "required": [
+          "Triggered",
+          "Processing"
+        ],
         "properties": {
-          "Processing": {
-            "description": "Count of processing incidents in the last 30 days.",
+          "Triggered": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Incidents started in the last 30 days that are still `Triggered` (not yet acknowledged)."
           },
-          "Triggered": {
-            "description": "Count of triggered incidents in the last 30 days.",
+          "Processing": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Incidents started in the last 30 days that are `Processing` (acknowledged, not yet closed)."
           }
-        },
-        "required": [
-          "Triggered",
-          "Processing"
-        ],
-        "type": "object"
+        }
       },
       "IncidentActionImage": {
         "description": "Image attached to an acknowledgement or resolution timeline entry.",
@@ -11331,9 +11537,23 @@
         "type": "object"
       },
       "IncidentCardHiddenFields": {
+        "type": "object",
+        "description": "Incident-card fields to hide, keyed by IM app type. Only supported IM app types and field names are accepted.",
+        "propertyNames": {
+          "type": "string",
+          "enum": [
+            "feishu_app",
+            "dingtalk_app",
+            "slack_app",
+            "teams_app",
+            "wecom_app"
+          ]
+        },
         "additionalProperties": {
-          "description": "Incident-card field names to hide for this IM app.",
+          "type": "array",
+          "description": "Fields to hide on this app's incident cards: `channel` (channel name), `snoozed_before` (snooze end time), `severity`, `responders`, `aggregate_alert_count` (number of merged alerts), `detail` (Detail button), `ai_analysis` (AI Analysis button).",
           "items": {
+            "type": "string",
             "enum": [
               "channel",
               "snoozed_before",
@@ -11342,23 +11562,9 @@
               "aggregate_alert_count",
               "detail",
               "ai_analysis"
-            ],
-            "type": "string"
-          },
-          "type": "array"
-        },
-        "description": "Incident-card fields to hide, keyed by IM app type. Only supported IM app types and field names are accepted.",
-        "propertyNames": {
-          "enum": [
-            "feishu_app",
-            "dingtalk_app",
-            "slack_app",
-            "teams_app",
-            "wecom_app"
-          ],
-          "type": "string"
-        },
-        "type": "object"
+            ]
+          }
+        }
       },
       "IncidentCommentTypeDisplay": {
         "description": "Resolved display of an account-level comment type, populated at read time from the current type definition.",
@@ -11449,69 +11655,28 @@
         "type": "object"
       },
       "IncidentFeedItem": {
+        "type": "object",
         "description": "Single incident timeline entry. The `detail` field is discriminated by `type`; see the per-type `FeedDetail*` schemas.",
+        "required": [
+          "ref_id",
+          "type",
+          "detail",
+          "account_id",
+          "creator_id",
+          "created_at",
+          "updated_at"
+        ],
         "properties": {
-          "account_id": {
-            "description": "Account ID.",
-            "format": "int64",
-            "type": "integer"
-          },
-          "created_at": {
-            "description": "Creation timestamp in milliseconds.",
-            "format": "int64",
-            "type": "integer"
-          },
-          "creator_id": {
-            "description": "User ID of the actor. `0` means system-generated.",
-            "format": "int64",
-            "type": "integer"
+          "ref_id": {
+            "type": "string",
+            "pattern": "^[0-9a-fA-F]{24}$",
+            "description": "ID of the incident the entry belongs to; equals the requested `incident_id`."
           },
-          "deleted_at": {
-            "description": "Soft-delete timestamp in milliseconds. Zero if not deleted.",
-            "format": "int64",
-            "type": "integer"
+          "type": {
+            "$ref": "#/components/schemas/IncidentFeedType"
           },
           "detail": {
             "description": "Type-specific payload. The concrete shape is determined by `type`; `null` when the entry has no structured detail.",
-            "discriminator": {
-              "mapping": {
-                "a_merge": "#/components/schemas/FeedDetailAlertMerge",
-                "i_a_rspd": "#/components/schemas/FeedDetailIncidentAddRspd",
-                "i_ack": "#/components/schemas/FeedDetailIncidentAck",
-                "i_assign": "#/components/schemas/FeedDetailIncidentAssign",
-                "i_auto_refresh": "#/components/schemas/FeedDetailIncidentAutoRefreshCard",
-                "i_comm": "#/components/schemas/FeedDetailIncidentComment",
-                "i_custom": "#/components/schemas/FeedDetailIncidentCustomAction",
-                "i_m_flapping": "#/components/schemas/FeedDetailIncidentMuteByFlapping",
-                "i_m_reply": "#/components/schemas/FeedDetailIncidentMuteReply",
-                "i_merge": "#/components/schemas/FeedDetailIncidentMerge",
-                "i_new": "#/components/schemas/FeedDetailIncidentNew",
-                "i_notify": "#/components/schemas/FeedDetailIncidentNotify",
-                "i_r_desc": "#/components/schemas/FeedDetailIncidentResetDescription",
-                "i_r_field": "#/components/schemas/FeedDetailIncidentResetField",
-                "i_r_impact": "#/components/schemas/FeedDetailIncidentResetImpact",
-                "i_r_rc": "#/components/schemas/FeedDetailIncidentResetRootCause",
-                "i_r_rsltn": "#/components/schemas/FeedDetailIncidentResetResolution",
-                "i_r_severity": "#/components/schemas/FeedDetailIncidentResetSeverity",
-                "i_r_title": "#/components/schemas/FeedDetailIncidentResetTitle",
-                "i_reopen": "#/components/schemas/FeedDetailIncidentReopen",
-                "i_rslv": "#/components/schemas/FeedDetailIncidentResolve",
-                "i_snooze": "#/components/schemas/FeedDetailIncidentSnooze",
-                "i_storm": "#/components/schemas/FeedDetailIncidentStorm",
-                "i_unack": "#/components/schemas/FeedDetailIncidentUnack",
-                "i_wake": "#/components/schemas/FeedDetailIncidentWake",
-                "i_wi_assignees": "#/components/schemas/FeedDetailWorkItemAssigneesChanged",
-                "i_wi_bound": "#/components/schemas/FeedDetailWorkItemBound",
-                "i_wi_completed": "#/components/schemas/FeedDetailWorkItemCompleted",
-                "i_wi_converted": "#/components/schemas/FeedDetailWorkItemConverted",
-                "i_wi_created": "#/components/schemas/FeedDetailWorkItemCreated",
-                "i_wi_deleted": "#/components/schemas/FeedDetailWorkItemDeleted",
-                "i_wi_updated": "#/components/schemas/FeedDetailWorkItemUpdated",
-                "i_wr_create": "#/components/schemas/FeedDetailIncidentWarRoomCreate",
-                "i_wr_delete": "#/components/schemas/FeedDetailIncidentWarRoomDelete"
-              },
-              "propertyName": "type"
-            },
             "oneOf": [
               {
                 "$ref": "#/components/schemas/FeedDetailIncidentNew"
@@ -11614,36 +11779,118 @@
               },
               {
                 "$ref": "#/components/schemas/FeedDetailAlertMerge"
+              },
+              {
+                "type": "object",
+                "title": "i_wi_auto_converted",
+                "description": "Detail payload for `i_wi_auto_converted`.",
+                "properties": {
+                  "count": {
+                    "type": "integer",
+                    "description": "Number of action items converted to follow-ups."
+                  },
+                  "work_item_ids": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    },
+                    "description": "IDs of the converted work items."
+                  },
+                  "titles": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    },
+                    "description": "Titles of the converted work items, in the same order as `work_item_ids`."
+                  },
+                  "post_mortem_id": {
+                    "type": "string",
+                    "description": "ID of the post-mortem the follow-ups are bound to; empty when the incident has no post-mortem."
+                  }
+                }
               }
-            ]
+            ],
+            "discriminator": {
+              "propertyName": "type",
+              "mapping": {
+                "i_new": "#/components/schemas/FeedDetailIncidentNew",
+                "i_assign": "#/components/schemas/FeedDetailIncidentAssign",
+                "i_a_rspd": "#/components/schemas/FeedDetailIncidentAddRspd",
+                "i_notify": "#/components/schemas/FeedDetailIncidentNotify",
+                "i_storm": "#/components/schemas/FeedDetailIncidentStorm",
+                "i_snooze": "#/components/schemas/FeedDetailIncidentSnooze",
+                "i_wake": "#/components/schemas/FeedDetailIncidentWake",
+                "i_ack": "#/components/schemas/FeedDetailIncidentAck",
+                "i_unack": "#/components/schemas/FeedDetailIncidentUnack",
+                "i_comm": "#/components/schemas/FeedDetailIncidentComment",
+                "i_rslv": "#/components/schemas/FeedDetailIncidentResolve",
+                "i_reopen": "#/components/schemas/FeedDetailIncidentReopen",
+                "i_merge": "#/components/schemas/FeedDetailIncidentMerge",
+                "i_r_title": "#/components/schemas/FeedDetailIncidentResetTitle",
+                "i_r_desc": "#/components/schemas/FeedDetailIncidentResetDescription",
+                "i_r_impact": "#/components/schemas/FeedDetailIncidentResetImpact",
+                "i_r_rc": "#/components/schemas/FeedDetailIncidentResetRootCause",
+                "i_r_rsltn": "#/components/schemas/FeedDetailIncidentResetResolution",
+                "i_r_severity": "#/components/schemas/FeedDetailIncidentResetSeverity",
+                "i_r_field": "#/components/schemas/FeedDetailIncidentResetField",
+                "i_m_flapping": "#/components/schemas/FeedDetailIncidentMuteByFlapping",
+                "i_m_reply": "#/components/schemas/FeedDetailIncidentMuteReply",
+                "i_custom": "#/components/schemas/FeedDetailIncidentCustomAction",
+                "i_wr_create": "#/components/schemas/FeedDetailIncidentWarRoomCreate",
+                "i_wr_delete": "#/components/schemas/FeedDetailIncidentWarRoomDelete",
+                "i_auto_refresh": "#/components/schemas/FeedDetailIncidentAutoRefreshCard",
+                "i_wi_created": "#/components/schemas/FeedDetailWorkItemCreated",
+                "i_wi_updated": "#/components/schemas/FeedDetailWorkItemUpdated",
+                "i_wi_assignees": "#/components/schemas/FeedDetailWorkItemAssigneesChanged",
+                "i_wi_completed": "#/components/schemas/FeedDetailWorkItemCompleted",
+                "i_wi_converted": "#/components/schemas/FeedDetailWorkItemConverted",
+                "i_wi_bound": "#/components/schemas/FeedDetailWorkItemBound",
+                "i_wi_deleted": "#/components/schemas/FeedDetailWorkItemDeleted",
+                "a_merge": "#/components/schemas/FeedDetailAlertMerge"
+              }
+            }
           },
-          "ref_id": {
-            "description": "ObjectID of the source alert or incident this entry references.",
-            "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
+          "account_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "ID of the account that owns this record; the same for every record returned to one `app_key`."
           },
-          "type": {
-            "$ref": "#/components/schemas/IncidentFeedType"
+          "creator_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "User ID of the actor. `0` means system-generated."
+          },
+          "deleted_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Soft-delete timestamp in milliseconds. Zero if not deleted."
+          },
+          "created_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Creation timestamp in milliseconds."
           },
           "updated_at": {
-            "description": "Last update timestamp in milliseconds.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Last update timestamp in milliseconds."
+          },
+          "via": {
+            "type": "string",
+            "enum": [
+              "ai_sre"
+            ],
+            "description": "`ai_sre` when AI SRE performed the action on behalf of `creator_id`; omitted for direct actions."
+          },
+          "agent_session_id": {
+            "type": "string",
+            "description": "ID of the AI SRE session that performed the action; present only when `via` is `ai_sre` and a session was recorded."
           }
-        },
-        "required": [
-          "ref_id",
-          "type",
-          "detail",
-          "account_id",
-          "creator_id",
-          "created_at",
-          "updated_at"
-        ],
-        "type": "object"
+        }
       },
       "IncidentFeedType": {
-        "description": "Incident timeline entry type. Each value identifies one lifecycle event; the matching `detail` payload shape is determined by this field. Incident types are prefixed with `i_`.\n\n| Type | Meaning |\n|---|---|\n| `i_new` | Incident Created: A new incident was created automatically or manually. |\n| `i_assign` | Assigned: Incident was assigned to responders. |\n| `i_a_rspd` | Responder Added: Additional responders joined the incident. |\n| `i_notify` | Notification dispatched through a channel at a specific escalation level. |\n| `i_storm` | Alert storm threshold reached on the incident. |\n| `i_snooze` | Notifications snoozed for a given duration. |\n| `i_wake` | Snooze cancelled and notifications resumed. |\n| `i_ack` | Acknowledged: Responder confirmed they are working on the incident. |\n| `i_unack` | Acknowledgement removed. |\n| `i_comm` | Comment: Responder logged progress or key information. |\n| `i_rslv` | Resolved: Incident was marked as resolved. |\n| `i_reopen` | Reopened: Resolved incident was reopened, possibly due to recurrence. |\n| `i_merge` | Merged: Multiple related incidents were merged into one. |\n| `i_r_title` | Title updated. |\n| `i_r_desc` | Description updated. |\n| `i_r_impact` | Impact updated. |\n| `i_r_rc` | Root cause updated. |\n| `i_r_rsltn` | Resolution updated. |\n| `i_r_severity` | Severity Changed: Incident severity level was adjusted. |\n| `i_r_field` | Custom field value updated. |\n| `i_m_flapping` | Incident muted by flapping detection. |\n| `i_m_reply` | Mute reply marker on a comment. |\n| `i_custom` | Action: Automated action or script was triggered. |\n| `i_wr_create` | War Room Created: Chat group was created for collaborative response. |\n| `i_wr_delete` | War room chat group deleted. |\n| `i_auto_refresh` | Card auto-refresh event posted back to the timeline. |\n| `i_wi_created` | Work Item Created: An Action or Follow-up was created. |\n| `i_wi_updated` | Work Item Updated: Title, description, status, or priority was changed. |\n| `i_wi_assignees` | Work Item Assignees Changed: Assignees were updated. |\n| `i_wi_completed` | Work Item Completed: An assignee marked the work item complete. |\n| `i_wi_converted` | Work Item Converted: An Action was converted to a Follow-up. |\n| `i_wi_bound` | Work Item Bound: A converted Follow-up was bound to a post-mortem. |\n| `i_wi_deleted` | Work Item Deleted: An Action or Follow-up was soft-deleted. |\n| `a_merge` | Alert Merged: An alert was merged into an existing incident. |",
+        "type": "string",
+        "description": "Incident timeline entry type. Each value identifies one lifecycle event; the matching `detail` payload shape is determined by this field. Incident types are prefixed with `i_`.\n\n| Type | Meaning |\n|---|---|\n| `i_new` | Incident Created: A new incident was created automatically or manually. |\n| `i_assign` | Assigned: Incident was assigned to responders. |\n| `i_a_rspd` | Responder Added: Additional responders joined the incident. |\n| `i_notify` | Notification dispatched through a channel at a specific escalation level. |\n| `i_storm` | Alert storm threshold reached on the incident. |\n| `i_snooze` | Notifications snoozed for a given duration. |\n| `i_wake` | Snooze cancelled and notifications resumed. |\n| `i_ack` | Acknowledged: Responder confirmed they are working on the incident. |\n| `i_unack` | Acknowledgement removed. |\n| `i_comm` | Comment: Responder logged progress or key information. |\n| `i_rslv` | Resolved: Incident was marked as resolved. |\n| `i_reopen` | Reopened: Resolved incident was reopened, possibly due to recurrence. |\n| `i_merge` | Merged: Multiple related incidents were merged into one. |\n| `i_r_title` | Title updated. |\n| `i_r_desc` | Description updated. |\n| `i_r_impact` | Impact updated. |\n| `i_r_rc` | Root cause updated. |\n| `i_r_rsltn` | Resolution updated. |\n| `i_r_severity` | Severity Changed: Incident severity level was adjusted. |\n| `i_r_field` | Custom field value updated. |\n| `i_m_flapping` | Incident muted by flapping detection. |\n| `i_m_reply` | Mute reply marker on a comment. |\n| `i_custom` | Action: Automated action or script was triggered. |\n| `i_wr_create` | War Room Created: Chat group was created for collaborative response. |\n| `i_wr_delete` | War room chat group deleted. |\n| `i_auto_refresh` | Card auto-refresh event posted back to the timeline. |\n| `i_wi_created` | Work Item Created: An Action or Follow-up was created. |\n| `i_wi_updated` | Work Item Updated: Title, description, status, or priority was changed. |\n| `i_wi_assignees` | Work Item Assignees Changed: Assignees were updated. |\n| `i_wi_completed` | Work Item Completed: An assignee marked the work item complete. |\n| `i_wi_converted` | Work Item Converted: An Action was converted to a Follow-up. |\n| `i_wi_bound` | Work Item Bound: A converted Follow-up was bound to a post-mortem. |\n| `i_wi_deleted` | Work Item Deleted: An Action or Follow-up was soft-deleted. |\n| `i_wi_auto_converted` | Work Items Auto-converted: Closing the incident converted its unfinished action items to follow-ups. |\n| `a_merge` | Alert Merged: An alert was merged into an existing incident. |",
         "enum": [
           "i_new",
           "i_assign",
@@ -11678,399 +11925,436 @@
           "i_wi_converted",
           "i_wi_bound",
           "i_wi_deleted",
+          "i_wi_auto_converted",
           "a_merge"
-        ],
-        "type": "string"
+        ]
       },
       "IncidentInfo": {
+        "type": "object",
         "description": "Detailed incident record.",
+        "required": [
+          "incident_id",
+          "account_id",
+          "channel_id",
+          "team_id",
+          "integration_id",
+          "integration_ids",
+          "integration_types",
+          "dedup_key",
+          "equals_md5",
+          "start_time",
+          "end_time",
+          "last_time",
+          "ack_time",
+          "close_time",
+          "creator_id",
+          "closer_id",
+          "owner_id",
+          "incident_status",
+          "incident_severity",
+          "progress",
+          "title",
+          "description",
+          "ai_summary",
+          "impact",
+          "root_cause",
+          "resolution",
+          "num",
+          "created_at",
+          "updated_at",
+          "snoozed_before",
+          "group_method",
+          "ever_muted",
+          "labels",
+          "fields",
+          "assigned_to",
+          "alert_cnt",
+          "active_alert_cnt",
+          "alert_event_cnt",
+          "responders",
+          "account_name",
+          "account_locale",
+          "account_time_zone",
+          "channel_name",
+          "channel_status",
+          "detail_url",
+          "silence_url",
+          "post_mortem_id",
+          "images",
+          "manual_overrides",
+          "has_unfinished_work_item"
+        ],
         "properties": {
-          "account_id": {
-            "description": "Account ID that owns the incident.",
-            "format": "int64",
-            "type": "integer"
-          },
-          "account_locale": {
-            "description": "Account locale.",
-            "type": "string"
-          },
-          "account_name": {
-            "description": "Account name.",
-            "type": "string"
-          },
-          "account_time_zone": {
-            "description": "Account time zone.",
-            "type": "string"
+          "incident_id": {
+            "type": "string",
+            "pattern": "^[0-9a-fA-F]{24}$",
+            "description": "Incident ID (MongoDB ObjectID)."
           },
-          "ack_time": {
-            "description": "Unix timestamp (seconds) when the incident was first acknowledged. 0 if unacknowledged.",
+          "account_id": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Account ID that owns the incident."
           },
-          "active_alert_cnt": {
-            "description": "Count of alerts currently in Critical/Warning/Info state.",
+          "channel_id": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
-          },
-          "ai_summary": {
-            "description": "AI-generated summary of the incident.",
-            "type": "string"
+            "description": "Channel ID. 0 for standalone incidents."
           },
-          "alert_cnt": {
-            "description": "Total count of alerts merged into this incident.",
+          "team_id": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "ID of the team that owns the incident's channel. 0 when the channel has no team."
           },
-          "alert_event_cnt": {
-            "description": "Total raw alert event count across all merged alerts.",
+          "integration_id": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "First integration associated with the incident."
           },
-          "alerts": {
-            "description": "Embedded alerts, only populated for notification templates and custom actions.",
+          "integration_ids": {
+            "type": [
+              "array",
+              "null"
+            ],
             "items": {
-              "$ref": "#/components/schemas/AlertInfo"
+              "type": "integer",
+              "format": "int64"
             },
-            "type": "array"
+            "description": "IDs of all integrations contributing alerts to this incident; `null` for incidents without integrations, such as manually created ones."
           },
-          "assigned_to": {
-            "$ref": "#/components/schemas/AssignedTo",
-            "description": "Current assignment target for the incident."
-          },
-          "channel_id": {
-            "description": "Channel ID. 0 for standalone incidents.",
-            "format": "int64",
-            "type": "integer"
+          "integration_types": {
+            "type": [
+              "array",
+              "null"
+            ],
+            "items": {
+              "type": "string"
+            },
+            "description": "Plugin types of all contributing integrations (see `integration_type`); `null` when there are none."
           },
-          "channel_name": {
-            "description": "Channel display name.",
-            "type": "string"
+          "dedup_key": {
+            "type": "string",
+            "description": "Deduplication key used to coalesce alerts."
           },
-          "channel_status": {
-            "description": "Channel status.",
-            "type": "string"
+          "equals_md5": {
+            "type": "string",
+            "description": "MD5 hash used for content-equality checks."
           },
-          "close_time": {
-            "description": "Unix timestamp (seconds) when the incident was closed. 0 if still open.",
+          "start_time": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Unix timestamp (seconds) when the incident started."
           },
-          "closer": {
-            "$ref": "#/components/schemas/PersonShort",
-            "description": "Closer member info."
+          "end_time": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Unix timestamp (seconds) when the incident ended. 0 if still active."
           },
-          "closer_id": {
-            "description": "Member ID that closed the incident. 0 if auto-closed.",
+          "last_time": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Unix timestamp (seconds) of the most recent update."
           },
-          "created_at": {
-            "description": "Creation timestamp (seconds).",
+          "ack_time": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Unix timestamp (seconds) when the incident was first acknowledged. 0 if unacknowledged."
           },
-          "creator": {
-            "$ref": "#/components/schemas/PersonShort",
-            "description": "Creator member info."
+          "close_time": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Unix timestamp (seconds) when the incident was closed. 0 if still open."
           },
           "creator_id": {
-            "description": "Member ID that created the incident. 0 if auto-created by the system.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Member ID that created the incident. 0 if auto-created by the system."
           },
-          "data_source_id": {
-            "deprecated": true,
-            "description": "Deprecated. Use `integration_id` instead.",
+          "closer_id": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Member ID that closed the incident. 0 if auto-closed."
           },
-          "data_source_ids": {
-            "deprecated": true,
-            "description": "Deprecated. Use `integration_ids` instead.",
-            "items": {
-              "format": "int64",
-              "type": "integer"
-            },
-            "type": "array"
+          "owner_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Primary owner member ID. 0 if none."
           },
-          "data_source_type": {
-            "deprecated": true,
-            "description": "Deprecated. Use `integration_type` instead.",
-            "type": "string"
+          "incident_status": {
+            "type": "string",
+            "enum": [
+              "Critical",
+              "Warning",
+              "Info",
+              "Ok"
+            ],
+            "description": "Current incident status, derived from alert statuses."
           },
-          "data_source_types": {
-            "deprecated": true,
-            "description": "Deprecated. Use `integration_types` instead.",
-            "items": {
-              "type": "string"
-            },
-            "type": "array"
+          "incident_severity": {
+            "type": "string",
+            "enum": [
+              "Critical",
+              "Warning",
+              "Info",
+              "Ok"
+            ],
+            "description": "Configured incident severity."
           },
-          "dedup_key": {
-            "description": "Deduplication key used to coalesce alerts.",
-            "type": "string"
+          "progress": {
+            "type": "string",
+            "enum": [
+              "Triggered",
+              "Processing",
+              "Closed"
+            ],
+            "description": "Incident progress. `Triggered` means fired and unacknowledged; `Processing` means acknowledged and being handled (un-acknowledging moves it back to `Triggered`); `Closed` means resolved."
           },
-          "deleted_at": {
-            "description": "Soft-delete timestamp (seconds). Zero if not deleted.",
-            "format": "int64",
-            "type": "integer"
+          "title": {
+            "type": "string",
+            "description": "Incident title."
           },
           "description": {
-            "description": "Incident description.",
-            "type": "string"
+            "type": "string",
+            "description": "Incident description."
           },
-          "detail_url": {
-            "description": "Web console URL for the incident.",
-            "type": "string"
+          "ai_summary": {
+            "type": "string",
+            "description": "AI-generated summary of the incident."
           },
-          "end_time": {
-            "description": "Unix timestamp (seconds) when the incident ended. 0 if still active.",
-            "format": "int64",
-            "type": "integer"
+          "impact": {
+            "type": "string",
+            "description": "Impact description."
           },
-          "equals_md5": {
-            "description": "MD5 hash used for content-equality checks.",
-            "type": "string"
+          "root_cause": {
+            "type": "string",
+            "description": "Root cause analysis."
           },
-          "ever_muted": {
-            "description": "Whether the incident has ever been silenced.",
-            "type": "boolean"
+          "resolution": {
+            "type": "string",
+            "description": "Resolution notes."
           },
-          "fields": {
-            "additionalProperties": true,
-            "description": "Custom field values keyed by field name.",
-            "type": "object"
+          "num": {
+            "type": "string",
+            "description": "Short display identifier; not guaranteed unique."
           },
           "frequency": {
+            "type": "string",
             "description": "Frequency bucket for recurrence analysis: `frequent` or `rare`.",
             "enum": [
               "frequent",
               "rare"
-            ],
-            "type": "string"
+            ]
+          },
+          "deleted_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Soft-delete timestamp (seconds). Zero if not deleted."
+          },
+          "created_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Creation timestamp (seconds)."
+          },
+          "updated_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Last update timestamp (seconds)."
+          },
+          "snoozed_before": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Unix timestamp (seconds) until which notifications are snoozed. 0 if not snoozed."
           },
           "group_method": {
+            "type": "string",
             "description": "Alert grouping method: `i` intelligent, `p` pattern, `n` none.",
             "enum": [
               "i",
               "p",
               "n"
-            ],
-            "type": "string"
-          },
-          "images": {
-            "description": "Attached images.",
-            "items": {
-              "$ref": "#/components/schemas/Image"
-            },
-            "type": "array"
+            ]
           },
-          "impact": {
-            "description": "Impact description.",
-            "type": "string"
+          "ever_muted": {
+            "type": "boolean",
+            "description": "Whether the incident has ever been silenced."
           },
-          "incident_id": {
-            "description": "Incident ID (MongoDB ObjectID).",
-            "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
+          "has_unfinished_work_item": {
+            "type": "boolean",
+            "description": "`true` when the incident still has at least one action item or follow-up that is neither `done` nor `cancelled`."
           },
-          "incident_severity": {
-            "description": "Configured incident severity.",
-            "enum": [
-              "Critical",
-              "Warning",
-              "Info",
-              "Ok"
+          "labels": {
+            "type": [
+              "object",
+              "null"
             ],
-            "type": "string"
+            "additionalProperties": {
+              "type": "string"
+            },
+            "description": "Labels propagated from alerts."
           },
-          "incident_status": {
-            "description": "Current incident status, derived from alert statuses.",
-            "enum": [
-              "Critical",
-              "Warning",
-              "Info",
-              "Ok"
-            ],
-            "type": "string"
+          "fields": {
+            "type": "object",
+            "additionalProperties": true,
+            "description": "Custom field values keyed by field name."
           },
-          "integration_id": {
-            "description": "First integration associated with the incident.",
+          "assigned_to": {
+            "$ref": "#/components/schemas/AssignedTo",
+            "description": "Current assignment target. Always present; for an incident that was never assigned, `type` and `id` are empty and `assigned_at` is `0`."
+          },
+          "reporter_email": {
+            "type": "string",
+            "description": "Reporter email for manually created incidents."
+          },
+          "alert_cnt": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Total count of alerts merged into this incident."
           },
-          "integration_ids": {
-            "description": "All integration IDs contributing alerts to this incident.",
-            "items": {
-              "format": "int64",
-              "type": "integer"
-            },
-            "type": "array"
+          "active_alert_cnt": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Count of alerts currently in Critical/Warning/Info state."
           },
-          "integration_type": {
-            "description": "First alert's integration type string, used by the detail page for label mappings.",
-            "type": "string"
+          "alert_event_cnt": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Total raw alert event count across all merged alerts."
           },
-          "integration_types": {
-            "description": "Integration type strings for all contributing integrations.",
+          "alerts": {
+            "type": "array",
             "items": {
-              "type": "string"
+              "$ref": "#/components/schemas/AlertInfo"
             },
-            "type": "array"
+            "description": "Not returned by the incident endpoints; present only in notification template and custom action payloads."
           },
-          "labels": {
-            "additionalProperties": {
-              "type": "string"
-            },
-            "description": "Labels propagated from alerts.",
-            "type": "object"
+          "closer": {
+            "$ref": "#/components/schemas/PersonShort",
+            "description": "Closer member info."
           },
-          "last_time": {
-            "description": "Unix timestamp (seconds) of the most recent update.",
-            "format": "int64",
-            "type": "integer"
+          "creator": {
+            "$ref": "#/components/schemas/PersonShort",
+            "description": "Creator member info."
           },
-          "links": {
-            "description": "Channel-level link integrations rendered for this incident.",
-            "items": {
-              "$ref": "#/components/schemas/LinkItem"
-            },
-            "type": "array"
+          "owner": {
+            "$ref": "#/components/schemas/PersonShort",
+            "description": "Owner member info. May be deprecated.",
+            "deprecated": true
           },
-          "manual_overrides": {
-            "description": "Fields that were manually overridden after auto-population.",
+          "responders": {
+            "type": "array",
             "items": {
-              "type": "string"
+              "$ref": "#/components/schemas/Responder"
             },
-            "type": "array"
+            "description": "Current responders with assignment/acknowledgement state."
           },
-          "num": {
-            "description": "Short display identifier; not guaranteed unique.",
-            "type": "string"
+          "account_name": {
+            "type": "string",
+            "description": "Always an empty string in API responses; filled only when the incident is rendered for notifications."
           },
-          "owner": {
-            "$ref": "#/components/schemas/PersonShort",
-            "deprecated": true,
-            "description": "Owner member info. May be deprecated."
+          "account_locale": {
+            "type": "string",
+            "description": "Always an empty string in API responses; filled only when the incident is rendered for notifications."
           },
-          "owner_id": {
-            "description": "Primary owner member ID. 0 if none.",
-            "format": "int64",
-            "type": "integer"
+          "account_time_zone": {
+            "type": "string",
+            "description": "Always an empty string in API responses; filled only when the incident is rendered for notifications."
           },
-          "post_mortem_id": {
-            "description": "Associated post-mortem ID, if any. One incident can only link to a single post-mortem.",
-            "type": "string"
+          "channel_name": {
+            "type": "string",
+            "description": "Channel display name."
           },
-          "progress": {
-            "description": "Incident progress. `Triggered` means fired and unacknowledged; `Processing` means acknowledged and being handled (un-acknowledging moves it back to `Triggered`); `Closed` means resolved.",
+          "channel_status": {
+            "type": "string",
+            "description": "Status of the channel: `enabled`, `disabled`, or `deleted`. Empty string when the record has no channel or the channel no longer exists.",
             "enum": [
-              "Triggered",
-              "Processing",
-              "Closed"
-            ],
-            "type": "string"
+              "enabled",
+              "disabled",
+              "deleted",
+              ""
+            ]
           },
-          "reporter_email": {
-            "description": "Reporter email for manually created incidents.",
-            "type": "string"
+          "detail_url": {
+            "type": "string",
+            "description": "Web console URL for the incident."
           },
-          "resolution": {
-            "description": "Resolution notes.",
-            "type": "string"
+          "silence_url": {
+            "type": "string",
+            "description": "Quick-silence URL for this incident."
           },
-          "responders": {
-            "description": "Current responders with assignment/acknowledgement state.",
+          "links": {
+            "type": "array",
             "items": {
-              "$ref": "#/components/schemas/Responder"
+              "$ref": "#/components/schemas/LinkItem"
             },
-            "type": "array"
+            "description": "Channel-level link integrations rendered for this incident."
           },
-          "root_cause": {
-            "description": "Root cause analysis.",
-            "type": "string"
+          "integration_type": {
+            "type": "string",
+            "description": "Plugin type of the incident's first integration (see `integration_types` for all). Open set, for example `prometheus.alert` or `monit.alert`; `POST /integration/type/list` returns the full list. Omitted when the incident has no integration or the endpoint does not fill it."
           },
-          "silence_url": {
-            "description": "Quick-silence URL for this incident.",
-            "type": "string"
+          "post_mortem_id": {
+            "type": "string",
+            "description": "Associated post-mortem ID, if any. One incident can only link to a single post-mortem."
           },
-          "snoozed_before": {
-            "description": "Unix timestamp (seconds) until which notifications are snoozed. 0 if not snoozed.",
-            "format": "int64",
-            "type": "integer"
+          "images": {
+            "type": [
+              "array",
+              "null"
+            ],
+            "items": {
+              "$ref": "#/components/schemas/Image"
+            },
+            "description": "Images attached to the incident; `null` when there are none. Tokens starting with `img_` are returned as download URLs."
           },
-          "start_time": {
-            "description": "Unix timestamp (seconds) when the incident started.",
-            "format": "int64",
-            "type": "integer"
+          "manual_overrides": {
+            "type": [
+              "array",
+              "null"
+            ],
+            "items": {
+              "type": "string",
+              "enum": [
+                "title",
+                "description",
+                "incident_severity"
+              ]
+            },
+            "description": "Fields edited manually and therefore no longer overwritten by merged alerts: `title`, `description`, `incident_severity`. `null` when none."
           },
-          "team_id": {
-            "description": "ID of the team that owns the incident's channel. 0 when the channel has no team.",
+          "data_source_id": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Deprecated. Use `integration_id` instead.",
+            "deprecated": true
           },
-          "title": {
-            "description": "Incident title.",
-            "type": "string"
+          "data_source_ids": {
+            "type": [
+              "array",
+              "null"
+            ],
+            "items": {
+              "type": "integer",
+              "format": "int64"
+            },
+            "description": "Deprecated. Use `integration_ids` instead.",
+            "deprecated": true
           },
-          "updated_at": {
-            "description": "Last update timestamp (seconds).",
-            "format": "int64",
-            "type": "integer"
+          "data_source_type": {
+            "type": "string",
+            "description": "Deprecated; same value as `integration_type`.",
+            "deprecated": true
+          },
+          "data_source_types": {
+            "type": [
+              "array",
+              "null"
+            ],
+            "items": {
+              "type": "string"
+            },
+            "description": "Deprecated. Use `integration_types` instead.",
+            "deprecated": true
           }
-        },
-        "required": [
-          "incident_id",
-          "account_id",
-          "channel_id",
-          "team_id",
-          "integration_id",
-          "integration_ids",
-          "integration_types",
-          "dedup_key",
-          "equals_md5",
-          "start_time",
-          "end_time",
-          "last_time",
-          "ack_time",
-          "close_time",
-          "creator_id",
-          "closer_id",
-          "owner_id",
-          "incident_status",
-          "incident_severity",
-          "progress",
-          "title",
-          "description",
-          "ai_summary",
-          "impact",
-          "root_cause",
-          "resolution",
-          "num",
-          "created_at",
-          "updated_at",
-          "snoozed_before",
-          "group_method",
-          "ever_muted",
-          "labels",
-          "fields",
-          "assigned_to",
-          "alert_cnt",
-          "active_alert_cnt",
-          "alert_event_cnt",
-          "responders",
-          "account_name",
-          "account_locale",
-          "account_time_zone",
-          "channel_name",
-          "channel_status",
-          "detail_url",
-          "silence_url",
-          "post_mortem_id",
-          "images",
-          "manual_overrides"
-        ],
-        "type": "object"
+        }
       },
       "IncidentInfoRequest": {
         "description": "Lookup parameters for a single incident. Supply either incident_id or num.",
@@ -12088,35 +12372,35 @@
         "type": "object"
       },
       "IncidentListResponse": {
+        "type": "object",
         "description": "Paginated list of incidents.",
+        "required": [
+          "items",
+          "total",
+          "has_next_page"
+        ],
         "properties": {
-          "has_next_page": {
-            "description": "True when more results are available beyond this page.",
-            "type": "boolean"
-          },
           "items": {
-            "description": "Incident list for the current page.",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/IncidentInfo"
             },
-            "type": "array"
-          },
-          "search_after_ctx": {
-            "description": "Opaque cursor to pass as `search_after_ctx` on the next request.",
-            "type": "string"
+            "description": "Incident list for the current page."
           },
           "total": {
-            "description": "Total number of matching incidents.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Number of matching incidents, capped at 1,000. For `POST /incident/list-by-ids`, the number of incidents found."
+          },
+          "has_next_page": {
+            "type": "boolean",
+            "description": "Whether another page exists. With `p`/`limit` paging it is computed against the capped `total`, so it is `false` past 1,000 matches even when more exist; with `search_after_ctx` paging it reflects the real data. Always `false` for `POST /incident/list-by-ids`."
+          },
+          "search_after_ctx": {
+            "type": "string",
+            "description": "Cursor pointing at the last item of this page; pass it as `search_after_ctx` on the next request to continue past the 1,000-item page limit. Returned for every non-empty page in `p`/`limit` mode, and in cursor mode only when `has_next_page` is `true`. Omitted by `POST /incident/list-by-ids`."
           }
-        },
-        "required": [
-          "items",
-          "total",
-          "has_next_page"
-        ],
-        "type": "object"
+        }
       },
       "IncidentRawItem": {
         "description": "Raw incident row returned by the analytics incident list, with per-incident handling metrics attached.",
@@ -12409,135 +12693,141 @@
         "type": "object"
       },
       "IncidentShort": {
+        "type": "object",
         "description": "Brief incident reference embedded in an alert.",
         "properties": {
           "incident_id": {
-            "description": "Incident ID (ObjectID hex string).",
-            "type": "string"
-          },
-          "progress": {
-            "description": "Incident progress — one of `Triggered`, `Processing`, `Closed`.",
-            "type": "string"
+            "type": "string",
+            "description": "Incident ID (ObjectID hex string)."
           },
           "title": {
-            "description": "Incident title.",
-            "type": "string"
+            "type": "string",
+            "description": "Incident title."
+          },
+          "progress": {
+            "type": "string",
+            "description": "Incident progress: `Triggered` not yet acknowledged; `Processing` acknowledged and being handled; `Closed` resolved.",
+            "enum": [
+              "Triggered",
+              "Processing",
+              "Closed"
+            ]
           }
-        },
-        "type": "object"
+        }
       },
       "InhibitRuleItem": {
+        "type": "object",
+        "required": [
+          "account_id",
+          "channel_id",
+          "rule_name",
+          "description",
+          "source_filters",
+          "target_filters",
+          "equals",
+          "is_directly_discard",
+          "status",
+          "rule_id",
+          "updated_by",
+          "created_at",
+          "updated_at"
+        ],
         "properties": {
           "account_id": {
-            "description": "ID of the account the rule belongs to.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "ID of the account the rule belongs to."
           },
           "channel_id": {
-            "description": "ID of the channel the rule belongs to.",
-            "format": "int64",
-            "type": "integer"
-          },
-          "created_at": {
-            "description": "Creation time, Unix timestamp in seconds.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "ID of the channel the rule belongs to."
           },
-          "deleted_at": {
-            "description": "Deletion time, Unix timestamp in seconds. Omitted unless the rule is soft-deleted; deleted rules are excluded from list responses.",
-            "format": "int64",
-            "type": "integer"
+          "rule_name": {
+            "type": "string",
+            "description": "Inhibit rule name, 1–39 characters."
           },
           "description": {
-            "description": "Rule description.",
-            "type": "string"
+            "type": "string",
+            "description": "Rule description."
+          },
+          "source_filters": {
+            "$ref": "#/components/schemas/FilterGroup",
+            "description": "Conditions the source alert must match, evaluated against stored active alerts. Supported keys: `status`, `incident_status`, `alert_status`, `severity`, `incident_severity`, `alert_severity`, `title`, `description`, or any `labels.<name>`. Empty makes the rule inert."
+          },
+          "target_filters": {
+            "$ref": "#/components/schemas/FilterGroup",
+            "description": "Conditions the incoming target alert event must match to be inhibited; empty means every incoming event is a target. Keys: `title`, `description`, `severity` (alias `alert_severity`, `event_severity`), `status`, `alert_key`, `title_rule`, `integration_id` (alias `data_source_id`), or any `labels.<name>`."
           },
           "equals": {
-            "description": "Field keys whose values must be equal between the source (inhibiting) alert and the target (suppressed) alert, e.g. `data_source_id` or `labels.cluster`.",
+            "type": "array",
             "items": {
               "type": "string"
             },
-            "type": "array"
+            "description": "Keys whose values must be equal on the source alert and the incoming event. Only `title`, `severity` and `labels.<name>` take effect; with any other key the rule never fires."
           },
           "is_directly_discard": {
-            "description": "When true, matching alert events are discarded entirely; when false, alerts are still recorded but marked as muted by this rule.",
-            "type": "boolean"
+            "type": "boolean",
+            "description": "When true, matching alert events are discarded entirely; when false, alerts are still recorded but marked as muted by this rule."
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "enabled",
+              "disabled"
+            ],
+            "description": "Rule status: `enabled` or `disabled`; deleted rules never appear in the list."
           },
           "rule_id": {
-            "description": "Rule ID (MongoDB ObjectID).",
+            "type": "string",
             "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
-          },
-          "rule_name": {
-            "description": "Rule name.",
-            "type": "string"
-          },
-          "source_filters": {
-            "$ref": "#/components/schemas/FilterGroup",
-            "description": "Conditions the source alert must match, evaluated against stored active alerts. Supported keys: `status`, `incident_status`, `alert_status`, `severity`, `incident_severity`, `alert_severity`, `title`, `description`, or any `labels.<name>`. Empty makes the rule inert."
+            "description": "Rule ID (MongoDB ObjectID)."
           },
-          "status": {
-            "description": "Rule status: `enabled` or `disabled`; deleted rules never appear in the list.",
-            "enum": [
-              "enabled",
-              "disabled"
-            ],
-            "type": "string"
+          "updated_by": {
+            "type": "integer",
+            "format": "int64",
+            "description": "ID of the user who last updated the rule."
           },
-          "target_filters": {
-            "$ref": "#/components/schemas/FilterGroup",
-            "description": "Conditions the incoming target alert event must match to be suppressed; empty means every event is a target."
+          "created_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Creation time, Unix timestamp in seconds."
           },
           "updated_at": {
-            "description": "Last update time, Unix timestamp in seconds.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Last update time, Unix timestamp in seconds."
           },
-          "updated_by": {
-            "description": "ID of the user who last updated the rule.",
+          "deleted_at": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Deletion time, Unix timestamp in seconds. Omitted unless the rule is soft-deleted; deleted rules are excluded from list responses."
           }
-        },
-        "required": [
-          "account_id",
-          "channel_id",
-          "rule_name",
-          "description",
-          "source_filters",
-          "target_filters",
-          "equals",
-          "is_directly_discard",
-          "status",
-          "rule_id",
-          "updated_by",
-          "created_at",
-          "updated_at"
-        ],
-        "type": "object"
+        }
       },
       "InitPostMortemRequest": {
+        "type": "object",
         "description": "Parameters for initializing a post-mortem report from incidents.",
+        "required": [
+          "incident_ids",
+          "template_id"
+        ],
         "properties": {
           "incident_ids": {
-            "description": "Incident IDs to link to the report. 1-10 incidents.",
+            "type": "array",
+            "minItems": 1,
+            "maxItems": 10,
             "items": {
-              "type": "string"
+              "type": "string",
+              "pattern": "^[0-9a-fA-F]{24}$"
             },
-            "maxItems": 10,
-            "minItems": 1,
-            "type": "array"
+            "description": "Incident IDs (MongoDB ObjectIDs) to link to the report, 1–10. All must exist in the account. The same set always maps to the same report."
           },
           "template_id": {
-            "description": "Template ID used to initialize the report.",
-            "type": "string"
+            "type": "string",
+            "description": "Template ID from `POST /incident/post-mortem/template/list`, e.g. the built-in `post_mortem_default_tmpl_en-us` or `post_mortem_default_tmpl_zh-cn`, or a custom template ID."
           }
-        },
-        "required": [
-          "incident_ids",
-          "template_id"
-        ],
-        "type": "object"
+        }
       },
       "InsightAlertByLabelItem": {
         "properties": {
@@ -12580,150 +12870,150 @@
         "type": "object"
       },
       "InsightFilter": {
+        "type": "object",
         "description": "Shared filter envelope for insight and export endpoints. Severities accept up to 3 values; team/channel/responder/incident filters accept up to 100 IDs each. The time range cannot exceed one year.",
+        "required": [
+          "start_time",
+          "end_time"
+        ],
         "properties": {
-          "asc": {
-            "description": "Sort ascending when `true`, descending otherwise. Only used by `/insight/incident/list`.",
-            "type": "boolean"
+          "start_time": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Start time, Unix seconds. Must be greater than 0.",
+            "exclusiveMinimum": 0
           },
-          "channel_ids": {
-            "description": "Filter by channel IDs. At most 100 entries.",
+          "end_time": {
+            "type": "integer",
+            "format": "int64",
+            "description": "End time, Unix seconds. Must be greater than `start_time`."
+          },
+          "team_ids": {
+            "type": "array",
             "items": {
-              "format": "int64",
-              "type": "integer"
+              "type": "integer",
+              "format": "int64"
             },
-            "maxItems": 100,
-            "type": "array"
-          },
-          "description_html_to_text": {
-            "description": "Strip HTML markup from the description column when exporting.",
-            "type": "boolean"
+            "description": "Filter by team IDs. At most 100 entries.",
+            "maxItems": 100
           },
-          "end_time": {
-            "description": "End time, Unix seconds. Must be greater than `start_time`.",
-            "format": "int64",
-            "type": "integer"
+          "channel_ids": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "int64"
+            },
+            "description": "Filter by channel IDs. At most 100 entries.",
+            "maxItems": 100
           },
-          "export_fields": {
-            "description": "CSV column keys to include in the export, in the given order; unknown or duplicate keys are rejected. The valid key set differs per export endpoint — see each export operation's description. Only used by the export endpoints; at most 50 entries.",
+          "responder_ids": {
+            "type": "array",
             "items": {
-              "type": "string"
+              "type": "integer",
+              "format": "int64"
             },
-            "maxItems": 50,
-            "type": "array"
+            "description": "Filter by responder member IDs. Used by `/insight/responder` (which responders to return) and the incident list/export (incidents any of them responded to); ignored by the account/team/channel and top-K endpoints. At most 100 entries.",
+            "maxItems": 100
           },
-          "fields": {
-            "additionalProperties": true,
-            "description": "Custom-field filters (exact match).",
-            "type": "object"
+          "severities": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "enum": [
+                "Critical",
+                "Warning",
+                "Info",
+                "Ok"
+              ]
+            },
+            "description": "Filter by severity: `Critical`, `Warning`, `Info`, or `Ok`. At most 3 entries.",
+            "maxItems": 3
           },
           "incident_ids": {
-            "description": "Filter by incident IDs (MongoDB ObjectIDs). At most 100 entries.",
+            "type": "array",
             "items": {
-              "pattern": "^[0-9a-fA-F]{24}$",
-              "type": "string"
+              "type": "string",
+              "pattern": "^[0-9a-fA-F]{24}$"
             },
-            "maxItems": 100,
-            "type": "array"
-          },
-          "include_ever_muted": {
-            "description": "Include incidents that have ever been muted. By default, they are excluded.",
-            "type": "boolean"
+            "description": "Filter by incident IDs (24-character hex). Used only by the incident list and export. At most 100 entries.",
+            "maxItems": 100
           },
-          "is_my_team": {
-            "description": "Restrict results to teams the caller belongs to. When true and the caller has no teams, the result set is empty.",
-            "type": "boolean"
+          "query": {
+            "type": "string",
+            "description": "Substring match on the incident title (SQL `LIKE %query%`)."
           },
           "labels": {
+            "type": "object",
             "additionalProperties": {
               "type": "string"
             },
-            "description": "Label filters (exact match).",
-            "type": "object"
+            "description": "Label filters (exact match)."
+          },
+          "fields": {
+            "type": "object",
+            "additionalProperties": true,
+            "description": "Custom-field filters (exact match)."
           },
           "orderby": {
-            "description": "Sort field of the incident list; only `created_at` (incident creation time) is supported. Used by `/insight/incident/list` only.",
+            "type": "string",
             "enum": [
               "created_at"
             ],
-            "type": "string"
+            "description": "Sort field of the incident list; only `created_at` (incident creation time, the default). Used by `/insight/incident/list` and `/insight/incident/export`."
           },
-          "query": {
-            "description": "Substring match on the incident title (SQL `LIKE %query%`).",
-            "type": "string"
-          },
-          "responder_ids": {
-            "description": "Filter by responder person IDs. At most 100 entries.",
-            "items": {
-              "format": "int64",
-              "type": "integer"
-            },
-            "maxItems": 100,
-            "type": "array"
+          "asc": {
+            "type": "boolean",
+            "description": "Sort ascending when `true`, descending (default) otherwise. Used by the incident list and export; `/insight/alert/topk-by-label` has its own `asc`."
           },
-          "seconds_to_ack_from": {
-            "description": "Lower bound (inclusive) on time-to-acknowledge, in seconds.",
-            "format": "int64",
-            "minimum": 0,
-            "type": "integer"
+          "is_my_team": {
+            "type": "boolean",
+            "description": "Restrict results to the caller's teams (intersected with `team_ids` when both are set). When the caller belongs to no team, the result is empty."
           },
-          "seconds_to_ack_to": {
-            "description": "Upper bound (exclusive) on time-to-acknowledge, in seconds. Must be greater than `seconds_to_ack_from` when both are set.",
-            "format": "int64",
-            "minimum": 0,
-            "type": "integer"
+          "time_zone": {
+            "type": "string",
+            "description": "IANA time zone (for example `Asia/Shanghai` or `UTC`) used to cut `aggregate_unit` buckets; abbreviations such as `EST` and `Etc/GMT±N` are rejected. Defaults to UTC. `/insight/incident/export` uses it to render times, falling back to the account time zone and then `Asia/Shanghai`."
           },
           "seconds_to_close_from": {
-            "description": "Lower bound (inclusive) on time-to-close, in seconds.",
+            "type": "integer",
             "format": "int64",
-            "minimum": 0,
-            "type": "integer"
+            "description": "Lower bound (inclusive) on time-to-close, in seconds.",
+            "minimum": 0
           },
           "seconds_to_close_to": {
-            "description": "Upper bound (exclusive) on time-to-close, in seconds. Must be greater than `seconds_to_close_from` when both are set.",
+            "type": "integer",
             "format": "int64",
-            "minimum": 0,
-            "type": "integer"
+            "description": "Upper bound (exclusive) on time-to-close, in seconds. Must be greater than `seconds_to_close_from` when both are set.",
+            "minimum": 0
           },
-          "severities": {
-            "description": "Filter by severity. At most 3 entries.",
-            "items": {
-              "enum": [
-                "Critical",
-                "Warning",
-                "Info",
-                "Ok"
-              ],
-              "type": "string"
-            },
-            "maxItems": 3,
-            "type": "array"
+          "seconds_to_ack_from": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Lower bound (inclusive) on time-to-acknowledge, in seconds.",
+            "minimum": 0
           },
-          "start_time": {
-            "description": "Start time, Unix seconds. Must be greater than 0.",
-            "exclusiveMinimum": 0,
+          "seconds_to_ack_to": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Upper bound (exclusive) on time-to-acknowledge, in seconds. Must be greater than `seconds_to_ack_from` when both are set.",
+            "minimum": 0
           },
-          "team_ids": {
-            "description": "Filter by team IDs. At most 100 entries.",
+          "export_fields": {
+            "type": "array",
             "items": {
-              "format": "int64",
-              "type": "integer"
+              "type": "string"
             },
-            "maxItems": 100,
-            "type": "array"
+            "description": "CSV column keys to include in the export, in the given order; unknown or duplicate keys are rejected. The valid key set differs per export endpoint — see each export operation's description. Only used by the export endpoints; at most 50 entries.",
+            "maxItems": 50
           },
-          "time_zone": {
-            "description": "IANA time zone name used to cut day/week/month buckets (e.g. `Asia/Shanghai`). Optional; defaults to UTC, except that `/insight/incident/export` falls back to the account time zone and then `Asia/Shanghai`.",
-            "type": "string"
+          "description_html_to_text": {
+            "type": "boolean",
+            "description": "Strip HTML markup from the description column when exporting."
+          },
+          "include_ever_muted": {
+            "type": "boolean",
+            "description": "Include incidents that have ever been muted. By default, they are excluded."
           }
-        },
-        "required": [
-          "start_time",
-          "end_time"
-        ],
-        "type": "object"
+        }
       },
       "InsightIncidentExportRequest": {
         "$ref": "#/components/schemas/InsightFilter"
@@ -12768,29 +13058,29 @@
         ]
       },
       "InsightIncidentListResponse": {
+        "type": "object",
         "properties": {
+          "total": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Number of matching incidents. When the request carried `search_after_ctx`, only incidents after the cursor are counted."
+          },
           "has_next_page": {
-            "description": "Whether another page of results is available.",
-            "type": "boolean"
+            "type": "boolean",
+            "description": "Whether another page of results is available."
+          },
+          "search_after_ctx": {
+            "type": "string",
+            "description": "Cursor token to fetch the next page — the incident ID of the last row on this page. Present only when `has_next_page` is true."
           },
           "items": {
-            "description": "Incident items.",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/IncidentRawItem"
             },
-            "type": "array"
-          },
-          "search_after_ctx": {
-            "description": "Cursor token to fetch the next page — the incident ID of the last row on this page. Present only when `has_next_page` is true.",
-            "type": "string"
-          },
-          "total": {
-            "description": "Total matching incidents.",
-            "format": "int64",
-            "type": "integer"
+            "description": "Incidents on this page; an empty array when none match."
           }
-        },
-        "type": "object"
+        }
       },
       "InsightQueryRequest": {
         "allOf": [
@@ -12798,23 +13088,23 @@
             "$ref": "#/components/schemas/InsightFilter"
           },
           {
+            "type": "object",
             "description": "Insight dimension-aggregation request. Extends InsightFilter with aggregation controls.",
             "properties": {
+              "split_hours": {
+                "type": "boolean",
+                "description": "When `true`, each bucket is further split into `work`, `sleep` and `off` hours, returned as separate rows with `hours` set."
+              },
               "aggregate_unit": {
-                "description": "Aggregates metrics by time granularity. When set, the time range must be at least 24 hours; with `day` granularity the range must not exceed 31 days. `day` buckets by calendar day, `week` by calendar week, and `month` by calendar month, with boundaries aligned to `time_zone`.",
+                "type": "string",
                 "enum": [
                   "day",
                   "week",
                   "month"
                 ],
-                "type": "string"
-              },
-              "split_hours": {
-                "description": "When true, metrics are split into `work`/`sleep`/`off` hour buckets.",
-                "type": "boolean"
+                "description": "Split the range into time buckets; omit for a single bucket covering the whole range. Requires a range of at least 24 hours, and `day` allows at most 31 days.\n- `day`: calendar days in `time_zone` (the first bucket runs from `start_time` to the next midnight).\n- `week`: consecutive 7-day buckets starting at `start_time` (not aligned to Monday).\n- `month`: calendar months in `time_zone` (the first bucket runs from `start_time` to the 1st of the next month)."
               }
-            },
-            "type": "object"
+            }
           }
         ]
       },
@@ -12824,195 +13114,235 @@
             "$ref": "#/components/schemas/InsightQueryRequest"
           },
           {
+            "type": "object",
+            "required": [
+              "label"
+            ],
             "properties": {
-              "asc": {
-                "description": "Sort ascending when `true`, descending otherwise.",
-                "type": "boolean"
-              },
-              "k": {
-                "default": 20,
-                "description": "Number of top entries to return, between 1 and 100. Defaults to 20.",
-                "maximum": 100,
-                "minimum": 1,
-                "type": "integer"
-              },
               "label": {
-                "description": "Aggregation dimension. `check` aggregates by the event's `labels.check` label (monitoring check); `resource` aggregates by the `labels.resource` label (monitored resource identifier).",
+                "type": "string",
                 "enum": [
                   "check",
                   "resource"
                 ],
-                "type": "string"
+                "description": "Aggregation dimension. `check` aggregates by the event's `labels.check` label (monitoring check); `resource` aggregates by the `labels.resource` label (monitored resource identifier)."
+              },
+              "k": {
+                "type": "integer",
+                "description": "Number of label values to return, between 1 and 100 (default 20). With `split_hours`, applied per hour bucket.",
+                "minimum": 1,
+                "maximum": 100,
+                "default": 20
               },
               "orderby": {
-                "description": "Sort field. `total_alert_cnt` sorts by alert count; `total_alert_event_cnt` sorts by raw alert event count (default).",
+                "type": "string",
                 "enum": [
                   "total_alert_cnt",
                   "total_alert_event_cnt"
                 ],
-                "type": "string"
+                "description": "Sort field. `total_alert_cnt` sorts by alert count; `total_alert_event_cnt` sorts by raw alert event count (default)."
+              },
+              "asc": {
+                "type": "boolean",
+                "description": "Sort ascending when `true`, descending otherwise."
               }
-            },
-            "required": [
-              "label"
-            ],
-            "type": "object"
+            }
           }
         ]
       },
       "InviteMemberItem": {
+        "type": "object",
         "description": "A member to invite. Identify the invitee by `email` alone, or by `member_name` + `phone` together.",
         "properties": {
-          "country_code": {
-            "description": "ISO 3166-1 alpha-2 region code for `phone` (e.g. \"CN\"). Validated and normalized to upper case before storage; invalid values are rejected with a 400. Also the parsing hint when `phone` has no \"+\" prefix (defaults to \"CN\").",
-            "type": "string"
-          },
-          "email": {
-            "description": "Email address. Required when `phone` is not provided.",
-            "type": "string"
-          },
-          "locale": {
-            "description": "Locale. One of: `zh-CN` (Simplified Chinese), `en-US` (English); other values are rejected with a 400.",
-            "enum": [
-              "zh-CN",
-              "en-US"
-            ],
-            "type": "string"
-          },
           "member_name": {
-            "description": "Display name, 2–39 characters. Required when `email` is not provided; derived from the email prefix when omitted.",
-            "maxLength": 39,
+            "type": "string",
             "minLength": 2,
-            "type": "string"
+            "maxLength": 39,
+            "description": "Display name, 2–39 characters. Required when `email` is not provided; derived from the email prefix when omitted."
+          },
+          "email": {
+            "type": "string",
+            "description": "Email address, stored in lower case. Required when `phone` is not provided."
           },
           "phone": {
-            "description": "Phone number. Required when `email` is not provided.",
-            "type": "string"
+            "type": "string",
+            "description": "Phone number. Required when `email` is not provided."
           },
-          "ref_id": {
-            "description": "External reference ID",
-            "type": "string"
+          "country_code": {
+            "type": "string",
+            "description": "ISO 3166-1 alpha-2 region code for `phone` (e.g. \"CN\"). Validated and normalized to upper case before storage; invalid values are rejected with a 400. Also the parsing hint when `phone` has no \"+\" prefix (defaults to \"CN\")."
           },
           "role_ids": {
-            "description": "Role IDs to assign",
+            "type": "array",
             "items": {
-              "format": "uint64",
-              "type": "integer"
+              "type": "integer",
+              "format": "uint64"
             },
-            "type": "array"
+            "description": "Role IDs to assign: built-in `2` (Admin), `6` (Responder), `8` (Viewer), or custom role IDs from `POST /role/list`. Defaults to Viewer (`8`) when omitted; an ID that does not exist returns `400`."
+          },
+          "locale": {
+            "type": "string",
+            "enum": [
+              "zh-CN",
+              "en-US"
+            ],
+            "description": "Locale: `zh-CN` (Simplified Chinese) or `en-US` (English); other values are rejected with a 400. Defaults to the account's locale when omitted."
           },
           "time_zone": {
-            "description": "Time zone",
-            "type": "string"
+            "type": "string",
+            "description": "IANA time zone name such as `Asia/Shanghai`. Omit it to have the member follow the account's time zone; an invalid name returns `400`."
+          },
+          "ref_id": {
+            "type": "string",
+            "description": "External reference ID (for example an employee ID in an HR system), usable later as a lookup key in `POST /member/delete` and `POST /member/info/reset`."
           }
-        },
-        "type": "object"
+        }
       },
       "KnowledgeFileDeleteRequest": {
+        "type": "object",
         "description": "Knowledge file to remove.",
         "properties": {
-          "force": {
-            "description": "Delete even when other knowledge files reference this file; the referrers are then returned as warnings instead of blocking the delete.",
-            "type": "boolean"
-          },
           "pack_id": {
-            "description": "Knowledge ID; defaults to the caller's account-scope knowledge.",
-            "type": "string"
+            "type": "string",
+            "description": "Knowledge ID; defaults to the caller's account-scope knowledge."
           },
           "rel_path": {
-            "description": "Path of the file relative to the knowledge root.",
-            "type": "string"
+            "type": "string",
+            "description": "Path of the file relative to the knowledge root. Same path rules as `POST /safari/knowledge/file/put`."
+          },
+          "force": {
+            "type": "boolean",
+            "description": "Delete even when other knowledge files reference this file; the referrers are then returned as warnings instead of blocking the delete."
+          },
+          "expected_version": {
+            "type": "integer",
+            "minimum": 0,
+            "default": 0,
+            "description": "Optimistic-concurrency guard. `0` or omitted: delete unconditionally. A positive value: delete only if the knowledge's current `version` equals it; otherwise nothing is deleted and the call returns HTTP 200 with `status` = `conflict` and the current `version`."
           }
         },
         "required": [
           "rel_path"
-        ],
-        "type": "object"
+        ]
       },
       "KnowledgeFileDeleteResponse": {
-        "description": "Deletion result; empty unless warnings were raised.",
+        "type": "object",
+        "description": "Delete result.",
         "properties": {
+          "status": {
+            "type": "string",
+            "enum": [
+              "ok",
+              "conflict"
+            ],
+            "description": "Outcome of the delete.\n- `ok`: the file was deleted, or did not exist.\n- `conflict`: `expected_version` did not match the current knowledge version, so nothing was deleted."
+          },
           "warnings": {
-            "description": "Non-blocking warnings after deletion; `code=still_referenced_by` means the (force-)deleted file is still @ref-referenced by other files in the knowledge (`refs` lists the referrers). Absent when there are no warnings (omitempty).",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/KnowledgeWarning"
             },
-            "type": "array"
+            "description": "Non-blocking warnings; `still_referenced_by` means `force` deleted a file that other files still reference (`refs` lists them). Omitted when there are no warnings."
+          },
+          "version": {
+            "type": "integer",
+            "description": "Knowledge `version` after the delete (unchanged if the file did not exist). When the file did not exist and `expected_version` was not sent, this is `0`. On `conflict`, the current version."
+          },
+          "message": {
+            "type": "string",
+            "description": "Explanation of the conflict. Present only when `status` is `conflict`."
           }
         },
-        "type": "object"
+        "required": [
+          "status",
+          "version"
+        ]
       },
       "KnowledgeFileGetRequest": {
+        "type": "object",
         "description": "Which file to fetch.",
         "properties": {
           "pack_id": {
-            "description": "Knowledge ID; defaults to the caller's account-scope knowledge.",
-            "type": "string"
+            "type": "string",
+            "description": "Knowledge ID; defaults to the caller's account-scope knowledge."
           },
           "rel_path": {
-            "description": "Path of the file relative to the knowledge root.",
-            "type": "string"
+            "type": "string",
+            "description": "Path of the file relative to the knowledge root. If no file exists at this path, the call still succeeds with `file` set to `null` and an empty `content_b64`."
           }
         },
         "required": [
           "rel_path"
-        ],
-        "type": "object"
+        ]
       },
       "KnowledgeFileGetResponse": {
-        "description": "File metadata plus its base64-encoded content.",
+        "type": "object",
+        "description": "File metadata, its base64-encoded content, and the current knowledge version.",
         "properties": {
+          "file": {
+            "description": "Metadata of the file; `null` when no file exists at `rel_path`.",
+            "oneOf": [
+              {
+                "$ref": "#/components/schemas/KnowledgeFileItem"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
           "content_b64": {
-            "description": "Base64-encoded file content; decodes to UTF-8 text.",
-            "type": "string"
+            "type": "string",
+            "description": "Base64-encoded file content. Empty string when the file does not exist (or is empty)."
           },
-          "file": {
-            "$ref": "#/components/schemas/KnowledgeFileItem"
+          "version": {
+            "type": "integer",
+            "description": "Current `version` of the knowledge. Pass it as `expected_version` to `POST /safari/knowledge/file/put` or `POST /safari/knowledge/file/delete` to reject the write if someone else changed the knowledge in between."
           }
         },
         "required": [
           "file",
-          "content_b64"
-        ],
-        "type": "object"
+          "content_b64",
+          "version"
+        ]
       },
       "KnowledgeFileItem": {
+        "type": "object",
         "description": "Metadata of one knowledge file. Content is fetched separately via file/get.",
         "properties": {
-          "checksum": {
-            "description": "SHA-256 hex digest of the file content.",
-            "type": "string"
-          },
-          "content_type": {
-            "description": "MIME type; inferred from the file extension when not set on upload.",
-            "type": "string"
-          },
           "file_id": {
-            "description": "File ID (`kfl_` prefix).",
-            "type": "string"
+            "type": "string",
+            "description": "File ID (`kfl_` prefix)."
           },
           "pack_id": {
-            "description": "ID of the knowledge that contains the file.",
-            "type": "string"
+            "type": "string",
+            "description": "ID of the knowledge that contains the file."
           },
           "rel_path": {
-            "description": "Path relative to the knowledge root, e.g. `runbooks/restart.md`.",
-            "type": "string"
+            "type": "string",
+            "description": "Path relative to the knowledge root, using `/` separators, e.g. `runbooks/restart.md`. Unique within the knowledge."
+          },
+          "content_type": {
+            "type": "string",
+            "description": "MIME type stored with the file. Open set: when `content_type` is omitted on write it is derived from the extension of `rel_path` — `.md` → `text/markdown`, `.yaml`/`.yml` → `text/yaml`, `.json` → `application/json`, `.sh` → `text/x-sh`, anything else → `text/plain`; a value passed explicitly is stored as given."
           },
           "size_bytes": {
+            "type": "integer",
             "description": "File size in bytes.",
-            "format": "int64",
-            "type": "integer"
+            "format": "int64"
           },
-          "updated_at_ms": {
-            "description": "Unix timestamp in milliseconds when the file was last modified.",
-            "format": "int64",
-            "type": "integer"
+          "checksum": {
+            "type": "string",
+            "description": "SHA-256 hex digest of the file content."
           },
           "updated_by": {
+            "type": "integer",
             "description": "Person ID of the member who last modified the file.",
-            "format": "int64",
-            "type": "integer"
+            "format": "int64"
+          },
+          "updated_at_ms": {
+            "type": "integer",
+            "description": "Unix timestamp in milliseconds when the file was last modified.",
+            "format": "int64"
           }
         },
         "required": [
@@ -13024,8 +13354,7 @@
           "checksum",
           "updated_by",
           "updated_at_ms"
-        ],
-        "type": "object"
+        ]
       },
       "KnowledgeFileListRequest": {
         "description": "Which knowledge's files to list.",
@@ -13046,70 +13375,99 @@
         "type": "object"
       },
       "KnowledgeFileListResponse": {
-        "description": "Files in the knowledge.",
+        "type": "object",
+        "description": "All files in the knowledge plus the current knowledge version.",
         "properties": {
           "files": {
-            "description": "Array of files in the specified knowledge; empty array when it has no files.",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/KnowledgeFileItem"
             },
-            "type": "array"
+            "description": "Array of files in the specified knowledge; empty array when it has no files."
           },
           "total": {
-            "description": "Total number of files in the knowledge.",
-            "format": "int64",
-            "type": "integer"
+            "type": "integer",
+            "description": "Number of files in `files` — always the full file count of the knowledge, since this endpoint does not paginate.",
+            "format": "int64"
+          },
+          "version": {
+            "type": "integer",
+            "description": "Current `version` of the knowledge; usable as `expected_version` for file writes."
           }
         },
         "required": [
           "files",
-          "total"
-        ],
-        "type": "object"
+          "total",
+          "version"
+        ]
       },
       "KnowledgeFilePutRequest": {
+        "type": "object",
         "description": "File to create or overwrite. The body is base64 text in `content_b64`, not a multipart upload.",
         "properties": {
+          "pack_id": {
+            "type": "string",
+            "description": "Knowledge ID; defaults to the caller's account-scope knowledge."
+          },
+          "rel_path": {
+            "type": "string",
+            "description": "Destination path relative to the knowledge root; an existing file at this path is overwritten. Must use `/` separators, must not start with `/`, must already be in normalized form, and no segment may be empty, `.`, `..`, or start with `.` (dotfiles are rejected)."
+          },
           "content_b64": {
-            "description": "Base64-encoded file content; must decode to valid UTF-8 text (binary is rejected). Per-file limit 1 MiB.",
-            "type": "string"
+            "type": "string",
+            "description": "Base64-encoded (standard alphabet) file content. The decoded bytes must be UTF-8 text with no NUL bytes and at most 1 MiB (`DUTY.md`: at most 32 KiB). Omit or send an empty string to write an empty file."
           },
           "content_type": {
-            "description": "MIME type; inferred from the file extension when omitted.",
-            "type": "string"
-          },
-          "pack_id": {
-            "description": "Knowledge ID; defaults to the caller's account-scope knowledge.",
-            "type": "string"
+            "type": "string",
+            "description": "MIME type to store with the file. Optional: when omitted it is derived from the extension of `rel_path` (`.md` → `text/markdown`, `.yaml`/`.yml` → `text/yaml`, `.json` → `application/json`, `.sh` → `text/x-sh`, otherwise `text/plain`). Any value passed is stored as given."
           },
-          "rel_path": {
-            "description": "Destination path relative to the knowledge root; existing files are overwritten.",
-            "type": "string"
+          "expected_version": {
+            "type": "integer",
+            "minimum": 0,
+            "default": 0,
+            "description": "Optimistic-concurrency guard. `0` or omitted: write unconditionally. A positive value: write only if the knowledge's current `version` equals it; otherwise nothing is written and the call returns HTTP 200 with `status` = `conflict` and the current `version`."
           }
         },
         "required": [
           "rel_path"
-        ],
-        "type": "object"
+        ]
       },
       "KnowledgeFilePutResponse": {
-        "description": "The written file plus any non-blocking warnings.",
+        "type": "object",
+        "description": "Write result. On success carries the written file; on a version conflict carries only `status`, `version` and `message`.",
         "properties": {
+          "status": {
+            "type": "string",
+            "enum": [
+              "ok",
+              "conflict"
+            ],
+            "description": "Outcome of the write.\n- `ok`: the change was committed.\n- `conflict`: `expected_version` did not match the current knowledge version, so nothing was changed; re-read the file and retry with the returned `version`."
+          },
           "file": {
-            "$ref": "#/components/schemas/KnowledgeFileItem"
+            "$ref": "#/components/schemas/KnowledgeFileItem",
+            "description": "The file as stored after the write. Omitted when `status` is `conflict`."
           },
           "warnings": {
-            "description": "Non-blocking warnings after a successful write; `code=unresolved_reference` means an @ref in the file content points to a file that does not exist in the knowledge. Absent when there are no warnings (omitempty).",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/KnowledgeWarning"
             },
-            "type": "array"
+            "description": "Non-blocking warnings; `unresolved_reference` means an @ref in the written content points to a path that does not exist in the knowledge. Omitted when there are no warnings."
+          },
+          "version": {
+            "type": "integer",
+            "description": "Knowledge `version` produced by this write when `status` is `ok`; the current version when `status` is `conflict`. Use it as `expected_version` for the next write."
+          },
+          "message": {
+            "type": "string",
+            "description": "Explanation of the conflict (`this knowledge was updated by someone else`). Present only when `status` is `conflict`."
           }
         },
         "required": [
-          "file"
-        ],
-        "type": "object"
+          "status",
+          "version"
+        ]
       },
       "KnowledgeGetRequest": {
         "description": "No request fields — the account-scope knowledge is always targeted.",
@@ -13150,105 +13508,106 @@
         "type": "object"
       },
       "KnowledgePackDeleteResponse": {
+        "type": "object",
         "description": "Deletion result.",
         "properties": {
           "ok": {
-            "description": "True when the knowledge was deleted.",
-            "type": "boolean"
+            "type": "boolean",
+            "description": "Always `true` on success; a failed delete returns an error instead."
           }
         },
         "required": [
           "ok"
-        ],
-        "type": "object"
+        ]
       },
       "KnowledgePackEnsureRequest": {
+        "type": "object",
         "description": "Scope at which to ensure knowledge exists.",
         "properties": {
           "scope": {
-            "description": "Scope of the knowledge to ensure. One of: `account` (account-level knowledge; scope_id is forced to the caller's account ID and only account admins may create it; first creation seeds a default DUTY.md), `team` (team-level knowledge; the `scope_id` team ID is required and the caller must belong to that team).",
+            "type": "string",
+            "description": "Scope of the knowledge to ensure.\n- `account`: the account knowledge. `scope_id` is replaced by the caller's account ID; only the account owner and admins may call this, even when the knowledge already exists. If the knowledge has no `DUTY.md`, a default one is written.\n- `team`: the knowledge of the team in `scope_id`. `scope_id` is required and the caller must be a member of that team.",
             "enum": [
               "account",
               "team"
-            ],
-            "type": "string"
+            ]
           },
           "scope_id": {
-            "description": "Team ID; required for `team` scope, ignored for `account` scope.",
-            "format": "int64",
-            "type": "integer"
+            "type": "integer",
+            "description": "Team ID. Required (non-zero) for `team` scope, otherwise the request fails with `InvalidParameter`; ignored for `account` scope.",
+            "format": "int64"
           }
         },
         "required": [
           "scope"
-        ],
-        "type": "object"
+        ]
       },
       "KnowledgePackItem": {
+        "type": "object",
         "description": "Knowledge — a versioned file tree staged into every AI SRE sandbox at session start. One knowledge exists per (account, scope, scope_id).",
         "properties": {
+          "pack_id": {
+            "type": "string",
+            "description": "Knowledge ID (`kpk_` prefix)."
+          },
           "account_id": {
+            "type": "integer",
             "description": "Account that owns the knowledge.",
-            "format": "int64",
-            "type": "integer"
-          },
-          "can_edit": {
-            "description": "Whether the caller can edit this knowledge.",
-            "type": "boolean"
-          },
-          "created_at_ms": {
-            "description": "Unix timestamp in milliseconds when the knowledge was created.",
-            "format": "int64",
-            "type": "integer"
-          },
-          "created_by": {
-            "description": "Person ID of the member who created the knowledge.",
-            "format": "int64",
-            "type": "integer"
-          },
-          "duty_version": {
-            "description": "Knowledge version at which DUTY.md was last authored or re-affirmed. When `version` is greater, DUTY.md no longer reflects every file in the knowledge.",
-            "type": "integer"
-          },
-          "file_count": {
-            "description": "Number of files in the knowledge.",
-            "type": "integer"
-          },
-          "pack_id": {
-            "description": "Knowledge ID (`kpk_` prefix).",
-            "type": "string"
+            "format": "int64"
           },
           "scope": {
-            "description": "Knowledge scope. `channel` is a legacy scope; new knowledge is `account` or `team` scope.",
+            "type": "string",
+            "description": "Knowledge scope.\n- `account`: account-level knowledge shared by the whole account; `scope_id` is the account ID.\n- `team`: knowledge owned by one team; `scope_id` is the team ID.\n- `channel`: legacy scope. It cannot be created or moved into through this API and is never returned by `POST /safari/knowledge/pack/list`; it can only appear when such knowledge is addressed directly by `pack_id`.",
             "enum": [
               "account",
               "team",
               "channel"
-            ],
-            "type": "string"
+            ]
           },
           "scope_id": {
+            "type": "integer",
             "description": "Scope owner: the account ID for `account` scope, the team ID for `team` scope.",
-            "format": "int64",
-            "type": "integer"
+            "format": "int64"
           },
           "team_name": {
-            "description": "Display name of the owning team (team scope only). Omitted when empty (account scope, or the team name could not be resolved).",
-            "type": "string"
+            "type": "string",
+            "description": "Display name of the owning team (team scope only). Omitted when empty (account scope, or the team name could not be resolved)."
+          },
+          "file_count": {
+            "type": "integer",
+            "description": "Number of files currently in the knowledge."
           },
           "total_bytes": {
-            "description": "Total size of all files in bytes.",
-            "format": "int64",
-            "type": "integer"
+            "type": "integer",
+            "description": "Total size of all files in bytes. Capped at 5 MiB per knowledge.",
+            "format": "int64"
+          },
+          "version": {
+            "type": "integer",
+            "description": "Knowledge version. Starts at 0 and increases by 1 on every file write or file deletion. Moving the knowledge to another scope does not change it."
+          },
+          "duty_version": {
+            "type": "integer",
+            "description": "The `version` at which `DUTY.md` was last written. Writing `DUTY.md` sets it to the new `version`; when `version` is greater, files were added, changed or deleted after `DUTY.md` was last updated, so `DUTY.md` may no longer index every file."
+          },
+          "created_by": {
+            "type": "integer",
+            "description": "Person ID of the member whose request created the knowledge. Account knowledge is created automatically by the first request that needs it, so this can be any member of the account.",
+            "format": "int64"
+          },
+          "created_at_ms": {
+            "type": "integer",
+            "description": "Unix timestamp in milliseconds when the knowledge was created.",
+            "format": "int64"
           },
           "updated_at_ms": {
+            "type": "integer",
             "description": "Unix timestamp in milliseconds when the knowledge was last modified.",
-            "format": "int64",
-            "type": "integer"
+            "format": "int64"
           },
-          "version": {
-            "description": "Knowledge version, incremented on every file change.",
-            "type": "integer"
+          "can_edit": {
+            "type": "boolean",
+            "description": "Whether the caller can change this knowledge and its files: for `account` scope, `true` only for the account owner and admins; for `team` scope, `true` only when the caller is a member of that team (owners and admins are not exempt)."
           }
         },
         "required": [
@@ -13264,51 +13623,50 @@
           "created_at_ms",
           "updated_at_ms",
           "can_edit"
-        ],
-        "type": "object"
+        ]
       },
       "KnowledgePackListRequest": {
+        "type": "object",
         "description": "Filter and pagination for the knowledge list.",
         "properties": {
-          "include_account": {
-            "description": "Include the account-scope knowledge; defaults to true.",
-            "type": [
-              "boolean",
-              "null"
-            ]
-          },
-          "limit": {
-            "description": "Page size.",
-            "type": "integer"
-          },
           "p": {
-            "description": "Page number, 1-based; returns all results when both `p` and `limit` are unset.",
-            "type": "integer"
+            "type": "integer",
+            "description": "Page number, 1-based. When both `p` and `limit` are omitted (or ≤ 0), all matching knowledge is returned without paging; when only `limit` is set, `p` defaults to 1."
           },
-          "query": {
-            "description": "Case-insensitive substring filter over knowledge ID, scope, scope ID/account ID, and team name.",
-            "maxLength": 128,
-            "type": "string"
+          "limit": {
+            "type": "integer",
+            "description": "Page size. Defaults to 20 when `p` is set and `limit` is omitted; no upper bound is enforced."
           },
           "scope": {
-            "description": "Restrict to one scope; `all` (default) overrides `include_account`. One of: `all` (account scope plus visible team scopes), `account` (account-level knowledge only), `team` (team-level knowledge only, can be combined with `team_ids`).",
+            "type": "string",
+            "description": "Which scopes to return:\n- `all` (default): account knowledge (unless `include_account` is `false`) plus the visible team knowledge.\n- `account`: only the account knowledge; `include_account` and `team_ids` are ignored.\n- `team`: only team knowledge, optionally narrowed by `team_ids`; `include_account` is ignored.",
             "enum": [
               "all",
               "account",
               "team"
-            ],
-            "type": "string"
+            ]
+          },
+          "query": {
+            "type": "string",
+            "description": "Case-insensitive substring filter over knowledge ID, scope, scope ID, account ID and team name. Account knowledge also matches `账户`/`账号` and team knowledge also matches `团队`. Leading and trailing spaces are ignored.",
+            "maxLength": 128
           },
           "team_ids": {
-            "description": "Restrict to these team IDs; for non-admins the list is intersected with their own teams.",
+            "type": "array",
+            "description": "Restrict team knowledge to these team IDs. IDs of teams the caller does not belong to are silently dropped — this applies to every caller, including owners and admins.",
             "items": {
-              "format": "int64",
-              "type": "integer"
-            },
-            "type": "array"
+              "type": "integer",
+              "format": "int64"
+            }
+          },
+          "include_account": {
+            "type": [
+              "boolean",
+              "null"
+            ],
+            "description": "Whether to include the account knowledge when `scope` is `all` or omitted. Defaults to `true`."
           }
-        },
-        "type": "object"
+        }
       },
       "KnowledgePackListResponse": {
         "description": "Visible knowledge and the total after filtering.",
@@ -13333,64 +13691,64 @@
         "type": "object"
       },
       "KnowledgePackUpdateRequest": {
+        "type": "object",
         "description": "Move knowledge to a different scope.",
         "properties": {
           "pack_id": {
-            "description": "Knowledge ID to update.",
-            "type": "string"
+            "type": "string",
+            "description": "Knowledge ID to update."
           },
           "scope": {
-            "description": "Destination scope; omit for a no-op that returns the current knowledge.",
-            "enum": [
-              "account",
-              "team"
-            ],
             "type": [
               "string",
               "null"
+            ],
+            "description": "Destination scope. Omit to leave the knowledge unchanged and get it back.\n- `account`: make it the account knowledge (only the account owner and admins).\n- `team`: move it to the team in `scope_id` (the caller must be a member of that team).\nAny other value returns `InvalidParameter`. If the destination already has knowledge, the request fails with `ReferenceExist`.",
+            "enum": [
+              "account",
+              "team"
             ]
           },
           "scope_id": {
-            "description": "Destination team ID; required when `scope` is `team`, set automatically for `account`.",
-            "format": "int64",
             "type": [
               "integer",
               "null"
-            ]
+            ],
+            "description": "Destination team ID. Required (non-zero) when `scope` is `team`; ignored when `scope` is `account` (the account ID is used).",
+            "format": "int64"
           }
         },
         "required": [
           "pack_id"
-        ],
-        "type": "object"
+        ]
       },
       "KnowledgeWarning": {
+        "type": "object",
         "description": "Non-blocking annotation returned by file uploads and deletions, e.g. references that point at a removed file.",
         "properties": {
           "code": {
+            "type": "string",
             "description": "Warning code. One of: `unresolved_reference` (an @ref in the written file's content points to a file that does not exist in the knowledge; `ref` carries it), `still_referenced_by` (the deleted file is still @ref-referenced by other files in the knowledge; `refs` lists the referrers).",
             "enum": [
               "unresolved_reference",
               "still_referenced_by"
-            ],
-            "type": "string"
+            ]
           },
           "ref": {
-            "description": "Single reference related to the warning.",
-            "type": "string"
+            "type": "string",
+            "description": "Set only for `unresolved_reference`: the referenced path that does not exist in the knowledge."
           },
           "refs": {
-            "description": "Multiple references related to the warning.",
+            "type": "array",
+            "description": "Set only for `still_referenced_by`: `rel_path` of every other file that still references the deleted file.",
             "items": {
               "type": "string"
-            },
-            "type": "array"
+            }
           }
         },
         "required": [
           "code"
-        ],
-        "type": "object"
+        ]
       },
       "LicenseListResponse": {
         "description": "People with active fixed or temporary On-call licenses.",
@@ -13493,171 +13851,155 @@
         "type": "object"
       },
       "ListChangeRequest": {
+        "type": "object",
         "properties": {
-          "asc": {
-            "description": "Sort in ascending order when true; default is descending.",
-            "type": "boolean"
+          "start_time": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Start of the query window, Unix seconds. Required in practice: it must be less than `end_time`, and the window can span at most 31 days. A change matches when its [start_time, last_time] range overlaps the window.",
+            "minimum": 0
           },
-          "channel_ids": {
-            "description": "Filter by channel IDs.",
-            "items": {
-              "description": "",
-              "format": "int64",
-              "type": "integer"
-            },
-            "type": "array"
+          "end_time": {
+            "type": "integer",
+            "format": "int64",
+            "description": "End of the query window, Unix seconds. Required in practice; see `start_time`.",
+            "minimum": 0
           },
-          "data_source_id": {
-            "deprecated": true,
-            "description": "Deprecated: use `integration_ids` instead. Single integration ID to filter by.",
+          "p": {
+            "type": "integer",
+            "description": "Page number, starting at 1. Defaults to 1.",
             "format": "int64",
             "minimum": 1,
-            "type": "integer"
-          },
-          "data_source_ids": {
-            "deprecated": true,
-            "description": "Deprecated: use `integration_ids` instead. At least 1 entry when provided.",
-            "items": {
-              "description": "Integration ID.",
-              "format": "int64",
-              "type": "integer"
-            },
-            "minItems": 1,
-            "type": "array"
+            "default": 1
           },
-          "end_time": {
-            "description": "End of the query window, Unix epoch seconds. See `start_time` for defaults and constraints.",
+          "limit": {
+            "type": "integer",
+            "description": "Number of items per page, 1-100. Defaults to 10.",
             "format": "int64",
-            "minimum": 0,
-            "type": "integer"
+            "minimum": 1,
+            "maximum": 100,
+            "default": 10
           },
-          "filters": {
-            "description": "Structured filters ANDed onto the query (e.g. on labels). Keys prefixed with `incident` are ignored.",
+          "channel_ids": {
+            "type": "array",
             "items": {
-              "$ref": "#/components/schemas/FilterCondition"
+              "type": "integer",
+              "description": "Channel ID.",
+              "format": "int64"
             },
-            "type": "array"
-          },
-          "include_events": {
-            "description": "Include the underlying change events for each change when true.",
-            "type": "boolean"
-          },
-          "integration_id": {
-            "deprecated": true,
-            "description": "Deprecated: use `integration_ids` instead. Single integration ID to filter by.",
-            "format": "int64",
-            "minimum": 1,
-            "type": "integer"
+            "description": "Filter by channel IDs."
           },
           "integration_ids": {
-            "description": "Filter by reporting integration IDs. At least 1 entry when provided.",
+            "type": "array",
             "items": {
-              "description": "",
-              "format": "int64",
-              "type": "integer"
+              "type": "integer",
+              "description": "Integration ID.",
+              "format": "int64"
             },
-            "minItems": 1,
-            "type": "array"
-          },
-          "limit": {
-            "default": 10,
-            "description": "Number of items per page.",
-            "format": "int64",
-            "maximum": 100,
-            "minimum": 1,
-            "type": "integer"
+            "description": "Filter by reporting integration IDs. At least 1 entry when provided.",
+            "minItems": 1
           },
           "orderby": {
+            "type": "string",
             "description": "Sort field: `start_time` or `last_time`. Defaults to `start_time`.",
             "enum": [
               "start_time",
               "last_time"
-            ],
-            "type": "string"
+            ]
           },
-          "p": {
-            "description": "Page number, starting at 1.",
-            "format": "int64",
-            "minimum": 1,
-            "type": "integer"
+          "asc": {
+            "type": "boolean",
+            "description": "Sort in ascending order when true; default is descending."
+          },
+          "include_events": {
+            "type": "boolean",
+            "description": "Include the underlying change events for each change when true."
           },
           "query": {
-            "description": "Case-insensitive substring or regular-expression match over the change title, change_key, and description. An invalid regular expression falls back to a literal match.",
-            "type": "string"
+            "type": "string",
+            "description": "Case-insensitive substring or regular-expression match over the change title, change_key, and description. An invalid regular expression falls back to a literal match."
           },
-          "start_time": {
-            "description": "Start of the query window, Unix epoch seconds. Optional — when both `start_time` and `end_time` are omitted or 0, the window defaults to the last hour. Must be less than `end_time`, with a span of at most 31 days. A change matches when its [start_time, last_time] window overlaps the query window.",
+          "filters": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/FilterCondition"
+            },
+            "description": "Structured filters ANDed onto the query (e.g. on labels). Keys prefixed with `incident` are ignored."
+          },
+          "data_source_ids": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "int64",
+              "description": "Integration ID."
+            },
+            "description": "Deprecated: use `integration_ids` instead. At least 1 entry when provided.",
+            "deprecated": true,
+            "minItems": 1
+          },
+          "data_source_id": {
+            "type": "integer",
             "format": "int64",
-            "minimum": 0,
-            "type": "integer"
+            "minimum": 1,
+            "deprecated": true,
+            "description": "Deprecated: use `integration_ids` instead. Single integration ID to filter by."
+          },
+          "integration_id": {
+            "type": "integer",
+            "format": "int64",
+            "minimum": 1,
+            "deprecated": true,
+            "description": "Deprecated: use `integration_ids` instead. Single integration ID to filter by."
           }
         },
-        "type": "object"
+        "required": [
+          "start_time",
+          "end_time"
+        ]
       },
       "ListChangeResponse": {
+        "type": "object",
         "properties": {
+          "total": {
+            "type": "integer",
+            "description": "Total number of matching changes.",
+            "format": "int64"
+          },
           "has_next_page": {
-            "description": "Whether more pages are available after this one.",
-            "type": "boolean"
+            "type": "boolean",
+            "description": "Whether more pages are available after this one."
           },
           "items": {
-            "description": "Changes on the current page.",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/ChangeItem"
             },
-            "type": "array"
-          },
-          "total": {
-            "description": "Total number of matching changes.",
-            "format": "int64",
-            "type": "integer"
+            "description": "Changes on the current page."
           }
         },
-        "type": "object"
+        "required": [
+          "total",
+          "has_next_page",
+          "items"
+        ]
       },
       "ListChannelsRequest": {
+        "type": "object",
         "properties": {
-          "asc": {
-            "description": "When true, sort ascending; defaults to false (descending).",
-            "type": "boolean"
-          },
-          "channel_ids": {
-            "description": "Filter by explicit channel IDs.",
-            "items": {
-              "format": "int64",
-              "type": "integer"
-            },
-            "type": "array"
-          },
-          "channel_name": {
-            "description": "Exact-match filter on channel name. Takes priority over `query` for name filtering. Must be valid UTF-8 — invalid byte sequences are rejected with `InvalidParameter`.",
-            "type": "string"
-          },
-          "is_brief": {
-            "description": "When true, return only `channel_id`, `channel_name`, `description` and `status`, and return all matches without pagination.",
-            "type": "boolean"
-          },
-          "is_my_managed": {
-            "description": "When true, return only channels the caller manages.",
-            "type": "boolean"
-          },
-          "is_my_starred": {
-            "description": "When true, return only channels the caller has starred. Mutually exclusive with `is_my_team`.",
-            "type": "boolean"
-          },
-          "is_my_team": {
-            "description": "When true, return channels owned by the caller's teams. Mutually exclusive with `is_my_starred`.",
-            "type": "boolean"
+          "p": {
+            "type": "integer",
+            "minimum": 1,
+            "description": "Page number, starting at 1. Always pass it: when omitted the first page is returned but `has_next_page` is unreliable."
           },
           "limit": {
-            "default": 100,
-            "description": "Page size. Defaults to 100 when omitted.",
-            "maximum": 100,
+            "type": "integer",
             "minimum": 1,
-            "type": "integer"
+            "maximum": 100,
+            "default": 100,
+            "description": "Page size. Defaults to 100 when omitted."
           },
           "orderby": {
-            "description": "Field used to order results. Defaults to `created_at`.",
+            "type": "string",
             "enum": [
               "ranking",
               "created_at",
@@ -13665,53 +14007,79 @@
               "channel_name",
               "last_incident_at"
             ],
-            "type": "string"
+            "description": "Sort field, default `created_at`. `ranking` uses the caller's own channel order saved in the console and falls back to creation order when none is saved; `channel_name` sorts case-insensitively."
           },
-          "p": {
-            "description": "Page number (1-based).",
-            "minimum": 1,
-            "type": "integer"
+          "asc": {
+            "type": "boolean",
+            "description": "When true, sort ascending; defaults to false (descending)."
           },
-          "query": {
-            "description": "Case-insensitive regular expression matched against channel name and description; invalid regex syntax falls back to a literal match. Must be valid UTF-8 — invalid byte sequences are rejected with `InvalidParameter`.",
-            "type": "string"
+          "is_my_managed": {
+            "type": "boolean",
+            "description": "When true, return only channels owned by one of the caller's teams or created by the caller. Takes precedence over `is_my_team` and `is_my_starred`."
+          },
+          "is_my_starred": {
+            "type": "boolean",
+            "description": "When true, return only channels the caller has starred. Cannot be combined with `is_my_team`."
+          },
+          "is_brief": {
+            "type": "boolean",
+            "description": "When true, return only `channel_id`, `channel_name`, `description`, `status` and `is_starred` for each channel, with all matches in one page."
+          },
+          "is_my_team": {
+            "type": "boolean",
+            "description": "When true, return only channels whose owning team is one of the caller's teams. Cannot be combined with `is_my_starred`."
           },
           "team_ids": {
-            "description": "Filter by team IDs.",
+            "type": "array",
             "items": {
-              "format": "int64",
-              "type": "integer"
+              "type": "integer",
+              "format": "int64"
             },
-            "type": "array"
+            "description": "Return only channels owned by these teams. Ignored when `is_my_managed` or `is_my_team` is true."
+          },
+          "query": {
+            "type": "string",
+            "description": "Case-insensitive regular expression matched against channel name and description; invalid regex syntax falls back to a literal match. Must be valid UTF-8 — invalid byte sequences are rejected with `InvalidParameter`."
+          },
+          "channel_ids": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "int64"
+            },
+            "description": "Filter by explicit channel IDs."
+          },
+          "channel_name": {
+            "type": "string",
+            "description": "Exact-match filter on channel name. Takes priority over `query` for name filtering. Must be valid UTF-8 — invalid byte sequences are rejected with `InvalidParameter`."
           }
-        },
-        "type": "object"
+        }
       },
       "ListChannelsResponse": {
+        "type": "object",
+        "required": [
+          "items",
+          "total",
+          "has_next_page"
+        ],
         "properties": {
-          "has_next_page": {
-            "description": "Whether more pages are available.",
-            "type": "boolean"
-          },
           "items": {
-            "description": "Channels on the current page.",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/ChannelItem"
             },
-            "type": "array"
+            "description": "Channels on the current page."
           },
           "total": {
-            "description": "Total matching channels.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Total number of matching channels across all pages."
+          },
+          "has_next_page": {
+            "type": "boolean",
+            "description": "Whether more pages follow. Reliable only when `p` is passed."
           }
-        },
-        "required": [
-          "items",
-          "total",
-          "has_next_page"
-        ],
-        "type": "object"
+        }
       },
       "ListDropRulesResponse": {
         "properties": {
@@ -13729,19 +14097,19 @@
         "type": "object"
       },
       "ListEscalationRulesResponse": {
+        "type": "object",
+        "required": [
+          "items"
+        ],
         "properties": {
           "items": {
-            "description": "All escalation rules of the channel, excluding deleted ones, ordered by priority ascending.",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/EscalateRuleItem"
             },
-            "type": "array"
+            "description": "Escalation rules of the channel, excluding deleted ones, in evaluation order: ascending `priority`, then creation time."
           }
-        },
-        "required": [
-          "items"
-        ],
-        "type": "object"
+        }
       },
       "ListIncidentAlertsRequest": {
         "description": "Filters for alerts belonging to an incident.",
@@ -13784,26 +14152,26 @@
         "type": "object"
       },
       "ListIncidentAlertsResponse": {
+        "type": "object",
         "description": "Paginated list of alerts merged into an incident.",
+        "required": [
+          "items",
+          "total"
+        ],
         "properties": {
           "items": {
-            "description": "Alert list.",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/AlertInfo"
             },
-            "type": "array"
+            "description": "Alerts on the requested page; an empty array when no alert matches."
           },
           "total": {
-            "description": "Total matching alerts.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Total matching alerts."
           }
-        },
-        "required": [
-          "items",
-          "total"
-        ],
-        "type": "object"
+        }
       },
       "ListIncidentCommentTypesRequest": {
         "description": "No parameters. The operation always returns every comment type of the calling account.",
@@ -13811,56 +14179,60 @@
         "type": "object"
       },
       "ListIncidentCommentTypesResponse": {
+        "type": "object",
         "description": "Full list of the account's comment types, ordered by position.",
         "properties": {
           "items": {
-            "description": "All comment types of the account, ordered by position.",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/IncidentCommentTypeItem"
             },
-            "type": "array"
+            "description": "All comment types of the account, ordered by position."
           }
         },
-        "type": "object"
+        "required": [
+          "items"
+        ]
       },
       "ListIncidentFeedRequest": {
+        "type": "object",
         "description": "Filters for the incident timeline query.",
+        "required": [
+          "incident_id"
+        ],
         "properties": {
-          "asc": {
-            "description": "Ascending chronological order when true.",
-            "type": "boolean"
-          },
           "incident_id": {
-            "description": "Incident ID (MongoDB ObjectID).",
+            "type": "string",
             "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
+            "description": "Incident ID (MongoDB ObjectID)."
           },
-          "limit": {
-            "default": 20,
-            "description": "Page size, at most 100.",
+          "p": {
+            "type": "integer",
             "format": "int64",
-            "maximum": 100,
             "minimum": 1,
-            "type": "integer"
-          },
-          "p": {
             "description": "Page number starting at 1.",
+            "default": 1
+          },
+          "limit": {
+            "type": "integer",
             "format": "int64",
             "minimum": 1,
-            "type": "integer"
+            "maximum": 100,
+            "default": 20,
+            "description": "Page size, at most 100."
+          },
+          "asc": {
+            "type": "boolean",
+            "description": "Ascending chronological order when true."
           },
           "types": {
-            "description": "Optional filter restricting the returned entries to specific types.",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/IncidentFeedType"
             },
-            "type": "array"
+            "description": "Return only entries of these types; omit to return all types."
           }
-        },
-        "required": [
-          "incident_id"
-        ],
-        "type": "object"
+        }
       },
       "ListIncidentFeedResponse": {
         "description": "Page of incident timeline entries.",
@@ -13901,140 +14273,144 @@
         "type": "object"
       },
       "ListIncidentsRequest": {
+        "type": "object",
         "description": "Filters for the incident list query. `start_time` and `end_time` are required; the window must not exceed 31 days.",
+        "required": [
+          "start_time",
+          "end_time"
+        ],
         "properties": {
-          "acker_ids": {
-            "description": "Filter by acker member IDs; obtain member IDs from `POST /member/list`.",
-            "items": {
-              "format": "int64",
-              "type": "integer"
-            },
-            "type": "array"
+          "start_time": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Start of the time window (Unix timestamp in seconds). The window with `end_time` may span at most 31 days and filters by incident start time."
+          },
+          "end_time": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Window end, Unix seconds. Must be greater than `start_time` and within 31 days."
           },
           "asc": {
-            "description": "Ascending order when true.",
-            "type": "boolean"
+            "type": "boolean",
+            "description": "Ascending order when true."
           },
-          "channel_ids": {
-            "description": "Channel IDs to filter by. Use 0 for standalone (global) incidents.",
-            "items": {
-              "format": "int64",
-              "type": "integer"
-            },
-            "type": "array"
+          "is_snoozed": {
+            "type": "boolean",
+            "description": "When true, include only snoozed incidents."
           },
-          "closer_ids": {
-            "description": "Closer member IDs. Use 0 for automatically closed incidents.",
-            "items": {
-              "format": "int64",
-              "type": "integer"
-            },
-            "type": "array"
+          "is_my_team": {
+            "type": "boolean",
+            "description": "When true, restrict to incidents in channels owned by the user's teams."
           },
-          "creator_ids": {
-            "description": "Creator member IDs. Use 0 for automatically created incidents.",
-            "items": {
-              "format": "int64",
-              "type": "integer"
-            },
-            "type": "array"
-          },
-          "end_time": {
-            "description": "Window end, Unix seconds. Must be greater than `start_time` and within 31 days.",
-            "format": "int64",
-            "type": "integer"
+          "is_my_channel": {
+            "type": "boolean",
+            "description": "When true, restrict to incidents in channels the user personally owns."
           },
           "ever_muted": {
-            "description": "When true, include only incidents that were ever silenced.",
-            "type": "boolean"
+            "type": "boolean",
+            "description": "When true, include only incidents that were ever silenced."
           },
-          "incident_ids": {
-            "description": "Restrict to the given incident IDs.",
+          "is_rare": {
+            "type": "boolean",
+            "description": "When true, include only outlier (rare) incidents."
+          },
+          "has_unfinished_work_item": {
+            "type": "boolean",
+            "description": "When true, include only incidents that still have an action item or follow-up that is neither `done` nor `cancelled`. `false` applies no filter."
+          },
+          "progress": {
+            "type": "string",
+            "description": "Comma-separated progress states to match, for example `Triggered,Processing`. Values: `Triggered` not yet acknowledged; `Processing` acknowledged and being handled; `Closed` resolved. Omit to match every state."
+          },
+          "query": {
+            "type": "string",
+            "description": "Full-text search query."
+          },
+          "incident_severity": {
+            "type": "string",
+            "description": "Comma-separated severities to match, for example `Critical,Warning`. Values: `Critical` most severe, `Warning`, `Info` least severe."
+          },
+          "channel_ids": {
+            "type": "array",
             "items": {
-              "type": "string"
+              "type": "integer",
+              "format": "int64"
             },
-            "type": "array"
+            "description": "Channel IDs to filter by. Use 0 for standalone (global) incidents."
           },
-          "incident_severity": {
-            "description": "Comma-separated list of severities (`Critical,Warning,Info`).",
-            "type": "string"
+          "team_ids": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "int64"
+            },
+            "description": "Team IDs; resolved to channels via channel ownership."
           },
-          "is_my_channel": {
-            "description": "When true, restrict to incidents in channels the user personally owns.",
-            "type": "boolean"
+          "responder_ids": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "int64"
+            },
+            "description": "Filter by responder member IDs; obtain member IDs from `POST /member/list`."
           },
-          "is_my_team": {
-            "description": "When true, restrict to incidents in channels owned by the user's teams.",
-            "type": "boolean"
+          "acker_ids": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "int64"
+            },
+            "description": "Filter by acker member IDs; obtain member IDs from `POST /member/list`."
           },
-          "is_rare": {
-            "description": "When true, include only outlier (rare) incidents.",
-            "type": "boolean"
+          "creator_ids": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "int64"
+            },
+            "description": "Creator member IDs. Use 0 for automatically created incidents."
           },
-          "is_snoozed": {
-            "description": "When true, include only snoozed incidents.",
-            "type": "boolean"
+          "closer_ids": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "int64"
+            },
+            "description": "Closer member IDs. Use 0 for automatically closed incidents."
           },
-          "limit": {
-            "default": 20,
-            "description": "Page size, at most 100.",
-            "format": "int64",
-            "maximum": 100,
-            "minimum": 0,
-            "type": "integer"
+          "incident_ids": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Restrict to the given incident IDs."
           },
           "nums": {
-            "description": "Filter by incident short numbers (the numbers shown before incident titles in the console).",
+            "type": "array",
             "items": {
               "type": "string"
             },
-            "type": "array"
+            "description": "Filter by incident short numbers (the numbers shown before incident titles in the console)."
           },
           "p": {
-            "description": "Page number starting at 1.",
+            "type": "integer",
             "format": "int64",
             "minimum": 0,
-            "type": "integer"
-          },
-          "progress": {
-            "description": "Comma-separated list of progress states to match (e.g. `Triggered,Processing`).",
-            "type": "string"
-          },
-          "query": {
-            "description": "Full-text search query.",
-            "type": "string"
-          },
-          "responder_ids": {
-            "description": "Filter by responder member IDs; obtain member IDs from `POST /member/list`.",
-            "items": {
-              "format": "int64",
-              "type": "integer"
-            },
-            "type": "array"
-          },
-          "search_after_ctx": {
-            "description": "Cursor from a previous response for forward pagination.",
-            "type": "string"
+            "description": "Page number starting at 1."
           },
-          "start_time": {
-            "description": "Start of the time window (Unix timestamp in seconds). The window with `end_time` may span at most 31 days and filters by incident start time.",
+          "limit": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "minimum": 0,
+            "maximum": 100,
+            "default": 20,
+            "description": "Page size, at most 100."
           },
-          "team_ids": {
-            "description": "Team IDs; resolved to channels via channel ownership.",
-            "items": {
-              "format": "int64",
-              "type": "integer"
-            },
-            "type": "array"
+          "search_after_ctx": {
+            "type": "string",
+            "description": "Cursor from the previous response's `search_after_ctx`; when set, `p` is ignored."
           }
-        },
-        "required": [
-          "start_time",
-          "end_time"
-        ],
-        "type": "object"
+        }
       },
       "ListInhibitRulesResponse": {
         "properties": {
@@ -14093,142 +14469,139 @@
         "type": "object"
       },
       "ListPostMortemTemplatesRequest": {
+        "type": "object",
         "description": "Pagination and ordering options for post-mortem templates.",
         "properties": {
-          "asc": {
-            "description": "Ascending order when true.",
-            "type": "boolean"
-          },
-          "limit": {
-            "default": 20,
-            "description": "Page size, at most 100.",
-            "format": "int64",
-            "maximum": 100,
-            "minimum": 0,
-            "type": "integer"
-          },
           "order_by": {
-            "description": "Field used to order results.",
+            "type": "string",
             "enum": [
               "created_at_seconds"
             ],
-            "type": "string"
+            "description": "Sort field for custom templates. Only `created_at_seconds` is supported, which is also the default."
+          },
+          "asc": {
+            "type": "boolean",
+            "description": "Sort custom templates in ascending order when true; default false (newest first)."
           },
           "p": {
-            "description": "Page number starting at 1.",
+            "type": "integer",
             "format": "int64",
             "minimum": 0,
-            "type": "integer"
+            "description": "Page number starting at 1; 0 or omitted means 1."
+          },
+          "limit": {
+            "type": "integer",
+            "format": "int64",
+            "minimum": 0,
+            "maximum": 100,
+            "default": 20,
+            "description": "Page size, 1–100; 0 or omitted means 20."
           },
           "search_after_ctx": {
-            "description": "Cursor from a previous response for forward pagination.",
-            "type": "string"
+            "type": "string",
+            "description": "Not supported by this operation; leave it unset and paginate with `p`. If sent, it must be an integer string, and `p` is then ignored (results start from the first page)."
           }
-        },
-        "type": "object"
+        }
       },
       "ListPostMortemTemplatesResponse": {
+        "type": "object",
         "description": "Paginated list of post-mortem templates.",
+        "required": [
+          "items",
+          "total",
+          "has_next_page"
+        ],
         "properties": {
-          "has_next_page": {
-            "description": "True when another page is available.",
-            "type": "boolean"
-          },
           "items": {
-            "description": "Templates in the current page.",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/PostMortemTemplate"
             },
-            "type": "array"
-          },
-          "search_after_ctx": {
-            "description": "Cursor for forward pagination.",
-            "type": "string"
+            "description": "Templates on this page; the built-in template is first on page 1."
           },
           "total": {
-            "description": "Total matching templates.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Total number of templates, including the built-in one."
+          },
+          "has_next_page": {
+            "type": "boolean",
+            "description": "True when another page is available."
           }
-        },
-        "required": [
-          "items",
-          "total",
-          "has_next_page"
-        ],
-        "type": "object"
+        }
       },
       "ListPostMortemsRequest": {
+        "type": "object",
         "description": "Filters for the post-mortem report list.",
         "properties": {
-          "asc": {
-            "description": "Ascending order when true.",
-            "type": "boolean"
+          "status": {
+            "type": "string",
+            "enum": [
+              "drafting",
+              "published"
+            ],
+            "description": "Optional status filter: `drafting` returns only drafts, `published` returns only published post-mortems. When omitted, post-mortems in all statuses are returned."
           },
-          "channel_ids": {
-            "description": "Channel IDs to restrict the query to.",
+          "team_ids": {
+            "type": "array",
             "items": {
-              "format": "int64",
-              "type": "integer"
+              "type": "integer",
+              "format": "int64"
             },
-            "type": "array"
+            "description": "Team IDs to restrict the query to."
           },
-          "created_at_end_seconds": {
-            "description": "Upper bound of post-mortem creation time (Unix timestamp in seconds).",
-            "format": "int64",
-            "minimum": 0,
-            "type": "integer"
+          "channel_ids": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "int64"
+            },
+            "description": "Channel IDs to restrict the query to."
           },
           "created_at_start_seconds": {
-            "description": "Lower bound of post-mortem creation time (Unix timestamp in seconds).",
+            "type": "integer",
             "format": "int64",
             "minimum": 0,
-            "type": "integer"
+            "description": "Lower bound of post-mortem creation time (Unix timestamp in seconds)."
           },
-          "limit": {
-            "default": 20,
-            "description": "Page size, at most 100.",
+          "created_at_end_seconds": {
+            "type": "integer",
             "format": "int64",
-            "maximum": 100,
             "minimum": 0,
-            "type": "integer"
+            "description": "Upper bound of post-mortem creation time (Unix timestamp in seconds)."
           },
           "order_by": {
-            "description": "Field used to order results.",
+            "type": "string",
             "enum": [
               "created_at_seconds",
               "updated_at_seconds"
             ],
-            "type": "string"
+            "description": "Sort field: `created_at_seconds` creation time, `updated_at_seconds` last update time.",
+            "default": "created_at_seconds"
+          },
+          "asc": {
+            "type": "boolean",
+            "description": "Ascending order when true."
           },
           "p": {
-            "description": "Page number starting at 1.",
+            "type": "integer",
             "format": "int64",
             "minimum": 0,
-            "type": "integer"
+            "description": "Page number starting at 1."
           },
-          "search_after_ctx": {
-            "description": "Cursor from a previous response for forward pagination.",
-            "type": "string"
-          },
-          "status": {
-            "description": "Optional status filter: `drafting` returns only drafts, `published` returns only published post-mortems. When omitted, post-mortems in all statuses are returned.",
-            "enum": [
-              "drafting",
-              "published"
-            ],
-            "type": "string"
+          "limit": {
+            "type": "integer",
+            "format": "int64",
+            "minimum": 0,
+            "maximum": 100,
+            "default": 20,
+            "description": "Page size, at most 100."
           },
-          "team_ids": {
-            "description": "Team IDs to restrict the query to.",
-            "items": {
-              "format": "int64",
-              "type": "integer"
-            },
-            "type": "array"
+          "search_after_ctx": {
+            "type": "string",
+            "description": "Cursor from a previous response for forward pagination."
           }
-        },
-        "type": "object"
+        }
       },
       "ListPostMortemsResponse": {
         "description": "Paginated list of post-mortem reports.",
@@ -14265,7 +14638,7 @@
         "description": "Remote configuration history request. Newest first by default.",
         "properties": {
           "application_id": {
-            "description": "RUM application ID.",
+            "description": "RUM application ID. Get application IDs via `POST /rum/application/list`.",
             "type": "string"
           },
           "asc": {
@@ -14274,13 +14647,12 @@
           },
           "limit": {
             "default": 20,
-            "description": "Page size. Default 20, max 100.",
-            "maximum": 100,
+            "description": "Page size. `0` or a negative value means 20; values above 100 are treated as 100.",
             "type": "integer"
           },
           "orderby": {
             "default": "updated_at",
-            "description": "Sort field. Default: `updated_at`.",
+            "description": "Sort field:\n\n- `updated_at`: publish time (default).\n- `version`: version number.\n\nAny other value falls back to `updated_at`.",
             "enum": [
               "updated_at",
               "version"
@@ -14304,40 +14676,45 @@
         "description": "Remote configuration history page.",
         "properties": {
           "has_next_page": {
-            "description": "Whether more pages remain.",
+            "description": "`true` when more versions remain after this page.",
             "type": "boolean"
           },
           "items": {
-            "description": "Version items, newest first by default.",
+            "description": "Versions on this page, newest first by default. Empty array when the application has never been configured.",
             "items": {
               "$ref": "#/components/schemas/RemoteConfigHistoryItem"
             },
             "type": "array"
           },
           "total": {
-            "description": "Total number of versions.",
+            "description": "Number of retained versions (at most 50).",
             "type": "integer"
           }
         },
-        "type": "object"
+        "type": "object",
+        "required": [
+          "total",
+          "has_next_page",
+          "items"
+        ]
       },
       "ListRoutesRequest": {
+        "type": "object",
         "description": "Parameters for listing routing rules across multiple integrations.",
+        "required": [
+          "integration_ids"
+        ],
         "properties": {
           "integration_ids": {
-            "description": "Integration IDs to fetch routing rules for.",
+            "type": "array",
             "items": {
-              "format": "int64",
-              "type": "integer"
+              "type": "integer",
+              "format": "int64"
             },
-            "minItems": 1,
-            "type": "array"
+            "description": "Shared integration IDs to fetch routing rules for, at least one; obtain them from `POST /integration/list`.",
+            "minItems": 1
           }
-        },
-        "required": [
-          "integration_ids"
-        ],
-        "type": "object"
+        }
       },
       "ListRoutesResponse": {
         "description": "Response wrapper for the routing rule list.",
@@ -14460,111 +14837,129 @@
         "type": "object"
       },
       "ListWebhookHistoryRequest": {
+        "type": "object",
         "description": "Filter parameters for listing outbound webhook delivery history. The query is bounded by a required millisecond time window; use `search_after_ctx` for cursor-based pagination.",
+        "required": [
+          "limit",
+          "start_time",
+          "end_time"
+        ],
         "properties": {
-          "asc": {
-            "description": "Ascending order by `event_time` when true; otherwise descending.",
-            "type": "boolean"
-          },
-          "end_time": {
-            "description": "Window end time in Unix milliseconds. Must be greater than `start_time`.",
-            "format": "int64",
-            "maximum": 9999999999999,
-            "minimum": 1000000000000,
-            "type": "integer"
-          },
-          "event_types": {
-            "description": "Filter by event type codes (e.g. `i_new` incident created, `a_new` alert triggered).",
-            "items": {
-              "type": "string"
-            },
-            "type": "array"
-          },
-          "integration_id": {
-            "description": "Filter by webhook integration ID.",
-            "format": "int64",
-            "minimum": 0,
-            "type": "integer"
+          "search_after_ctx": {
+            "type": "string",
+            "description": "Opaque cursor returned by a previous call for fetching the next page."
           },
           "limit": {
-            "description": "Page size.",
-            "maximum": 100,
+            "type": "integer",
             "minimum": 1,
-            "type": "integer"
+            "maximum": 100,
+            "description": "Number of records per page, 1–100."
+          },
+          "asc": {
+            "type": "boolean",
+            "description": "Ascending order by `event_time` when true; otherwise descending."
           },
           "orderby": {
-            "description": "Sort field. Currently only `event_time` is supported.",
+            "type": "string",
             "enum": [
               "event_time"
             ],
-            "type": "string"
+            "description": "Sort field. Currently only `event_time` is supported."
           },
           "ref_id": {
-            "description": "Reference ID filter (incident or alert ID).",
+            "type": "string",
             "maxLength": 128,
-            "type": "string"
-          },
-          "search_after_ctx": {
-            "description": "Opaque cursor returned by a previous call for fetching the next page.",
-            "type": "string"
+            "description": "Reference ID filter (incident or alert ID)."
           },
-          "start_time": {
-            "description": "Window start time in Unix milliseconds.",
+          "integration_id": {
+            "type": "integer",
             "format": "int64",
-            "maximum": 9999999999999,
-            "minimum": 1000000000000,
-            "type": "integer"
+            "minimum": 0,
+            "description": "Filter by webhook integration ID; `0` or omitted returns all integrations."
+          },
+          "event_types": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Filter by event type codes (e.g. `i_new` incident created, `a_new` alert triggered)."
           },
           "status": {
-            "description": "Filter by delivery status: `success` or `failed`.",
+            "type": "string",
             "enum": [
               "success",
               "failed"
             ],
-            "type": "string"
+            "description": "Filter by delivery status: `success` or `failed`."
+          },
+          "start_time": {
+            "type": "integer",
+            "format": "int64",
+            "minimum": 1000000000000,
+            "maximum": 9999999999999,
+            "description": "Window start time in Unix milliseconds."
+          },
+          "end_time": {
+            "type": "integer",
+            "format": "int64",
+            "minimum": 1000000000000,
+            "maximum": 9999999999999,
+            "description": "Window end time in Unix milliseconds. Must be greater than `start_time`."
           }
-        },
-        "required": [
-          "limit",
-          "start_time",
-          "end_time"
-        ],
-        "type": "object"
+        }
       },
       "ListWebhookHistoryResponse": {
+        "type": "object",
         "description": "Paginated webhook delivery history.",
+        "required": [
+          "items",
+          "total",
+          "search_after_ctx"
+        ],
         "properties": {
           "items": {
-            "description": "Webhook delivery records on the current page.",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/WebhookHistoryItem"
             },
-            "type": "array"
-          },
-          "search_after_ctx": {
-            "description": "Cursor to pass as `search_after_ctx` to fetch the next page. Empty when no further pages are available.",
-            "type": "string"
+            "description": "Webhook delivery records on the current page."
           },
           "total": {
-            "description": "Total number of matching records.",
-            "format": "int64",
-            "type": "integer"
+            "type": "integer",
+            "description": "Total number of records matching the filters, not capped.",
+            "format": "int64"
+          },
+          "search_after_ctx": {
+            "type": "string",
+            "description": "Cursor to pass as `search_after_ctx` to fetch the next page. Empty when no further pages are available."
           }
-        },
-        "required": [
-          "items",
-          "total",
-          "search_after_ctx"
-        ],
-        "type": "object"
+        }
       },
       "ListWorkItemRequest": {
+        "type": "object",
         "description": "Filters for listing work items. At least one of `incident_id`, `post_mortem_id`, `assignee_id`, or `assignee_type` = `ai_sre` is required.",
         "properties": {
+          "incident_id": {
+            "type": "string",
+            "pattern": "^[0-9a-fA-F]{24}$",
+            "description": "Incident ID (MongoDB ObjectID). Also returns follow-ups anchored on the incident's post-mortem."
+          },
+          "post_mortem_id": {
+            "type": "string",
+            "description": "Post-mortem ID (32-character hex string). Returns follow-ups bound to this post-mortem."
+          },
+          "item_type": {
+            "type": "string",
+            "enum": [
+              "action",
+              "follow_up"
+            ],
+            "description": "Filter by work item type: `action` action item, `follow_up` post-mortem follow-up."
+          },
           "assignee_id": {
-            "description": "Restrict results to items assigned to this member ID. Listing by assignee alone requires being that assignee or an account admin. Ignored when `assignee_type` is `ai_sre`.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Restrict results to items assigned to this member ID. Listing by assignee alone requires being that member or an account owner or admin. Ignored when `assignee_type` is `ai_sre`."
           },
           "assignee_type": {
             "description": "Filter by assignee type: `person` or `ai_sre`. `ai_sre` returns items assigned to AI SRE (an AI caller uses this to list its own tasks) and does not require `assignee_id`. `person` together with `assignee_id` restricts results to that member. Omitted with a positive `assignee_id` means `person`.",
@@ -14575,150 +14970,136 @@
             "type": "string"
           },
           "cursor": {
-            "description": "Pagination cursor from a previous response's `next_cursor`.",
-            "type": "string"
-          },
-          "incident_id": {
-            "description": "Incident ID (MongoDB ObjectID). Also returns follow-ups anchored on the incident's post-mortem.",
-            "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
-          },
-          "item_type": {
-            "description": "Filter by work item type: `action` action item, `follow_up` post-mortem follow-up.",
-            "enum": [
-              "action",
-              "follow_up"
-            ],
-            "type": "string"
+            "type": "string",
+            "description": "Opaque cursor from a previous response's `next_cursor`. An invalid cursor returns `InvalidParameter`."
           },
           "limit": {
-            "default": 50,
-            "description": "Page size, at most 200. Defaults to 50.",
+            "type": "integer",
             "format": "int64",
-            "maximum": 200,
-            "minimum": 0,
-            "type": "integer"
-          },
-          "post_mortem_id": {
-            "description": "Post-mortem ID (32-character hex string). Returns follow-ups bound to this post-mortem.",
-            "type": "string"
+            "default": 50,
+            "description": "Page size. 0, negative or omitted means 50; values above 200 are treated as 200."
           }
-        },
-        "type": "object"
+        }
       },
       "MCPServerCreateRequest": {
+        "type": "object",
         "description": "Configuration for a new MCP server.",
         "properties": {
-          "allow_insecure_oauth_http": {
-            "description": "Allow this server's OAuth token exchange over plaintext HTTP. Testing use only; defaults to false.",
-            "type": "boolean"
+          "server_name": {
+            "type": "string",
+            "description": "MCP server name: must start with a letter and contain only letters, digits, `-`, or `_` (`@` is reserved); unique within its scope (account-wide or one team).",
+            "minLength": 1,
+            "maxLength": 255
           },
-          "allow_insecure_tls_skip_verify": {
-            "description": "Skip TLS certificate verification when connecting to this server. Testing use only; defaults to false.",
-            "type": "boolean"
+          "description": {
+            "type": "string",
+            "description": "Server description.",
+            "minLength": 1,
+            "maxLength": 1024
+          },
+          "transport": {
+            "type": "string",
+            "description": "Transport protocol: `stdio` launches a local process via `command`/`args`/`env`, `sse` / `streamable-http` connects to a remote service via `url`/`headers`.",
+            "enum": [
+              "stdio",
+              "sse",
+              "streamable-http"
+            ]
+          },
+          "command": {
+            "type": "string",
+            "description": "Executable command (stdio transport)."
           },
           "args": {
-            "description": "Command arguments (stdio transport).",
+            "type": "array",
             "items": {
               "type": "string"
             },
-            "type": "array"
-          },
-          "auth_mode": {
-            "description": "Authentication mode: shared (default), per_user_secret, or per_user_oauth.",
-            "type": "string"
-          },
-          "call_timeout": {
-            "description": "Tool-call timeout in seconds. 0 = default (60s).",
-            "type": "integer"
-          },
-          "command": {
-            "description": "Executable command (stdio transport).",
-            "type": "string"
-          },
-          "connect_timeout": {
-            "description": "Connection timeout in seconds. 0 = default (10s).",
-            "type": "integer"
-          },
-          "description": {
-            "description": "Server description.",
-            "maxLength": 1024,
-            "minLength": 1,
-            "type": "string"
+            "description": "Command arguments (stdio transport)."
           },
           "env": {
+            "type": "object",
             "additionalProperties": {
               "type": "string"
             },
-            "description": "Environment variables (stdio transport).",
-            "type": "object"
+            "description": "Environment variables (`stdio` transport). Values under credential-looking names (containing `KEY`, `SECRET`, `TOKEN`, `PASSWORD`, …) are encrypted at rest and masked in responses."
           },
-          "environments": {
-            "description": "Execution environments this server is callable from: `cloud` and/or BYOC runner environment IDs. Omitted or empty means all environments.",
-            "items": {
-              "type": "string"
-            },
-            "type": "array"
+          "url": {
+            "type": "string",
+            "description": "Server URL (sse / streamable-http transport)."
           },
           "headers": {
+            "type": "object",
             "additionalProperties": {
               "type": "string"
             },
-            "description": "HTTP headers (sse / streamable-http).",
-            "type": "object"
+            "description": "HTTP headers (`sse` / `streamable-http` transport). Values under credential-looking names (containing `KEY`, `TOKEN`, `AUTHORIZATION`, …) are encrypted at rest and masked in responses."
           },
-          "oauth_metadata": {
-            "description": "JSON OAuth metadata; reserved for per_user_oauth.",
-            "type": "string"
+          "connect_timeout": {
+            "type": "integer",
+            "description": "Connection timeout in seconds. Omitted or `0` is stored as `0` and means the 10-second default."
           },
-          "secret_schema": {
-            "description": "JSON secret schema; required when auth_mode=per_user_secret.",
-            "type": "string"
+          "call_timeout": {
+            "type": "integer",
+            "description": "Tool-call timeout in seconds. Omitted or `0` is stored as `0` and means the 60-second default."
           },
-          "server_name": {
-            "description": "MCP server name: must start with a letter and contain only letters, digits, `-`, or `_` (`@` is reserved); unique within its scope (account-wide or one team), case-insensitive.",
-            "maxLength": 255,
-            "minLength": 1,
-            "type": "string"
+          "auth_mode": {
+            "type": "string",
+            "description": "Who supplies the credential:\n- `shared` (default; an empty value behaves the same): one credential stored on the server (`env` / `headers`) is used for every caller.\n- `per_user_secret`: each user stores their own secret, sent in the header named by `secret_schema.header_name`.\n- `per_user_oauth`: each user completes their own OAuth authorization; discovery and client registration run on first use.\n\n`per_user_secret` requires `secret_schema` with a non-empty `header_name`; any other value returns `InvalidParameter`.",
+            "enum": [
+              "shared",
+              "per_user_secret",
+              "per_user_oauth"
+            ],
+            "default": "shared"
           },
-          "source_template_name": {
-            "description": "Marketplace template name when created from a connector template.",
-            "type": "string"
+          "secret_schema": {
+            "type": "string",
+            "description": "JSON secret schema; required when auth_mode=per_user_secret."
+          },
+          "oauth_metadata": {
+            "type": "string",
+            "description": "JSON OAuth metadata; reserved for per_user_oauth."
           },
           "status": {
-            "default": "enabled",
+            "type": "string",
             "description": "Initial status: `enabled` (default) or `disabled` (created but kept off).",
             "enum": [
               "enabled",
               "disabled"
             ],
-            "type": "string"
+            "default": "enabled"
           },
           "team_id": {
-            "description": "Team scope: 0 = account-wide; >0 = team.",
-            "format": "int64",
-            "type": "integer"
-          },
-          "transport": {
-            "description": "Transport protocol: `stdio` launches a local process via `command`/`args`/`env`, `sse` / `streamable-http` connects to a remote service via `url`/`headers`.",
-            "enum": [
-              "stdio",
-              "sse",
-              "streamable-http"
-            ],
-            "type": "string"
+            "type": "integer",
+            "description": "Team scope: `0` = account-wide (account owner or admin only); `>0` = a team the caller belongs to. Ignored when `source_template_name` is set — marketplace installs are always account-wide.",
+            "format": "int64"
           },
-          "url": {
-            "description": "Server URL (sse / streamable-http transport).",
-            "type": "string"
+          "environments": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Execution environments this server is callable from: `cloud` and/or BYOC runner environment IDs. Omitted or empty means all environments."
+          },
+          "allow_insecure_oauth_http": {
+            "type": "boolean",
+            "description": "Allow this server's OAuth token exchange over plaintext HTTP. Testing use only; defaults to false."
+          },
+          "allow_insecure_tls_skip_verify": {
+            "type": "boolean",
+            "description": "Skip TLS certificate verification when connecting to this server. Testing use only; defaults to false."
+          },
+          "source_template_name": {
+            "type": "string",
+            "description": "Name of the marketplace template to install. When set, the template must exist, the server is created at account scope, and the connection fields must match the template except for its declared parameter values. Cannot be changed later."
           }
         },
         "required": [
           "server_name",
           "description",
           "transport"
-        ],
-        "type": "object"
+        ]
       },
       "MCPServerDeleteRequest": {
         "description": "MCP server deletion by ID.",
@@ -14747,146 +15128,156 @@
         "type": "object"
       },
       "MCPServerItem": {
+        "type": "object",
         "description": "An MCP server (connector) registered on the account.",
         "properties": {
+          "server_id": {
+            "type": "string",
+            "description": "Unique MCP server ID (prefix `mcp_`)."
+          },
           "account_id": {
+            "type": "integer",
             "description": "Owning account ID.",
-            "format": "int64",
-            "type": "integer"
-          },
-          "ai_description": {
-            "description": "LLM-generated description, preferred over `description` when present. Omitted when not yet generated.",
-            "type": "string"
+            "format": "int64"
           },
-          "allow_insecure_oauth_http": {
-            "description": "Allow this server's OAuth token exchange over plaintext HTTP; testing use only. Omitted when false.",
-            "type": "boolean"
+          "team_id": {
+            "type": "integer",
+            "description": "Team scope: 0 = account-wide; >0 = the owning team.",
+            "format": "int64"
           },
-          "allow_insecure_tls_skip_verify": {
-            "description": "Skip TLS certificate verification when connecting to this server; testing use only. Omitted when false.",
-            "type": "boolean"
+          "can_edit": {
+            "type": "boolean",
+            "description": "Whether the caller may update, enable, disable, or delete this server: `true` for an account-scoped server only for the account owner or an admin, for a team server only for members of that team. Create and update responses always return `true`."
           },
-          "args": {
-            "description": "Command arguments (stdio transport).",
+          "environments": {
+            "type": "array",
             "items": {
               "type": "string"
             },
-            "type": "array"
-          },
-          "auth_mode": {
-            "description": "Authentication mode. One of: `shared` (a single static credential saved on the resource and shared by all callers in the account; the default — an empty value behaves the same), `per_user_secret` (each user stores their own secret per `secret_schema`, injected per user at runtime), `per_user_oauth` (each user completes their own OAuth grant; discovery and registration run lazily on first use).",
-            "enum": [
-              "shared",
-              "per_user_secret",
-              "per_user_oauth"
-            ],
-            "type": "string"
-          },
-          "call_timeout": {
-            "description": "Tool-call timeout in seconds (0 = server default, 60s).",
-            "type": "integer"
+            "description": "Execution environments this server is callable from (`cloud` and/or BYOC runner environment IDs). Always present; `[]` means all environments (also the value on legacy rows created before this field)."
           },
-          "can_edit": {
-            "description": "Whether the caller may edit this server.",
-            "type": "boolean"
+          "server_name": {
+            "type": "string",
+            "description": "MCP server name, unique within its scope (account-wide or one team)."
           },
-          "command": {
-            "description": "Executable command (stdio transport only).",
-            "type": "string"
+          "description": {
+            "type": "string",
+            "description": "Server description."
           },
-          "connect_timeout": {
-            "description": "Connection timeout in seconds (0 = server default, 10s).",
-            "type": "integer"
+          "ai_description": {
+            "type": "string",
+            "description": "LLM-generated description, preferred over `description` when present. Omitted when not yet generated."
           },
-          "created_at": {
-            "description": "Creation time. Unix timestamp in milliseconds.",
-            "format": "int64",
-            "type": "integer"
+          "transport": {
+            "type": "string",
+            "description": "Transport protocol. One of: `stdio` (standard I/O to a local subprocess), `sse` (standalone SSE, the legacy MCP transport), `streamable-http` (the newer HTTP streaming transport).",
+            "enum": [
+              "stdio",
+              "sse",
+              "streamable-http"
+            ]
           },
-          "created_by": {
-            "description": "Member ID that created the server.",
-            "format": "int64",
-            "type": "integer"
+          "command": {
+            "type": "string",
+            "description": "Executable command (stdio transport only)."
           },
-          "description": {
-            "description": "Server description.",
-            "type": "string"
+          "args": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Command arguments (stdio transport)."
           },
           "env": {
+            "type": "object",
             "additionalProperties": {
               "type": "string"
             },
-            "description": "Environment variables (stdio transport). Secret values are masked.",
-            "type": "object"
+            "description": "Environment variables (`stdio` transport). Values under credential-looking names, or encrypted at rest, are masked: longer than 8 characters shows the first and last 4 characters around `****`, otherwise `****`. Omitted when empty."
           },
-          "environments": {
-            "description": "Execution environments this server is callable from (`cloud` and/or BYOC runner environment IDs). Always present; `[]` means all environments (also the value on legacy rows created before this field).",
-            "items": {
-              "type": "string"
-            },
-            "type": "array"
+          "url": {
+            "type": "string",
+            "description": "Server URL (sse / streamable-http transport)."
           },
           "headers": {
+            "type": "object",
             "additionalProperties": {
               "type": "string"
             },
-            "description": "HTTP headers (sse / streamable-http). Secret values are masked.",
-            "type": "object"
-          },
-          "oauth_metadata": {
-            "description": "JSON-encoded OAuth metadata (per_user_oauth mode).",
-            "type": "string"
+            "description": "HTTP headers (`sse` / `streamable-http` transport), masked by the same rule as `env`. Omitted when empty."
           },
           "proxy_url": {
-            "description": "Outbound proxy URL used to reach the server.",
-            "type": "string"
+            "type": "string",
+            "description": "Outbound proxy URL used to reach the server. Not settable through the public API; omitted when empty."
           },
-          "secret_schema": {
-            "description": "JSON-encoded secret schema (per_user_secret mode).",
-            "type": "string"
+          "status": {
+            "type": "string",
+            "description": "Whether the server's tools are offered to AI SRE sessions:\n- `enabled`: available (default on create).\n- `disabled`: kept but not offered; re-enable with `POST /safari/mcp/server/enable`.",
+            "enum": [
+              "enabled",
+              "disabled"
+            ]
           },
-          "server_id": {
-            "description": "Unique MCP server ID (prefix `mcp_`).",
-            "type": "string"
+          "connect_timeout": {
+            "type": "integer",
+            "description": "Connection timeout in seconds as stored; `0` means the 10-second default is used."
           },
-          "server_name": {
-            "description": "MCP server name, unique within its scope (account-wide or one team), case-insensitive.",
-            "type": "string"
+          "call_timeout": {
+            "type": "integer",
+            "description": "Tool-call timeout in seconds as stored; `0` means the 60-second default is used."
           },
-          "source_template_name": {
-            "description": "Marketplace template this connector was installed from; empty for user-authored.",
-            "type": "string"
+          "allow_insecure_oauth_http": {
+            "type": "boolean",
+            "description": "Allow this server's OAuth token exchange over plaintext HTTP; testing use only. Omitted when false."
           },
-          "status": {
-            "description": "Server status.",
+          "allow_insecure_tls_skip_verify": {
+            "type": "boolean",
+            "description": "Skip TLS certificate verification when connecting to this server; testing use only. Omitted when false."
+          },
+          "auth_mode": {
+            "type": "string",
+            "description": "Who supplies the credential; omitted when empty, which behaves like `shared`:\n- `shared`: one credential stored on the server (`env` / `headers`) is used for every caller.\n- `per_user_secret`: each user stores their own secret, sent in the header named by `secret_schema.header_name`.\n- `per_user_oauth`: each user completes their own OAuth authorization; discovery and client registration run on first use.",
             "enum": [
-              "enabled",
-              "disabled"
-            ],
-            "type": "string"
+              "shared",
+              "per_user_secret",
+              "per_user_oauth"
+            ]
           },
-          "team_id": {
-            "description": "Team scope: 0 = account-wide; >0 = the owning team.",
+          "secret_schema": {
+            "type": "string",
+            "description": "JSON-encoded secret schema (per_user_secret mode)."
+          },
+          "oauth_metadata": {
+            "type": "string",
+            "description": "JSON-encoded OAuth metadata (per_user_oauth mode)."
+          },
+          "source_template_name": {
+            "type": "string",
+            "description": "Marketplace template this server was installed from; omitted for servers created by hand."
+          },
+          "test_error": {
+            "type": "string",
+            "description": "Error message from the last connection test; omitted when the last test succeeded or the server was never tested."
+          },
+          "tested_at": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Time of the last connection test, Unix timestamp in milliseconds; omitted if the server was never tested."
           },
-          "transport": {
-            "description": "Transport protocol. One of: `stdio` (standard I/O to a local subprocess), `sse` (standalone SSE, the legacy MCP transport), `streamable-http` (the newer HTTP streaming transport).",
-            "enum": [
-              "stdio",
-              "sse",
-              "streamable-http"
-            ],
-            "type": "string"
+          "created_by": {
+            "type": "integer",
+            "description": "Member ID that created the server.",
+            "format": "int64"
           },
-          "updated_at": {
-            "description": "Last update time. Unix timestamp in milliseconds.",
+          "created_at": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Creation time. Unix timestamp in milliseconds."
           },
-          "url": {
-            "description": "Server URL (sse / streamable-http transport).",
-            "type": "string"
+          "updated_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Last update time. Unix timestamp in milliseconds."
           }
         },
         "required": [
@@ -14904,53 +15295,53 @@
           "created_at",
           "updated_at",
           "environments"
-        ],
-        "type": "object"
+        ]
       },
       "MCPServerListRequest": {
+        "type": "object",
         "description": "Pagination, scope, and search filters for listing MCP servers.",
         "properties": {
-          "include_account": {
-            "description": "Include account-scoped (team_id=0) rows. Defaults to true.",
-            "type": [
-              "boolean",
-              "null"
-            ]
-          },
-          "limit": {
-            "default": 20,
-            "description": "Page size.",
-            "type": "integer"
-          },
           "p": {
-            "default": 1,
-            "description": "Page number, 1-based.",
-            "type": "integer"
+            "type": "integer",
+            "description": "Page number, 1-based; values below 1 are treated as 1.",
+            "default": 1
           },
-          "query": {
-            "description": "Case-insensitive substring search across name, description, AI-generated description, server ID, transport, URL, command, and source template name.",
-            "maxLength": 128,
-            "type": "string"
+          "limit": {
+            "type": "integer",
+            "description": "Page size; values below 1 fall back to 20. No upper bound is enforced.",
+            "default": 20
           },
           "scope": {
+            "type": "string",
             "description": "Restrict results to a scope: `account` for account-wide rows only, `team` for the caller's own visible team rows only, or omit (defaults to `all`) for both, subject to team_ids/include_account.",
             "enum": [
               "all",
               "account",
               "team"
             ],
-            "type": "string"
+            "default": "all"
+          },
+          "query": {
+            "type": "string",
+            "maxLength": 128,
+            "description": "Case-insensitive substring search across name, description, AI-generated description, server ID, transport, URL, command, and source template name."
           },
           "team_ids": {
-            "description": "Filter to these team IDs; empty = the caller's visible set.",
+            "type": "array",
             "items": {
-              "format": "int64",
-              "type": "integer"
+              "type": "integer",
+              "format": "int64"
             },
-            "type": "array"
+            "description": "Restrict to these team IDs. IDs of teams the caller does not belong to are ignored; empty means all of the caller's teams."
+          },
+          "include_account": {
+            "type": [
+              "boolean",
+              "null"
+            ],
+            "description": "Include account-scoped (`team_id=0`) rows. Defaults to `true`; ignored when `scope` is `account` (always included) or `team` (never included)."
           }
-        },
-        "type": "object"
+        }
       },
       "MCPServerListResponse": {
         "description": "Paginated MCP server list.",
@@ -14988,119 +15379,124 @@
         "type": "object"
       },
       "MCPServerUpdateRequest": {
+        "type": "object",
         "description": "Partial update of an MCP server. Omit a field to leave it unchanged.",
         "properties": {
-          "allow_insecure_oauth_http": {
-            "description": "Allow OAuth token exchange over plaintext HTTP. Omit to leave unchanged.",
-            "type": [
-              "boolean",
-              "null"
-            ]
+          "server_id": {
+            "type": "string",
+            "description": "Target MCP server ID, from the list returned by `POST /safari/mcp/server/list`."
           },
-          "allow_insecure_tls_skip_verify": {
-            "description": "Skip TLS certificate verification. Omit to leave unchanged.",
-            "type": [
-              "boolean",
-              "null"
+          "server_name": {
+            "type": "string",
+            "description": "New name; omitted or empty leaves it unchanged.",
+            "minLength": 1,
+            "maxLength": 255
+          },
+          "description": {
+            "type": "string",
+            "description": "New description; omitted or empty leaves it unchanged.",
+            "minLength": 1,
+            "maxLength": 1024
+          },
+          "transport": {
+            "type": "string",
+            "description": "Transport protocol; when switching, also supply the matching fields (`command`/`args`/`env` for `stdio`, `url`/`headers` for `sse` / `streamable-http`); omitted or empty leaves it unchanged.",
+            "enum": [
+              "stdio",
+              "sse",
+              "streamable-http"
             ]
           },
+          "command": {
+            "type": "string",
+            "description": "New executable command (`stdio` transport); omitted or empty leaves it unchanged."
+          },
           "args": {
-            "description": "Command arguments (`stdio` transport); replaces the whole list — pass `[]` to clear, omit to leave unchanged.",
+            "type": "array",
             "items": {
               "type": "string"
             },
-            "type": "array"
-          },
-          "auth_mode": {
-            "description": "Authentication mode: shared (default), per_user_secret, or per_user_oauth.",
-            "type": "string"
-          },
-          "call_timeout": {
-            "description": "Tool-call timeout in seconds. 0 = default (60s).",
-            "type": "integer"
-          },
-          "command": {
-            "description": "Executable command (stdio transport).",
-            "type": "string"
-          },
-          "connect_timeout": {
-            "description": "Connection timeout in seconds. 0 = default (10s).",
-            "type": "integer"
-          },
-          "description": {
-            "description": "New description; omitted or empty leaves it unchanged.",
-            "maxLength": 1024,
-            "minLength": 1,
-            "type": "string"
+            "description": "Command arguments (`stdio` transport); replaces the whole list — pass `[]` to clear, omit to leave unchanged."
           },
           "env": {
+            "type": "object",
             "additionalProperties": {
               "type": "string"
             },
-            "description": "Environment variables (`stdio` transport); replaces the whole map, but a sensitive key sent back masked or as an empty string keeps its stored value; omit to leave unchanged.",
-            "type": "object"
+            "description": "Environment variables (`stdio` transport); replaces the whole map, so keys left out are removed. For a protected key (see the masking rule on get), sending the masked value or an empty string keeps the stored value. Omit to leave unchanged."
           },
-          "environments": {
-            "description": "Execution environments this server is callable from: `cloud` and/or BYOC runner environment IDs. Omit (null) to leave unchanged; send a list to set it — an empty list clears the restriction back to all environments.",
-            "items": {
-              "type": "string"
-            },
-            "type": [
-              "array",
-              "null"
-            ]
+          "url": {
+            "type": "string",
+            "description": "New server URL (`sse` / `streamable-http` transport); omitted or empty leaves it unchanged. A real change also clears `oauth_metadata` unless a new one is sent."
           },
           "headers": {
+            "type": "object",
             "additionalProperties": {
               "type": "string"
             },
-            "description": "HTTP headers (`sse` / `streamable-http` transport); replaces the whole map, with the same masked/empty-value preservation as `env`; omit to leave unchanged.",
-            "type": "object"
+            "description": "HTTP headers (`sse` / `streamable-http` transport); replaces the whole map, with the same masked/empty-value preservation as `env`; omit to leave unchanged."
           },
-          "oauth_metadata": {
-            "description": "JSON OAuth metadata; reserved for per_user_oauth.",
-            "type": "string"
+          "connect_timeout": {
+            "type": "integer",
+            "description": "New connection timeout in seconds; omitted or `0` leaves it unchanged (a stored `0` means the 10-second default)."
           },
-          "secret_schema": {
-            "description": "JSON secret schema; required when auth_mode=per_user_secret.",
-            "type": "string"
+          "call_timeout": {
+            "type": "integer",
+            "description": "New tool-call timeout in seconds; omitted or `0` leaves it unchanged (a stored `0` means the 60-second default)."
           },
-          "server_id": {
-            "description": "Target MCP server ID, from the list returned by `POST /safari/mcp/server/list`.",
-            "type": "string"
+          "auth_mode": {
+            "type": "string",
+            "description": "New auth mode; omitted or empty leaves it unchanged. Who supplies the credential:\n- `shared` (default; an empty value behaves the same): one credential stored on the server (`env` / `headers`) is used for every caller.\n- `per_user_secret`: each user stores their own secret, sent in the header named by `secret_schema.header_name`.\n- `per_user_oauth`: each user completes their own OAuth authorization; discovery and client registration run on first use.\n\n`per_user_secret` requires `secret_schema` with a non-empty `header_name`; any other value returns `InvalidParameter`.",
+            "enum": [
+              "shared",
+              "per_user_secret",
+              "per_user_oauth"
+            ]
           },
-          "server_name": {
-            "description": "New name; omitted or empty leaves it unchanged.",
-            "maxLength": 255,
-            "minLength": 1,
-            "type": "string"
+          "secret_schema": {
+            "type": "string",
+            "description": "New JSON secret schema, e.g. `{\"header_name\":\"X-Api-Key\"}`. Applied only together with a non-empty `auth_mode`; sent alone it is ignored."
+          },
+          "oauth_metadata": {
+            "type": "string",
+            "description": "New JSON OAuth metadata. A non-empty value is stored as sent. When omitted or empty, the stored value is kept unless `auth_mode` or `url` changes, in which case it is cleared."
           },
           "team_id": {
-            "description": "Reassign team scope: 0 = account-wide; >0 = team. Omit to leave unchanged.",
-            "format": "int64",
             "type": [
               "integer",
               "null"
-            ]
+            ],
+            "description": "Reassign team scope: `0` = account-wide (account owner or admin only); `>0` = a team the caller belongs to. Servers installed from the marketplace can only move to `0`. Omit to leave unchanged.",
+            "format": "int64"
           },
-          "transport": {
-            "description": "Transport protocol; when switching, also supply the matching fields (`command`/`args`/`env` for `stdio`, `url`/`headers` for `sse` / `streamable-http`); omitted or empty leaves it unchanged.",
-            "enum": [
-              "stdio",
-              "sse",
-              "streamable-http"
+          "environments": {
+            "type": [
+              "array",
+              "null"
             ],
-            "type": "string"
+            "items": {
+              "type": "string"
+            },
+            "description": "Execution environments this server is callable from: `cloud` and/or BYOC runner environment IDs. Omit (null) to leave unchanged; send a list to set it — an empty list clears the restriction back to all environments."
           },
-          "url": {
-            "description": "Server URL (sse / streamable-http transport).",
-            "type": "string"
+          "allow_insecure_oauth_http": {
+            "type": [
+              "boolean",
+              "null"
+            ],
+            "description": "Allow OAuth token exchange over plaintext HTTP. Omit to leave unchanged."
+          },
+          "allow_insecure_tls_skip_verify": {
+            "type": [
+              "boolean",
+              "null"
+            ],
+            "description": "Skip TLS certificate verification. Omit to leave unchanged."
           }
         },
         "required": [
           "server_id"
-        ],
-        "type": "object"
+        ]
       },
       "ManualRunRuleResult": {
         "description": "Result of manually running an Automation rule outside its schedule.",
@@ -15131,73 +15527,75 @@
         "type": "object"
       },
       "MappingAPICreateRequest": {
+        "type": "object",
+        "required": [
+          "api_name",
+          "url"
+        ],
         "properties": {
           "api_name": {
-            "description": "Unique API name (max 199 chars).",
+            "type": "string",
             "maxLength": 199,
-            "type": "string"
+            "description": "Name of the mapping API, unique among non-deleted mapping APIs (max 199 characters)."
           },
           "description": {
-            "description": "Optional description. Values longer than 500 characters are silently truncated.",
-            "type": "string"
+            "type": "string",
+            "description": "Optional description. Values longer than 500 characters are silently truncated."
+          },
+          "url": {
+            "type": "string",
+            "format": "uri",
+            "maxLength": 500,
+            "description": "Endpoint called with `POST`. Must be an `http` or `https` URL of at most 500 characters; in SaaS the host must not resolve to an internal IP address."
+          },
+          "insecure_skip_verify": {
+            "type": "boolean",
+            "description": "Skip TLS certificate verification. Default `false`."
           },
           "headers": {
+            "type": "object",
             "additionalProperties": {
               "type": "string"
             },
-            "description": "Custom HTTP request headers. In SaaS mode, security-sensitive names (`authorization`, `cookie`, `x-forwarded-for`, etc.) are rejected; keys must be RFC 7230 token characters (max 1024 chars) and values max 4096 chars.",
-            "type": "object"
+            "description": "Custom HTTP request headers. In SaaS mode, security-sensitive names (`authorization`, `cookie`, `x-forwarded-for`, etc.) are rejected; keys must be RFC 7230 token characters (max 1024 chars) and values max 4096 chars."
           },
-          "insecure_skip_verify": {
-            "description": "Skip TLS certificate verification. Default `false`.",
-            "type": "boolean"
+          "timeout": {
+            "type": "integer",
+            "description": "Timeout of the whole request in seconds (1–3). Defaults to 2 when omitted or 0.",
+            "minimum": 1,
+            "maximum": 3,
+            "default": 2
           },
           "retry_count": {
-            "description": "Number of retries on failure (0–1). Default 0.",
-            "maximum": 1,
+            "type": "integer",
+            "description": "Number of retries after a failed call (0–1). Defaults to 0.",
             "minimum": 0,
-            "type": "integer"
+            "maximum": 1,
+            "default": 0
           },
           "team_id": {
-            "description": "Owning team ID; obtain it from `POST /team/list`.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
-          },
-          "timeout": {
-            "description": "Request timeout in seconds (1–3). Default 2.",
-            "maximum": 3,
-            "minimum": 1,
-            "type": "integer"
-          },
-          "url": {
-            "description": "HTTP/HTTPS endpoint URL (max 500 chars).",
-            "format": "uri",
-            "maxLength": 500,
-            "type": "string"
+            "description": "Owning team ID; obtain it from `POST /team/list`. `0` or omitted means no team. A non-zero ID must be an existing team."
           }
-        },
-        "required": [
-          "api_name",
-          "url"
-        ],
-        "type": "object"
+        }
       },
       "MappingAPICreateResponse": {
+        "type": "object",
         "properties": {
           "api_id": {
-            "description": "Created API ID (MongoDB ObjectID hex).",
-            "type": "string"
+            "type": "string",
+            "description": "Created API ID (MongoDB ObjectID hex)."
           },
           "api_name": {
-            "description": "API name.",
-            "type": "string"
+            "type": "string",
+            "description": "Name of the created mapping API, as sent in the request."
           }
         },
         "required": [
           "api_id",
           "api_name"
-        ],
-        "type": "object"
+        ]
       },
       "MappingAPIIDRequest": {
         "properties": {
@@ -15212,83 +15610,84 @@
         "type": "object"
       },
       "MappingAPIItem": {
+        "type": "object",
         "description": "Mapping API configuration.",
         "properties": {
           "api_id": {
-            "description": "API ID (MongoDB ObjectID hex).",
-            "type": "string"
+            "type": "string",
+            "description": "API ID (MongoDB ObjectID hex)."
           },
           "api_name": {
-            "description": "API name.",
-            "type": "string"
-          },
-          "created_at": {
-            "description": "Creation time, Unix seconds. Omitted when 0 (legacy records).",
-            "format": "int64",
-            "type": "integer"
-          },
-          "creator_id": {
-            "description": "Creator member ID.",
-            "format": "int64",
-            "type": "integer"
-          },
-          "deleted_at": {
-            "description": "Deletion time, Unix seconds. Omitted when the API has not been soft-deleted.",
-            "format": "int64",
-            "type": "integer"
+            "type": "string",
+            "description": "Name of the mapping API, unique among non-deleted mapping APIs."
           },
           "description": {
-            "description": "Description.",
-            "type": "string"
+            "type": "string",
+            "description": "Free-text description (at most 500 characters); an empty string when none was given."
+          },
+          "url": {
+            "type": "string",
+            "description": "Endpoint URL."
           },
           "headers": {
-            "additionalProperties": {
-              "type": "string"
-            },
-            "description": "Custom request headers. `null` when none are configured.",
             "type": [
               "object",
               "null"
-            ]
+            ],
+            "additionalProperties": {
+              "type": "string"
+            },
+            "description": "Request headers sent with every call, returned in plain text. `null` when none are configured."
           },
-          "insecure_skip_verify": {
-            "description": "Whether TLS verification is skipped.",
-            "type": "boolean"
+          "timeout": {
+            "type": "integer",
+            "description": "Timeout of the whole request in seconds (1–3)."
           },
           "retry_count": {
-            "description": "Retry count.",
-            "type": "integer"
+            "type": "integer",
+            "description": "Number of retries after a failed call: `0` or `1`."
+          },
+          "insecure_skip_verify": {
+            "type": "boolean",
+            "description": "Whether TLS verification is skipped."
           },
           "status": {
-            "description": "API status: `enabled` or `deleted` (soft-deleted). The list endpoint excludes `deleted` items; the info endpoint may return them.",
+            "type": "string",
             "enum": [
               "enabled",
               "deleted"
             ],
-            "type": "string"
+            "description": "API status: `enabled` or `deleted` (soft-deleted). The list endpoint excludes `deleted` items; the info endpoint may return them."
           },
           "team_id": {
-            "description": "Owning team ID.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
-          },
-          "timeout": {
-            "description": "Request timeout in seconds.",
-            "type": "integer"
+            "description": "Owning team ID."
           },
-          "updated_at": {
-            "description": "Last update time, Unix seconds. Omitted when 0 (legacy records).",
+          "creator_id": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Creator member ID."
           },
           "updated_by": {
-            "description": "Last updater member ID.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Last updater member ID."
           },
-          "url": {
-            "description": "Endpoint URL.",
-            "type": "string"
+          "created_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Creation time, Unix seconds. Omitted when 0 (legacy records)."
+          },
+          "updated_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Last update time, Unix seconds. Omitted when 0 (legacy records)."
+          },
+          "deleted_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Deletion time, Unix seconds. Omitted when the API has not been soft-deleted."
           }
         },
         "required": [
@@ -15304,340 +15703,348 @@
           "team_id",
           "updated_by",
           "creator_id"
-        ],
-        "type": "object"
+        ]
       },
       "MappingAPIListResponse": {
+        "type": "object",
         "properties": {
+          "total": {
+            "type": "integer",
+            "description": "Number of items returned; the list is not paginated."
+          },
           "items": {
-            "description": "Mapping APIs.",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/MappingAPIItem"
             },
-            "type": "array"
-          },
-          "total": {
-            "description": "Total API count.",
-            "type": "integer"
+            "description": "Mapping APIs."
           }
         },
         "required": [
           "total",
           "items"
-        ],
-        "type": "object"
+        ]
       },
       "MappingAPIUpdateRequest": {
+        "type": "object",
+        "required": [
+          "api_id"
+        ],
         "properties": {
           "api_id": {
-            "description": "Mapping API ID (MongoDB ObjectID hex).",
-            "type": "string"
+            "type": "string",
+            "description": "Mapping API ID (MongoDB ObjectID hex)."
           },
           "api_name": {
-            "description": "New API name (max 199 chars).",
-            "maxLength": 199,
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "maxLength": 199,
+            "description": "New name, unique among non-deleted mapping APIs (max 199 characters). Omit to keep."
           },
           "description": {
-            "description": "New description.",
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "New description; longer than 500 characters is truncated. Omit to keep, send `\"\"` to clear."
           },
-          "headers": {
-            "additionalProperties": {
-              "type": "string"
-            },
-            "description": "Custom HTTP request headers. In SaaS mode, security-sensitive names (`authorization`, `cookie`, `x-forwarded-for`, etc.) are rejected; keys must be RFC 7230 token characters (max 1024 chars) and values max 4096 chars.",
-            "type": "object"
+          "url": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "format": "uri",
+            "maxLength": 500,
+            "description": "New `http`/`https` endpoint (max 500 characters); in SaaS the host must not resolve to an internal IP. Omit to keep."
           },
           "insecure_skip_verify": {
-            "description": "New TLS skip-verify setting.",
             "type": [
               "boolean",
               "null"
-            ]
+            ],
+            "description": "New TLS skip-verify setting. Omit to keep."
           },
-          "retry_count": {
-            "description": "New retry count.",
-            "maximum": 1,
-            "minimum": 0,
-            "type": [
-              "integer",
-              "null"
-            ]
+          "headers": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "string"
+            },
+            "description": "Replaces the whole header map when sent; send `{}` to remove all headers. Omit to keep. In SaaS, sensitive header names (see `/enrichment/mapping/api/create`) are rejected; keys are at most 1,024 characters and values at most 4,096."
           },
-          "team_id": {
-            "description": "New owning team ID; obtain it from `POST /team/list`.",
-            "format": "int64",
+          "timeout": {
             "type": [
               "integer",
               "null"
-            ]
-          },
-          "timeout": {
-            "description": "New timeout in seconds.",
-            "maximum": 3,
+            ],
+            "description": "New whole-request timeout in seconds (1–3). Omit to keep.",
             "minimum": 1,
+            "maximum": 3
+          },
+          "retry_count": {
             "type": [
               "integer",
               "null"
-            ]
+            ],
+            "description": "New retry count (0–1). Omit to keep.",
+            "minimum": 0,
+            "maximum": 1
           },
-          "url": {
-            "description": "New endpoint URL (max 500 chars).",
-            "format": "uri",
-            "maxLength": 500,
+          "team_id": {
             "type": [
-              "string",
+              "integer",
               "null"
-            ]
+            ],
+            "format": "int64",
+            "description": "New owning team ID from `POST /team/list`; `0` removes the team. Omit to keep."
           }
-        },
-        "required": [
-          "api_id"
-        ],
-        "type": "object"
+        }
       },
       "MappingDataDeleteRequest": {
+        "type": "object",
+        "required": [
+          "schema_id",
+          "keys"
+        ],
         "properties": {
+          "schema_id": {
+            "type": "string",
+            "description": "Mapping schema ID (MongoDB ObjectID hex)."
+          },
           "keys": {
-            "description": "Keys of rows to delete.",
+            "type": "array",
             "items": {
               "type": "string"
             },
             "maxItems": 100,
-            "type": "array"
-          },
-          "schema_id": {
-            "description": "Mapping schema ID (MongoDB ObjectID hex).",
-            "type": "string"
+            "description": "Row keys to delete (at most 100), as returned in `key` by `/enrichment/mapping/data/list` or in `keys` by `/enrichment/mapping/data/upsert`. Keys that match no row are ignored."
           }
-        },
-        "required": [
-          "schema_id",
-          "keys"
-        ],
-        "type": "object"
+        }
       },
       "MappingDataItem": {
+        "type": "object",
         "description": "A single mapping data row.",
         "properties": {
-          "created_at": {
-            "description": "Creation time, Unix seconds. Omitted when 0.",
-            "format": "int64",
-            "type": "integer"
+          "key": {
+            "type": "string",
+            "description": "Composite row key — MD5 of the row's source label values (sorted by label name, joined with `:`). Omitted when empty."
           },
           "fields": {
+            "type": "object",
             "additionalProperties": {
               "type": "string"
             },
-            "description": "All label key-value pairs of this row. Omitted when empty.",
-            "type": "object"
+            "description": "All label key-value pairs of this row. Omitted when empty."
           },
-          "key": {
-            "description": "Composite row key — MD5 of the row's source label values (sorted by label name, joined with `:`). Omitted when empty.",
-            "type": "string"
+          "created_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Time the row was last written, Unix seconds; a replaced row gets a new value. Omitted when 0."
           },
           "updated_at": {
-            "description": "Last update time, Unix seconds. Omitted when 0.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Last update time, Unix seconds. Omitted when 0."
           }
-        },
-        "type": "object"
+        }
       },
       "MappingDataListRequest": {
+        "type": "object",
+        "required": [
+          "schema_id"
+        ],
         "properties": {
-          "asc": {
-            "description": "Sort ascending when `true`.",
-            "type": "boolean"
+          "schema_id": {
+            "type": "string",
+            "description": "Mapping schema ID (MongoDB ObjectID hex)."
           },
-          "limit": {
-            "description": "Page size (0–100); defaults to 20 when omitted, `null`, or 0.",
-            "format": "int64",
-            "maximum": 100,
-            "minimum": 0,
-            "type": [
-              "integer",
-              "null"
-            ]
+          "query": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "string"
+            },
+            "description": "Exact-match filter on source label values. Keys that are not source labels of the schema are silently ignored; if any source label is given, all source labels must be provided."
           },
           "orderby": {
-            "description": "Sort field. Defaults to `updated_at`.",
+            "type": "string",
             "enum": [
               "created_at",
               "updated_at"
             ],
-            "type": "string"
+            "description": "Sort field. Defaults to `updated_at`."
+          },
+          "asc": {
+            "type": "boolean",
+            "description": "Sort ascending when `true`; defaults to `false` (newest first).",
+            "default": false
           },
           "p": {
-            "description": "Page number (1-based) for offset pagination; defaults to 1 when omitted, `null`, or 0. Ignored when `search_after_ctx` is set. Page-based navigation can reach at most 10,000 rows (`p * limit <= 10000`).",
-            "format": "int64",
-            "minimum": 0,
             "type": [
               "integer",
               "null"
-            ]
-          },
-          "query": {
-            "additionalProperties": {
-              "type": "string"
-            },
-            "description": "Exact-match filter on source label values. Keys that are not source labels of the schema are silently ignored; if any source label is given, all source labels must be provided.",
-            "type": "object"
+            ],
+            "format": "int64",
+            "description": "Page number (1-based) for offset pagination; defaults to 1 when omitted, `null`, or 0. Ignored when `search_after_ctx` is set. Page-based navigation can reach at most 10,000 rows (`p * limit <= 10000`).",
+            "minimum": 0
           },
-          "schema_id": {
-            "description": "Mapping schema ID (MongoDB ObjectID hex).",
-            "type": "string"
+          "limit": {
+            "type": [
+              "integer",
+              "null"
+            ],
+            "format": "int64",
+            "description": "Page size (0–100); defaults to 20 when omitted, `null`, or 0.",
+            "minimum": 0,
+            "maximum": 100
           },
           "search_after_ctx": {
-            "description": "Opaque cursor for cursor-based pagination — pass the `search_after_ctx` value from the previous response. Must be a MongoDB ObjectID hex string; when set, `p` is ignored.",
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "Opaque cursor for cursor-based pagination — pass the `search_after_ctx` value from the previous response. Must be a MongoDB ObjectID hex string; when set, `p` is ignored."
           }
-        },
-        "required": [
-          "schema_id"
-        ],
-        "type": "object"
+        }
       },
       "MappingDataListResponse": {
+        "type": "object",
         "properties": {
-          "has_next_page": {
-            "description": "Whether more pages exist.",
-            "type": "boolean"
-          },
           "items": {
-            "description": "Data rows.",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/MappingDataItem"
             },
-            "type": "array"
-          },
-          "search_after_ctx": {
-            "description": "Cursor token (ObjectID hex of this page's last row) for fetching the next page. Omitted when there is no next page.",
-            "type": "string"
+            "description": "Data rows of this page, ordered by `orderby`/`asc`. Empty when nothing matches."
           },
           "total": {
-            "description": "Total matching rows.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Number of rows matching `query`, counted up to 1,000; a value of 1,000 means at least 1,000."
+          },
+          "has_next_page": {
+            "type": "boolean",
+            "description": "`true` when more rows follow this page."
+          },
+          "used_cnt": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Total number of rows stored in the schema, regardless of `query`. Compare it with the schema row limit (10,000 by default)."
+          },
+          "search_after_ctx": {
+            "type": "string",
+            "description": "Cursor token (ObjectID hex of this page's last row) for fetching the next page. Omitted when there is no next page."
           }
         },
         "required": [
           "items",
           "total",
-          "has_next_page"
-        ],
-        "type": "object"
+          "has_next_page",
+          "used_cnt"
+        ]
       },
       "MappingDataUpsertRequest": {
+        "type": "object",
+        "required": [
+          "schema_id",
+          "docs"
+        ],
         "properties": {
+          "schema_id": {
+            "type": "string",
+            "description": "Mapping schema ID (MongoDB ObjectID hex)."
+          },
           "docs": {
-            "description": "Rows to insert or update. Each row must include all source and result labels; unknown labels are silently dropped; a value longer than 2048 characters is rejected.",
+            "type": "array",
             "items": {
+              "type": "object",
               "additionalProperties": {
                 "type": "string"
-              },
-              "type": "object"
+              }
             },
             "maxItems": 1000,
-            "type": "array"
-          },
-          "schema_id": {
-            "description": "Mapping schema ID (MongoDB ObjectID hex).",
-            "type": "string"
+            "description": "Rows to insert or replace (at most 1,000). Each row maps label names to values and must include every source and result label; other keys are dropped; a value longer than 2,048 bytes is rejected. A row whose source label values match an existing row replaces it."
           }
-        },
-        "required": [
-          "schema_id",
-          "docs"
-        ],
-        "type": "object"
+        }
       },
       "MappingDataUpsertResponse": {
+        "type": "object",
         "properties": {
           "keys": {
-            "description": "Composite keys of upserted rows.",
+            "type": "array",
             "items": {
               "type": "string"
             },
-            "type": "array"
+            "description": "Row keys of the written rows (one per distinct row, in no particular order); use them with `/enrichment/mapping/data/delete`."
           }
         },
         "required": [
           "keys"
-        ],
-        "type": "object"
+        ]
       },
       "MappingSchemaCreateRequest": {
+        "type": "object",
+        "required": [
+          "schema_name",
+          "source_labels",
+          "result_labels"
+        ],
         "properties": {
+          "schema_name": {
+            "type": "string",
+            "maxLength": 39,
+            "description": "Schema name, unique among the account's non-deleted schemas (max 39 characters)."
+          },
           "description": {
-            "description": "Optional description (max 500 chars).",
+            "type": "string",
             "maxLength": 500,
-            "type": "string"
-          },
-          "result_labels": {
-            "description": "Output label names written on a match (1–10). Each must match `^[a-zA-Z_][a-zA-Z0-9_]*$`; entries must be unique and must not overlap with `source_labels`.",
-            "items": {
-              "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$",
-              "type": "string"
-            },
-            "maxItems": 10,
-            "type": "array",
-            "uniqueItems": true
+            "description": "Optional description (max 500 chars)."
           },
-          "schema_name": {
-            "description": "Unique schema name (max 39 chars).",
-            "maxLength": 39,
-            "type": "string"
+          "team_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Owning team ID from `POST /team/list`. `0` or omitted means no team; a non-zero ID must be an existing team."
           },
           "source_labels": {
-            "description": "Lookup key label names (1–3). Each must match `^[a-zA-Z_][a-zA-Z0-9_]*$`; entries must be unique and must not overlap with `result_labels`.",
+            "type": "array",
             "items": {
-              "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$",
-              "type": "string"
+              "type": "string",
+              "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$"
             },
             "maxItems": 3,
-            "type": "array",
-            "uniqueItems": true
+            "description": "Lookup key label names (1–3). Each must match `^[a-zA-Z_][a-zA-Z0-9_]*$`; entries must be unique and must not overlap with `result_labels`.",
+            "uniqueItems": true,
+            "minItems": 1
           },
-          "team_id": {
-            "description": "Owning team ID. `0` means no team.",
-            "format": "int64",
-            "type": "integer"
+          "result_labels": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$"
+            },
+            "maxItems": 10,
+            "description": "Output label names written on a match (1–10). Each must match `^[a-zA-Z_][a-zA-Z0-9_]*$`; entries must be unique and must not overlap with `source_labels`.",
+            "uniqueItems": true,
+            "minItems": 1
           }
-        },
-        "required": [
-          "schema_name",
-          "source_labels",
-          "result_labels"
-        ],
-        "type": "object"
+        }
       },
       "MappingSchemaCreateResponse": {
+        "type": "object",
         "properties": {
           "schema_id": {
-            "description": "Created schema ID (MongoDB ObjectID hex).",
-            "type": "string"
+            "type": "string",
+            "description": "Created schema ID (MongoDB ObjectID hex)."
           },
           "schema_name": {
-            "description": "Schema name.",
-            "type": "string"
+            "type": "string",
+            "description": "Name of the created schema, as sent in the request."
           }
         },
         "required": [
           "schema_id",
           "schema_name"
-        ],
-        "type": "object"
+        ]
       },
       "MappingSchemaIDRequest": {
         "properties": {
@@ -15652,71 +16059,72 @@
         "type": "object"
       },
       "MappingSchemaItem": {
+        "type": "object",
         "description": "Mapping schema definition.",
         "properties": {
-          "created_at": {
-            "description": "Creation time, Unix seconds. Omitted when 0 (legacy records).",
-            "format": "int64",
-            "type": "integer"
-          },
-          "creator_id": {
-            "description": "Creator member ID.",
-            "format": "int64",
-            "type": "integer"
+          "schema_id": {
+            "type": "string",
+            "description": "Schema ID (MongoDB ObjectID hex)."
           },
-          "deleted_at": {
-            "description": "Deletion time, Unix seconds. Omitted when the schema has not been soft-deleted.",
-            "format": "int64",
-            "type": "integer"
+          "schema_name": {
+            "type": "string",
+            "description": "Schema name, unique among the account's non-deleted schemas."
           },
           "description": {
-            "description": "Schema description.",
-            "type": "string"
+            "type": "string",
+            "description": "Schema description."
           },
-          "result_labels": {
-            "description": "Output label names.",
+          "source_labels": {
+            "type": "array",
             "items": {
               "type": "string"
             },
-            "type": "array"
-          },
-          "schema_id": {
-            "description": "Schema ID (MongoDB ObjectID hex).",
-            "type": "string"
-          },
-          "schema_name": {
-            "description": "Schema name.",
-            "type": "string"
+            "description": "Label names whose values form the lookup key of a data row (1–3); fixed at creation."
           },
-          "source_labels": {
-            "description": "Lookup key label names.",
+          "result_labels": {
+            "type": "array",
             "items": {
               "type": "string"
             },
-            "type": "array"
+            "description": "Label names written to the event when a row matches (1–10); fixed at creation."
           },
           "status": {
-            "description": "Schema status: `enabled` or `deleted` (soft-deleted). The list endpoint excludes `deleted` items; the info endpoint may return them.",
+            "type": "string",
             "enum": [
               "enabled",
               "deleted"
             ],
-            "type": "string"
+            "description": "Schema status: `enabled` or `deleted` (soft-deleted). The list endpoint excludes `deleted` items; the info endpoint may return them."
           },
           "team_id": {
-            "description": "Owning team ID.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Owning team ID; `0` when the schema belongs to no team."
           },
-          "updated_at": {
-            "description": "Last update time, Unix seconds. Omitted when 0 (legacy records).",
+          "creator_id": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Creator member ID."
           },
           "updated_by": {
-            "description": "Last updater member ID.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Last updater member ID."
+          },
+          "created_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Creation time, Unix seconds. Omitted when 0 (legacy records)."
+          },
+          "updated_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Last update time, Unix seconds. Omitted when 0 (legacy records)."
+          },
+          "deleted_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Deletion time, Unix seconds. Omitted when the schema has not been soft-deleted."
           }
         },
         "required": [
@@ -15729,66 +16137,99 @@
           "team_id",
           "updated_by",
           "creator_id"
-        ],
-        "type": "object"
+        ]
       },
       "MappingSchemaListResponse": {
+        "type": "object",
         "properties": {
+          "total": {
+            "type": "integer",
+            "description": "Number of items returned; the list is not paginated."
+          },
           "items": {
-            "description": "Mapping schemas.",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/MappingSchemaItem"
             },
-            "type": "array"
-          },
-          "total": {
-            "description": "Total schema count.",
-            "type": "integer"
+            "description": "Mapping schemas."
           }
         },
         "required": [
           "total",
           "items"
-        ],
-        "type": "object"
+        ]
       },
       "MappingSchemaUpdateRequest": {
+        "type": "object",
+        "required": [
+          "schema_id"
+        ],
         "properties": {
-          "description": {
-            "description": "New description (max 500 chars).",
-            "maxLength": 500,
-            "type": [
-              "string",
-              "null"
-            ]
-          },
           "schema_id": {
-            "description": "Schema ID (MongoDB ObjectID hex).",
-            "type": "string"
+            "type": "string",
+            "description": "Schema ID (MongoDB ObjectID hex)."
           },
           "schema_name": {
-            "description": "New schema name (max 39 chars).",
+            "type": [
+              "string",
+              "null"
+            ],
             "maxLength": 39,
+            "description": "New name, unique among non-deleted schemas (max 39 characters). Omit to keep."
+          },
+          "description": {
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "maxLength": 500,
+            "description": "New description (max 500 characters). Omit to keep, send `\"\"` to clear."
           },
           "team_id": {
-            "description": "New owning team ID. `0` removes the team association.",
-            "format": "int64",
             "type": [
               "integer",
               "null"
-            ]
+            ],
+            "format": "int64",
+            "description": "New owning team ID from `POST /team/list`; `0` removes the team. Omit to keep."
           }
-        },
-        "required": [
-          "schema_id"
-        ],
-        "type": "object"
+        }
       },
       "MemberDeleteRequest": {
+        "type": "object",
+        "description": "Delete member request (provide one of the lookup fields)",
+        "properties": {
+          "member_id": {
+            "type": "integer",
+            "format": "uint64",
+            "description": "Member ID. When several lookup fields are provided, the first non-empty one wins in the order `member_id` > `member_name` > `email` > `phone` > `ref_id`"
+          },
+          "member_name": {
+            "type": "string",
+            "description": "Member name. Only used when `member_id` is not provided"
+          },
+          "email": {
+            "type": "string",
+            "description": "Email address. Only used when neither `member_id` nor `member_name` is provided"
+          },
+          "phone": {
+            "type": "string",
+            "description": "Phone number. Only used when `member_id`, `member_name`, and `email` are all absent"
+          },
+          "country_code": {
+            "type": "string",
+            "description": "Region hint for parsing `phone` when it has no \"+\" prefix — an ISO 3166-1 alpha-2 code such as \"CN\" (the default when omitted). Legacy digit calling codes like \"86\" are still accepted in this parsing context."
+          },
+          "ref_id": {
+            "type": "string",
+            "description": "External reference ID. Only used when all other lookup fields are absent"
+          },
+          "is_force": {
+            "type": "boolean",
+            "description": "Skip the reference check. When false (default), the call fails with `ReferenceExist` if the member belongs to a team, is targeted by an escalation rule, or is in a schedule. A forced delete does not remove those references.",
+            "default": false
+          }
+        },
         "anyOf": [
           {
             "required": [
@@ -15815,41 +16256,7 @@
               "ref_id"
             ]
           }
-        ],
-        "description": "Delete member request (provide one of the lookup fields)",
-        "properties": {
-          "country_code": {
-            "description": "Region hint for parsing `phone` when it has no \"+\" prefix — an ISO 3166-1 alpha-2 code such as \"CN\" (the default when omitted). Legacy digit calling codes like \"86\" are still accepted in this parsing context.",
-            "type": "string"
-          },
-          "email": {
-            "description": "Email address. Only used when neither `member_id` nor `member_name` is provided",
-            "type": "string"
-          },
-          "is_force": {
-            "default": false,
-            "description": "Force delete. Defaults to false, which checks for references from escalation rules, schedules, etc. Set to true to skip the reference check and delete immediately",
-            "type": "boolean"
-          },
-          "member_id": {
-            "description": "Member ID. When several lookup fields are provided, the first non-empty one wins in the order `member_id` > `member_name` > `email` > `phone` > `ref_id`",
-            "format": "uint64",
-            "type": "integer"
-          },
-          "member_name": {
-            "description": "Member name. Only used when `member_id` is not provided",
-            "type": "string"
-          },
-          "phone": {
-            "description": "Phone number. Only used when `member_id`, `member_name`, and `email` are all absent",
-            "type": "string"
-          },
-          "ref_id": {
-            "description": "External reference ID. Only used when all other lookup fields are absent",
-            "type": "string"
-          }
-        },
-        "type": "object"
+        ]
       },
       "MemberEmptyObject": {
         "description": "Empty response",
@@ -15862,102 +16269,110 @@
         "type": "object"
       },
       "MemberInfoResponse": {
+        "type": "object",
         "description": "Current member profile",
         "properties": {
-          "account_avatar": {
-            "description": "Account avatar URL",
-            "type": "string"
-          },
-          "account_email": {
-            "description": "Account email",
-            "type": "string"
-          },
           "account_id": {
-            "description": "Account ID",
+            "type": "integer",
             "format": "uint64",
-            "type": "integer"
-          },
-          "account_locale": {
-            "description": "Account-level locale preference (e.g. zh-CN or en-US). Omitted when the account has none set.",
-            "type": "string"
+            "description": "ID of the account the member belongs to."
           },
           "account_name": {
-            "description": "Account name",
-            "type": "string"
+            "type": "string",
+            "description": "Name of the account (organization)."
+          },
+          "account_avatar": {
+            "type": "string",
+            "description": "Account avatar URL"
+          },
+          "account_email": {
+            "type": "string",
+            "description": "Contact email of the account owner."
           },
           "account_role_ids": {
-            "description": "Assigned role IDs",
+            "type": "array",
             "items": {
-              "format": "uint64",
-              "type": "integer"
+              "type": "integer",
+              "format": "uint64"
             },
-            "type": "array"
+            "description": "IDs of the roles assigned to the member; resolve them with `POST /role/list`."
+          },
+          "account_locale": {
+            "type": "string",
+            "description": "Account-level locale preference (e.g. zh-CN or en-US). Omitted when the account has none set."
           },
           "account_time_zone": {
-            "description": "Account-level time zone (e.g. Asia/Shanghai). Omitted when the account has none set.",
-            "type": "string"
+            "type": "string",
+            "description": "The account's IANA time zone setting; empty string when the account has none. Always present."
           },
-          "avatar": {
-            "description": "Member avatar URL",
-            "type": "string"
+          "resolved_time_zone": {
+            "type": "string",
+            "description": "Effective time zone to render times in: the member's `time_zone` if valid, otherwise the account's, otherwise `Asia/Shanghai`. Always present."
           },
-          "country_code": {
-            "description": "ISO 3166-1 alpha-2 region code of the member's contact phone (e.g. \"CN\", \"US\", \"HK\").",
-            "type": "string"
+          "domain": {
+            "type": "string",
+            "description": "Account domain, the subdomain used to sign in to the console."
           },
-          "created_at": {
-            "description": "Member creation time, Unix timestamp in seconds.",
-            "format": "int64",
-            "type": "integer"
+          "member_id": {
+            "type": "integer",
+            "format": "uint64",
+            "description": "ID of the calling member."
           },
-          "domain": {
-            "description": "Account domain",
-            "type": "string"
+          "member_name": {
+            "type": "string",
+            "description": "Member display name"
+          },
+          "phone": {
+            "type": "string",
+            "description": "Masked phone number"
+          },
+          "phone_verified": {
+            "type": "boolean",
+            "description": "Whether phone is verified"
           },
           "email": {
-            "description": "Email address",
-            "type": "string"
+            "type": "string",
+            "description": "Email address"
           },
           "email_verified": {
-            "description": "Whether email is verified",
-            "type": "boolean"
+            "type": "boolean",
+            "description": "Whether email is verified"
           },
-          "is_external": {
-            "description": "Whether provisioned via SSO",
-            "type": "boolean"
+          "country_code": {
+            "type": "string",
+            "description": "ISO 3166-1 alpha-2 region code of the member's contact phone (e.g. \"CN\", \"US\", \"HK\")."
+          },
+          "avatar": {
+            "type": "string",
+            "description": "Member avatar URL"
           },
           "locale": {
-            "description": "Member's locale preference. Omitted when the member has none set.",
-            "type": "string"
+            "type": "string",
+            "description": "Member's locale preference. Omitted when the member has none set."
           },
-          "member_id": {
-            "description": "Member ID",
-            "format": "uint64",
-            "type": "integer"
+          "time_zone": {
+            "type": "string",
+            "description": "The member's own IANA time zone setting; empty string when the member follows the account's time zone. Always present."
           },
-          "member_name": {
-            "description": "Member display name",
-            "type": "string"
+          "is_external": {
+            "type": "boolean",
+            "description": "Whether provisioned via SSO"
           },
-          "mp_account_id": {
-            "description": "Account identifier on the marketplace platform. Omitted together with `mp_plat`.",
-            "type": "string"
+          "created_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Member creation time, Unix timestamp in seconds."
           },
           "mp_plat": {
-            "description": "Cloud marketplace platform the account was provisioned from. Omitted when the account did not come from a marketplace.",
-            "type": "string"
-          },
-          "phone": {
-            "description": "Masked phone number",
-            "type": "string"
-          },
-          "phone_verified": {
-            "description": "Whether phone is verified",
-            "type": "boolean"
+            "type": "string",
+            "description": "Cloud marketplace the account was provisioned from: `aws` — AWS Marketplace. Omitted when the account did not come from a marketplace.",
+            "enum": [
+              "aws"
+            ]
           },
-          "time_zone": {
-            "description": "Member's IANA time zone. Omitted when the member has none set.",
-            "type": "string"
+          "mp_account_id": {
+            "type": "string",
+            "description": "Account identifier on the marketplace platform. Omitted together with `mp_plat`."
           }
         },
         "required": [
@@ -15976,9 +16391,11 @@
           "country_code",
           "avatar",
           "is_external",
-          "created_at"
-        ],
-        "type": "object"
+          "created_at",
+          "time_zone",
+          "account_time_zone",
+          "resolved_time_zone"
+        ]
       },
       "MemberInviteRequest": {
         "description": "Invite members request",
@@ -16002,187 +16419,190 @@
         "type": "object"
       },
       "MemberInviteResponse": {
+        "type": "object",
         "description": "Invite members response",
         "properties": {
           "items": {
-            "description": "Newly created members",
+            "type": [
+              "array",
+              "null"
+            ],
             "items": {
               "$ref": "#/components/schemas/NewMemberItem"
             },
-            "type": "array"
+            "description": "Members created by this call; entries skipped because they already exist are not listed. `null` when no member was created."
           }
-        },
-        "type": "object"
+        }
       },
       "MemberItem": {
+        "type": "object",
         "description": "Member item",
+        "required": [
+          "account_id",
+          "member_id",
+          "member_name",
+          "country_code",
+          "phone",
+          "email",
+          "phone_verified",
+          "email_verified",
+          "avatar",
+          "status",
+          "account_role_ids",
+          "created_at",
+          "updated_at",
+          "ref_id",
+          "is_external"
+        ],
         "properties": {
           "account_id": {
-            "description": "Account ID",
+            "type": "integer",
             "format": "uint64",
-            "type": "integer"
+            "description": "ID of the account the member belongs to."
           },
-          "account_role_ids": {
-            "description": "Role IDs",
-            "items": {
-              "format": "uint64",
-              "type": "integer"
-            },
-            "type": "array"
+          "member_id": {
+            "type": "integer",
+            "format": "uint64",
+            "description": "Member ID; the same value is used as the person ID in other APIs (for example `person_ids`)."
           },
-          "avatar": {
-            "description": "Avatar URL",
-            "type": "string"
+          "member_name": {
+            "type": "string",
+            "description": "Display name, unique in the account."
           },
           "country_code": {
-            "description": "ISO 3166-1 alpha-2 region code of the member's contact phone (e.g. \"CN\", \"US\", \"HK\").",
-            "type": "string"
+            "type": "string",
+            "description": "ISO 3166-1 alpha-2 region code of the member's contact phone (e.g. \"CN\", \"US\", \"HK\")."
           },
-          "created_at": {
-            "description": "Creation timestamp (Unix seconds)",
-            "format": "int64",
-            "type": "integer"
+          "phone": {
+            "type": "string",
+            "description": "Phone number in E.164 form with the middle digits masked (for example `+86151****6519`); empty string when unset."
           },
           "email": {
-            "description": "Email address",
-            "type": "string"
-          },
-          "email_verified": {
-            "description": "Email verified",
-            "type": "boolean"
-          },
-          "is_external": {
-            "description": "Provisioned via SSO",
-            "type": "boolean"
+            "type": "string",
+            "description": "Email address in lower case; empty string when unset."
           },
           "locale": {
-            "description": "Member's locale preference (e.g. `zh-CN`). Omitted when empty — the list endpoint does not populate it.",
-            "type": "string"
-          },
-          "member_id": {
-            "description": "Member ID",
-            "format": "uint64",
-            "type": "integer"
-          },
-          "member_name": {
-            "description": "Display name",
-            "type": "string"
+            "type": "string",
+            "description": "Locale preference. Not populated by `POST /member/list`, so it is always omitted there."
           },
-          "phone": {
-            "description": "Masked phone number",
-            "type": "string"
+          "time_zone": {
+            "type": "string",
+            "description": "The member's own IANA time zone setting (for example `Asia/Shanghai`). Omitted when unset, which means the member follows the account's time zone; `POST /member/info` returns the effective zone."
           },
           "phone_verified": {
-            "description": "Phone verified",
-            "type": "boolean"
+            "type": "boolean",
+            "description": "`true` once the member has verified the phone number."
           },
-          "ref_id": {
-            "description": "External reference ID",
-            "type": "string"
+          "email_verified": {
+            "type": "boolean",
+            "description": "`true` once the member has verified the email address."
+          },
+          "avatar": {
+            "type": "string",
+            "description": "Avatar image URL or path; empty string when unset."
           },
           "status": {
-            "description": "Member status. `enabled` — active member; `pending` — invited but not yet accepted; `deleted` — removed from the organization.",
+            "type": "string",
             "enum": [
               "enabled",
-              "pending",
-              "deleted"
+              "pending"
             ],
-            "type": "string"
+            "description": "Member status. `enabled` — active member; `pending` — invited but has not accepted yet. Removed members are not listed."
           },
-          "time_zone": {
-            "description": "Member's IANA time zone (e.g. `Asia/Shanghai`). Omitted when empty — the list endpoint does not populate it.",
-            "type": "string"
+          "account_role_ids": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "uint64"
+            },
+            "description": "IDs of the roles assigned to the member: built-in `2` (Admin), `6` (Responder), `8` (Viewer), or custom role IDs from `POST /role/list`."
+          },
+          "is_external": {
+            "type": "boolean",
+            "description": "`true` when the member was provisioned through SSO rather than invited or registered."
+          },
+          "ref_id": {
+            "type": "string",
+            "description": "External reference ID (for example an employee ID in an HR system); empty string when unset."
+          },
+          "created_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Creation timestamp (Unix seconds)"
           },
           "updated_at": {
-            "description": "Update timestamp (Unix seconds)",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Update timestamp (Unix seconds)"
           }
-        },
-        "required": [
-          "account_id",
-          "member_id",
-          "member_name",
-          "country_code",
-          "phone",
-          "email",
-          "phone_verified",
-          "email_verified",
-          "avatar",
-          "status",
-          "account_role_ids",
-          "created_at",
-          "updated_at",
-          "ref_id",
-          "is_external"
-        ],
-        "type": "object"
+        }
       },
       "MemberListRequest": {
+        "type": "object",
         "description": "List members request",
         "properties": {
-          "asc": {
-            "description": "Ascending order. Default: false (descending)",
-            "type": "boolean"
-          },
-          "limit": {
-            "default": 100,
-            "description": "Page size. Defaults to 100 on the server when omitted or 0",
-            "maximum": 100,
-            "minimum": 1,
-            "type": "integer"
+          "role_id": {
+            "type": "integer",
+            "format": "uint64",
+            "description": "Filter by role ID. Get role IDs from `POST /role/list` (built-in roles: 2=Admin, 6=Responder, 8=Viewer)"
           },
           "member_id": {
-            "description": "Filter by member ID. Return only the member with this ID.",
+            "type": "integer",
             "format": "uint64",
-            "type": "integer"
+            "description": "Filter by member ID. Return only the member with this ID."
+          },
+          "p": {
+            "type": "integer",
+            "minimum": 1,
+            "description": "Page number, starting at 1. Defaults to the first page."
+          },
+          "limit": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 100,
+            "description": "Page size. Defaults to 100 on the server when omitted or 0",
+            "default": 100
           },
           "orderby": {
-            "description": "Sort field. Default: `updated_at`",
+            "type": "string",
             "enum": [
               "created_at",
               "updated_at"
             ],
-            "type": "string"
+            "description": "Sort field. Default: `updated_at`"
           },
-          "p": {
-            "description": "Page number, 1-based",
-            "minimum": 1,
-            "type": "integer"
+          "asc": {
+            "type": "boolean",
+            "description": "Ascending order. Default: false (descending)"
           },
           "query": {
-            "description": "Substring match on member name or email; if the keyword parses as a phone number, an exact phone match is also applied",
-            "type": "string"
-          },
-          "role_id": {
-            "description": "Filter by role ID. Get role IDs from `POST /role/list` (built-in roles: 2=Admin, 6=Responder, 8=Viewer)",
-            "format": "uint64",
-            "type": "integer"
+            "type": "string",
+            "description": "Keyword. Matches a substring of the member name or email; a numeric keyword also matches an exact member ID, and a keyword that parses as a phone number (without `+`, parsed as a Chinese number) also matches the exact phone."
           }
-        },
-        "type": "object"
+        }
       },
       "MemberListResponse": {
+        "type": "object",
         "description": "Member list response",
         "properties": {
-          "items": {
-            "description": "Member items",
-            "items": {
-              "$ref": "#/components/schemas/MemberItem"
-            },
-            "type": "array"
+          "p": {
+            "type": "integer",
+            "description": "Page number from the request; `0` when `p` was omitted (the first page is returned)."
           },
           "limit": {
-            "description": "Page size",
-            "type": "integer"
-          },
-          "p": {
-            "description": "Current page",
-            "type": "integer"
+            "type": "integer",
+            "description": "Page size applied; 100 when `limit` was omitted."
           },
           "total": {
-            "description": "Total count",
-            "type": "integer"
+            "type": "integer",
+            "description": "Number of members matching the filters, across all pages."
+          },
+          "items": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/MemberItem"
+            },
+            "description": "Members on this page; empty array when none match."
           }
         },
         "required": [
@@ -16190,33 +16610,32 @@
           "limit",
           "total",
           "items"
-        ],
-        "type": "object"
+        ]
       },
       "MemberOncallInterval": {
+        "type": "object",
         "description": "One on-call shift interval of a member.",
         "properties": {
-          "end_at": {
-            "description": "Unix timestamp in seconds - when the shift ends. Absent while the shift is ongoing.",
-            "format": "int64",
-            "type": "integer"
-          },
           "schedule_id": {
+            "type": "integer",
             "description": "Owning schedule ID.",
-            "format": "int64",
-            "type": "integer"
+            "format": "int64"
           },
           "schedule_name": {
-            "description": "Owning schedule name.",
-            "type": "string"
+            "type": "string",
+            "description": "Owning schedule name."
           },
           "start_at": {
+            "type": "integer",
             "description": "Unix timestamp in seconds - when the shift starts.",
-            "format": "int64",
-            "type": "integer"
+            "format": "int64"
+          },
+          "end_at": {
+            "type": "integer",
+            "description": "Unix timestamp in seconds when the shift ends. Present on `current`; omitted on `next`.",
+            "format": "int64"
           }
-        },
-        "type": "object"
+        }
       },
       "MemberResetInfoRequest": {
         "anyOf": [
@@ -16288,397 +16707,397 @@
         "type": "object"
       },
       "MemberResetInfoUpdates": {
+        "type": "object",
         "description": "Member profile fields to write. Omitted fields remain unchanged.",
         "properties": {
-          "avatar": {
-            "description": "New avatar URL.",
-            "maxLength": 499,
+          "member_name": {
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "minLength": 2,
+            "maxLength": 39,
+            "description": "New display name, 2–39 characters, unique in the account."
           },
-          "country_code": {
-            "description": "ISO 3166-1 alpha-2 region code (e.g. \"CN\", \"US\"). Updated independently — `phone` is not required — and also used as the parsing hint for `phone`. Invalid values are rejected with a 400; an explicit empty string is not allowed.",
+          "password": {
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "New login password in the encrypted format accepted by the backend."
           },
-          "email": {
-            "description": "New email address.",
+          "phone": {
             "type": [
               "string",
               "null"
-            ]
-          },
-          "locale": {
-            "description": "New locale preference. One of: `zh-CN` (Simplified Chinese), `en-US` (English); other values are rejected with a 400.",
-            "enum": [
-              "zh-CN",
-              "en-US"
             ],
+            "description": "New phone number; include `country_code` when it is not in E.164 format. Must not belong to another member; the new number is marked unverified (see `from`)."
+          },
+          "country_code": {
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "ISO 3166-1 alpha-2 region code (e.g. \"CN\", \"US\"). Updated independently — `phone` is not required — and also used as the parsing hint for `phone`. Invalid values are rejected with a 400; an explicit empty string is not allowed."
           },
-          "member_name": {
-            "description": "New display name.",
-            "maxLength": 39,
-            "minLength": 2,
+          "email": {
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "New email address. Must not belong to another member; the new address is marked unverified (see `from`)."
           },
-          "password": {
-            "description": "New login password in the encrypted format accepted by the backend.",
+          "avatar": {
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "maxLength": 499,
+            "description": "New avatar URL."
           },
-          "phone": {
-            "description": "New phone number. Include country_code when the number is not in E.164 format.",
+          "locale": {
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "enum": [
+              "zh-CN",
+              "en-US"
+            ],
+            "description": "New locale preference. One of: `zh-CN` (Simplified Chinese), `en-US` (English); other values are rejected with a 400."
           },
-          "ref_id": {
-            "description": "New external reference ID.",
+          "time_zone": {
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "New IANA time zone name such as `Asia/Shanghai`; an empty string clears it so the member follows the account's time zone. An invalid name returns `400`."
           },
-          "time_zone": {
-            "description": "New IANA time zone name, such as Asia/Shanghai.",
+          "ref_id": {
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "New external reference ID; an empty string clears it."
           }
-        },
-        "type": "object"
+        }
       },
       "MemberRoleGrantRequest": {
+        "type": "object",
         "description": "Grant role to member request",
+        "required": [
+          "member_id",
+          "role_ids"
+        ],
         "properties": {
           "member_id": {
-            "description": "Member ID",
+            "type": "integer",
             "format": "uint64",
-            "type": "integer"
+            "description": "ID of the member whose roles change (from `POST /member/list`)."
           },
           "role_ids": {
-            "description": "Role IDs to grant; appended to the member's current roles (duplicates are deduplicated).",
+            "type": "array",
             "items": {
-              "format": "uint64",
-              "type": "integer"
+              "type": "integer",
+              "format": "uint64"
             },
-            "type": "array"
+            "description": "Role IDs to grant; appended to the member's current roles (duplicates are deduplicated)."
           }
-        },
+        }
+      },
+      "MemberRoleRevokeRequest": {
+        "type": "object",
+        "description": "Revoke role from member request",
         "required": [
           "member_id",
           "role_ids"
         ],
-        "type": "object"
-      },
-      "MemberRoleRevokeRequest": {
-        "description": "Revoke role from member request",
         "properties": {
           "member_id": {
-            "description": "Member ID",
+            "type": "integer",
             "format": "uint64",
-            "type": "integer"
+            "description": "ID of the member whose roles change (from `POST /member/list`)."
           },
           "role_ids": {
-            "description": "Role IDs to remove from the member.",
+            "type": "array",
             "items": {
-              "format": "uint64",
-              "type": "integer"
+              "type": "integer",
+              "format": "uint64"
             },
-            "type": "array"
+            "description": "Role IDs to remove from the member."
           }
-        },
-        "required": [
-          "member_id",
-          "role_ids"
-        ],
-        "type": "object"
+        }
       },
       "MemberRoleUpdateRequest": {
+        "type": "object",
         "description": "Update member roles request",
+        "required": [
+          "member_id"
+        ],
         "properties": {
           "member_id": {
-            "description": "Member ID",
+            "type": "integer",
             "format": "uint64",
-            "type": "integer"
+            "description": "ID of the member whose roles change (from `POST /member/list`)."
           },
           "role_ids": {
-            "description": "New role ID set. Replaces the member's existing roles entirely (not additive); get IDs from `POST /role/list`. Leave empty to reset to the built-in Viewer role (ID 8)",
+            "type": "array",
             "items": {
-              "format": "uint64",
-              "type": "integer"
+              "type": "integer",
+              "format": "uint64"
             },
-            "type": "array"
+            "description": "New role ID set; replaces the member's existing roles entirely (not additive). Get IDs from `POST /role/list`."
           }
-        },
-        "required": [
-          "member_id"
-        ],
-        "type": "object"
+        }
       },
       "MemberScheduleItem": {
+        "type": "object",
         "description": "An enabled schedule the member participates in.",
         "properties": {
           "schedule_id": {
-            "description": "Schedule ID.",
-            "format": "int64",
-            "type": "integer"
+            "type": "integer",
+            "description": "ID of a schedule the member participates in; pass it to `/schedule/info`.",
+            "format": "int64"
           },
           "schedule_name": {
-            "description": "Schedule name.",
-            "type": "string"
+            "type": "string",
+            "description": "Name of that schedule."
           }
-        },
-        "type": "object"
+        }
       },
       "MergeIncidentsRequest": {
+        "type": "object",
         "description": "Parameters for merging source incidents into a target.",
+        "required": [
+          "source_incident_ids",
+          "target_incident_id"
+        ],
         "properties": {
-          "comment": {
-            "description": "Optional comment recorded on the merge timeline entry.",
-            "maxLength": 1024,
-            "type": "string"
-          },
-          "owner_id": {
-            "description": "Accepted for compatibility but currently ignored by the server; the merge does not change the target incident owner.",
-            "format": "int64",
-            "type": "integer"
-          },
-          "remove_source_incidents": {
-            "description": "When true, soft-delete the source incidents after merging instead of closing them.",
-            "type": "boolean"
-          },
           "source_incident_ids": {
-            "description": "Source incident IDs. The target incident is removed from this set automatically.",
+            "type": "array",
             "items": {
-              "pattern": "^[0-9a-fA-F]{24}$",
-              "type": "string"
+              "type": "string",
+              "pattern": "^[0-9a-fA-F]{24}$"
             },
-            "maxItems": 100,
             "minItems": 1,
-            "type": "array"
+            "maxItems": 100,
+            "description": "Source incident IDs. The target incident is removed from this set automatically."
           },
           "target_incident_id": {
-            "description": "Target incident ID of the merge; obtain it from `POST /incident/list`.",
+            "type": "string",
             "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
+            "description": "Target incident ID of the merge; obtain it from `POST /incident/list`."
           },
           "title": {
-            "description": "Optional new title for the target incident.",
+            "type": "string",
             "maxLength": 512,
-            "type": "string"
+            "description": "Optional new title for the target incident."
+          },
+          "comment": {
+            "type": "string",
+            "maxLength": 1024,
+            "description": "Optional comment recorded on the merge timeline entry."
+          },
+          "owner_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Accepted for compatibility but currently ignored by the server; the merge does not change the target incident owner."
+          },
+          "remove_source_incidents": {
+            "type": "boolean",
+            "description": "When true, permanently delete the source incidents after their alerts move to the target. When false, the sources are closed and kept."
           }
-        },
-        "required": [
-          "source_incident_ids",
-          "target_incident_id"
-        ],
-        "type": "object"
+        }
       },
       "MetricsBase": {
+        "type": "object",
         "description": "Shared dimension identifiers attached to every aggregated insight row.",
         "properties": {
-          "channel_id": {
-            "description": "Channel ID, returned only when aggregating by channel (`/insight/channel`).",
-            "format": "int64",
-            "type": "integer"
-          },
-          "channel_name": {
-            "description": "Channel name, returned when aggregating by channel; omitted when the name cannot be resolved.",
-            "type": "string"
-          },
           "hours": {
-            "description": "Hour bucket when `split_hours` is enabled. `work` is Mon–Fri 08:00–19:00, `sleep` is daily 23:00–08:00, and `off` is everything else, all evaluated in the account timezone (`sleep` takes precedence over `work`). Omitted when `split_hours` is false.",
+            "type": "string",
             "enum": [
               "work",
               "sleep",
               "off"
             ],
-            "type": "string"
+            "description": "Hour bucket when `split_hours` is enabled. `work` is Mon–Fri 08:00–19:00, `sleep` is daily 23:00–08:00, and `off` is everything else, all evaluated in the account timezone (`sleep` takes precedence over `work`). Omitted when `split_hours` is false."
           },
-          "responder_id": {
-            "description": "Responder (person) ID, returned only when aggregating by responder (`/insight/responder`).",
+          "ts": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Start of the time bucket, Unix seconds. Equals `start_time` when `aggregate_unit` is not set."
           },
-          "responder_name": {
-            "description": "Responder name, returned when aggregating by responder; omitted when the name cannot be resolved.",
-            "type": "string"
+          "channel_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Channel ID, returned only when aggregating by channel (`/insight/channel`)."
           },
           "team_id": {
-            "description": "Team ID, returned only when aggregating by team (`/insight/team`).",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Team ID, returned only by `/insight/team`. Omitted on the row that aggregates incidents without a team."
+          },
+          "responder_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Responder (person) ID, returned only when aggregating by responder (`/insight/responder`)."
           },
           "team_name": {
-            "description": "Team name, returned when aggregating by team; omitted when the name cannot be resolved (e.g. team deleted).",
-            "type": "string"
+            "type": "string",
+            "description": "Team name, returned when aggregating by team; omitted when the name cannot be resolved (e.g. team deleted)."
           },
-          "ts": {
-            "description": "Start of the aggregation bucket, Unix epoch seconds. Equals `start_time` when no `aggregate_unit` is given.",
-            "format": "int64",
-            "type": "integer"
+          "channel_name": {
+            "type": "string",
+            "description": "Channel name, returned when aggregating by channel; omitted when the name cannot be resolved."
+          },
+          "responder_name": {
+            "type": "string",
+            "description": "Responder name, returned when aggregating by responder; omitted when the name cannot be resolved."
           }
-        },
-        "type": "object"
+        }
       },
       "MigrateStatusPageEmailSubscribersRequest": {
+        "type": "object",
         "description": "Parameters for starting an Atlassian Statuspage email subscriber migration job.",
+        "required": [
+          "api_key",
+          "source_page_id",
+          "target_page_id"
+        ],
         "properties": {
           "api_key": {
-            "description": "Atlassian Statuspage API key with access to the source page.",
-            "type": "string"
+            "type": "string",
+            "description": "Atlassian Statuspage API key with access to the source page."
           },
           "source_page_id": {
-            "description": "Atlassian Statuspage source page ID.",
-            "type": "string"
+            "type": "string",
+            "description": "Atlassian Statuspage source page ID; only letters, digits, `_`, and `-` are accepted."
           },
           "target_page_id": {
-            "description": "Flashduty target status page ID that will receive the imported subscribers.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Flashduty target status page ID that will receive the imported subscribers."
           }
-        },
-        "required": [
-          "api_key",
-          "source_page_id",
-          "target_page_id"
-        ],
-        "type": "object"
+        }
       },
       "MigrateStatusPageStructureRequest": {
+        "type": "object",
         "description": "Parameters for starting an Atlassian Statuspage structure and history migration job.",
+        "required": [
+          "api_key",
+          "source_page_id"
+        ],
         "properties": {
           "api_key": {
-            "description": "Atlassian Statuspage API key with access to the source page.",
-            "type": "string"
+            "type": "string",
+            "description": "Atlassian Statuspage API key with access to the source page."
           },
           "source_page_id": {
-            "description": "Atlassian Statuspage source page ID.",
-            "type": "string"
+            "type": "string",
+            "description": "Atlassian Statuspage source page ID; only letters, digits, `_`, and `-` are accepted."
           },
           "url_name": {
-            "description": "Target URL name for the new status page, normalized to a URL-safe slug (max 255 characters). Omit or pass null to derive it from the source page name; an explicitly empty string is rejected.",
-            "maxLength": 255,
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "Target URL name for the new status page, normalized to a URL-safe slug (max 255 characters). Omit or pass null to derive it from the source page name; an explicitly empty string is rejected.",
+            "maxLength": 255
           }
-        },
-        "required": [
-          "api_key",
-          "source_page_id"
-        ],
-        "type": "object"
+        }
       },
       "NameMessage": {
+        "type": "object",
         "description": "Per-item result for batch rule operations.",
-        "properties": {
-          "message": {
-            "description": "Empty on success, error message on failure.",
-            "type": "string"
-          },
-          "name": {
-            "description": "Rule name.",
-            "type": "string"
-          }
-        },
         "required": [
           "name",
           "message"
         ],
-        "type": "object"
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "Name of the rule this result belongs to; `id: <id>` when the rule ID does not exist."
+          },
+          "message": {
+            "type": "string",
+            "description": "Outcome for this rule. On success it is empty for `/monit/rule/update/fields` and a localized success text (`Move successfully` / `移动成功`) for `/monit/rule/move`; on failure it carries the error message."
+          }
+        }
       },
       "NewMemberItem": {
+        "type": "object",
         "description": "Newly created member",
         "properties": {
           "member_id": {
-            "description": "Member ID",
+            "type": "integer",
             "format": "uint64",
-            "type": "integer"
+            "description": "ID of the newly created member."
           },
           "member_name": {
-            "description": "Member display name",
-            "type": "string"
+            "type": "string",
+            "description": "Display name stored for the member; derived from the email prefix when `member_name` was omitted."
           }
-        },
-        "type": "object"
+        }
       },
       "NotifyChat": {
+        "type": "object",
         "description": "Notification delivery record for a chat group recipient.",
         "properties": {
+          "data_source_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Integration data source ID used to send the notification."
+          },
           "chat_id": {
-            "description": "Chat group identifier.",
-            "type": "string"
+            "type": "string",
+            "description": "Chat group identifier."
           },
           "chat_name": {
-            "description": "Chat group display name.",
-            "type": "string"
-          },
-          "data_source_id": {
-            "description": "Integration data source ID used to send the notification.",
-            "format": "int64",
-            "type": "integer"
+            "type": "string",
+            "description": "Chat group display name."
           },
           "failed_reason": {
-            "description": "Failure reason if delivery did not succeed.",
-            "type": "string"
+            "type": "string",
+            "description": "Localized, human-readable reason the delivery failed, as reported by the delivery channel; omitted when delivery succeeded or no failure was reported. The text is not a fixed code set."
           }
-        },
-        "type": "object"
+        }
       },
       "NotifyPerson": {
+        "type": "object",
         "description": "Notification delivery record for a single person recipient.",
         "properties": {
-          "failed_reason": {
-            "description": "Failure reason if delivery did not succeed.",
-            "type": "string"
-          },
           "person_id": {
-            "description": "Recipient member ID.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Recipient member ID."
+          },
+          "failed_reason": {
+            "type": "string",
+            "description": "Localized, human-readable reason the delivery failed, as reported by the delivery channel; omitted when delivery succeeded or no failure was reported. The text is not a fixed code set."
           },
           "sms_content": {
-            "description": "SMS text delivered to the recipient; present on SMS deliveries.",
-            "type": "string"
+            "type": "string",
+            "description": "SMS text delivered to the recipient; present on SMS deliveries."
           }
-        },
-        "type": "object"
+        }
       },
       "NotifyRobot": {
+        "type": "object",
         "description": "Notification delivery record for a robot webhook recipient.",
         "properties": {
+          "token": {
+            "type": "string",
+            "description": "Robot token or identifier."
+          },
           "alias": {
-            "description": "Robot alias.",
-            "type": "string"
+            "type": "string",
+            "description": "Robot alias."
           },
           "failed_reason": {
-            "description": "Failure reason if delivery did not succeed.",
-            "type": "string"
-          },
-          "token": {
-            "description": "Robot token or identifier.",
-            "type": "string"
+            "type": "string",
+            "description": "Localized, human-readable reason the delivery failed, as reported by the delivery channel; omitted when delivery succeeded or no failure was reported. The text is not a fixed code set."
           }
-        },
-        "type": "object"
+        }
       },
       "OnceTimeFilter": {
         "description": "One-off time window defined by unix seconds.",
@@ -16915,99 +17334,99 @@
         "type": "object"
       },
       "PersonItem": {
+        "type": "object",
         "description": "Person profile",
+        "required": [
+          "account_id",
+          "person_id",
+          "phone_verified",
+          "email_verified"
+        ],
         "properties": {
           "account_id": {
-            "description": "Account ID",
+            "type": "integer",
             "format": "uint64",
-            "type": "integer"
-          },
-          "as": {
-            "description": "Principal kind: `account` — the account owner principal; `member` — an organization member.",
-            "enum": [
-              "account",
-              "member"
-            ],
-            "type": "string"
+            "description": "ID of the account the person belongs to."
           },
-          "avatar": {
-            "description": "Avatar URL. Omitted when empty.",
-            "type": "string"
+          "person_id": {
+            "type": "integer",
+            "format": "uint64",
+            "description": "Person ID: the account ID for the account owner, otherwise the member ID."
           },
-          "email": {
-            "description": "Email address. Omitted when empty.",
-            "type": "string"
+          "person_name": {
+            "type": "string",
+            "description": "Display name. Omitted when empty."
           },
-          "email_verified": {
-            "description": "Email verified",
-            "type": "boolean"
+          "avatar": {
+            "type": "string",
+            "description": "Avatar URL. Omitted when empty."
           },
           "locale": {
-            "description": "Locale. Omitted when empty.",
-            "type": "string"
+            "type": "string",
+            "description": "Locale preference (`zh-CN` or `en-US`). Omitted when unset."
           },
-          "person_id": {
-            "description": "Person ID",
-            "format": "uint64",
-            "type": "integer"
+          "time_zone": {
+            "type": "string",
+            "description": "IANA time zone setting: the member's own setting, or the account's for the account owner. Omitted when unset (a member without a setting follows the account's time zone)."
           },
-          "person_name": {
-            "description": "Display name. Omitted when empty.",
-            "type": "string"
+          "email": {
+            "type": "string",
+            "description": "Email address. Omitted when empty."
           },
           "phone": {
-            "description": "Phone number. Omitted when empty — this endpoint never populates it.",
-            "type": "string"
+            "type": "string",
+            "description": "Phone number. Omitted when empty — this endpoint never populates it."
           },
           "phone_verified": {
-            "description": "Whether the phone is verified. Always false in this endpoint's response.",
-            "type": "boolean"
+            "type": "boolean",
+            "description": "Whether the phone is verified. Always false in this endpoint's response."
+          },
+          "email_verified": {
+            "type": "boolean",
+            "description": "`true` when the email address is verified; for the account owner, `true` whenever an email is set."
+          },
+          "as": {
+            "type": "string",
+            "description": "Principal kind: `account` — the account owner principal; `member` — an organization member.",
+            "enum": [
+              "account",
+              "member"
+            ]
           },
           "status": {
-            "description": "Person status. `enabled` — active; `pending` — invited but not yet accepted; `deleted` — removed. Omitted when empty.",
+            "type": "string",
             "enum": [
               "enabled",
               "pending",
               "deleted"
             ],
-            "type": "string"
-          },
-          "time_zone": {
-            "description": "Time zone. Omitted when empty.",
-            "type": "string"
+            "description": "Person status. `enabled` — active; `pending` — invited but not yet accepted; `deleted` — removed. Omitted when empty."
           }
-        },
-        "required": [
-          "account_id",
-          "person_id",
-          "phone_verified",
-          "email_verified"
-        ],
-        "type": "object"
+        }
       },
       "PersonShort": {
+        "type": "object",
         "description": "A Flashduty member reference.",
         "properties": {
-          "as": {
-            "description": "Role label for this member in the context of the current object.",
-            "type": "string"
-          },
-          "email": {
-            "description": "Member email address.",
-            "format": "email",
-            "type": "string"
-          },
           "person_id": {
-            "description": "Member ID.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Member ID; the same ID that `POST /member/list` returns."
           },
           "person_name": {
-            "description": "Member display name.",
-            "type": "string"
+            "type": "string",
+            "description": "Member display name."
+          },
+          "email": {
+            "type": "string",
+            "format": "email",
+            "description": "Member email address."
+          },
+          "as": {
+            "type": "string",
+            "description": "Role label for this member in the context of the current object."
           }
-        },
-        "type": "object"
+        }
       },
       "PlatformEmptyObject": {
         "additionalProperties": false,
@@ -17063,281 +17482,293 @@
         "type": "object"
       },
       "PostMortemItem": {
+        "type": "object",
         "description": "Full post-mortem report including basics, content and follow-ups.",
+        "required": [
+          "meta",
+          "basics",
+          "content",
+          "follow_ups",
+          "has_active_incident"
+        ],
         "properties": {
+          "meta": {
+            "$ref": "#/components/schemas/PostMortemMeta"
+          },
           "basics": {
-            "description": "Basics aggregated automatically from the linked incidents: highest severity, earliest start / latest close time, total duration, and responders.",
+            "type": "object",
+            "required": [
+              "incidents_highest_severity",
+              "incidents_earliest_start_seconds",
+              "incidents_latest_close_seconds",
+              "incidents_total_duration_seconds",
+              "responders"
+            ],
             "properties": {
+              "incidents_highest_severity": {
+                "type": "string",
+                "description": "Highest severity among linked incidents: `Critical`, `Warning`, or `Info`; `Ok` only when it was set manually.",
+                "enum": [
+                  "Critical",
+                  "Warning",
+                  "Info",
+                  "Ok"
+                ]
+              },
               "incidents_earliest_start_seconds": {
-                "description": "Earliest start time among linked incidents (seconds).",
+                "type": "integer",
                 "format": "int64",
-                "type": "integer"
-              },
-              "incidents_highest_severity": {
-                "description": "Highest severity among linked incidents.",
-                "type": "string"
+                "description": "Earliest start time among linked incidents (Unix seconds)."
               },
               "incidents_latest_close_seconds": {
-                "description": "Latest close time among linked incidents (seconds).",
+                "type": "integer",
                 "format": "int64",
-                "type": "integer"
+                "description": "Latest close time among linked incidents (Unix seconds); an incident not yet closed contributes its `end_time`."
               },
               "incidents_total_duration_seconds": {
-                "description": "Cumulative duration in seconds.",
+                "type": "integer",
                 "format": "int64",
-                "type": "integer"
+                "description": "Seconds from the earliest start to the latest close among linked incidents (not the sum of each incident's duration)."
               },
               "responders": {
-                "description": "Responders involved in the incident(s).",
+                "type": "array",
                 "items": {
                   "$ref": "#/components/schemas/Responder"
                 },
-                "type": "array"
+                "description": "Responders involved in the incident(s)."
               }
             },
-            "required": [
-              "incidents_highest_severity",
-              "incidents_earliest_start_seconds",
-              "incidents_latest_close_seconds",
-              "incidents_total_duration_seconds",
-              "responders"
-            ],
-            "type": "object"
+            "description": "Basics aggregated automatically from the linked incidents: highest severity, earliest start / latest close time, total duration, and responders."
           },
           "content": {
-            "description": "Post-mortem body; the object holds a single `content` field whose value is a BlockNote JSON string.",
+            "type": "object",
+            "required": [
+              "content"
+            ],
             "properties": {
               "content": {
-                "description": "Report body content (BlockNote JSON).",
-                "type": "string"
+                "type": "string",
+                "description": "Report body content (BlockNote JSON)."
               }
             },
-            "required": [
-              "content"
-            ],
-            "type": "object"
+            "description": "Post-mortem body; the object holds a single `content` field whose value is a BlockNote JSON string."
           },
           "follow_ups": {
-            "description": "Follow-up action items rendered as a single string.",
-            "type": "string"
+            "type": "string",
+            "description": "Follow-up action items rendered as a single string."
           },
-          "meta": {
-            "$ref": "#/components/schemas/PostMortemMeta"
+          "has_active_incident": {
+            "type": "boolean",
+            "description": "`true` when at least one linked incident is not closed yet; follow-ups stay locked until all are closed. Computed per request."
           }
-        },
-        "required": [
-          "meta",
-          "basics",
-          "content",
-          "follow_ups"
-        ],
-        "type": "object"
+        }
       },
       "PostMortemMeta": {
+        "type": "object",
         "description": "Post-mortem metadata (lightweight shape used in lists).",
+        "required": [
+          "account_id",
+          "title",
+          "status",
+          "post_mortem_id",
+          "template_id",
+          "incident_ids",
+          "media_count",
+          "author_ids",
+          "team_id",
+          "channel_id",
+          "is_private",
+          "generation",
+          "revision",
+          "channel_name",
+          "created_at_seconds",
+          "updated_at_seconds"
+        ],
         "properties": {
           "account_id": {
-            "description": "Account ID.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "ID of the account that owns this record; the same for every record returned to one `app_key`."
           },
-          "author_ids": {
-            "description": "Member IDs that contributed to the report.",
-            "items": {
-              "format": "int64",
-              "type": "integer"
-            },
-            "type": "array"
-          },
-          "channel_id": {
-            "description": "Owning channel ID. 0 if none.",
-            "format": "int64",
-            "type": "integer"
+          "title": {
+            "type": "string",
+            "description": "Report title."
           },
-          "channel_name": {
-            "description": "Channel name, filled by the server.",
-            "type": "string"
+          "status": {
+            "type": "string",
+            "enum": [
+              "drafting",
+              "published"
+            ],
+            "description": "Post-mortem status. `drafting` means still being edited; `published` means published."
           },
-          "created_at_seconds": {
-            "description": "Creation timestamp (seconds).",
-            "format": "int64",
-            "type": "integer"
+          "post_mortem_id": {
+            "type": "string",
+            "description": "Post-mortem ID: a 32-character hex string derived from the account ID and the linked incident IDs."
           },
-          "generation": {
-            "description": "Collaboration document generation. Incremented by each full content reset; 0 for legacy documents.",
-            "format": "int64",
-            "type": "integer"
+          "template_id": {
+            "type": "string",
+            "description": "Template used to initialize the report."
           },
           "incident_ids": {
-            "description": "Linked incident IDs.",
+            "type": "array",
             "items": {
               "type": "string"
             },
-            "type": "array"
-          },
-          "is_private": {
-            "description": "When true, only team members and admins can view.",
-            "type": "boolean"
+            "description": "Linked incident IDs."
           },
           "media_count": {
-            "description": "Number of uploaded media files.",
-            "type": "integer"
+            "type": "integer",
+            "description": "Number of uploaded media files."
           },
-          "post_mortem_id": {
-            "description": "Deterministic post-mortem ID derived from account and incident IDs.",
-            "type": "string"
+          "author_ids": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "int64"
+            },
+            "description": "Member IDs that contributed to the report."
           },
-          "revision": {
-            "description": "Content revision for optimistic concurrency. Monotonically increases on collaborative saves and full content resets.",
+          "team_id": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Owning team ID. 0 if none."
           },
-          "status": {
-            "description": "Post-mortem status. `drafting` means still being edited; `published` means published.",
-            "enum": [
-              "drafting",
-              "published"
-            ],
-            "type": "string"
+          "channel_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Owning channel ID. 0 if none."
           },
-          "team_id": {
-            "description": "Owning team ID. 0 if none.",
+          "is_private": {
+            "type": "boolean",
+            "description": "When true, only team members and admins can view."
+          },
+          "generation": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Collaboration document generation. Incremented by each full content reset; 0 for legacy documents."
           },
-          "template_id": {
-            "description": "Template used to initialize the report.",
-            "type": "string"
+          "revision": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Content revision for optimistic concurrency. Monotonically increases on collaborative saves and full content resets."
           },
-          "title": {
-            "description": "Report title.",
-            "type": "string"
+          "channel_name": {
+            "type": "string",
+            "description": "Channel name, filled by the server."
+          },
+          "created_at_seconds": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Creation timestamp (seconds)."
           },
           "updated_at_seconds": {
-            "description": "Last update timestamp (seconds).",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Last update timestamp (seconds)."
           }
-        },
+        }
+      },
+      "PostMortemTemplate": {
+        "type": "object",
+        "description": "Post-mortem report template.",
         "required": [
           "account_id",
-          "title",
-          "status",
-          "post_mortem_id",
           "template_id",
-          "incident_ids",
-          "media_count",
-          "author_ids",
+          "name",
+          "description",
+          "content",
+          "content_markdown",
           "team_id",
-          "channel_id",
-          "is_private",
-          "generation",
-          "revision",
-          "channel_name",
           "created_at_seconds",
           "updated_at_seconds"
         ],
-        "type": "object"
-      },
-      "PostMortemTemplate": {
-        "description": "Post-mortem report template.",
         "properties": {
           "account_id": {
-            "description": "Account ID that owns the template. 0 for built-in templates.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
-          },
-          "content": {
-            "description": "BlockNote JSON content used to initialize the report body.",
-            "type": "string"
+            "description": "Account ID that owns the template; 0 for the built-in template."
           },
-          "content_markdown": {
-            "description": "Markdown version of the template content, used by AI generation.",
-            "type": "string"
+          "template_id": {
+            "type": "string",
+            "description": "Template ID: `post_mortem_default_tmpl_zh-cn` or `post_mortem_default_tmpl_en-us` for the built-in templates, a server-generated ID for custom ones."
           },
-          "created_at_seconds": {
-            "description": "Unix timestamp in seconds when the template was created.",
-            "format": "int64",
-            "type": "integer"
+          "name": {
+            "type": "string",
+            "description": "Template name shown in the console."
           },
           "description": {
-            "description": "Template description.",
-            "type": "string"
+            "type": "string",
+            "description": "Template description."
           },
-          "name": {
-            "description": "Template name shown in the console.",
-            "type": "string"
+          "content": {
+            "type": "string",
+            "description": "Template body as BlockNote editor JSON (an array of blocks), serialized as a string."
+          },
+          "content_markdown": {
+            "type": "string",
+            "description": "Markdown version of the template content, used by AI generation."
           },
           "team_id": {
-            "description": "Managing team ID. Built-in templates use 0.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Managing team ID; 0 for the built-in template."
           },
-          "template_id": {
-            "description": "Template ID. Built-in templates use a stable `post_mortem_default_tmpl_*` ID.",
-            "type": "string"
+          "created_at_seconds": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Creation time, Unix timestamp in seconds; 0 for the built-in template."
           },
           "updated_at_seconds": {
-            "description": "Unix timestamp in seconds when the template was last updated.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Last update time, Unix timestamp in seconds; 0 for the built-in template."
           }
-        },
-        "required": [
-          "account_id",
-          "template_id",
-          "name",
-          "description",
-          "content",
-          "content_markdown",
-          "team_id",
-          "created_at_seconds",
-          "updated_at_seconds"
-        ],
-        "type": "object"
+        }
       },
       "PreflightResult": {
+        "type": "object",
         "description": "Readiness checks computed before a manual run is allowed to start.",
         "properties": {
-          "app_name": {
-            "description": "App the rule is scoped to. Currently always ai-sre; manual runs are only supported for that app.",
-            "type": "string"
+          "ok": {
+            "type": "boolean",
+            "description": "Whether all readiness checks passed. Always `true` in a 200 response; a failed preflight returns an error instead."
           },
           "checks": {
-            "description": "Names of the readiness checks performed, in order. Current fixed set: rule_loaded, actor_authorized, app_allowed, runtime_scope_resolved, rule_config_valid.",
+            "type": "array",
             "items": {
               "type": "string"
             },
-            "type": "array"
-          },
-          "ok": {
-            "description": "Whether all readiness checks passed. Always true in a response that reaches the caller — a failed preflight returns a 400/403 error instead of a payload with ok=false.",
-            "type": "boolean"
-          },
-          "owner_id": {
-            "description": "Rule owner person ID.",
-            "format": "int64",
-            "type": "integer"
+            "description": "Names of the readiness checks performed, in order. Current fixed set: rule_loaded, actor_authorized, app_allowed, runtime_scope_resolved, rule_config_valid."
           },
           "scope": {
-            "description": "Resolved run scope for this run; mirrors the rule's run_scope. One of: `person` (personal rule, runs as its creator), `team` (team rule, runs under the owning team).",
+            "type": "string",
             "enum": [
               "person",
               "team"
             ],
-            "type": "string"
+            "description": "Resolved run scope for this run; mirrors the rule's run_scope. One of: `person` (personal rule, runs as its creator), `team` (team rule, runs under the owning team)."
+          },
+          "owner_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Rule owner person ID."
           },
           "team_id": {
-            "description": "Rule's scope team ID; 0 means a personal rule.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Rule's scope team ID; 0 means a personal rule."
+          },
+          "app_name": {
+            "type": "string",
+            "description": "App the rule is scoped to. Currently always ai-sre; manual runs are only supported for that app."
           },
           "warnings": {
-            "description": "Non-fatal warnings surfaced during preflight. Omitted or empty when there are none.",
+            "type": "array",
             "items": {
               "type": "string"
             },
-            "type": "array"
+            "description": "Non-fatal warnings from preflight. Currently never populated, so the field is omitted."
           }
         },
         "required": [
@@ -17347,54 +17778,29 @@
           "owner_id",
           "team_id",
           "app_name"
-        ],
-        "type": "object"
-      },
-      "PreviewIncidentCardFixedField": {
-        "description": "Fixed incident-card fields returned for supported IM previews after the requested hiding rules are applied.",
-        "properties": {
-          "field": {
-            "description": "Incident-card field name.\n\n| Value | Meaning |\n|---|---|\n| `channel` | Name of the alert channel that produced the incident; returned only when non-empty. |\n| `snoozed_before` | Snooze-until timestamp formatted as `YYYY-MM-DD HH:MM:SS`; returned only while the incident is snoozed. |\n| `severity` | Incident severity label; returned only when non-empty. |\n| `responders` | Names of the current responders, separated by spaces; returned only when the incident has responders. |\n| `aggregate_alert_count` | Number of alerts aggregated into the incident; returned only when greater than 1. |",
-            "enum": [
-              "channel",
-              "snoozed_before",
-              "severity",
-              "responders",
-              "aggregate_alert_count"
-            ],
-            "type": "string"
-          },
-          "value": {
-            "description": "Rendered display value for the fixed field.",
-            "type": "string"
-          }
-        },
-        "required": [
-          "field",
-          "value"
-        ],
-        "type": "object"
+        ]
       },
       "PreviewRemoteConfigRequest": {
         "description": "Preview request. Omit `config` to preview the currently live configuration.",
         "properties": {
           "app_version": {
-            "description": "App version the simulated client reports.",
+            "description": "App version the simulated client reports, compared exactly with rules' `match.app_version` (no range or prefix matching). Omitted = not reported.",
             "type": "string"
           },
           "application_id": {
-            "description": "RUM application ID.",
+            "description": "RUM application ID. Get application IDs via `POST /rum/application/list`.",
             "type": "string"
           },
           "config": {
-            "$ref": "#/components/schemas/RemoteConfig"
+            "$ref": "#/components/schemas/RemoteConfig",
+            "description": "Draft configuration to evaluate, validated like `POST /rum/application/remote-config/update`. Omit to evaluate the live configuration."
           },
           "env": {
-            "description": "Environment the simulated client reports.",
+            "description": "Environment the simulated client reports, compared exactly with rules' `match.env`. Omitted = not reported, so rules that test `env` cannot match.",
             "type": "string"
           },
           "sdk": {
-            "description": "SDK name and version the simulated client reports, e.g. `web@2.4.1`.",
+            "description": "SDK identifier the simulated client reports, e.g. `web@2.4.1`, compared exactly with rules' `match.sdk`. Omitted = not reported.",
             "type": "string"
           }
         },
@@ -17407,173 +17813,348 @@
         "description": "Values the simulated client would receive.",
         "properties": {
           "hit_rule_index": {
-            "description": "0-based index of the rule that decided the result, or -1 when only the default applied.",
+            "description": "0-based index into `config.rules` of the first rule that matched, or `-1` when no rule matched (only `default` applied) or the configuration is disabled or absent.",
             "type": "integer"
           },
           "values": {
-            "$ref": "#/components/schemas/RemoteConfigValues"
+            "$ref": "#/components/schemas/RemoteConfigValues",
+            "description": "`default` merged with the matching rule's `set`. Fields set by neither are omitted; an empty object means the client keeps all its init values."
           }
         },
-        "type": "object"
+        "type": "object",
+        "required": [
+          "values",
+          "hit_rule_index"
+        ]
       },
       "PreviewTemplateRequest": {
-        "description": "Template preview request.",
+        "type": "object",
         "properties": {
           "content": {
-            "description": "Template content to render.",
-            "type": "string"
+            "type": "string",
+            "description": "Template source to render for the channel `type`. Empty or omitted previews the channel's built-in preset content. Ignored for `push`."
           },
-          "feishu_app_card_v2_enabled": {
-            "type": "boolean",
-            "description": "Render the preview as a Feishu app card v2 message."
+          "type": {
+            "type": "string",
+            "description": "Channel to preview; other values return `InvalidParameter`.\n- `email`: email body (HTML template).\n- `sms`, `voice`: SMS text and voice call script.\n- `push`: mobile app push (fixed content; `content` is ignored).\n- `dingtalk`, `wecom`, `feishu`, `zoom`, `telegram`, `slack`: robot (webhook) messages.\n- `feishu_app`, `dingtalk_app`, `wecom_app`, `slack_app`, `teams_app`: IM app cards.",
+            "enum": [
+              "email",
+              "sms",
+              "voice",
+              "push",
+              "dingtalk",
+              "wecom",
+              "feishu",
+              "zoom",
+              "telegram",
+              "slack",
+              "feishu_app",
+              "dingtalk_app",
+              "wecom_app",
+              "slack_app",
+              "teams_app"
+            ]
           },
-          "feishu_app_card_v2_preserve_blank_lines": {
-            "type": "boolean",
-            "description": "Keep blank lines in the body of the Feishu app card v2 preview."
+          "incident_id": {
+            "type": "string",
+            "description": "Incident whose data is rendered (24-character hex ID from `/incident/list`); must exist in the account, otherwise `InvalidParameter`. When omitted a mock incident is used.",
+            "pattern": "^[0-9a-fA-F]{24}$"
           },
           "incident_card_hidden_fields": {
             "$ref": "#/components/schemas/IncidentCardHiddenFields",
             "description": "Incident card fields to hide per IM app when previewing."
           },
-          "incident_id": {
-            "description": "Incident ID whose data is used to render the template; mock data is used when omitted. A MongoDB ObjectID hex string.",
-            "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
+          "feishu_app_card_v2_table_enabled": {
+            "type": "boolean",
+            "default": false,
+            "description": "Render Markdown tables in `feishu_app` content as native Feishu card tables, as the template setting of the same name does."
           },
-          "type": {
-            "description": "Template channel type that selects the rendering engine. `email` renders as Go html/template; other channels render as text/template. Values match the template channel fields, for example `email`, `sms`, `voice`, `dingtalk`, `wecom`, `feishu`, `feishu_app`, `dingtalk_app`, `wecom_app`, `slack_app`, `teams_app`, `telegram`, `slack`, `zoom`.",
-            "type": "string"
+          "feishu_app_card_v2_preserve_blank_lines": {
+            "type": "boolean",
+            "description": "Keep blank lines in the body of the Feishu app card v2 preview."
+          },
+          "wecom_markdown_v2_enabled": {
+            "type": "boolean",
+            "default": false,
+            "description": "Preview `wecom` content as a `markdown_v2` message, as the template setting of the same name does (size limit 4,096 bytes)."
           }
         },
         "required": [
-          "content",
           "type"
         ],
-        "type": "object"
+        "description": "Template preview request."
       },
       "PreviewTemplateResponse": {
-        "description": "Template preview result.",
+        "type": "object",
         "properties": {
-          "content": {
-            "description": "Rendered template output, present when success is true.",
-            "type": "string"
-          },
-          "fixed_fields": {
-            "description": "Fixed incident-card fields returned for supported IM previews after the requested hiding rules are applied.",
-            "items": {
-              "$ref": "#/components/schemas/PreviewIncidentCardFixedField"
-            },
-            "type": "array"
-          },
-          "message": {
-            "description": "Error message describing why rendering failed, present when success is false.",
-            "type": "string"
-          },
           "success": {
-            "description": "Whether the template rendered without errors.",
-            "type": "boolean"
-          }
-        },
-        "required": [
-          "success",
-          "content",
-          "message"
-        ],
-        "type": "object"
-      },
-      "PublishedArtifactItem": {
-        "description": "One published artifact in the gallery. Time fields are Unix timestamps in milliseconds.",
-        "properties": {
-          "artifact_id": {
-            "description": "Artifact ID (`art_` prefix). Also the key of the public-share link.",
-            "type": "string"
-          },
-          "can_edit": {
-            "description": "Whether the caller may manage this artifact (rename, transfer, delete, share): the creator, any member of the owning team, or a manager of the source session.",
-            "type": "boolean"
-          },
-          "content_type": {
-            "description": "MIME type of the file.",
-            "type": "string"
-          },
-          "created_at": {
-            "description": "Unix timestamp in milliseconds when the artifact was published.",
-            "format": "int64",
-            "type": "integer"
+            "type": "boolean",
+            "description": "Whether the template rendered without errors."
           },
-          "creator_name": {
-            "description": "Creator's display name.",
-            "type": "string"
+          "content": {
+            "type": "string",
+            "description": "Rendered template output; an empty string when `success` is `false`."
           },
-          "file_id": {
-            "description": "Presented-file ID (`pf_` prefix) currently holding the artifact's bytes. Changes on every republish.",
-            "type": "string"
+          "message": {
+            "type": "string",
+            "description": "Why rendering failed, in the caller's language; an empty string when `success` is `true`."
           },
-          "is_mine": {
-            "description": "Whether the caller is the creator.",
-            "type": "boolean"
+          "card": {
+            "type": "object",
+            "description": "Message frame around the rendered template, in the account language. Returned for `email`, `feishu_app`, `dingtalk_app`, `wecom_app`, `slack_app` and `teams_app`; omitted otherwise.",
+            "required": [
+              "title",
+              "elements"
+            ],
+            "properties": {
+              "title": {
+                "type": "string",
+                "description": "Email subject or card title."
+              },
+              "elements": {
+                "type": "array",
+                "description": "Card elements in display order.",
+                "items": {
+                  "type": "object",
+                  "required": [
+                    "type"
+                  ],
+                  "properties": {
+                    "type": {
+                      "type": "string",
+                      "enum": [
+                        "template",
+                        "markdown",
+                        "divider",
+                        "actions"
+                      ],
+                      "description": "Element kind.\n- `template`: where the rendered template (`content`) appears.\n- `markdown`: fixed text in the channel's Markdown, in `content`.\n- `divider`: a horizontal rule.\n- `actions`: a row of buttons, in `actions`."
+                    },
+                    "content": {
+                      "type": "string",
+                      "description": "Markdown text of a `markdown` element; omitted for other kinds."
+                    },
+                    "actions": {
+                      "type": "array",
+                      "description": "Buttons of an `actions` element; omitted for other kinds.",
+                      "items": {
+                        "type": "object",
+                        "required": [
+                          "text"
+                        ],
+                        "properties": {
+                          "text": {
+                            "type": "string",
+                            "description": "Button label."
+                          },
+                          "style": {
+                            "type": "string",
+                            "enum": [
+                              "primary",
+                              "danger",
+                              "select"
+                            ],
+                            "description": "Button style: `primary` (highlighted), `danger` (destructive), `select` (a drop-down menu). Omitted for a plain button."
+                          }
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
           },
-          "name": {
-            "description": "Underlying file name including extension.",
-            "type": "string"
+          "blocks": {
+            "type": "array",
+            "description": "How the recipient's client shows `content`, split into blocks. Omitted for channels that show the text as is.",
+            "items": {
+              "type": "object",
+              "required": [
+                "type"
+              ],
+              "properties": {
+                "type": {
+                  "type": "string",
+                  "enum": [
+                    "markdown",
+                    "table"
+                  ],
+                  "description": "Block kind: `markdown` (text in `content`) or `table` (a table in `columns`/`rows`)."
+                },
+                "content": {
+                  "type": "string",
+                  "description": "Text of a `markdown` block."
+                },
+                "native": {
+                  "type": "boolean",
+                  "description": "`true` when a `table` block is shown as a native card table; omitted otherwise."
+                },
+                "columns": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  },
+                  "description": "Column headers of a `table` block."
+                },
+                "rows": {
+                  "type": "array",
+                  "items": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    }
+                  },
+                  "description": "Cell values of a `table` block, one array per row."
+                },
+                "page_size": {
+                  "type": "integer",
+                  "description": "Rows shown per page in a native table; omitted when not set."
+                }
+              }
+            }
+          },
+          "notices": {
+            "type": "array",
+            "description": "Warnings about how the content will be delivered. Omitted when there are none.",
+            "items": {
+              "type": "object",
+              "required": [
+                "code"
+              ],
+              "properties": {
+                "code": {
+                  "type": "string",
+                  "enum": [
+                    "table_not_rendered",
+                    "native_table_fallback",
+                    "content_too_large"
+                  ],
+                  "description": "Warning kind.\n- `table_not_rendered`: the channel cannot show Markdown tables; they are sent as text.\n- `native_table_fallback`: a table cannot be a native card table and is sent as Markdown; `reason` says why (`too_many_tables`, `too_many_columns`, `too_many_rows`, `cell_too_long`, `unsupported_cell`, `card_too_large`).\n- `content_too_large`: the content exceeds `size_limit_bytes`; `reason` is `truncated` (cut to fit), `compact_fallback` (sent in a compact form) or `rejected` (the channel will refuse it)."
+                },
+                "reason": {
+                  "type": "string",
+                  "description": "Detail for `code`, as listed there; omitted for `table_not_rendered`."
+                }
+              }
+            }
+          },
+          "size_bytes": {
+            "type": "integer",
+            "description": "Size of the rendered content in bytes, measured before any truncation."
+          },
+          "size_limit_bytes": {
+            "type": "integer",
+            "description": "Size limit the channel applies in bytes: 4,000 for robot channels (and `wecom` without `markdown_v2`), 4,096 for `wecom` with `markdown_v2`, 15,000 for `slack_app`, 30,720 for `feishu_app`; `0` when the channel has no limit."
+          }
+        },
+        "required": [
+          "success",
+          "content",
+          "message",
+          "size_bytes",
+          "size_limit_bytes"
+        ],
+        "description": "Template preview result."
+      },
+      "PublishedArtifactItem": {
+        "type": "object",
+        "description": "One published artifact in the gallery. Time fields are Unix timestamps in milliseconds.",
+        "properties": {
+          "artifact_id": {
+            "type": "string",
+            "description": "Artifact ID (`art_` prefix). Also the key of the public-share link."
+          },
+          "title": {
+            "type": "string",
+            "description": "Display title in the gallery."
+          },
+          "team_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Owning scope. `0` means a personal artifact: it appears only in its creator's list, and can be managed by the creator or by anyone who can manage the source session. A positive value is the owning team ID: the artifact appears in that team's members' lists and any team member can manage it. Set from the source session at first publish; change it with `/safari/artifact/gallery/update`."
+          },
+          "team_name": {
+            "type": "string",
+            "description": "Owning team's display name. Omitted for personal artifacts."
           },
           "person_id": {
-            "description": "Person (member) ID of the creator.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Person ID of the artifact's creator: the owner of the source session at first publish. It never changes on republish or scope transfer."
           },
-          "public_url": {
-            "description": "Anonymous public link — a console `/share/artifact/<artifact_id>` page served entirely from CDN. Present only while shared; anyone with the link can view it, no login required.",
-            "type": "string"
+          "creator_name": {
+            "type": "string",
+            "description": "Creator's display name."
+          },
+          "is_mine": {
+            "type": "boolean",
+            "description": "`true` when the caller (for an `app_key` call, the key owner) is the creator, i.e. `person_id` equals the caller's person ID."
+          },
+          "can_edit": {
+            "type": "boolean",
+            "description": "Whether the caller may manage this artifact (rename, transfer, delete, share): the creator, any member of the owning team, or a manager of the source session."
           },
           "session_id": {
-            "description": "Source session ID (`sess_` prefix) that produced the file.",
-            "type": "string"
+            "type": "string",
+            "description": "Source session ID (`sess_` prefix) that produced the file."
           },
           "session_title": {
-            "description": "Source session's title. Omitted when the session has been deleted.",
-            "type": "string"
+            "type": "string",
+            "description": "Source session's title. Omitted when the session has been deleted."
           },
-          "share_enabled": {
-            "description": "Whether anonymous public sharing is on. Omitted when false.",
-            "type": "boolean"
+          "file_id": {
+            "type": "string",
+            "description": "Presented-file ID (`pf_` prefix) currently holding the artifact's bytes. Changes on every republish."
           },
-          "share_file_id": {
-            "description": "Presented-file ID the public snapshot was materialized from. When `share_enabled` is true and `file_id` differs from `share_file_id`, the public snapshot is stale — call `/safari/artifact/gallery/share/sync` to refresh it.",
-            "type": "string"
+          "name": {
+            "type": "string",
+            "description": "Underlying file name including extension. Empty when the underlying file record is missing."
           },
-          "shared_at": {
-            "description": "Unix timestamp in milliseconds of the last share enable or snapshot sync. Present only while shared.",
+          "size": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "File size in bytes."
           },
-          "shared_by": {
-            "description": "Person ID of the member who enabled sharing. Present only while shared.",
+          "content_type": {
+            "type": "string",
+            "description": "MIME type, derived from the file-name extension when the file was produced: `text/html` (.html/.htm), `text/markdown` (.md), `text/plain` (.txt/.log), `text/csv`, `text/yaml` (.yaml/.yml), `text/x-python`, `text/x-go`, `text/x-sh`, `application/json`, `application/xml`, `application/pdf`, `image/png`, `image/jpeg`, `image/gif`, `image/svg+xml`, `image/webp`, `application/zip`, `application/gzip` (.tar/.gz/.tgz); any other extension is `application/octet-stream`. Empty when the underlying file record is missing."
+          },
+          "created_at": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Unix timestamp in milliseconds when the artifact was published."
           },
-          "size": {
-            "description": "File size in bytes.",
+          "updated_at": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Unix timestamp in milliseconds of the last change to the artifact row (rename, transfer, republish, or share state change)."
           },
-          "team_id": {
-            "description": "Owning team ID. `0` means a personal artifact (creator-only management); a positive value means team-owned.",
+          "pinned_at": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Unix timestamp in milliseconds when the caller pinned this artifact in the console gallery. Pins are per member; omitted when the caller has not pinned it. Pinned artifacts are listed first by `/safari/artifact/gallery/list`."
           },
-          "team_name": {
-            "description": "Owning team's display name. Omitted for personal artifacts.",
-            "type": "string"
+          "share_enabled": {
+            "type": "boolean",
+            "description": "Whether anonymous public sharing is on. Omitted when false."
           },
-          "title": {
-            "description": "Display title in the gallery.",
-            "type": "string"
+          "public_url": {
+            "type": "string",
+            "description": "Anonymous public link — a console `/share/artifact/<artifact_id>` page served entirely from CDN. Present only while shared; anyone with the link can view it, no login required."
           },
-          "updated_at": {
-            "description": "Unix timestamp in milliseconds when the artifact was last updated (rename, transfer, or republish).",
+          "shared_by": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Person ID of the member who enabled sharing; a later snapshot sync does not change it. Present only while shared."
+          },
+          "shared_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Unix timestamp in milliseconds of the last share enable or snapshot sync. Present only while shared."
+          },
+          "share_file_id": {
+            "type": "string",
+            "description": "Presented-file ID the public snapshot was materialized from. When `share_enabled` is true and `file_id` differs from `share_file_id`, the public snapshot is stale — call `/safari/artifact/gallery/share/sync` to refresh it."
           }
         },
         "required": [
@@ -17591,16 +18172,15 @@
           "content_type",
           "created_at",
           "updated_at"
-        ],
-        "type": "object"
+        ]
       },
       "QueryDataRequest": {
+        "description": "Request body of the structured query endpoint.",
         "allOf": [
           {
             "$ref": "#/components/schemas/QueryRowsRequest"
           }
-        ],
-        "description": "Request for the stable structured query endpoint. It accepts the same query fields as the retired rows endpoint."
+        ]
       },
       "QueryDataResponse": {
         "description": "Stable, Edge-version-independent structured query response.",
@@ -17772,43 +18352,59 @@
         ]
       },
       "QueryRowsRequest": {
+        "type": "object",
+        "required": [
+          "ds_type",
+          "ds_name",
+          "expr"
+        ],
         "properties": {
           "account_id": {
-            "description": "Optional consistency check. Must equal the authenticated account when supplied; mismatched values are rejected. Business execution always uses the authenticated account.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
-          },
-          "args": {
-            "additionalProperties": {
-              "type": "string"
-            },
-            "description": "Polymorphic key/value extension parameters forwarded verbatim to monit-edge. All values must be strings, and keys are always namespaced by source (e.g. `sls.project`, `loki.type`). Validation depends on `ds_type`: SLS requires `sls.project` + `sls.logstore`. Elasticsearch accepts `es.type` of `sql`, or omitted — any other value is rejected. Loki and VictoriaLogs accept `<source>.type` of `stats`, `raw`, or omitted; `raw` additionally requires a time range, either `<source>.start` + `<source>.end` or `<source>.timespan.value` + `<source>.timespan.unit` (unit one of `s`, `m`, `h`, `d`). Prometheus and the remaining SQL sources ignore `args` entirely.",
-            "type": "object"
+            "description": "Optional consistency check. When supplied it must equal the authenticated account, otherwise the request fails with `AccessDenied`. The query always runs as the authenticated account."
           },
-          "delay_seconds": {
-            "default": 0,
-            "description": "Look-back offset in seconds applied to point-in-time queries (Prometheus, Loki stats, VictoriaLogs stats). Ignored for raw / detail queries.",
-            "type": "integer"
+          "ds_type": {
+            "type": "string",
+            "description": "Data source type. Together with `ds_name` it must match an enabled data source of the account.\n\n- `prometheus`: Prometheus-compatible data source; `expr` is PromQL.\n- `loki`: Grafana Loki; `expr` is LogQL.\n- `victorialogs`: VictoriaLogs.\n- `sls`: Alibaba Cloud Log Service (SLS).\n- `tencent_cls`: Tencent Cloud Log Service (CLS); requires monit-edge v0.66.0 or later.\n- `elasticsearch`: Elasticsearch.\n- `mysql`: MySQL; `expr` is SQL.\n- `postgres`: PostgreSQL; `expr` is SQL.\n- `oracle`: Oracle Database; `expr` is SQL.\n- `clickhouse`: ClickHouse; `expr` is SQL.\n\nOther data source types (for example MongoDB, Redis, or Kafka) are rejected.",
+            "enum": [
+              "clickhouse",
+              "elasticsearch",
+              "loki",
+              "mysql",
+              "oracle",
+              "postgres",
+              "prometheus",
+              "sls",
+              "tencent_cls",
+              "victorialogs"
+            ]
           },
           "ds_name": {
-            "description": "Data source name; must match a configured data source under the tenant.",
-            "type": "string"
-          },
-          "ds_type": {
-            "description": "Data source type; must match a configured data source under the tenant. Examples: `prometheus`, `loki`, `victorialogs`, `sls`, `elasticsearch`, `mysql`, `postgres`, `oracle`, `clickhouse`.",
-            "type": "string"
+            "type": "string",
+            "description": "Data source name, as returned by `/monit/datasource/list`. The data source must be enabled; a name that matches no data source of the account returns HTTP 400."
           },
           "expr": {
-            "description": "Query expression. Syntax depends on `ds_type` and is interpreted by the corresponding monit-edge client (PromQL for Prometheus, LogQL for Loki, SQL for SQL sources, etc.).",
-            "type": "string"
+            "type": "string",
+            "description": "Query expression in the language of `ds_type` (PromQL for `prometheus`, LogQL for `loki`, SQL for SQL sources, and so on). Required, at most 64 KiB (12 KiB for `tencent_cls`). Loki's `$__auto` is not supported here; use a fixed duration such as `[5m]`. Prometheus expressions are syntax-checked before dispatch.",
+            "minLength": 1
+          },
+          "delay_seconds": {
+            "type": "integer",
+            "description": "Look-back offset in seconds, from 0 to 86400. Applied to point-in-time queries (Prometheus, Loki stats, VictoriaLogs stats); ignored for raw and detail queries. When `args` carries an absolute `<source>.time` and the Edge is v0.74.0 or later, the absolute time takes precedence and this offset is not applied.",
+            "default": 0,
+            "minimum": 0,
+            "maximum": 86400
+          },
+          "args": {
+            "type": "object",
+            "description": "Extra query parameters as string key/value pairs; keys are namespaced by data source (for example `sls.project`, `loki.type`). At most 128 entries, keys up to 256 bytes, values up to 64 KiB, and 128 KiB in total. What is accepted depends on `ds_type`:\n\n- `prometheus`: optional `prometheus.time`, the evaluation time as Unix seconds, not in the future.\n- `loki`, `victorialogs`: `<source>.type` is `stats` (default) or `raw`. `stats` accepts an optional `<source>.time` (Unix seconds, not in the future). `raw` requires a time range, either `<source>.start` + `<source>.end` (Unix seconds) or `<source>.timespan.value` + `<source>.timespan.unit` (`s`, `m`, `h`, or `d`), spanning at most 6 hours, and accepts `<source>.limit` from 1 to 1001.\n- `sls`: `sls.project` and `sls.logstore` are required. Optional: `sls.lines` (1 to 100), `sls.offset` (0 or more), and a time range of at most 6 hours given as `sls.from` + `sls.to` (Unix seconds) or `sls.timespan.value` + `sls.timespan.unit`.\n- `tencent_cls`: `tencent_cls.region`, `tencent_cls.topic_id`, `tencent_cls.query_mode` (`raw` or `analysis`), and `tencent_cls.syntax` (`cql` or `lucene`) are required. Optional: `tencent_cls.limit` (1 to 100, `raw` mode only, needs monit-edge v0.67.0 or later) and a time range given as `tencent_cls.from` + `tencent_cls.to` (Unix seconds) or `tencent_cls.timespan.value` + `tencent_cls.timespan.unit`, at most 6 hours in `raw` mode and 24 hours in `analysis` mode. Any other key is rejected.\n- `elasticsearch`: `es.type` may be `sql` or omitted; any other value is rejected.\n- `mysql`, `postgres`, `oracle`, `clickhouse`: no arguments are defined.\n\nAn absolute `<source>.time` is only valid for its own data source type. Edges older than v0.74.0 approximate it with a look-back offset and accept only times within the last 86,400 seconds.",
+            "additionalProperties": {
+              "type": "string"
+            }
           }
         },
-        "required": [
-          "ds_type",
-          "ds_name",
-          "expr"
-        ],
-        "type": "object"
+        "description": "Query to run. `ds_type` and `ds_name` together select the data source; `expr` and `args` are interpreted by that data source type."
       },
       "QuerySample": {
         "properties": {
@@ -17878,29 +18474,35 @@
             "type": "string"
           },
           "custom": {
-            "additionalProperties": {},
-            "description": "Application-defined pass-through values handed to the host app verbatim. At most 5 keys, each key up to 64 bytes, each value up to 4 KB of JSON nested at most 3 levels, 16 KB in total. Anyone holding the public client token can read it.",
+            "additionalProperties": {
+              "description": "Any JSON value: string, number, boolean, array or object."
+            },
+            "description": "Free-form key/value map that SDKs hand to the host app verbatim; the platform does not interpret it. At most 5 keys, each key 1–64 bytes, each value valid JSON of at most 4 KB nested at most 3 levels, 16 KB in total. Anyone holding the public client token can read it. Omitted from responses when empty.",
             "maxProperties": 5,
             "type": "object"
           },
           "default": {
-            "$ref": "#/components/schemas/RemoteConfigValues"
+            "$ref": "#/components/schemas/RemoteConfigValues",
+            "description": "Values every client receives unless a matching rule overrides them."
           },
           "enabled": {
-            "description": "Kill switch. When false the engine reports no values at all and SDKs fall back to their init values.",
+            "description": "Kill switch. When `false` the SDK config endpoint returns no values and SDKs fall back to their init values; `default` and `rules` are kept. Treated as `false` when omitted.",
             "type": "boolean"
           },
           "refresh_on_foreground": {
-            "description": "Let clients re-check the configuration when they return to the foreground instead of waiting for the next poll.",
+            "description": "If `true`, clients re-check the configuration when they return to the foreground instead of waiting for the next poll. Default `false`; omitted from responses when `false`.",
             "type": "boolean"
           },
           "rules": {
-            "description": "Targeting rules, evaluated in order; at most 20 per application.",
+            "description": "Targeting rules, evaluated in order; the first match wins. At most 20. Can be `null` when the configuration was saved without rules.",
             "items": {
               "$ref": "#/components/schemas/RemoteConfigRule"
             },
             "maxItems": 20,
-            "type": "array"
+            "type": [
+              "array",
+              "null"
+            ]
           }
         },
         "type": "object"
@@ -17909,18 +18511,19 @@
         "description": "One published remote configuration version.",
         "properties": {
           "config": {
-            "$ref": "#/components/schemas/RemoteConfig"
+            "$ref": "#/components/schemas/RemoteConfig",
+            "description": "The configuration content that went live under this version."
           },
           "content_hash": {
-            "description": "Hash of the configuration content; lets the console identify versions with identical content.",
+            "description": "Fingerprint of the stored configuration: the first 16 hex characters of its SHA-256. Versions with equal hashes have identical content. Can be empty for older versions.",
             "type": "string"
           },
           "equivalent_to": {
-            "description": "Earliest version carrying the same content, when that is not this version itself.",
+            "description": "Earliest retained version with the same `content_hash`, e.g. the version a revert restored. Omitted when this version is itself the earliest.",
             "type": "integer"
           },
           "reason": {
-            "description": "Operator's note left when the version was published. Empty when none was given.",
+            "description": "Free-text note (not an enum) sent as `reason` when the version was published or reverted; `\"\"` when none was given.",
             "type": "string"
           },
           "updated_at": {
@@ -17934,7 +18537,7 @@
             "type": "integer"
           },
           "updated_by_name": {
-            "description": "Name of the member who published the version.",
+            "description": "Name of the member who published the version at publish time, truncated to 128 characters.",
             "type": "string"
           },
           "version": {
@@ -17942,18 +18545,35 @@
             "type": "integer"
           }
         },
-        "type": "object"
+        "type": "object",
+        "required": [
+          "config",
+          "version",
+          "content_hash",
+          "reason",
+          "updated_by",
+          "updated_by_name",
+          "updated_at"
+        ]
       },
       "RemoteConfigRule": {
-        "description": "One targeting rule: when `match` holds, `set` overrides `default`. The first matching rule wins and evaluation stops there - rule order is the priority.",
+        "description": "One targeting rule: when every `match` condition holds, `set` overrides `default`. The first matching rule wins and evaluation stops there; rule order is the priority. `set` must set at least one value.",
         "properties": {
           "match": {
             "additionalProperties": {
               "maxLength": 256,
+              "minLength": 1,
               "type": "string"
             },
-            "description": "Key/value conditions the SDK's config request must equal. Keys are limited to `env`, `app_version` and `sdk`; values are at most 256 bytes.",
+            "description": "Conditions on what the SDK reports in its config request, combined with AND and compared as exact strings. Keys are limited to `env`, `app_version` and `sdk`; values are 1–256 bytes. A key the SDK does not report never matches.",
             "minProperties": 1,
+            "propertyNames": {
+              "enum": [
+                "env",
+                "app_version",
+                "sdk"
+              ]
+            },
             "type": "object"
           },
           "set": {
@@ -17970,7 +18590,7 @@
         "description": "The SDK knobs a configuration can set. Every field is optional: a value absent from both rule and default is omitted from the SDK response, which tells the SDK to keep its init value.",
         "properties": {
           "defaultPrivacyLevel": {
-            "description": "How Session Replay masks a page by default.",
+            "description": "How Session Replay masks a page by default:\n\n- `mask`: replaces text and hides input values.\n- `mask-user-input`: keeps page text but hides what users type.\n- `allow`: records the page as it is; content already uploaded cannot be masked later.",
             "enum": [
               "mask",
               "mask-user-input",
@@ -17996,7 +18616,7 @@
             ]
           },
           "sessionReplaySampleRate": {
-            "description": "Session Replay sampling rate (0-100).",
+            "description": "Percentage of sessions that record Session Replay (0–100).",
             "maximum": 100,
             "minimum": 0,
             "type": [
@@ -18005,7 +18625,7 @@
             ]
           },
           "sessionSampleRate": {
-            "description": "Session sampling rate (0-100).",
+            "description": "Percentage of sessions collected (0–100).",
             "maximum": 100,
             "minimum": 0,
             "type": [
@@ -18014,7 +18634,7 @@
             ]
           },
           "traceSampleRate": {
-            "description": "Trace sampling rate (0-100): which sessions inject trace headers into their requests.",
+            "description": "Percentage of sessions that inject trace headers into their requests (0–100). Decided per session: a session traces all of its requests or none.",
             "maximum": 100,
             "minimum": 0,
             "type": [
@@ -18045,28 +18665,28 @@
         "type": "object"
       },
       "ReopenIncidentRequest": {
+        "type": "object",
         "description": "Parameters for reopening one or more closed incidents.",
+        "required": [
+          "incident_ids"
+        ],
         "properties": {
           "incident_ids": {
-            "description": "Incident IDs to reopen. At most 100 per call.",
+            "type": "array",
             "items": {
-              "pattern": "^[0-9a-fA-F]{24}$",
-              "type": "string"
+              "type": "string",
+              "pattern": "^[0-9a-fA-F]{24}$"
             },
             "maxItems": 100,
-            "minItems": 1,
-            "type": "array"
+            "description": "Incident IDs to reopen. At most 100 per call.",
+            "minItems": 1
           },
           "reason": {
-            "description": "Optional reason recorded on the timeline.",
+            "type": "string",
             "maxLength": 1024,
-            "type": "string"
+            "description": "Optional free-text reason, recorded on the `i_reopen` timeline entry. At most 1,024 characters."
           }
-        },
-        "required": [
-          "incident_ids"
-        ],
-        "type": "object"
+        }
       },
       "ReorderIncidentCommentTypesRequest": {
         "description": "Parameters for reordering comment types.",
@@ -18087,77 +18707,77 @@
         "type": "object"
       },
       "ResetIncidentFieldRequest": {
+        "type": "object",
         "description": "Parameters for updating a custom field value on an incident.",
+        "required": [
+          "incident_id",
+          "field_name"
+        ],
         "properties": {
+          "incident_id": {
+            "type": "string",
+            "pattern": "^[0-9a-fA-F]{24}$",
+            "description": "Incident ID (MongoDB ObjectID)."
+          },
           "field_name": {
-            "description": "Custom field name; must match a field defined on the account.",
-            "type": "string"
+            "type": "string",
+            "description": "Custom field name (the field's `field_name`, not its display name). The field must exist and be enabled; list fields with `POST /field/list`."
           },
           "field_value": {
-            "description": "New field value. Type must match the field definition."
-          },
-          "incident_id": {
-            "description": "Incident ID (MongoDB ObjectID).",
-            "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
+            "description": "New value. Its type must match the field: `checkbox` takes a boolean, `single_select` one of the options, `multi_select` an array of options, `text` a string. Omit it or send `null` to clear the field."
           }
-        },
-        "required": [
-          "incident_id",
-          "field_name"
-        ],
-        "type": "object"
+        }
       },
       "ResetPostMortemBasicsRequest": {
+        "type": "object",
         "description": "Basic incident facts to write back to a post-mortem report.",
+        "required": [
+          "post_mortem_id",
+          "incidents_highest_severity",
+          "incidents_earliest_start_seconds"
+        ],
         "properties": {
-          "incidents_earliest_start_seconds": {
-            "description": "Unix timestamp in seconds for the earliest linked incident start time.",
-            "format": "int64",
-            "minimum": 1,
-            "type": "integer"
+          "post_mortem_id": {
+            "type": "string",
+            "description": "Post-mortem ID; obtain it from `POST /incident/post-mortem/list`."
           },
           "incidents_highest_severity": {
-            "description": "Highest severity among linked incidents: `Critical`, `Warning`, `Info`, or `Ok`.",
+            "type": "string",
+            "description": "Highest severity among the linked incidents.\n- `Critical`: critical.\n- `Warning`: warning.\n- `Info`: informational.\n- `Ok`: recovered.",
             "enum": [
               "Critical",
               "Warning",
               "Info",
               "Ok"
-            ],
-            "type": "string"
+            ]
+          },
+          "incidents_earliest_start_seconds": {
+            "type": "integer",
+            "format": "int64",
+            "minimum": 1,
+            "description": "Unix timestamp in seconds for the earliest linked incident start time."
           },
           "incidents_latest_close_seconds": {
-            "description": "Unix timestamp in seconds for the latest linked incident close time. 0 when still open.",
+            "type": "integer",
             "format": "int64",
             "minimum": 0,
-            "type": "integer"
+            "description": "Latest close time among the linked incidents, Unix timestamp in seconds. 0 (also when omitted) means still open."
           },
           "incidents_total_duration_seconds": {
-            "description": "Total incident duration in seconds.",
+            "type": "integer",
             "format": "int64",
             "minimum": 0,
-            "type": "integer"
-          },
-          "post_mortem_id": {
-            "description": "Post-mortem ID; obtain it from `POST /incident/post-mortem/list`.",
-            "type": "string"
+            "description": "Total incident duration in seconds; 0 when omitted."
           },
           "responder_ids": {
-            "description": "Responder member IDs to store on the report.",
+            "type": "array",
             "items": {
-              "format": "int64",
-              "type": "integer"
+              "type": "integer",
+              "format": "int64"
             },
-            "type": "array"
+            "description": "Member IDs to store as the report's responders. Replaces the stored list; omit or send `[]` to clear it. IDs that do not resolve to a person are dropped."
           }
-        },
-        "required": [
-          "post_mortem_id",
-          "incidents_highest_severity",
-          "incidents_earliest_start_seconds"
-        ],
-        "type": "object"
+        }
       },
       "ResetPostMortemContentRequest": {
         "description": "Parameters for fully replacing a drafting post-mortem report body.",
@@ -18195,72 +18815,88 @@
         "type": "object"
       },
       "ResetPostMortemFollowUpsRequest": {
+        "type": "object",
         "description": "Parameters for replacing post-mortem follow-up action items.",
-        "properties": {
-          "follow_ups": {
-            "description": "Follow-up action items as free text.",
-            "type": "string"
-          },
-          "post_mortem_id": {
-            "description": "Post-mortem ID; obtain it from `POST /incident/post-mortem/list`.",
-            "type": "string"
-          }
-        },
         "required": [
           "post_mortem_id"
         ],
-        "type": "object"
+        "properties": {
+          "post_mortem_id": {
+            "type": "string",
+            "description": "Post-mortem ID; obtain it from `POST /incident/post-mortem/list`."
+          },
+          "follow_ups": {
+            "type": "string",
+            "description": "Follow-ups as free text, replacing the stored string. A JSON array in the console's follow-up format (objects with `title`, `status`, `priority`, `assignee_ids`, …) is also synced into structured follow-up work items."
+          }
+        }
       },
       "ResetPostMortemStatusRequest": {
+        "type": "object",
         "description": "Parameters for changing a post-mortem report status.",
+        "required": [
+          "post_mortem_id",
+          "status"
+        ],
         "properties": {
           "post_mortem_id": {
-            "description": "Post-mortem ID; obtain it from `POST /incident/post-mortem/list`.",
-            "type": "string"
+            "type": "string",
+            "description": "Post-mortem ID; obtain it from `POST /incident/post-mortem/list`."
           },
           "status": {
-            "description": "Target report status: `drafting` draft, `published` published.",
+            "type": "string",
             "enum": [
               "drafting",
               "published"
             ],
-            "type": "string"
+            "description": "Target report status.\n- `drafting`: being edited; the body can still be replaced with a content reset.\n- `published`: published; media files no longer referenced by the body are deleted."
           }
-        },
-        "required": [
-          "post_mortem_id",
-          "status"
-        ],
-        "type": "object"
+        }
       },
       "ResetPostMortemTitleRequest": {
+        "type": "object",
         "description": "Parameters for changing a post-mortem report title.",
+        "required": [
+          "post_mortem_id",
+          "title"
+        ],
         "properties": {
           "post_mortem_id": {
-            "description": "Post-mortem ID; obtain it from `POST /incident/post-mortem/list`.",
-            "type": "string"
+            "type": "string",
+            "description": "Post-mortem ID; obtain it from `POST /incident/post-mortem/list`."
           },
           "title": {
-            "description": "New report title.",
-            "type": "string"
+            "type": "string",
+            "maxLength": 256,
+            "description": "New report title, at most 256 characters."
           }
-        },
-        "required": [
-          "post_mortem_id",
-          "title"
-        ],
-        "type": "object"
+        }
       },
       "ResetWorkItemAssigneesRequest": {
-        "description": "Full replacement of a work item's assignee set.",
+        "type": "object",
+        "description": "Full replacement of a work item's assignee set. Exactly one of `assignees` or `assignee_ids` must be sent.",
+        "required": [
+          "work_item_id",
+          "version"
+        ],
         "properties": {
+          "work_item_id": {
+            "type": "string",
+            "maxLength": 128,
+            "description": "Work item ID (opaque string, max 128 characters)."
+          },
+          "version": {
+            "type": "integer",
+            "format": "int64",
+            "description": "The item's current `version` (≥ 1) for optimistic locking."
+          },
           "assignee_ids": {
-            "description": "Legacy alias for the replacement assignee set. Equivalent to `assignees` with every entry `type` `person`. Mutually exclusive with `assignees`: sending both returns an error. An empty array clears all assignees.",
+            "type": "array",
             "items": {
-              "format": "int64",
-              "type": "integer"
+              "type": "integer",
+              "format": "int64"
             },
-            "type": "array"
+            "description": "Legacy alias for the replacement assignee set. Equivalent to `assignees` with every entry `type` `person`. Mutually exclusive with `assignees`: sending both returns an error. An empty array clears all assignees."
           },
           "assignees": {
             "description": "Replacement assignee set. Each entry is `{type, id?}`. `type` is `person` or `ai_sre`; an `ai_sre` entry omits `id`. Mutually exclusive with `assignee_ids`: sending both returns an error. `assignee_ids` is the legacy alias and is equivalent to an all-`person` list. At most 20 entries. An empty array clears all assignees.",
@@ -18269,23 +18905,8 @@
             },
             "maxItems": 20,
             "type": "array"
-          },
-          "version": {
-            "description": "Current item version for optimistic locking. Must match the stored version.",
-            "format": "int64",
-            "type": "integer"
-          },
-          "work_item_id": {
-            "description": "Work item ID (opaque string, max 128 characters).",
-            "maxLength": 128,
-            "type": "string"
           }
-        },
-        "required": [
-          "work_item_id",
-          "version"
-        ],
-        "type": "object"
+        }
       },
       "ResolveIncidentRequest": {
         "description": "Parameters for resolving one or more incidents.",
@@ -18458,51 +19079,51 @@
         ]
       },
       "ResponderInsightResponse": {
+        "type": "object",
         "properties": {
           "items": {
-            "description": "Incident response metric rows aggregated by responder; further split by hour bucket or time bucket when `split_hours` or `aggregate_unit` is enabled.",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/ResponderInsightItem"
             },
-            "type": "array"
+            "description": "Per-responder metric rows, newest bucket first. Responders without incidents in a bucket produce no row."
           }
-        },
-        "type": "object"
+        }
       },
       "ResponseEnvelope": {
+        "type": "object",
         "description": "Standard response envelope used by every Flashduty public API. On success `data` contains the endpoint-specific payload and `error` is absent. On failure `error` is present and `data` is absent. `request_id` is always present and is also mirrored in the `Flashcat-Request-Id` response header.",
         "properties": {
-          "data": {
-            "description": "Endpoint-specific payload. See each operation's 200 response schema."
+          "request_id": {
+            "type": "string",
+            "description": "Unique ID for this request. Mirrored in the Flashcat-Request-Id header. Include it when reporting issues.",
+            "example": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
           },
           "error": {
             "$ref": "#/components/schemas/DutyError"
           },
-          "request_id": {
-            "description": "Unique ID for this request. Mirrored in the Flashcat-Request-Id header. Include it when reporting issues.",
-            "example": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
-            "type": "string"
+          "data": {
+            "description": "Operation-specific payload, documented in each operation's 200 response. Operations without a payload return `{}` or omit `data` entirely."
           }
         },
         "required": [
           "request_id"
-        ],
-        "type": "object"
+        ]
       },
       "RevertRemoteConfigRequest": {
         "description": "Republish an earlier version's content under a new version number.",
         "properties": {
           "application_id": {
-            "description": "RUM application ID.",
+            "description": "RUM application ID. Get application IDs via `POST /rum/application/list`.",
             "type": "string"
           },
           "reason": {
-            "description": "Operator's note. The console fills in `rolled back to vN` when left empty.",
+            "description": "Optional free-text note (not an enum), at most 255 characters, stored verbatim and returned as `reason` by `POST /rum/application/remote-config/history/list`. The server does not fill it in when omitted.",
             "maxLength": 255,
             "type": "string"
           },
           "version": {
-            "description": "History version to republish.",
+            "description": "Version to restore. Must be one of the retained versions listed by `POST /rum/application/remote-config/history/list`.",
             "minimum": 1,
             "type": "integer"
           }
@@ -18517,53 +19138,53 @@
         "description": "Version created by the revert.",
         "properties": {
           "version": {
-            "description": "New version number created by the revert.",
+            "description": "New version number created by the revert (previous highest version + 1).",
             "type": "integer"
           }
         },
         "type": "object"
       },
       "RoleDeleteRequest": {
+        "type": "object",
+        "required": [
+          "role_id"
+        ],
         "description": "Request to delete a role.",
         "properties": {
-          "is_force": {
-            "default": false,
-            "description": "When false (default), deletion fails with a `ReferenceExist` error listing the members that still hold the role in `data.refs`. When true, the role is first revoked from all holders and then deleted.",
-            "type": "boolean"
-          },
           "role_id": {
-            "description": "Role ID to delete. Get IDs from `POST /role/list` (built-in roles: 2=Admin, 6=Responder, 8=Viewer).",
+            "type": "integer",
             "format": "uint64",
-            "type": "integer"
+            "description": "Role ID to delete. Get IDs from `POST /role/list` (built-in roles: 2=Admin, 6=Responder, 8=Viewer)."
+          },
+          "is_force": {
+            "type": "boolean",
+            "default": false,
+            "description": "When false (default), deletion fails with `ReferenceExist` while members still hold the role, listing them in `data.refs`. When true, the role is first revoked from all holders and then deleted. Does not bypass the SSO default-role check."
           }
-        },
+        }
+      },
+      "RoleGrantRequest": {
+        "type": "object",
         "required": [
+          "member_ids",
           "role_id"
         ],
-        "type": "object"
-      },
-      "RoleGrantRequest": {
         "description": "Request to grant or revoke a role from members.",
         "properties": {
           "member_ids": {
-            "description": "Member IDs to grant/revoke the role.",
+            "type": "array",
             "items": {
-              "format": "uint64",
-              "type": "integer"
+              "type": "integer",
+              "format": "uint64"
             },
-            "type": "array"
+            "description": "IDs of the members to grant the role to or revoke it from (from `POST /member/list`). All must be members of the account; duplicates are rejected."
           },
           "role_id": {
-            "description": "Role ID to grant or revoke. Get IDs from `POST /role/list`.",
+            "type": "integer",
             "format": "uint64",
-            "type": "integer"
+            "description": "Role ID to grant or revoke. Get IDs from `POST /role/list`."
           }
-        },
-        "required": [
-          "member_ids",
-          "role_id"
-        ],
-        "type": "object"
+        }
       },
       "RoleIDRequest": {
         "properties": {
@@ -18592,63 +19213,63 @@
         "type": "object"
       },
       "RoleItem": {
+        "type": "object",
         "description": "A role and its permission set.",
+        "required": [
+          "role_id",
+          "role_name",
+          "description",
+          "status",
+          "permission_ids",
+          "editable",
+          "created_at",
+          "updated_at"
+        ],
         "properties": {
-          "created_at": {
-            "description": "Unix epoch seconds the role was created.",
-            "format": "int64",
-            "type": "integer"
-          },
-          "description": {
-            "description": "Role description.",
-            "type": "string"
-          },
-          "editable": {
-            "description": "False for built-in roles which cannot be modified.",
-            "type": "boolean"
-          },
-          "permission_ids": {
-            "description": "IDs of permissions granted by this role.",
-            "items": {
-              "format": "uint64",
-              "type": "integer"
-            },
-            "type": "array"
-          },
           "role_id": {
-            "description": "Unique role ID.",
+            "type": "integer",
             "format": "uint64",
-            "type": "integer"
+            "description": "Role ID. Built-in roles use the fixed IDs `2` (Admin), `6` (Responder), and `8` (Viewer)."
           },
           "role_name": {
-            "description": "Role display name.",
-            "type": "string"
+            "type": "string",
+            "description": "Role name, unique in the account. The built-in roles are named `Admin`, `Responder`, and `Viewer` in every language."
+          },
+          "description": {
+            "type": "string",
+            "description": "Role description. For built-in roles it is localized by the request language."
           },
           "status": {
-            "description": "Role status.",
+            "type": "string",
             "enum": [
               "enabled",
               "disabled"
             ],
-            "type": "string"
+            "description": "Role status. `enabled` — active; `disabled` — turned off with `POST /role/disable`. Built-in roles are always `enabled`; deleted roles are never returned."
+          },
+          "permission_ids": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "uint64"
+            },
+            "description": "IDs of the permissions the role grants, in ascending order; resolve them with `POST /role/permission/list`. Empty array when none."
+          },
+          "editable": {
+            "type": "boolean",
+            "description": "`false` for the built-in roles (Admin, Responder, Viewer); `true` for custom roles."
+          },
+          "created_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Time the role was created, Unix timestamp in seconds. Built-in roles carry a fixed timestamp."
           },
           "updated_at": {
-            "description": "Unix epoch seconds the role was last updated.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Unix epoch seconds the role was last updated."
           }
-        },
-        "required": [
-          "role_id",
-          "role_name",
-          "description",
-          "status",
-          "permission_ids",
-          "editable",
-          "created_at",
-          "updated_at"
-        ],
-        "type": "object"
+        }
       },
       "RoleListRequest": {
         "description": "Filters for listing roles.",
@@ -18673,43 +19294,43 @@
         "type": "object"
       },
       "RoleListResponse": {
+        "type": "object",
         "description": "Role list result.",
+        "required": [
+          "total",
+          "items"
+        ],
         "properties": {
+          "total": {
+            "type": "integer",
+            "description": "Number of roles returned: custom roles plus the 3 built-in roles unless `no_global` is true."
+          },
           "items": {
-            "description": "Array of roles; includes account roles plus built-in global roles unless `no_global=true`; empty array when no results.",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/RoleItem"
             },
-            "type": "array"
-          },
-          "total": {
-            "description": "Total role count.",
-            "type": "integer"
+            "description": "Array of roles; includes account roles plus built-in global roles unless `no_global=true`; empty array when no results."
           }
-        },
-        "required": [
-          "total",
-          "items"
-        ],
-        "type": "object"
+        }
       },
       "RolePermissionListRequest": {
+        "type": "object",
         "description": "Filters for listing permissions.",
         "properties": {
           "role_ids": {
-            "description": "Filter to permissions granted to these roles.",
+            "type": "array",
             "items": {
-              "format": "uint64",
-              "type": "integer"
+              "type": "integer",
+              "format": "uint64"
             },
-            "type": "array"
+            "description": "Role IDs (built-in or custom) whose granted permissions to return or mark. IDs that do not exist are ignored."
           },
           "with_all": {
-            "description": "If true, return all permissions with is_granted set to indicate which are granted.",
-            "type": "boolean"
+            "type": "boolean",
+            "description": "When true, return every permission and use `is_granted` to mark the ones granted by `role_ids`. When false (default), return only the granted permissions."
           }
-        },
-        "type": "object"
+        }
       },
       "RolePermissionListResponse": {
         "description": "Permission list result.",
@@ -18728,37 +19349,37 @@
         "type": "object"
       },
       "RoleUpsertRequest": {
+        "type": "object",
+        "required": [
+          "role_name"
+        ],
         "description": "Parameters for creating or updating a custom role.",
         "properties": {
+          "role_id": {
+            "type": "integer",
+            "format": "uint64",
+            "description": "ID of the custom role to update. Omit or set to 0 to create a new role. Do not pass the built-in role IDs `2`, `6`, or `8`."
+          },
+          "role_name": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 39,
+            "description": "Role display name. 1–39 characters."
+          },
           "description": {
-            "description": "Role description.",
+            "type": "string",
             "maxLength": 499,
-            "type": "string"
+            "description": "Role description, up to 499 characters. Omitting it on update clears the stored description."
           },
           "permission_ids": {
-            "description": "Permission IDs to grant. Replaces the existing set.",
+            "type": "array",
             "items": {
-              "format": "uint64",
-              "type": "integer"
+              "type": "integer",
+              "format": "uint64"
             },
-            "type": "array"
-          },
-          "role_id": {
-            "description": "Role ID. Omit or set to 0 to create.",
-            "format": "uint64",
-            "type": "integer"
-          },
-          "role_name": {
-            "description": "Role display name. 1–39 characters.",
-            "maxLength": 39,
-            "minLength": 1,
-            "type": "string"
+            "description": "IDs of the permissions the role grants (from `POST /role/permission/list`). Replaces the existing set; omitting it or sending an empty array leaves the role with no permissions."
           }
-        },
-        "required": [
-          "role_name"
-        ],
-        "type": "object"
+        }
       },
       "RoleUpsertResponse": {
         "description": "Role create/update result.",
@@ -18780,177 +19401,177 @@
         "type": "object"
       },
       "RouteCase": {
+        "type": "object",
         "description": "A single case branch in the routing rule. When all of its conditions match, the alert is dispatched to the configured channels.",
+        "required": [
+          "if"
+        ],
         "properties": {
-          "channel_ids": {
-            "description": "Target channel IDs. Required when `routing_mode` is `standard` (or empty); returned as `null` for `name_mapping`.",
+          "if": {
+            "type": "array",
+            "description": "Conditions joined with AND; an empty list matches every event. Required.",
             "items": {
-              "format": "int64",
-              "type": "integer"
-            },
+              "$ref": "#/components/schemas/RouteMatchCondition"
+            }
+          },
+          "channel_ids": {
             "type": [
               "array",
               "null"
-            ]
-          },
-          "fallthrough": {
-            "description": "If `true`, evaluation continues to the next case after this one matches; otherwise matching stops at the first hit.",
-            "type": "boolean"
-          },
-          "if": {
-            "description": "List of match conditions that are AND-ed together.",
+            ],
             "items": {
-              "$ref": "#/components/schemas/RouteMatchCondition"
+              "type": "integer",
+              "format": "int64"
             },
-            "type": "array"
+            "description": "Target channel IDs. Required when `routing_mode` is `standard` (or empty); returned as `null` for `name_mapping`."
           },
-          "name_mapping_label": {
-            "description": "Label key whose value is used as the target channel name. Required when `routing_mode` is `name_mapping`.",
-            "type": "string"
+          "fallthrough": {
+            "type": "boolean",
+            "description": "When `true`, evaluation continues with the next case after this one matches and the channels of all matched cases are combined; when `false`, evaluation stops at this case."
           },
           "routing_mode": {
-            "description": "Routing mode. `standard` (default, also used when left empty) routes to the fixed channel IDs; `name_mapping` resolves channels by reading a label value from the alert event.",
+            "type": "string",
             "enum": [
               "standard",
               "name_mapping"
             ],
-            "type": "string"
+            "description": "Routing mode. `standard` routes to the fixed `channel_ids`; `name_mapping` routes to the enabled channel whose name equals the value of `name_mapping_label` on the event. An empty value is treated as `standard` and is omitted in responses."
+          },
+          "name_mapping_label": {
+            "type": "string",
+            "description": "Event field whose value is used as the target channel name, for example `labels.service`. Required when `routing_mode` is `name_mapping`; if no enabled channel has that name, the case adds no channel."
           }
-        },
-        "required": [
-          "if"
-        ],
-        "type": "object"
+        }
       },
       "RouteDefault": {
+        "type": "object",
         "description": "Default branch used when no case matches (or all matched cases yield no valid channels).",
         "properties": {
           "channel_ids": {
-            "description": "Channel IDs to fall back to.",
+            "type": "array",
             "items": {
-              "format": "int64",
-              "type": "integer"
+              "type": "integer",
+              "format": "int64"
             },
-            "type": "array"
+            "description": "Channels used when no case yields a channel. An empty list is treated as no default branch."
           }
-        },
-        "type": "object"
+        }
       },
       "RouteInfoRequest": {
+        "type": "object",
         "description": "Parameters for retrieving the routing rule of one integration.",
+        "required": [
+          "integration_id"
+        ],
         "properties": {
           "integration_id": {
-            "description": "Integration ID. Must be greater than 0.",
-            "exclusiveMinimum": 0,
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Shared integration ID, greater than 0; obtain it from `POST /integration/list`.",
+            "exclusiveMinimum": 0
           }
-        },
-        "required": [
-          "integration_id"
-        ],
-        "type": "object"
+        }
       },
       "RouteItem": {
-        "description": "Routing rule of an integration. Alerts are evaluated against `cases` in order; unmatched alerts fall through to `default`. Returns `null` when the integration has no configured rule.",
+        "type": "object",
+        "description": "Routing rule of a shared integration. Alerts are evaluated against `cases` in order; when no case yields a channel, `default` is used.",
+        "required": [
+          "version",
+          "updated_by",
+          "creator_id"
+        ],
         "properties": {
+          "integration_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Integration the rule belongs to."
+          },
           "cases": {
-            "description": "Ordered list of case branches.",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/RouteCase"
             },
-            "type": "array"
-          },
-          "created_at": {
-            "description": "Creation time, Unix timestamp in seconds.",
-            "format": "int64",
-            "type": "integer"
-          },
-          "creator_id": {
-            "description": "ID of the person who created the rule.",
-            "format": "int64",
-            "type": "integer"
-          },
-          "default": {
-            "$ref": "#/components/schemas/RouteDefault"
-          },
-          "deleted_at": {
-            "description": "Soft-delete timestamp, Unix seconds. Omitted when the rule is active.",
-            "format": "int64",
-            "type": "integer"
-          },
-          "integration_id": {
-            "description": "Integration the rule belongs to.",
-            "format": "int64",
-            "type": "integer"
+            "description": "Ordered list of case branches."
           },
           "sections": {
-            "description": "Optional sections that visually group cases.",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/RouteSection"
             },
-            "type": "array"
+            "description": "Optional sections that visually group cases."
+          },
+          "default": {
+            "$ref": "#/components/schemas/RouteDefault"
           },
           "status": {
-            "description": "Route status. `enabled` means active; `deleted` means removed, visible only in historical versions.",
+            "type": "string",
             "enum": [
               "enabled",
               "deleted"
             ],
-            "type": "string"
+            "description": "Rule status. These endpoints return only `enabled` rules; `deleted` rules (for example of a deleted integration) are not returned."
           },
-          "updated_at": {
-            "description": "Last update time, Unix timestamp in seconds.",
+          "version": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Version number, increased on every `POST /route/upsert`. The server does not use it for concurrency checks."
           },
           "updated_by": {
-            "description": "ID of the person who performed the last update.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "ID of the person who performed the last update."
           },
-          "version": {
-            "description": "Monotonic version number, incremented on each update. Use it for optimistic concurrency control.",
+          "creator_id": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "ID of the person who created the rule."
+          },
+          "deleted_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Soft-delete time, Unix timestamp in seconds. Not returned by these endpoints, which return only active rules."
+          },
+          "created_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Creation time, Unix timestamp in seconds."
+          },
+          "updated_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Last update time, Unix timestamp in seconds."
           }
-        },
-        "required": [
-          "version",
-          "updated_by",
-          "creator_id"
-        ],
-        "type": "object"
+        }
       },
       "RouteMatchCondition": {
+        "type": "object",
         "description": "A single match condition. All conditions inside one case form an AND group.",
+        "required": [
+          "key",
+          "oper",
+          "vals"
+        ],
         "properties": {
           "key": {
-            "description": "Field key to match against the alert event (e.g. `alert_severity`, `labels.service`).",
-            "type": "string"
+            "type": "string",
+            "description": "Alert or change event field to match: `title`, `description`, `severity` (alias `alert_severity`, `event_severity`), `status`, `alert_key`, `change_key`, `title_rule`, `integration_id` (alias `data_source_id`), or any `labels.<name>`. An unknown key returns `InvalidParameter`."
           },
           "oper": {
-            "description": "Match operator. `IN` matches when the field value is one of `vals`; `NOTIN` matches when it is not.",
+            "type": "string",
             "enum": [
               "IN",
               "NOTIN"
             ],
-            "type": "string"
+            "description": "Match operator. `IN` matches when the field value matches any entry in `vals`; `NOTIN` matches when it matches none. A missing field never matches `IN` and always matches `NOTIN`."
           },
           "vals": {
-            "description": "Values to compare against. Each value may be a literal string, a wildcard (`*`, `?`), a regular expression wrapped in slashes (`/pattern/`), a CIDR (`cidr:10.0.0.0/8`), or a numeric comparison (`num:lt:100`).",
+            "type": "array",
             "items": {
               "type": "string"
             },
-            "type": "array"
+            "description": "Values to compare, at least one. Each entry is matched as: an exact string; a wildcard pattern when it contains `*` or `?` (must match the whole value); a regular expression when wrapped in slashes, such as `/^db-/` (may match anywhere in the value); an IP range written `cidr:<network>`, such as `cidr:203.0.113.0/24`; or a numeric comparison `num:<op>:<number>` with `lt`, `le`, `gt` or `ge`, such as `num:gt:90`."
           }
-        },
-        "required": [
-          "key",
-          "oper",
-          "vals"
-        ],
-        "type": "object"
+        }
       },
       "RouteSection": {
         "description": "A logical section that groups consecutive cases for display purposes.",
@@ -19270,75 +19891,24 @@
         "type": "object"
       },
       "RuleFieldsUpdateRequest": {
+        "type": "object",
+        "required": [
+          "ids",
+          "fields"
+        ],
         "properties": {
-          "annotations": {
-            "additionalProperties": {
-              "type": "string"
-            },
-            "description": "Annotation key-value pairs delivered with alert events; keys must not start with `$` (reserved for query fields). Effective only when `fields` includes `annotations`.",
-            "type": "object"
-          },
-          "annotations_patch": {
-            "$ref": "#/components/schemas/StringMapPatch",
-            "description": "Partial annotation update. Effective only when `fields` includes `annotations`; takes precedence over `annotations` when both are sent."
-          },
-          "channel_ids": {
-            "description": "IDs of the collaboration spaces alerts are sent to; may be empty. Effective only when `fields` includes `channel_ids`.",
-            "items": {
-              "format": "uint64",
-              "type": "integer"
-            },
-            "type": "array"
-          },
-          "cron_pattern": {
-            "description": "Schedule expression: a 6-field cron (with seconds) or an `@every 30s` interval descriptor; `CRON_TZ=`/`TZ=` prefixes are not allowed. Effective only when `fields` includes `cron_pattern`.",
-            "type": "string"
-          },
-          "debug_log_enabled": {
-            "description": "Whether to enable debug logging; the edge emits detailed evaluation logs for troubleshooting. Effective only when `fields` includes `debug_log_enabled`.",
-            "type": "boolean"
-          },
-          "delay_seconds": {
-            "description": "Seconds to shift the evaluation query window backward, compensating for data ingestion latency. Effective only when `fields` includes `delay_seconds`.",
-            "type": "integer"
-          },
-          "description": {
-            "description": "Rule description (Markdown). Effective only when `fields` includes `description`.",
-            "type": "string"
-          },
-          "ds_ids": {
-            "description": "Datasource IDs, merged with `ds_list` to decide which datasources the rule monitors; IDs survive datasource renames. Effective only when `fields` includes `ds_ids`.",
-            "items": {
-              "format": "uint64",
-              "type": "integer"
-            },
-            "type": "array"
-          },
-          "ds_list": {
-            "description": "Datasource name match patterns; wildcards supported. Effective only when `fields` includes `ds_list`.",
-            "items": {
-              "type": "string"
-            },
-            "type": "array"
-          },
-          "ds_type": {
-            "description": "Datasource type identifier. Effective only when `fields` includes `ds_type`.",
-            "type": "string"
-          },
-          "enabled": {
-            "description": "Whether the rule is enabled. Setting it to `false` makes the server clean up the rule's active alerts. Effective only when `fields` includes `enabled`.",
-            "type": "boolean"
-          },
-          "enabled_times": {
-            "description": "Time windows during which the rule is in effect; element structure see `EnabledTime`. Effective only when `fields` includes `enabled_times`.",
+          "ids": {
+            "type": "array",
             "items": {
-              "$ref": "#/components/schemas/EnabledTime"
+              "type": "integer",
+              "format": "uint64"
             },
-            "type": "array"
+            "description": "IDs of the rules to update; must contain at least one ID."
           },
           "fields": {
-            "description": "Field names to update. Only listed fields are updated, taking new values from the same-named request fields; values for unlisted fields are silently ignored.",
+            "type": "array",
             "items": {
+              "type": "string",
               "enum": [
                 "labels",
                 "ds_type",
@@ -19355,51 +19925,102 @@
                 "channel_ids",
                 "repeat_interval",
                 "repeat_total"
-              ],
+              ]
+            },
+            "description": "Names of the fields to update. Each listed field takes the value of the same-named request field, and is set to its zero value when that value is omitted; values sent for unlisted fields are ignored. An unknown name fails the whole call with `InvalidParameter`."
+          },
+          "labels": {
+            "type": "object",
+            "additionalProperties": {
               "type": "string"
             },
-            "type": "array"
+            "description": "Custom label key-value pairs; replaces existing labels as a whole. Effective only when `fields` includes `labels`; cannot be sent together with `labels_patch`."
           },
-          "ids": {
-            "description": "Rule IDs to update.",
+          "ds_type": {
+            "type": "string",
+            "description": "Datasource type identifier. Enabled rules must use a type that supports alerting: `prometheus`, `elasticsearch`, `loki`, `clickhouse`, `mysql`, `oracle`, `postgres`, `sls`, `tencent_cls`, `victorialogs`. Effective only when `fields` includes `ds_type`."
+          },
+          "ds_list": {
+            "type": "array",
             "items": {
-              "format": "uint64",
-              "type": "integer"
+              "type": "string"
             },
-            "type": "array"
+            "description": "Datasource name match patterns; wildcards supported. Effective only when `fields` includes `ds_list`."
           },
-          "labels": {
+          "ds_ids": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "uint64"
+            },
+            "description": "Datasource IDs, merged with `ds_list` to decide which datasources the rule monitors; IDs survive datasource renames. Effective only when `fields` includes `ds_ids`."
+          },
+          "enabled": {
+            "type": "boolean",
+            "description": "Whether the rule is enabled. Setting it to `false` makes the server clean up the rule's active alerts. Effective only when `fields` includes `enabled`."
+          },
+          "debug_log_enabled": {
+            "type": "boolean",
+            "description": "Whether to enable debug logging; the edge emits detailed evaluation logs for troubleshooting. Effective only when `fields` includes `debug_log_enabled`."
+          },
+          "cron_pattern": {
+            "type": "string",
+            "description": "Schedule expression: a 6-field cron (with seconds) or an `@every 30s` interval descriptor; `CRON_TZ=`/`TZ=` prefixes are not allowed. Effective only when `fields` includes `cron_pattern`."
+          },
+          "timezone": {
+            "type": "string",
+            "description": "Timezone the rule runs in, as an IANA name (e.g. `Asia/Shanghai`, `UTC`); empty falls back to `Asia/Shanghai`. Effective only when `fields` includes `timezone`.",
+            "default": "Asia/Shanghai"
+          },
+          "delay_seconds": {
+            "type": "integer",
+            "description": "Seconds to shift the evaluation query window backward, compensating for data ingestion latency. Effective only when `fields` includes `delay_seconds`."
+          },
+          "enabled_times": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/EnabledTime"
+            },
+            "description": "Time windows during which the rule is in effect; element structure see `EnabledTime`. Effective only when `fields` includes `enabled_times`."
+          },
+          "annotations": {
+            "type": "object",
             "additionalProperties": {
               "type": "string"
             },
-            "description": "Custom label key-value pairs; replaces existing labels as a whole. Effective only when `fields` includes `labels`.",
-            "type": "object"
+            "description": "Annotation key-value pairs delivered with alert events; replaces existing annotations as a whole, and keys must not start with `$` (reserved for query fields). Effective only when `fields` includes `annotations`; cannot be sent together with `annotations_patch`."
           },
-          "labels_patch": {
-            "$ref": "#/components/schemas/StringMapPatch",
-            "description": "Partial label update. Effective only when `fields` includes `labels`; takes precedence over `labels` when both are sent."
+          "description": {
+            "type": "string",
+            "description": "Rule description, rendered according to the rule's existing `description_type` (which this endpoint cannot change). Effective only when `fields` includes `description`."
+          },
+          "channel_ids": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "uint64"
+            },
+            "description": "IDs of the collaboration spaces alerts are sent to; may be empty. Effective only when `fields` includes `channel_ids`."
           },
           "repeat_interval": {
-            "description": "Interval in seconds between repeated alert notifications. Effective only when `fields` includes `repeat_interval`.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Interval in seconds between repeated alert notifications; values below 1 fall back to 3600, maximum 2147483647. Effective only when `fields` includes `repeat_interval`."
           },
           "repeat_total": {
-            "description": "Maximum number of repeated notifications. Effective only when `fields` includes `repeat_total`.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Maximum number of repeated notifications; values below 1 fall back to 3, maximum 2147483647. Effective only when `fields` includes `repeat_total`."
           },
-          "timezone": {
-            "default": "Asia/Shanghai",
-            "description": "Timezone in which the rule executes. IANA timezone name; defaults to `Asia/Shanghai`.",
-            "type": "string"
+          "labels_patch": {
+            "$ref": "#/components/schemas/StringMapPatch",
+            "description": "Partial label update that keeps unmentioned labels. Requires `labels` in `fields` and cannot be sent together with `labels`; otherwise the call returns `InvalidParameter`."
+          },
+          "annotations_patch": {
+            "$ref": "#/components/schemas/StringMapPatch",
+            "description": "Partial annotation update that keeps unmentioned annotations. Requires `annotations` in `fields` and cannot be sent together with `annotations`; otherwise the call returns `InvalidParameter`."
           }
-        },
-        "required": [
-          "ids",
-          "fields"
-        ],
-        "type": "object"
+        }
       },
       "RuleIDRequest": {
         "properties": {
@@ -19415,20 +20036,20 @@
         "type": "object"
       },
       "RuleIDsRequest": {
+        "type": "object",
+        "required": [
+          "ids"
+        ],
         "properties": {
           "ids": {
-            "description": "Rule IDs.",
+            "type": "array",
             "items": {
-              "format": "uint64",
-              "type": "integer"
+              "type": "integer",
+              "format": "uint64"
             },
-            "type": "array"
+            "description": "IDs of the alert rules to delete; must contain at least one ID. Get them from `POST /monit/rule/list/basic`."
           }
-        },
-        "required": [
-          "ids"
-        ],
-        "type": "object"
+        }
       },
       "RuleImportRequest": {
         "description": "Array of alert rule export objects to import.",
@@ -19445,51 +20066,51 @@
         "type": "array"
       },
       "RuleListRequest": {
+        "type": "object",
         "description": "Filter parameter for listing rules in a folder.",
         "properties": {
           "folder_id": {
-            "description": "Folder ID. Must be an existing folder; `0` is rejected with a `folder_not_found` error.",
+            "type": "integer",
             "format": "uint64",
-            "type": "integer"
+            "description": "ID of the folder to list. Must be an existing folder the caller can manage; `0` or an unknown ID returns `InvalidParameter`."
           },
           "include_descendants": {
-            "description": "Also include rules from all descendant folders. When `true`, each returned item carries only `id`, `folder_id` and `name`; combine with `query` / `limit` for rule-picker scenarios.",
-            "type": "boolean"
+            "type": "boolean",
+            "description": "Also search all descendant folders. When `true`, results are sorted by name, capped by `limit`, and each item fills only `id`, `folder_id` and `name` (other fields carry zero values); combine with `query` for rule-picker scenarios."
+          },
+          "query": {
+            "type": "string",
+            "description": "Filter by rule name substring; a numeric value also matches the rule with that ID. Only effective when `include_descendants` is `true`."
           },
           "limit": {
+            "type": "integer",
             "default": 50,
-            "description": "Max number of rules returned; only effective when `include_descendants` is `true`. Defaults to 50, capped at 100.",
             "maximum": 100,
-            "type": "integer"
-          },
-          "query": {
-            "description": "Rule name fuzzy filter; only effective when `include_descendants` is `true`.",
-            "type": "string"
+            "description": "Max number of rules returned; only effective when `include_descendants` is `true`. Defaults to 50, capped at 100."
           }
-        },
-        "type": "object"
+        }
       },
       "RuleMoveRequest": {
+        "type": "object",
+        "required": [
+          "ids",
+          "dest_folder_id"
+        ],
         "properties": {
-          "dest_folder_id": {
-            "description": "Destination folder ID. Obtainable via `POST /monit/folder/list`.",
-            "format": "uint64",
-            "type": "integer"
-          },
           "ids": {
-            "description": "Rule IDs to move.",
+            "type": "array",
             "items": {
-              "format": "uint64",
-              "type": "integer"
+              "type": "integer",
+              "format": "uint64"
             },
-            "type": "array"
+            "description": "IDs of the rules to move; must contain at least one ID."
+          },
+          "dest_folder_id": {
+            "type": "integer",
+            "format": "uint64",
+            "description": "Destination folder ID, from `POST /monit/folder/list`. Must be non-zero; a folder that does not exist or that the caller cannot manage fails the whole call with `AccessDenied`."
           }
-        },
-        "required": [
-          "ids",
-          "dest_folder_id"
-        ],
-        "type": "object"
+        }
       },
       "RuleNameMessageListResponse": {
         "description": "Per-rule batch-operation results.",
@@ -19502,12 +20123,15 @@
         "description": "Alert settings for the application.",
         "properties": {
           "channel_ids": {
-            "description": "Channel IDs to send alerts to. Used only when `delivery_mode` is `oncall`.",
+            "description": "On-call channel IDs that receive the alerts; used only when `delivery_mode` is `oncall`. Kept as a draft in `webhook` mode. Can be `null` when never set.",
             "items": {
               "format": "int64",
               "type": "integer"
             },
-            "type": "array"
+            "type": [
+              "array",
+              "null"
+            ]
           },
           "delivery_mode": {
             "description": "Alert delivery channel: `oncall` routes alert events through Flashduty On-call, `webhook` POSTs them directly to `webhook_url`. An empty value is treated as `oncall`, and on create/update it is persisted as the deployment default (`webhook` on RUM-only on-premises deployments, `oncall` otherwise). Omitted when empty (legacy rows).",
@@ -19518,7 +20142,7 @@
             "type": "string"
           },
           "enabled": {
-            "description": "Whether alerting is enabled.",
+            "description": "Whether alerting is on. `false` turns alerting off; with `false`, `webhook_url` is not checked.",
             "type": "boolean"
           },
           "integration_id": {
@@ -19527,7 +20151,7 @@
             "type": "integer"
           },
           "webhook_url": {
-            "description": "URL that receives alert events when `delivery_mode` is `webhook`; required in that mode, ignored otherwise. Omitted when empty.",
+            "description": "URL that receives alert events when `delivery_mode` is `webhook`. Required in that mode while `enabled` is `true`; must use `http` or `https`, and on Flashduty cloud must not resolve to a private, loopback, link-local or reserved address. Ignored in `oncall` mode. Omitted from responses when empty.",
             "format": "uri",
             "type": "string"
           }
@@ -19551,7 +20175,7 @@
             "type": "string"
           },
           "is_private": {
-            "description": "Restrict access to team members only.",
+            "description": "If `true`, only the account owner, account admins, the creator and members of the owning team can see or edit the application. Default `false`.",
             "type": "boolean"
           },
           "links": {
@@ -19567,11 +20191,11 @@
             "description": "Source code repositories to link, in order; the first entry is the primary repository. At most 10 entries."
           },
           "no_geo": {
-            "description": "Do not infer geographic location.",
+            "description": "If `true`, geographic location is not inferred from the client IP. Default `false`.",
             "type": "boolean"
           },
           "no_ip": {
-            "description": "Do not collect IP addresses.",
+            "description": "If `true`, client IP addresses are not collected. Default `false`.",
             "type": "boolean"
           },
           "team_id": {
@@ -19582,7 +20206,7 @@
           },
           "tracing": {
             "$ref": "#/components/schemas/RumApplicationTracing",
-            "description": "Optional APM tracing integration configuration."
+            "description": "Optional APM tracing integration configuration. Stored as empty (`enabled: false`, empty `open_type` and `endpoint`) when omitted."
           },
           "type": {
             "description": "Platform identifier:\n\n| Value | Meaning |\n|---|---|\n| `browser` | Web browser application (JavaScript SDK) |\n| `ios` | Apple iOS application |\n| `android` | Android application |\n| `react-native` | React Native application |\n| `flutter` | Flutter application |\n| `kotlin-multiplatform` | Kotlin Multiplatform application |\n| `roku` | Roku channel application |\n| `unity` | Unity application |\n| `miniprogram` | WeChat mini program |\n| `harmony` | HarmonyOS application |\n| `electron` | Electron desktop application |",
@@ -19613,7 +20237,7 @@
         "description": "Result of creating a RUM application.",
         "properties": {
           "application_id": {
-            "description": "Auto-generated unique application ID.",
+            "description": "Server-generated application ID (22-character short UUID); pass it as `application_id` to the other application operations.",
             "type": "string"
           },
           "application_name": {
@@ -19621,11 +20245,16 @@
             "type": "string"
           },
           "client_token": {
-            "description": "Token for RUM SDK initialization.",
+            "description": "Token used to initialize the RUM SDK. Also returned by `POST /rum/application/info`.",
             "type": "string"
           }
         },
-        "type": "object"
+        "type": "object",
+        "required": [
+          "application_id",
+          "application_name",
+          "client_token"
+        ]
       },
       "RumApplicationIDRequest": {
         "description": "Request with a single application ID.",
@@ -19644,7 +20273,7 @@
         "description": "Batch application info request.",
         "properties": {
           "application_ids": {
-            "description": "Up to 200 application IDs. Get IDs via `POST /rum/application/list`.",
+            "description": "Up to 200 application IDs. Duplicates are collapsed, and unknown or deleted IDs are skipped. Get IDs via `POST /rum/application/list`.",
             "items": {
               "type": "string"
             },
@@ -19661,26 +20290,29 @@
         "description": "Batch application info response.",
         "properties": {
           "items": {
-            "description": "Application info items matching the requested `application_ids` (max 200, deduplicated).",
+            "description": "Applications found among the requested `application_ids`, in no guaranteed order. Empty array when none match.",
             "items": {
               "$ref": "#/components/schemas/RumApplicationItem"
             },
             "type": "array"
           }
         },
-        "type": "object"
+        "type": "object",
+        "required": [
+          "items"
+        ]
       },
       "RumApplicationItem": {
         "description": "A RUM application.",
         "properties": {
           "account_id": {
-            "description": "Account ID.",
+            "description": "ID of the Flashduty account that owns the application.",
             "format": "int64",
             "type": "integer"
           },
           "alerting": {
             "$ref": "#/components/schemas/RumApplicationAlerting",
-            "description": "Alerting configuration of the application."
+            "description": "Alerting configuration of the application. Always an object."
           },
           "application_id": {
             "description": "Unique application ID.",
@@ -19700,17 +20332,17 @@
             "type": "integer"
           },
           "created_by": {
-            "description": "Creator member ID.",
+            "description": "Member ID of the creator. The creator can always edit the application.",
             "format": "int64",
             "type": "integer"
           },
           "is_private": {
-            "description": "If `true`, the application is only accessible to team members.",
+            "description": "If `true`, only the account owner, account admins, the creator and members of the owning team can see or edit the application.",
             "type": "boolean"
           },
           "links": {
             "$ref": "#/components/schemas/RumApplicationLinks",
-            "description": "External-link integration configuration."
+            "description": "External-link integration configuration. Always an object; `systems` can be `null` when no system was ever saved."
           },
           "repositories": {
             "type": "array",
@@ -19718,7 +20350,7 @@
               "$ref": "#/components/schemas/RumApplicationRepository"
             },
             "maxItems": 10,
-            "description": "Linked source code repositories, in order; the first entry is the primary repository. Linking grants no access by itself: AI sessions can only read repositories granted to the account's GitHub App installations."
+            "description": "Linked source code repositories, in order; the first entry is the primary repository. Empty array when none are linked. Linking grants no access by itself: AI sessions can only read repositories granted to the account's GitHub App installations."
           },
           "no_geo": {
             "description": "If `true`, geographic location is not inferred from IP.",
@@ -19729,7 +20361,7 @@
             "type": "boolean"
           },
           "status": {
-            "description": "Application status. One of `enabled` (active, receiving data), `disabled` (deactivated), `deleted` (soft-delete marker; every query filters it out, so it never actually appears in responses).",
+            "description": "Application status:\n\n- `enabled`: the SDK `client_token` is accepted and data is collected. Every application created through the API starts in this state.\n- `disabled`: the `client_token` is rejected, so no new data is collected. No public operation sets this status.\n- `deleted`: soft-delete marker; deleted applications are filtered out of every response, so this value is never returned.",
             "enum": [
               "enabled",
               "disabled",
@@ -19738,13 +20370,13 @@
             "type": "string"
           },
           "team_id": {
-            "description": "Owning team ID.",
+            "description": "Owning team ID. Members of this team can edit the application and, when it is private, see it.",
             "format": "int64",
             "type": "integer"
           },
           "tracing": {
             "$ref": "#/components/schemas/RumApplicationTracing",
-            "description": "APM tracing integration configuration."
+            "description": "APM tracing integration configuration. Always an object; when tracing was never configured it is `enabled: false` with empty `open_type` and `endpoint`."
           },
           "type": {
             "description": "Platform identifier:\n\n| Value | Meaning |\n|---|---|\n| `browser` | Web browser application (JavaScript SDK) |\n| `ios` | Apple iOS application |\n| `android` | Android application |\n| `react-native` | React Native application |\n| `flutter` | Flutter application |\n| `kotlin-multiplatform` | Kotlin Multiplatform application |\n| `roku` | Roku channel application |\n| `unity` | Unity application |\n| `miniprogram` | WeChat mini program |\n| `harmony` | HarmonyOS application |\n| `electron` | Electron desktop application |",
@@ -19774,13 +20406,33 @@
             "type": "integer"
           }
         },
-        "type": "object"
+        "type": "object",
+        "required": [
+          "account_id",
+          "application_id",
+          "application_name",
+          "type",
+          "client_token",
+          "team_id",
+          "is_private",
+          "no_ip",
+          "no_geo",
+          "alerting",
+          "tracing",
+          "links",
+          "repositories",
+          "status",
+          "created_by",
+          "updated_by",
+          "created_at",
+          "updated_at"
+        ]
       },
       "RumApplicationLink": {
         "description": "External system link rendered on matching RUM event detail pages.",
         "properties": {
           "enabled": {
-            "description": "Whether this external system link is enabled.",
+            "description": "Whether this external system link is shown. Treated as `false` when omitted.",
             "type": "boolean"
           },
           "event_types": {
@@ -19801,15 +20453,15 @@
             "type": "array"
           },
           "icon_color": {
-            "description": "Display color for the link icon.",
+            "description": "Display color for the link icon, e.g. `#0F766E`. Omitted from responses when empty.",
             "type": "string"
           },
           "icon_text": {
-            "description": "Short text shown in the link icon.",
+            "description": "Short text shown in the link icon, e.g. `S3`. Omitted from responses when empty.",
             "type": "string"
           },
           "id": {
-            "description": "Stable client-side identifier for this external system.",
+            "description": "Client-chosen identifier for this external system, kept as sent; the server does not validate it.",
             "type": "string"
           },
           "name": {
@@ -19834,7 +20486,7 @@
         "description": "External link integration settings for the application.",
         "properties": {
           "enabled": {
-            "description": "Whether external link integration is enabled.",
+            "description": "Master switch for the external-link integration. Treated as `false` when omitted.",
             "type": "boolean"
           },
           "systems": {
@@ -19857,11 +20509,11 @@
         "description": "Filters for listing RUM applications.",
         "properties": {
           "asc": {
-            "description": "Sort ascending if `true`.",
+            "description": "Sort ascending if `true`; default `false` (descending).",
             "type": "boolean"
           },
           "is_my_team": {
-            "description": "If `true`, return only applications belonging to the current user's teams.",
+            "description": "If `true`, return only applications owned by teams the caller belongs to. Has no effect when the caller belongs to no team.",
             "type": "boolean"
           },
           "limit": {
@@ -19884,7 +20536,7 @@
             "type": "integer"
           },
           "query": {
-            "description": "Substring match on the application name.",
+            "description": "Substring match on the application name (SQL `LIKE`, so `%` and `_` act as wildcards).",
             "type": "string"
           },
           "team_id": {
@@ -19903,7 +20555,7 @@
             "type": "boolean"
           },
           "items": {
-            "description": "RUM applications of the current page.",
+            "description": "RUM applications on the current page. Empty array when nothing matches.",
             "items": {
               "$ref": "#/components/schemas/RumApplicationItem"
             },
@@ -19914,24 +20566,30 @@
             "type": "integer"
           }
         },
-        "type": "object"
+        "type": "object",
+        "required": [
+          "has_next_page",
+          "total",
+          "items"
+        ]
       },
       "RumApplicationTracing": {
         "description": "APM tracing integration settings.",
         "properties": {
           "enabled": {
-            "description": "Whether tracing integration is enabled.",
+            "description": "Whether trace links are shown on RUM events.",
             "type": "boolean"
           },
           "endpoint": {
-            "description": "Trace endpoint URL (http or https).",
+            "description": "Trace endpoint URL; must start with `http` or `https`. Required whenever `tracing` is sent, even with `enabled: false`. Empty in responses when tracing was never configured.",
             "type": "string"
           },
           "open_type": {
-            "description": "How to open the trace link. One of `popup` (open trace details in a popup) or `tab` (open in a new browser tab).",
+            "description": "How the trace link opens:\n\n- `popup`: open trace details in a popup.\n- `tab`: open them in a new browser tab.\n- `\"\"` (empty): returned only when tracing was never configured; rejected in requests.",
             "enum": [
               "popup",
-              "tab"
+              "tab",
+              ""
             ],
             "type": "string"
           }
@@ -19948,7 +20606,7 @@
         "properties": {
           "alerting": {
             "$ref": "#/components/schemas/RumApplicationAlerting",
-            "description": "Alerting configuration. Omit to leave unchanged.",
+            "description": "Alerting configuration. When sent, it replaces the stored alerting object (except `integration_id`, which the server manages). Omit to leave unchanged.",
             "x-flashduty-preserve-absence": true
           },
           "application_id": {
@@ -19965,7 +20623,7 @@
             ]
           },
           "is_private": {
-            "description": "Restrict access to members of the owning team; `false` explicitly makes the application public. Omit to leave unchanged.",
+            "description": "`true` limits access to the account owner, account admins, the creator and members of the owning team; `false` makes the application visible to everyone in the account. Omit to leave unchanged.",
             "type": [
               "boolean",
               "null"
@@ -19973,7 +20631,7 @@
           },
           "links": {
             "$ref": "#/components/schemas/RumApplicationLinks",
-            "description": "External-link integration configuration. Omit to leave unchanged.",
+            "description": "External-link integration configuration. When sent, it replaces the stored object, including the whole `systems` list. Omit to leave unchanged.",
             "x-flashduty-preserve-absence": true
           },
           "repositories": {
@@ -20000,7 +20658,7 @@
             ]
           },
           "team_id": {
-            "description": "Owning team ID. Get team IDs via `POST /team/list`. Omit to leave unchanged.",
+            "description": "New owning team ID. Get team IDs via `POST /team/list`. Omit to leave unchanged. Moving the application to another team changes who can edit it.",
             "exclusiveMinimum": 0,
             "format": "int64",
             "type": [
@@ -20010,7 +20668,7 @@
           },
           "tracing": {
             "$ref": "#/components/schemas/RumApplicationTracing",
-            "description": "APM tracing integration configuration. Omit to leave unchanged."
+            "description": "APM tracing integration configuration. When sent, it replaces the stored object and must carry a valid `open_type` and `endpoint`. Omit to leave unchanged."
           },
           "type": {
             "description": "Application type. Omit to leave unchanged. Platform identifier:\n\n| Value | Meaning |\n|---|---|\n| `browser` | Web browser application (JavaScript SDK) |\n| `ios` | Apple iOS application |\n| `android` | Android application |\n| `react-native` | React Native application |\n| `flutter` | Flutter application |\n| `kotlin-multiplatform` | Kotlin Multiplatform application |\n| `roku` | Roku channel application |\n| `unity` | Unity application |\n| `miniprogram` | WeChat mini program |\n| `harmony` | HarmonyOS application |\n| `electron` | Electron desktop application |",
@@ -20042,15 +20700,15 @@
         "description": "Metadata for one returned column.",
         "properties": {
           "name": {
-            "description": "Column name.",
+            "description": "Column name or alias as written in `sql`; `ts` for the bucket column of `time_series` queries.",
             "type": "string"
           },
           "nullable": {
-            "description": "Whether values in this column may be null.",
+            "description": "Whether values in this column may be `null`. `true` when the driver cannot tell.",
             "type": "boolean"
           },
           "type": {
-            "description": "Backend database type name for this column.",
+            "description": "Column type name as reported by the database driver, such as `VARCHAR`, `BIGINT`, `DOUBLE` or `DATETIME`. It depends on the selected column or expression, so the set is open; use it as a hint for parsing `values`.",
             "type": "string"
           }
         },
@@ -20065,11 +20723,11 @@
         "description": "One RUM data query definition.",
         "properties": {
           "disable_sampling": {
-            "description": "When true, asks the query engine to avoid sampling when possible.",
+            "description": "When `true`, the query always runs on the full data and the response never carries `sampling`. When `false` (default), the server may sample aggregate queries over large time windows.",
             "type": "boolean"
           },
           "dql": {
-            "description": "Optional RUM DQL filter expression used together with SQL validation.",
+            "description": "Optional RUM DQL filter. It is translated and `AND`-ed into the `WHERE` clause of `sql`. A DQL parse error is reported in this query's `error` entry.",
             "type": "string"
           },
           "format": {
@@ -20087,28 +20745,28 @@
           },
           "interval": {
             "default": 3600,
-            "description": "Time bucket interval in seconds for `time_series` queries.",
+            "description": "Minimum time-bucket width in **milliseconds** for `time_series` queries. Default 3600 (3.6 seconds). The effective width is the smallest step of a fixed ladder that is at least this value and at least the window length divided by `max_points`; it is returned as `interval`. Ignored for `table` queries.",
             "exclusiveMinimum": 0,
             "format": "int64",
             "type": "integer"
           },
           "max_points": {
             "default": 1226,
-            "description": "Maximum number of points for `time_series` queries.",
+            "description": "Upper bound on the number of buckets for `time_series` queries. Default 1226. The bucket width grows so that the window holds at most this many buckets. Ignored for `table` queries.",
             "exclusiveMinimum": 0,
             "format": "int64",
             "type": "integer"
           },
           "search_after_ctx": {
-            "description": "Opaque cursor returned by a previous table query for continuing pagination.",
+            "description": "Cursor from a previous response's `search_after_ctx`, to fetch the next page of the same `table` query. Only used by non-aggregate queries with `ORDER BY` and no `OFFSET`. An invalid value makes this query fail.",
             "type": "string"
           },
           "sql": {
-            "description": "RUM SQL query to execute.",
+            "description": "RUM SQL `SELECT` statement. `FROM` names a scope table (`sessions`, `views`, `actions`, `errors`, `resources`, `long_tasks`, `vitals`, `issues`, `sourcemaps`); columns are `field_key` values from `POST /rum/field/list`. The server adds the account and time-range filters.",
             "type": "string"
           },
           "time_zone": {
-            "description": "IANA time zone name used when evaluating time functions, such as `Asia/Shanghai`.",
+            "description": "IANA time zone name, such as `Asia/Shanghai`, used to align `time_series` bucket boundaries to local time. Defaults to UTC alignment. Ignored for `table` queries; an unknown name fails the request with `InvalidParameter`.",
             "type": "string"
           }
         },
@@ -20128,7 +20786,7 @@
           },
           "error": {
             "$ref": "#/components/schemas/DutyError",
-            "description": "Subquery failure details. Omitted when the query succeeded."
+            "description": "Set when this query failed after request validation (unknown table or column, invalid `dql` or `search_after_ctx`, database error). The code is always `InternalError`. Omitted when the query succeeded."
           }
         },
         "type": "object"
@@ -20176,14 +20834,14 @@
         "description": "Rows and metadata returned by one RUM data query.",
         "properties": {
           "fields": {
-            "description": "Column metadata for the values matrix.",
+            "description": "Column metadata, one entry per returned column, in the same order as `values`. For `time_series` queries the first column is `ts`.",
             "items": {
               "$ref": "#/components/schemas/RumDataFieldMeta"
             },
             "type": "array"
           },
           "interval": {
-            "description": "Effective time bucket interval in seconds. Omitted for `table`-format queries.",
+            "description": "Effective time-bucket width in **milliseconds** used by a `time_series` query. Omitted for `table` queries.",
             "format": "int64",
             "type": "integer"
           },
@@ -20192,14 +20850,17 @@
             "description": "Sampling metadata. Omitted when the query did not use sampling."
           },
           "search_after_ctx": {
-            "description": "Opaque cursor for continuing paginated table queries. Omitted when the query is not a cursor-paginated table query or no further pages exist.",
+            "description": "Cursor for the next page of a non-aggregate `table` query with `ORDER BY` and no `OFFSET`. Present only when this page returned as many rows as the `LIMIT`; omitted otherwise.",
             "type": "string"
           },
           "values": {
-            "description": "Rows returned by the query. Each row aligns with `fields` by index.",
+            "description": "Result values in column-major order: `values[i]` is the list of every row's value for column `fields[i]`. A column is `null` when the query returned no rows. Datetime values are returned as RFC 3339 strings.",
             "items": {
               "items": {},
-              "type": "array"
+              "type": [
+                "array",
+                "null"
+              ]
             },
             "type": "array"
           }
@@ -20218,7 +20879,7 @@
             "type": "boolean"
           },
           "scale_factor": {
-            "description": "Multiplier used to scale sampled counts back to estimated full counts.",
+            "description": "Multiplier applied to scale sampled results back to estimated full values. `COUNT`, `SUM` and `COUNT(DISTINCT)` columns in `values` are already multiplied by it; other aggregates are returned as computed on the sample.",
             "type": "number"
           }
         },
@@ -20236,13 +20897,13 @@
             "type": "string"
           },
           "description": {
-            "description": "Rule description, up to 512 characters.",
+            "description": "Rule description, up to 512 characters. Defaults to an empty string.",
             "maxLength": 512,
             "type": "string"
           },
           "filters": {
             "$ref": "#/components/schemas/RumErrorIngestionOrFilters",
-            "description": "Filter conditions (OR-of-ANDs) to match errors; matched errors are dropped and not ingested."
+            "description": "Conditions (OR-of-ANDs) that select errors. A matched error is still stored but is not grouped into any issue."
           },
           "rule_name": {
             "description": "Rule name, 1-128 characters.",
@@ -20285,11 +20946,11 @@
         "description": "A single filter condition matched against one error field.",
         "properties": {
           "key": {
-            "description": "Field key. One of `error.usr_id`, `error.usr_email`, `error.error_type`, `error.error_message`, `error.error_stack`, `error.view_url`, `error.env`, `error.version`, `error.service`, `error.browser_name`, `error.browser_version`, `error.fingerprint`, `error.is_crash`, or a `context.`-prefixed custom context path (up to 3 levels deep).",
+            "description": "Field to match. One of `error.usr_id`, `error.usr_email`, `error.error_type`, `error.error_message`, `error.error_stack`, `error.view_url`, `error.env`, `error.version`, `error.service`, `error.browser_name`, `error.browser_version`, `error.fingerprint`, `error.is_crash` (value `true` or `false`), or a `context.`-prefixed path into the error's custom context. Context objects are flattened with dots up to 3 levels (`context.a.b.c`); a deeper object is compared as its JSON text, and array values can't be matched.",
             "type": "string"
           },
           "oper": {
-            "description": "Match mode: `IN` matches when the field value matches any entry in `vals`; `NOTIN` matches when it matches none.",
+            "description": "Match mode:\n- `IN`: matches when the field value matches any entry in `vals`. A context field the error doesn't carry never matches.\n- `NOTIN`: matches when the field value matches none of `vals`. A context field the error doesn't carry always matches.",
             "enum": [
               "IN",
               "NOTIN"
@@ -20297,7 +20958,7 @@
             "type": "string"
           },
           "vals": {
-            "description": "Values to match against, at least 1 entry. Each entry is an exact string, or a special pattern using wildcards (`*`/`?`), a regexp wrapped in `/`, a `cidr:`-prefixed CIDR match, or a `num:lt|le|gt|ge:`-prefixed numeric comparison.",
+            "description": "Values to match against, at least 1 entry. Each entry is one of: an exact, case-sensitive string; a wildcard pattern using `*`/`?` that must match the whole value; a regexp wrapped in `/` (matches anywhere in the value unless anchored); `cidr:<range>` (the value is parsed as an IP); or `num:lt|le|gt|ge:<number>` (the value is parsed as a number, non-numeric values don't match).",
             "items": {
               "type": "string"
             },
@@ -20316,28 +20977,28 @@
         "description": "A snapshot of every rule for the application at one history version.",
         "properties": {
           "rules": {
-            "description": "The application's complete rule list as of this version.",
+            "description": "The application's complete non-deleted rule list as it was just before the change that created this version. Empty for the version created by the application's first rule.",
             "items": {
               "$ref": "#/components/schemas/RumErrorIngestionRuleSnapshotItem"
             },
             "type": "array"
           },
           "updated_at": {
-            "description": "Unix timestamp in milliseconds when this snapshot was recorded.",
+            "description": "Time of the change that created this version, as a Unix timestamp in milliseconds.",
             "format": "int64",
             "type": "integer"
           },
           "updated_by": {
-            "description": "Member ID whose action triggered this snapshot.",
+            "description": "Member ID of the person who made the change that created this version.",
             "format": "int64",
             "type": "integer"
           },
           "updated_by_name": {
-            "description": "Display name of the member whose action triggered this snapshot.",
+            "description": "Display name of that member at the time of the change.",
             "type": "string"
           },
           "version": {
-            "description": "History version number, incrementing from 1.",
+            "description": "History version number, starting at 1 and incremented by every write. Pass it to `POST /rum/error-ingestion/rules/history/revert`.",
             "type": "integer"
           }
         },
@@ -20359,20 +21020,23 @@
           },
           "asc": {
             "default": false,
-            "description": "Sort ascending instead of the default descending order.",
+            "description": "`true` sorts ascending; `false` (default) sorts descending, newest first.",
             "type": "boolean"
           },
           "limit": {
             "default": 20,
-            "description": "Page size. Default 20, capped at 100; values ≤ 0 fall back to the default.",
+            "description": "Page size. Default 20; values above 100 are clamped to 100, and values of 0 or below fall back to 20.",
             "format": "int64",
-            "maximum": 100,
             "type": "integer"
           },
           "orderby": {
             "default": "updated_at",
-            "description": "Sort column: `updated_at` or `version`. Unrecognized values fall back to `updated_at`.",
-            "type": "string"
+            "description": "Sort column:\n- `updated_at`: time of the change that created the version (default).\n- `version`: version number.\nAny other value falls back to `updated_at`.",
+            "type": "string",
+            "enum": [
+              "updated_at",
+              "version"
+            ]
           },
           "p": {
             "default": 0,
@@ -20391,7 +21055,7 @@
         "description": "Paginated error ingestion rule history.",
         "properties": {
           "has_next_page": {
-            "description": "Whether another page of history exists after this one.",
+            "description": "`true` when more versions exist after this page.",
             "type": "boolean"
           },
           "items": {
@@ -20402,7 +21066,7 @@
             "type": "array"
           },
           "total": {
-            "description": "Total number of history versions for the application.",
+            "description": "Total number of history versions for the application, across all pages.",
             "format": "int64",
             "type": "integer"
           }
@@ -20444,7 +21108,7 @@
         "type": "object"
       },
       "RumErrorIngestionOrFilters": {
-        "description": "OR-of-ANDs filter set. The outer array is OR — an error matches the rule if it matches at least one inner AND-group.",
+        "description": "OR-of-ANDs filter set. The outer array is OR: an error matches the rule if it matches at least one inner AND-group. An empty outer array never matches; an empty inner group matches every error.",
         "items": {
           "description": "AND-group. The group only matches when every condition inside it matches.",
           "items": {
@@ -20477,20 +21141,20 @@
         "description": "An error ingestion rule.",
         "properties": {
           "created_at": {
-            "description": "Unix timestamp in milliseconds when the rule was created.",
+            "description": "Unix timestamp in milliseconds when the rule was created; reset to the revert time when the rule is restored by a history revert.",
             "format": "int64",
             "type": "integer"
           },
           "description": {
-            "description": "Rule description, up to 512 characters.",
+            "description": "Rule description, up to 512 characters; empty string when none was given.",
             "type": "string"
           },
           "filters": {
             "$ref": "#/components/schemas/RumErrorIngestionOrFilters",
-            "description": "The rule's filter conditions."
+            "description": "The rule's conditions. An error that matches them is stored but not grouped into any issue."
           },
           "rule_id": {
-            "description": "Rule ID.",
+            "description": "Rule ID, generated by the server on `create`. It stays the same across updates and history reverts.",
             "type": "string"
           },
           "rule_name": {
@@ -20498,7 +21162,7 @@
             "type": "string"
           },
           "status": {
-            "description": "Current status of the rule.",
+            "description": "Rule status:\n- `enabled`: the rule is applied to newly ingested errors.\n- `disabled`: the rule is kept but not applied.",
             "enum": [
               "enabled",
               "disabled"
@@ -20506,7 +21170,7 @@
             "type": "string"
           },
           "updated_at": {
-            "description": "Unix timestamp in milliseconds when the rule was last updated.",
+            "description": "Unix timestamp in milliseconds of the last update, enable, or disable; reset to the revert time when the rule is restored by a history revert.",
             "format": "int64",
             "type": "integer"
           }
@@ -20544,7 +21208,7 @@
         "description": "One rule record inside a history snapshot. Carries the raw storage fields, a superset of the fields returned by `list`.",
         "properties": {
           "account_id": {
-            "description": "Account ID.",
+            "description": "ID of the account that owns the rule.",
             "format": "int64",
             "type": "integer"
           },
@@ -20563,12 +21227,12 @@
             "type": "integer"
           },
           "deleted_at": {
-            "description": "Unix timestamp in milliseconds when the row was soft-deleted; `0` when not deleted.",
+            "description": "Soft-delete time as a Unix timestamp in milliseconds. Always `0` here, because snapshots contain only non-deleted rules.",
             "format": "int64",
             "type": "integer"
           },
           "description": {
-            "description": "Rule description.",
+            "description": "Rule description as of this snapshot version; empty string when none was given.",
             "type": "string"
           },
           "filters": {
@@ -20576,20 +21240,20 @@
             "description": "The rule's filter conditions as of this snapshot version."
           },
           "id": {
-            "description": "Internal row ID.",
+            "description": "Internal storage row ID. Not accepted by any endpoint; use `rule_id` instead. Changes when the rule is restored by a history revert.",
             "format": "int64",
             "type": "integer"
           },
           "rule_id": {
-            "description": "Rule ID.",
+            "description": "Rule ID, the same value `list` returns for this rule.",
             "type": "string"
           },
           "rule_name": {
-            "description": "Rule name.",
+            "description": "Rule name as of this snapshot version.",
             "type": "string"
           },
           "status": {
-            "description": "The rule's status as of this snapshot version.",
+            "description": "The rule's status as of this snapshot version:\n- `enabled`: applied to newly ingested errors.\n- `disabled`: kept but not applied.",
             "enum": [
               "enabled",
               "disabled"
@@ -20602,7 +21266,7 @@
             "type": "integer"
           },
           "updated_by": {
-            "description": "Member ID who last updated the rule.",
+            "description": "Member ID who last updated the rule before this snapshot.",
             "format": "int64",
             "type": "integer"
           }
@@ -20667,7 +21331,7 @@
         "description": "Parameters for counting facet value distribution.",
         "properties": {
           "dql": {
-            "description": "RUM DQL filter expression applied before counting.",
+            "description": "RUM DQL filter expression applied before counting. Fields in it are validated against the `scope`.",
             "type": "string"
           },
           "end_time": {
@@ -20677,11 +21341,11 @@
             "type": "integer"
           },
           "facet_key": {
-            "description": "Field key whose value distribution to count; must be a registered field of the given `scope`. List available fields via `POST /rum/field/list`.",
+            "description": "Field key whose value distribution to count, such as `error_type`. Must be a facet field of the given `scope` with `show_type: list` and a non-array `value_type`. List candidates with `POST /rum/field/list`.",
             "type": "string"
           },
           "facet_value": {
-            "description": "When set, filter events where `facet_key` equals this value before counting. Accepts string, number, or boolean."
+            "description": "When set, count only events whose `facet_key` equals this value. The JSON type must match the field's `value_type` (string, number or boolean); a mismatch returns `InvalidParameter`. When omitted, events with a `null` value are excluded."
           },
           "kind": {
             "description": "Symbol kind, used only when `scope` is `sourcemap` and only meaningful for `android`/`harmony`: `mapping` (default) selects ProGuard/R8 mappings or ArkTS sourcemaps, `native` selects native .so symbols.",
@@ -20713,7 +21377,7 @@
             "type": "string"
           },
           "sql": {
-            "description": "SQL WHERE clause (no SELECT) for additional filtering.",
+            "description": "Bare SQL `WHERE` condition (without the `WHERE` keyword) for extra filtering, such as `env = 'prod'`. Any occurrence of `SELECT` is rejected.",
             "type": "string"
           },
           "start_time": {
@@ -20805,7 +21469,7 @@
             "type": "string"
           },
           "group": {
-            "description": "Display group for this field.",
+            "description": "Display group used to cluster fields in the console, such as `error`, `action` or `device`. Empty when the field has no group.",
             "type": "string"
           },
           "is_facet": {
@@ -20817,7 +21481,7 @@
             "type": "boolean"
           },
           "scopes": {
-            "description": "RUM scopes this field appears in.",
+            "description": "RUM scopes this field appears in, using the same values as the request `scopes` (for example `error`, `issue`).",
             "items": {
               "type": "string"
             },
@@ -20832,15 +21496,34 @@
             "type": "string"
           },
           "status": {
-            "description": "Field status, e.g. `active`.",
+            "description": "Field status. `enabled`: the field is in use. `disabled`: the field is defined but switched off. Deleted fields are never returned.",
+            "enum": [
+              "enabled",
+              "disabled"
+            ],
             "type": "string"
           },
           "unit_family": {
-            "description": "Measurement unit family, e.g. `time`, `bytes`. Empty for dimensionless fields.",
+            "description": "Measurement unit family. `time`: a duration or timestamp (see `unit_name`). `bytes`: a size in bytes. Empty string for dimensionless fields.",
+            "enum": [
+              "",
+              "time",
+              "bytes"
+            ],
             "type": "string"
           },
           "unit_name": {
-            "description": "Specific measurement unit, e.g. `millisecond`, `byte`.",
+            "description": "Unit of the stored value. Durations: `nanosecond`, `microsecond`, `millisecond`, `second`. Timestamps: `unix_millisecond`, `unix_second`. Sizes: `byte`. Empty string for dimensionless fields. Most built-in duration fields are in `nanosecond`.",
+            "enum": [
+              "",
+              "nanosecond",
+              "microsecond",
+              "millisecond",
+              "second",
+              "unix_millisecond",
+              "unix_second",
+              "byte"
+            ],
             "type": "string"
           },
           "value_type": {
@@ -20941,11 +21624,11 @@
             "type": "boolean"
           },
           "console_origin": {
-            "description": "Console origin used to build the `issue_url` column, e.g. `https://console.flashcat.cloud`. The service cannot infer it (SaaS, on-premises and dev releases answer on different origins).",
+            "description": "Console origin used to build the `issue_url` column, e.g. `https://console.flashcat.cloud`; a trailing `/` is trimmed. The service cannot infer it. When omitted, `issue_url` holds only the path `/rum/error-tracking/issue/<issue_id>`.",
             "type": "string"
           },
           "dql": {
-            "description": "DQL query for advanced filtering. Cannot be used with `sql`.",
+            "description": "DQL query for advanced filtering. Field names must be fields of the `issue` scope (see `POST /rum/field/list` with `scopes: [\"issue\"]`); a bare full-text term searches the error message. Cannot be used with `sql`.",
             "type": "string"
           },
           "end_time": {
@@ -20958,7 +21641,7 @@
             "type": "boolean"
           },
           "export_fields": {
-            "description": "CSV columns to export, in the order they appear. Unknown keys are rejected with a parameter error; an empty array uses the default column set.\n\n| Value | Column content |\n|---|---|\n| `issue_id` | Issue ID |\n| `issue_url` | Console URL of the issue detail page (built from `console_origin`) |\n| `application_name` | Owning application name |\n| `service` | Service name |\n| `error_type` | Error type |\n| `error_message` | Error message |\n| `status` | Triage status |\n| `severity` | Severity |\n| `is_crash` | Whether the error caused a crash |\n| `error_count` | Error occurrence count |\n| `session_count` | Affected session count |\n| `first_seen_at` | First occurrence time (rendered in `time_zone`) |\n| `first_seen_version` | Application version at first occurrence |\n| `last_seen_at` | Most recent occurrence time (rendered in `time_zone`) |\n| `last_seen_version` | Application version at the most recent occurrence |\n| `versions` | All affected versions |\n| `suspected_cause` | Suspected cause category |\n| `resolved_at` | Resolution time (rendered in `time_zone`) |",
+            "description": "CSV columns to export, in the order they appear. Unknown keys are rejected with a parameter error and duplicates are dropped. Empty or omitted: every column below except the `sample_first_*` group.\n\n| Value | Column content |\n|---|---|\n| `issue_id` | Issue ID |\n| `issue_url` | Console URL of the issue detail page (built from `console_origin`) |\n| `application_name` | Owning application name |\n| `service` | Service name |\n| `error_type` | Error type |\n| `error_message` | Error message |\n| `status` | Triage status |\n| `severity` | Severity |\n| `is_crash` | Whether the error caused a crash |\n| `error_count` | Error occurrence count |\n| `session_count` | Affected session count |\n| `first_seen_at` | First occurrence time (rendered in `time_zone`) |\n| `first_seen_version` | Application version at first occurrence |\n| `last_seen_at` | Most recent occurrence time (rendered in `time_zone`) |\n| `last_seen_version` | Application version at the most recent occurrence |\n| `versions` | All affected versions |\n| `suspected_cause` | Suspected cause category |\n| `resolved_at` | Resolution time (rendered in `time_zone`); empty while unresolved |\n| `sample_time` | Latest error event in the time window: time of the event (rendered in `time_zone`) |\n| `sample_version` | Latest error event in the time window: application version |\n| `sample_view` | Latest error event in the time window: view name, or the view URL when the name is empty |\n| `sample_session_id` | Latest error event in the time window: session ID |\n| `sample_device` | Latest error event in the time window: device brand and model |\n| `sample_os` | Latest error event in the time window: OS name and version |\n| `sample_browser` | Latest error event in the time window: browser name and version |\n| `sample_stack` | Latest error event in the time window: error stack, truncated to the first 20 lines |\n| `sample_first_time` | Earliest error event in the time window: time of the event (rendered in `time_zone`) |\n| `sample_first_version` | Earliest error event in the time window: application version |\n| `sample_first_view` | Earliest error event in the time window: view name, or the view URL when the name is empty |\n| `sample_first_session_id` | Earliest error event in the time window: session ID |\n| `sample_first_device` | Earliest error event in the time window: device brand and model |\n| `sample_first_os` | Earliest error event in the time window: OS name and version |\n| `sample_first_browser` | Earliest error event in the time window: browser name and version |\n| `sample_first_stack` | Earliest error event in the time window: error stack, truncated to the first 20 lines |",
             "items": {
               "enum": [
                 "issue_id",
@@ -20978,7 +21661,23 @@
                 "last_seen_version",
                 "versions",
                 "suspected_cause",
-                "resolved_at"
+                "resolved_at",
+                "sample_time",
+                "sample_version",
+                "sample_view",
+                "sample_session_id",
+                "sample_device",
+                "sample_os",
+                "sample_browser",
+                "sample_stack",
+                "sample_first_time",
+                "sample_first_version",
+                "sample_first_view",
+                "sample_first_session_id",
+                "sample_first_device",
+                "sample_first_os",
+                "sample_first_browser",
+                "sample_first_stack"
               ],
               "type": "string"
             },
@@ -21007,11 +21706,11 @@
             "type": "integer"
           },
           "sql": {
-            "description": "SQL-style query for advanced filtering. Cannot be used with `dql`.",
+            "description": "SQL-style WHERE condition for advanced filtering, without the `WHERE` keyword (for example `error_count > 100`). Field names must be fields of the `issue` scope; any text containing `SELECT` is rejected. Cannot be used with `dql`.",
             "type": "string"
           },
           "start_time": {
-            "description": "Start of the time range, Unix epoch milliseconds.",
+            "description": "Start of the time range, Unix timestamp in milliseconds (a value that looks like seconds is rejected). Issues are matched by creation time unless `by_intersection` is `true`.",
             "format": "int64",
             "type": "integer"
           },
@@ -21052,7 +21751,7 @@
             "type": "array"
           },
           "time_zone": {
-            "description": "IANA time zone used to render timestamps in the CSV, e.g. `Asia/Shanghai` or `UTC`. Default: `Asia/Shanghai`.",
+            "description": "IANA time zone used to render the CSV time columns and the file name, e.g. `Asia/Shanghai` or `UTC`. Default: `Asia/Shanghai`. An unknown zone name returns `InvalidParameter`.",
             "type": "string"
           }
         },
@@ -21103,7 +21802,7 @@
                 "type": "string"
               },
               "type": {
-                "description": "Error type, from the error event's `error_type` field as reported by the SDK.",
+                "description": "Error type reported by the SDK in the error event's `error_type` field — free-form, not a fixed set. Browser errors carry the JavaScript exception name, e.g. `Error`, `TypeError`, `ReferenceError`.",
                 "type": "string"
               }
             },
@@ -21153,7 +21852,7 @@
             "type": "object"
           },
           "regression": {
-            "description": "Regression metadata. Present only when a previously resolved issue re-occurred.",
+            "description": "Regression record. Present only after a resolved issue was reopened because its error recurred; cleared when the issue is resolved again.",
             "properties": {
               "regressed_at": {
                 "description": "Time the regression was detected, Unix timestamp in milliseconds.",
@@ -21173,15 +21872,23 @@
             "type": "object"
           },
           "resolved_at": {
-            "description": "Time the issue was marked resolved, Unix timestamp in milliseconds; 0 while unresolved.",
+            "description": "Time the issue was marked resolved (by a user or automatically), Unix timestamp in milliseconds; `0` while unresolved.",
             "format": "int64",
             "type": "integer"
           },
           "resolved_by": {
-            "description": "Person ID of the user who marked the issue resolved; 0 while unresolved.",
+            "description": "Person ID of the user who marked the issue resolved; `0` while unresolved or when the issue was resolved automatically.",
             "format": "int64",
             "type": "integer"
           },
+          "resolve_mode": {
+            "description": "How the issue reacts when its error recurs after being resolved: `any` reopens it on any recurrence; `version` reopens it only when the error recurs in an application version the issue has not been seen in (errors without a version always reopen it). New issues and automatic resolution use `version`; resolving through `POST /rum/issue/update` without `resolve_mode` sets `any`.",
+            "enum": [
+              "any",
+              "version"
+            ],
+            "type": "string"
+          },
           "service": {
             "description": "Name of the service that produced this issue, taken from the error event's `service` field.",
             "type": "string"
@@ -21192,7 +21899,7 @@
             "type": "integer"
           },
           "severity": {
-            "description": "Issue severity: `Critical`, `Warning`, or `Info`. Empty string on legacy issues created before severity existed.",
+            "description": "Issue severity, fixed when the issue is created: the first matching enabled preset severity rule (see `POST /rum/issue/preset-severity/rules/list`) decides it, otherwise a built-in rule (crashes are `Critical`; other errors are scored by environment and message keywords). An error only joins an existing issue of equal or higher severity, so the same error can produce separate issues per severity. Empty string on legacy issues created before severity existed.",
             "enum": [
               "Critical",
               "Warning",
@@ -21201,7 +21908,7 @@
             "type": "string"
           },
           "status": {
-            "description": "Triage status of the issue; soft-deleted (`deleted`) issues are never returned.\n\n| Value | Meaning |\n|---|---|\n| `for_review` | Pending triage |\n| `reviewed` | Reviewed |\n| `ignored` | Ignored |\n| `resolved` | Resolved |",
+            "description": "Triage status of the issue; soft-deleted (`deleted`) issues are never returned. The system resolves an issue automatically when its error has not been seen for 14 days, or when a newer application version reports no such error, and reopens a resolved issue as `for_review` when the error recurs (see `resolve_mode`).\n\n| Value | Meaning |\n|---|---|\n| `for_review` | Pending triage |\n| `reviewed` | Reviewed |\n| `ignored` | Ignored |\n| `resolved` | Resolved |",
             "enum": [
               "for_review",
               "reviewed",
@@ -21219,7 +21926,7 @@
                 "type": "integer"
               },
               "reason": {
-                "description": "Explanation for the cause determination, generated only by AI analysis; empty string when AI is disabled or analysis has not run.",
+                "description": "Free-text explanation of the cause, written only by AI analysis; empty string when AI analysis is disabled, has not run yet, or the cause was set by a user.",
                 "type": "string"
               },
               "source": {
@@ -21256,14 +21963,40 @@
             "type": "integer"
           },
           "versions": {
-            "description": "Deduplicated list of application versions in which this issue has occurred; may contain an empty string for events without version info.",
+            "description": "Deduplicated list of application versions in which this issue has occurred; may contain an empty string for events without version info. `null` on issues that never recorded a version list.",
             "items": {
               "type": "string"
             },
-            "type": "array"
+            "type": [
+              "array",
+              "null"
+            ]
           }
         },
-        "type": "object"
+        "type": "object",
+        "required": [
+          "team_id",
+          "issue_id",
+          "application_id",
+          "application_name",
+          "service",
+          "status",
+          "error_count",
+          "session_count",
+          "is_crash",
+          "age",
+          "resolved_at",
+          "resolved_by",
+          "resolve_mode",
+          "created_at",
+          "updated_at",
+          "first_seen",
+          "last_seen",
+          "error",
+          "suspected_cause",
+          "versions",
+          "severity"
+        ]
       },
       "RumIssueListRequest": {
         "description": "Filters for listing issues.",
@@ -21284,7 +22017,7 @@
             "type": "boolean"
           },
           "dql": {
-            "description": "DQL query for advanced filtering. Cannot be used with `sql`.",
+            "description": "DQL query for advanced filtering. Field names must be fields of the `issue` scope (see `POST /rum/field/list` with `scopes: [\"issue\"]`); a bare full-text term searches the error message. Cannot be used with `sql`.",
             "type": "string"
           },
           "end_time": {
@@ -21319,11 +22052,11 @@
             "type": "integer"
           },
           "sql": {
-            "description": "SQL-style query for advanced filtering. Cannot be used with `dql`.",
+            "description": "SQL-style WHERE condition for advanced filtering, without the `WHERE` keyword (for example `error_count > 100`). Field names must be fields of the `issue` scope; any text containing `SELECT` is rejected. Cannot be used with `dql`.",
             "type": "string"
           },
           "start_time": {
-            "description": "Start of the time range, Unix epoch milliseconds.",
+            "description": "Start of the time range, Unix timestamp in milliseconds (a value that looks like seconds is rejected). Issues are matched by creation time unless `by_intersection` is `true`.",
             "format": "int64",
             "type": "integer"
           },
@@ -21398,7 +22131,7 @@
             "type": "string"
           },
           "status": {
-            "description": "New status. Setting `resolved` records the resolution time and operator; switching away from `resolved` clears them.\n\n| Value | Meaning |\n|---|---|\n| `for_review` | Pending triage |\n| `reviewed` | Reviewed |\n| `ignored` | Ignored |\n| `resolved` | Resolved |",
+            "description": "New status. Setting `resolved` on an unresolved issue records the resolution time and operator and clears `regression`; switching away from `resolved` clears the resolution time and operator. Omit to keep the current status.\n\n| Value | Meaning |\n|---|---|\n| `for_review` | Pending triage |\n| `reviewed` | Reviewed |\n| `ignored` | Ignored |\n| `resolved` | Resolved |",
             "enum": [
               "for_review",
               "reviewed",
@@ -21407,6 +22140,14 @@
             ],
             "type": "string"
           },
+          "resolve_mode": {
+            "description": "How the issue reacts when its error recurs after being resolved. Applied only together with `status: resolved`; defaults to `any` there when omitted, and is ignored with any other status.\n\n| Value | Meaning |\n|---|---|\n| `any` | Reopen the issue on any recurrence |\n| `version` | Reopen only when the error recurs in an application version the issue has not been seen in; errors without a version always reopen it |",
+            "enum": [
+              "any",
+              "version"
+            ],
+            "type": "string"
+          },
           "suspected_cause": {
             "description": "New suspected cause; setting it marks the cause source as `user`, overriding the automatic classification. One of:\n\n| Value | Meaning |\n|---|---|\n| `api.failed_request` | API request failure |\n| `network.error` | Network connectivity error |\n| `code.exception` | Code exception |\n| `code.invalid_object_access` | Invalid object access |\n| `code.invalid_argument` | Invalid argument |\n| `unknown` | Unknown cause |",
             "enum": [
@@ -21438,7 +22179,7 @@
             "type": "string"
           },
           "filters": {
-            "description": "OR-of-ANDs filter structure: the outer array is OR'd, each inner array is AND'd. A rule matches an error when at least one inner AND-group fully matches.",
+            "description": "OR-of-ANDs filter structure: the outer array is OR'd, each inner array is AND'd. A rule matches an error when at least one inner AND-group fully matches. An empty outer array never matches; an empty inner group matches every error.",
             "items": {
               "items": {
                 "$ref": "#/components/schemas/RumPresetSeverityRuleFilterCondition"
@@ -21497,7 +22238,7 @@
         "description": "One filter condition within an AND group.",
         "properties": {
           "key": {
-            "description": "Filter attribute key. Only these Error-level attributes are supported for preset severity rules.\n\n| Value | Meaning |\n|---|---|\n| `error.usr_id` | User ID |\n| `error.usr_email` | User email |\n| `error.view_url` | Full URL of the page where the error occurred |\n| `error.view_url_path` | URL path of the page where the error occurred |\n| `error.error_type` | Error type |\n| `error.error_message` | Error message |\n| `error.env` | Environment (e.g. production/staging) |\n| `error.service` | Service name |\n| `error.device_type` | Device type |\n| `error.os_name` | Operating system name |\n| `error.browser_name` | Browser name |\n| `error.is_crash` | Whether the error is a crash (boolean) |",
+            "description": "Filter attribute key. Only these Error-level attributes are supported for preset severity rules.\n\n| Value | Meaning |\n|---|---|\n| `error.usr_id` | User ID |\n| `error.usr_email` | User email |\n| `error.view_url` | Full URL of the page where the error occurred |\n| `error.view_url_path` | URL path of the page where the error occurred |\n| `error.error_type` | Error type |\n| `error.error_message` | Error message |\n| `error.env` | Environment (e.g. production/staging) |\n| `error.service` | Service name |\n| `error.device_type` | Device type |\n| `error.os_name` | Operating system name |\n| `error.browser_name` | Browser name |\n| `error.is_crash` | Whether the error is a crash, compared as the string `true` or `false` |",
             "enum": [
               "error.usr_id",
               "error.usr_email",
@@ -21515,7 +22256,7 @@
             "type": "string"
           },
           "oper": {
-            "description": "Match semantics: `IN` matches when the field's value matches any of `vals`; `NOTIN` matches when it matches none of them (and matches when the field is absent).",
+            "description": "Match semantics: `IN` matches when the attribute value matches any of `vals`; `NOTIN` matches when it matches none of them. An attribute the error does not carry is compared as an empty string.",
             "enum": [
               "IN",
               "NOTIN"
@@ -21523,7 +22264,7 @@
             "type": "string"
           },
           "vals": {
-            "description": "Values to match against. Each entry supports exact string match, wildcard (`*`/`?`), regex (wrap in `/.../`), CIDR (`cidr:10.0.0.0/8`) for IP-shaped values, or numeric comparison (`num:gt:100`, `num:le:50`, etc.).",
+            "description": "Values to match against; at least one, none empty. Each entry is one of: an exact, case-sensitive whole-value match; a wildcard pattern with `*`/`?` (whole value); a regular expression wrapped in `/.../` (matches anywhere in the value unless anchored with `^`/`$`); `cidr:<network>` for IP-shaped values, e.g. `cidr:10.0.0.0/8`; or a numeric comparison `num:<op>:<number>` with `op` one of `lt`, `le`, `gt`, `ge`, e.g. `num:gt:100`. For `error.is_crash`, use `true` or `false`.",
             "items": {
               "type": "string"
             },
@@ -21693,7 +22434,7 @@
             "type": "string"
           },
           "filters": {
-            "description": "OR-of-ANDs filter structure: the outer array is OR'd, each inner array is AND'd. A rule matches an error when at least one inner AND-group fully matches.",
+            "description": "OR-of-ANDs filter structure: the outer array is OR'd, each inner array is AND'd. A rule matches an error when at least one inner AND-group fully matches. An empty outer array never matches; an empty inner group matches every error.",
             "items": {
               "items": {
                 "$ref": "#/components/schemas/RumPresetSeverityRuleFilterCondition"
@@ -21797,7 +22538,7 @@
             "type": "string"
           },
           "filters": {
-            "description": "OR-of-ANDs filter structure: the outer array is OR'd, each inner array is AND'd. A rule matches an error when at least one inner AND-group fully matches.",
+            "description": "OR-of-ANDs filter structure: the outer array is OR'd, each inner array is AND'd. A rule matches an error when at least one inner AND-group fully matches. An empty outer array never matches; an empty inner group matches every error.",
             "items": {
               "items": {
                 "$ref": "#/components/schemas/RumPresetSeverityRuleFilterCondition"
@@ -21921,7 +22662,7 @@
             ]
           },
           "filters": {
-            "description": "OR-of-ANDs filter structure: the outer array is OR'd, each inner array is AND'd. A rule matches an error when at least one inner AND-group fully matches.",
+            "description": "New OR-of-ANDs filter structure; replaces the whole current structure. Omit or pass `null` to leave unchanged. The outer array is OR'd, each inner array is AND'd; an empty outer array never matches, an empty inner group matches every error.",
             "items": {
               "items": {
                 "$ref": "#/components/schemas/RumPresetSeverityRuleFilterCondition"
@@ -21981,15 +22722,15 @@
         "type": "object"
       },
       "RumReplayForegroundPeriod": {
-        "description": "A time span during which the app was in the foreground (mobile sessions).",
+        "description": "A span during which a view was in the foreground (focused).",
         "properties": {
           "end": {
-            "description": "Unix timestamp in milliseconds when the foreground period ended.",
+            "description": "End of the foreground period, in **nanoseconds** since the start of the view identified by `view_id` (not a Unix timestamp).",
             "format": "int64",
             "type": "integer"
           },
           "start": {
-            "description": "Unix timestamp in milliseconds when the foreground period started.",
+            "description": "Start of the foreground period, in **nanoseconds** since the start of the view identified by `view_id` (not a Unix timestamp).",
             "format": "int64",
             "type": "integer"
           },
@@ -22003,7 +22744,7 @@
       "RumReplaySession": {
         "properties": {
           "end": {
-            "description": "Unix timestamp in milliseconds when the session ended (or was last updated, if still active).",
+            "description": "Unix timestamp in milliseconds of the session end: the later of the session's recorded end and the end of its last returned view.",
             "format": "int64",
             "type": "integer"
           },
@@ -22012,7 +22753,7 @@
             "type": "boolean"
           },
           "server_time_delta": {
-            "description": "Clock skew in milliseconds between the client and Flashduty's servers, added to client timestamps for correction.",
+            "description": "Always `0`: timestamps are returned as recorded by the client, without clock-skew correction.",
             "format": "int64",
             "type": "integer"
           },
@@ -22044,7 +22785,20 @@
       "RumReplayView": {
         "properties": {
           "container_source": {
-            "description": "SDK platform of the container app, when this view is embedded (e.g. a WebView inside a native app). Omitted when the view is not embedded.",
+            "description": "SDK platform of the app that embeds this view (for example a WebView inside a native app). Omitted when the view is not embedded.\n\n| Value | Meaning |\n|---|---|\n| `browser` | Web browser application |\n| `ios` | Apple iOS application |\n| `android` | Android application |\n| `react-native` | React Native application |\n| `flutter` | Flutter application |\n| `kotlin-multiplatform` | Kotlin Multiplatform application |\n| `roku` | Roku channel application |\n| `unity` | Unity application |\n| `miniprogram` | WeChat mini program |\n| `harmony` | HarmonyOS application |\n| `electron` | Electron desktop application |",
+            "enum": [
+              "browser",
+              "ios",
+              "android",
+              "react-native",
+              "flutter",
+              "kotlin-multiplatform",
+              "roku",
+              "unity",
+              "miniprogram",
+              "harmony",
+              "electron"
+            ],
             "type": "string"
           },
           "container_view_id": {
@@ -22061,7 +22815,7 @@
             "type": "boolean"
           },
           "loading_type": {
-            "description": "How the view was entered, e.g. `initial_load`, `route_change`.",
+            "description": "How the view was entered, as reported by the SDK. Web: `initial_load`, `route_change`. Mobile: `activity_display`, `activity_redisplay`, `fragment_display`, `fragment_redisplay`, `view_controller_display`, `view_controller_redisplay`. Empty when not reported.",
             "type": "string"
           },
           "name": {
@@ -22069,7 +22823,7 @@
             "type": "string"
           },
           "server_time_delta": {
-            "description": "Clock skew in milliseconds between the client and Flashduty's servers, added to client timestamps for correction.",
+            "description": "Always `0`: timestamps are returned as recorded by the client, without clock-skew correction.",
             "format": "int64",
             "type": "integer"
           },
@@ -22185,7 +22939,7 @@
             "type": "integer"
           },
           "session_investigate.free_cnt": {
-            "description": "Free quota for investigate sessions per application, per billing window.",
+            "description": "Free quota of investigate (error tracking) sessions per application, per billing window. A negative value means unlimited.",
             "format": "int64",
             "type": "integer"
           },
@@ -22195,11 +22949,11 @@
             "type": "integer"
           },
           "session_limit_reached": {
-            "description": "`true` when a `version=free` account has exceeded its combined free session quota across all applications. Always `false` for non-free plans.",
+            "description": "`true` when a `version=free` account's investigate or replay sessions in the current window have reached the per-application free quota multiplied by the number of applications. Always `false` for non-free plans and for accounts without applications.",
             "type": "boolean"
           },
           "session_measure.free_cnt": {
-            "description": "Free quota for measure sessions per application, per billing window.",
+            "description": "Free quota of measure (performance) sessions per application, per billing window. A negative value means unlimited.",
             "format": "int64",
             "type": "integer"
           },
@@ -22209,7 +22963,7 @@
             "type": "integer"
           },
           "session_replay.free_cnt": {
-            "description": "Free quota for session-replay sessions per application, per billing window.",
+            "description": "Free quota of session-replay sessions per application, per billing window. A negative value means unlimited.",
             "format": "int64",
             "type": "integer"
           },
@@ -22296,7 +23050,7 @@
             "description": "Device that recorded the session."
           },
           "foreground_periods": {
-            "description": "Foreground periods across the session (mobile sessions only; empty for web).",
+            "description": "Periods during which a view was in the foreground (focused), collected from every returned view. Empty when the SDK reported none.",
             "items": {
               "$ref": "#/components/schemas/RumReplayForegroundPeriod"
             },
@@ -22307,7 +23061,7 @@
             "description": "Session bounds and state."
           },
           "views": {
-            "description": "Every view recorded during the session, in chronological order.",
+            "description": "Views of the session that carry replay data, ordered by start time.",
             "items": {
               "$ref": "#/components/schemas/RumReplayView"
             },
@@ -22324,7 +23078,7 @@
             "type": "string"
           },
           "ts": {
-            "description": "Unix timestamp in milliseconds of the session start time. Optional; disambiguates when a session ID has been reused across different time windows.",
+            "description": "Session start time, Unix milliseconds. Optional. When set, it must match the session's start exactly; use it to pick one session when a `session_id` was reused.",
             "exclusiveMinimum": 0,
             "format": "int64",
             "type": "integer"
@@ -22354,7 +23108,7 @@
             "type": "string"
           },
           "ts": {
-            "description": "Unix timestamp in milliseconds. When set (and `search_after_ctx` is empty), seeks to the most recent full-snapshot segment at or before this time instead of starting from the beginning.",
+            "description": "Unix timestamp in milliseconds. When set and `search_after_ctx` is empty, paging starts at the last full-snapshot segment at or before this time (searching up to 4 hours back); if none is found, paging starts from the beginning.",
             "exclusiveMinimum": 0,
             "format": "int64",
             "type": "integer"
@@ -22377,14 +23131,14 @@
         "description": "Presigned segment URLs, returned only when `url_mode` is `true`.",
         "properties": {
           "items": {
-            "description": "Presigned, time-limited URLs (valid 1 hour) for downloading each segment's raw compressed bytes.",
+            "description": "Presigned URLs (valid 1 hour) for downloading each segment object. The object body is zlib-compressed; decompress it to get the segment JSON.",
             "items": {
               "type": "string"
             },
             "type": "array"
           },
           "search_after_ctx": {
-            "description": "Pagination cursor to pass as `search_after_ctx` on the next call. Empty when this page was the last one.",
+            "description": "Cursor to pass as `search_after_ctx` on the next call. Set whenever this page returned `limit` segments (the next page may then be empty); empty string when fewer were returned.",
             "type": "string"
           }
         },
@@ -22394,11 +23148,11 @@
         "description": "Parameters for sending a sample RUM alert webhook.",
         "properties": {
           "application_id": {
-            "description": "RUM application ID. Get application IDs via `POST /rum/application/list`.",
+            "description": "RUM application whose name is put in the sample event's `labels.application_name`. The caller must be able to edit it. Get application IDs via `POST /rum/application/list`.",
             "type": "string"
           },
           "webhook_url": {
-            "description": "Webhook URL to receive the sample alert event.",
+            "description": "Webhook URL to receive the sample alert event; must use `http` or `https`. Not saved: use `POST /rum/application/update` with `alerting.webhook_url` to store it.",
             "format": "uri",
             "type": "string"
           }
@@ -22413,15 +23167,15 @@
         "description": "Result of the webhook test delivery.",
         "properties": {
           "message": {
-            "description": "`ok` on success, otherwise the delivery error message.",
+            "description": "`ok` on success. Otherwise `unexpected status <code>` when the endpoint answered with an error status, or `request failed: <error>` when no response was received.",
             "type": "string"
           },
           "ok": {
-            "description": "Whether the webhook endpoint accepted the sample event.",
+            "description": "`true` when the endpoint answered with a status below 400 (after following redirects); `false` otherwise.",
             "type": "boolean"
           },
           "status_code": {
-            "description": "HTTP status code returned by the webhook endpoint. 0 when the request did not receive a response.",
+            "description": "HTTP status code of the last delivery attempt. `0` when no response was received (connection error or timeout).",
             "type": "integer"
           }
         },
@@ -22587,108 +23341,135 @@
         "type": "object"
       },
       "ScheduleByPersonResponse": {
+        "type": "object",
         "description": "The member's on-call status: the shift in progress, the next one, and every enabled schedule they participate in.",
         "properties": {
           "current": {
-            "$ref": "#/components/schemas/MemberOncallInterval"
+            "oneOf": [
+              {
+                "$ref": "#/components/schemas/MemberOncallInterval"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "Shift in progress now; `null` when the member is not on call."
           },
           "next": {
-            "$ref": "#/components/schemas/MemberOncallInterval"
+            "oneOf": [
+              {
+                "$ref": "#/components/schemas/MemberOncallInterval"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "Next upcoming shift (without `end_at`); `null` when none within 45 days."
           },
           "schedules": {
+            "type": "array",
             "description": "All enabled schedules the member participates in.",
             "items": {
               "$ref": "#/components/schemas/MemberScheduleItem"
-            },
-            "type": "array"
+            }
           }
         },
         "required": [
           "schedules"
-        ],
-        "type": "object"
+        ]
       },
       "ScheduleCalculatedLayer": {
+        "type": "object",
         "description": "Computed schedule for a single layer.",
+        "required": [
+          "layer_name",
+          "name",
+          "mode",
+          "schedules"
+        ],
         "properties": {
           "layer_name": {
-            "description": "Layer display name.",
-            "type": "string"
-          },
-          "mode": {
-            "description": "Layer mode: 0 = common rotation, 1 = override.",
-            "type": "integer"
+            "type": "string",
+            "description": "Layer name; empty string in `final_schedule`."
           },
           "name": {
-            "description": "Layer internal name.",
-            "type": "string"
+            "type": "string",
+            "description": "Same as `layer_name`."
+          },
+          "mode": {
+            "type": "integer",
+            "enum": [
+              0,
+              1
+            ],
+            "description": "Type of the source layer: `0` = rotation layer, `1` = override layer. Always `0` in `final_schedule`."
           },
           "schedules": {
-            "description": "Computed shifts; null when the layer produces none.",
-            "items": {
-              "$ref": "#/components/schemas/ScheduleCalculatedSchedule"
-            },
             "type": [
               "array",
               "null"
-            ]
+            ],
+            "items": {
+              "$ref": "#/components/schemas/ScheduleCalculatedSchedule"
+            },
+            "description": "Computed shifts; null when the layer produces none."
           }
-        },
-        "required": [
-          "layer_name",
-          "name",
-          "mode",
-          "schedules"
-        ],
-        "type": "object"
+        }
       },
       "ScheduleCalculatedSchedule": {
+        "type": "object",
         "description": "Computed shift inside a schedule layer.",
+        "required": [
+          "start",
+          "end",
+          "group",
+          "index"
+        ],
         "properties": {
+          "start": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Shift start timestamp (Unix seconds)."
+          },
           "end": {
-            "description": "Shift end timestamp (Unix seconds).",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Shift end timestamp (Unix seconds)."
           },
           "group": {
-            "$ref": "#/components/schemas/ScheduleGroup",
-            "description": "Oncall group covering the shift; null marks a coverage gap."
+            "oneOf": [
+              {
+                "$ref": "#/components/schemas/ScheduleGroup"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "Group on call during the shift; `null` marks a gap with nobody on call."
           },
           "index": {
-            "description": "Index inside the rotation.",
-            "type": "integer"
-          },
-          "start": {
-            "description": "Shift start timestamp (Unix seconds).",
-            "format": "int64",
-            "type": "integer"
+            "type": "integer",
+            "description": "Zero-based position, in the schedule's layer list, of the layer the shift comes from."
           }
-        },
-        "required": [
-          "start",
-          "end",
-          "group",
-          "index"
-        ],
-        "type": "object"
+        }
       },
       "ScheduleDayMask": {
+        "type": "object",
         "description": "Day-of-week mask for a rotation layer.",
         "properties": {
           "repeat": {
-            "description": "Weekday numbers (0 = Sunday) included in the rotation. Conflicts with restrict_mode = 2 (week).",
-            "items": {
-              "maximum": 6,
-              "minimum": 0,
-              "type": "integer"
-            },
             "type": [
               "array",
               "null"
-            ]
+            ],
+            "items": {
+              "type": "integer",
+              "minimum": 0,
+              "maximum": 6
+            },
+            "description": "Weekdays on which the layer is on call: `0` = Sunday … `6` = Saturday, in the schedule's time zone. Empty or all seven days means every day. Cannot be combined with `restrict_mode` 2."
           }
-        },
-        "type": "object"
+        }
       },
       "ScheduleEmptyObject": {
         "description": "Empty response.",
@@ -22727,45 +23508,45 @@
         "type": "object"
       },
       "ScheduleGroup": {
+        "type": "object",
         "description": "Oncall group definition within a rotation layer.",
+        "required": [
+          "group_name",
+          "name",
+          "members",
+          "start",
+          "end"
+        ],
         "properties": {
-          "end": {
-            "description": "Group end timestamp (Unix seconds).",
-            "format": "int64",
-            "type": "integer"
-          },
           "group_name": {
-            "description": "Group display name. Null when only the legacy name is set.",
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "Group display name. Null when only the legacy name is set."
+          },
+          "name": {
+            "type": "string",
+            "description": "Legacy group name."
           },
           "members": {
-            "description": "Members of this group.",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/ScheduleMember"
             },
-            "type": "array"
-          },
-          "name": {
-            "description": "Legacy group name.",
-            "type": "string"
+            "description": "Members of this group."
           },
           "start": {
-            "description": "Group start timestamp (Unix seconds).",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Start of the group's shift (Unix seconds) in computed results; `0` in layer definitions and ignored on input."
+          },
+          "end": {
+            "type": "integer",
+            "format": "int64",
+            "description": "End of the group's shift (Unix seconds) in computed results; `0` in layer definitions and ignored on input."
           }
-        },
-        "required": [
-          "group_name",
-          "name",
-          "members",
-          "start",
-          "end"
-        ],
-        "type": "object"
+        }
       },
       "ScheduleIDResponse": {
         "description": "Schedule ID response returned after create.",
@@ -22782,21 +23563,21 @@
         "type": "object"
       },
       "ScheduleIDsBodyRequest": {
-        "description": "Request carrying a list of schedule IDs (used by delete/enable/disable).",
+        "type": "object",
+        "description": "Request carrying a list of schedule IDs.",
+        "required": [
+          "schedule_ids"
+        ],
         "properties": {
           "schedule_ids": {
-            "description": "Schedule IDs to operate on; obtain them from `POST /schedule/list`.",
+            "type": "array",
             "items": {
-              "format": "int64",
-              "type": "integer"
+              "type": "integer",
+              "format": "int64"
             },
-            "type": "array"
+            "description": "Schedule IDs to operate on; obtain them from `POST /schedule/list`."
           }
-        },
-        "required": [
-          "schedule_ids"
-        ],
-        "type": "object"
+        }
       },
       "ScheduleIDsRequest": {
         "description": "Request carrying a list of schedule IDs (used by batch info).",
@@ -22816,686 +23597,832 @@
         "type": "object"
       },
       "ScheduleImNotify": {
+        "type": "object",
         "description": "IM webhook notification entry.",
+        "required": [
+          "type",
+          "settings"
+        ],
         "properties": {
+          "type": {
+            "type": "string",
+            "enum": [
+              "feishu",
+              "dingtalk",
+              "wecom",
+              "slack",
+              "telegram",
+              "zoom",
+              "feishu_app",
+              "dingtalk_app",
+              "slack_app",
+              "teams_app"
+            ],
+            "description": "Where the notification goes:\n- `feishu`, `dingtalk`, `wecom`, `slack`: group robot webhook given by `settings.token`.\n- `telegram`: bot `settings.token` posting to `settings.chat_ids`.\n- `zoom`: Zoom robot with `settings.token` and `settings.verify_token`.\n- `feishu_app`, `dingtalk_app`, `slack_app`, `teams_app`: an IM integration (`settings.data_source_id`) posting to the group chats in `settings.chat_ids`.\nOther values are stored but never sent."
+          },
           "settings": {
             "$ref": "#/components/schemas/ScheduleImNotifySettings",
             "description": "Webhook channel settings."
-          },
-          "type": {
-            "description": "IM provider type (for example feishu_app, dingtalk_app, wecom_app, teams_app, slack_app).",
-            "type": "string"
           }
-        },
-        "required": [
-          "type",
-          "settings"
-        ],
-        "type": "object"
+        }
       },
       "ScheduleImNotifySettings": {
+        "type": "object",
         "description": "Settings for an IM webhook notification channel.",
+        "required": [
+          "token",
+          "alias",
+          "data_source_id",
+          "chat_ids",
+          "verify_token",
+          "sign_secret"
+        ],
         "properties": {
+          "token": {
+            "type": "string",
+            "description": "Robot webhook token for `feishu`, `dingtalk`, `wecom`, `slack`, `telegram` and `zoom`; empty for the `*_app` types."
+          },
           "alias": {
-            "description": "Channel alias.",
-            "type": "string"
+            "type": "string",
+            "description": "Display alias for the entry; not used when sending."
+          },
+          "data_source_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "ID of the IM integration used by the `*_app` types; `0` for robot types."
           },
           "chat_ids": {
-            "description": "Chat IDs.",
+            "type": "array",
             "items": {
               "type": "string"
             },
-            "type": "array"
+            "description": "Target chat IDs: group chats of the IM integration for `*_app` types, or Telegram chat IDs for `telegram`."
           },
-          "data_source_id": {
-            "description": "Data source ID.",
-            "format": "int64",
-            "type": "integer"
+          "verify_token": {
+            "type": "string",
+            "description": "Verification token, used by the `zoom` type."
           },
           "sign_secret": {
-            "description": "Signature secret.",
-            "type": "string"
-          },
-          "token": {
-            "description": "Webhook token.",
-            "type": "string"
-          },
-          "verify_token": {
-            "description": "Verification token.",
-            "type": "string"
+            "type": "string",
+            "description": "Robot signing secret. Stored with the entry."
           }
-        },
-        "required": [
-          "token",
-          "alias",
-          "data_source_id",
-          "chat_ids",
-          "verify_token",
-          "sign_secret"
-        ],
-        "type": "object"
+        }
       },
       "ScheduleInfoRequest": {
-        "description": "Schedule detail request. start/end define the window for computed layers; the span must be less than 45 days.",
+        "type": "object",
+        "description": "Schedule detail request. `start`/`end` set the window for computed shifts; at most 45 days apart.",
+        "required": [
+          "schedule_id",
+          "start",
+          "end"
+        ],
         "properties": {
-          "end": {
-            "description": "Preview end timestamp (Unix seconds, 10 digits).",
-            "format": "int64",
-            "type": "integer"
-          },
           "schedule_id": {
-            "description": "Schedule ID; obtain it from `POST /schedule/list`.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Schedule ID; obtain it from `POST /schedule/list`."
           },
           "start": {
-            "description": "Preview start timestamp (Unix seconds, 10 digits).",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Preview start timestamp (Unix seconds, 10 digits)."
+          },
+          "end": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Preview end timestamp (Unix seconds, 10 digits)."
           }
-        },
+        }
+      },
+      "ScheduleItem": {
+        "type": "object",
+        "description": "On-call schedule as returned by info, list, infos, self and preview. Which computed fields are filled depends on the endpoint — see each operation's notes.",
         "required": [
+          "id",
+          "name",
+          "account_id",
+          "group_id",
+          "time_zone",
+          "disabled",
+          "create_at",
+          "create_by",
+          "update_at",
+          "update_by",
+          "layers",
+          "schedule_layers",
+          "final_schedule",
+          "notify",
           "schedule_id",
-          "start",
-          "end"
+          "schedule_name",
+          "team_id",
+          "description",
+          "layer_schedules",
+          "status",
+          "cur_oncall",
+          "next_oncall"
         ],
-        "type": "object"
-      },
-      "ScheduleItem": {
-        "description": "Full schedule detail returned by info/preview/list.",
         "properties": {
-          "account_id": {
-            "description": "Account ID.",
+          "id": {
+            "type": [
+              "integer",
+              "null"
+            ],
             "format": "int64",
-            "type": "integer"
+            "description": "Schedule ID. null when returned from /schedule/preview."
           },
-          "create_at": {
-            "description": "Creation timestamp (Unix seconds).",
-            "format": "int64",
-            "type": "integer"
+          "name": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "Schedule name (legacy field; mirrors schedule_name). null when returned from /schedule/preview."
           },
-          "create_by": {
-            "description": "Creator person ID.",
+          "account_id": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "ID of the account that owns the schedule."
           },
-          "cur_oncall": {
-            "$ref": "#/components/schemas/ScheduleOncallGroup",
-            "description": "Current on-call group, or null when nobody is on-call."
-          },
-          "description": {
-            "description": "Schedule description. null when returned from /schedule/preview.",
+          "group_id": {
             "type": [
-              "string",
+              "integer",
               "null"
-            ]
+            ],
+            "format": "int64",
+            "description": "Legacy team/group ID. null when returned from /schedule/preview."
+          },
+          "time_zone": {
+            "type": "string",
+            "description": "IANA time zone (for example `Asia/Shanghai`) in which the schedule's handoffs, restriction windows, weekdays and fixed-time notifications are evaluated. Set at creation and immutable. An empty string means none was set and the schedule is evaluated in `Asia/Shanghai`."
           },
           "disabled": {
-            "description": "Disabled flag (0 = enabled, 1 = disabled). Deprecated. null when returned from /schedule/preview.",
             "type": [
               "integer",
               "null"
-            ]
+            ],
+            "enum": [
+              0,
+              1,
+              null
+            ],
+            "description": "Whether the schedule is disabled: `0` = enabled, `1` = disabled (disabled schedules send no shift notifications and are skipped by `/schedule/self` and `/schedule/by-person`). Same value as `status`. `null` in `/schedule/preview` unless sent."
           },
-          "end": {
-            "description": "Window end (Unix seconds). Omitted when 0 (no window requested).",
+          "create_at": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
-          },
-          "field": {
-            "description": "Field name used by the legacy update-field endpoint.",
-            "type": "string"
+            "description": "Creation timestamp (Unix seconds)."
           },
-          "final_schedule": {
-            "$ref": "#/components/schemas/ScheduleCalculatedLayer",
-            "description": "Collapsed final schedule across all layers."
+          "create_by": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Creator person ID."
           },
-          "group_id": {
-            "description": "Legacy team/group ID. null when returned from /schedule/preview.",
+          "update_at": {
+            "type": "integer",
             "format": "int64",
-            "type": [
-              "integer",
-              "null"
-            ]
+            "description": "Last update timestamp (Unix seconds)."
           },
-          "id": {
-            "description": "Schedule ID. null when returned from /schedule/preview.",
+          "update_by": {
+            "type": "integer",
             "format": "int64",
-            "type": [
-              "integer",
-              "null"
-            ]
+            "description": "Last updater person ID."
           },
-          "layer_schedules": {
-            "description": "Alias of schedule_layers returned for compatibility. Null when not computed.",
-            "items": {
-              "$ref": "#/components/schemas/ScheduleCalculatedLayer"
-            },
+          "layers": {
             "type": [
               "array",
               "null"
-            ]
-          },
-          "layers": {
-            "description": "Rotation layers defined on the schedule. Null when layers were not loaded (for example by `/schedule/infos`, or by `/schedule/list` without start/end).",
+            ],
             "items": {
               "$ref": "#/components/schemas/ScheduleLayer"
             },
+            "description": "Rotation layers defined on the schedule. Null when layers were not loaded (for example by `/schedule/infos`, or by `/schedule/list` without start/end)."
+          },
+          "schedule_layers": {
             "type": [
               "array",
               "null"
-            ]
+            ],
+            "items": {
+              "$ref": "#/components/schemas/ScheduleCalculatedLayer"
+            },
+            "description": "Shifts of each visible (non-hidden) layer in the requested window. `null` when no window was computed (`/schedule/infos`, `/schedule/self`, `/schedule/list` without `start`/`end`)."
           },
-          "name": {
-            "description": "Schedule name (legacy field; mirrors schedule_name). null when returned from /schedule/preview.",
-            "type": [
-              "string",
-              "null"
-            ]
+          "final_schedule": {
+            "$ref": "#/components/schemas/ScheduleCalculatedLayer",
+            "description": "All layers merged into one timeline for the window: where layers overlap, override layers win over rotation layers and later layers win over earlier ones. In `/schedule/self` it keeps only the caller's shifts. Empty (`schedules` is `null`) when nothing was computed."
           },
-          "next_oncall": {
-            "$ref": "#/components/schemas/ScheduleOncallGroup",
-            "description": "Next on-call group, or null when unknown."
+          "start": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Window start (Unix seconds). Only echoed by `/schedule/preview`; omitted elsewhere."
+          },
+          "end": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Window end (Unix seconds). Only echoed by `/schedule/preview`; omitted elsewhere."
           },
           "notify": {
-            "$ref": "#/components/schemas/ScheduleNotify",
-            "description": "Notification configuration. Null when the schedule has none."
+            "oneOf": [
+              {
+                "$ref": "#/components/schemas/ScheduleNotify"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "Shift notification configuration; `null` when the schedule has none."
           },
           "schedule_id": {
-            "description": "Schedule ID. Null when returned from `/schedule/preview`.",
-            "format": "int64",
             "type": [
               "integer",
               "null"
-            ]
-          },
-          "schedule_layers": {
-            "description": "Computed per-layer schedules for the requested window. Null when not computed.",
-            "items": {
-              "$ref": "#/components/schemas/ScheduleCalculatedLayer"
-            },
-            "type": [
-              "array",
-              "null"
-            ]
+            ],
+            "format": "int64",
+            "description": "Schedule ID. Null when returned from `/schedule/preview`."
           },
           "schedule_name": {
-            "description": "Schedule display name. null when returned from /schedule/preview.",
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "Schedule display name. null when returned from /schedule/preview."
           },
-          "start": {
-            "description": "Window start (Unix seconds). Omitted when 0 (no window requested).",
+          "team_id": {
+            "type": [
+              "integer",
+              "null"
+            ],
             "format": "int64",
-            "type": "integer"
+            "description": "Owning team ID. null when returned from /schedule/preview."
           },
-          "status": {
-            "description": "Legacy status flag. Deprecated. null when returned from /schedule/preview.",
+          "description": {
             "type": [
-              "integer",
+              "string",
               "null"
-            ]
+            ],
+            "description": "Schedule description. null when returned from /schedule/preview."
           },
-          "team_id": {
-            "description": "Owning team ID. null when returned from /schedule/preview.",
-            "format": "int64",
+          "layer_schedules": {
+            "type": [
+              "array",
+              "null"
+            ],
+            "items": {
+              "$ref": "#/components/schemas/ScheduleCalculatedLayer"
+            },
+            "description": "Same content as `schedule_layers`, filled by `/schedule/info` and `/schedule/preview` only; `null` elsewhere."
+          },
+          "status": {
             "type": [
               "integer",
               "null"
-            ]
+            ],
+            "enum": [
+              0,
+              1,
+              null
+            ],
+            "description": "Mirror of `disabled`: `0` = enabled, `1` = disabled. Send it on `/schedule/update` to enable or disable a schedule. `null` in `/schedule/preview` unless sent."
           },
-          "update_at": {
-            "description": "Last update timestamp (Unix seconds).",
-            "format": "int64",
-            "type": "integer"
+          "cur_oncall": {
+            "oneOf": [
+              {
+                "$ref": "#/components/schemas/ScheduleOncallGroup"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "The shift in progress now; `null` when nobody is on call, or when the endpoint does not compute it (`/schedule/infos`, `/schedule/self`, `/schedule/list` without a window)."
           },
-          "update_by": {
-            "description": "Last updater person ID.",
-            "format": "int64",
-            "type": "integer"
+          "next_oncall": {
+            "oneOf": [
+              {
+                "$ref": "#/components/schemas/ScheduleOncallGroup"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "The next shift with someone on duty after the current one; `null` when none is found within 45 days or the endpoint does not compute it."
           }
-        },
+        }
+      },
+      "ScheduleLayer": {
+        "type": "object",
+        "description": "One layer of a schedule. A rotation layer (`mode` 0) cycles through `groups`; an override layer (`mode` 1) puts its first group on call from `layer_start` to `layer_end`. Response-only fields (`account_id`, `schedule_id`, `create_*`, `update_*`) are ignored in requests.",
         "required": [
-          "id",
-          "name",
           "account_id",
-          "group_id",
-          "disabled",
-          "create_at",
-          "create_by",
-          "update_at",
-          "update_by",
-          "layers",
-          "schedule_layers",
-          "final_schedule",
-          "notify",
+          "name",
           "schedule_id",
-          "schedule_name",
-          "team_id",
-          "description",
-          "layer_schedules",
-          "status",
-          "cur_oncall",
-          "next_oncall"
+          "hidden",
+          "mode",
+          "weight",
+          "groups",
+          "rotation_duration",
+          "handoff_time",
+          "enable_time",
+          "expire_time",
+          "restrict_mode",
+          "restrict_start",
+          "restrict_end",
+          "restrict_periods",
+          "day_mask",
+          "create_at",
+          "create_by",
+          "update_at",
+          "update_by",
+          "fair_rotation",
+          "rotation_unit",
+          "rotation_value",
+          "mask_continuous_enabled"
         ],
-        "type": "object"
-      },
-      "ScheduleLayer": {
-        "description": "One rotation layer inside a schedule.",
         "properties": {
           "account_id": {
-            "description": "Account ID.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "ID of the account that owns the layer. Set by the server."
           },
-          "create_at": {
-            "description": "Creation timestamp (Unix seconds).",
+          "name": {
+            "type": "string",
+            "description": "Layer name. Either `name` or `layer_name` is required; `layer_name` wins when both are set."
+          },
+          "schedule_id": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "ID of the schedule the layer belongs to. Set by the server."
           },
-          "create_by": {
-            "description": "Creator person ID.",
+          "hidden": {
+            "type": "integer",
+            "enum": [
+              0,
+              1
+            ],
+            "description": "`1` leaves the layer out of `schedule_layers`; its shifts still feed `final_schedule`. `0` (default) shows it."
+          },
+          "mode": {
+            "type": "integer",
+            "description": "Layer type:\n- `0`: rotation layer — groups take turns according to `rotation_unit`/`rotation_value`.\n- `1`: override layer — the first group in `groups` is on call for the whole `layer_start`–`layer_end` period and takes precedence over rotation layers.",
+            "enum": [
+              0,
+              1
+            ]
+          },
+          "weight": {
+            "type": "integer",
+            "description": "Stored as sent; not used when computing shifts."
+          },
+          "groups": {
+            "type": [
+              "array",
+              "null"
+            ],
+            "items": {
+              "$ref": "#/components/schemas/ScheduleGroup"
+            },
+            "description": "On-call groups of the layer, in rotation order. Each group needs `group_name` (or `name`) and members with at least one person. `start`/`end` are ignored on input."
+          },
+          "rotation_duration": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Rotation length in seconds. Legacy alternative to `rotation_unit` + `rotation_value`: when only this is set, the server derives them (whole weeks, days or hours), and when only those are set, it fills this in (a month counts as 30 days)."
           },
-          "day_mask": {
-            "$ref": "#/components/schemas/ScheduleDayMask",
-            "description": "Day-of-week mask."
+          "handoff_time": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Weekly handoff point for weekly rotations, as seconds from Monday 00:00 in the schedule's time zone (`weekday × 86400 + seconds of day`, Monday = 0 … Sunday = 6). Not a Unix timestamp. Easier to set with `handoff`."
           },
           "enable_time": {
-            "description": "When the layer becomes effective (Unix seconds).",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "When the layer takes effect (Unix seconds). For rotations its time of day is also the daily handoff time. `layer_start` overrides it when sent."
           },
           "expire_time": {
-            "description": "When the layer expires (Unix seconds, 0 means never).",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "When the layer stops (Unix seconds); `0` = never. Must not be earlier than `enable_time`. `layer_end` overrides it when sent."
           },
-          "fair_rotation": {
-            "description": "Whether fair rotation is enabled.",
-            "type": "boolean"
+          "restrict_mode": {
+            "type": "integer",
+            "description": "Restricts the layer to time windows given in `restrict_periods`:\n- `0`: no restriction.\n- `1`: daily windows; offsets are seconds from 00:00 (0–86400).\n- `2`: weekly windows; offsets are seconds from Monday 00:00 (0–604800). Cannot be combined with `day_mask`.\nWindows use the schedule's time zone.",
+            "enum": [
+              0,
+              1,
+              2
+            ]
           },
-          "groups": {
-            "description": "Oncall groups participating in the rotation. Null when not set.",
-            "items": {
-              "$ref": "#/components/schemas/ScheduleGroup"
-            },
+          "restrict_start": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Legacy single-window start offset in seconds; prefer `restrict_periods`."
+          },
+          "restrict_end": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Legacy single-window end offset in seconds; prefer `restrict_periods`."
+          },
+          "restrict_periods": {
             "type": [
               "array",
               "null"
-            ]
+            ],
+            "items": {
+              "$ref": "#/components/schemas/ScheduleRestrictPeriod"
+            },
+            "description": "Time windows in which the layer is on call, interpreted by `restrict_mode`. Outside them the layer has nobody on call. `null` when not set."
           },
-          "handoff_time": {
-            "description": "Rotation handoff time as a weekly offset in seconds (weekday x 86400 + seconds since midnight), not an absolute Unix timestamp.",
+          "day_mask": {
+            "$ref": "#/components/schemas/ScheduleDayMask",
+            "description": "Weekdays on which the rotation layer is on call."
+          },
+          "create_at": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Creation timestamp (Unix seconds)."
           },
-          "hidden": {
-            "description": "Whether the layer is hidden in the UI (0 = no, 1 = yes).",
-            "type": "integer"
+          "create_by": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Creator person ID."
           },
-          "layer_end": {
-            "description": "Layer end timestamp (Unix seconds). null means open-ended.",
+          "update_at": {
+            "type": "integer",
             "format": "int64",
-            "type": [
-              "integer",
-              "null"
-            ]
+            "description": "Last update timestamp (Unix seconds)."
+          },
+          "update_by": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Last updater person ID."
           },
           "layer_name": {
-            "description": "User-facing layer name. Null when not set.",
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "Layer name shown in the console; same value as `name` in responses."
+          },
+          "fair_rotation": {
+            "type": "boolean",
+            "description": "When `true`, the group that starts each full round shifts by one, so that no group is always first. `false` (default) always restarts from the first group."
           },
           "layer_start": {
-            "description": "Layer effective start (Unix seconds). Null when not set.",
-            "format": "int64",
             "type": [
               "integer",
               "null"
-            ]
-          },
-          "mask_continuous_enabled": {
-            "description": "Whether continuous masking is enabled.",
-            "type": "boolean"
-          },
-          "mode": {
-            "description": "Layer mode: 0 = common rotation, 1 = override.",
-            "enum": [
-              0,
-              1
             ],
-            "type": "integer"
-          },
-          "name": {
-            "description": "Layer internal name.",
-            "type": "string"
-          },
-          "restrict_end": {
-            "description": "Legacy end offset inside the restriction window (seconds).",
             "format": "int64",
-            "type": "integer"
-          },
-          "restrict_mode": {
-            "description": "Restriction mode: 0 = none, 1 = day, 2 = week.",
-            "enum": [
-              0,
-              1,
-              2
-            ],
-            "type": "integer"
+            "description": "Same as `enable_time`; takes precedence over it in requests. `null` when `enable_time` is 0."
           },
-          "restrict_periods": {
-            "description": "Restriction windows inside each rotation cycle. Null when not set.",
-            "items": {
-              "$ref": "#/components/schemas/ScheduleRestrictPeriod"
-            },
+          "layer_end": {
             "type": [
-              "array",
+              "integer",
               "null"
-            ]
-          },
-          "restrict_start": {
-            "description": "Legacy start offset inside the restriction window (seconds).",
-            "format": "int64",
-            "type": "integer"
-          },
-          "rotation_duration": {
-            "description": "Rotation duration in seconds.",
+            ],
             "format": "int64",
-            "type": "integer"
+            "description": "Same as `expire_time`; takes precedence over it in requests. `null` means the layer never ends."
           },
           "rotation_unit": {
+            "type": "string",
             "description": "Rotation unit. On-call assignees rotate in turn by this unit.\n| Value | Meaning |\n|---|---|\n| `hour` | Rotates hourly. |\n| `day` | Rotates daily. |\n| `week` | Rotates weekly. |\n| `month` | Rotates monthly. |",
             "enum": [
               "hour",
               "day",
               "week",
               "month"
-            ],
-            "type": "string"
+            ]
           },
           "rotation_value": {
-            "description": "Rotation quantity (number of rotation_unit per cycle).",
+            "type": "integer",
             "format": "int64",
-            "minimum": 0,
-            "type": "integer"
+            "description": "Number of `rotation_unit`s each group stays on call before handing off. A rotation layer needs either this (with `rotation_unit`) or `rotation_duration`.",
+            "minimum": 0
           },
-          "schedule_id": {
-            "description": "Parent schedule ID.",
-            "format": "int64",
-            "type": "integer"
+          "mask_continuous_enabled": {
+            "type": "boolean",
+            "description": "Only applies when `day_mask` selects 1–6 weekdays. When `true`, each on-call day runs from the layer's start time of day to the same time the next day instead of midnight to midnight."
           },
-          "update_at": {
-            "description": "Last update timestamp (Unix seconds).",
-            "format": "int64",
-            "type": "integer"
+          "starts_at": {
+            "type": "object",
+            "writeOnly": true,
+            "description": "Request only. Layer start as a wall-clock date and time in the schedule's time zone; overrides `layer_start`/`enable_time`.",
+            "required": [
+              "date"
+            ],
+            "properties": {
+              "date": {
+                "type": "string",
+                "description": "Calendar date, `YYYY-MM-DD`."
+              },
+              "time": {
+                "type": "string",
+                "description": "Time of day, `HH:MM` (24-hour); defaults to `00:00`."
+              }
+            }
           },
-          "update_by": {
-            "description": "Last updater person ID.",
-            "format": "int64",
-            "type": "integer"
+          "ends_at": {
+            "type": "object",
+            "writeOnly": true,
+            "description": "Request only. Layer end as a wall-clock date and time in the schedule's time zone; overrides `layer_end`/`expire_time`. Send `{\"date\": \"\"}` to make the layer never end.",
+            "properties": {
+              "date": {
+                "type": "string",
+                "description": "Calendar date, `YYYY-MM-DD`."
+              },
+              "time": {
+                "type": "string",
+                "description": "Time of day, `HH:MM` (24-hour); defaults to `00:00`."
+              }
+            }
           },
-          "weight": {
-            "description": "Layer weight for ordering.",
-            "type": "integer"
+          "handoff": {
+            "type": "object",
+            "writeOnly": true,
+            "required": [
+              "weekday",
+              "time"
+            ],
+            "description": "Request only. Handoff weekday and time in the schedule's time zone; sets `handoff_time` and the time of day of `enable_time`.",
+            "properties": {
+              "weekday": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 7,
+                "description": "ISO weekday: `1` = Monday … `7` = Sunday."
+              },
+              "time": {
+                "type": "string",
+                "description": "Time of day, `HH:MM` (24-hour)."
+              }
+            }
+          },
+          "restricts_wall": {
+            "type": "array",
+            "writeOnly": true,
+            "description": "Request only. Restriction windows as wall-clock times in the schedule's time zone; replaces `restrict_periods`. With `restrict_mode` 1 use `from`/`to` (`to` = `00:00` means end of day); with `restrict_mode` 2 also set `from_day`/`to_day`. Rejected when `restrict_mode` is 0.",
+            "items": {
+              "type": "object",
+              "properties": {
+                "from_day": {
+                  "type": "integer",
+                  "minimum": 1,
+                  "maximum": 7,
+                  "description": "ISO weekday the window starts on (`restrict_mode` 2 only): `1` = Monday … `7` = Sunday."
+                },
+                "from": {
+                  "type": "string",
+                  "description": "Window start, `HH:MM`."
+                },
+                "to_day": {
+                  "type": "integer",
+                  "minimum": 1,
+                  "maximum": 7,
+                  "description": "ISO weekday the window ends on (`restrict_mode` 2 only)."
+                },
+                "to": {
+                  "type": "string",
+                  "description": "Window end, `HH:MM`."
+                }
+              }
+            }
           }
-        },
-        "required": [
-          "account_id",
-          "name",
-          "schedule_id",
-          "hidden",
-          "mode",
-          "weight",
-          "groups",
-          "rotation_duration",
-          "handoff_time",
-          "enable_time",
-          "expire_time",
-          "restrict_mode",
-          "restrict_start",
-          "restrict_end",
-          "restrict_periods",
-          "day_mask",
-          "create_at",
-          "create_by",
-          "update_at",
-          "update_by",
-          "fair_rotation",
-          "rotation_unit",
-          "rotation_value",
-          "mask_continuous_enabled"
-        ],
-        "type": "object"
+        }
       },
       "ScheduleListRequest": {
-        "description": "Schedule list request. limit defaults to 10 and is capped at 100; p defaults to 1. is_my_team and is_my_manage are mutually exclusive.",
+        "type": "object",
+        "description": "Schedule list filters. `limit` defaults to 10 and is capped at 100; `p` defaults to 1. `is_my_team` and `is_my_manage` cannot both be true.",
         "properties": {
-          "end": {
-            "description": "Window end timestamp (Unix seconds).",
-            "format": "int64",
-            "type": "integer"
-          },
-          "is_my_manage": {
-            "description": "Only return schedules created by the current user within their teams.",
-            "type": "boolean"
+          "query": {
+            "type": "string",
+            "description": "Substring matched against the schedule name or description."
           },
-          "is_my_team": {
-            "description": "Only return schedules whose owning team the current user belongs to.",
-            "type": "boolean"
+          "p": {
+            "type": "integer",
+            "description": "Page number (1-indexed).",
+            "default": 1
           },
           "limit": {
+            "type": "integer",
+            "description": "Page size. Default 10; values above 100 are treated as 100.",
             "default": 10,
-            "description": "Page size. Default 10, max 100.",
-            "maximum": 100,
-            "type": "integer"
-          },
-          "p": {
-            "default": 1,
-            "description": "Page number (1-indexed).",
-            "type": "integer"
+            "maximum": 100
           },
-          "query": {
-            "description": "Search keyword matched against schedule name or description.",
-            "type": "string"
+          "is_my_team": {
+            "type": "boolean",
+            "description": "Only schedules owned by the caller's teams. A caller in no team gets an empty list."
           },
-          "start": {
-            "description": "When set together with end, computed layer schedules are returned. Span must be less than 45 days.",
-            "format": "int64",
-            "type": "integer"
+          "is_my_manage": {
+            "type": "boolean",
+            "description": "Only schedules owned by the caller's teams or created by the caller."
           },
           "team_ids": {
-            "description": "Filter by team IDs.",
+            "type": "array",
             "items": {
-              "format": "int64",
-              "type": "integer"
+              "type": "integer",
+              "format": "int64"
             },
-            "type": "array"
+            "description": "Only schedules owned by these teams; intersected with `is_my_team`/`is_my_manage` when either is set."
+          },
+          "start": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Window start, 10-digit Unix seconds. Send together with `end` to compute layers and shifts."
+          },
+          "end": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Window end, 10-digit Unix seconds, after `start` and at most 45 days later. Sending `end` without `start` is rejected."
           }
-        },
-        "type": "object"
+        }
       },
       "ScheduleListResponse": {
+        "type": "object",
         "description": "Schedule list response.",
+        "required": [
+          "items",
+          "total"
+        ],
         "properties": {
           "items": {
-            "description": "Schedules on this page; null when no schedule matches.",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/ScheduleItem"
             },
-            "type": [
-              "array",
-              "null"
-            ]
+            "description": "Schedules on this page; an empty array when none match."
           },
           "total": {
-            "description": "Total number of schedules matching the filters.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Total number of schedules matching the filters."
           }
-        },
-        "required": [
-          "items",
-          "total"
-        ],
-        "type": "object"
+        }
       },
       "ScheduleMember": {
+        "type": "object",
         "description": "Schedule group member reference.",
+        "required": [
+          "role_id",
+          "person_ids"
+        ],
         "properties": {
+          "role_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "On-call role assigned to the people in this slot; `0` = no role.",
+            "minimum": 0
+          },
           "person_ids": {
-            "description": "Person IDs in this slot.",
+            "type": "array",
             "items": {
-              "format": "int64",
-              "type": "integer"
+              "type": "integer",
+              "format": "int64"
             },
-            "minItems": 1,
-            "type": "array"
-          },
-          "role_id": {
-            "description": "Oncall role ID.",
-            "format": "int64",
-            "minimum": 0,
-            "type": "integer"
+            "description": "Member IDs in this slot; at least one.",
+            "minItems": 1
           }
-        },
-        "required": [
-          "role_id",
-          "person_ids"
-        ],
-        "type": "object"
+        }
       },
       "ScheduleNotify": {
+        "type": "object",
         "description": "Notification configuration attached to a schedule.",
+        "required": [
+          "fixed_time",
+          "by",
+          "webhooks"
+        ],
         "properties": {
           "advance_in_time": {
-            "description": "Advance notification lead time in seconds. `0` notifies exactly at shift start; omitting disables advance notification.",
-            "format": "int64",
             "type": [
               "integer",
               "null"
-            ]
-          },
-          "by": {
-            "$ref": "#/components/schemas/ScheduleNotifyBy",
-            "description": "Recipient notification preference; null when not configured."
+            ],
+            "format": "int64",
+            "description": "Lead time in seconds for the shift-change notification: `0` notifies at the start of the shift, `300` five minutes before. Omitted or `null` disables shift-change notifications."
           },
           "fixed_time": {
-            "$ref": "#/components/schemas/ScheduleFixedTimeNotifyInfo",
-            "description": "Fixed-time notification config; null when not configured."
+            "oneOf": [
+              {
+                "$ref": "#/components/schemas/ScheduleFixedTimeNotifyInfo"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "Send a shift summary at a fixed time; `null` when not configured."
+          },
+          "by": {
+            "oneOf": [
+              {
+                "$ref": "#/components/schemas/ScheduleNotifyBy"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "Personal notifications sent to the people on call; `null` when not configured."
           },
           "im": {
+            "type": "object",
             "additionalProperties": {
               "type": "string"
             },
-            "description": "Legacy IM-type to token map.",
-            "type": "object"
+            "description": "Legacy map of robot type to webhook token. Entries not already in `webhooks` are added to `webhooks` when read; use `webhooks` instead."
           },
           "webhooks": {
-            "description": "IM webhook notification channels; null when not configured.",
-            "items": {
-              "$ref": "#/components/schemas/ScheduleImNotify"
-            },
             "type": [
               "array",
               "null"
-            ]
+            ],
+            "items": {
+              "$ref": "#/components/schemas/ScheduleImNotify"
+            },
+            "description": "Group chats or robots that receive shift-change notifications; `null` when not configured."
           }
-        },
-        "required": [
-          "fixed_time",
-          "by",
-          "webhooks"
-        ],
-        "type": "object"
+        }
       },
       "ScheduleNotifyBy": {
+        "type": "object",
         "description": "Per-recipient notification preference.",
+        "required": [
+          "follow_preference",
+          "personal_channels"
+        ],
         "properties": {
           "follow_preference": {
-            "description": "Whether to follow each responder's personal notification preference.",
-            "type": "boolean"
+            "type": "boolean",
+            "description": "`true`: notify each person through the channels in their own shift-notification preference, ignoring `personal_channels`. `false`: use `personal_channels`."
           },
           "personal_channels": {
-            "description": "Personal notification channel keys.",
+            "type": [
+              "array",
+              "null"
+            ],
             "items": {
               "type": "string"
             },
-            "type": "array"
+            "description": "Channels used when `follow_preference` is `false`: `email`, `sms`, `push` (mobile app), and the IM apps `feishu_app`, `dingtalk_app`, `wecom_app`, `teams_app`, `slack_app`. An IM app value may carry the integration ID as `<type>:<integration ID>` (for example `feishu_app:5427276014131`). Unknown values are stored but never used. `null` when not set."
           }
-        },
-        "required": [
-          "follow_preference",
-          "personal_channels"
-        ],
-        "type": "object"
+        }
       },
       "ScheduleOncallGroup": {
+        "type": "object",
         "description": "Snapshot of the currently or next on-call group.",
+        "required": [
+          "start",
+          "end",
+          "group",
+          "update_at",
+          "weight",
+          "index"
+        ],
         "properties": {
+          "start": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Shift start timestamp (Unix seconds)."
+          },
           "end": {
-            "description": "Shift end timestamp (Unix seconds).",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Shift end timestamp (Unix seconds)."
           },
           "group": {
             "$ref": "#/components/schemas/ScheduleGroup",
             "description": "Oncall group on duty for the shift."
           },
-          "index": {
-            "description": "Index inside the rotation.",
-            "type": "integer"
-          },
-          "start": {
-            "description": "Shift start timestamp (Unix seconds).",
-            "format": "int64",
-            "type": "integer"
-          },
           "update_at": {
-            "description": "Update timestamp (Unix seconds).",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Update time as a Unix timestamp in seconds; always `0` in these responses."
           },
           "weight": {
-            "description": "Layer weight the shift comes from.",
-            "type": "integer"
+            "type": "integer",
+            "description": "Always `0` in these responses."
+          },
+          "index": {
+            "type": "integer",
+            "description": "Always `0` in these responses."
           }
-        },
-        "required": [
-          "start",
-          "end",
-          "group",
-          "update_at",
-          "weight",
-          "index"
-        ],
-        "type": "object"
+        }
       },
       "ScheduleRestrictPeriod": {
-        "description": "Restrict window inside a rotation cycle. restrict_start and restrict_end are second offsets and cannot be equal unless both are 0.",
+        "type": "object",
+        "description": "One on-call window inside a day or week (see `restrict_mode`). A window whose start is later than its end wraps past midnight (or the end of the week). `{0, 0}` means the whole day or week. Start and end may not be equal otherwise.",
+        "required": [
+          "restrict_start",
+          "restrict_end"
+        ],
         "properties": {
-          "restrict_end": {
-            "description": "End offset inside the rotation cycle.",
+          "restrict_start": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Window start in seconds: from 00:00 when `restrict_mode` is 1, from Monday 00:00 when it is 2."
           },
-          "restrict_start": {
-            "description": "Start offset inside the rotation cycle.",
+          "restrict_end": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Window end in seconds, same reference point as `restrict_start`."
           }
-        },
-        "required": [
-          "restrict_start",
-          "restrict_end"
-        ],
-        "type": "object"
+        }
       },
       "ScheduleSelfRequest": {
         "description": "Query parameters for listing the current user's schedules. start and end are required 10-digit Unix timestamps in seconds, and the window must not exceed 45 days.",
@@ -23518,169 +24445,194 @@
         "type": "object"
       },
       "ScheduleSelfResponse": {
-        "description": "Response of /schedule/self and /schedule/infos. Only the items field is populated.",
+        "type": "object",
+        "description": "Response of `/schedule/self` and `/schedule/infos`.",
+        "required": [
+          "items"
+        ],
         "properties": {
           "items": {
-            "description": "Schedules assigned to the current user (or matching the requested IDs); null when none.",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/ScheduleItem"
             },
-            "type": [
-              "array",
-              "null"
-            ]
+            "description": "Matching schedules; an empty array when none match."
           }
-        },
-        "required": [
-          "items"
-        ],
-        "type": "object"
+        }
       },
       "ScheduleUpsertRequest": {
-        "description": "Schedule create/update/preview request body. The server accepts the same shape as the schedule detail model; only the key fields are listed here. `schedule_name` (or the legacy `name`) is required on create, `schedule_id` is required on update, and `start`/`end` are required on preview.",
+        "type": "object",
+        "description": "Request body of `/schedule/create`, `/schedule/update` and `/schedule/preview`. `schedule_name` (or the legacy `name`) is required on create, `schedule_id` on update, and `start`/`end` on preview.",
         "properties": {
-          "description": {
-            "description": "Schedule description. Max 500 characters.",
-            "maxLength": 500,
+          "schedule_id": {
             "type": [
-              "string",
+              "integer",
               "null"
-            ]
+            ],
+            "format": "int64",
+            "description": "Schedule ID, required on update; obtain it from `POST /schedule/list`."
           },
-          "disabled": {
-            "description": "0 = enabled, 1 = disabled. Defaults to enabled when omitted.",
+          "schedule_name": {
             "type": [
-              "integer",
+              "string",
               "null"
-            ]
-          },
-          "end": {
-            "description": "Preview window end (Unix seconds, 10 digits). Required for /schedule/preview. Max 45 days after start.",
-            "format": "int64",
-            "type": "integer"
-          },
-          "layers": {
-            "description": "Rotation layers.",
-            "items": {
-              "$ref": "#/components/schemas/ScheduleLayer"
-            },
-            "type": "array"
+            ],
+            "description": "Schedule name, at most 40 characters, unique within the account. On update, omitting it keeps the current name.",
+            "maxLength": 40
           },
           "name": {
-            "description": "Legacy schedule name field. Used when schedule_name is empty.",
-            "maxLength": 40,
             "type": [
               "string",
               "null"
-            ]
-          },
-          "notify": {
-            "$ref": "#/components/schemas/ScheduleNotify",
-            "description": "Rotation notification configuration."
+            ],
+            "description": "Legacy name field, used on create only when `schedule_name` is empty. Ignored on update.",
+            "maxLength": 40
           },
-          "schedule_id": {
-            "description": "Schedule ID, required on update; obtain it from `POST /schedule/list`.",
-            "format": "int64",
+          "description": {
             "type": [
-              "integer",
+              "string",
               "null"
-            ]
+            ],
+            "description": "Schedule description, at most 500 characters. On update, omitting it keeps the current text and an empty string clears it.",
+            "maxLength": 500
           },
-          "schedule_name": {
-            "description": "Schedule display name. Max 40 characters.",
-            "maxLength": 40,
+          "team_id": {
             "type": [
-              "string",
+              "integer",
               "null"
-            ]
+            ],
+            "format": "int64",
+            "description": "ID of the owning team; obtain it from `POST /team/list`. On create, omitting it leaves the schedule without a team (`0`); on update, omitting it keeps the current team."
+          },
+          "time_zone": {
+            "type": "string",
+            "description": "IANA time zone in which the schedule's wall-clock rules are evaluated, for example `Asia/Shanghai` or `UTC`; abbreviations such as `EST` and `Etc/GMT±N` are rejected. Set on create (default: evaluated in `Asia/Shanghai`); immutable afterwards — on update send nothing or the current value. On preview it sets the evaluation time zone."
+          },
+          "layers": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/ScheduleLayer"
+            },
+            "description": "Rotation layers. Required in practice: on update the list replaces all existing layers, so omitting it deletes every layer."
+          },
+          "notify": {
+            "oneOf": [
+              {
+                "$ref": "#/components/schemas/ScheduleNotify"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "Shift notification configuration. On update, omitting it keeps the current configuration; a sent object replaces it entirely."
           },
           "start": {
-            "description": "Preview window start (Unix seconds, 10 digits). Required for /schedule/preview.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Preview window start, 10-digit Unix seconds. Required for `/schedule/preview`; ignored by create and update."
           },
-          "team_id": {
-            "description": "Owning team ID; obtain it from `POST /team/list`.",
+          "end": {
+            "type": "integer",
             "format": "int64",
+            "description": "Preview window end, 10-digit Unix seconds, after `start` and at most 45 days later. Required for `/schedule/preview`; ignored by create and update."
+          },
+          "disabled": {
             "type": [
               "integer",
               "null"
-            ]
+            ],
+            "enum": [
+              0,
+              1,
+              null
+            ],
+            "description": "Create only: `0` = enabled (default), `1` = disabled. Ignored on update — use `status` instead."
+          },
+          "status": {
+            "type": [
+              "integer",
+              "null"
+            ],
+            "enum": [
+              0,
+              1,
+              null
+            ],
+            "description": "`0` = enabled, `1` = disabled. On update, omitting it keeps the current state. On create it takes precedence over `disabled`."
           }
-        },
-        "type": "object"
+        }
       },
       "ServiceDeskPlusRequestListRequest": {
+        "type": "object",
         "description": "Filters for listing ServiceDeskPlus request synchronization records. A time window is optional when querying by incident ID; otherwise provide a Unix-second window no longer than 30 days.",
         "properties": {
-          "asc": {
-            "description": "When `true`, sort by internal record ID ascending; otherwise descending.",
-            "type": "boolean"
+          "start_time": {
+            "type": "integer",
+            "format": "int64",
+            "minimum": 0,
+            "description": "Window start, Unix seconds. Optional when `incident_id` is provided."
+          },
+          "end_time": {
+            "type": "integer",
+            "format": "int64",
+            "minimum": 0,
+            "description": "Window end, Unix seconds. Must be greater than or equal to `start_time`. Optional when `incident_id` is provided."
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "success",
+              "failed"
+            ],
+            "description": "Filter by sync status: `success` or `failed`."
           },
           "channel_ids": {
-            "description": "Channel IDs to filter by.",
+            "type": "array",
             "items": {
-              "format": "int64",
-              "type": "integer"
+              "type": "integer",
+              "format": "int64"
             },
-            "type": "array"
+            "description": "Channel IDs to filter by."
           },
-          "end_time": {
-            "description": "Window end, Unix seconds. Must be greater than or equal to `start_time`. Optional when `incident_id` is provided.",
+          "integration_id": {
+            "type": "integer",
             "format": "int64",
             "minimum": 0,
-            "type": "integer"
+            "description": "ServiceDeskPlus integration ID."
           },
           "incident_id": {
-            "description": "Flashduty incident ID. When set, the time window can be omitted.",
+            "type": "string",
             "maxLength": 64,
-            "type": "string"
+            "description": "Flashduty incident ID. When set, the time window can be omitted."
           },
-          "integration_id": {
-            "description": "ServiceDeskPlus integration ID.",
-            "format": "int64",
-            "minimum": 0,
-            "type": "integer"
+          "request_id": {
+            "type": "string",
+            "maxLength": 64,
+            "description": "ServiceDeskPlus request ID."
           },
-          "limit": {
-            "default": 20,
-            "description": "Page size. Defaults to 20; maximum 100.",
-            "format": "int64",
-            "maximum": 100,
-            "minimum": 0,
-            "type": "integer"
+          "asc": {
+            "type": "boolean",
+            "description": "When `true`, sort by internal record ID ascending; otherwise descending."
           },
           "p": {
-            "description": "Page number starting at 1. Ignored when `search_after_ctx` is set.",
+            "type": "integer",
             "format": "int64",
             "minimum": 0,
-            "type": "integer"
-          },
-          "request_id": {
-            "description": "ServiceDeskPlus request ID.",
-            "maxLength": 64,
-            "type": "string"
-          },
-          "search_after_ctx": {
-            "description": "Pagination cursor: leave empty for the first page, then pass the `search_after_ctx` returned by the previous response.",
-            "type": "string"
+            "description": "Not supported; pagination uses only `search_after_ctx`, so this value is ignored."
           },
-          "start_time": {
-            "description": "Window start, Unix seconds. Optional when `incident_id` is provided.",
+          "limit": {
+            "type": "integer",
             "format": "int64",
             "minimum": 0,
-            "type": "integer"
+            "maximum": 100,
+            "default": 20,
+            "description": "Page size. Defaults to 20; maximum 100."
           },
-          "status": {
-            "description": "Filter by sync status: `success` or `failed`.",
-            "enum": [
-              "success",
-              "failed"
-            ],
-            "type": "string"
+          "search_after_ctx": {
+            "type": "string",
+            "description": "Pagination cursor: leave empty for the first page, then pass the `search_after_ctx` returned by the previous response."
           }
-        },
-        "type": "object"
+        }
       },
       "ServiceDeskPlusRequestListResponse": {
         "description": "Paginated list of ServiceDeskPlus request synchronization records.",
@@ -23845,29 +24797,26 @@
         "type": "object"
       },
       "SessionGetResponse": {
+        "type": "object",
         "description": "A session plus a backward-paged window of its events.",
         "properties": {
+          "session": {
+            "$ref": "#/components/schemas/SessionItem"
+          },
           "events": {
-            "description": "Recent events, ascending by (created_at, event_id).",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/EventItem"
             },
-            "type": "array"
+            "description": "The newest page of events (older pages via `search_after_ctx`), ascending by (`created_at`, `event_id`). Internal control events are excluded. Always an array."
           },
           "has_more_older": {
-            "description": "True when older events remain beyond this page.",
-            "type": "boolean"
+            "type": "boolean",
+            "description": "True when older events remain beyond this page."
           },
           "search_after_ctx": {
-            "description": "Opaque keyset cursor; pass back as search_after_ctx to fetch the next older page. Omitted when has_more_older is false.",
-            "type": "string"
-          },
-          "session": {
-            "$ref": "#/components/schemas/SessionItem"
-          },
-          "suggest_init": {
-            "description": "Account-wide onboarding flag: true when the account has no knowledge in any scope; not specific to this session.",
-            "type": "boolean"
+            "type": "string",
+            "description": "Opaque keyset cursor; pass back as search_after_ctx to fetch the next older page. Omitted when has_more_older is false."
           },
           "pending_messages": {
             "type": "array",
@@ -23881,214 +24830,252 @@
           "session",
           "events",
           "has_more_older",
-          "suggest_init",
           "pending_messages"
-        ],
-        "type": "object"
+        ]
       },
       "SessionItem": {
+        "type": "object",
         "description": "One agent session row.",
         "properties": {
-          "access_source": {
-            "description": "How the caller received access to this session. Omitted when no access source is resolved. One of:\n| Value | Meaning |\n| --- | --- |\n| `owner` | Caller is the session creator (full access) |\n| `team_member` | Caller belongs to the session's bound team (full access) |\n| `manager` | Manager grant (reserved; never produced by the current version) |\n| `share_link` | Granted via a valid share link (view/fork only; cannot continue or manage) |\n| `participant` | Same-account non-member granted via a participable team session (view/continue/fork only) |",
-            "enum": [
-              "owner",
-              "team_member",
-              "manager",
-              "share_link",
-              "participant"
-            ],
-            "type": "string"
+          "session_id": {
+            "type": "string",
+            "description": "Session identifier."
+          },
+          "parent_session_id": {
+            "type": "string",
+            "description": "Parent session id for subagent (child) sessions; empty otherwise."
+          },
+          "session_name": {
+            "type": "string",
+            "description": "Session title; may be empty for untitled sessions."
           },
           "app_name": {
-            "description": "Agent app that owns the session.",
-            "type": "string"
+            "type": "string",
+            "description": "Agent app that owns the session."
           },
-          "archived_at": {
-            "description": "Unix timestamp in milliseconds when archived; 0 means not archived.",
-            "format": "int64",
-            "type": "integer"
+          "entry_kind": {
+            "type": "string",
+            "description": "Surface that created the session:\n- `web`: web console (also returned for subagent child sessions and for sessions that predate this field)\n- `im`: IM bot or IM H5 client\n- `api`: public API\n- `automation`: automation rule (unattended run)",
+            "enum": [
+              "web",
+              "im",
+              "api",
+              "automation"
+            ]
           },
-          "bound_environment": {
-            "$ref": "#/components/schemas/EnvironmentBinding"
+          "person_id": {
+            "type": "string",
+            "description": "Creator person id."
           },
-          "can_continue": {
-            "description": "True when the caller can add a new turn to this session.",
-            "type": "boolean"
+          "ref": {
+            "type": "string",
+            "description": "Business object the session is about, as a prefixed reference (for example an incident reference). Omitted when the session is not bound to one."
           },
-          "can_fork": {
-            "description": "True when the caller can fork this session.",
-            "type": "boolean"
+          "creator_name": {
+            "type": "string",
+            "description": "Display name of the session creator. Returned by `POST /safari/session/list` only; omitted when the name lookup fails."
           },
-          "can_manage": {
-            "description": "True when the caller may rename/archive/delete the session; personal sessions are creator-only, team sessions allow the creator, account admin, or team member.",
-            "type": "boolean"
+          "team_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Owning team id; 0 means no team is bound. Immutable after create."
+          },
+          "team_name": {
+            "type": "string",
+            "description": "Resolved team name; empty for unbound rows or deleted teams."
+          },
+          "automation": {
+            "type": "object",
+            "description": "Automation rule that produced this session. Returned by `POST /safari/session/get` only, for sessions started by an automation rule.",
+            "properties": {
+              "rule_id": {
+                "type": "string",
+                "description": "ID of the automation rule."
+              },
+              "rule_name": {
+                "type": "string",
+                "description": "Rule name; empty when the rule has since been deleted."
+              },
+              "trigger_kind": {
+                "type": "string",
+                "enum": [
+                  "schedule",
+                  "manual",
+                  "http_post",
+                  "oncall_incident",
+                  "war_room_created",
+                  ""
+                ],
+                "description": "How this run was triggered:\n- `schedule`: the rule's schedule fired\n- `manual`: run on demand (console or `POST /safari/automation/rule/run`)\n- `http_post`: the rule's HTTP trigger URL was called\n- `oncall_incident`: an On-call incident event matched the rule\n- `war_room_created`: a war room was created\n- `\"\"`: the run record no longer exists"
+              },
+              "can_edit": {
+                "type": "boolean",
+                "description": "True when the caller may open and manage the rule; false when the rule has been deleted."
+              }
+            },
+            "required": [
+              "rule_id",
+              "rule_name",
+              "trigger_kind",
+              "can_edit"
+            ]
+          },
+          "is_mine": {
+            "type": "boolean",
+            "description": "True when the caller created this session."
           },
           "can_view": {
-            "description": "True when the caller can view this session.",
-            "type": "boolean"
+            "type": "boolean",
+            "description": "True when the caller can read this session: always true for the creator, team members, and other members of the same account on a team session; true through a valid share link otherwise."
           },
-          "context_resolved": {
-            "$ref": "#/components/schemas/ContextResolvedItem"
+          "can_continue": {
+            "type": "boolean",
+            "description": "True when the caller can add a new turn to this session."
           },
-          "context_window": {
-            "description": "The bound model's max context size in tokens. 0 means unknown.",
-            "format": "int64",
-            "type": "integer"
+          "can_manage": {
+            "type": "boolean",
+            "description": "True when the caller may rename, archive, or delete the session: the creator of a personal session, or the creator or a member of the owning team for a team session. Account owners and admins get no exemption."
           },
-          "created_at": {
-            "description": "Unix timestamp in milliseconds when the session was created.",
-            "format": "int64",
-            "type": "integer"
+          "can_fork": {
+            "type": "boolean",
+            "description": "True when the caller can fork this session."
           },
-          "current_context_tokens": {
-            "description": "Size in tokens of the LLM context window as of the most recent turn. 0 means no turn has completed.",
-            "format": "int64",
-            "type": "integer"
+          "access_source": {
+            "type": "string",
+            "description": "How the caller obtained access. Omitted when the caller has no access. One of:\n| Value | Meaning |\n| --- | --- |\n| `owner` | Caller created the session (full access) |\n| `team_member` | Caller belongs to the session's team (full access) |\n| `manager` | Reserved; not produced by the current version |\n| `share_link` | Granted by a valid share link (view and fork only; view only for subagent child sessions) |\n| `participant` | Another member of the same account on a team session (view, continue, fork; no manage) |",
+            "enum": [
+              "owner",
+              "team_member",
+              "manager",
+              "share_link",
+              "participant"
+            ]
           },
-          "current_turn_active_ms": {
-            "description": "Active working duration in milliseconds for the current or most recent round, excluding time spent waiting on ask_user; resets to 0 at the start of each new round.",
-            "format": "int64",
-            "type": "integer"
+          "share_enabled": {
+            "type": "boolean",
+            "description": "True when the session's share link is active."
           },
-          "current_turn_started_at": {
-            "description": "Unix timestamp in milliseconds when the current or most recent round started; 0 if no round has started yet.",
+          "share_version": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Revision of the share link; it increases when sharing is revoked."
           },
-          "current_turn_tokens": {
-            "description": "Total tokens (input+output+reasoning) for the in-flight round across the parent and its subagents; only computed by session/get while the session is running, always 0 in session/list responses and when idle.",
+          "shared_at": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Unix timestamp in milliseconds when sharing was last enabled; 0 if never shared."
           },
-          "current_turn_wait_ms": {
-            "description": "Accumulated ask_user human-wait duration in milliseconds for the current round; resets to 0 at the start of each new round.",
+          "shared_by": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Person ID that most recently enabled sharing; 0 if never shared."
           },
-          "entry_kind": {
-            "description": "Surface that created the session. One of:\n| Value | Meaning |\n| --- | --- |\n| `web` | Created from the web console |\n| `im` | Created from an IM client (IM bot / IM H5) |\n| `api` | Created via the public API |\n| `automation` | Created by an automation rule (unattended run) |\n| `subagent` | Child session spawned by a parent's agent_dispatch (audit label; at runtime it executes on the web tool surface) |",
+          "status": {
+            "type": "string",
+            "description": "Lifecycle status. Always `enabled` in responses: deleted sessions are never returned.",
             "enum": [
-              "web",
-              "im",
-              "api",
-              "automation",
-              "subagent"
-            ],
-            "type": "string"
-          },
-          "has_unread": {
-            "description": "True when there is assistant output the caller has not yet viewed.",
-            "type": "boolean"
+              "enabled"
+            ]
           },
           "incognito": {
-            "description": "True for incognito (non-persisted-memory) sessions.",
-            "type": "boolean"
-          },
-          "is_mine": {
-            "description": "True when the caller created this session.",
-            "type": "boolean"
-          },
-          "is_running": {
-            "description": "True when an agent turn is currently in flight for this session.",
-            "type": "boolean"
+            "type": "boolean",
+            "description": "True for incognito (non-persisted-memory) sessions."
           },
-          "standing_tasks": {
+          "created_at": {
             "type": "integer",
-            "description": "Number of process-type tasks (background shell or monitor) still alive when the response was rendered."
+            "format": "int64",
+            "description": "Unix timestamp in milliseconds when the session was created."
           },
-          "last_event_at": {
-            "description": "Unix timestamp in milliseconds of the most recent assistant-side event.",
+          "updated_at": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Unix timestamp in milliseconds of the last session update."
           },
-          "parent_session_id": {
-            "description": "Parent session id for subagent (child) sessions; empty otherwise.",
-            "type": "string"
+          "template_staging_round_id": {
+            "type": "string",
+            "description": "Current save→validate round id (template-assistant only); empty otherwise."
           },
-          "person_id": {
-            "description": "Creator person id.",
-            "type": "string"
+          "state": {
+            "type": "object",
+            "additionalProperties": true,
+            "description": "Raw session-state key/value map. Returned by `POST /safari/session/get` only; omitted when empty."
           },
-          "creator_name": {
-            "type": "string",
-            "description": "Display name of the session creator, resolved when the response is rendered. Omitted when the member lookup fails."
+          "bound_environment": {
+            "$ref": "#/components/schemas/EnvironmentBinding"
           },
-          "pinned_at": {
-            "description": "Caller's per-user pin time as a Unix timestamp in milliseconds; 0 means not pinned.",
-            "format": "int64",
-            "type": "integer"
+          "context_resolved": {
+            "$ref": "#/components/schemas/ContextResolvedItem"
           },
-          "session_id": {
-            "description": "Session identifier.",
-            "type": "string"
+          "token_usage": {
+            "$ref": "#/components/schemas/SessionTokenUsage"
           },
-          "session_name": {
-            "description": "Session title; may be empty for untitled sessions.",
-            "type": "string"
+          "current_context_tokens": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Size in tokens of the LLM context window as of the most recent turn. 0 means no turn has completed."
           },
-          "share_enabled": {
-            "description": "True when the session's share link is active.",
-            "type": "boolean"
+          "context_window": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Maximum context size of the session's model, in tokens. Computed by `POST /safari/session/get` only; always 0 in list responses and when the lookup fails."
           },
-          "share_version": {
-            "description": "Revision of the share link; it increases when sharing is revoked.",
+          "archived_at": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Unix timestamp in milliseconds when archived; 0 means not archived."
           },
-          "shared_at": {
-            "description": "Unix timestamp in milliseconds when sharing was last enabled; 0 if never shared.",
+          "pinned_at": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "When the caller pinned this session, as a Unix timestamp in milliseconds; 0 when not pinned. Pins are per user. Filled by `POST /safari/session/list` only; always 0 in `POST /safari/session/get`."
           },
-          "shared_by": {
-            "description": "Person ID that most recently enabled sharing; 0 if never shared.",
+          "last_event_at": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Unix timestamp in milliseconds of the latest assistant-side event; user messages alone do not advance it. Omitted when 0."
           },
-          "state": {
-            "additionalProperties": true,
-            "description": "Raw session-state bag (session-scoped keys). Omitted when empty.",
-            "type": "object"
+          "is_running": {
+            "type": "boolean",
+            "description": "True when an agent turn is currently in flight for this session."
           },
-          "status": {
-            "description": "Lifecycle status. One of: `enabled` (active), `deleted` (soft-deleted, no longer accessible).",
-            "enum": [
-              "enabled",
-              "deleted"
-            ],
-            "type": "string"
+          "standing_tasks": {
+            "type": "integer",
+            "description": "Number of the session's process-type tasks (background shell commands or monitors) still alive when the response was built; 0 when none or when the count cannot be read."
           },
-          "team_id": {
-            "description": "Owning team id; 0 means no team is bound. Immutable after create.",
-            "format": "int64",
-            "type": "integer"
+          "has_unread": {
+            "type": "boolean",
+            "description": "True when assistant output exists that the caller has not viewed yet; always false while `is_running` is true. Computed by `POST /safari/session/list` only; always false in `POST /safari/session/get`."
           },
-          "team_name": {
-            "description": "Resolved team name; empty for unbound rows or deleted teams.",
-            "type": "string"
+          "has_open_tasks": {
+            "type": "boolean",
+            "description": "True when the session still has open tasks (for example running subagents or background processes), which tells a handed-off turn apart from a settled session. Returned by `POST /safari/session/get` only; omitted when false or when the lookup fails, so treat absence as unknown rather than idle."
           },
-          "template_staging_round_id": {
-            "description": "Current save→validate round id (template-assistant only); empty otherwise.",
-            "type": "string"
+          "current_turn_started_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Unix timestamp in milliseconds when the current or most recent round started; 0 if no round has started yet."
           },
-          "token_usage": {
-            "$ref": "#/components/schemas/SessionTokenUsage"
+          "current_turn_active_ms": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Active working duration in milliseconds for the current or most recent round, excluding time spent waiting on ask_user; resets to 0 at the start of each new round."
           },
-          "updated_at": {
-            "description": "Unix timestamp in milliseconds of the last session update.",
+          "current_turn_wait_ms": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Accumulated ask_user human-wait duration in milliseconds for the current round; resets to 0 at the start of each new round."
           },
-          "has_open_tasks": {
-            "type": "boolean",
-            "description": "Whether the session still has open tasks, used to tell a handed-off turn from a settled session. Best-effort: when the read fails the field is absent (`omitempty`), which callers must treat as \"unknown\", never as proof the session is idle."
+          "current_turn_tokens": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Total tokens (input+output+reasoning) for the in-flight round across the parent and its subagents; only computed by session/get while the session is running, always 0 in session/list responses and when idle."
           }
         },
         "required": [
           "session_id",
           "session_name",
           "app_name",
+          "entry_kind",
           "person_id",
           "team_id",
           "is_mine",
@@ -24115,14 +25102,15 @@
           "current_turn_active_ms",
           "current_turn_wait_ms",
           "current_turn_tokens"
-        ],
-        "type": "object"
+        ]
       },
       "SessionListRequest": {
+        "type": "object",
         "description": "Filters for listing agent sessions. `all` visibility means the caller's own personal sessions plus accessible team sessions; account admins do not see other users' personal sessions.",
         "properties": {
           "app_name": {
-            "description": "Agent app whose sessions to list. One of:\n| Value | Meaning |\n| --- | --- |\n| `ask-ai` | Ask AI assistant |\n| `support` | Customer-support agent |\n| `support-website` | Website support agent (exposed over A2A, not built into the console) |\n| `support-flashcat` | Flashcat-site support agent (exposed over A2A) |\n| `ai-sre` | The AI SRE main app |\n| `template-assistant` | Notification-template assistant (template editing/validation) |\n| `swe` | Internal benchmarking app (not customer-facing) |",
+            "type": "string",
+            "description": "Agent app whose sessions to list. One of:\n| Value | Meaning |\n| --- | --- |\n| `ask-ai` | Ask AI assistant |\n| `support` | Customer-support agent |\n| `support-website` | Website support agent (exposed over A2A, not built into the console) |\n| `support-flashcat` | Flashcat-site support agent (exposed over A2A) |\n| `ai-sre` | The AI SRE main app |\n| `template-assistant` | Notification-template assistant (template editing/validation) |\n| `query-assistant` | Monitors query-writing assistant |\n| `swe` | Software-engineering agent app (not offered in the console) |",
             "enum": [
               "ask-ai",
               "support",
@@ -24130,82 +25118,60 @@
               "support-flashcat",
               "ai-sre",
               "template-assistant",
+              "query-assistant",
               "swe"
-            ],
-            "type": "string"
-          },
-          "asc": {
-            "description": "Ascending order when true, descending when false. Only honored together with `orderby`; when `orderby` is omitted the sort is always `updated_at` descending.",
-            "type": "boolean"
-          },
-          "entry_kinds": {
-            "description": "Restrict to sessions produced by these surfaces; empty returns every kind.",
-            "items": {
-              "enum": [
-                "web",
-                "im",
-                "api",
-                "automation"
-              ],
-              "type": "string"
-            },
-            "type": "array"
-          },
-          "include_subagent_sessions": {
-            "description": "Include subagent-dispatched sessions in the list.",
-            "type": "boolean"
+            ]
           },
-          "keyword": {
-            "description": "Filter by session-name keyword.",
-            "maxLength": 64,
-            "type": "string"
+          "p": {
+            "type": "integer",
+            "description": "Page number, 1-based.",
+            "default": 1,
+            "minimum": 1
           },
           "limit": {
-            "default": 20,
+            "type": "integer",
             "description": "Page size, 1–100.",
-            "maximum": 100,
             "minimum": 1,
-            "type": "integer"
+            "maximum": 100,
+            "default": 20
           },
           "orderby": {
+            "type": "string",
             "description": "Sort field: `created_at` by creation time, `updated_at` by last update; defaults to `updated_at` when omitted.",
             "enum": [
               "created_at",
               "updated_at"
-            ],
-            "type": "string"
+            ]
           },
-          "p": {
-            "default": 1,
-            "description": "Page number, 1-based.",
-            "minimum": 1,
-            "type": "integer"
+          "asc": {
+            "type": "boolean",
+            "description": "Ascending order when true, descending when false. Only honored together with `orderby`; when `orderby` is omitted the sort is always `updated_at` descending."
+          },
+          "include_subagent_sessions": {
+            "type": "boolean",
+            "description": "When true, also list child sessions spawned by subagent dispatch. Defaults to false (top-level sessions only)."
+          },
+          "keyword": {
+            "type": "string",
+            "description": "Return only sessions whose `session_name` contains this text; leading and trailing spaces are ignored.",
+            "maxLength": 64
           },
           "scope": {
-            "description": "Visibility scope: `all` (own personal + accessible team sessions), `personal`, or `team`; default `all`.",
+            "type": "string",
+            "description": "Visibility scope:\n- `all` (default): sessions the caller created plus sessions bound to teams the caller belongs to\n- `personal`: the caller's own sessions with no team (`team_id` = 0)\n- `team`: sessions bound to teams the caller belongs to; empty when the caller is in no team",
             "enum": [
               "all",
               "personal",
               "team"
-            ],
-            "type": "string"
-          },
-          "status": {
-            "description": "Archive bucket: active (default) returns un-archived, archived returns archived, all returns both.",
-            "enum": [
-              "active",
-              "archived",
-              "all"
-            ],
-            "type": "string"
+            ]
           },
           "team_ids": {
-            "description": "Optional explicit team filter; intersects with `scope` and never expands access.",
+            "type": "array",
             "items": {
-              "format": "int64",
-              "type": "integer"
+              "type": "integer",
+              "format": "int64"
             },
-            "type": "array"
+            "description": "Optional explicit team filter; intersects with `scope` and never expands access."
           },
           "person_ids": {
             "type": "array",
@@ -24214,39 +25180,55 @@
               "format": "int64"
             },
             "description": "Filter by who started the session: returns only sessions started by these members (a session is kept when `person_id` matches any of them). Intersects with `scope` and `team_ids`, so it never widens what the caller is allowed to see."
+          },
+          "entry_kinds": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "enum": [
+                "web",
+                "im",
+                "api",
+                "automation"
+              ]
+            },
+            "description": "Restrict to sessions created from these surfaces: `web` (console), `im` (IM bot or IM H5), `api` (public API), `automation` (automation rule). Empty returns every kind."
+          },
+          "status": {
+            "type": "string",
+            "description": "Archive filter:\n- `active` (default): sessions that are not archived\n- `archived`: archived sessions only\n- `all`: both",
+            "enum": [
+              "active",
+              "archived",
+              "all"
+            ]
           }
         },
         "required": [
           "app_name"
-        ],
-        "type": "object"
+        ]
       },
       "SessionListResponse": {
+        "type": "object",
         "description": "A page of agent sessions.",
         "properties": {
+          "total": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Number of matching sessions, ignoring pagination. Pinned sessions prepended on page 1 are not counted."
+          },
           "sessions": {
-            "description": "The page of sessions.",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/SessionItem"
             },
-            "type": "array"
-          },
-          "suggest_init": {
-            "description": "Account-wide onboarding flag: true when the account has no knowledge in any scope; not dependent on this call's filters.",
-            "type": "boolean"
-          },
-          "total": {
-            "description": "Total number of sessions matching the filter (ignoring pagination).",
-            "format": "int64",
-            "type": "integer"
+            "description": "The page of sessions: on page 1, the caller's matching pinned sessions (newest pin first) followed by up to `limit` other sessions in the requested order."
           }
         },
         "required": [
           "total",
-          "sessions",
-          "suggest_init"
-        ],
-        "type": "object"
+          "sessions"
+        ]
       },
       "SessionTokenUsage": {
         "description": "Cumulative session-level token rollup across all turns. The account-billing source of truth.",
@@ -24281,32 +25263,33 @@
         "type": "object"
       },
       "SignedURLs": {
+        "type": "object",
         "description": "Short-lived signed URLs for downloading or previewing a file.",
         "properties": {
-          "content_type": {
-            "description": "MIME type of the file.",
-            "type": "string"
-          },
           "download_url": {
-            "description": "Relative URL (`/safari/artifact/stream?...`) that serves the file as an attachment. Prepend the API base `https://api.flashcat.cloud` before use; expires with `expires_in`.",
-            "type": "string"
+            "type": "string",
+            "description": "Relative URL (`/safari/artifact/stream?...`) that serves the file as an attachment. Prepend the API base `https://api.flashcat.cloud` before use; expires with `expires_in`."
           },
-          "expires_in": {
-            "description": "Validity of both URLs in seconds (300).",
-            "type": "integer"
+          "preview_url": {
+            "type": "string",
+            "description": "Same as `download_url` but served inline for browser preview."
           },
-          "name": {
-            "description": "File name including extension.",
-            "type": "string"
+          "expires_in": {
+            "type": "integer",
+            "description": "Validity of both URLs in seconds. Always `300`."
           },
-          "preview_url": {
-            "description": "Same as `download_url` but served inline for browser preview.",
-            "type": "string"
+          "name": {
+            "type": "string",
+            "description": "File name including extension."
           },
           "size": {
-            "description": "File size in bytes.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "File size in bytes."
+          },
+          "content_type": {
+            "type": "string",
+            "description": "MIME type, derived from the file-name extension when the file was produced: `text/html` (.html/.htm), `text/markdown` (.md), `text/plain` (.txt/.log), `text/csv`, `text/yaml` (.yaml/.yml), `text/x-python`, `text/x-go`, `text/x-sh`, `application/json`, `application/xml`, `application/pdf`, `image/png`, `image/jpeg`, `image/gif`, `image/svg+xml`, `image/webp`, `application/zip`, `application/gzip` (.tar/.gz/.tgz); any other extension is `application/octet-stream`."
           }
         },
         "required": [
@@ -24316,112 +25299,111 @@
           "name",
           "size",
           "content_type"
-        ],
-        "type": "object"
+        ]
       },
       "SilenceRuleItem": {
+        "type": "object",
+        "required": [
+          "account_id",
+          "channel_id",
+          "rule_name",
+          "description",
+          "time_filters",
+          "time_filter",
+          "filters",
+          "is_directly_discard",
+          "status",
+          "rule_id",
+          "updated_by",
+          "created_at",
+          "updated_at",
+          "is_effective"
+        ],
         "properties": {
           "account_id": {
-            "description": "ID of the account the rule belongs to.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "ID of the account the rule belongs to."
           },
           "channel_id": {
-            "description": "ID of the channel the rule belongs to.",
-            "format": "int64",
-            "type": "integer"
-          },
-          "created_at": {
-            "description": "Creation time, Unix timestamp in seconds.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "ID of the channel the rule belongs to."
           },
-          "deleted_at": {
-            "description": "Deletion time, Unix timestamp in seconds. Omitted unless the rule is soft-deleted; deleted rules are excluded from list responses.",
-            "format": "int64",
-            "type": "integer"
+          "rule_name": {
+            "type": "string",
+            "description": "Silence rule name, 1–39 characters."
           },
           "description": {
-            "description": "Rule description.",
-            "type": "string"
-          },
-          "filters": {
-            "$ref": "#/components/schemas/FilterGroup",
-            "description": "Alert event match conditions; matching events are silenced within the time window."
+            "type": "string",
+            "description": "Rule description."
           },
           "from_incident_id": {
-            "description": "Incident the rule is attached to. Always present; the zero ObjectID `000000000000000000000000` means the rule was not created from an incident.",
+            "type": "string",
             "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
-          },
-          "is_auto_delete": {
-            "description": "When true, the silence rule is automatically deleted after its time window expires. Defaults to false.",
-            "type": "boolean"
+            "description": "Incident the rule is attached to. Always present; the zero ObjectID `000000000000000000000000` means the rule was not created from an incident."
           },
-          "is_directly_discard": {
-            "description": "When true, silenced alerts are dropped instead of suppressed into incidents.",
-            "type": "boolean"
+          "time_filters": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/TimeFilter"
+            },
+            "description": "Recurring silence windows. Empty when the rule uses a one-off `time_filter`."
           },
-          "is_effective": {
-            "description": "Whether the rule's time window covers the current moment, evaluated at response time.",
-            "type": "boolean"
+          "time_filter": {
+            "$ref": "#/components/schemas/OnceTimeFilter",
+            "description": "One-off silence window. Present with zero values when the rule uses recurring `time_filters` instead."
           },
-          "rule_id": {
-            "description": "Rule ID (MongoDB ObjectID).",
-            "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
+          "filters": {
+            "$ref": "#/components/schemas/FilterGroup",
+            "description": "Alert event conditions (OR of AND groups); matching events are silenced while the time window is active."
           },
-          "rule_name": {
-            "description": "Rule name.",
-            "type": "string"
+          "is_directly_discard": {
+            "type": "boolean",
+            "description": "When true, matching alert events are discarded entirely; when false, alerts are still recorded but marked as silenced by this rule."
           },
           "status": {
-            "description": "Rule status: `enabled` or `disabled`; deleted rules never appear in the list.",
+            "type": "string",
             "enum": [
               "enabled",
               "disabled"
             ],
-            "type": "string"
+            "description": "Rule status: `enabled` or `disabled`; deleted rules never appear in the list."
           },
-          "time_filter": {
-            "$ref": "#/components/schemas/OnceTimeFilter",
-            "description": "One-off silence window. Present with zero values when the rule uses recurring `time_filters` instead."
+          "rule_id": {
+            "type": "string",
+            "pattern": "^[0-9a-fA-F]{24}$",
+            "description": "Rule ID (MongoDB ObjectID)."
           },
-          "time_filters": {
-            "description": "Recurring silence windows. Empty when the rule uses a one-off `time_filter`.",
-            "items": {
-              "$ref": "#/components/schemas/TimeFilter"
-            },
-            "type": "array"
+          "updated_by": {
+            "type": "integer",
+            "format": "int64",
+            "description": "ID of the user who last updated the rule."
+          },
+          "created_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Creation time, Unix timestamp in seconds."
           },
           "updated_at": {
-            "description": "Last update time, Unix timestamp in seconds.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Last update time, Unix timestamp in seconds."
           },
-          "updated_by": {
-            "description": "ID of the user who last updated the rule.",
+          "is_effective": {
+            "type": "boolean",
+            "description": "Whether the rule's time window covers the current moment, evaluated at response time."
+          },
+          "is_auto_delete": {
+            "type": "boolean",
+            "description": "When true, the rule is permanently removed about 24 hours after its one-off window ends; rules with recurring windows are never removed. Returned only when `true`."
+          },
+          "deleted_at": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Deletion time, Unix timestamp in seconds. Omitted unless the rule is soft-deleted; deleted rules are excluded from list responses."
           }
-        },
-        "required": [
-          "account_id",
-          "channel_id",
-          "rule_name",
-          "description",
-          "time_filters",
-          "time_filter",
-          "filters",
-          "is_directly_discard",
-          "status",
-          "rule_id",
-          "updated_by",
-          "created_at",
-          "updated_at",
-          "is_effective"
-        ],
-        "type": "object"
+        }
       },
       "SkillDeleteRequest": {
         "description": "Skill deletion by ID.",
@@ -24450,125 +25432,151 @@
         "type": "object"
       },
       "SkillItem": {
+        "type": "object",
         "description": "An AI SRE skill — a packaged SKILL.md bundle the agent can load.",
         "properties": {
+          "skill_id": {
+            "type": "string",
+            "description": "Unique skill ID (prefix `skill_`)."
+          },
           "account_id": {
+            "type": "integer",
             "description": "Owning account ID.",
-            "format": "int64",
-            "type": "integer"
+            "format": "int64"
           },
-          "author": {
-            "description": "Skill author.",
-            "type": "string"
-          },
-          "can_edit": {
-            "description": "Whether the caller may edit this skill.",
-            "type": "boolean"
-          },
-          "checksum": {
-            "description": "SHA-256 checksum of the skill zip.",
-            "type": "string"
+          "team_id": {
+            "type": "integer",
+            "description": "Team scope: 0 = account-wide; >0 = the owning team.",
+            "format": "int64"
           },
-          "content": {
-            "description": "Full SKILL.md content. Omitted in list responses.",
-            "type": "string"
+          "skill_name": {
+            "type": "string",
+            "description": "Skill name, unique within its scope (account-wide or within one team)."
           },
-          "created": {
-            "description": "Set only on install-from-session responses: true = fresh install, false = in-place update.",
-            "type": "boolean"
+          "description": {
+            "type": "string",
+            "description": "Human-readable description from the SKILL.md frontmatter."
           },
-          "created_at": {
-            "description": "Creation time. Unix timestamp in milliseconds.",
-            "format": "int64",
-            "type": "integer"
+          "description_en": {
+            "type": "string",
+            "description": "Optional English description. English-locale UI responses prefer this over `description`; the skill catalog also uses it as a stable selection signal when `description` is localized for display."
           },
-          "created_by": {
-            "description": "Member ID that created the skill.",
-            "format": "int64",
-            "type": "integer"
+          "content": {
+            "type": "string",
+            "description": "Full SKILL.md content. Omitted in list responses."
           },
-          "description": {
-            "description": "Human-readable description from the SKILL.md frontmatter.",
-            "type": "string"
+          "version": {
+            "type": "string",
+            "description": "Skill version from the frontmatter."
           },
-          "description_en": {
-            "description": "Optional English description. English-locale UI responses prefer this over `description`; the skill catalog also uses it as a stable selection signal when `description` is localized for display.",
-            "type": "string"
+          "tags": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Tags parsed from the frontmatter."
           },
-          "is_modified": {
-            "description": "True when a marketplace-sourced skill was edited locally (auto-update skips it).",
-            "type": "boolean"
+          "author": {
+            "type": "string",
+            "description": "Skill author."
           },
           "license": {
-            "description": "Skill license.",
-            "type": "string"
-          },
-          "s3_key": {
-            "description": "Object-storage key of the skill zip.",
-            "type": "string"
+            "type": "string",
+            "description": "Skill license."
           },
-          "skill_id": {
-            "description": "Unique skill ID (prefix `skill_`).",
-            "type": "string"
+          "tools": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Required tools (builtin or `mcp:server/tool`)."
           },
-          "skill_name": {
-            "description": "Skill name, unique within its scope (account-wide or within one team).",
-            "type": "string"
+          "venues": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "enum": [
+                "cloud",
+                "byoc"
+              ]
+            },
+            "description": "Execution environments the skill is restricted to: `cloud` (managed sandbox) and/or `byoc` (self-hosted runner). Omitted when empty, which means every environment."
           },
-          "source_template_name": {
-            "description": "Marketplace template this skill was installed from; empty for user-authored.",
-            "type": "string"
+          "s3_key": {
+            "type": "string",
+            "description": "Object-storage key of the skill zip."
           },
-          "source_template_version": {
-            "description": "Template version at install time.",
-            "type": "string"
+          "checksum": {
+            "type": "string",
+            "description": "SHA-256 checksum of the skill zip."
           },
           "status": {
-            "description": "Skill status. Deleted skills are excluded from every API response, so only these two values are ever returned.",
+            "type": "string",
+            "description": "Skill status: `enabled` (agents load it) or `disabled` (kept but not loaded). Deleted skills never appear in responses.",
             "enum": [
               "enabled",
               "disabled"
-            ],
-            "type": "string"
+            ]
           },
-          "tags": {
-            "description": "Tags parsed from the frontmatter.",
-            "items": {
-              "type": "string"
-            },
-            "type": "array"
+          "created_by": {
+            "type": "integer",
+            "description": "Member ID that created the skill.",
+            "format": "int64"
           },
-          "team_id": {
-            "description": "Team scope: 0 = account-wide; >0 = the owning team.",
+          "created_at": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Creation time. Unix timestamp in milliseconds."
           },
-          "tools": {
-            "description": "Required tools (builtin or `mcp:server/tool`).",
-            "items": {
-              "type": "string"
-            },
-            "type": "array"
+          "updated_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Last update time. Unix timestamp in milliseconds."
+          },
+          "can_edit": {
+            "type": "boolean",
+            "description": "True when the caller may change this skill: account owners and admins for account-scope skills, team members for team skills."
+          },
+          "source_template_name": {
+            "type": "string",
+            "description": "Marketplace template this skill was installed from; empty for user-authored."
+          },
+          "source_template_version": {
+            "type": "string",
+            "description": "Template version at install time."
           },
           "update_available": {
-            "description": "True when the marketplace has a newer template version.",
-            "type": "boolean"
+            "type": "boolean",
+            "description": "True when the marketplace template this skill was installed from has a newer version. Computed by `POST /safari/skill/list` only; always false in other responses."
           },
-          "updated_at": {
-            "description": "Last update time. Unix timestamp in milliseconds.",
-            "format": "int64",
-            "type": "integer"
+          "is_modified": {
+            "type": "boolean",
+            "description": "True when a marketplace-installed skill was changed locally (for example by uploading a new archive); automatic marketplace updates skip it."
           },
-          "venues": {
-            "description": "Execution-environment kinds (EnvironmentKind strings, e.g. `byoc`) the skill is restricted to. Omitted when empty, which means the skill is available in all venues.",
-            "items": {
-              "type": "string"
-            },
-            "type": "array"
+          "created": {
+            "type": "boolean",
+            "description": "Not returned by these endpoints; it is set only by the install-from-session flow."
           },
-          "version": {
-            "description": "Skill version from the frontmatter.",
-            "type": "string"
+          "examples": {
+            "type": "array",
+            "description": "Example prompts declared in the SKILL.md frontmatter (up to 10), shown as suggested questions. Omitted when none.",
+            "items": {
+              "type": "object",
+              "properties": {
+                "zh": {
+                  "type": "string",
+                  "description": "Chinese prompt text."
+                },
+                "en": {
+                  "type": "string",
+                  "description": "English prompt text."
+                }
+              },
+              "required": [
+                "zh",
+                "en"
+              ]
+            }
           }
         },
         "required": [
@@ -24584,53 +25592,52 @@
           "can_edit",
           "update_available",
           "is_modified"
-        ],
-        "type": "object"
+        ]
       },
       "SkillListRequest": {
+        "type": "object",
         "description": "Pagination, search, and team filter for listing skills.",
         "properties": {
-          "include_account": {
-            "description": "Include account-scoped (team_id=0) rows. Defaults to true. Ignored when `scope` is `account` or `team`.",
-            "type": [
-              "boolean",
-              "null"
-            ]
-          },
-          "limit": {
-            "default": 20,
-            "description": "Page size.",
-            "type": "integer"
-          },
           "p": {
-            "default": 1,
-            "description": "Page number, 1-based.",
-            "type": "integer"
+            "type": "integer",
+            "description": "Page number, 1-based; values below 1 fall back to 1.",
+            "default": 1
           },
-          "query": {
-            "description": "Free-text search across skill name, description, English description, skill ID, marketplace source template name, and author.",
-            "maxLength": 128,
-            "type": "string"
+          "limit": {
+            "type": "integer",
+            "description": "Page size; values below 1 fall back to 20.",
+            "default": 20
           },
           "scope": {
-            "description": "Restrict results to `all` (default), `account`-only (team_id=0), or `team`-only (excludes account-scoped rows). Overrides `include_account` when set.",
+            "type": "string",
+            "description": "Which skills to return; overrides `include_account` when set:\n- `all` (default): account-scope skills (unless `include_account` is false) plus the caller's team skills\n- `account`: account-scope skills only (`team_id` = 0)\n- `team`: the caller's team skills only",
             "enum": [
               "all",
               "account",
               "team"
-            ],
-            "type": "string"
+            ]
+          },
+          "query": {
+            "type": "string",
+            "description": "Free-text search across skill name, description, English description, skill ID, marketplace source template name, and author.",
+            "maxLength": 128
           },
           "team_ids": {
-            "description": "Filter to these team IDs; empty = the caller's visible set.",
+            "type": "array",
             "items": {
-              "format": "int64",
-              "type": "integer"
+              "type": "integer",
+              "format": "int64"
             },
-            "type": "array"
+            "description": "Limit team-scope results to these team IDs; IDs of teams the caller does not belong to are dropped. Empty = all of the caller's teams."
+          },
+          "include_account": {
+            "type": [
+              "boolean",
+              "null"
+            ],
+            "description": "Include account-scoped (team_id=0) rows. Defaults to true. Ignored when `scope` is `account` or `team`."
           }
-        },
-        "type": "object"
+        }
       },
       "SkillListResponse": {
         "description": "Paginated skill list.",
@@ -24702,31 +25709,31 @@
         "type": "object"
       },
       "SkillUploadRequest": {
+        "type": "object",
         "description": "Multipart form for uploading a skill archive.",
         "properties": {
           "file": {
-            "description": "Skill archive (.skill / .zip / .tar.gz / .tgz). Max 100MB; oversized files are rejected before the body is read.",
+            "type": "string",
             "format": "binary",
-            "type": "string"
+            "description": "Skill archive (`.skill`, `.zip`, `.tar.gz`, or `.tgz`), up to 100 MB, containing `SKILL.md` at its root or inside a single top-level folder."
+          },
+          "team_id": {
+            "type": "integer",
+            "description": "Scope for the created or overwritten-by-name skill: 0 = account scope (default), >0 = that team. Ignored when `replace=true` and `skill_id` are both set.",
+            "format": "int64"
           },
           "replace": {
-            "description": "When true, overwrite an existing skill instead of failing on a name collision — matched by `skill_id` if provided, otherwise by skill name.",
-            "type": "boolean"
+            "type": "boolean",
+            "description": "When true, overwrite an existing skill instead of failing on a name clash: the skill given by `skill_id`, or else the same-named skill in `team_id`. Accepts `true`, `1`, `yes`, `on` (case-insensitive); anything else is false."
           },
           "skill_id": {
-            "description": "Existing skill ID to target when replacing a specific skill (requires `replace=true`).",
-            "type": "string"
-          },
-          "team_id": {
-            "description": "Team scope for the created/upserted skill: 0 = account-wide. Ignored when replacing a specific skill via `skill_id`.",
-            "format": "int64",
-            "type": "integer"
+            "type": "string",
+            "description": "ID of the skill to overwrite, from `POST /safari/skill/list`. Used only together with `replace=true`; ignored otherwise."
           }
         },
         "required": [
           "file"
-        ],
-        "type": "object"
+        ]
       },
       "SnoozeIncidentRequest": {
         "description": "Parameters for snoozing notifications on one or more incidents.",
@@ -24799,11 +25806,6 @@
             "type": "string"
           }
         },
-        "required": [
-          "uuid",
-          "name",
-          "is_system"
-        ],
         "type": "object"
       },
       "SourcemapCodeSnippet": {
@@ -24875,7 +25877,7 @@
             "type": "string"
           },
           "key": {
-            "description": "Storage key uniquely identifying this sourcemap file.",
+            "description": "Record identifier: a 32-character MD5 hex digest derived from the uploaded file's identity (storage path, or service/version/build identifiers for native symbols).",
             "type": "string"
           },
           "metadata": {
@@ -24936,7 +25938,7 @@
             "type": "boolean"
           },
           "build_id": {
-            "description": "Android only. Filter by Gradle plugin build identifier. Max 200 characters.",
+            "description": "Substring filter on the build ID (Android Gradle plugin build identifier, or the build ID of native symbols). Max 200 characters.",
             "maxLength": 200,
             "type": "string"
           },
@@ -25008,7 +26010,7 @@
             "type": "string"
           },
           "uuid": {
-            "description": "iOS only. Filter by dSYM bundle UUID. Max 200 characters.",
+            "description": "iOS only. Substring filter on the dSYM UUID; upper-cased and stripped of hyphens before matching. Max 200 characters.",
             "maxLength": 200,
             "type": "string"
           },
@@ -25050,7 +26052,7 @@
         "description": "Stack trace enrichment request.",
         "properties": {
           "arch": {
-            "description": "Android NDK architecture such as `arm`, `arm64`, `x86`, or `x64`.",
+            "description": "Native CPU architecture, such as `arm`, `arm64`, `x86` or `x64`. With `type: android` and an empty `source_type`, sending `arch` selects NDK native symbolication.",
             "type": "string"
           },
           "binary_images": {
@@ -25087,7 +26089,7 @@
             "type": "string"
           },
           "source_type": {
-            "description": "Android error source type. Use `ndk` with `arch` for native symbolication.",
+            "description": "The error's `error.source_type` as reported by the SDK. It reroutes symbolication: for `android`, a value containing `ndk` selects NDK native symbols; for `flutter` and `react-native`, `ios` selects dSYM and `android`/`ndk` selects Android symbols; for `electron`, `macos`, `windows` or `linux` selects Breakpad symbols. Ignored for other types.",
             "type": "string"
           },
           "stack": {
@@ -25205,68 +26207,42 @@
         "type": "object"
       },
       "StatusPageChangeItem": {
+        "type": "object",
         "description": "A status page event (incident or maintenance).",
+        "required": [
+          "change_id",
+          "type",
+          "title"
+        ],
         "properties": {
-          "affected_components": {
-            "description": "Components currently affected by this event, with their resulting status. Omitted when no components are affected.",
-            "items": {
-              "$ref": "#/components/schemas/AffectedStatusPageComponentItem"
-            },
-            "type": "array"
-          },
-          "auto_update_by_schedule": {
-            "description": "Maintenance only: whether the status advances automatically based on the scheduled window. Omitted when false.",
-            "type": "boolean"
-          },
           "change_id": {
-            "description": "Event ID.",
-            "format": "int64",
-            "type": "integer"
-          },
-          "close_at_seconds": {
-            "description": "Event close time in Unix seconds. For maintenances this is the scheduled end time; for closed events, the time the event reached its terminal status (`resolved`/`completed`). Omitted when not set.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
-          },
-          "description": {
-            "description": "Event description (Markdown). Omitted when empty.",
-            "type": "string"
-          },
-          "is_retrospective": {
-            "description": "Whether this event is a retrospective (historical) one. Omitted when false.",
-            "type": "boolean"
-          },
-          "linked_change_ids": {
-            "description": "Linked event IDs (related incidents, deployments, etc.). Omitted when empty.",
-            "items": {
-              "type": "string"
-            },
-            "type": "array"
-          },
-          "notify_subscribers": {
-            "description": "Whether subscribers were notified about this event. Omitted when false.",
-            "type": "boolean"
+            "description": "Event ID, returned by `POST /status-page/change/create`; pass it as `change_id` to the other event endpoints."
           },
           "page_id": {
-            "description": "Parent status page ID. Omitted when 0 (never for stored events).",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Parent status page ID. Omitted when 0 (never for stored events)."
           },
-          "responder_ids": {
-            "description": "Member IDs responsible for this event. Omitted when no responders are assigned.",
-            "items": {
-              "format": "int64",
-              "type": "integer"
-            },
-            "type": "array"
+          "type": {
+            "type": "string",
+            "enum": [
+              "incident",
+              "maintenance"
+            ],
+            "description": "Change type. `incident` is an unplanned outage; `maintenance` is a planned maintenance. The type determines which status values are valid."
           },
-          "start_at_seconds": {
-            "description": "Event start time in Unix seconds, derived from the first timeline update. Omitted when 0.",
-            "format": "int64",
-            "type": "integer"
+          "title": {
+            "type": "string",
+            "description": "Event title."
+          },
+          "description": {
+            "type": "string",
+            "description": "Event description (Markdown). Omitted when empty."
           },
           "status": {
-            "description": "Current event status. Incident statuses: `investigating`/`identified`/`monitoring`/`resolved`. Maintenance statuses: `scheduled`/`ongoing`/`completed`. Omitted when empty (never for stored events).",
+            "type": "string",
             "enum": [
               "investigating",
               "identified",
@@ -25276,34 +26252,60 @@
               "ongoing",
               "completed"
             ],
-            "type": "string"
+            "description": "Current event status. Incident statuses: `investigating`/`identified`/`monitoring`/`resolved`. Maintenance statuses: `scheduled`/`ongoing`/`completed`. Omitted when empty (never for stored events)."
           },
-          "title": {
-            "description": "Event title.",
-            "type": "string"
+          "affected_components": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/AffectedStatusPageComponentItem"
+            },
+            "description": "Components currently affected by this event, with their resulting status. Omitted when no components are affected."
           },
-          "type": {
-            "description": "Change type. `incident` is an unplanned outage; `maintenance` is a planned maintenance. The type determines which status values are valid.",
-            "enum": [
-              "incident",
-              "maintenance"
-            ],
-            "type": "string"
+          "responder_ids": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "int64"
+            },
+            "description": "Member IDs responsible for this event. Omitted when no responders are assigned."
+          },
+          "linked_change_ids": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Linked event IDs (related incidents, deployments, etc.). Omitted when empty."
+          },
+          "start_at_seconds": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Event start time in Unix seconds. For incidents it is the time of the first timeline entry; for maintenances it is the scheduled start given at creation, or the first entry's time when none was given. Omitted when 0."
+          },
+          "close_at_seconds": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Event close time in Unix seconds. For maintenances this is the scheduled end time; for closed events, the time the event reached its terminal status (`resolved`/`completed`). Omitted when not set."
+          },
+          "is_retrospective": {
+            "type": "boolean",
+            "description": "Whether this event is a retrospective (historical) one. Omitted when false."
           },
           "updates": {
-            "description": "Timeline updates attached to this event, ordered by time. Omitted when the event has no timeline updates.",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/StatusPageChangeUpdateItem"
             },
-            "type": "array"
+            "description": "Timeline updates attached to this event, ordered by time. Omitted when the event has no timeline updates."
+          },
+          "notify_subscribers": {
+            "type": "boolean",
+            "description": "Whether subscribers were notified about this event. Omitted when false."
+          },
+          "auto_update_by_schedule": {
+            "type": "boolean",
+            "description": "Maintenance only: whether the status advances automatically based on the scheduled window. Omitted when false."
           }
-        },
-        "required": [
-          "change_id",
-          "type",
-          "title"
-        ],
-        "type": "object"
+        }
       },
       "StatusPageChangeListResponse": {
         "description": "List of status page events.",
@@ -25335,26 +26337,24 @@
         "type": "object"
       },
       "StatusPageChangeUpdateItem": {
+        "type": "object",
         "description": "A single timeline update on a status page event.",
+        "required": [
+          "update_id",
+          "at_seconds"
+        ],
         "properties": {
+          "update_id": {
+            "type": "string",
+            "description": "Timeline entry ID (a ULID string), assigned by the server; pass it as `update_id` to edit or delete the entry."
+          },
           "at_seconds": {
-            "description": "Update timestamp in Unix seconds.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
-          },
-          "component_changes": {
-            "description": "Component status transitions applied by this update. Omitted when the update changes no component statuses.",
-            "items": {
-              "$ref": "#/components/schemas/StatusPageComponentChangeItem"
-            },
-            "type": "array"
-          },
-          "description": {
-            "description": "Update description (Markdown). Omitted when empty.",
-            "type": "string"
+            "description": "Update timestamp in Unix seconds."
           },
           "status": {
-            "description": "Change status after this update. Omitted when the update does not change the overall status. The first four values apply to incident-type changes, the last three to maintenance-type changes.\n| Value | Meaning |\n|---|---|\n| `investigating` | Investigating (incident). |\n| `identified` | Root cause identified (incident). |\n| `monitoring` | Fix deployed, monitoring (incident). |\n| `resolved` | Resolved (incident). |\n| `scheduled` | Scheduled (maintenance). |\n| `ongoing` | In progress (maintenance). |\n| `completed` | Completed (maintenance). |",
+            "type": "string",
             "enum": [
               "investigating",
               "identified",
@@ -25364,32 +26364,39 @@
               "ongoing",
               "completed"
             ],
-            "type": "string"
+            "description": "Change status after this update. Omitted when the update does not change the overall status. The first four values apply to incident-type changes, the last three to maintenance-type changes.\n| Value | Meaning |\n|---|---|\n| `investigating` | Investigating (incident). |\n| `identified` | Root cause identified (incident). |\n| `monitoring` | Fix deployed, monitoring (incident). |\n| `resolved` | Resolved (incident). |\n| `scheduled` | Scheduled (maintenance). |\n| `ongoing` | In progress (maintenance). |\n| `completed` | Completed (maintenance). |"
           },
-          "update_id": {
-            "description": "Update ID.",
-            "type": "string"
+          "description": {
+            "type": "string",
+            "description": "Update description (Markdown). Omitted when empty."
+          },
+          "component_changes": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/StatusPageComponentChangeItem"
+            },
+            "description": "Component status transitions applied by this update. Omitted when the update changes no component statuses."
           }
-        },
-        "required": [
-          "update_id",
-          "at_seconds"
-        ],
-        "type": "object"
+        }
       },
       "StatusPageComponentChangeItem": {
+        "type": "object",
         "description": "Component status transition applied in a timeline update.",
+        "required": [
+          "component_id",
+          "status"
+        ],
         "properties": {
           "component_id": {
-            "description": "Component ID.",
-            "type": "string"
+            "type": "string",
+            "description": "ID of the component whose status changes; matches `component_id` in `GET /status-page/info`."
           },
           "component_name": {
-            "description": "Component display name. Populated by the backend on read; ignored on write. Omitted when empty.",
-            "type": "string"
+            "type": "string",
+            "description": "Component display name. Populated by the backend on read; ignored on write. Omitted when empty."
           },
           "status": {
-            "description": "New component status. Incidents support `operational`/`degraded`/`partial_outage`/`full_outage`; maintenances support `operational`/`under_maintenance`.",
+            "type": "string",
             "enum": [
               "operational",
               "degraded",
@@ -25397,14 +26404,9 @@
               "full_outage",
               "under_maintenance"
             ],
-            "type": "string"
+            "description": "New component status. Incidents support `operational`/`degraded`/`partial_outage`/`full_outage`; maintenances support `operational`/`under_maintenance`."
           }
-        },
-        "required": [
-          "component_id",
-          "status"
-        ],
-        "type": "object"
+        }
       },
       "StatusPageComponentItem": {
         "description": "A status page component.",
@@ -25450,23 +26452,23 @@
         "type": "object"
       },
       "StatusPageDraftCreateResponse": {
+        "type": "object",
         "description": "Result of storing a status page draft.",
-        "properties": {
-          "created_at": {
-            "description": "Creation time in Unix epoch seconds.",
-            "format": "int64",
-            "type": "integer"
-          },
-          "draft_id": {
-            "description": "Draft ID matching `draft_[A-Za-z0-9]{22}`; the console review link carries it.",
-            "type": "string"
-          }
-        },
         "required": [
           "draft_id",
           "created_at"
         ],
-        "type": "object"
+        "properties": {
+          "draft_id": {
+            "type": "string",
+            "description": "Draft ID matching `draft_[A-Za-z0-9]{22}`; pass it as `draft_id` to `POST /status-page/change/create` or `POST /status-page/change/timeline/create` to publish."
+          },
+          "created_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Creation time in Unix epoch seconds."
+          }
+        }
       },
       "StatusPageInfoResponse": {
         "allOf": [
@@ -25490,108 +26492,123 @@
         "type": "object"
       },
       "StatusPageItem": {
+        "type": "object",
         "properties": {
-          "components": {
-            "description": "Components tracked on the status page.",
-            "items": {
-              "$ref": "#/components/schemas/StatusPageComponentItem"
-            },
-            "type": "array"
+          "page_id": {
+            "type": "integer",
+            "description": "Status page ID.",
+            "format": "int64"
           },
-          "contact_info": {
-            "description": "Get-in-touch contact, a mailto or website URL. Omitted when not set.",
-            "type": "string"
+          "name": {
+            "type": "string",
+            "description": "Display name of the status page."
+          },
+          "url_name": {
+            "type": "string",
+            "description": "URL-safe slug of the page, unique among the account's pages of the same type."
+          },
+          "type": {
+            "type": "string",
+            "description": "Page visibility type. `public` pages are accessible to anyone and use email subscriptions; `internal` pages are restricted to account members and use IM subscriptions.",
+            "enum": [
+              "public",
+              "internal"
+            ]
           },
           "custom_domain": {
-            "description": "Custom domain pointing to the status page. Omitted when not set.",
-            "type": "string"
+            "type": "string",
+            "description": "Custom domain pointing to the status page. Omitted when not set."
           },
-          "custom_links": {
-            "description": "Custom navigation links shown on the status page. Omitted when not set.",
-            "items": {
-              "additionalProperties": {
-                "type": "string"
-              },
-              "type": "object"
-            },
-            "type": "array"
+          "logo": {
+            "type": "string",
+            "description": "Logo image of the status page. Omitted when not set."
           },
           "dark_logo": {
-            "description": "Dark-mode logo image of the status page. Omitted when not set.",
-            "type": "string"
+            "type": "string",
+            "description": "Dark-mode logo image of the status page. Omitted when not set."
+          },
+          "logo_url": {
+            "type": "string",
+            "description": "URL opened when the logo is clicked. Omitted when not set."
+          },
+          "favicon": {
+            "type": "string",
+            "description": "Favicon of the status page. Omitted when not set."
+          },
+          "page_header": {
+            "type": "string",
+            "description": "Header content of the status page. Omitted when not set."
+          },
+          "page_footer": {
+            "type": "string",
+            "description": "Footer content of the status page. Omitted when not set."
           },
           "date_view": {
+            "type": "string",
             "description": "How the timeline displays change dates. `calendar` uses a calendar view; `list` uses a list view. Omitted when not set.",
             "enum": [
               "calendar",
               "list"
-            ],
-            "type": "string"
+            ]
           },
           "display_uptime_mode": {
+            "type": "string",
             "description": "How uptime is displayed. `chart_and_percentage` shows both the uptime chart and the percentage figure; `chart` shows only the chart; `none` hides uptime entirely. Omitted when not set.",
             "enum": [
               "chart_and_percentage",
               "chart",
               "none"
-            ],
-            "type": "string"
-          },
-          "favicon": {
-            "description": "Favicon of the status page. Omitted when not set.",
-            "type": "string"
-          },
-          "logo": {
-            "description": "Logo image of the status page. Omitted when not set.",
-            "type": "string"
-          },
-          "logo_url": {
-            "description": "URL opened when the logo is clicked. Omitted when not set.",
-            "type": "string"
-          },
-          "name": {
-            "description": "Display name of the status page.",
-            "type": "string"
+            ]
           },
-          "page_footer": {
-            "description": "Footer content of the status page. Omitted when not set.",
-            "type": "string"
+          "custom_links": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "key": {
+                  "type": "string",
+                  "description": "Link text shown on the page."
+                },
+                "value": {
+                  "type": "string",
+                  "description": "URL the link text points to, such as `https://www.example.com`."
+                }
+              },
+              "additionalProperties": {
+                "type": "string"
+              }
+            },
+            "description": "Custom navigation links shown on the status page. Omitted when not set."
           },
-          "page_header": {
-            "description": "Header content of the status page. Omitted when not set.",
-            "type": "string"
+          "contact_info": {
+            "type": "string",
+            "description": "Get-in-touch contact, a mailto or website URL. Omitted when not set."
           },
-          "page_id": {
-            "description": "Status page ID.",
-            "format": "int64",
-            "type": "integer"
+          "components": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/StatusPageComponentItem"
+            },
+            "description": "Components tracked on the status page."
           },
           "sections": {
-            "description": "Sections grouping the components.",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/StatusPageSectionItem"
             },
-            "type": "array"
+            "description": "Sections grouping the components."
           },
           "subscription": {
             "$ref": "#/components/schemas/StatusPageSubscriptionItem",
             "description": "Subscription channel toggles."
           },
           "template_preference": {
-            "description": "Preferred event template type: `pre_defined` or `message`. Omitted when never set.",
-            "type": "string"
-          },
-          "type": {
-            "description": "Page visibility type. `public` pages are accessible to anyone and use email subscriptions; `internal` pages are restricted to account members and use IM subscriptions.",
+            "type": "string",
+            "description": "Event template mode used when publishing events in the console: `message` (status descriptions: per-status texts) or `pre_defined` (full status updates: complete examples with title, status, and description). Omitted when never set; the console then uses `message`.",
             "enum": [
-              "public",
-              "internal"
-            ],
-            "type": "string"
-          },
-          "url_name": {
-            "description": "URL-safe slug, unique per account.",
-            "type": "string"
+              "pre_defined",
+              "message"
+            ]
           }
         },
         "required": [
@@ -25602,8 +26619,7 @@
           "components",
           "sections",
           "subscription"
-        ],
-        "type": "object"
+        ]
       },
       "StatusPageMessageTemplate": {
         "description": "A message template: per-status notification texts for one change type. In `POST /status-page/template/upsert`, omit `template_id` to create and supply it to update; on update only non-empty fields are applied.",
@@ -25635,136 +26651,136 @@
         "type": "object"
       },
       "StatusPageMigrationJob": {
+        "type": "object",
         "description": "A migration job's current state and progress.",
+        "required": [
+          "job_id",
+          "account_id",
+          "source_page_id",
+          "target_page_id",
+          "phase",
+          "status",
+          "progress",
+          "created_at",
+          "updated_at"
+        ],
         "properties": {
-          "account_id": {
-            "description": "Owner account ID.",
-            "format": "int64",
-            "type": "integer"
+          "job_id": {
+            "type": "string",
+            "description": "Migration job ID."
           },
-          "created_at": {
-            "description": "Job creation time as a Unix timestamp in seconds.",
+          "account_id": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Owner account ID."
           },
-          "error": {
-            "description": "Terminal error message when `status` is `failed`. Omitted when the job has not failed.",
-            "type": "string"
+          "source_page_id": {
+            "type": "string",
+            "description": "Atlassian Statuspage source page ID."
           },
-          "job_id": {
-            "description": "Migration job ID.",
-            "type": "string"
+          "target_page_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Flashduty target status page ID. For a structure migration it is 0 until the page is created or reused; for a subscriber migration it is the `target_page_id` from the request."
           },
           "phase": {
-            "description": "Current migration phase. `structure` imports the page structure (sections and components); `history` imports historical incidents, maintenances, and incident templates; `subscribers` imports email subscribers.",
+            "type": "string",
             "enum": [
               "structure",
               "history",
               "subscribers"
             ],
-            "type": "string"
-          },
-          "progress": {
-            "$ref": "#/components/schemas/StatusPageMigrationProgress",
-            "description": "Per-entity progress counters."
-          },
-          "source_page_id": {
-            "description": "Atlassian Statuspage source page ID.",
-            "type": "string"
+            "description": "Current migration phase. `structure` imports the page structure (sections and components); `history` imports historical incidents, maintenances, and incident templates; `subscribers` imports email subscribers."
           },
           "status": {
-            "description": "Current job status.\n| Value | Meaning |\n|---|---|\n| `running` | In progress. |\n| `completed` | Finished successfully. |\n| `failed` | Failed; the `error` field holds the reason. |\n| `cancelled` | Canceled by request. |",
+            "type": "string",
             "enum": [
               "running",
               "completed",
               "failed",
               "cancelled"
             ],
-            "type": "string"
+            "description": "Current job status.\n| Value | Meaning |\n|---|---|\n| `running` | In progress. |\n| `completed` | Finished successfully. |\n| `failed` | Failed; the `error` field holds the reason. |\n| `cancelled` | Canceled by request. |"
           },
-          "target_page_id": {
-            "description": "Flashduty target status page ID. Set once the job produces one, or supplied up front for subscriber migration.",
+          "progress": {
+            "$ref": "#/components/schemas/StatusPageMigrationProgress",
+            "description": "Per-entity progress counters."
+          },
+          "error": {
+            "type": "string",
+            "description": "Terminal error message when `status` is `failed`. Omitted when the job has not failed."
+          },
+          "created_at": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Job creation time as a Unix timestamp in seconds."
           },
           "updated_at": {
-            "description": "Last status update time as a Unix timestamp in seconds.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Last status update time as a Unix timestamp in seconds."
           }
-        },
-        "required": [
-          "job_id",
-          "account_id",
-          "source_page_id",
-          "target_page_id",
-          "phase",
-          "status",
-          "progress",
-          "created_at",
-          "updated_at"
-        ],
-        "type": "object"
+        }
       },
       "StatusPageMigrationProgress": {
+        "type": "object",
         "description": "Progress counters for a migration job.",
+        "required": [
+          "total_steps",
+          "completed_steps",
+          "components_imported",
+          "sections_imported",
+          "incidents_imported",
+          "maintenances_imported",
+          "subscribers_imported",
+          "templates_imported",
+          "subscribers_skipped"
+        ],
         "properties": {
+          "total_steps": {
+            "type": "integer",
+            "description": "Total steps of the job: 5 for a structure migration (page, sections, components, incidents and maintenances, templates) and 1 for a subscriber migration."
+          },
           "completed_steps": {
-            "description": "Steps completed so far.",
-            "type": "integer"
+            "type": "integer",
+            "description": "Steps completed so far."
           },
           "components_imported": {
-            "description": "Number of components imported from the source status page.",
-            "type": "integer"
+            "type": "integer",
+            "description": "Number of components imported from the source status page."
+          },
+          "sections_imported": {
+            "type": "integer",
+            "description": "Number of sections (Atlassian component groups) imported from the source status page."
           },
           "incidents_imported": {
-            "description": "Number of historical incidents imported.",
-            "type": "integer"
+            "type": "integer",
+            "description": "Number of historical incidents imported."
           },
           "maintenances_imported": {
-            "description": "Number of scheduled maintenances imported.",
-            "type": "integer"
-          },
-          "sections_imported": {
-            "description": "Number of sections (Atlassian component groups) imported from the source status page.",
-            "type": "integer"
+            "type": "integer",
+            "description": "Number of scheduled maintenances imported."
           },
           "subscribers_imported": {
-            "description": "Number of email subscribers successfully imported.",
-            "type": "integer"
-          },
-          "subscribers_skipped": {
-            "description": "Number of subscribers skipped (e.g. because they would create duplicates).",
-            "type": "integer"
+            "type": "integer",
+            "description": "Number of email subscribers successfully imported."
           },
           "templates_imported": {
-            "description": "Number of incident templates successfully imported; templates that fail are skipped and recorded in `warnings`.",
-            "type": "integer"
+            "type": "integer",
+            "description": "Number of incident templates successfully imported; templates that fail are skipped and recorded in `warnings`."
           },
-          "total_steps": {
-            "description": "Total steps this job will perform.",
-            "type": "integer"
+          "subscribers_skipped": {
+            "type": "integer",
+            "description": "Number of source subscribers skipped because they are not email subscribers, have no email address, or are quarantined. Recipients already subscribed on the target page are not counted here."
           },
           "warnings": {
-            "description": "Non-fatal warnings recorded during the job. Omitted when empty.",
+            "type": "array",
             "items": {
               "type": "string"
             },
-            "type": "array"
+            "description": "Non-fatal warnings recorded during the job. Omitted when empty."
           }
-        },
-        "required": [
-          "total_steps",
-          "completed_steps",
-          "components_imported",
-          "sections_imported",
-          "incidents_imported",
-          "maintenances_imported",
-          "subscribers_imported",
-          "templates_imported",
-          "subscribers_skipped"
-        ],
-        "type": "object"
+        }
       },
       "StatusPageMigrationStartResponse": {
         "description": "Result of starting a migration job.",
@@ -25780,14 +26796,27 @@
         "type": "object"
       },
       "StatusPagePreDefinedTemplate": {
+        "type": "object",
         "description": "A predefined event template: a reusable draft of an event's title, type, status, and description. In `POST /status-page/template/upsert`, omit `template_id` to create and supply it to update; on update only non-empty fields are applied.",
         "properties": {
-          "description": {
-            "description": "Template body text (Markdown).",
-            "type": "string"
+          "template_id": {
+            "type": "string",
+            "description": "Template ID. Omit to create a new template; supply to update an existing one."
+          },
+          "title": {
+            "type": "string",
+            "description": "Template title."
+          },
+          "type": {
+            "type": "string",
+            "enum": [
+              "incident",
+              "maintenance"
+            ],
+            "description": "Change type the template applies to: `incident` unplanned incident, `maintenance` planned maintenance. Set on create; ignored on update."
           },
           "status": {
-            "description": "Change status the template maps to. Incidents use `investigating`/`identified`/`monitoring`/`resolved`; maintenances use `scheduled`/`ongoing`/`completed`.",
+            "type": "string",
             "enum": [
               "investigating",
               "identified",
@@ -25797,26 +26826,13 @@
               "ongoing",
               "completed"
             ],
-            "type": "string"
-          },
-          "template_id": {
-            "description": "Template ID. Omit to create a new template; supply to update an existing one.",
-            "type": "string"
-          },
-          "title": {
-            "description": "Template title.",
-            "type": "string"
+            "description": "Change status the template maps to. Incidents use `investigating`/`identified`/`monitoring`/`resolved`; maintenances use `scheduled`/`ongoing`/`completed`."
           },
-          "type": {
-            "description": "Change type the template applies to: `incident` unplanned incident, `maintenance` planned maintenance.",
-            "enum": [
-              "incident",
-              "maintenance"
-            ],
-            "type": "string"
+          "description": {
+            "type": "string",
+            "description": "Template body text (Markdown)."
           }
-        },
-        "type": "object"
+        }
       },
       "StatusPageSectionItem": {
         "properties": {
@@ -25904,70 +26920,69 @@
         "type": "object"
       },
       "StringMapPatch": {
-        "description": "Partial update for a map field: keys in `set` are inserted or replaced, keys in `delete` are removed, all other keys are preserved.",
+        "type": "object",
+        "description": "Partial update for a map field: keys in `set` are inserted or replaced, keys in `delete` are removed, all other keys are preserved. At least one of `set` / `delete` must be non-empty, keys must not be blank, and a key may not appear in both or twice in `delete`.",
         "properties": {
-          "delete": {
-            "description": "Keys to remove.",
-            "items": {
+          "set": {
+            "type": "object",
+            "additionalProperties": {
               "type": "string"
             },
-            "type": "array"
+            "description": "Keys to insert or replace."
           },
-          "set": {
-            "additionalProperties": {
+          "delete": {
+            "type": "array",
+            "items": {
               "type": "string"
             },
-            "description": "Keys to insert or replace.",
-            "type": "object"
+            "description": "Keys to remove."
           }
-        },
-        "type": "object"
+        }
       },
       "SuccessEnvelope": {
+        "type": "object",
         "description": "Success response envelope. On every 2xx response, `request_id` identifies the call (also mirrored in the `Flashcat-Request-Id` header) and `data` holds the endpoint-specific payload. Failure responses use a different shape — see `ErrorResponse`.",
         "properties": {
-          "data": {
-            "description": "Endpoint-specific payload. See each operation's 200 response schema."
-          },
           "request_id": {
+            "type": "string",
             "description": "Unique ID for this request. Mirrored in the Flashcat-Request-Id response header. Include it when reporting issues.",
-            "example": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
-            "type": "string"
+            "example": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
+          },
+          "data": {
+            "description": "Operation-specific payload, documented in each operation's 200 response. Operations without a payload return `{}` or omit `data` entirely."
           }
         },
         "required": [
-          "request_id",
-          "data"
-        ],
-        "type": "object"
+          "request_id"
+        ]
       },
       "TeamBriefItem": {
+        "type": "object",
         "description": "Brief team info for batch responses.",
         "properties": {
-          "person_ids": {
-            "description": "Array of person IDs belonging to the team; empty array (never null) when the team has no members.",
-            "items": {
-              "format": "uint64",
-              "type": "integer"
-            },
-            "type": "array"
-          },
           "team_id": {
-            "description": "Team ID.",
+            "type": "integer",
             "format": "uint64",
-            "type": "integer"
+            "description": "Team ID, one of the requested `team_ids`."
           },
           "team_name": {
-            "description": "Team name.",
-            "type": "string"
-          }
+            "type": "string",
+            "description": "Team name. Deleted teams are included, so this can be the name of a team that no longer appears in `POST /team/list`."
+          },
+          "person_ids": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "uint64"
+            },
+            "description": "Array of person IDs belonging to the team; empty array (never null) when the team has no members."
+          }
         },
         "required": [
           "team_id",
           "team_name",
           "person_ids"
-        ],
-        "type": "object"
+        ]
       },
       "TeamDeleteRequest": {
         "anyOf": [
@@ -26059,107 +27074,110 @@
         "type": "object"
       },
       "TeamInfosResponse": {
+        "type": "object",
         "description": "Batch team info result.",
+        "required": [
+          "items"
+        ],
         "properties": {
           "items": {
-            "description": "Array of brief team info for the matched `team_ids`; may be null when no ID matches.",
+            "type": [
+              "array",
+              "null"
+            ],
             "items": {
               "$ref": "#/components/schemas/TeamBriefItem"
             },
-            "type": "array"
+            "description": "Brief info for the matched teams, including deleted ones; `null` when no ID matches."
           }
-        },
-        "required": [
-          "items"
-        ],
-        "type": "object"
+        }
       },
       "TeamItem": {
+        "type": "object",
         "description": "A team and its membership.",
+        "required": [
+          "account_id",
+          "team_id",
+          "team_name",
+          "description",
+          "status",
+          "updated_by_name",
+          "updated_by",
+          "creator_id",
+          "creator_name",
+          "created_at",
+          "updated_at",
+          "person_ids",
+          "ref_id"
+        ],
         "properties": {
           "account_id": {
-            "description": "Owning account ID.",
+            "type": "integer",
             "format": "uint64",
-            "type": "integer"
-          },
-          "created_at": {
-            "description": "Unix epoch seconds the team was created.",
-            "format": "int64",
-            "type": "integer"
+            "description": "Owning account ID."
           },
-          "creator_id": {
-            "description": "Member ID of the creator.",
+          "team_id": {
+            "type": "integer",
             "format": "uint64",
-            "type": "integer"
+            "description": "Unique team ID."
           },
-          "creator_name": {
-            "description": "Display name of the creator. Not populated by current endpoints — always an empty string; resolve `creator_id` via `POST /person/infos`.",
-            "type": "string"
+          "team_name": {
+            "type": "string",
+            "description": "Team display name. 1–39 characters, unique per account."
           },
           "description": {
-            "description": "Free-form description.",
-            "type": "string"
-          },
-          "person_ids": {
-            "description": "Member IDs of team members.",
-            "items": {
-              "format": "uint64",
-              "type": "integer"
-            },
-            "type": "array"
-          },
-          "ref_id": {
-            "description": "External reference ID for third-party HR system integration.",
-            "type": "string"
+            "type": "string",
+            "description": "Free-form description."
           },
           "status": {
-            "description": "Team status. `enabled` — active; `deleted` — soft-deleted (only possible when fetching a deleted team by `team_id`; list and name/ref_id lookups exclude deleted teams).",
+            "type": "string",
             "enum": [
               "enabled",
               "deleted"
             ],
-            "type": "string"
+            "description": "Team status. `enabled` — active; `deleted` — soft-deleted (only possible when fetching a deleted team by `team_id`; list and name/ref_id lookups exclude deleted teams)."
           },
-          "team_id": {
-            "description": "Unique team ID.",
+          "updated_by_name": {
+            "type": "string",
+            "description": "Name of the last editor: the member's name, or the account name when the account owner made the change; empty string when unknown."
+          },
+          "updated_by": {
+            "type": "integer",
             "format": "uint64",
-            "type": "integer"
+            "description": "Member ID of the last editor."
           },
-          "team_name": {
-            "description": "Team display name. 1–39 characters, unique per account.",
-            "type": "string"
+          "creator_id": {
+            "type": "integer",
+            "format": "uint64",
+            "description": "Member ID of the creator."
+          },
+          "creator_name": {
+            "type": "string",
+            "description": "Display name of the creator. Not populated by current endpoints — always an empty string; resolve `creator_id` via `POST /person/infos`."
+          },
+          "created_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Unix epoch seconds the team was created."
           },
           "updated_at": {
-            "description": "Unix epoch seconds the team was last updated.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Unix epoch seconds the team was last updated."
           },
-          "updated_by": {
-            "description": "Member ID of the last editor.",
-            "format": "uint64",
-            "type": "integer"
+          "person_ids": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "uint64"
+            },
+            "description": "Person IDs of the team's members (member IDs; the account owner's ID when the owner is in the team). Empty array when the team has no members."
           },
-          "updated_by_name": {
-            "description": "Display name of the last editor.",
-            "type": "string"
+          "ref_id": {
+            "type": "string",
+            "description": "External reference ID for third-party HR system integration."
           }
-        },
-        "required": [
-          "account_id",
-          "team_id",
-          "team_name",
-          "description",
-          "status",
-          "updated_by_name",
-          "updated_by",
-          "creator_id",
-          "creator_name",
-          "created_at",
-          "updated_at",
-          "person_ids",
-          "ref_id"
-        ],
-        "type": "object"
+        }
       },
       "TeamListRequest": {
         "description": "Filters for listing teams.",
@@ -26203,95 +27221,95 @@
         "type": "object"
       },
       "TeamListResponse": {
+        "type": "object",
         "description": "Paginated team list.",
-        "properties": {
-          "items": {
-            "description": "Array of teams for the current page, used with `p`, `limit` and `total` for pagination; empty array on an empty page.",
-            "items": {
-              "$ref": "#/components/schemas/TeamItem"
-            },
-            "type": "array"
-          },
-          "limit": {
-            "description": "Page size used.",
-            "type": "integer"
-          },
-          "p": {
-            "description": "Current page number.",
-            "type": "integer"
-          },
-          "total": {
-            "description": "Total number of teams matching the filter.",
-            "type": "integer"
-          }
-        },
         "required": [
           "p",
           "limit",
           "total",
           "items"
         ],
-        "type": "object"
+        "properties": {
+          "p": {
+            "type": "integer",
+            "description": "Page number from the request; `0` when `p` was omitted (the first page is returned)."
+          },
+          "limit": {
+            "type": "integer",
+            "description": "Page size applied; 20 when `limit` was omitted."
+          },
+          "total": {
+            "type": "integer",
+            "description": "Number of non-deleted teams matching the filters, across all pages."
+          },
+          "items": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/TeamItem"
+            },
+            "description": "Array of teams for the current page, used with `p`, `limit` and `total` for pagination; empty array on an empty page."
+          }
+        }
       },
       "TeamUpsertRequest": {
+        "type": "object",
+        "required": [
+          "team_name"
+        ],
         "description": "Parameters for creating or updating a team.",
         "properties": {
-          "countryCode": {
-            "description": "Default country code applied to any `phones` entries that are not in E.164 format.",
-            "type": "string"
+          "team_id": {
+            "type": "integer",
+            "format": "uint64",
+            "description": "ID of the team to update. Omit or set to 0 to create a new team; a non-zero ID must belong to an existing team of the account."
+          },
+          "team_name": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 39,
+            "description": "Team display name. 1–39 characters."
           },
           "description": {
-            "description": "Free-form description.",
+            "type": "string",
             "maxLength": 500,
-            "type": "string"
+            "description": "Free-form description, up to 500 characters. On update, omitting it clears the stored description."
           },
-          "emails": {
-            "description": "Add existing members to the team by email. Addresses that don't match an existing member are silently ignored — no invitation is sent.",
+          "person_ids": {
+            "type": "array",
             "items": {
-              "format": "email",
-              "type": "string"
+              "type": "integer",
+              "format": "uint64"
             },
-            "type": "array"
+            "description": "Person IDs to place in the team (member IDs, or the account ID for the account owner). Together with `emails` and `phones` they replace the entire member list; IDs that are not members of the account are ignored."
           },
-          "person_ids": {
-            "description": "Member IDs to set as team members. Replaces the existing member list.",
+          "emails": {
+            "type": "array",
             "items": {
-              "format": "uint64",
-              "type": "integer"
+              "type": "string",
+              "format": "email"
             },
-            "type": "array"
+            "description": "Emails of existing members to place in the team; merged with `person_ids` and `phones`. Addresses that match no member are ignored and no invitation is sent."
           },
           "phones": {
-            "description": "Add existing members to the team by phone number. Numbers not in E.164 format are parsed with `countryCode`; an unparseable number fails the whole request with a 400. Numbers that parse but match no existing member are silently ignored.",
+            "type": "array",
             "items": {
               "type": "string"
             },
-            "type": "array"
+            "description": "Phone numbers of existing members to place in the team; merged with `person_ids` and `emails`. Numbers without a `+` prefix are parsed with `countryCode`; an unparseable number fails the whole request with `400`, and numbers that match no member are ignored."
+          },
+          "countryCode": {
+            "type": "string",
+            "description": "Region hint for `phones` entries without a `+` prefix: an ISO 3166-1 alpha-2 code such as `CN` (the default when omitted) or a digit calling code such as `86`."
           },
           "ref_id": {
-            "description": "External reference ID for HR system integration.",
-            "type": "string"
+            "type": "string",
+            "description": "External reference ID (for example a department ID in an HR system), usable as a lookup key in `POST /team/info` and `POST /team/delete`. On update, omitting it clears the stored value."
           },
           "reset_if_name_exist": {
-            "description": "When true and `team_id` is 0, an existing team with the same `team_name` is updated in place instead of returning a name-conflict error.",
-            "type": "boolean"
-          },
-          "team_id": {
-            "description": "Team ID. Omit or set to 0 to create a new team.",
-            "format": "uint64",
-            "type": "integer"
-          },
-          "team_name": {
-            "description": "Team display name. 1–39 characters.",
-            "maxLength": 39,
-            "minLength": 1,
-            "type": "string"
+            "type": "boolean",
+            "description": "When true and `team_id` is 0, an existing team with the same `team_name` is updated in place instead of returning a name-conflict error."
           }
-        },
-        "required": [
-          "team_name"
-        ],
-        "type": "object"
+        }
       },
       "TeamUpsertResponse": {
         "description": "Team create/update result.",
@@ -26313,50 +27331,111 @@
         "type": "object"
       },
       "TemplateCreateRequest": {
+        "type": "object",
         "description": "Create a new notification template.",
+        "required": [
+          "template_name"
+        ],
         "properties": {
+          "team_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Owning team ID from `POST /team/list`; `0` (default) means account-wide. A non-zero ID must be an existing team.",
+            "default": 0
+          },
+          "template_name": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 39,
+            "description": "Template name, 1–39 characters, unique among the account's non-deleted templates and different from the built-in preset template's name in every supported language.",
+            "example": "Prod incident default"
+          },
           "description": {
-            "description": "Free-form description. Up to 500 characters.",
+            "type": "string",
             "maxLength": 500,
-            "type": "string"
+            "description": "Free-form description. Up to 500 characters."
+          },
+          "email": {
+            "type": "string",
+            "description": "Email body template source (Go `html/template` syntax)."
+          },
+          "sms": {
+            "type": "string",
+            "description": "SMS template source (Go `text/template` syntax)."
+          },
+          "voice": {
+            "type": "string",
+            "description": "Voice call script template source."
           },
           "dingtalk": {
-            "description": "DingTalk robot message template source.",
-            "type": "string"
+            "type": "string",
+            "description": "DingTalk robot message template source."
           },
-          "dingtalk_app": {
-            "description": "DingTalk app message template source.",
-            "type": "string"
+          "wecom": {
+            "type": "string",
+            "description": "WeCom robot message template source."
           },
-          "dingtalk_app_war_room_enabled": {
+          "wecom_markdown_v2_enabled": {
             "type": "boolean",
-            "description": "Show the Create War Room button on DingTalk app cards."
-          },
-          "email": {
-            "description": "Email body template source (Go `html/template` syntax).",
-            "type": "string"
+            "description": "Send WeCom robot notifications as `markdown_v2` messages instead of plain markdown. While enabled, the rendered `wecom` content must be at most 4,096 bytes."
           },
           "feishu": {
-            "description": "Feishu robot message template source.",
-            "type": "string"
+            "type": "string",
+            "description": "Feishu robot message template source."
           },
           "feishu_app": {
-            "description": "Feishu app message template source.",
-            "type": "string"
+            "type": "string",
+            "description": "Feishu app message template source."
+          },
+          "feishu_app_card_v2_table_enabled": {
+            "type": "boolean",
+            "default": false,
+            "description": "Render Markdown tables in the `feishu_app` content as native Feishu card tables."
           },
           "feishu_app_card_v2_preserve_blank_lines": {
             "type": "boolean",
             "description": "Keep blank lines in the body of Feishu app card v2 messages."
           },
-          "feishu_app_card_v2_table_enabled": {
-            "default": false,
-            "description": "Render alert labels as a table in Feishu app cards.",
-            "type": "boolean"
-          },
           "feishu_app_war_room_enabled": {
             "type": "boolean",
             "description": "Show the Create War Room button on Feishu app cards."
           },
+          "dingtalk_app_war_room_enabled": {
+            "type": "boolean",
+            "description": "Show the Create War Room button on DingTalk app cards."
+          },
+          "slack_app_war_room_enabled": {
+            "type": "boolean",
+            "description": "Show the Create War Room button on Slack app cards."
+          },
+          "dingtalk_app": {
+            "type": "string",
+            "description": "DingTalk app message template source."
+          },
+          "wecom_app": {
+            "type": "string",
+            "description": "WeCom app message template source."
+          },
+          "slack_app": {
+            "type": "string",
+            "description": "Slack app message template source."
+          },
+          "teams_app": {
+            "type": "string",
+            "description": "Microsoft Teams app message template source."
+          },
+          "telegram": {
+            "type": "string",
+            "description": "Telegram bot message template source."
+          },
+          "slack": {
+            "type": "string",
+            "description": "Slack robot message template source."
+          },
+          "zoom": {
+            "type": "string",
+            "description": "Zoom bot message template source."
+          },
           "incident_card_closed_action_apps": {
             "type": "array",
             "items": {
@@ -26373,70 +27452,9 @@
           },
           "incident_card_hidden_fields": {
             "$ref": "#/components/schemas/IncidentCardHiddenFields",
-            "description": "Incident card fields hidden per IM app type."
-          },
-          "slack": {
-            "description": "Slack robot message template source.",
-            "type": "string"
-          },
-          "slack_app": {
-            "description": "Slack app message template source.",
-            "type": "string"
-          },
-          "slack_app_war_room_enabled": {
-            "type": "boolean",
-            "description": "Show the Create War Room button on Slack app cards."
-          },
-          "sms": {
-            "description": "SMS template source (Go `text/template` syntax).",
-            "type": "string"
-          },
-          "team_id": {
-            "default": 0,
-            "description": "Team scope. 0 for account-wide.",
-            "format": "int64",
-            "type": "integer"
-          },
-          "teams_app": {
-            "description": "Microsoft Teams app message template source.",
-            "type": "string"
-          },
-          "telegram": {
-            "description": "Telegram bot message template source.",
-            "type": "string"
-          },
-          "template_name": {
-            "description": "Template name, unique per account. 1–39 characters.",
-            "example": "Prod incident default",
-            "maxLength": 39,
-            "minLength": 1,
-            "type": "string"
-          },
-          "voice": {
-            "description": "Voice call script template source.",
-            "type": "string"
-          },
-          "wecom": {
-            "description": "WeCom robot message template source.",
-            "type": "string"
-          },
-          "wecom_app": {
-            "description": "WeCom app message template source.",
-            "type": "string"
-          },
-          "wecom_markdown_v2_enabled": {
-            "type": "boolean",
-            "description": "Send WeCom robot notifications as `markdown_v2` messages instead of plain markdown."
-          },
-          "zoom": {
-            "description": "Zoom bot message template source.",
-            "type": "string"
+            "description": "Incident card fields to hide per IM app type."
           }
-        },
-        "required": [
-          "template_name"
-        ],
-        "type": "object"
+        }
       },
       "TemplateCreateResponse": {
         "description": "Create template response.",
@@ -26475,70 +27493,152 @@
         "type": "object"
       },
       "TemplateItem": {
+        "type": "object",
         "description": "A notification template. Each channel field holds the template source string for that delivery channel; an empty string means 'no custom template for that channel'.",
+        "required": [
+          "account_id",
+          "team_id",
+          "template_id",
+          "template_name",
+          "description",
+          "email",
+          "sms",
+          "voice",
+          "dingtalk",
+          "wecom",
+          "feishu",
+          "feishu_app",
+          "feishu_app_card_v2_table_enabled",
+          "wecom_markdown_v2_enabled",
+          "feishu_app_card_v2_preserve_blank_lines",
+          "feishu_app_war_room_enabled",
+          "dingtalk_app_war_room_enabled",
+          "slack_app_war_room_enabled",
+          "dingtalk_app",
+          "wecom_app",
+          "slack_app",
+          "teams_app",
+          "telegram",
+          "slack",
+          "zoom",
+          "status",
+          "creator_id",
+          "updated_by",
+          "created_at",
+          "updated_at",
+          "incident_card_closed_action_apps",
+          "incident_card_hidden_fields"
+        ],
         "properties": {
           "account_id": {
-            "description": "ID of the owning account.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "ID of the owning account."
           },
-          "created_at": {
-            "description": "Unix epoch seconds the template was created.",
+          "team_id": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "ID of the team this template is scoped to, or 0 for account-wide."
           },
-          "creator_id": {
-            "description": "Member ID of the creator.",
-            "format": "int64",
-            "type": "integer"
+          "template_id": {
+            "type": "string",
+            "pattern": "^[0-9a-fA-F]{24}$",
+            "description": "Template ID (24-character hex). The built-in preset template always has the ID `6321aad26c12104586a88916`.",
+            "example": "6605a1b2c3d4e5f6a7b8c9d0"
           },
-          "deleted_at": {
-            "description": "Unix epoch seconds the template was soft-deleted. Absent (omitempty) when the template is live.",
-            "format": "int64",
-            "type": "integer"
+          "template_name": {
+            "type": "string",
+            "description": "Unique template name within the account."
           },
           "description": {
-            "description": "Free-form description.",
-            "type": "string"
+            "type": "string",
+            "description": "Free-form description (up to 500 characters); empty string when none was given."
+          },
+          "email": {
+            "type": "string",
+            "description": "Email body template source (Go `html/template` syntax)."
+          },
+          "sms": {
+            "type": "string",
+            "description": "SMS template source (Go `text/template` syntax)."
+          },
+          "voice": {
+            "type": "string",
+            "description": "Voice call script template source."
           },
           "dingtalk": {
-            "description": "DingTalk robot message template source.",
-            "type": "string"
+            "type": "string",
+            "description": "DingTalk robot message template source."
           },
-          "dingtalk_app": {
-            "description": "DingTalk app message template source.",
-            "type": "string"
+          "wecom": {
+            "type": "string",
+            "description": "WeCom robot message template source."
           },
-          "dingtalk_app_war_room_enabled": {
+          "wecom_markdown_v2_enabled": {
             "type": "boolean",
-            "description": "Whether DingTalk app cards show the Create War Room button. Hidden for closed incidents and when the incident has no responders."
-          },
-          "email": {
-            "description": "Email body template source (Go `html/template` syntax).",
-            "type": "string"
+            "description": "Whether WeCom robot notifications use the `markdown_v2` message format."
           },
           "feishu": {
-            "description": "Feishu robot message template source.",
-            "type": "string"
+            "type": "string",
+            "description": "Feishu robot message template source."
           },
           "feishu_app": {
-            "description": "Feishu app message template source.",
-            "type": "string"
+            "type": "string",
+            "description": "Feishu app message template source."
+          },
+          "feishu_app_card_v2_table_enabled": {
+            "type": "boolean",
+            "description": "Whether Markdown tables in the `feishu_app` content are rendered as native Feishu card tables."
           },
           "feishu_app_card_v2_preserve_blank_lines": {
             "type": "boolean",
             "description": "Whether Feishu app card v2 messages keep blank lines in the body."
           },
-          "feishu_app_card_v2_table_enabled": {
-            "description": "Whether alert labels use table rendering in Feishu app cards.",
-            "type": "boolean"
-          },
           "feishu_app_war_room_enabled": {
             "type": "boolean",
             "description": "Whether Feishu app cards show the Create War Room button. Hidden when the incident has no responders."
           },
+          "dingtalk_app_war_room_enabled": {
+            "type": "boolean",
+            "description": "Whether DingTalk app cards show the Create War Room button. Hidden for closed incidents and when the incident has no responders."
+          },
+          "slack_app_war_room_enabled": {
+            "type": "boolean",
+            "description": "Whether Slack app cards show the Create War Room button. Hidden for closed incidents and when the incident has no responders."
+          },
+          "dingtalk_app": {
+            "type": "string",
+            "description": "DingTalk app message template source."
+          },
+          "wecom_app": {
+            "type": "string",
+            "description": "WeCom app message template source."
+          },
+          "slack_app": {
+            "type": "string",
+            "description": "Slack app message template source."
+          },
+          "teams_app": {
+            "type": "string",
+            "description": "Microsoft Teams app message template source."
+          },
+          "telegram": {
+            "type": "string",
+            "description": "Telegram bot message template source."
+          },
+          "slack": {
+            "type": "string",
+            "description": "Slack robot message template source."
+          },
+          "zoom": {
+            "type": "string",
+            "description": "Zoom bot message template source."
+          },
           "incident_card_closed_action_apps": {
-            "type": "array",
+            "type": [
+              "array",
+              "null"
+            ],
             "items": {
               "type": "string",
               "enum": [
@@ -26549,185 +27649,106 @@
                 "teams_app"
               ]
             },
-            "description": "IM apps whose closed-incident cards keep the custom action buttons. Supported values: `feishu_app`, `dingtalk_app`, `wecom_app`, `slack_app`, `teams_app`. An empty list hides the buttons on every app."
+            "description": "IM apps whose cards for closed incidents keep the custom action buttons (open incidents always show them). Values: `feishu_app`, `dingtalk_app`, `wecom_app`, `slack_app`, `teams_app`. Empty or `null` hides the buttons on closed-incident cards in every app."
           },
           "incident_card_hidden_fields": {
             "$ref": "#/components/schemas/IncidentCardHiddenFields",
             "description": "Incident card fields hidden per IM app type; an empty object when none are configured."
           },
-          "slack": {
-            "description": "Slack robot message template source.",
-            "type": "string"
-          },
-          "slack_app": {
-            "description": "Slack app message template source.",
-            "type": "string"
-          },
-          "slack_app_war_room_enabled": {
-            "type": "boolean",
-            "description": "Whether Slack app cards show the Create War Room button. Hidden for closed incidents and when the incident has no responders."
-          },
-          "sms": {
-            "description": "SMS template source (Go `text/template` syntax).",
-            "type": "string"
-          },
           "status": {
-            "description": "Template lifecycle status. `enabled` templates can be referenced by escalation policies for notifications; `disabled` templates are no longer used for new notifications; `deleted` templates are never returned by list endpoints.",
+            "type": "string",
+            "description": "Template status.\n- `enabled`: usable by escalation rules.\n- `disabled`: not used for new notifications; cannot be set through this API.\n- `deleted`: soft-deleted by `/template/delete`; excluded from `/template/list` but still returned by `/template/info`.",
             "enum": [
               "enabled",
               "disabled",
               "deleted"
-            ],
-            "type": "string"
+            ]
           },
-          "team_id": {
-            "description": "ID of the team this template is scoped to, or 0 for account-wide.",
+          "creator_id": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
-          },
-          "teams_app": {
-            "description": "Microsoft Teams app message template source.",
-            "type": "string"
-          },
-          "telegram": {
-            "description": "Telegram bot message template source.",
-            "type": "string"
-          },
-          "template_id": {
-            "description": "Template ID.",
-            "example": "6605a1b2c3d4e5f6a7b8c9d0",
-            "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
+            "description": "Member ID of the creator."
           },
-          "template_name": {
-            "description": "Unique template name within the account.",
-            "type": "string"
+          "updated_by": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Member ID of the last editor."
           },
-          "updated_at": {
-            "description": "Unix epoch seconds the template was last updated.",
+          "deleted_at": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Unix epoch seconds the template was soft-deleted. Absent (omitempty) when the template is live."
           },
-          "updated_by": {
-            "description": "Member ID of the last editor.",
+          "created_at": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Unix epoch seconds the template was created."
           },
-          "voice": {
-            "description": "Voice call script template source.",
-            "type": "string"
-          },
-          "wecom": {
-            "description": "WeCom robot message template source.",
-            "type": "string"
-          },
-          "wecom_app": {
-            "description": "WeCom app message template source.",
-            "type": "string"
-          },
-          "wecom_markdown_v2_enabled": {
-            "type": "boolean",
-            "description": "Whether WeCom robot notifications use the `markdown_v2` message format."
-          },
-          "zoom": {
-            "description": "Zoom bot message template source.",
-            "type": "string"
+          "updated_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Unix epoch seconds the template was last updated."
           }
-        },
-        "required": [
-          "account_id",
-          "team_id",
-          "template_id",
-          "template_name",
-          "description",
-          "email",
-          "sms",
-          "voice",
-          "dingtalk",
-          "wecom",
-          "feishu",
-          "feishu_app",
-          "feishu_app_card_v2_table_enabled",
-          "wecom_markdown_v2_enabled",
-          "feishu_app_card_v2_preserve_blank_lines",
-          "feishu_app_war_room_enabled",
-          "dingtalk_app_war_room_enabled",
-          "slack_app_war_room_enabled",
-          "dingtalk_app",
-          "wecom_app",
-          "slack_app",
-          "teams_app",
-          "telegram",
-          "slack",
-          "zoom",
-          "status",
-          "creator_id",
-          "updated_by",
-          "created_at",
-          "updated_at",
-          "incident_card_closed_action_apps",
-          "incident_card_hidden_fields"
-        ],
-        "type": "object"
+        }
       },
       "TemplateListRequest": {
+        "type": "object",
         "description": "Paginated list filters. Defaults: p=1, limit=20. Max limit=100.",
         "properties": {
-          "asc": {
-            "default": false,
-            "description": "Ascending sort order.",
-            "type": "boolean"
-          },
-          "creator_id": {
-            "description": "Filter by creator member ID; obtain member IDs from `POST /member/list`.",
-            "format": "int64",
-            "type": [
-              "integer",
-              "null"
-            ]
-          },
-          "is_my_team": {
-            "default": false,
-            "description": "When true, only return templates scoped to teams the caller belongs to.",
-            "type": "boolean"
+          "p": {
+            "type": "integer",
+            "description": "Page number, starting at 1.",
+            "minimum": 1,
+            "default": 1,
+            "example": 1
           },
           "limit": {
-            "default": 20,
+            "type": "integer",
             "description": "Page size. Capped at 100.",
-            "example": 20,
-            "maximum": 100,
             "minimum": 1,
-            "type": "integer"
+            "maximum": 100,
+            "default": 20,
+            "example": 20
           },
           "orderby": {
-            "description": "Sort field.",
+            "type": "string",
+            "description": "Sort field: `created_at` (default, creation time) or `updated_at` (last update time).",
             "enum": [
               "created_at",
               "updated_at"
-            ],
-            "type": "string"
+            ]
           },
-          "p": {
-            "default": 1,
-            "description": "Page number, starting at 1.",
-            "example": 1,
-            "minimum": 1,
-            "type": "integer"
+          "asc": {
+            "type": "boolean",
+            "description": "Sort ascending when `true`; defaults to newest first.",
+            "default": false
           },
-          "query": {
-            "description": "Regex or substring match on template_name.",
-            "type": "string"
+          "is_my_team": {
+            "type": "boolean",
+            "description": "When `true`, only templates of teams the caller belongs to are returned. If `team_ids` is also sent, only teams in both lists are kept; when they share no team, no team filter is applied and templates of all teams are returned. A caller in no team gets an empty result.",
+            "default": false
           },
           "team_ids": {
-            "description": "Filter by specific team IDs.",
+            "type": "array",
             "items": {
-              "format": "int64",
-              "type": "integer"
+              "type": "integer",
+              "format": "int64"
             },
-            "type": "array"
+            "description": "Return only templates of these team IDs (from `POST /team/list`); `0` selects account-wide templates. Empty or omitted applies no team filter. See `is_my_team` for how the two combine."
+          },
+          "creator_id": {
+            "type": [
+              "integer",
+              "null"
+            ],
+            "format": "int64",
+            "description": "Filter by creator member ID; obtain member IDs from `POST /member/list`."
+          },
+          "query": {
+            "type": "string",
+            "description": "Case-insensitive regular expression matched against `template_name`; an invalid expression is matched as literal text."
           }
-        },
-        "type": "object"
+        }
       },
       "TemplateListResponse": {
         "description": "Paginated template list.",
@@ -26759,71 +27780,110 @@
         "type": "object"
       },
       "TemplateUpdateRequest": {
+        "type": "object",
         "description": "Update an existing template.",
+        "required": [
+          "template_id",
+          "template_name"
+        ],
         "properties": {
+          "template_id": {
+            "type": "string",
+            "pattern": "^[0-9a-fA-F]{24}$",
+            "description": "Target template ID; obtain it from `POST /template/list`.",
+            "example": "6605a1b2c3d4e5f6a7b8c9d0"
+          },
+          "team_id": {
+            "type": [
+              "integer",
+              "null"
+            ],
+            "format": "int64",
+            "description": "Team scope. 0 for account-wide. Omit to keep the template's current team."
+          },
+          "template_name": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 39,
+            "description": "Template name, 1–39 characters. Required and written on every call; must not be used by another template."
+          },
           "description": {
-            "description": "Free-form description. Up to 500 characters. Omit to keep the current content; send an empty string to clear it.",
+            "type": [
+              "string",
+              "null"
+            ],
             "maxLength": 500,
+            "description": "Free-form description. Up to 500 characters. Omit to keep the current content; send an empty string to clear it."
+          },
+          "email": {
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "Email body template source (Go `html/template` syntax). Omit to keep the current content; send an empty string to clear it."
           },
-          "dingtalk": {
-            "description": "DingTalk robot message template source. Omit to keep the current content; send an empty string to clear it.",
+          "sms": {
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "SMS template source (Go `text/template` syntax). Omit to keep the current content; send an empty string to clear it."
           },
-          "dingtalk_app": {
-            "description": "DingTalk app message template source. Omit to keep the current content; send an empty string to clear it.",
+          "voice": {
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "Voice call script template source. Omit to keep the current content; send an empty string to clear it."
           },
-          "dingtalk_app_war_room_enabled": {
+          "dingtalk": {
             "type": [
-              "boolean",
+              "string",
               "null"
             ],
-            "description": "When set, show or hide the Create War Room button on DingTalk app cards. Omit to keep the existing setting."
+            "description": "DingTalk robot message template source. Omit to keep the current content; send an empty string to clear it."
           },
-          "email": {
-            "description": "Email body template source (Go `html/template` syntax). Omit to keep the current content; send an empty string to clear it.",
+          "wecom": {
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "WeCom robot message template source. Omit to keep the current content; send an empty string to clear it."
+          },
+          "wecom_markdown_v2_enabled": {
+            "type": [
+              "boolean",
+              "null"
+            ],
+            "description": "Send WeCom robot notifications as `markdown_v2` messages instead of plain markdown. While enabled, the rendered `wecom` content must be at most 4,096 bytes. Omit to keep the current setting."
           },
           "feishu": {
-            "description": "Feishu robot message template source. Omit to keep the current content; send an empty string to clear it.",
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "Feishu robot message template source. Omit to keep the current content; send an empty string to clear it."
           },
           "feishu_app": {
-            "description": "Feishu app message template source. Omit to keep the current content; send an empty string to clear it.",
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "Feishu app message template source. Omit to keep the current content; send an empty string to clear it."
           },
-          "feishu_app_card_v2_preserve_blank_lines": {
+          "feishu_app_card_v2_table_enabled": {
             "type": [
               "boolean",
               "null"
             ],
-            "description": "When set, keep or drop blank lines in the body of Feishu app card v2 messages. Omit to keep the existing setting."
+            "description": "Render Markdown tables in the `feishu_app` content as native Feishu card tables. Omit to keep the current setting."
           },
-          "feishu_app_card_v2_table_enabled": {
-            "description": "When set, enable or disable table rendering for alert labels in Feishu app cards. Omit to keep the existing setting.",
+          "feishu_app_card_v2_preserve_blank_lines": {
             "type": [
               "boolean",
               "null"
-            ]
+            ],
+            "description": "When set, keep or drop blank lines in the body of Feishu app card v2 messages. Omit to keep the existing setting."
           },
           "feishu_app_war_room_enabled": {
             "type": [
@@ -26832,37 +27892,12 @@
             ],
             "description": "When set, show or hide the Create War Room button on Feishu app cards. Omit to keep the existing setting."
           },
-          "incident_card_closed_action_apps": {
-            "type": "array",
-            "items": {
-              "type": "string",
-              "enum": [
-                "feishu_app",
-                "dingtalk_app",
-                "wecom_app",
-                "slack_app",
-                "teams_app"
-              ]
-            },
-            "description": "Replaces the retained-app list when sent. Supported values: `feishu_app`, `dingtalk_app`, `wecom_app`, `slack_app`, `teams_app`. Omit the field to leave it unchanged."
-          },
-          "incident_card_hidden_fields": {
-            "$ref": "#/components/schemas/IncidentCardHiddenFields",
-            "description": "Incident card fields hidden per IM app type."
-          },
-          "slack": {
-            "description": "Slack robot message template source. Omit to keep the current content; send an empty string to clear it.",
-            "type": [
-              "string",
-              "null"
-            ]
-          },
-          "slack_app": {
-            "description": "Slack app message template source. Omit to keep the current content; send an empty string to clear it.",
+          "dingtalk_app_war_room_enabled": {
             "type": [
-              "string",
+              "boolean",
               "null"
-            ]
+            ],
+            "description": "When set, show or hide the Create War Room button on DingTalk app cards. Omit to keep the existing setting."
           },
           "slack_app_war_room_enabled": {
             "type": [
@@ -26871,119 +27906,105 @@
             ],
             "description": "When set, show or hide the Create War Room button on Slack app cards. Omit to keep the existing setting."
           },
-          "sms": {
-            "description": "SMS template source (Go `text/template` syntax). Omit to keep the current content; send an empty string to clear it.",
+          "dingtalk_app": {
             "type": [
               "string",
               "null"
-            ]
-          },
-          "team_id": {
-            "description": "Team scope. 0 for account-wide. Omit to keep the template's current team.",
-            "format": "int64",
-            "type": [
-              "integer",
-              "null"
-            ]
+            ],
+            "description": "DingTalk app message template source. Omit to keep the current content; send an empty string to clear it."
           },
-          "teams_app": {
-            "description": "Microsoft Teams app message template source. Omit to keep the current content; send an empty string to clear it.",
+          "wecom_app": {
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "WeCom app message template source. Omit to keep the current content; send an empty string to clear it."
           },
-          "telegram": {
-            "description": "Telegram bot message template source. Omit to keep the current content; send an empty string to clear it.",
+          "slack_app": {
             "type": [
               "string",
               "null"
-            ]
-          },
-          "template_id": {
-            "description": "Target template ID; obtain it from `POST /template/list`.",
-            "example": "6605a1b2c3d4e5f6a7b8c9d0",
-            "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
-          },
-          "template_name": {
-            "description": "Template name. 1–39 characters.",
-            "maxLength": 39,
-            "minLength": 1,
-            "type": "string"
+            ],
+            "description": "Slack app message template source. Omit to keep the current content; send an empty string to clear it."
           },
-          "voice": {
-            "description": "Voice call script template source. Omit to keep the current content; send an empty string to clear it.",
+          "teams_app": {
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "Microsoft Teams app message template source. Omit to keep the current content; send an empty string to clear it."
           },
-          "wecom": {
-            "description": "WeCom robot message template source. Omit to keep the current content; send an empty string to clear it.",
+          "telegram": {
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "Telegram bot message template source. Omit to keep the current content; send an empty string to clear it."
           },
-          "wecom_app": {
-            "description": "WeCom app message template source. Omit to keep the current content; send an empty string to clear it.",
+          "slack": {
             "type": [
               "string",
               "null"
-            ]
-          },
-          "wecom_markdown_v2_enabled": {
-            "type": [
-              "boolean",
-              "null"
             ],
-            "description": "When set, switch WeCom robot notifications between `markdown_v2` and plain markdown. Omit to keep the existing setting."
+            "description": "Slack robot message template source. Omit to keep the current content; send an empty string to clear it."
           },
           "zoom": {
-            "description": "Zoom bot message template source. Omit to keep the current content; send an empty string to clear it.",
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "Zoom bot message template source. Omit to keep the current content; send an empty string to clear it."
+          },
+          "incident_card_closed_action_apps": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "enum": [
+                "feishu_app",
+                "dingtalk_app",
+                "wecom_app",
+                "slack_app",
+                "teams_app"
+              ]
+            },
+            "description": "Replaces the retained-app list when sent. Supported values: `feishu_app`, `dingtalk_app`, `wecom_app`, `slack_app`, `teams_app`. Omit the field to leave it unchanged."
+          },
+          "incident_card_hidden_fields": {
+            "$ref": "#/components/schemas/IncidentCardHiddenFields",
+            "description": "Incident card fields to hide per IM app type. When sent, replaces the stored value as a whole; omit to keep."
           }
-        },
-        "required": [
-          "template_id",
-          "template_name"
-        ],
-        "type": "object"
+        }
       },
       "TimeFilter": {
-        "description": "Recurring time window. `start`/`end` use 24-hour `HH:MM` format; `repeat` lists ISO-style weekday indices (0=Sunday … 6=Saturday).",
+        "type": "object",
+        "description": "Recurring time window. `start` and `end` are `HH:MM` in 24-hour format with `start` not later than `end` (windows cannot cross midnight); `00:00`–`00:00` means the whole day.",
         "properties": {
-          "cal_id": {
-            "description": "Optional calendar ID; restricts the window to days matching the calendar.",
-            "type": "string"
+          "start": {
+            "type": "string",
+            "description": "Window start, `HH:MM`, inclusive."
           },
           "end": {
-            "description": "End of the window in `HH:MM`.",
-            "type": "string"
-          },
-          "is_off": {
-            "description": "When true, match days marked as days-off in the calendar.",
-            "type": "boolean"
+            "type": "string",
+            "description": "Window end, `HH:MM`, inclusive (`23:59` lasts to midnight)."
           },
           "repeat": {
-            "description": "Days of the week this window repeats on. Empty means every day.",
+            "type": "array",
             "items": {
-              "maximum": 6,
+              "type": "integer",
               "minimum": 0,
-              "type": "integer"
+              "maximum": 6
             },
-            "type": "array"
+            "description": "Days of the week the window applies on: `0` = Sunday … `6` = Saturday. Empty means every day."
           },
-          "start": {
-            "description": "Start of the window in `HH:MM`.",
-            "type": "string"
+          "cal_id": {
+            "type": "string",
+            "description": "Service calendar ID from `POST /calendar/list` (for example `cal.xxxx`). When set, the window applies only on the calendar's workdays or days off, as chosen by `is_off`."
+          },
+          "is_off": {
+            "type": "boolean",
+            "description": "Used with `cal_id`: `true` applies the window only on the calendar's days off, `false` only on its workdays."
           }
-        },
-        "type": "object"
+        }
       },
       "TryLinkPersonRequest": {
         "description": "Parameters for attempting automatic IM account linking.",
@@ -27000,21 +28021,31 @@
         "type": "object"
       },
       "TryLinkPersonResponse": {
-        "description": "People linked by this attempt. When nobody could be newly linked, the response either carries an empty `new_linked_person_ids` array or omits the `data` field entirely.",
+        "type": "object",
+        "description": "Result of one linking run for the integration.",
+        "required": [
+          "new_linked_person_ids",
+          "unmatched_count",
+          "no_contact_count"
+        ],
         "properties": {
           "new_linked_person_ids": {
-            "description": "Person IDs newly linked during this call.",
+            "type": "array",
             "items": {
-              "format": "int64",
-              "type": "integer"
+              "type": "integer",
+              "format": "int64"
             },
-            "type": "array"
+            "description": "Person IDs linked to the IM app during this call. Empty when nobody was newly linked."
+          },
+          "unmatched_count": {
+            "type": "integer",
+            "description": "Members with an email or phone that were looked up but not newly linked: not found on the IM platform, the IM account is already linked to another member, or the lookup failed for them."
+          },
+          "no_contact_count": {
+            "type": "integer",
+            "description": "Unlinked members skipped because they have neither an email nor a phone number."
           }
-        },
-        "required": [
-          "new_linked_person_ids"
-        ],
-        "type": "object"
+        }
       },
       "UnackIncidentRequest": {
         "description": "Parameters for removing acknowledgement from one or more incidents.",
@@ -27036,302 +28067,327 @@
         "type": "object"
       },
       "UnsubscribeRuleItem": {
+        "type": "object",
         "description": "Drop (unsubscribe) rule record.",
+        "required": [
+          "account_id",
+          "channel_id",
+          "rule_name",
+          "description",
+          "filters",
+          "status",
+          "rule_id",
+          "updated_by",
+          "created_at",
+          "updated_at"
+        ],
         "properties": {
           "account_id": {
-            "description": "ID of the account the rule belongs to.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "ID of the account the rule belongs to."
           },
           "channel_id": {
-            "description": "ID of the channel the rule belongs to.",
-            "format": "int64",
-            "type": "integer"
-          },
-          "created_at": {
-            "description": "Creation time, Unix timestamp in seconds.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "ID of the channel the rule belongs to."
           },
-          "deleted_at": {
-            "description": "Deletion time, Unix timestamp in seconds. Omitted unless the rule is soft-deleted; deleted rules are excluded from list responses.",
-            "format": "int64",
-            "type": "integer"
+          "rule_name": {
+            "type": "string",
+            "description": "Drop rule name, 1–39 characters."
           },
           "description": {
-            "description": "Rule description.",
-            "type": "string"
+            "type": "string",
+            "description": "Rule description."
           },
           "filters": {
             "$ref": "#/components/schemas/FilterGroup",
-            "description": "Alert event match conditions (OR-of-AND); matching events are discarded entirely. Empty means the rule matches nothing."
-          },
-          "rule_id": {
-            "description": "Rule ID (MongoDB ObjectID).",
-            "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
-          },
-          "rule_name": {
-            "description": "Rule name.",
-            "type": "string"
+            "description": "Alert event conditions (OR of AND groups); matching events are discarded entirely. Empty means the rule matches nothing; `null` when the last update omitted `filters`."
           },
           "status": {
-            "description": "Rule status: `enabled` or `disabled`; deleted rules never appear in the list.",
+            "type": "string",
             "enum": [
               "enabled",
               "disabled"
             ],
-            "type": "string"
+            "description": "Rule status: `enabled` or `disabled`; deleted rules never appear in the list."
+          },
+          "rule_id": {
+            "type": "string",
+            "pattern": "^[0-9a-fA-F]{24}$",
+            "description": "Rule ID (MongoDB ObjectID)."
+          },
+          "updated_by": {
+            "type": "integer",
+            "format": "int64",
+            "description": "ID of the user who last updated the rule."
+          },
+          "created_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Creation time, Unix timestamp in seconds."
           },
           "updated_at": {
-            "description": "Last update time, Unix timestamp in seconds.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Last update time, Unix timestamp in seconds."
           },
-          "updated_by": {
-            "description": "ID of the user who last updated the rule.",
+          "deleted_at": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Deletion time, Unix timestamp in seconds. Omitted unless the rule is soft-deleted; deleted rules are excluded from list responses."
           }
-        },
-        "required": [
-          "account_id",
-          "channel_id",
-          "rule_name",
-          "description",
-          "filters",
-          "status",
-          "rule_id",
-          "updated_by",
-          "created_at",
-          "updated_at"
-        ],
-        "type": "object"
+        }
       },
       "UpdateChannelRequest": {
+        "type": "object",
+        "required": [
+          "channel_id"
+        ],
         "description": "Parameters for updating a channel. Only the fields you pass are updated.",
         "properties": {
-          "auto_resolve_mode": {
-            "description": "Auto-resolve timing mode: `trigger` starts the timer when the incident triggers, `update` restarts it on every alert update. Applied only when `auto_resolve_timeout` is also present in the request.",
-            "enum": [
-              "trigger",
-              "update"
-            ],
-            "type": "string"
-          },
-          "auto_resolve_timeout": {
-            "description": "Auto-resolve timeout in seconds. 0 disables auto-resolve. Max 30 days.",
+          "channel_id": {
+            "type": "integer",
             "format": "int64",
-            "maximum": 2592000,
-            "minimum": 0,
+            "description": "ID of the channel to update; obtain it from `POST /channel/list`."
+          },
+          "team_id": {
             "type": [
               "integer",
               "null"
-            ]
-          },
-          "channel_id": {
-            "description": "ID of the channel to update; obtain it from `POST /channel/list`.",
+            ],
             "format": "int64",
-            "type": "integer"
+            "description": "New owning team ID; obtain it from `POST /team/list`. Must exist. Omit or pass `null` to keep the current team."
+          },
+          "managing_team_ids": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "int64"
+            },
+            "maxItems": 3,
+            "description": "Replaces the additional managing teams, up to 3; every ID must exist. Pass `[]` to remove them all; omit to keep the current list."
           },
           "channel_name": {
-            "description": "New channel name. 1 to 59 characters.",
-            "maxLength": 59,
-            "minLength": 1,
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "minLength": 1,
+            "maxLength": 59,
+            "description": "New channel name, 1–59 characters, unique within the account. Omit or pass `null` to keep the current name."
           },
           "description": {
-            "description": "New description. Up to 500 characters.",
-            "maxLength": 500,
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "maxLength": 500,
+            "description": "New description. Up to 500 characters."
           },
-          "disable_auto_close": {
-            "description": "Disable automatic incident closing.",
+          "auto_resolve_timeout": {
             "type": [
-              "boolean",
+              "integer",
               "null"
-            ]
+            ],
+            "format": "int64",
+            "minimum": 0,
+            "maximum": 2592000,
+            "description": "Auto-resolve timeout in seconds. 0 disables auto-resolve. Max 30 days."
           },
-          "disable_outlier_detection": {
-            "description": "Disable outlier incident detection.",
+          "auto_resolve_mode": {
+            "type": "string",
+            "enum": [
+              "trigger",
+              "update"
+            ],
+            "description": "How the auto-resolve timer runs: `trigger` starts it once when the incident is triggered, `update` restarts it whenever a new alert merges in. Applied only together with `auto_resolve_timeout`; if `auto_resolve_timeout` is sent without it, the mode resets to `trigger`."
+          },
+          "is_private": {
             "type": [
               "boolean",
               "null"
-            ]
+            ],
+            "description": "When true, the channel is visible only to its managing teams."
           },
-          "event_group": {
-            "$ref": "#/components/schemas/EventGroup",
-            "description": "Alert event merge configuration. Updated only when present."
+          "group": {
+            "$ref": "#/components/schemas/Group",
+            "description": "Alert grouping configuration; replaces the stored configuration as a whole when present."
           },
           "flapping": {
             "$ref": "#/components/schemas/Flapping",
-            "description": "Flapping detection configuration."
-          },
-          "group": {
-            "$ref": "#/components/schemas/Group",
-            "description": "Alert grouping configuration."
+            "description": "Flapping detection configuration; replaces the stored configuration as a whole when present."
           },
-          "is_external_report_enabled": {
-            "description": "Allow external reporters to file incidents into this channel.",
+          "disable_outlier_detection": {
             "type": [
               "boolean",
               "null"
-            ]
+            ],
+            "description": "Disable outlier incident detection."
           },
-          "is_private": {
-            "description": "When true, the channel is visible only to its managing teams.",
+          "disable_auto_close": {
             "type": [
               "boolean",
               "null"
-            ]
-          },
-          "managing_team_ids": {
-            "description": "Additional teams that can manage the channel. Up to 3 entries.",
-            "items": {
-              "format": "int64",
-              "type": "integer"
-            },
-            "maxItems": 3,
-            "type": "array"
+            ],
+            "description": "Disable automatic incident closing."
           },
-          "team_id": {
-            "description": "New owning team ID; obtain it from `POST /team/list`.",
-            "format": "int64",
+          "is_external_report_enabled": {
             "type": [
-              "integer",
+              "boolean",
               "null"
-            ]
+            ],
+            "description": "`true` enables external reporting and generates a new token, returned in the response (any previous token stops working); `false` disables it and clears the token."
+          },
+          "event_group": {
+            "$ref": "#/components/schemas/EventGroup",
+            "description": "Alert event merge configuration; replaces the stored configuration as a whole when present."
           }
-        },
-        "required": [
-          "channel_id"
-        ],
-        "type": "object"
+        }
       },
       "UpdateChannelResponse": {
-        "description": "Response from updating a channel. Only populated when `is_external_report_enabled` is set to `true`; otherwise all fields are empty.",
+        "type": "object",
+        "description": "Contains `external_report_token` only when the request set `is_external_report_enabled` to `true`; otherwise `data` is an empty object.",
         "properties": {
           "external_report_token": {
-            "description": "Newly generated token for external reporters. Only returned when `is_external_report_enabled` is set to `true` in the request. Callers should store this value; it cannot be retrieved afterwards.",
-            "type": "string"
+            "type": "string",
+            "description": "Newly generated token for external reporters; the previous token stops working. It can be read again later from `external_report_token` in `POST /channel/info`."
           }
-        },
-        "type": "object"
+        }
       },
       "UpdateDropRuleRequest": {
+        "type": "object",
         "description": "Parameters for updating a channel drop rule.",
+        "required": [
+          "channel_id",
+          "rule_id",
+          "rule_name"
+        ],
         "properties": {
           "channel_id": {
-            "description": "Owning channel ID; obtain it from `POST /channel/list`.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
-          },
-          "description": {
-            "description": "Rule description, up to 500 characters.",
-            "maxLength": 500,
-            "type": "string"
-          },
-          "filters": {
-            "$ref": "#/components/schemas/FilterGroup",
-            "description": "Alert event match conditions (OR-of-AND); matching events are discarded entirely. When empty, the rule matches nothing."
+            "description": "Owning channel ID; obtain it from `POST /channel/list`."
           },
           "rule_id": {
-            "description": "Drop rule ID (MongoDB ObjectID).",
+            "type": "string",
             "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
+            "description": "Drop rule ID (MongoDB ObjectID)."
           },
           "rule_name": {
-            "description": "Rule name, 1 to 39 characters.",
-            "maxLength": 39,
+            "type": "string",
             "minLength": 1,
-            "type": "string"
+            "maxLength": 39,
+            "description": "Rule name, 1 to 39 characters."
+          },
+          "description": {
+            "type": "string",
+            "maxLength": 500,
+            "description": "Rule description, up to 500 characters. Omitting it clears the stored description."
+          },
+          "filters": {
+            "$ref": "#/components/schemas/FilterGroup",
+            "description": "Alert event conditions (OR of AND groups); matching events are discarded entirely. Keys: `title`, `description`, `severity` (alias `alert_severity`, `event_severity`), `status`, `alert_key`, `title_rule`, `integration_id` (alias `data_source_id`), or any `labels.<name>`. The stored conditions are replaced; omitting this field clears them and the rule then matches nothing."
           }
-        },
+        }
+      },
+      "UpdateEscalationRuleRequest": {
+        "type": "object",
+        "description": "Parameters for updating an escalation rule.",
         "required": [
           "channel_id",
           "rule_id",
-          "rule_name"
+          "template_id",
+          "rule_name",
+          "layers"
         ],
-        "type": "object"
-      },
-      "UpdateEscalationRuleRequest": {
-        "description": "Parameters for updating an escalation rule.",
         "properties": {
-          "aggr_window": {
-            "description": "Delay window in seconds. 0 disables delay.",
-            "type": "integer"
-          },
           "channel_id": {
-            "description": "Owning channel ID; obtain it from `POST /channel/list`.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
-          },
-          "description": {
-            "description": "Rule description, up to 500 characters.",
-            "maxLength": 500,
-            "type": "string"
-          },
-          "filters": {
-            "$ref": "#/components/schemas/FilterGroup",
-            "description": "Incident-level match conditions (OR-of-AND tree): the rule is matched against the incident the alert was grouped into, not against the alert itself. Omit or leave empty to apply the rule to all incidents in the channel."
+            "description": "Owning channel ID; obtain it from `POST /channel/list`."
           },
-          "layers": {
-            "description": "Escalation levels in order. At least one level is required.",
-            "items": {
-              "$ref": "#/components/schemas/EscalateLayer"
-            },
-            "type": "array"
+          "rule_id": {
+            "type": "string",
+            "pattern": "^[0-9a-fA-F]{24}$",
+            "description": "Escalation rule ID (MongoDB ObjectID)."
           },
           "priority": {
-            "description": "Evaluation priority. Lower runs first.",
             "type": [
               "integer",
               "null"
-            ]
+            ],
+            "description": "Evaluation order; lower values are evaluated first. Omit or pass `null` to keep the current value."
           },
-          "rule_id": {
-            "description": "Escalation rule ID (MongoDB ObjectID).",
+          "aggr_window": {
+            "type": "integer",
+            "description": "Delay in seconds before the first notification for a newly assigned incident; `0` notifies immediately. Omitting it resets the value to `0`."
+          },
+          "template_id": {
+            "type": "string",
             "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
+            "description": "Notification template ID (24-character hex); obtain it from `POST /template/list`. Must exist."
           },
           "rule_name": {
-            "description": "Rule name, 1 to 39 characters.",
-            "maxLength": 39,
+            "type": "string",
             "minLength": 1,
-            "type": "string"
+            "maxLength": 39,
+            "description": "Rule name, 1 to 39 characters."
           },
-          "template_id": {
-            "description": "Notification template ID (MongoDB ObjectID).",
-            "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
+          "description": {
+            "type": "string",
+            "maxLength": 500,
+            "description": "Rule description, up to 500 characters. Omitting it clears the stored description."
+          },
+          "layers": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/EscalateLayer"
+            },
+            "description": "Escalation levels in order. At least one level is required."
           },
           "time_filters": {
-            "description": "Optional recurring time windows during which the rule applies.",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/TimeFilter"
             },
-            "type": "array"
+            "description": "Recurring time windows during which the rule can match. Replaces the stored windows; omit or leave empty to match at any time."
+          },
+          "filters": {
+            "$ref": "#/components/schemas/FilterGroup",
+            "description": "Incident conditions (OR of AND groups), matched against the incident the alert was grouped into, not against the alert. Keys: `title`, `description`, `severity` (alias `incident_severity`, `alert_severity`), `status` (alias `incident_status`, `alert_status`), `dedup_key`, `integration_id` (alias `data_source_id`), or any `labels.<name>`. Replaces the stored conditions; omit or leave empty to match every incident in the channel."
           }
-        },
-        "required": [
-          "channel_id",
-          "rule_id",
-          "template_id",
-          "rule_name",
-          "layers"
-        ],
-        "type": "object"
+        }
       },
       "UpdateFieldRequest": {
+        "type": "object",
+        "required": [
+          "field_id"
+        ],
         "properties": {
+          "field_id": {
+            "type": "string",
+            "pattern": "^[a-f0-9]{24}$",
+            "description": "Field ID — 24-character hex ObjectID."
+          },
+          "display_name": {
+            "type": "string",
+            "maxLength": 39,
+            "description": "New display name (max 39 characters); must stay unique among non-deleted fields. Always written."
+          },
+          "description": {
+            "type": "string",
+            "description": "New description. Always written: omitting it clears the description."
+          },
+          "options": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Replacement options list. Must obey the same per-type rules as create. Note: the update always overwrites `display_name`, `description`, `options`, and `default_value` with the submitted values, so for `single_select`/`multi_select` fields a non-empty `options` list must be sent on every update."
+          },
           "default_value": {
-            "description": "Replacement default value. Type must match the field's existing `field_type`.",
+            "description": "New default value; its type must match the field's `field_type`. Always written: omitting it clears the default.",
             "oneOf": [
               {
                 "type": "boolean"
@@ -27340,184 +28396,160 @@
                 "type": "string"
               },
               {
+                "type": "array",
                 "items": {
                   "type": "string"
-                },
-                "type": "array"
+                }
               },
               {
                 "type": "null"
               }
             ]
-          },
-          "description": {
-            "description": "New description.",
-            "type": "string"
-          },
-          "display_name": {
-            "description": "New display name. Must remain unique within the account.",
-            "maxLength": 39,
-            "type": "string"
-          },
-          "field_id": {
-            "description": "Field ID — 24-character hex ObjectID.",
-            "pattern": "^[a-f0-9]{24}$",
-            "type": "string"
-          },
-          "options": {
-            "description": "Replacement options list. Must obey the same per-type rules as create. Note: the update always overwrites `display_name`, `description`, `options`, and `default_value` with the submitted values, so for `single_select`/`multi_select` fields a non-empty `options` list must be sent on every update.",
-            "items": {
-              "type": "string"
-            },
-            "type": "array"
           }
-        },
-        "required": [
-          "field_id"
-        ],
-        "type": "object"
+        }
       },
       "UpdateIncidentCommentTypeRequest": {
+        "type": "object",
         "description": "Parameters for updating a comment type. Partial update: at least one of `name` or `color` must be provided.",
+        "required": [
+          "comment_type_id"
+        ],
         "properties": {
-          "color": {
-            "description": "New label color as a hex value in #RRGGBB format. Normalized to uppercase.",
-            "pattern": "^#[0-9A-Fa-f]{6}$",
-            "type": "string"
-          },
           "comment_type_id": {
-            "description": "ID of the comment type to update (24-character hex ObjectID).",
+            "type": "string",
             "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
+            "description": "ID of the comment type to update (24-character hex ObjectID)."
           },
           "name": {
-            "description": "New display name. Trimmed before storing; must be unique within the account (case-insensitive). At most 40 characters.",
+            "type": "string",
             "maxLength": 40,
-            "type": "string"
+            "description": "New display name. Trimmed before storing; must be unique within the account (case-insensitive). At most 40 characters. Must not contain control or text-direction characters."
+          },
+          "color": {
+            "type": "string",
+            "pattern": "^#[0-9A-Fa-f]{6}$",
+            "description": "New label color as a hex value in #RRGGBB format. Normalized to uppercase."
           }
-        },
-        "required": [
-          "comment_type_id"
-        ],
-        "type": "object"
+        }
       },
       "UpdateIncidentFieldsRequest": {
-        "description": "Parameters for updating user-editable fields of an incident. At least one field must be provided; the handler will update only the fields you supply.",
+        "type": "object",
+        "description": "Fields to update on an incident. At least one field besides `incident_id` must be non-empty; omitted or empty fields keep their current values.",
+        "required": [
+          "incident_id"
+        ],
         "properties": {
+          "incident_id": {
+            "type": "string",
+            "pattern": "^[0-9a-fA-F]{24}$",
+            "description": "Incident ID (MongoDB ObjectID)."
+          },
+          "title": {
+            "type": "string",
+            "minLength": 3,
+            "maxLength": 200,
+            "description": "New incident title."
+          },
           "description": {
-            "description": "New description.",
-            "maxLength": 6144,
+            "type": "string",
             "minLength": 3,
-            "type": "string"
+            "maxLength": 6144,
+            "description": "New description."
           },
           "impact": {
-            "description": "New impact description.",
+            "type": "string",
+            "minLength": 3,
             "maxLength": 6144,
+            "description": "New impact description."
+          },
+          "root_cause": {
+            "type": "string",
             "minLength": 3,
-            "type": "string"
+            "maxLength": 6144,
+            "description": "New root cause analysis."
           },
-          "incident_id": {
-            "description": "Incident ID (MongoDB ObjectID).",
-            "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
+          "resolution": {
+            "type": "string",
+            "minLength": 3,
+            "maxLength": 6144,
+            "description": "New resolution notes."
           },
           "incident_severity": {
-            "description": "New severity: `Info`, `Warning` or `Critical` (most severe).",
+            "type": "string",
             "enum": [
               "Info",
               "Warning",
               "Critical"
             ],
-            "type": "string"
-          },
-          "resolution": {
-            "description": "New resolution notes.",
-            "maxLength": 6144,
-            "minLength": 3,
-            "type": "string"
-          },
-          "root_cause": {
-            "description": "New root cause analysis.",
-            "maxLength": 6144,
-            "minLength": 3,
-            "type": "string"
-          },
-          "title": {
-            "description": "New incident title.",
-            "maxLength": 200,
-            "minLength": 3,
-            "type": "string"
+            "description": "New severity: `Info`, `Warning` or `Critical` (most severe)."
           }
-        },
-        "required": [
-          "incident_id"
-        ],
-        "type": "object"
+        }
       },
       "UpdateInhibitRuleRequest": {
+        "type": "object",
         "description": "Parameters for updating an inhibit rule.",
+        "required": [
+          "channel_id",
+          "rule_id",
+          "rule_name",
+          "equals"
+        ],
         "properties": {
           "channel_id": {
-            "description": "Owning channel ID; obtain it from `POST /channel/list`.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Owning channel ID; obtain it from `POST /channel/list`."
+          },
+          "rule_id": {
+            "type": "string",
+            "pattern": "^[0-9a-fA-F]{24}$",
+            "description": "Inhibit rule ID (MongoDB ObjectID)."
+          },
+          "rule_name": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 39,
+            "description": "Rule name, 1 to 39 characters."
           },
           "description": {
-            "description": "Rule description, up to 500 characters.",
+            "type": "string",
             "maxLength": 500,
-            "type": "string"
+            "description": "Rule description, up to 500 characters. Omitting it clears the stored description."
           },
           "equals": {
-            "description": "Field keys whose values must be equal between the source (inhibiting) alert and the target (suppressed) alert, e.g. `data_source_id` or `labels.cluster`.",
+            "type": "array",
             "items": {
               "type": "string"
             },
-            "type": "array"
-          },
-          "is_directly_discard": {
-            "description": "When true, matching alert events are discarded entirely; when false, alerts are still recorded but marked as muted by this rule.",
-            "type": "boolean"
-          },
-          "rule_id": {
-            "description": "Inhibit rule ID (MongoDB ObjectID).",
-            "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
-          },
-          "rule_name": {
-            "description": "Rule name, 1 to 39 characters.",
-            "maxLength": 39,
-            "minLength": 1,
-            "type": "string"
+            "description": "Keys whose values must be equal on the source alert and the incoming event. Only `title`, `severity` and `labels.<name>` take effect; any other key (for example `data_source_id`) is accepted but makes the rule never fire. Must be present; an empty array also makes the rule inert."
           },
           "source_filters": {
             "$ref": "#/components/schemas/FilterGroup",
-            "description": "Conditions the source alert must match, evaluated against stored active alerts. Supported keys: `status`, `incident_status`, `alert_status`, `severity`, `incident_severity`, `alert_severity`, `title`, `description`, or any `labels.<name>`. Empty makes the rule inert."
+            "description": "Conditions the source (inhibiting) alert must match, evaluated against active alerts already stored in the channel. Keys: `title`, `description`, `severity` (alias `incident_severity`, `alert_severity`), `status` (alias `incident_status`, `alert_status`), or any `labels.<name>`. Empty makes the rule inert. Omitting it clears the stored conditions."
           },
           "target_filters": {
             "$ref": "#/components/schemas/FilterGroup",
-            "description": "Conditions the incoming target alert event must match to be suppressed; empty means every event is a target."
+            "description": "Conditions the incoming target alert event must match to be inhibited; empty means every incoming event is a target. Keys: `title`, `description`, `severity` (alias `alert_severity`, `event_severity`), `status`, `alert_key`, `title_rule`, `integration_id` (alias `data_source_id`), or any `labels.<name>`. Omitting it clears the stored conditions."
+          },
+          "is_directly_discard": {
+            "type": "boolean",
+            "description": "When true, matching alert events are discarded entirely; when false, alerts are still recorded but marked as muted by this rule. Omitting it sets it to `false`."
           }
-        },
-        "required": [
-          "channel_id",
-          "rule_id",
-          "rule_name",
-          "equals"
-        ],
-        "type": "object"
+        }
       },
       "UpdateRemoteConfigRequest": {
         "description": "Publish a whole new remote configuration version. The client sends the complete object, not a patch: rule order carries meaning.",
         "properties": {
           "application_id": {
-            "description": "RUM application ID.",
+            "description": "RUM application ID. Get application IDs via `POST /rum/application/list`.",
             "type": "string"
           },
           "config": {
-            "$ref": "#/components/schemas/RemoteConfig"
+            "$ref": "#/components/schemas/RemoteConfig",
+            "description": "The complete configuration to publish."
           },
           "reason": {
-            "description": "Operator's note on why this version was published. Stored verbatim.",
+            "description": "Optional free-text note (not an enum) on why this version was published, at most 255 characters; stored verbatim and returned as `reason` by `POST /rum/application/remote-config/history/list`.",
             "maxLength": 255,
             "type": "string"
           }
@@ -27532,474 +28564,493 @@
         "description": "Version allocated to the published configuration.",
         "properties": {
           "version": {
-            "description": "New published version number.",
+            "description": "Version number allocated to the published configuration (previous highest version + 1).",
             "type": "integer"
           }
         },
         "type": "object"
       },
       "UpdateSilenceRuleRequest": {
+        "type": "object",
         "description": "Parameters for updating a silence rule. Exactly one of `time_filter` or `time_filters` must be provided, and `filters` must be non-empty.",
+        "required": [
+          "channel_id",
+          "rule_id",
+          "rule_name"
+        ],
         "properties": {
           "channel_id": {
-            "description": "Owning channel ID; obtain it from `POST /channel/list`.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
-          },
-          "description": {
-            "description": "Rule description, up to 500 characters.",
-            "maxLength": 500,
-            "type": "string"
-          },
-          "filters": {
-            "$ref": "#/components/schemas/FilterGroup",
-            "description": "Match conditions for the alerts to silence; required and must not be empty."
-          },
-          "is_auto_delete": {
-            "description": "When true, the silence rule is automatically deleted after its time window expires. Defaults to false.",
-            "type": "boolean"
-          },
-          "is_directly_discard": {
-            "description": "When true, matching alert events are discarded entirely; when false, alerts are still recorded but marked as muted by this rule.",
-            "type": "boolean"
+            "description": "Owning channel ID; obtain it from `POST /channel/list`."
           },
           "rule_id": {
-            "description": "Silence rule ID (MongoDB ObjectID).",
+            "type": "string",
             "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
+            "description": "Silence rule ID (MongoDB ObjectID)."
           },
           "rule_name": {
-            "description": "Rule name, 1 to 39 characters.",
-            "maxLength": 39,
+            "type": "string",
             "minLength": 1,
-            "type": "string"
+            "maxLength": 39,
+            "description": "Rule name, 1 to 39 characters."
           },
-          "time_filter": {
-            "$ref": "#/components/schemas/OnceTimeFilter",
-            "description": "One-off silence window. Mutually exclusive with `time_filters`; exactly one of the two must be set."
+          "description": {
+            "type": "string",
+            "maxLength": 500,
+            "description": "Rule description, up to 500 characters. Omitting it clears the stored description."
           },
           "time_filters": {
-            "description": "Recurring time windows. Mutually exclusive with `time_filter`.",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/TimeFilter"
             },
-            "type": "array"
+            "description": "Recurring time windows. Mutually exclusive with `time_filter`."
+          },
+          "time_filter": {
+            "$ref": "#/components/schemas/OnceTimeFilter",
+            "description": "One-off silence window. Mutually exclusive with `time_filters`; exactly one of the two must be set."
+          },
+          "filters": {
+            "$ref": "#/components/schemas/FilterGroup",
+            "description": "Alert event conditions (OR of AND groups); matching events are silenced while the time window is active. Required, with at least one condition. Keys: `title`, `description`, `severity` (alias `alert_severity`, `event_severity`), `status`, `alert_key`, `title_rule`, `integration_id` (alias `data_source_id`), or any `labels.<name>`."
+          },
+          "is_directly_discard": {
+            "type": "boolean",
+            "description": "When true, matching alert events are discarded entirely; when false, alerts are still recorded but marked as silenced by this rule. Omitting it sets it to `false`."
+          },
+          "is_auto_delete": {
+            "type": "boolean",
+            "description": "When true, a rule with a one-off `time_filter` is permanently removed about 24 hours after `end_time` (or after its last update, whichever is later). Rules created with `from_incident_id` are cleaned up the same way. Rules with recurring `time_filters` are never removed automatically. Omitting it sets it to `false`."
           }
-        },
-        "required": [
-          "channel_id",
-          "rule_id",
-          "rule_name"
-        ],
-        "type": "object"
+        }
       },
       "UpdateStatusPageChangeRequest": {
+        "type": "object",
         "description": "Parameters for updating the editable fields of a status page event.",
+        "required": [
+          "page_id",
+          "change_id"
+        ],
         "properties": {
-          "change_id": {
-            "description": "Target change ID; obtain it from `GET /status-page/change/list`.",
-            "format": "int64",
-            "type": "integer"
-          },
-          "linked_changes": {
-            "description": "Linked event IDs. Pass the full replacement list.",
-            "items": {
-              "type": "string"
-            },
-            "type": "array"
-          },
           "page_id": {
-            "description": "Status page ID; obtain it from `GET /status-page/list`.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Status page ID; obtain it from `GET /status-page/list`."
           },
-          "responders": {
-            "description": "Member IDs responsible for this event. Pass the full replacement list.",
-            "items": {
-              "format": "int64",
-              "type": "integer"
-            },
-            "type": "array"
+          "change_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Target change ID; obtain it from `GET /status-page/change/list`."
           },
           "title": {
-            "description": "New event title, up to 255 characters. Omit to keep the existing value.",
-            "maxLength": 255,
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "maxLength": 255,
+            "description": "New event title, up to 255 characters. Omit to keep the existing value."
+          },
+          "responders": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "int64"
+            },
+            "description": "Member IDs responsible for this event, replacing the current list. An omitted or empty array keeps the current list."
+          },
+          "linked_changes": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Linked event IDs, replacing the current list. An omitted or empty array keeps the current list."
           }
-        },
-        "required": [
-          "page_id",
-          "change_id"
-        ],
-        "type": "object"
+        }
       },
       "UpdateStatusPageChangeTimelineRequest": {
+        "type": "object",
         "description": "Parameters for updating an existing timeline entry on a status page event. At least one of `at_seconds` or `description` must be provided; omitted fields keep their current values.",
+        "required": [
+          "page_id",
+          "change_id",
+          "update_id"
+        ],
         "properties": {
-          "at_seconds": {
-            "description": "New update timestamp in Unix seconds.",
+          "page_id": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Status page ID; obtain it from `GET /status-page/list`."
           },
           "change_id": {
-            "description": "Owning change ID; obtain it from `GET /status-page/change/list`.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Owning change ID; obtain it from `GET /status-page/change/list`."
           },
-          "description": {
-            "description": "New update description (Markdown).",
-            "type": "string"
+          "update_id": {
+            "type": "string",
+            "description": "Target timeline update ID; obtain it from `GET /status-page/change/info`."
           },
-          "page_id": {
-            "description": "Status page ID; obtain it from `GET /status-page/list`.",
+          "at_seconds": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "New update time in Unix seconds; must not be earlier than the previous entry or later than the next one. Omit or pass 0 to keep the current time."
           },
-          "update_id": {
-            "description": "Target timeline update ID; obtain it from `GET /status-page/change/info`.",
-            "type": "string"
+          "description": {
+            "type": "string",
+            "description": "New update description (Markdown). Omit or pass an empty string to keep the current text; editing the latest entry also updates the event description."
           }
-        },
-        "required": [
-          "page_id",
-          "change_id",
-          "update_id"
-        ],
-        "type": "object"
+        }
       },
       "UpdateStatusPageRequest": {
+        "type": "object",
         "description": "Parameters for updating an existing status page. All fields except `page_id` are optional; omit a field or pass null to keep its existing value.",
+        "required": [
+          "page_id"
+        ],
         "properties": {
-          "contact_info": {
-            "description": "Get-in-touch contact, such as a mailto or website URL. Omit or pass null to keep the existing value.",
-            "type": [
-              "string",
-              "null"
-            ]
+          "page_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Status page ID; obtain it from `GET /status-page/list`."
           },
-          "custom_domain": {
-            "description": "Custom domain for a public status page. Omit or pass null to keep the existing value.",
-            "maxLength": 255,
+          "name": {
             "type": [
               "string",
               "null"
-            ]
-          },
-          "custom_links": {
-            "description": "Custom navigation links shown on the status page. Omit or pass an empty array to keep the current links.",
-            "items": {
-              "additionalProperties": {
-                "type": "string"
-              },
-              "type": "object"
-            },
-            "type": "array"
+            ],
+            "description": "Display name of the status page. Omit or pass null to keep the existing value.",
+            "maxLength": 255
           },
-          "dark_logo": {
-            "description": "Dark-mode logo image of the status page. Omit or pass null to keep the existing value.",
+          "url_name": {
             "type": [
               "string",
               "null"
-            ]
-          },
-          "date_view": {
-            "description": "How change dates are displayed. Leave empty to keep the current value. `calendar` uses a calendar view; `list` uses a list view.",
-            "enum": [
-              "calendar",
-              "list"
             ],
-            "type": [
-              "string",
-              "null"
-            ]
+            "description": "URL-safe slug; normalized to lowercase with non-alphanumeric characters replaced by hyphens, and must be unique among the account's pages of the same type. Omit or pass null to keep the existing value.",
+            "maxLength": 255
           },
-          "display_uptime_mode": {
-            "description": "How uptime is displayed. Leave empty to keep the current value. `chart_and_percentage` shows both chart and percentage; `chart` shows only the chart; `none` hides uptime.",
-            "enum": [
-              "chart_and_percentage",
-              "chart",
-              "none"
-            ],
+          "custom_domain": {
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "Custom domain for a public status page; must not be used by another status page. Rejected for internal pages. Omit or pass null to keep the existing value; an empty string removes the domain.",
+            "maxLength": 255
           },
-          "favicon": {
-            "description": "Favicon of the status page. Omit or pass null to keep the existing value.",
+          "page_title": {
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "Accepted for compatibility but not stored; it has no effect."
           },
           "logo": {
-            "description": "Logo image of the status page. Omit or pass null to keep the existing value.",
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "Logo image of the status page. Omit or pass null to keep the existing value."
           },
-          "logo_url": {
-            "description": "URL opened when the logo is clicked. Omit or pass null to keep the existing value.",
-            "maxLength": 255,
+          "dark_logo": {
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "Dark-mode logo image of the status page. Omit or pass null to keep the existing value."
           },
-          "name": {
-            "description": "Display name of the status page. Omit or pass null to keep the existing value.",
-            "maxLength": 255,
+          "logo_url": {
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "URL opened when the logo is clicked. Omit or pass null to keep the existing value.",
+            "maxLength": 255
           },
-          "page_footer": {
-            "description": "Footer content shown on the status page. Omit or pass null to keep the existing value.",
+          "favicon": {
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "Favicon of the status page. Omit or pass null to keep the existing value."
           },
           "page_header": {
-            "description": "Header content shown on the status page. Omit or pass null to keep the existing value.",
             "type": [
               "string",
               "null"
-            ]
-          },
-          "page_id": {
-            "description": "Status page ID; obtain it from `GET /status-page/list`.",
-            "format": "int64",
-            "type": "integer"
+            ],
+            "description": "Header content shown on the status page. Omit or pass null to keep the existing value."
           },
-          "page_title": {
-            "description": "Browser title shown for the status page. Omit or pass null to keep the existing value.",
+          "page_footer": {
             "type": [
               "string",
               "null"
-            ]
-          },
-          "subscription": {
-            "$ref": "#/components/schemas/StatusPageSubscriptionItem",
-            "description": "Subscription channel toggles. Omit or pass null to keep the existing value."
+            ],
+            "description": "Footer content shown on the status page. Omit or pass null to keep the existing value."
           },
-          "template_preference": {
-            "description": "Preferred event template type: `pre_defined` or `message`. Omit or pass null to keep the existing value.",
+          "date_view": {
             "type": [
               "string",
               "null"
+            ],
+            "description": "How event dates are displayed: `calendar` uses a calendar view, `list` uses a list view. Omit or pass null to keep the current value; an empty string clears the setting.",
+            "enum": [
+              "calendar",
+              "list",
+              "",
+              null
             ]
           },
-          "url_name": {
-            "description": "URL-safe slug, unique per account and page type. Omit or pass null to keep the existing value.",
-            "maxLength": 255,
+          "display_uptime_mode": {
             "type": [
               "string",
               "null"
+            ],
+            "description": "How uptime is displayed: `chart_and_percentage` shows the chart and the percentage, `chart` shows only the chart, `none` hides uptime. Omit or pass null to keep the current value; an empty string clears the setting.",
+            "enum": [
+              "chart_and_percentage",
+              "chart",
+              "none",
+              "",
+              null
+            ]
+          },
+          "custom_links": {
+            "type": "array",
+            "description": "Custom navigation links shown on the status page. Omit or pass an empty array to keep the current links.",
+            "items": {
+              "type": "object",
+              "properties": {
+                "key": {
+                  "type": "string",
+                  "description": "Link text shown on the page."
+                },
+                "value": {
+                  "type": "string",
+                  "description": "URL the link text points to, such as `https://www.example.com`."
+                }
+              },
+              "additionalProperties": {
+                "type": "string"
+              }
+            }
+          },
+          "contact_info": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "Get-in-touch contact, such as a mailto or website URL. Omit or pass null to keep the existing value."
+          },
+          "subscription": {
+            "$ref": "#/components/schemas/StatusPageSubscriptionItem",
+            "description": "Subscription channel toggles. A public page can enable only `email` and an internal page only `im`. Omit or pass null to keep the existing value."
+          },
+          "template_preference": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "Event template mode used when publishing events in the console: `message` (status descriptions: per-status texts) or `pre_defined` (full status updates: complete examples with title, status, and description). Omit or pass null to keep the current value; the value is not validated.",
+            "enum": [
+              "pre_defined",
+              "message",
+              null
             ]
           }
-        },
-        "required": [
-          "page_id"
-        ],
-        "type": "object"
+        }
       },
       "UpdateWorkItemRequest": {
-        "description": "Partial patch for a work item. Omitted fields stay unchanged; an explicit `null` clears the field.",
+        "type": "object",
+        "description": "Partial patch for a work item. Omitted fields and fields sent as `null` stay unchanged.",
+        "required": [
+          "work_item_id",
+          "version"
+        ],
         "properties": {
-          "description": {
-            "description": "New description (max 65,535 characters).",
-            "maxLength": 65535,
+          "work_item_id": {
+            "type": "string",
+            "maxLength": 128,
+            "description": "Work item ID (opaque string, max 128 characters)."
+          },
+          "version": {
+            "type": "integer",
+            "format": "int64",
+            "description": "The item's current `version` (≥ 1) for optimistic locking."
+          },
+          "title": {
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "New title, at most 512 characters; trimmed and must not be blank. `null` or omitted keeps the current title.",
+            "maxLength": 512
           },
-          "priority": {
-            "description": "New client-defined priority (max 64 characters).",
-            "maxLength": 64,
+          "description": {
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "New description, at most 65,535 characters; `\"\"` clears it. `null` or omitted keeps the current value.",
+            "maxLength": 65535
           },
           "status": {
-            "description": "New status. One of `open`, `in_progress`, `done`, `cancelled`.",
+            "type": [
+              "string",
+              "null"
+            ],
             "enum": [
               "open",
               "in_progress",
               "done",
-              "cancelled"
+              "cancelled",
+              null
             ],
-            "maxLength": 64,
-            "type": [
-              "string",
-              "null"
-            ]
+            "description": "New status. `null` or omitted keeps the current status.\n- `open`: not started.\n- `in_progress`: being worked on.\n- `done`: finished.\n- `cancelled`: no longer needed."
           },
-          "title": {
-            "description": "New title (max 512 characters).",
-            "maxLength": 512,
+          "priority": {
             "type": [
               "string",
               "null"
-            ]
-          },
-          "version": {
-            "description": "Current item version for optimistic locking. Must match the stored version.",
-            "format": "int64",
-            "type": "integer"
-          },
-          "work_item_id": {
-            "description": "Work item ID (opaque string, max 128 characters).",
-            "maxLength": 128,
-            "type": "string"
+            ],
+            "description": "New free-form priority, at most 64 characters; `\"\"` clears it. `null` or omitted keeps the current value.",
+            "maxLength": 64
           }
-        },
-        "required": [
-          "work_item_id",
-          "version"
-        ],
-        "type": "object"
+        }
       },
       "UpsertPostMortemTemplateRequest": {
+        "type": "object",
         "description": "Parameters for creating or updating a post-mortem template.",
+        "required": [
+          "name",
+          "content"
+        ],
         "properties": {
-          "content": {
-            "description": "BlockNote JSON template content.",
-            "type": "string"
-          },
-          "content_markdown": {
-            "description": "Markdown version of the template content.",
-            "type": "string"
+          "template_id": {
+            "type": "string",
+            "description": "ID of the custom template to replace. Omit it to create a new template (the server generates the ID)."
           },
-          "description": {
-            "description": "Template description.",
-            "type": "string"
+          "team_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Managing team ID. Required when creating; the team must exist. On update, a different team ID moves the template; omit it or send 0 to keep the current team."
           },
           "name": {
-            "description": "Template name.",
-            "type": "string"
+            "type": "string",
+            "description": "Template name shown in the console."
           },
-          "team_id": {
-            "description": "Managing team ID. Required when creating a custom template.",
-            "format": "int64",
-            "type": "integer"
+          "description": {
+            "type": "string",
+            "description": "Template description; empty when omitted."
           },
-          "template_id": {
-            "description": "Template ID. Omit to create a new template; provide it to update an existing template.",
-            "type": "string"
+          "content": {
+            "type": "string",
+            "description": "Template body as BlockNote editor JSON (an array of blocks), serialized as a string. New reports created from this template start from this body."
+          },
+          "content_markdown": {
+            "type": "string",
+            "description": "Markdown version of the body, used as the outline when AI generates a report. Empty when omitted."
           }
-        },
-        "required": [
-          "name",
-          "content"
-        ],
-        "type": "object"
+        }
       },
       "UpsertRouteRequest": {
-        "description": "Parameters for creating or updating the routing rule of an integration. The handler creates a rule when none exists for the integration, otherwise it overwrites the existing one. At least one of `cases` or `default` must be provided.",
+        "type": "object",
+        "description": "Creates the integration's routing rule, or replaces it entirely when one exists. At least one of `cases` or `default` must be provided.",
+        "required": [
+          "integration_id"
+        ],
         "properties": {
+          "integration_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Shared integration ID; obtain it from `POST /integration/list`. Channel-exclusive integrations are rejected with `InvalidParameter`."
+          },
           "cases": {
-            "description": "Ordered list of case branches. Cases are evaluated top to bottom.",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/RouteCase"
             },
-            "type": "array"
-          },
-          "default": {
-            "$ref": "#/components/schemas/RouteDefault",
-            "description": "Fallback branch used when no case matches."
-          },
-          "integration_id": {
-            "description": "Integration the rule belongs to.",
-            "format": "int64",
-            "type": "integer"
+            "description": "Ordered list of case branches. Cases are evaluated top to bottom."
           },
           "sections": {
-            "description": "Optional sections that group consecutive cases for display.",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/RouteSection"
             },
-            "type": "array"
+            "description": "Optional sections that group consecutive cases for display."
+          },
+          "default": {
+            "$ref": "#/components/schemas/RouteDefault",
+            "description": "Fallback branch used when no case yields a channel. Omitting it removes any existing default branch."
           },
           "version": {
-            "description": "Reserved for optimistic concurrency control; currently ignored — the server increments `version` automatically on every upsert.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Ignored. The server increments `version` on every upsert and does not compare it with this value."
           }
-        },
-        "required": [
-          "integration_id"
-        ],
-        "type": "object"
+        }
       },
       "UpsertStatusPageComponentRequest": {
+        "type": "object",
         "description": "Parameters for creating or updating one or more service components on a status page.",
+        "required": [
+          "page_id",
+          "components"
+        ],
         "properties": {
+          "page_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Status page ID; obtain it from `GET /status-page/list`."
+          },
           "components": {
+            "type": "array",
             "description": "Components to create or update.",
             "items": {
+              "type": "object",
+              "required": [
+                "name"
+              ],
               "properties": {
-                "available_since_seconds": {
-                  "description": "Time the component became (or becomes) available, in Unix seconds. On create, defaults to the current time; on update, replaces the stored value.",
-                  "format": "int64",
-                  "type": "integer"
-                },
                 "component_id": {
-                  "description": "Component ID. Omit to create a new component; supply to update an existing one.",
-                  "type": "string"
+                  "type": "string",
+                  "description": "Component ID. Omit to create a new component; supply to update an existing one."
+                },
+                "section_id": {
+                  "type": "string",
+                  "description": "Parent section ID; must be an existing section of the page. Omit to place the component at the top level (on update too)."
+                },
+                "name": {
+                  "type": "string",
+                  "description": "Component display name; must be unique within the page."
                 },
                 "description": {
-                  "description": "Component description.",
-                  "type": "string"
+                  "type": "string",
+                  "description": "Component description."
                 },
-                "hide_all": {
-                  "description": "When true, the component is hidden entirely from summary endpoints.",
-                  "type": "boolean"
+                "order_id": {
+                  "type": "integer",
+                  "format": "int64",
+                  "description": "Display order within its section; on update an omitted value resets to 0."
                 },
                 "hide_uptime": {
-                  "description": "When true, uptime data is hidden from summary responses.",
-                  "type": "boolean"
+                  "type": "boolean",
+                  "description": "When true, uptime data is hidden from summary responses."
                 },
-                "name": {
-                  "description": "Component display name.",
-                  "type": "string"
+                "hide_all": {
+                  "type": "boolean",
+                  "description": "When true, the component is hidden entirely from summary endpoints."
                 },
-                "order_id": {
-                  "description": "Display order within its section.",
+                "available_since_seconds": {
+                  "type": "integer",
                   "format": "int64",
-                  "type": "integer"
-                },
-                "section_id": {
-                  "description": "Parent section ID. Omit to place the component at the top level.",
-                  "type": "string"
+                  "description": "Time the component became available, in Unix seconds, used as the start of its uptime history. Applies only on create, defaulting to the current time; ignored on update."
                 }
-              },
-              "required": [
-                "name"
-              ],
-              "type": "object"
+              }
             },
-            "minItems": 1,
-            "type": "array"
-          },
-          "page_id": {
-            "description": "Status page ID; obtain it from `GET /status-page/list`.",
-            "format": "int64",
-            "type": "integer"
+            "minItems": 1
           }
-        },
-        "required": [
-          "page_id",
-          "components"
-        ],
-        "type": "object"
+        }
       },
       "UpsertStatusPageComponentResponse": {
         "description": "Result of upserting status page components.",
@@ -28018,57 +29069,57 @@
         "type": "object"
       },
       "UpsertStatusPageSectionRequest": {
+        "type": "object",
         "description": "Parameters for creating or updating one or more sections on a status page.",
+        "required": [
+          "page_id",
+          "sections"
+        ],
         "properties": {
           "page_id": {
-            "description": "Status page ID; obtain it from `GET /status-page/list`.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Status page ID; obtain it from `GET /status-page/list`."
           },
           "sections": {
+            "type": "array",
             "description": "Sections to create or update.",
             "items": {
+              "type": "object",
+              "required": [
+                "name"
+              ],
               "properties": {
-                "description": {
-                  "description": "Section description.",
-                  "type": "string"
-                },
-                "hide_all": {
-                  "description": "When true, the entire section is hidden from summary endpoints.",
-                  "type": "boolean"
-                },
-                "hide_uptime": {
-                  "description": "When true, uptime data for all components in this section is hidden.",
-                  "type": "boolean"
+                "section_id": {
+                  "type": "string",
+                  "description": "Section ID. Omit to create a new section; supply to update an existing one."
                 },
                 "name": {
-                  "description": "Section display name.",
-                  "type": "string"
+                  "type": "string",
+                  "description": "Section display name; must be unique within the page."
+                },
+                "description": {
+                  "type": "string",
+                  "description": "Section description."
                 },
                 "order_id": {
-                  "description": "Display order.",
+                  "type": "integer",
                   "format": "int64",
-                  "type": "integer"
+                  "description": "Display order of the section; on update an omitted value resets to 0."
                 },
-                "section_id": {
-                  "description": "Section ID. Omit to create a new section; supply to update an existing one.",
-                  "type": "string"
+                "hide_uptime": {
+                  "type": "boolean",
+                  "description": "When true, uptime data for all components in this section is hidden."
+                },
+                "hide_all": {
+                  "type": "boolean",
+                  "description": "When true, the entire section is hidden from summary endpoints."
                 }
-              },
-              "required": [
-                "name"
-              ],
-              "type": "object"
+              }
             },
-            "minItems": 1,
-            "type": "array"
+            "minItems": 1
           }
-        },
-        "required": [
-          "page_id",
-          "sections"
-        ],
-        "type": "object"
+        }
       },
       "UpsertStatusPageSectionResponse": {
         "description": "Result of upserting status page sections.",
@@ -28154,130 +29205,140 @@
         "type": "object"
       },
       "WarRoom": {
-        "description": "Live war room details fetched from the IM side. Returns an empty object if the group was deleted externally.",
+        "type": "object",
+        "description": "War room group details read from the IM platform. When the IM lookup fails (for example, the group was dissolved outside Flashduty), all fields are empty strings.",
+        "required": [
+          "chat_id",
+          "chat_name",
+          "share_link"
+        ],
         "properties": {
           "chat_id": {
-            "description": "Chat/group ID on the IM side.",
-            "type": "string"
+            "type": "string",
+            "description": "Chat/group ID on the IM side."
           },
           "chat_name": {
-            "description": "Chat/group display name.",
-            "type": "string"
+            "type": "string",
+            "description": "Chat/group display name."
           },
           "share_link": {
-            "description": "Join link for the war room, if provided by the IM.",
-            "type": "string"
+            "type": "string",
+            "description": "Join link for the war room, if provided by the IM."
           }
-        },
-        "required": [
-          "chat_id",
-          "chat_name",
-          "share_link"
-        ],
-        "type": "object"
+        }
       },
       "WarRoomDataSourceItem": {
-        "description": "An IM integration (data source) entry.",
+        "type": "object",
         "properties": {
-          "account_id": {
-            "description": "Account this integration belongs to.",
-            "format": "int64",
-            "type": "integer"
-          },
-          "category": {
-            "description": "Plugin category; `im` for the IM integrations returned here.",
-            "type": "string"
-          },
-          "created_at": {
-            "description": "Unix timestamp in seconds when the integration was created.",
-            "format": "int64",
-            "type": "integer"
-          },
-          "creator_id": {
-            "description": "Person who created the integration.",
-            "format": "int64",
-            "type": "integer"
-          },
           "data_source_id": {
+            "type": "integer",
             "description": "Integration ID.",
-            "format": "int64",
-            "type": "integer"
-          },
-          "description": {
-            "description": "Integration description.",
-            "type": "string"
+            "format": "int64"
           },
-          "exclusive_data_source_id": {
-            "description": "Legacy exclusive-integration linkage; deprecated.",
-            "format": "int64",
-            "type": "integer"
-          },
-          "integration_id": {
-            "description": "Integration ID, alias of data_source_id.",
-            "format": "int64",
-            "type": "integer"
+          "account_id": {
+            "type": "integer",
+            "description": "Account this integration belongs to.",
+            "format": "int64"
           },
-          "integration_key": {
-            "description": "Push key used by alert sources to send to this integration.",
-            "type": "string"
+          "team_id": {
+            "type": "integer",
+            "description": "Team that owns this integration.",
+            "format": "int64"
           },
-          "last_time": {
-            "description": "Unix timestamp in seconds of the most recent activity in this datasource. Always `0` — this endpoint does not populate the field.",
-            "format": "int64",
-            "type": "integer"
+          "plugin_id": {
+            "type": "integer",
+            "description": "Plugin ID backing this integration.",
+            "format": "int64"
           },
           "name": {
-            "description": "Integration name.",
-            "type": "string"
+            "type": "string",
+            "description": "Integration name."
           },
-          "no_editable": {
-            "description": "Whether the integration is read-only.",
-            "type": "boolean"
+          "status": {
+            "type": "string",
+            "description": "Integration status: `enabled` or `disabled`. Deleted integrations are never returned.",
+            "enum": [
+              "enabled",
+              "disabled"
+            ]
           },
-          "plugin_id": {
-            "description": "Plugin ID backing this integration.",
-            "format": "int64",
-            "type": "integer"
+          "category": {
+            "type": "string",
+            "description": "Plugin category. Always `im`, because this endpoint returns only IM integrations.",
+            "enum": [
+              "im"
+            ]
           },
           "plugin_type": {
-            "description": "Plugin type identifier of the IM integration, for example `feishu_app`, `dingtalk_app`, `wecom_app`, `slack_app`, or `teams_app`.",
-            "type": "string"
+            "type": "string",
+            "description": "IM integration type: `feishu_app` Feishu (Lark), `dingtalk_app` DingTalk, `wecom_app` WeCom, `slack_app` Slack, `teams_app` Microsoft Teams.",
+            "enum": [
+              "feishu_app",
+              "dingtalk_app",
+              "wecom_app",
+              "slack_app",
+              "teams_app"
+            ]
           },
           "plugin_type_name": {
-            "description": "Localized display name of the integration plugin type.",
-            "type": "string"
+            "type": "string",
+            "description": "Localized display name of the integration plugin type."
+          },
+          "description": {
+            "type": "string",
+            "description": "Integration description."
+          },
+          "integration_key": {
+            "type": "string",
+            "description": "Push key used by alert sources to send to this integration."
           },
           "ref_id": {
-            "description": "External reference ID of the integration.",
-            "type": "string"
+            "type": "string",
+            "description": "External reference ID of the integration."
           },
           "settings": {
+            "type": "object",
             "additionalProperties": true,
-            "description": "Plugin-specific configuration of the integration.",
-            "type": "object"
+            "description": "Plugin-specific configuration of the integration; includes `war_room_enabled: true`. Secret values are masked as `******`."
           },
-          "status": {
-            "description": "Integration status: `enabled` or `disabled`. Deleted integrations are never returned.",
-            "enum": [
-              "enabled",
-              "disabled"
-            ],
-            "type": "string"
+          "no_editable": {
+            "type": "boolean",
+            "description": "Whether the integration is read-only."
           },
-          "team_id": {
-            "description": "Team that owns this integration.",
+          "creator_id": {
+            "type": "integer",
+            "description": "Person who created the integration.",
+            "format": "int64"
+          },
+          "updated_by": {
+            "type": "integer",
+            "description": "Person who last updated the integration.",
+            "format": "int64"
+          },
+          "created_at": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Unix timestamp in seconds when the integration was created."
           },
           "updated_at": {
-            "description": "Unix timestamp in seconds when the integration was last updated.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Unix timestamp in seconds when the integration was last updated."
           },
-          "updated_by": {
-            "description": "Person who last updated the integration.",
+          "last_time": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Unix timestamp in seconds of the most recent activity in this datasource. Always `0` — this endpoint does not populate the field."
+          },
+          "exclusive_data_source_id": {
+            "type": "integer",
+            "description": "Deprecated; always `0` in this response.",
+            "format": "int64"
+          },
+          "integration_id": {
+            "type": "integer",
+            "description": "Integration ID; same value as `data_source_id`.",
+            "format": "int64"
           }
         },
         "required": [
@@ -28303,51 +29364,69 @@
           "exclusive_data_source_id",
           "integration_id"
         ],
-        "type": "object"
+        "description": "An IM integration (data source) entry."
       },
       "WarRoomItem": {
+        "type": "object",
         "description": "Stored war room record.",
+        "required": [
+          "account_id",
+          "integration_id",
+          "created_by",
+          "chat_id",
+          "incident_id",
+          "status",
+          "created_at",
+          "plugin_type",
+          "chat_name"
+        ],
         "properties": {
           "account_id": {
-            "description": "Account ID.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
-          },
-          "chat_id": {
-            "description": "Chat/group ID on the IM side.",
-            "type": "string"
+            "description": "ID of the account that owns this record; the same for every record returned to one `app_key`."
           },
-          "created_at": {
-            "description": "Creation timestamp (seconds).",
+          "integration_id": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "IM integration ID."
           },
           "created_by": {
-            "description": "Member ID that created the war room.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Member ID that created the war room."
+          },
+          "chat_id": {
+            "type": "string",
+            "description": "Chat/group ID on the IM side."
           },
           "incident_id": {
-            "description": "Associated incident ID (MongoDB ObjectID).",
+            "type": "string",
             "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
+            "description": "Associated incident ID (MongoDB ObjectID)."
           },
-          "integration_id": {
-            "description": "IM integration ID.",
+          "status": {
+            "type": "string",
+            "description": "Record status. Always `enabled` in this list, because deleted war rooms are not returned.",
+            "enum": [
+              "enabled"
+            ]
+          },
+          "created_at": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Unix timestamp (seconds) when the war room was created."
           },
           "plugin_type": {
-            "description": "IM plugin type (e.g. `feishu`, `dingtalk`, `wecom`, `slack`).",
-            "type": "string"
-          },
-          "status": {
-            "description": "War room record status: `enabled` active, `deleted` disbanded.",
+            "type": "string",
+            "description": "Plugin type of the IM integration: `feishu_app` (Feishu), `dingtalk_app` (DingTalk), `wecom_app` (WeCom), or `slack_app` (Slack). Empty string when the integration no longer exists.",
             "enum": [
-              "enabled",
-              "deleted"
-            ],
-            "type": "string"
+              "feishu_app",
+              "dingtalk_app",
+              "wecom_app",
+              "slack_app",
+              ""
+            ]
           },
           "chat_name": {
             "type": "string",
@@ -28357,161 +29436,175 @@
             "type": "boolean",
             "description": "True when the IM integration behind this war room is disabled or no longer exists."
           }
-        },
-        "required": [
-          "account_id",
-          "integration_id",
-          "created_by",
-          "chat_id",
-          "incident_id",
-          "status",
-          "created_at",
-          "plugin_type",
-          "chat_name"
-        ],
-        "type": "object"
+        }
       },
       "WarRoomPersonItem": {
+        "type": "object",
         "properties": {
           "account_id": {
+            "type": "integer",
             "description": "Account this person belongs to.",
-            "format": "int64",
-            "type": "integer"
+            "format": "int64"
           },
-          "as": {
-            "description": "Role the person holds in the related context.",
-            "type": "string"
+          "person_id": {
+            "type": "integer",
+            "description": "Person ID: a member ID, or the account ID when the person is the account owner (`as` = `account`).",
+            "format": "int64"
+          },
+          "person_name": {
+            "type": "string",
+            "description": "Display name of the person."
           },
           "avatar": {
-            "description": "URL of the person's avatar image.",
-            "type": "string"
+            "type": "string",
+            "description": "URL of the person's avatar image."
           },
           "email": {
-            "description": "Email address of the person.",
-            "type": "string"
-          },
-          "locale": {
-            "description": "Preferred language locale of the person.",
-            "type": "string"
-          },
-          "person_id": {
-            "description": "Person ID.",
-            "format": "int64",
-            "type": "integer"
-          },
-          "person_name": {
-            "description": "Display name of the person.",
-            "type": "string"
+            "type": "string",
+            "description": "Email address; omitted when the member has not verified it."
           },
           "phone": {
-            "description": "Phone number of the person.",
-            "type": "string"
+            "type": "string",
+            "description": "Phone number; omitted when the member has not verified it."
           },
-          "status": {
-            "description": "Current status of the person.",
-            "type": "string"
+          "locale": {
+            "type": "string",
+            "description": "Preferred language, e.g. `zh-CN` or `en-US`."
           },
           "time_zone": {
-            "description": "Time zone of the person.",
-            "type": "string"
-          }
-        },
-        "required": [
+            "type": "string",
+            "description": "IANA time zone name, e.g. `Asia/Shanghai`."
+          },
+          "as": {
+            "type": "string",
+            "enum": [
+              "account",
+              "member"
+            ],
+            "description": "Identity type of the person.\n- `account`: the account owner.\n- `member`: a regular member of the account."
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "enabled",
+              "pending",
+              "deleted"
+            ],
+            "description": "Membership status.\n- `enabled`: active.\n- `pending`: invited but has not joined yet.\n- `deleted`: removed from the account."
+          }
+        },
+        "required": [
           "account_id",
           "person_id"
-        ],
-        "type": "object"
+        ]
       },
       "WebhookHistoryDetail": {
+        "type": "object",
         "description": "Full detail for a webhook delivery attempt. Extends `WebhookHistoryItem` with human-friendly reference metadata resolved at query time. When no matching record exists, `data` is an empty object.",
+        "required": [
+          "integration_id",
+          "event_id",
+          "webhook_type",
+          "event_type",
+          "endpoint",
+          "attempt",
+          "duration",
+          "status",
+          "status_code",
+          "event_time"
+        ],
         "properties": {
-          "attempt": {
-            "description": "Attempt sequence number.",
-            "type": "integer"
-          },
-          "channel_id": {
-            "description": "Channel ID when applicable.",
+          "integration_id": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
-          },
-          "channel_name": {
-            "description": "Name of the associated channel, resolved at query time.",
-            "type": "string"
-          },
-          "duration": {
-            "description": "Total elapsed time of the attempt in milliseconds.",
-            "type": "integer"
-          },
-          "endpoint": {
-            "description": "Destination URL.",
-            "type": "string"
-          },
-          "error_message": {
-            "description": "Error message when delivery failed.",
-            "type": "string"
+            "description": "ID of the webhook integration that sent the request."
           },
           "event_id": {
-            "description": "Event ID.",
-            "type": "string"
+            "type": "string",
+            "description": "ID of this delivery record: the delivery date (`YYYYMMDD`) followed by a random suffix. Pass it to `POST /webhook/history/detail`."
           },
-          "event_time": {
-            "description": "Event time formatted as `YYYY-MM-DD HH:MM:SS.ffffff`.",
-            "type": "string"
+          "webhook_type": {
+            "type": "string",
+            "description": "Source object kind: `incident` or `alert`.",
+            "enum": [
+              "incident",
+              "alert"
+            ]
           },
           "event_type": {
-            "description": "Event type code. `i_*` values are incident events (for example `i_new` = incident created); `a_*` values are alert events (for example `a_new` = alert triggered).",
-            "type": "string"
+            "type": "string",
+            "description": "Event type code. `i_*` values are incident events (for example `i_new` = incident created); `a_*` values are alert events (for example `a_new` = alert triggered)."
           },
-          "integration_id": {
-            "description": "Integration ID.",
+          "channel_id": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Channel ID when applicable."
           },
           "ref_id": {
-            "description": "Source object ID.",
-            "type": "string"
+            "type": "string",
+            "description": "Source object ID."
           },
-          "ref_title": {
-            "description": "Title of the source incident or alert, resolved at query time.",
-            "type": "string"
+          "request_headers": {
+            "type": "string",
+            "description": "Serialized outbound request headers."
           },
           "request_body": {
-            "description": "Outbound request body payload.",
-            "type": "string"
+            "type": "string",
+            "description": "JSON payload sent to the endpoint, truncated to the stored size limit."
           },
-          "request_headers": {
-            "description": "Serialized outbound request headers.",
-            "type": "string"
+          "endpoint": {
+            "type": "string",
+            "description": "Destination URL."
           },
-          "response_body": {
-            "description": "Response body.",
-            "type": "string"
+          "attempt": {
+            "type": "integer",
+            "description": "Number of HTTP tries made for this delivery; retries happen only on connection errors."
           },
-          "response_headers": {
-            "description": "Serialized response headers.",
-            "type": "string"
+          "duration": {
+            "type": "integer",
+            "description": "Total time of the delivery including retries, in milliseconds."
           },
           "status": {
-            "description": "Delivery outcome.",
+            "type": "string",
             "enum": [
               "success",
               "failed"
             ],
-            "type": "string"
+            "description": "Delivery outcome: `success` when the endpoint answered HTTP 200; `failed` on a connection error or any other status code."
           },
           "status_code": {
-            "description": "HTTP status code.",
-            "type": "integer"
+            "type": "integer",
+            "description": "HTTP status code returned by the endpoint; `0` when no response was received."
           },
-          "webhook_type": {
-            "description": "Source object kind: `incident` or `alert`.",
-            "enum": [
-              "incident",
-              "alert"
-            ],
-            "type": "string"
+          "error_message": {
+            "type": "string",
+            "description": "Error text when the delivery failed (connection error or unexpected status code), truncated. Omitted on success."
+          },
+          "response_headers": {
+            "type": "string",
+            "description": "Serialized response headers."
+          },
+          "response_body": {
+            "type": "string",
+            "description": "Body returned by the endpoint, truncated to the stored size limit. Omitted when empty or when no response was received."
+          },
+          "event_time": {
+            "type": "string",
+            "description": "Event time formatted as `YYYY-MM-DD HH:MM:SS.ffffff`."
+          },
+          "ref_title": {
+            "type": "string",
+            "description": "Title of the source incident or alert, resolved at query time."
+          },
+          "channel_name": {
+            "type": "string",
+            "description": "Name of the associated channel, resolved at query time."
           }
-        },
+        }
+      },
+      "WebhookHistoryItem": {
+        "type": "object",
+        "description": "A single webhook delivery attempt. Fields with `omitempty` are absent when zero-valued.",
         "required": [
           "integration_id",
           "event_id",
@@ -28524,103 +29617,86 @@
           "status_code",
           "event_time"
         ],
-        "type": "object"
-      },
-      "WebhookHistoryItem": {
-        "description": "A single webhook delivery attempt. Fields with `omitempty` are absent when zero-valued.",
         "properties": {
-          "attempt": {
-            "description": "Attempt sequence number.",
-            "type": "integer"
-          },
-          "channel_id": {
-            "description": "Channel ID associated with the event, when applicable.",
+          "integration_id": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
-          },
-          "duration": {
-            "description": "Total elapsed time of the attempt in milliseconds.",
-            "type": "integer"
-          },
-          "endpoint": {
-            "description": "Destination URL.",
-            "type": "string"
-          },
-          "error_message": {
-            "description": "Error message when delivery failed.",
-            "type": "string"
+            "description": "ID of the webhook integration that sent the request."
           },
           "event_id": {
-            "description": "Unique event identifier for the delivery attempt.",
-            "type": "string"
+            "type": "string",
+            "description": "ID of this delivery record: the delivery date (`YYYYMMDD`) followed by a random suffix. Pass it to `POST /webhook/history/detail`."
           },
-          "event_time": {
-            "description": "Event time formatted as `YYYY-MM-DD HH:MM:SS.ffffff`.",
-            "type": "string"
+          "webhook_type": {
+            "type": "string",
+            "description": "Source object kind: `incident` or `alert`.",
+            "enum": [
+              "incident",
+              "alert"
+            ]
           },
           "event_type": {
-            "description": "Event type code. `i_*` values are incident events (for example `i_new` = incident created); `a_*` values are alert events (for example `a_new` = alert triggered).",
-            "type": "string"
+            "type": "string",
+            "description": "Event type code. `i_*` values are incident events (for example `i_new` = incident created); `a_*` values are alert events (for example `a_new` = alert triggered)."
           },
-          "integration_id": {
-            "description": "Integration ID that triggered the webhook.",
+          "channel_id": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Channel ID associated with the event, when applicable."
           },
           "ref_id": {
-            "description": "Source object ID (incident ID or alert ID).",
-            "type": "string"
+            "type": "string",
+            "description": "Source object ID (incident ID or alert ID)."
+          },
+          "request_headers": {
+            "type": "string",
+            "description": "Serialized outbound request headers."
           },
           "request_body": {
-            "description": "Outbound request body payload.",
-            "type": "string"
+            "type": "string",
+            "description": "JSON payload sent to the endpoint, truncated to the stored size limit."
           },
-          "request_headers": {
-            "description": "Serialized outbound request headers.",
-            "type": "string"
+          "endpoint": {
+            "type": "string",
+            "description": "Destination URL."
           },
-          "response_body": {
-            "description": "Response body returned by the destination.",
-            "type": "string"
+          "attempt": {
+            "type": "integer",
+            "description": "Number of HTTP tries made for this delivery; retries happen only on connection errors."
           },
-          "response_headers": {
-            "description": "Serialized response headers from the destination.",
-            "type": "string"
+          "duration": {
+            "type": "integer",
+            "description": "Total time of the delivery including retries, in milliseconds."
           },
           "status": {
-            "description": "Delivery outcome.",
+            "type": "string",
             "enum": [
               "success",
               "failed"
             ],
-            "type": "string"
+            "description": "Delivery outcome: `success` when the endpoint answered HTTP 200; `failed` on a connection error or any other status code."
           },
           "status_code": {
-            "description": "HTTP status code returned by the destination.",
-            "type": "integer"
+            "type": "integer",
+            "description": "HTTP status code returned by the endpoint; `0` when no response was received."
           },
-          "webhook_type": {
-            "description": "Source object kind: `incident` or `alert`.",
-            "enum": [
-              "incident",
-              "alert"
-            ],
-            "type": "string"
+          "error_message": {
+            "type": "string",
+            "description": "Error text when the delivery failed (connection error or unexpected status code), truncated. Omitted on success."
+          },
+          "response_headers": {
+            "type": "string",
+            "description": "Serialized response headers from the destination."
+          },
+          "response_body": {
+            "type": "string",
+            "description": "Body returned by the endpoint, truncated to the stored size limit. Omitted when empty or when no response was received."
+          },
+          "event_time": {
+            "type": "string",
+            "description": "Event time formatted as `YYYY-MM-DD HH:MM:SS.ffffff`."
           }
-        },
-        "required": [
-          "integration_id",
-          "event_id",
-          "webhook_type",
-          "event_type",
-          "endpoint",
-          "attempt",
-          "duration",
-          "status",
-          "status_code",
-          "event_time"
-        ],
-        "type": "object"
+        }
       },
       "WorkItemAssignee": {
         "description": "One assignee on a work item.",
@@ -28645,165 +29721,165 @@
         "type": "object"
       },
       "WorkItemCreateResult": {
+        "type": "object",
         "description": "Result of creating a work item.",
+        "required": [
+          "item"
+        ],
         "properties": {
+          "item": {
+            "$ref": "#/components/schemas/WorkItemItem"
+          },
           "added_assignee_ids": {
-            "description": "Assignee member IDs that were newly added (and notified).",
+            "type": "array",
             "items": {
-              "format": "int64",
-              "type": "integer"
+              "type": "integer",
+              "format": "int64"
             },
-            "type": "array"
+            "description": "Member IDs of the person assignees added by this call (and notified); AI SRE is not included. Omitted when none."
           },
           "idempotent_replay": {
-            "description": "True when the call replayed an earlier request with the same idempotency key and no new item was created.",
-            "type": "boolean"
-          },
-          "item": {
-            "$ref": "#/components/schemas/WorkItemItem"
+            "type": "boolean",
+            "description": "True when the call replayed an earlier request with the same idempotency key and no new item was created."
           }
-        },
-        "required": [
-          "item"
-        ],
-        "type": "object"
+        }
       },
       "WorkItemItem": {
+        "type": "object",
         "description": "A structured incident work item (action or post-mortem follow-up) with its assignees.",
+        "required": [
+          "work_item_id",
+          "item_type",
+          "incident_id",
+          "title",
+          "status",
+          "source_kind",
+          "version",
+          "assignee_ids",
+          "assignees",
+          "created_by",
+          "updated_by",
+          "created_at_seconds",
+          "updated_at_seconds"
+        ],
         "properties": {
-          "agent_session_id": {
-            "description": "ID of the AI SRE session executing this item. Omitted when no session is recorded.",
-            "type": "string"
+          "work_item_id": {
+            "type": "string",
+            "maxLength": 128,
+            "description": "Work item ID (opaque string, max 128 characters)."
           },
-          "agent_session_venue": {
-            "description": "Where that AI SRE session runs: `web` or `im`. Omitted when no session is recorded.",
+          "item_type": {
+            "type": "string",
             "enum": [
-              "web",
-              "im"
+              "action",
+              "follow_up"
             ],
-            "type": "string"
+            "description": "Work item type.\n- `action`: a to-do on an incident that is not closed yet.\n- `follow_up`: a post-mortem follow-up, created on a closed incident or converted from an action."
           },
-          "assignee_ids": {
-            "description": "Member IDs of the current person assignees. AI SRE is not included. Never null; an empty array means no person assignee.",
-            "items": {
-              "format": "int64",
-              "type": "integer"
-            },
-            "type": "array"
-          },
-          "assignees": {
-            "description": "Current assignees. Each entry is `{type, id?}`. `type` is `person` or `ai_sre`; an `ai_sre` entry omits `id`. Never null; an empty array means unassigned. `assignee_ids` is the person-only subset of this list.",
-            "items": {
-              "$ref": "#/components/schemas/WorkItemAssignee"
-            },
-            "type": "array"
-          },
-          "converted_at_seconds": {
-            "description": "Conversion time as a Unix timestamp in seconds. Present only after conversion.",
-            "format": "int64",
-            "type": "integer"
-          },
-          "converted_by": {
-            "description": "Member ID of the operator who converted the action into a follow-up. Present only after conversion.",
-            "format": "int64",
-            "type": "integer"
+          "incident_id": {
+            "type": "string",
+            "pattern": "^[0-9a-fA-F]{24}$",
+            "description": "Incident ID (MongoDB ObjectID) the item is anchored to."
           },
-          "created_at_seconds": {
-            "description": "Creation time as a Unix timestamp in seconds.",
-            "format": "int64",
-            "type": "integer"
+          "post_mortem_id": {
+            "type": "string",
+            "description": "Post-mortem ID (32-character hex string). Present only on follow-ups bound to a report; omitted otherwise."
           },
-          "created_by": {
-            "description": "Member ID of the creator.",
-            "format": "int64",
-            "type": "integer"
+          "title": {
+            "type": "string",
+            "maxLength": 512,
+            "description": "Item title (max 512 characters)."
           },
           "description": {
-            "description": "Optional longer description (max 65,535 characters).",
+            "type": "string",
             "maxLength": 65535,
-            "type": "string"
-          },
-          "incident_id": {
-            "description": "Incident ID (MongoDB ObjectID) the item is anchored to.",
-            "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
+            "description": "Optional longer description (max 65,535 characters)."
           },
-          "item_type": {
-            "description": "`action` for an item anchored to an active incident; `follow_up` for a post-mortem follow-up.",
-            "enum": [
-              "action",
-              "follow_up"
-            ],
-            "type": "string"
-          },
-          "legacy_source_id": {
-            "description": "Original identifier of the legacy follow-up this item was migrated from. Present only when `source_kind` is `legacy_follow_up`.",
-            "type": "string"
-          },
-          "post_mortem_id": {
-            "description": "Post-mortem ID (32-character hex string). Present on follow-up items once bound to a post-mortem.",
-            "type": "string"
+          "status": {
+            "type": "string",
+            "maxLength": 64,
+            "description": "Item status: `open` (not started), `in_progress` (being worked on), `done` (finished) or `cancelled` (no longer needed). `done` and `cancelled` count as finished. Older items may still hold other free text, which counts as unfinished."
           },
           "priority": {
-            "description": "Optional client-defined priority (max 64 characters).",
+            "type": "string",
             "maxLength": 64,
-            "type": "string"
+            "description": "Free-form priority, at most 64 characters; omitted when empty. The console uses `high`, `medium` and `low`, but any string set through the API is returned as-is."
           },
           "source_kind": {
-            "description": "`native` for items created through this API; `legacy_follow_up` for items migrated from legacy post-mortem follow-ups.",
+            "type": "string",
             "enum": [
               "native",
               "legacy_follow_up"
             ],
-            "type": "string"
+            "description": "`native` for items created through this API; `legacy_follow_up` for items migrated from legacy post-mortem follow-ups."
           },
-          "status": {
-            "description": "Client-defined status (max 64 characters). There is no fixed state machine.",
-            "maxLength": 64,
+          "legacy_source_id": {
+            "type": "string",
+            "description": "Original identifier of the legacy follow-up this item was migrated from. Present only when `source_kind` is `legacy_follow_up`."
+          },
+          "version": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Optimistic-locking version, incremented on every mutation."
+          },
+          "assignee_ids": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "int64"
+            },
+            "description": "Member IDs of the current person assignees. AI SRE is not included. Never null; an empty array means no person assignee."
+          },
+          "assignees": {
+            "description": "Current assignees. Each entry is `{type, id?}`. `type` is `person` or `ai_sre`; an `ai_sre` entry omits `id`. Never null; an empty array means unassigned. `assignee_ids` is the person-only subset of this list.",
+            "items": {
+              "$ref": "#/components/schemas/WorkItemAssignee"
+            },
+            "type": "array"
+          },
+          "agent_session_id": {
+            "description": "ID of the AI SRE session executing this item. Omitted when no session is recorded.",
             "type": "string"
           },
-          "title": {
-            "description": "Item title (max 512 characters).",
-            "maxLength": 512,
+          "agent_session_venue": {
+            "description": "Where that AI SRE session runs: `web` or `im`. Omitted when no session is recorded.",
+            "enum": [
+              "web",
+              "im"
+            ],
             "type": "string"
           },
-          "updated_at_seconds": {
-            "description": "Last update time as a Unix timestamp in seconds.",
+          "created_by": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Member ID of the creator."
           },
           "updated_by": {
-            "description": "Member ID of the last updater.",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Member ID of the last updater."
           },
-          "version": {
-            "description": "Optimistic-locking version, incremented on every mutation.",
+          "converted_by": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "Member ID of the operator who converted the action into a follow-up. Present only after conversion."
           },
-          "work_item_id": {
-            "description": "Work item ID (opaque string, max 128 characters).",
-            "maxLength": 128,
-            "type": "string"
+          "converted_at_seconds": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Conversion time as a Unix timestamp in seconds. Present only after conversion."
+          },
+          "created_at_seconds": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Creation time as a Unix timestamp in seconds."
+          },
+          "updated_at_seconds": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Last update time as a Unix timestamp in seconds."
           }
-        },
-        "required": [
-          "work_item_id",
-          "item_type",
-          "incident_id",
-          "title",
-          "status",
-          "source_kind",
-          "version",
-          "assignee_ids",
-          "assignees",
-          "created_by",
-          "updated_by",
-          "created_at_seconds",
-          "updated_at_seconds"
-        ],
-        "type": "object"
+        }
       },
       "WorkItemListResult": {
         "description": "Cursor-paginated list of work items.",
@@ -28835,33 +29911,33 @@
         "type": "object"
       },
       "WorkItemMutationResult": {
-        "description": "Result of mutating a work item.",
+        "type": "object",
+        "description": "Result of mutating a work item. `item` is absent for delete.",
         "properties": {
+          "item": {
+            "$ref": "#/components/schemas/WorkItemItem"
+          },
           "added_assignee_ids": {
-            "description": "Assignee member IDs that were newly added (and notified).",
+            "type": "array",
             "items": {
-              "format": "int64",
-              "type": "integer"
+              "type": "integer",
+              "format": "int64"
             },
-            "type": "array"
-          },
-          "idempotent_replay": {
-            "description": "True when the call replayed an earlier request with the same idempotency key.",
-            "type": "boolean"
-          },
-          "item": {
-            "$ref": "#/components/schemas/WorkItemItem"
+            "description": "Member IDs of the person assignees added by this call (and notified); AI SRE is not included. Omitted when none."
           },
           "removed_assignee_ids": {
-            "description": "Assignee member IDs that were removed (never notified).",
+            "type": "array",
             "items": {
-              "format": "int64",
-              "type": "integer"
+              "type": "integer",
+              "format": "int64"
             },
-            "type": "array"
+            "description": "Member IDs of the person assignees removed by this call (never notified). Omitted when none."
+          },
+          "idempotent_replay": {
+            "type": "boolean",
+            "description": "True when the call replayed an earlier request with the same idempotency key."
           }
-        },
-        "type": "object"
+        }
       },
       "AlertRuleV2": {
         "type": "object",
@@ -28891,11 +29967,11 @@
             "additionalProperties": {
               "type": "string"
             },
-            "description": "Custom labels."
+            "description": "Custom labels added to every alert event of the rule. Keys are trimmed, must not be empty and must not start with `__alert_rule_` (reserved); values containing `{{` are rendered as templates when events are delivered; `job` and `instance` values are limited to 255 characters. The serialized object may not exceed 1024 characters."
           },
           "ds_type": {
             "type": "string",
-            "description": "Datasource type identifier (e.g. `prometheus`, `elasticsearch`)."
+            "description": "Datasource type the rule queries. When the rule is enabled it must be a type that supports alerting: `prometheus`, `elasticsearch`, `loki`, `clickhouse`, `mysql`, `oracle`, `postgres`, `sls`, `tencent_cls`, `victorialogs`."
           },
           "ds_list": {
             "type": "array",
@@ -28926,7 +30002,7 @@
           },
           "cron_pattern": {
             "type": "string",
-            "description": "Schedule expression: a 6-field cron (with seconds) or an `@every 30s` interval. Must not start with `CRON_TZ=` or `TZ=`; set the timezone in the `timezone` field instead."
+            "description": "Schedule expression: a 6-field cron with seconds (e.g. `0 * * * * *`), a descriptor such as `@hourly`, or `@every <duration>` with a whole number of seconds of at least `1s` (e.g. `@every 30s`). Must not start with `CRON_TZ=` or `TZ=`; set the timezone in the `timezone` field instead."
           },
           "timezone": {
             "type": "string",
@@ -28963,15 +30039,15 @@
                   "items": {
                     "type": "integer"
                   },
-                  "description": "Days of week (0=Sunday)."
+                  "description": "Days of week the window applies to, `0` = Sunday through `6` = Saturday; non-empty, no duplicates."
                 },
                 "stime": {
                   "type": "string",
-                  "description": "Start time, e.g. `09:00`."
+                  "description": "Start time in 24-hour `HH:MM` format, e.g. `09:00`."
                 },
                 "etime": {
                   "type": "string",
-                  "description": "End time, e.g. `18:00`."
+                  "description": "End time in 24-hour `HH:MM` format, e.g. `18:00`."
                 }
               }
             }
@@ -28994,7 +30070,7 @@
           },
           "description": {
             "type": "string",
-            "description": "Rule description, Markdown format."
+            "description": "Rule description; rendered as plain text or Markdown according to `description_type`."
           },
           "channel_ids": {
             "type": "array",
@@ -29007,12 +30083,12 @@
           "repeat_interval": {
             "type": "integer",
             "format": "int64",
-            "description": "Notification repeat interval in seconds. Values below 1 fall back to the default 3600."
+            "description": "Notification repeat interval in seconds. Values below 1 fall back to the default 3600; maximum 2147483647."
           },
           "repeat_total": {
             "type": "integer",
             "format": "int64",
-            "description": "Maximum number of repeat notifications. Values below 1 fall back to the default 3."
+            "description": "Maximum number of repeat notifications. Values below 1 fall back to the default 3; maximum 2147483647."
           },
           "investigation_targets": {
             "type": "array",
@@ -29020,7 +30096,7 @@
               "$ref": "#/components/schemas/InvestigationTarget"
             },
             "maxItems": 20,
-            "description": "Drill-down entries linked from the alert event detail page; at most 20 items, duplicates rejected. On update the field is presence-based: omit it to keep the current value, pass `[]` to clear.",
+            "description": "Drill-down entries linked from the alert event detail page; at most 20 items, duplicates rejected, and at most 32 KiB once serialized. On update the field is presence-based: omit it to keep the current value, pass `[]` to clear; `null` is rejected.",
             "x-flashduty-preserve-absence": true
           },
           "creator_id": {
@@ -29105,7 +30181,7 @@
           },
           "relate_queries": {
             "type": "array",
-            "description": "Optional auxiliary queries whose results attach to alert events as context. Each entry needs a unique `name` (not colliding with any query name) and a non-empty `expr`.",
+            "description": "Optional auxiliary queries whose results attach to alert events as context. Each entry needs a unique `name` (not colliding with any query name) and a non-empty `expr`. Always returned, as `[]` when there are none.",
             "items": {
               "type": "object",
               "properties": {
@@ -29424,7 +30500,7 @@
       },
       "DashboardQuery": {
         "type": "object",
-        "description": "Query payload shared by dashboards and drill-down entries.",
+        "description": "Query payload shared by dashboard panels and alert rule drill-down entries. Template syntax differs by context: dashboard panels use dashboard variables (`${name}`), drill-down entries use event labels (`{{ }}`).",
         "properties": {
           "mode": {
             "type": "string",
@@ -29433,18 +30509,18 @@
               "range",
               "window"
             ],
-            "description": "Evaluation mode: `instant` evaluates at a single timestamp, `range` evaluates a stepped series, `window` returns raw rows inside a time window."
+            "description": "Evaluation mode: `instant` = evaluate at a single timestamp; `range` = evaluate a stepped series over the time range; `window` = return raw rows inside the time range. Dashboard panels on Prometheus and Loki accept `instant` or `range` (Loki `logs` panels need `range`); MySQL panels need `window`."
           },
           "expr": {
             "type": "string",
-            "description": "Query expression in the target data source's language. May reference event labels through `{{ }}` templates."
+            "description": "Query expression in the datasource's language. In dashboard panels it may reference variables as `${name}`, `${name:raw}` (one value inserted as is) or `${name:regex}` (values joined as a regex alternation), or as `$name` in Prometheus and Loki; write `$${...}` for a literal. Without a formatter, multi-value or `all` variables and values inside `=~`/`!~` are inserted in regex form, so they cannot be used with `=` or `!=`. MySQL queries do not support variables. In drill-down entries the expression may reference event labels through `{{ }}` templates."
           },
           "args": {
             "type": "object",
             "additionalProperties": {
               "type": "string"
             },
-            "description": "Named query arguments; defaults to an empty object. Values are passed through verbatim and must not contain `{{ }}` templates."
+            "description": "Named query arguments; defaults to an empty object. In dashboard panels values may use `${name}` templates except for Loki and MySQL datasources. In drill-down entries keys and values must not contain `{{ }}` templates."
           },
           "min_step_seconds": {
             "type": [
@@ -29454,7 +30530,7 @@
             "format": "int64",
             "minimum": 1,
             "maximum": 9007199254740,
-            "description": "Minimum step, in seconds. Only accepted when `mode` is `range`, and must be greater than zero; omit or pass null to let the server decide."
+            "description": "Minimum step, in seconds; must be greater than zero. In drill-down entries it is only accepted when `mode` is `range`. Omit or pass null to let the server decide."
           }
         },
         "required": [
@@ -29571,7 +30647,7 @@
       },
       "DashboardDefinition": {
         "type": "object",
-        "description": "Complete dashboard payload stored as a portable `dashboard.v1` document. Unknown keys, duplicate keys, NaN/Inf, over-range numbers and trailing values are rejected; the serialized form must stay within 1 MiB.",
+        "description": "Complete dashboard payload stored as a portable `dashboard.v1` document. Unknown keys, duplicate keys, trailing values and nesting deeper than 32 levels are rejected, and the serialized form must stay within 1 MiB. Limits: 10 tabs, 10 sections per tab, 30 panels and 100 queries per tab, 100 panels and 300 queries per dashboard, 20 variables.",
         "properties": {
           "title": {
             "type": "string",
@@ -29603,7 +30679,7 @@
               "$ref": "#/components/schemas/DashboardVariable"
             },
             "maxItems": 20,
-            "description": "Dashboard variables, at most 20. Names must be unique within the definition and match the variable-name pattern."
+            "description": "Dashboard variables, at most 20, with unique names. Variables may reference other variables but not in a cycle."
           },
           "tabs": {
             "type": "array",
@@ -29612,7 +30688,7 @@
             },
             "minItems": 1,
             "maxItems": 10,
-            "description": "Tabs, 1–10. Every tab title is unique and every tab or section ID must be a canonical UUIDv7 used only once across the definition."
+            "description": "Tabs, 1–10. Every tab, section and panel `id` must be a canonical UUIDv7 used only once across the definition. Tab titles do not need to be unique."
           }
         },
         "required": [
@@ -29667,7 +30743,7 @@
             "type": "string",
             "minLength": 1,
             "maxLength": 189,
-            "description": "Tab title, 1–189 Unicode code points. Unique among tabs."
+            "description": "Tab title, 1–189 Unicode code points after trimming."
           },
           "description": {
             "type": "string",
@@ -29680,7 +30756,7 @@
               "$ref": "#/components/schemas/DashboardPanel"
             },
             "maxItems": 30,
-            "description": "Panels placed directly on the tab, at most 30."
+            "description": "Panels placed directly on the tab. A tab holds at most 30 panels in total, counting top panels and section panels, and at most 100 queries."
           },
           "sections": {
             "type": "array",
@@ -29728,7 +30804,7 @@
               "$ref": "#/components/schemas/DashboardPanel"
             },
             "maxItems": 30,
-            "description": "Panels in the section, at most 30."
+            "description": "Panels in the section; they count toward the tab's 30-panel limit."
           }
         },
         "required": [
@@ -29740,7 +30816,7 @@
       },
       "DashboardPanel": {
         "type": "object",
-        "description": "A single visualization. Panels must not overlap inside the same container; the 24-column grid is validated on save.",
+        "description": "A single visualization. `datasource_ref` is required for every kind except `text`, where it is forbidden. Panels must not overlap inside the same container; the 24-column grid is validated on save.",
         "properties": {
           "id": {
             "type": "string",
@@ -29835,17 +30911,18 @@
             "type": "integer",
             "format": "uint64",
             "minimum": 1,
-            "description": "Datasource ID. Required when `kind` is `fixed`, forbidden when `kind` is `variable`."
+            "description": "Datasource ID. Required when `kind` is `fixed`, forbidden when `kind` is `variable`.",
+            "maximum": 9007199254740991
           },
           "name": {
             "type": "string",
             "pattern": "^[A-Za-z_][A-Za-z0-9_]{0,63}$",
-            "description": "Datasource variable name. Required when `kind` is `variable`, forbidden when `kind` is `fixed`."
+            "description": "Name of a `datasource` variable in the same definition. Required when `kind` is `variable`, forbidden when `kind` is `fixed`."
           },
           "datasource_type": {
             "type": "string",
             "pattern": "^[a-z][a-z0-9_]{0,63}$",
-            "description": "Datasource type identifier, e.g. `prometheus` or `victorialogs`."
+            "description": "Datasource type identifier: lowercase letters, digits and underscores, starting with a letter. The set is open, so saving accepts any such value, but the dashboard runtime only runs `prometheus`, `mysql` and `loki` datasources; panels on other types fail when run. With `kind` = `variable` it must equal the referenced datasource variable's `datasource_type`."
           }
         },
         "required": [
@@ -29868,7 +30945,7 @@
           "legend_alias": {
             "type": "string",
             "maxLength": 1024,
-            "description": "Optional legend label; supports the same variable templates as `expr`."
+            "description": "Optional legend label, at most 1024 Unicode code points. The console replaces `{{label}}` with that series label's value (for example `{{env}} requests`); dashboard variables are not substituted here."
           }
         },
         "required": [
@@ -29912,7 +30989,7 @@
           "name": {
             "type": "string",
             "pattern": "^[A-Za-z_][A-Za-z0-9_]{0,63}$",
-            "description": "Variable name used in `{{ }}` templates, at most 64 characters. Names starting with `__` are reserved for built-in time variables."
+            "description": "Variable name, unique within the definition. Queries reference it as `${name}` (or `$name` inside Prometheus and Loki expressions). Names starting with `__` are reserved for the built-in variables `__interval`, `__rate_interval`, `__range` and `__auto`."
           },
           "label": {
             "type": "string",
@@ -29922,7 +30999,7 @@
           "datasource_type": {
             "type": "string",
             "pattern": "^[a-z][a-z0-9_]{0,63}$",
-            "description": "Datasource type the candidates are drawn from."
+            "description": "Type of datasource offered as candidates; candidates are the account's enabled datasources of this type. The set is open, so saving accepts any such value, but the dashboard runtime only runs `prometheus`, `mysql` and `loki` datasources; panels on other types fail when run. "
           },
           "name_patterns": {
             "type": "array",
@@ -29937,7 +31014,8 @@
           "default_datasource_id": {
             "type": "integer",
             "format": "uint64",
-            "description": "Default datasource ID. Without a usable default the runtime picks the first candidate by name, then ID."
+            "description": "Default datasource ID. Without a usable default the runtime picks the first candidate by name, then ID.",
+            "maximum": 9007199254740991
           }
         },
         "required": [
@@ -29960,7 +31038,7 @@
           "name": {
             "type": "string",
             "pattern": "^[A-Za-z_][A-Za-z0-9_]{0,63}$",
-            "description": "Variable name used in `{{ }}` templates, at most 64 characters. Names starting with `__` are reserved for built-in time variables."
+            "description": "Variable name, unique within the definition. Queries reference it as `${name}` (or `$name` inside Prometheus and Loki expressions). Names starting with `__` are reserved for the built-in variables `__interval`, `__rate_interval`, `__range` and `__auto`."
           },
           "label": {
             "type": "string",
@@ -30004,7 +31082,7 @@
           "name": {
             "type": "string",
             "pattern": "^[A-Za-z_][A-Za-z0-9_]{0,63}$",
-            "description": "Variable name used in `{{ }}` templates, at most 64 characters. Names starting with `__` are reserved for built-in time variables."
+            "description": "Variable name, unique within the definition. Queries reference it as `${name}` (or `$name` inside Prometheus and Loki expressions). Names starting with `__` are reserved for the built-in variables `__interval`, `__rate_interval`, `__range` and `__auto`."
           },
           "label": {
             "type": "string",
@@ -30065,7 +31143,7 @@
       },
       "DashboardSelection": {
         "type": "object",
-        "description": "A concrete selection of variable values. An empty `values` array is valid wire input and means unresolved — the server never substitutes a default for it.",
+        "description": "A concrete selection of variable values. As a saved variable `default`, `values` must be non-empty and hold exactly one value in `single` mode. In runtime requests an empty `values` array is valid and means unresolved — the server never substitutes a default for it.",
         "properties": {
           "kind": {
             "type": "string",
@@ -30152,7 +31230,7 @@
           },
           "metric": {
             "type": "string",
-            "description": "Optional metric used to restrict the series considered."
+            "description": "Optional metric selector that restricts the series considered; may reference other variables as `${name}` or `$name`."
           },
           "label_filters": {
             "type": "array",
@@ -30174,7 +31252,7 @@
           "label": {
             "type": "string",
             "pattern": "^[A-Za-z_][A-Za-z0-9_:.\\-]{0,189}$",
-            "description": "Label name."
+            "description": "Prometheus label name to match, e.g. `job`; letters, digits, `_`, `:`, `.` and `-`, starting with a letter or `_`."
           },
           "op": {
             "type": "string",
@@ -30189,7 +31267,7 @@
           "value": {
             "type": "string",
             "minLength": 1,
-            "description": "Matcher value; may reference other variables through `{{ }}`."
+            "description": "Matcher value; may reference other variables as `${name}`. A multi-value or `all` variable needs `=~` or `!~`."
           }
         },
         "required": [
@@ -30211,7 +31289,7 @@
           },
           "expr": {
             "type": "string",
-            "description": "SQL statement; may reference other variables through `{{ }}`."
+            "description": "SQL statement whose result supplies the candidates. SQL variable queries run only on MySQL datasources, and MySQL queries do not support variable references."
           },
           "args": {
             "type": "object",
@@ -30250,7 +31328,7 @@
           },
           "expr": {
             "type": "string",
-            "description": "Logs query expression; may reference other variables through `{{ }}`. May be empty for a Loki datasource, which then lists the field's values across all streams."
+            "description": "Logs query expression; may reference other variables as `${name}`. Logs variable queries run only on Loki datasources, where `expr` may be empty to list the field's values across all streams."
           },
           "args": {
             "type": "object",
@@ -30273,7 +31351,7 @@
         ]
       },
       "DashboardVizConfig": {
-        "description": "Visualization configuration. `kind` selects the arm and therefore which sibling config object is required; `time_series` also carries the shared numeric options.",
+        "description": "Visualization configuration. `kind` selects the arm and therefore which sibling fields are allowed; `time_series`, `stat`, `bar` and `gauge` also carry the shared numeric fields `unit`, `decimals` and `threshold`. Fields of another kind are rejected.",
         "oneOf": [
           {
             "$ref": "#/components/schemas/DashboardTimeSeriesViz"
@@ -30340,7 +31418,7 @@
               "bytes_per_second",
               "bits_per_second"
             ],
-            "description": "Display unit for the panel's numeric values: `unitless` = raw number; `ratio` = fraction of 1; `percent` = percentage; `milliseconds` = duration in milliseconds; `seconds` = duration in seconds; `bytes` = size in bytes; `bits` = size in bits; `count_per_second` = per-second count; `bytes_per_second` = bytes per second; `bits_per_second` = bits per second."
+            "description": "Display unit for the panel's numeric values: `unitless` = raw number; `ratio` = fraction of 1; `percent` = percentage; `milliseconds` = duration in milliseconds; `seconds` = duration in seconds; `bytes` = size in bytes; `bits` = size in bits; `count_per_second` = per-second count; `bytes_per_second` = bytes per second; `bits_per_second` = bits per second. Defaults to `unitless` when omitted."
           },
           "decimals": {
             "type": [
@@ -30348,7 +31426,8 @@
               "null"
             ],
             "minimum": 0,
-            "description": "Fixed decimal places; omit or send null to let the renderer decide."
+            "description": "Fixed number of decimal places, 0–15; omit or send null to let the console decide.",
+            "maximum": 15
           },
           "threshold": {
             "$ref": "#/components/schemas/DashboardThreshold"
@@ -30380,15 +31459,14 @@
             "additionalProperties": {
               "$ref": "#/components/schemas/DashboardColumnOption"
             },
-            "description": "Per-column display overrides keyed by field name, at most 100 entries."
+            "description": "Per-column display overrides keyed by result field name, at most 100 entries. Keys must be non-empty, at most 1024 Unicode code points and not `frame_index` or `field_index`."
           },
           "sort": {
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/DashboardFieldSort"
             },
-            "maxItems": 2,
-            "description": "Initial sort keys; fields must be unique."
+            "description": "Initial sort keys, applied in order; each field may appear once."
           },
           "link_columns": {
             "type": "array",
@@ -30434,7 +31512,7 @@
               "bytes_per_second",
               "bits_per_second"
             ],
-            "description": "Display unit for the panel's numeric values: `unitless` = raw number; `ratio` = fraction of 1; `percent` = percentage; `milliseconds` = duration in milliseconds; `seconds` = duration in seconds; `bytes` = size in bytes; `bits` = size in bits; `count_per_second` = per-second count; `bytes_per_second` = bytes per second; `bits_per_second` = bits per second."
+            "description": "Display unit for the panel's numeric values: `unitless` = raw number; `ratio` = fraction of 1; `percent` = percentage; `milliseconds` = duration in milliseconds; `seconds` = duration in seconds; `bytes` = size in bytes; `bits` = size in bits; `count_per_second` = per-second count; `bytes_per_second` = bytes per second; `bits_per_second` = bits per second. Defaults to `unitless` when omitted."
           },
           "decimals": {
             "type": [
@@ -30442,7 +31520,8 @@
               "null"
             ],
             "minimum": 0,
-            "description": "Fixed decimal places; omit or send null to let the renderer decide."
+            "description": "Fixed number of decimal places, 0–15; omit or send null to let the console decide.",
+            "maximum": 15
           },
           "threshold": {
             "$ref": "#/components/schemas/DashboardThreshold"
@@ -30452,7 +31531,9 @@
             "items": {
               "type": "string"
             },
-            "description": "Fields reduced to the displayed values."
+            "description": "Result fields reduced to the displayed values; at least one, each listed once. Names are matched exactly and must not be `frame_index` or `field_index`.",
+            "minItems": 1,
+            "uniqueItems": true
           },
           "reducer": {
             "type": "string",
@@ -30503,7 +31584,7 @@
               "bytes_per_second",
               "bits_per_second"
             ],
-            "description": "Display unit for the panel's numeric values: `unitless` = raw number; `ratio` = fraction of 1; `percent` = percentage; `milliseconds` = duration in milliseconds; `seconds` = duration in seconds; `bytes` = size in bytes; `bits` = size in bits; `count_per_second` = per-second count; `bytes_per_second` = bytes per second; `bits_per_second` = bits per second."
+            "description": "Display unit for the panel's numeric values: `unitless` = raw number; `ratio` = fraction of 1; `percent` = percentage; `milliseconds` = duration in milliseconds; `seconds` = duration in seconds; `bytes` = size in bytes; `bits` = size in bits; `count_per_second` = per-second count; `bytes_per_second` = bytes per second; `bits_per_second` = bits per second. Defaults to `unitless` when omitted."
           },
           "decimals": {
             "type": [
@@ -30511,21 +31592,25 @@
               "null"
             ],
             "minimum": 0,
-            "description": "Fixed decimal places; omit or send null to let the renderer decide."
+            "description": "Fixed number of decimal places, 0–15; omit or send null to let the console decide.",
+            "maximum": 15
           },
           "threshold": {
             "$ref": "#/components/schemas/DashboardThreshold"
           },
           "category_field": {
             "type": "string",
-            "description": "Field supplying the category axis."
+            "description": "Result field supplying the category axis; required, at most 1024 Unicode code points, not `frame_index` or `field_index`.",
+            "minLength": 1
           },
           "value_fields": {
             "type": "array",
             "items": {
               "type": "string"
             },
-            "description": "Fields supplying the bar values."
+            "description": "Result fields supplying the bar values; at least one, each listed once. Names must not be `frame_index` or `field_index`.",
+            "minItems": 1,
+            "uniqueItems": true
           },
           "data_link": {
             "$ref": "#/components/schemas/DashboardDataLink"
@@ -30568,7 +31653,7 @@
               "bytes_per_second",
               "bits_per_second"
             ],
-            "description": "Display unit for the panel's numeric values: `unitless` = raw number; `ratio` = fraction of 1; `percent` = percentage; `milliseconds` = duration in milliseconds; `seconds` = duration in seconds; `bytes` = size in bytes; `bits` = size in bits; `count_per_second` = per-second count; `bytes_per_second` = bytes per second; `bits_per_second` = bits per second."
+            "description": "Display unit for the panel's numeric values: `unitless` = raw number; `ratio` = fraction of 1; `percent` = percentage; `milliseconds` = duration in milliseconds; `seconds` = duration in seconds; `bytes` = size in bytes; `bits` = size in bits; `count_per_second` = per-second count; `bytes_per_second` = bytes per second; `bits_per_second` = bits per second. Defaults to `unitless` when omitted."
           },
           "decimals": {
             "type": [
@@ -30576,7 +31661,8 @@
               "null"
             ],
             "minimum": 0,
-            "description": "Fixed decimal places; omit or send null to let the renderer decide."
+            "description": "Fixed number of decimal places, 0–15; omit or send null to let the console decide.",
+            "maximum": 15
           },
           "threshold": {
             "$ref": "#/components/schemas/DashboardThreshold"
@@ -30586,7 +31672,9 @@
             "items": {
               "type": "string"
             },
-            "description": "Fields reduced to the gauge value."
+            "description": "Result fields reduced to the gauge value; at least one, each listed once. Names are matched exactly and must not be `frame_index` or `field_index`.",
+            "minItems": 1,
+            "uniqueItems": true
           },
           "reducer": {
             "type": "string",
@@ -30669,7 +31757,7 @@
           "markdown": {
             "type": "string",
             "maxLength": 65536,
-            "description": "Markdown body, at most 64 KiB. Only a restricted node set (headings, lists, tables, links, code) survives validation."
+            "description": "Markdown body, at most 64 KiB. Allowed: paragraphs, headings, lists, block quotes, code blocks and spans, emphasis, tables, horizontal rules and links. Links must be `https://` URLs or site-relative paths starting with `/`. Images, raw HTML and `${` templates are rejected with `InvalidParameter`, not stripped."
           }
         },
         "required": [
@@ -30747,7 +31835,7 @@
               "bytes_per_second",
               "bits_per_second"
             ],
-            "description": "Unit override for the column: `unitless` = raw number; `ratio` = fraction of 1; `percent` = percentage; `milliseconds` = duration in milliseconds; `seconds` = duration in seconds; `bytes` = size in bytes; `bits` = size in bits; `count_per_second` = per-second count; `bytes_per_second` = bytes per second; `bits_per_second` = bits per second."
+            "description": "Unit override for the column: `unitless` = raw number; `ratio` = fraction of 1; `percent` = percentage; `milliseconds` = duration in milliseconds; `seconds` = duration in seconds; `bytes` = size in bytes; `bits` = size in bits; `count_per_second` = per-second count; `bytes_per_second` = bytes per second; `bits_per_second` = bits per second. Defaults to `unitless` when omitted."
           },
           "threshold": {
             "$ref": "#/components/schemas/DashboardThreshold"
@@ -30772,7 +31860,7 @@
           "field": {
             "type": "string",
             "minLength": 1,
-            "description": "Field name to sort by."
+            "description": "Result field name to sort by; at most 1024 Unicode code points, not `frame_index` or `field_index`."
           },
           "direction": {
             "type": "string",
@@ -30790,12 +31878,12 @@
       },
       "DashboardDataLink": {
         "type": "object",
-        "description": "Drill-down link from a table column or bar panel into another dashboard. The target dashboard must exist and the mapping sources must match the source panel's shape.",
+        "description": "Drill-down link from a table or bar panel into another dashboard. Only the ID format is checked on save; a link to a dashboard that does not exist is accepted. The mapping sources allowed depend on the source panel kind.",
         "properties": {
           "dashboard_id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "Target dashboard ID."
+            "description": "ID of the dashboard to open; must be a canonical UUIDv7."
           },
           "target_id": {
             "type": "string",
@@ -30811,7 +31899,7 @@
             "additionalProperties": {
               "$ref": "#/components/schemas/DashboardLinkMapping"
             },
-            "description": "Maps target variable names to a source value such as a column or a source variable."
+            "description": "Values to set in the target dashboard, keyed by target variable name (must match `^[A-Za-z_][A-Za-z0-9_]{0,63}$`); each entry says where the value comes from. Send `{}` for none."
           }
         },
         "required": [
@@ -30833,15 +31921,15 @@
               "series",
               "value"
             ],
-            "description": "Where the value comes from: `variable` = a dashboard variable; `row_column` = a table column (requires `column`); `category` = the bar category; `series` = the series name; `value` = the value itself. `category`, `series` and `value` are only valid for bar panels."
+            "description": "Where the value comes from: `variable` = the current value of a variable of the source dashboard (requires `name`), allowed on table and bar panels; `row_column` = the clicked row's value in a table column (requires `column`), table panels only; `category` = the clicked bar's category, `series` = its series name, `value` = its value — these three are bar panels only and take no extra fields."
           },
           "column": {
             "type": "string",
-            "description": "Source column name; required when `source` is `row_column`."
+            "description": "Table column (result field) to read; required when `source` is `row_column` and forbidden otherwise."
           },
           "name": {
             "type": "string",
-            "description": "Source dashboard variable name; required when `source` is `variable`."
+            "description": "Variable of the source dashboard to read; required when `source` is `variable` and must exist in the same definition; forbidden for other sources."
           }
         },
         "required": [
@@ -30855,11 +31943,11 @@
           "id": {
             "type": "integer",
             "format": "uint64",
-            "description": "Member ID."
+            "description": "Member ID of the person who performed the action."
           },
           "name": {
             "type": "string",
-            "description": "Member display name."
+            "description": "Member display name, recorded at the time of the action."
           }
         },
         "required": [
@@ -30942,13 +32030,13 @@
           "dashboard_id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "Dashboard ID."
+            "description": "Dashboard ID; pass it to `POST /monit/dashboard/get` for the full definition."
           },
           "folder_id": {
             "type": "integer",
             "format": "uint64",
             "minimum": 1,
-            "description": "Folder ID."
+            "description": "ID of the folder the dashboard is stored in."
           },
           "folder_breadcrumb": {
             "type": "array",
@@ -30963,7 +32051,7 @@
           },
           "description": {
             "type": "string",
-            "description": "Dashboard description; empty when unset."
+            "description": "Dashboard description; omitted when unset."
           },
           "revision": {
             "type": "integer",
@@ -31019,7 +32107,7 @@
           "dashboard_id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "Dashboard ID."
+            "description": "ID of the trashed dashboard; pass it to `POST /monit/dashboard/restore`."
           },
           "folder_id": {
             "type": "integer",
@@ -31040,13 +32128,13 @@
           },
           "description": {
             "type": "string",
-            "description": "Dashboard description; empty when unset."
+            "description": "Dashboard description; omitted when unset."
           },
           "revision": {
             "type": "integer",
             "format": "uint64",
             "minimum": 1,
-            "description": "Revision the dashboard had when deleted."
+            "description": "Current revision of the trashed dashboard (the deletion bumped it); send it as `expected_revision` to restore."
           },
           "deleted_by": {
             "$ref": "#/components/schemas/DashboardActor"
@@ -31081,7 +32169,7 @@
           "total": {
             "type": "integer",
             "format": "int64",
-            "description": "Total number of deleted dashboards."
+            "description": "Total number of trashed dashboards visible to the caller, across all pages."
           }
         },
         "required": [
@@ -31091,11 +32179,11 @@
       },
       "DashboardUpdateOutput": {
         "type": "object",
-        "description": "Result of an update or move. `changed` is false when the write was a no-op — the canonical serialized definition matched the stored one byte for byte, in which case `resource` still describes the unchanged dashboard.",
+        "description": "Result of an update or move. `changed` is false when nothing was written — for update, the normalized definition and `schema_version` equal the stored ones; for move, the dashboard is already in the target folder. `revision` then stays the same and `resource` describes the unchanged dashboard.",
         "properties": {
           "changed": {
             "type": "boolean",
-            "description": "Whether the stored dashboard actually changed."
+            "description": "Whether the dashboard was written and its `revision` incremented."
           },
           "resource": {
             "$ref": "#/components/schemas/DashboardResource"
@@ -31113,13 +32201,13 @@
           "dashboard_id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "Dashboard ID."
+            "description": "ID of the dashboard moved to the trash."
           },
           "revision": {
             "type": "integer",
             "format": "uint64",
             "minimum": 1,
-            "description": "Revision recorded for the deletion."
+            "description": "Revision after the deletion; send it as `expected_revision` to restore."
           }
         },
         "required": [
@@ -31134,7 +32222,7 @@
           "dashboard_id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "Dashboard ID."
+            "description": "ID of the dashboard this revision belongs to."
           },
           "revision": {
             "type": "integer",
@@ -31151,7 +32239,7 @@
           "message": {
             "type": "string",
             "maxLength": 1024,
-            "description": "Optional commit message; at most 1024 Unicode code points."
+            "description": "Message passed to `POST /monit/dashboard/update`; omitted when none was given and on revisions written by create, move, delete and restore."
           },
           "actor": {
             "$ref": "#/components/schemas/DashboardActor"
@@ -31193,7 +32281,7 @@
           "dashboard_id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "Dashboard ID."
+            "description": "ID of the dashboard this revision belongs to."
           },
           "schema_version": {
             "type": "string",
@@ -31220,7 +32308,7 @@
           "message": {
             "type": "string",
             "maxLength": 1024,
-            "description": "Optional commit message."
+            "description": "Message passed to `POST /monit/dashboard/update`; omitted when none was given."
           },
           "actor": {
             "$ref": "#/components/schemas/DashboardActor"
@@ -31280,7 +32368,7 @@
           "dashboard_id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "Dashboard ID."
+            "description": "Dashboard ID, as passed in the request."
           },
           "title": {
             "type": "string",
@@ -31288,7 +32376,7 @@
           },
           "description": {
             "type": "string",
-            "description": "Dashboard description; empty when unset."
+            "description": "Dashboard description; omitted when unset."
           },
           "revision": {
             "type": "integer",
@@ -31317,7 +32405,7 @@
             "type": "integer",
             "format": "uint64",
             "minimum": 1,
-            "description": "Folder ID."
+            "description": "ID of the folder the dashboard is stored in."
           },
           "breadcrumb": {
             "type": "array",
@@ -31343,7 +32431,7 @@
           },
           "label": {
             "type": "string",
-            "description": "Display label; empty when unset."
+            "description": "Display label; omitted when unset."
           },
           "kind": {
             "type": "string",
@@ -31370,15 +32458,15 @@
           "id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "Tab ID."
+            "description": "Tab ID; pass it as `target_id` to narrow the outline to this tab."
           },
           "title": {
             "type": "string",
-            "description": "Tab title."
+            "description": "Tab title as stored in the definition."
           },
           "description": {
             "type": "string",
-            "description": "Tab description; empty when unset."
+            "description": "Tab description; omitted when unset."
           },
           "breadcrumb": {
             "type": "array",
@@ -31417,7 +32505,7 @@
           "id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "Section ID."
+            "description": "Section ID; pass it as `target_id` to narrow the outline to this section."
           },
           "title": {
             "type": "string",
@@ -31425,7 +32513,7 @@
           },
           "description": {
             "type": "string",
-            "description": "Section description; empty when unset."
+            "description": "Section description; omitted when unset."
           },
           "breadcrumb": {
             "type": "array",
@@ -31456,7 +32544,7 @@
           "id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "Panel ID."
+            "description": "Panel ID; use it as `panel_id` for `POST /monit/dashboard/panel/run` or as `target_id` here."
           },
           "title": {
             "type": "string",
@@ -31464,7 +32552,7 @@
           },
           "description": {
             "type": "string",
-            "description": "Panel description; empty when unset."
+            "description": "Panel description; omitted when unset."
           },
           "breadcrumb": {
             "type": "array",
@@ -31478,7 +32566,7 @@
           },
           "datasource_type": {
             "type": "string",
-            "description": "Datasource type the panel queries; empty when the panel has no datasource (text panels)."
+            "description": "Datasource type from the panel's `datasource_ref`, such as `prometheus`, `mysql` or `loki`; omitted for text panels, which have no datasource. The set is open: it echoes whatever type was saved."
           }
         },
         "required": [
@@ -31544,7 +32632,7 @@
           "dashboard_id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "Canonical UUIDv7 of the dashboard."
+            "description": "Lowercase canonical UUIDv7 generated by the caller; it becomes the dashboard's permanent ID."
           },
           "schema_version": {
             "type": "string",
@@ -31557,7 +32645,7 @@
             "type": "integer",
             "format": "uint64",
             "minimum": 1,
-            "description": "Folder the dashboard is created in. Must be a folder the caller can write."
+            "description": "Folder to create the dashboard in; must exist and be accessible to the `app_key` owner, otherwise `FolderNotFound`."
           },
           "definition": {
             "$ref": "#/components/schemas/DashboardDefinition"
@@ -31660,7 +32748,7 @@
             "type": "integer",
             "format": "uint64",
             "minimum": 1,
-            "description": "Destination folder ID."
+            "description": "Destination folder ID; must exist and be accessible to the caller, otherwise `FolderNotFound`."
           }
         },
         "required": [
@@ -31671,7 +32759,7 @@
       },
       "DashboardDeleteRequest": {
         "type": "object",
-        "description": "Move a dashboard to the trash. The definition is retained for 30 days so the delete can be undone with the restore endpoint.",
+        "description": "Move a dashboard to the trash. It is purged permanently 30 days after deletion; until then the restore endpoint can undo the delete.",
         "properties": {
           "dashboard_id": {
             "type": "string",
@@ -31703,7 +32791,7 @@
             "type": "integer",
             "format": "uint64",
             "minimum": 1,
-            "description": "Revision the caller last read. The write fails with `DashboardRevisionConflict` unless it still matches the stored revision."
+            "description": "Current revision of the trashed dashboard, as returned by the delete call or listed in the trash. The restore fails with `DashboardRevisionConflict` if it does not match."
           },
           "folder_id": {
             "type": [
@@ -31712,7 +32800,7 @@
             ],
             "format": "uint64",
             "minimum": 1,
-            "description": "Destination folder. Omit to restore to the original folder; when the original folder is no longer writable the call fails with `RestoreFolderRequired` and you must pass one."
+            "description": "Destination folder. Omit or send null to restore into the original folder; if that folder no longer exists the call fails with `RestoreFolderRequired` and a destination must be passed."
           }
         },
         "required": [
@@ -31749,12 +32837,12 @@
             "type": "integer",
             "format": "uint64",
             "minimum": 1,
-            "description": "Folder whose dashboards are listed."
+            "description": "Folder whose directly contained dashboards are listed; subfolders are not included."
           },
           "query": {
             "type": "string",
             "maxLength": 128,
-            "description": "Optional space-separated search words matched against title and description; at most 128 Unicode code points."
+            "description": "Optional search words separated by whitespace, at most 128 Unicode code points. A dashboard matches when every word appears in its title or description."
           },
           "sort": {
             "type": "array",
@@ -31788,7 +32876,7 @@
             "type": "string",
             "minLength": 1,
             "maxLength": 128,
-            "description": "Space-separated search words; at least one word and at most 128 Unicode code points."
+            "description": "Search words separated by whitespace; at least one word and at most 128 Unicode code points. A dashboard matches when every word appears in its title or description."
           },
           "sort": {
             "type": "array",
@@ -31847,13 +32935,15 @@
             "type": "integer",
             "format": "int64",
             "minimum": 0,
-            "description": "Unix timestamp in milliseconds."
+            "description": "Start of the window as a Unix timestamp in milliseconds. Must be 0 or greater and less than `to_ms`.",
+            "maximum": 9007199254740991
           },
           "to_ms": {
             "type": "integer",
             "format": "int64",
             "minimum": 1,
-            "description": "Unix timestamp in milliseconds."
+            "description": "End of the window as a Unix timestamp in milliseconds. Must be greater than `from_ms`; `instant` queries are evaluated at this time.",
+            "maximum": 9007199254740991
           }
         },
         "required": [
@@ -31863,15 +32953,15 @@
       },
       "DashboardRuntimeError": {
         "type": "object",
-        "description": "Per-variable or per-query failure. A failed arm does not fail the whole call.",
+        "description": "Failure of one variable or one query. A failed variable or query does not fail the whole call.",
         "properties": {
           "reason": {
             "type": "string",
-            "description": "Machine-readable failure reason. Observed values include `invalid_request`, `variable_invalid`, `panel_missing`, `field_missing`, `datasource_permission_denied`, `timeout`, `panel_deadline`, `panel_canceled`, `canceled`, `overloaded`, `source_too_large`, `edge_unavailable`, `edge_upgrade_required`, `edge_version_unknown`, `mixed_edge_versions` and `internal`."
+            "description": "Machine-readable failure reason. The set is open; current values:\n- `invalid_request`: the query or datasource setup is rejected (unsupported datasource type or query mode, non-empty `args` where none are allowed, a malformed argument).\n- `variable_invalid`: a variable could not be used (no selection and no default, a selection outside the candidates, an unresolved dependency, a bad substitution, or an unusable candidate list).\n- `panel_missing`: the panel is not in the dashboard (queries resolve only).\n- `datasource_permission_denied`: the datasource is missing, disabled, not accessible to the caller, or no accessible datasource matches the variable.\n- `field_missing`, `value_not_scalar`, `empty_field_name`, `duplicate_field_name`, `field_type_changed`: the result does not fit the panel's visualization, or a SQL variable query returned unusable columns.\n- `timeout`: the datasource call timed out; `panel_deadline`: the run hit the overall 35-second deadline.\n- `canceled`, `panel_canceled`: the call was cancelled.\n- `overloaded`: the datasource side is rate limiting.\n- `too_many_rows`, `result_too_large`, `source_too_large`: a row, size or candidate-count limit was exceeded.\n- `edge_unavailable`, `no_active_edge`, `edge_upgrade_required`, `edge_version_unknown`, `mixed_edge_versions`: the Edge cluster of the datasource is not connected, too old, of unknown version, or mixed.\n- `internal`: an unexpected server-side error."
           },
           "message": {
             "type": "string",
-            "description": "Human-readable detail for the failure."
+            "description": "Human-readable detail for display or troubleshooting; its wording is not stable, so do not parse it."
           }
         },
         "required": [
@@ -31881,18 +32971,18 @@
       },
       "DashboardRuntimeDatasource": {
         "type": "object",
-        "description": "The datasource a runtime query was bound to.",
+        "description": "The datasource a runtime variable or query was bound to.",
         "properties": {
           "id": {
             "type": "integer",
             "format": "uint64",
             "minimum": 1,
-            "description": "Datasource ID."
+            "description": "Datasource ID, as listed by the datasource list endpoint."
           },
           "type": {
             "type": "string",
             "pattern": "^[a-z][a-z0-9_]{0,63}$",
-            "description": "Datasource type identifier."
+            "description": "Datasource type identifier. Resolved queries and `query` variables only use `prometheus`, `mysql` or `loki`; the datasource chosen by a `datasource` variable can be any type identifier the variable was configured with."
           },
           "name": {
             "type": "string",
@@ -31907,12 +32997,12 @@
       },
       "DashboardResolvedVariable": {
         "type": "object",
-        "description": "One resolved variable. An unreachable datasource, a bad expression or an empty result leaves `candidates` incomplete and fills `error` instead of failing the request.",
+        "description": "One resolved variable. A failure (no selection and no default, a selection outside the candidates, an unresolved dependency, an unreachable datasource, an unusable query result) fills `error` and leaves `selection` out instead of failing the request.",
         "properties": {
           "name": {
             "type": "string",
             "pattern": "^[A-Za-z_][A-Za-z0-9_]{0,63}$",
-            "description": "Variable name."
+            "description": "Variable name, as defined in the dashboard or draft."
           },
           "kind": {
             "type": "string",
@@ -31928,7 +33018,7 @@
             "items": {
               "$ref": "#/components/schemas/DashboardCandidate"
             },
-            "description": "Resolved candidates, at most 1000."
+            "description": "Selectable options, at most 1000; an empty array when there are none or resolution failed. Order: `custom` keeps the definition order, `datasource` is sorted by name then ID, `query` is sorted by value."
           },
           "selection": {
             "$ref": "#/components/schemas/DashboardSelection"
@@ -31963,13 +33053,13 @@
             "additionalProperties": {
               "$ref": "#/components/schemas/DashboardSelection"
             },
-            "description": "Selections already made, keyed by variable name, at most 20 entries. Variables omitted here fall back to their stored defaults."
+            "description": "Selections already made, keyed by variable name, at most 20 entries. Variables without an entry fall back to their stored defaults; a name the dashboard does not define fails the call with HTTP 400.",
+            "maxProperties": 20
           }
         },
         "required": [
           "dashboard_id",
-          "time",
-          "variables"
+          "time"
         ]
       },
       "DashboardVariablesResolveResponse": {
@@ -31979,7 +33069,7 @@
           "dashboard_id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "Dashboard ID."
+            "description": "ID of the dashboard the variables were resolved for, echoing the request."
           },
           "revision": {
             "type": "integer",
@@ -32016,7 +33106,7 @@
           "ref_id": {
             "type": "string",
             "pattern": "^[A-Z]$",
-            "description": "Panel-local query reference."
+            "description": "Query reference within the panel: a single letter `A`–`Z`."
           },
           "datasource": {
             "$ref": "#/components/schemas/DashboardRuntimeDatasource"
@@ -32028,27 +33118,24 @@
               "instant",
               "window"
             ],
-            "description": "Evaluation mode: `range` = a stepped time series; `instant` = a single point in time; `window` = raw rows inside a bounded time window."
+            "description": "Evaluation mode: `range` = a stepped time series; `instant` = a single point in time; `window` = rows inside a bounded time window. Prometheus and Loki queries use `range` or `instant`; MySQL queries use `window`."
           },
           "expr": {
             "type": "string",
-            "description": "Expression with variable templates substituted."
+            "description": "Expression with variable templates substituted. Built-in time variables stay verbatim when the request set `preserve_builtin_variables` to `true`."
           },
           "args": {
             "type": "object",
             "additionalProperties": {
               "type": "string"
             },
-            "description": "Query arguments; empty object when none."
+            "description": "Query arguments; an empty object when none. Only Loki queries carry arguments: `loki.limit` (a decimal integer from 1 to 1000, the maximum number of log entries) and `loki.direction` (`latest` or `earliest`)."
           },
           "min_step_seconds": {
-            "type": [
-              "integer",
-              "null"
-            ],
+            "type": "integer",
             "format": "int64",
             "minimum": 1,
-            "description": "Minimum step in seconds; null when unset."
+            "description": "Minimum step in seconds from the panel query; omitted when unset."
           }
         },
         "required": [
@@ -32061,12 +33148,12 @@
       },
       "DashboardResolvedPanelQueries": {
         "type": "object",
-        "description": "Per-panel resolution result. `state` is `success` when every query resolved, `partial` when some did and `error` when none did.",
+        "description": "Per-panel resolution result. `state` is `success` when every query resolved, `partial` when some did and `error` when none did. `error` describes only the first failure.",
         "properties": {
           "panel_id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "Panel ID."
+            "description": "ID of the panel, echoing an entry of `panel_ids`."
           },
           "state": {
             "type": "string",
@@ -32075,14 +33162,14 @@
               "partial",
               "error"
             ],
-            "description": "Aggregate state of the panel's queries: `success` = every query resolved; `partial` = some resolved; `error` = none resolved."
+            "description": "Resolution state of the panel's queries: `success` = every query resolved; `partial` = some resolved and some failed; `error` = none resolved, including a panel that does not exist."
           },
           "queries": {
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/DashboardResolvedQuery"
             },
-            "description": "Successfully resolved queries."
+            "description": "Queries that resolved successfully, in the panel's query order. Queries that failed are left out; empty array when none resolved."
           },
           "error": {
             "$ref": "#/components/schemas/DashboardRuntimeError"
@@ -32121,7 +33208,8 @@
             "additionalProperties": {
               "$ref": "#/components/schemas/DashboardSelection"
             },
-            "description": "Selections keyed by variable name, at most 20 entries."
+            "description": "Selections keyed by variable name, at most 20 entries. Variables without an entry fall back to their stored defaults; a name the dashboard does not define fails the call with HTTP 400.",
+            "maxProperties": 20
           },
           "max_data_points": {
             "type": [
@@ -32130,7 +33218,7 @@
             ],
             "minimum": 2,
             "maximum": 5000,
-            "description": "Downsampling target used to compute the step and render the built-in time variables, 2–5000 points; omit or send null for the server default of 100."
+            "description": "Target maximum number of points per series, used to compute the step and render the built-in time variables. 2–5000; omit or send null for the default of 100."
           },
           "preserve_builtin_variables": {
             "type": "boolean",
@@ -32140,18 +33228,17 @@
         "required": [
           "dashboard_id",
           "panel_ids",
-          "time",
-          "variables"
+          "time"
         ]
       },
       "DashboardQueriesResolveResponse": {
         "type": "object",
-        "description": "One entry per requested panel, in request order.",
+        "description": "Resolved queries of the requested panels, plus the effective variable selections they were resolved with. Nothing is executed.",
         "properties": {
           "dashboard_id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "Dashboard ID."
+            "description": "ID of the dashboard the queries were resolved against, echoing the request."
           },
           "revision": {
             "type": "integer",
@@ -32167,14 +33254,14 @@
             "additionalProperties": {
               "$ref": "#/components/schemas/DashboardSelection"
             },
-            "description": "Selections that resolved successfully."
+            "description": "Effective selections of the variables that resolved successfully, keyed by variable name; variables that failed to resolve are left out."
           },
           "panels": {
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/DashboardResolvedPanelQueries"
             },
-            "description": "Per-panel results."
+            "description": "One entry per requested panel, in request order."
           }
         },
         "required": [
@@ -32192,12 +33279,12 @@
           "max_concurrency": {
             "type": "integer",
             "minimum": 1,
-            "description": "Concurrency cap applied to the panel's queries."
+            "description": "Maximum number of the panel's queries executed at the same time; fixed at 6."
           },
           "execution_count": {
             "type": "integer",
             "minimum": 0,
-            "description": "Number of queries launched."
+            "description": "Number of queries that resolved successfully and were dispatched for execution; queries that failed to resolve are not counted."
           }
         },
         "required": [
@@ -32207,12 +33294,12 @@
       },
       "DashboardPanelRunRef": {
         "type": "object",
-        "description": "Result of one query inside a panel run. The raw execution payload differs per datasource type and is passed through unmodified, so it is not schema-constrained here.",
+        "description": "Result of one query inside a panel run or preview. The raw execution payload differs per datasource type and is passed through unmodified, so it is not schema-constrained here.",
         "properties": {
           "ref_id": {
             "type": "string",
             "pattern": "^[A-Z]$",
-            "description": "Panel-local query reference."
+            "description": "Query reference within the panel: a single letter `A`–`Z`, as set in the panel's `queries`."
           },
           "state": {
             "type": "string",
@@ -32221,16 +33308,16 @@
               "error",
               "incompatible"
             ],
-            "description": "Per-query execution state: `success` = the query executed; `error` = the query failed; `incompatible` = the datasource accepted the call but the query mode or field selection does not fit the datasource type."
+            "description": "Per-query state: `success` = the query ran and `execution` is present; `error` = the query could not be resolved or executed, or the run was cancelled or timed out, and `error` explains why; `incompatible` = the query ran, but its result does not fit the panel's visualization (for example a configured field is missing or not numeric), so `execution` is still present and `error` explains the mismatch."
           },
           "child_request_id": {
             "type": "string",
-            "description": "Request ID of the underlying datasource execution; use it when tracing a single query."
+            "description": "Request ID of the underlying datasource execution; use it when tracing a single query. Absent when the query never reached the datasource."
           },
           "execution": {
             "type": "object",
             "additionalProperties": true,
-            "description": "Datasource-specific execution payload, passed through unmodified."
+            "description": "Datasource-specific execution result, passed through unmodified. Present when `state` is `success` or `incompatible`; absent when `state` is `error`."
           },
           "error": {
             "$ref": "#/components/schemas/DashboardRuntimeError"
@@ -32243,7 +33330,7 @@
       },
       "DashboardPanelRunRequest": {
         "type": "object",
-        "description": "Execute one panel against the stored dashboard. Omit `revision` to run the current revision; send it to have stale responses rejected.",
+        "description": "Execute one panel of a stored dashboard. Omit `revision` (or send 0) to run the current revision; send it to have a stale call rejected. Text panels cannot be run.",
         "properties": {
           "dashboard_id": {
             "type": "string",
@@ -32253,13 +33340,12 @@
           "panel_id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "Panel to execute."
+            "description": "ID of the panel to execute. It must belong to the dashboard, otherwise the call returns `TargetNotFound` (HTTP 404)."
           },
           "revision": {
             "type": "integer",
             "format": "uint64",
-            "minimum": 1,
-            "description": "Revision guard; when set it must equal the current revision."
+            "description": "Revision guard. When set (non-zero) it must equal the dashboard's current revision, otherwise the call fails with `DashboardRevisionConflict` (HTTP 409). Omit or send 0 to skip the check."
           },
           "time": {
             "$ref": "#/components/schemas/DashboardAbsoluteTimeRange"
@@ -32269,7 +33355,8 @@
             "additionalProperties": {
               "$ref": "#/components/schemas/DashboardSelection"
             },
-            "description": "Selections keyed by variable name, at most 20 entries."
+            "description": "Selections keyed by variable name, at most 20 entries. Variables without an entry fall back to their stored defaults; a name the dashboard does not define fails the call with HTTP 400.",
+            "maxProperties": 20
           },
           "max_data_points": {
             "type": [
@@ -32278,29 +33365,28 @@
             ],
             "minimum": 2,
             "maximum": 5000,
-            "description": "Downsampling target, 2–5000 points; omit or send null for the server default of 100."
+            "description": "Target maximum number of points per series for `range` queries; the server derives the query step from it. 2–5000; omit or send null for the default of 100."
           }
         },
         "required": [
           "dashboard_id",
           "panel_id",
-          "time",
-          "variables"
+          "time"
         ]
       },
       "DashboardPanelRunResponse": {
         "type": "object",
-        "description": "Panel execution result. `run_state` aggregates the per-query states: `success` when all succeeded, `partial` when some did, otherwise `incompatible`, `cancelled` or `error`. The total response is capped at 8 MiB.",
+        "description": "Panel execution result. HTTP 200 is returned even when every query failed; read `run_state` and each ref's `state` and `error`. A response larger than 8 MiB is rejected with `EntityTooLarge` (HTTP 413) instead of being truncated.",
         "properties": {
           "dashboard_id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "Dashboard ID."
+            "description": "ID of the dashboard that was run, echoing the request."
           },
           "panel_id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "Panel ID."
+            "description": "ID of the panel that was run, echoing the request."
           },
           "revision": {
             "type": "integer",
@@ -32317,7 +33403,7 @@
               "cancelled",
               "error"
             ],
-            "description": "Aggregate state of the run: `success` = all queries succeeded; `partial` = some succeeded; `incompatible` = at least one query is incompatible with its datasource; `cancelled` = the run was cancelled; `error` = all queries failed."
+            "description": "Aggregate state of the run: `success` = every query succeeded; `partial` = at least one query succeeded and at least one did not; `cancelled` = no query succeeded and the client cancelled the request; `incompatible` = no query succeeded and at least one query ran but returned a result that does not fit the panel's visualization; `error` = no query succeeded and none is `incompatible` (also when the panel has no queries)."
           },
           "time": {
             "$ref": "#/components/schemas/DashboardAbsoluteTimeRange"
@@ -32327,14 +33413,14 @@
             "additionalProperties": {
               "$ref": "#/components/schemas/DashboardSelection"
             },
-            "description": "Selections that resolved successfully."
+            "description": "Effective selections of the variables that resolved successfully, keyed by variable name; variables that failed to resolve are left out."
           },
           "refs": {
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/DashboardPanelRunRef"
             },
-            "description": "One entry per query in the panel."
+            "description": "One entry per query of the panel, in the panel's query order. A query that failed to resolve appears with `state` `error`."
           },
           "display": {
             "$ref": "#/components/schemas/DashboardVizConfig"
@@ -32370,13 +33456,13 @@
           "dashboard_id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "Required for `existing`, forbidden for `new`."
+            "description": "Required for `existing`, forbidden for `new`. The caller must have access to the dashboard's folder."
           },
           "folder_id": {
             "type": "integer",
             "format": "uint64",
             "minimum": 1,
-            "description": "Required for `new`, forbidden for `existing`."
+            "description": "Required for `new`, forbidden for `existing`. Must be a folder the caller can access, otherwise the call returns `FolderNotFound` (HTTP 404)."
           }
         },
         "required": [
@@ -32396,14 +33482,15 @@
               "$ref": "#/components/schemas/DashboardVariable"
             },
             "maxItems": 20,
-            "description": "Draft variables, at most 20."
+            "description": "Draft variables, at most 20. They are validated like a stored definition (names, dependencies, option limits) and must stay within 1 MiB."
           },
           "selections": {
             "type": "object",
             "additionalProperties": {
               "$ref": "#/components/schemas/DashboardSelection"
             },
-            "description": "Selections keyed by variable name, at most 20 entries."
+            "description": "Selections keyed by variable name, at most 20 entries. Variables without an entry fall back to their draft default; a name that is not in `variables` fails the call with HTTP 400.",
+            "maxProperties": 20
           },
           "time": {
             "$ref": "#/components/schemas/DashboardAbsoluteTimeRange"
@@ -32412,7 +33499,6 @@
         "required": [
           "context",
           "variables",
-          "selections",
           "time"
         ]
       },
@@ -32425,14 +33511,14 @@
             "items": {
               "$ref": "#/components/schemas/DashboardResolvedVariable"
             },
-            "description": "Resolved variables."
+            "description": "Resolved variables, in the order of the draft `variables`."
           },
           "selections": {
             "type": "object",
             "additionalProperties": {
               "$ref": "#/components/schemas/DashboardSelection"
             },
-            "description": "Effective selections keyed by variable name."
+            "description": "Effective selections keyed by variable name; only variables that resolved successfully appear."
           }
         },
         "required": [
@@ -32442,7 +33528,7 @@
       },
       "DashboardPanelPreviewRequest": {
         "type": "object",
-        "description": "Execute a draft panel inline, without saving a dashboard revision. Subject to the same 1 MiB definition-size ceiling.",
+        "description": "Execute a draft panel inline, without saving a dashboard revision. The draft `panel` and `variables` together must stay within 1 MiB, and the request body within 2 MiB.",
         "properties": {
           "context": {
             "$ref": "#/components/schemas/DashboardDraftContext"
@@ -32456,14 +33542,15 @@
               "$ref": "#/components/schemas/DashboardVariable"
             },
             "maxItems": 20,
-            "description": "Draft variables the panel may reference."
+            "description": "Draft variables the panel may reference, at most 20. Required; the panel's queries can only use variables listed here."
           },
           "selections": {
             "type": "object",
             "additionalProperties": {
               "$ref": "#/components/schemas/DashboardSelection"
             },
-            "description": "Selections keyed by variable name."
+            "description": "Selections keyed by variable name, at most 20 entries. Variables without an entry fall back to their draft default.",
+            "maxProperties": 20
           },
           "time": {
             "$ref": "#/components/schemas/DashboardAbsoluteTimeRange"
@@ -32475,25 +33562,24 @@
             ],
             "minimum": 2,
             "maximum": 5000,
-            "description": "Downsampling target, 2–5000 points."
+            "description": "Target maximum number of points per series for `range` queries; the server derives the query step from it. 2–5000; omit or send null for the default of 100."
           }
         },
         "required": [
           "context",
           "panel",
           "variables",
-          "selections",
           "time"
         ]
       },
       "DashboardPanelPreviewResponse": {
         "type": "object",
-        "description": "Draft panel execution result. Same shape as a stored panel run, minus the dashboard identity.",
+        "description": "Draft panel execution result. Same shape as a stored panel run, minus `dashboard_id` and `revision`. HTTP 200 is returned even when every query failed; a response larger than 8 MiB is rejected with `EntityTooLarge` (HTTP 413).",
         "properties": {
           "panel_id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "Panel ID."
+            "description": "ID of the draft panel, echoing `panel.id` from the request."
           },
           "run_state": {
             "type": "string",
@@ -32504,7 +33590,7 @@
               "cancelled",
               "error"
             ],
-            "description": "Aggregate state of the run: `success` = all queries succeeded; `partial` = some succeeded; `incompatible` = at least one query is incompatible with its datasource; `cancelled` = the run was cancelled; `error` = all queries failed."
+            "description": "Aggregate state of the run: `success` = every query succeeded; `partial` = at least one query succeeded and at least one did not; `cancelled` = no query succeeded and the client cancelled the request; `incompatible` = no query succeeded and at least one query ran but returned a result that does not fit the panel's visualization; `error` = no query succeeded and none is `incompatible` (also when the panel has no queries)."
           },
           "time": {
             "$ref": "#/components/schemas/DashboardAbsoluteTimeRange"
@@ -32514,14 +33600,14 @@
             "additionalProperties": {
               "$ref": "#/components/schemas/DashboardSelection"
             },
-            "description": "Selections that resolved successfully."
+            "description": "Effective selections of the variables that resolved successfully, keyed by variable name; variables that failed to resolve are left out."
           },
           "refs": {
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/DashboardPanelRunRef"
             },
-            "description": "One entry per query in the panel."
+            "description": "One entry per query of the panel, in the panel's query order. A query that failed to resolve appears with `state` `error`."
           },
           "display": {
             "$ref": "#/components/schemas/DashboardVizConfig"
@@ -32542,12 +33628,12 @@
       },
       "FolderItem": {
         "type": "object",
-        "description": "A monitor folder (监控节点). Folders form a tree; `parent_path` is the comma-separated ancestor ID list, so the caller can rebuild the tree and search it client-side.",
+        "description": "A monitor folder. Folders form a tree; `parent_path` is the comma-separated ancestor ID list, so the caller can rebuild the tree and search it client-side.",
         "properties": {
           "id": {
             "type": "integer",
             "format": "uint64",
-            "description": "Folder ID."
+            "description": "Folder ID. Pass it as `id` to update, move, or delete the folder, as `parent_id` or `dest_parent_id` to nest folders under it, and as `folder_id` on alert rules and dashboards."
           },
           "account_id": {
             "type": "integer",
@@ -32566,7 +33652,7 @@
           "team_id": {
             "type": "integer",
             "format": "uint64",
-            "description": "Team the folder is scoped to; 0 when account-wide."
+            "description": "ID of the team the folder belongs to; 0 when it has no team. Members of the team can see and modify the folder."
           },
           "name": {
             "type": "string",
@@ -32579,7 +33665,7 @@
           "creator_id": {
             "type": "integer",
             "format": "uint64",
-            "description": "Member ID of the creator."
+            "description": "Member ID of the creator; the creator can always see and modify the folder."
           },
           "creator_name": {
             "type": "string",
@@ -32588,7 +33674,7 @@
           "updater_id": {
             "type": "integer",
             "format": "uint64",
-            "description": "Member ID of the last updater."
+            "description": "Member ID of the last updater. Updates and moves both set it."
           },
           "updater_name": {
             "type": "string",
@@ -32597,12 +33683,12 @@
           "created_at": {
             "type": "integer",
             "format": "int64",
-            "description": "Unix timestamp in seconds."
+            "description": "Creation time as a Unix timestamp in seconds."
           },
           "updated_at": {
             "type": "integer",
             "format": "int64",
-            "description": "Unix timestamp in seconds."
+            "description": "Time of the last update or move as a Unix timestamp in seconds."
           }
         },
         "required": [
@@ -32651,7 +33737,7 @@
           },
           "category": {
             "type": "string",
-            "description": "Filter by category. Accepts a comma-separated list, for example `event.alert,event.change`."
+            "description": "Comma-separated category filter. Values: `event.alert` (alert events), `event.change` (change events), `im` (IM bots), `webhook` (custom webhooks). Unknown values are not rejected and match nothing."
           },
           "asc": {
             "type": [
@@ -32677,7 +33763,7 @@
         "properties": {
           "plugin_type": {
             "type": "string",
-            "description": "Type identifier to pass as `plugin_type` when creating an integration.",
+            "description": "Type key to pass as `plugin_type` when creating an integration, for example `standard.alert`, `prometheus.alert`, `zabbix.alert` or `feishu`. The set grows as integrations are added; this endpoint returns the full list.",
             "example": "standard.alert"
           },
           "plugin_type_name": {
@@ -32701,7 +33787,11 @@
           },
           "status": {
             "type": "string",
-            "description": "Platform status of the type."
+            "description": "Platform status of the type: `enabled` types can be used; `disabled` types are switched off platform-wide and `POST /integration/create` or `POST /integration/update` returns `InvalidParameter` for them.",
+            "enum": [
+              "enabled",
+              "disabled"
+            ]
           },
           "supports_api_create": {
             "type": "boolean",
@@ -32771,23 +33861,23 @@
           },
           "category": {
             "type": "string",
-            "description": "Filter by category. Accepts a comma-separated list."
+            "description": "Comma-separated category filter. Values: `event.alert` (alert events), `event.change` (change events), `im` (IM bots), `webhook` (custom webhooks). Unknown values are not rejected and match nothing."
           },
           "type": {
             "type": "string",
-            "description": "Deprecated. Merged into `plugin_type` when both are set."
+            "description": "Deprecated alias of `plugin_type` (comma-separated type keys such as `prometheus.alert`, `zabbix.alert`). Ignored when `plugin_type` is also set."
           },
           "plugin_type": {
             "type": "string",
-            "description": "Filter by integration type. Accepts a comma-separated list."
+            "description": "Comma-separated integration type keys, for example `standard.alert,prometheus.alert`; the keys are the `plugin_type` values from `POST /integration/type/list`."
           },
           "status": {
             "type": "string",
-            "description": "Filter by status. Accepts a comma-separated list."
+            "description": "Comma-separated status filter: `enabled` (accepting events) and/or `disabled` (paused)."
           },
           "name": {
             "type": "string",
-            "description": "Filter by integration name."
+            "description": "Filter by integration name; matches any name that contains this text."
           },
           "ref_ids": {
             "type": "array",
@@ -32845,7 +33935,7 @@
           "integration_id": {
             "type": "integer",
             "format": "int64",
-            "description": "Integration ID."
+            "description": "Integration ID; pass it as `integration_id` to the other `/integration/*` endpoints."
           },
           "team_id": {
             "type": "integer",
@@ -32997,7 +34087,7 @@
             "type": "integer",
             "format": "int64",
             "minimum": 1,
-            "description": "Integration ID.",
+            "description": "ID of a public integration, returned by `POST /integration/list`. An unknown ID or a channel-owned integration returns `ResourceNotFound`.",
             "example": 6113996590131
           }
         }
@@ -33030,7 +34120,7 @@
           "integration_id": {
             "type": "integer",
             "format": "int64",
-            "description": "Integration ID."
+            "description": "Integration ID; pass it as `integration_id` to the other `/integration/*` endpoints."
           },
           "team_id": {
             "type": "integer",
@@ -33242,7 +34332,7 @@
             "type": "integer",
             "format": "int64",
             "minimum": 1,
-            "description": "Integration ID.",
+            "description": "ID of a public integration, returned by `POST /integration/list`. An unknown ID or a channel-owned integration returns `ResourceNotFound`.",
             "example": 6113996590131
           },
           "name": {
@@ -33293,7 +34383,7 @@
             "type": "integer",
             "format": "int64",
             "minimum": 1,
-            "description": "Integration ID.",
+            "description": "ID of a public integration, returned by `POST /integration/list`. An unknown ID or a channel-owned integration returns `ResourceNotFound`.",
             "example": 6113996590131
           }
         }
@@ -33314,26 +34404,26 @@
       },
       "FolderCreateRequest": {
         "type": "object",
-        "description": "Monitor folder request.",
+        "description": "Request to create a monitor folder.",
         "properties": {
           "name": {
             "type": "string",
-            "description": "Folder name; cannot contain a period, slash, or comma.",
+            "description": "Folder name; required, and must not contain a period (`.`), slash (`/`), or comma (`,`).",
             "minLength": 1
           },
           "note": {
             "type": "string",
-            "description": "Free-form note; omitted or empty clears the note on update."
+            "description": "Free-form note. Empty when omitted."
           },
           "parent_id": {
             "type": "integer",
-            "description": "Parent folder ID; 0 or omitted creates a root folder.",
+            "description": "ID of the parent folder; 0 or omitted creates a root folder. The caller must be allowed to modify the parent.",
             "format": "uint64",
             "minimum": 0
           },
           "team_id": {
             "type": "integer",
-            "description": "Team ID; 0 means account-wide. Omitted on update resets to 0.",
+            "description": "ID of the team the folder belongs to; 0 or omitted means no team. Members of the team can see and modify the folder and everything below it.",
             "format": "uint64",
             "minimum": 0
           }
@@ -33344,26 +34434,26 @@
       },
       "FolderUpdateRequest": {
         "type": "object",
-        "description": "Monitor folder request.",
+        "description": "Request to update a monitor folder. Editable fields are replaced as a whole.",
         "properties": {
           "id": {
             "type": "integer",
-            "description": "Folder ID.",
+            "description": "ID of the folder to update, from `/monit/folder/list` or the create response.",
             "format": "uint64",
             "minimum": 1
           },
           "name": {
             "type": "string",
-            "description": "Folder name; cannot contain a period, slash, or comma.",
+            "description": "New folder name; required, and must not contain a period (`.`), slash (`/`), or comma (`,`).",
             "minLength": 1
           },
           "note": {
             "type": "string",
-            "description": "Free-form note; omitted or empty clears the note on update."
+            "description": "New note. Omitted or empty clears the note."
           },
           "team_id": {
             "type": "integer",
-            "description": "Team ID; 0 means account-wide. Omitted on update resets to 0.",
+            "description": "New team ID; 0 or omitted removes the team assignment.",
             "format": "uint64",
             "minimum": 0
           }
@@ -33375,17 +34465,17 @@
       },
       "FolderMoveRequest": {
         "type": "object",
-        "description": "Monitor folder request.",
+        "description": "Request to move a monitor folder and its descendants.",
         "properties": {
           "id": {
             "type": "integer",
-            "description": "Folder ID.",
+            "description": "ID of the folder to move, from `/monit/folder/list`.",
             "format": "uint64",
             "minimum": 1
           },
           "dest_parent_id": {
             "type": "integer",
-            "description": "Destination parent folder ID; required even when 0 to move to the root.",
+            "description": "ID of the new parent folder; send 0 to move to the root. The field cannot be omitted. Must differ from `id` and must not be a descendant of the folder.",
             "format": "uint64",
             "minimum": 0
           }
@@ -33397,11 +34487,11 @@
       },
       "FolderDeleteRequest": {
         "type": "object",
-        "description": "Monitor folder request.",
+        "description": "Request to delete a monitor folder.",
         "properties": {
           "id": {
             "type": "integer",
-            "description": "Folder ID.",
+            "description": "ID of the folder to delete, from `/monit/folder/list`. The folder must be empty.",
             "format": "uint64",
             "minimum": 1
           }
@@ -33416,13 +34506,13 @@
         "properties": {
           "folder_id": {
             "type": "integer",
-            "description": "Folder ID.",
+            "description": "ID of the folder this entry describes; matches `id` in `/monit/folder/list`.",
             "format": "uint64",
             "minimum": 0
           },
           "has_issue": {
             "type": "boolean",
-            "description": "Whether this folder or a visible descendant has active alerts or rule runtime issues."
+            "description": "`true` when a rule in this folder or in any descendant has an active alert or a runtime problem (`runtime_state` of `offline`, `abnormal`, `stale`, or `no_datasource`). Rules in folders the caller cannot read are not counted."
           }
         },
         "required": [
@@ -33436,7 +34526,7 @@
         "properties": {
           "items": {
             "type": "array",
-            "description": "Folder health summaries.",
+            "description": "One health entry per folder visible to the caller, sorted by `folder_id`.",
             "items": {
               "$ref": "#/components/schemas/FolderHealthItem"
             }
@@ -33449,15 +34539,10 @@
     },
     "securitySchemes": {
       "AppKeyAuth": {
-        "description": "App key issued from the Flashduty console under Account → APP Keys. Required on every public API call. Keep it secret — it grants the same access as the owning account.",
+        "type": "apiKey",
         "in": "query",
         "name": "app_key",
-        "type": "apiKey"
-      },
-      "AutomationTriggerBearerAuth": {
-        "description": "Bearer token generated for one Automation HTTP POST trigger. This is not an app_key.",
-        "scheme": "bearer",
-        "type": "http"
+        "description": "APP Key created in the Flashduty console under My → APP Key. Send it as the `app_key` query parameter or in the `Fd-App-Key` request header. Its effective access is the intersection of the key's permission scope and the creator's current role permissions. Keep it secret."
       }
     }
   },
@@ -33470,67 +34555,76 @@
   "paths": {
     "/account/info": {
       "post": {
+        "summary": "Get account detail",
         "description": "Return the current account's profile and settings.",
         "operationId": "account-read-info",
+        "tags": [
+          "Platform/Account"
+        ],
+        "security": [
+          {
+            "AppKeyAuth": []
+          }
+        ],
         "requestBody": {
           "content": {
             "application/json": {
-              "example": {},
               "schema": {
                 "type": "object"
-              }
+              },
+              "example": {}
             }
           }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/AccountInfo"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "account_id": 1001,
                     "account_name": "acme",
-                    "avatar": "https://cdn.flashcat.cloud/avatar/acme.png",
-                    "country_code": "CN",
-                    "created_at": 1716960000,
                     "domain": "acme",
-                    "email": "ops@acme.example",
                     "extra_domains": [
                       "acme-corp"
                     ],
-                    "locale": "zh-CN",
                     "phone": "138****8000",
+                    "country_code": "CN",
+                    "email": "ops@acme.example",
+                    "avatar": "https://example.com/avatar/acme.png",
+                    "locale": "zh-CN",
+                    "time_zone": "Asia/Shanghai",
+                    "created_at": 1716960000,
                     "restrictions": {
-                      "allow_subdomain": true,
+                      "ips": [
+                        "203.0.113.0/24"
+                      ],
                       "email_domains": [
                         "acme.example"
                       ],
-                      "ips": [
-                        "203.0.113.0/24"
-                      ]
-                    },
-                    "time_zone": "Asia/Shanghai"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/AccountInfo"
-                        }
-                      },
-                      "type": "object"
+                      "allow_subdomain": true
                     }
-                  ]
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -33538,6 +34632,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -33545,82 +34642,69 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "security": [
-          {
-            "AppKeyAuth": []
-          }
-        ],
-        "summary": "Get account detail",
-        "tags": [
-          "Platform/Account"
-        ],
         "x-mint": {
-          "content": "| Permission | Description |\n| --- | --- |\n| None | None — any valid app_key can call this operation. |\n\nFind this operation in the [Platform API reference](/en/api-reference/platform/account/account-read-info).",
-          "href": "/en/api-reference/platform/account/account-read-info",
           "metadata": {
             "sidebarTitle": "Get account detail"
-          }
+          },
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — but see the credential requirement under Usage |\n\n## Usage\n\n- Requires the account owner's credentials (for example an app key created by the account owner); member credentials return `401 Unauthorized`. Members can use `POST /member/info` instead.\n- `restrictions` is present only when join or access restrictions have been configured; `mp_plat` and `mp_account_id` only for accounts provisioned through a cloud marketplace.",
+          "href": "/en/api-reference/platform/account/account-read-info"
         }
       }
     },
     "/alert-event/list": {
       "post": {
-        "description": "Return a cursor-paginated list of raw alert events across all alerts, with filtering by integration, channel, time range, and severity.",
         "operationId": "alert-event-read-list",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "end_time": 1712707200,
-                "limit": 20,
-                "severities": "Critical",
-                "start_time": 1712620800
-              },
-              "schema": {
-                "$ref": "#/components/schemas/AlertEventGlobalListRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "List raw alert events",
+        "description": "Return a cursor-paginated list of raw alert events across all alerts, with filtering by integration, channel, time range, and severity.",
+        "tags": [
+          "On-call/Alerts"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Both `start_time` and `end_time` are required Unix epoch seconds. `start_time` must be less than `end_time`; the span must not exceed 31 days.\n- Results are filtered by the caller's channel data-access permissions.\n- `severities` is a comma-separated list matched against `event_severity`, e.g. `\"Critical,Warning\"`. Values are not validated, so an unknown value (or `Ok`) matches nothing.\n- Pass `search_after_ctx` from the previous response for the next page; without it, `p`/`limit` page numbers apply and `p * limit` must stay within 10,000.",
+          "href": "/en/api-reference/on-call/alerts/alert-event-read-list",
+          "metadata": {
+            "sidebarTitle": "List raw alert events"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "has_next_page": false,
-                    "items": [
-                      {
-                        "alert_id": "663a1b2c3d4e5f6789abcdef",
-                        "event_id": "663a1b2c3d4e5f6789abc001",
-                        "event_severity": "Critical",
-                        "event_time": 1712650000,
-                        "title": "CPU usage > 90%"
-                      }
-                    ],
-                    "total": 1
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/AlertEventGlobalListResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "total": 1,
+                    "has_next_page": false,
+                    "items": [
+                      {
+                        "event_id": "663a1b2c3d4e5f6789abc001",
+                        "alert_id": "663a1b2c3d4e5f6789abcdef",
+                        "title": "CPU usage > 90%",
+                        "event_severity": "Critical",
+                        "event_time": 1712650000
+                      }
+                    ],
+                    "search_after_ctx": "663a1b2c3d4e5f6789abc001"
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -33628,6 +34712,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -33635,80 +34722,82 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "List raw alert events",
-        "tags": [
-          "On-call/Alerts"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Read** (`on-call`) |\n\n## Usage\n\n- Both `start_time` and `end_time` are required Unix epoch seconds. `start_time` must be less than `end_time`; the span must not exceed 31 days.\n- Results are filtered by the caller's channel data-access permissions.\n- `severities` is a comma-separated string, e.g. `\"Critical,Warning\"`.",
-          "href": "/en/api-reference/on-call/alerts/alert-event-read-list",
-          "metadata": {
-            "sidebarTitle": "List raw alert events"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/AlertEventGlobalListRequest"
+              },
+              "example": {
+                "start_time": 1712620800,
+                "end_time": 1712707200,
+                "limit": 20,
+                "severities": "Critical"
+              }
+            }
           }
         }
       }
     },
     "/alert/event/list": {
       "post": {
-        "description": "Return raw events for an alert with cursor or page-number pagination.",
         "operationId": "alert-read-event-list",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "alert_id": "663a1b2c3d4e5f6789abcdef",
-                "limit": 20
-              },
-              "schema": {
-                "$ref": "#/components/schemas/AlertEventListRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "List events for an alert",
+        "description": "Return raw events for an alert with cursor or page-number pagination.",
+        "tags": [
+          "On-call/Alerts"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Read** (`on-call`) or **Channels Manage** (`on-call`) or **Incidents Read** (`on-call`) or **Incidents Manage** (`on-call`) |\n\n## Usage\n\n- Results are newest-first by default. Set `asc=true` to read events oldest-first.\n- Use `limit` with `search_after_ctx` from the previous response to fetch the next page.\n- Classic page-number pagination is also supported with `p`, but `p * limit` must stay within 10,000 records.\n- An `alert_id` not found in the account returns `InvalidParameter`.",
+          "href": "/en/api-reference/on-call/alerts/alert-read-event-list",
+          "metadata": {
+            "sidebarTitle": "List events for an alert"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "has_next_page": true,
-                    "items": [
-                      {
-                        "alert_id": "663a1b2c3d4e5f6789abcdef",
-                        "event_id": "663a1b2c3d4e5f6789abc001",
-                        "event_severity": "Critical",
-                        "event_status": "Critical",
-                        "event_time": 1712650000,
-                        "labels": {
-                          "host": "web-01"
-                        },
-                        "title": "CPU usage > 90%"
-                      }
-                    ],
-                    "search_after_ctx": "663a1b2c3d4e5f6789abc001",
-                    "total": 57
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/AlertEventListResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "total": 57,
+                    "has_next_page": true,
+                    "search_after_ctx": "663a1b2c3d4e5f6789abc001",
+                    "items": [
+                      {
+                        "event_id": "663a1b2c3d4e5f6789abc001",
+                        "alert_id": "663a1b2c3d4e5f6789abcdef",
+                        "title": "CPU usage > 90%",
+                        "event_severity": "Critical",
+                        "event_status": "Critical",
+                        "event_time": 1712650000,
+                        "labels": {
+                          "host": "web-01"
+                        }
+                      }
+                    ]
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -33716,6 +34805,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -33723,77 +34815,78 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "List events for an alert",
-        "tags": [
-          "On-call/Alerts"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Read** (`on-call`) |\n\n## Usage\n\n- Results are newest-first by default. Set `asc=true` to read events oldest-first.\n- Use `limit` with `search_after_ctx` from the previous response to fetch the next page.\n- Classic page-number pagination is also supported with `p`, but `p * limit` must stay within 10,000 records.\n- Each alert can accumulate a large raw event history; prefer cursor pagination for hot alerts.",
-          "href": "/en/api-reference/on-call/alerts/alert-read-event-list",
-          "metadata": {
-            "sidebarTitle": "List events for an alert"
-          }
-        }
-      }
-    },
-    "/alert/feed": {
-      "post": {
-        "description": "Return the activity feed (comments, state changes, merges, silence events) for a single alert, with page-based pagination.",
-        "operationId": "alert-read-feed",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/AlertEventListRequest"
+              },
               "example": {
                 "alert_id": "663a1b2c3d4e5f6789abcdef",
-                "asc": false,
                 "limit": 20
-              },
-              "schema": {
-                "$ref": "#/components/schemas/AlertFeedRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/alert/feed": {
+      "post": {
+        "operationId": "alert-read-feed",
+        "summary": "List alert activity feed",
+        "description": "Return the activity feed (comments, state changes, merges, silence events) for a single alert, with page-based pagination.",
+        "tags": [
+          "On-call/Alerts"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Use `p` (page number, starting at 1) and `limit` (max 100, default 20) for pagination.\n- Set `asc` to `true` for chronological order.\n- Use `types` to filter by specific feed types (e.g. `a_comm`, `a_merge`).\n- An `alert_id` not found in the account returns `InvalidParameter`.",
+          "href": "/en/api-reference/on-call/alerts/alert-read-feed",
+          "metadata": {
+            "sidebarTitle": "List alert activity feed"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "has_next_page": false,
-                    "items": [
-                      {
-                        "created_at": 1712651000,
-                        "creator_id": 80011,
-                        "detail": {
-                          "comment": "Investigating now."
-                        },
-                        "ref_id": "663a1b2c3d4e5f6789abcdef",
-                        "type": "a_comm"
-                      }
-                    ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/AlertFeedResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "has_next_page": false,
+                    "items": [
+                      {
+                        "ref_id": "663a1b2c3d4e5f6789abcdef",
+                        "type": "a_comm",
+                        "detail": {
+                          "comment": "Investigating now."
+                        },
+                        "account_id": 10023,
+                        "creator_id": 80011,
+                        "created_at": 1712651000000,
+                        "updated_at": 1712651000000
+                      }
+                    ]
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -33801,6 +34894,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -33808,69 +34904,71 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "List alert activity feed",
-        "tags": [
-          "On-call/Alerts"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Read** (`on-call`) |\n\n## Usage\n\n- Use `p` (page number, starting at 1) and `limit` (max 100, default 20) for pagination.\n- Set `asc` to `true` for chronological order.\n- Use `types` to filter by specific feed types (e.g. `a_comm`, `a_merge`).",
-          "href": "/en/api-reference/on-call/alerts/alert-read-feed",
-          "metadata": {
-            "sidebarTitle": "List alert activity feed"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/AlertFeedRequest"
+              },
+              "example": {
+                "alert_id": "663a1b2c3d4e5f6789abcdef",
+                "limit": 20,
+                "asc": false
+              }
+            }
           }
         }
       }
     },
     "/alert/info": {
       "post": {
-        "description": "Return the full details of a single alert by its ID, including its associated incident and event count.",
         "operationId": "alert-read-info",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "alert_id": "663a1b2c3d4e5f6789abcdef"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/AlertInfoRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "Get alert detail",
+        "description": "Return the full details of a single alert by its ID, including its associated incident and event count.",
+        "tags": [
+          "On-call/Alerts"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Read** (`on-call`) or **Channels Manage** (`on-call`) or **Incidents Read** (`on-call`) or **Incidents Manage** (`on-call`) |\n\n## Usage\n\n- `alert_id` is an ObjectID hex string returned by `POST /alert/list` or `POST /alert-event/list`.\n- An `alert_id` not found in the account returns `InvalidParameter`.",
+          "href": "/en/api-reference/on-call/alerts/alert-read-info",
+          "metadata": {
+            "sidebarTitle": "Get alert detail"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "alert_id": "663a1b2c3d4e5f6789abcdef",
-                    "alert_severity": "Critical",
-                    "alert_status": "Critical",
-                    "event_cnt": 3,
-                    "start_time": 1712650000,
-                    "title": "CPU usage > 90%"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/AlertItem"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "alert_id": "663a1b2c3d4e5f6789abcdef",
+                    "title": "CPU usage > 90%",
+                    "alert_severity": "Critical",
+                    "alert_status": "Critical",
+                    "start_time": 1712650000,
+                    "event_cnt": 3
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -33878,6 +34976,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -33885,92 +34986,90 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Get alert detail",
-        "tags": [
-          "On-call/Alerts"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Read** (`on-call`) |\n\n## Usage\n\n- `alert_id` is an ObjectID hex string returned by `POST /alert/list` or `POST /alert-event/list`.",
-          "href": "/en/api-reference/on-call/alerts/alert-read-info",
-          "metadata": {
-            "sidebarTitle": "Get alert detail"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/AlertInfoRequest"
+              },
+              "example": {
+                "alert_id": "663a1b2c3d4e5f6789abcdef"
+              }
+            }
           }
         }
       }
     },
     "/alert/list": {
       "post": {
-        "description": "Return a cursor-paginated list of alerts matching the given filters.",
         "operationId": "alert-read-list",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "end_time": 1712707200,
-                "is_active": true,
-                "limit": 20,
-                "start_time": 1712620800
-              },
-              "schema": {
-                "$ref": "#/components/schemas/AlertListRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "List alerts",
+        "description": "Return a cursor-paginated list of alerts matching the given filters.",
+        "tags": [
+          "On-call/Alerts"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Read** (`on-call`) or **Channels Manage** (`on-call`) or **Incidents Read** (`on-call`) or **Incidents Manage** (`on-call`) or **Integrations Read** (`on-call`) or **Integrations Manage** (`on-call`) |\n\n## Usage\n\n- `start_time` and `end_time` are required Unix seconds and filter on the alert's `start_time`; the span must not exceed 31 days.\n- With `by_updated_at: true`, an `updated_at` window with the same bounds is added on top of the `start_time` filter, and the span must not exceed 7 days.\n- A `start_time` earlier than the account's data retention period is moved up to the retention start; an `end_time` before that start returns `InvalidParameter`.\n- Pass `search_after_ctx` from the previous response for the next page; without it, `p`/`limit` page numbers apply and `p * limit` must stay within 10,000.\n- `total` is capped at 1,000. In page-number mode `has_next_page` is computed from that capped total, so it turns `false` once you reach 1,000 alerts even when more match. Every non-empty page returns `search_after_ctx` for its last alert; to read past 1,000, pass it back and continue in cursor mode, where `has_next_page` is exact.\n- Results are filtered by the caller's channel data-access permissions.\n- Set `is_active` to `true` to retrieve only active (firing) alerts; `false` to retrieve resolved alerts.",
+          "href": "/en/api-reference/on-call/alerts/alert-read-list",
+          "metadata": {
+            "sidebarTitle": "List alerts"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/AlertListResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
+                    "total": 1,
                     "has_next_page": false,
                     "items": [
                       {
-                        "account_id": 10023,
                         "alert_id": "663a1b2c3d4e5f6789abcdef",
+                        "integration_id": 10001,
+                        "channel_id": 20001,
+                        "account_id": 10023,
+                        "title": "CPU usage > 90%",
                         "alert_severity": "Critical",
                         "alert_status": "Critical",
-                        "channel_id": 20001,
-                        "channel_name": "Production",
-                        "created_at": 1712650000,
+                        "start_time": 1712650000,
+                        "last_time": 1712655000,
                         "end_time": 0,
-                        "event_cnt": 3,
-                        "ever_muted": false,
-                        "integration_id": 10001,
-                        "integration_name": "Prometheus",
-                        "integration_type": "prometheus",
                         "labels": {
                           "host": "web-01"
                         },
-                        "last_time": 1712655000,
-                        "start_time": 1712650000,
-                        "title": "CPU usage > 90%",
-                        "updated_at": 1712655000
+                        "ever_muted": false,
+                        "created_at": 1712650000,
+                        "updated_at": 1712655000,
+                        "integration_name": "Prometheus",
+                        "integration_type": "prometheus",
+                        "channel_name": "Production",
+                        "event_cnt": 3
                       }
                     ],
-                    "total": 1
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/AlertListResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                    "search_after_ctx": "663a1b2c3d4e5f6789abcdef"
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -33978,6 +35077,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -33985,73 +35087,74 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "List alerts",
-        "tags": [
-          "On-call/Alerts"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Read** (`on-call`) |\n\n## Usage\n\n- Both `start_time` and `end_time` are required Unix epoch seconds. Maximum span is 31 days.\n- Use `search_after_ctx` from the previous response to fetch the next page.\n- Results are filtered by the caller's channel data-access permissions.\n- Set `is_active` to `true` to retrieve only active (firing) alerts; `false` to retrieve resolved alerts.",
-          "href": "/en/api-reference/on-call/alerts/alert-read-list",
-          "metadata": {
-            "sidebarTitle": "List alerts"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/AlertListRequest"
+              },
+              "example": {
+                "start_time": 1712620800,
+                "end_time": 1712707200,
+                "limit": 20,
+                "is_active": true
+              }
+            }
           }
         }
       }
     },
     "/alert/list-by-ids": {
       "post": {
-        "description": "Return the details of multiple alerts by their IDs in a single request. Note: this endpoint does not paginate — `total` and `has_next_page` are always `0`/`false` and `search_after_ctx` is never set.",
         "operationId": "alert-read-list-by-ids",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "alert_ids": [
-                  "663a1b2c3d4e5f6789abcdef"
-                ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/AlertListByIDsRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "List alerts by IDs",
+        "description": "Return the details of several alerts by ID in one request, without pagination.",
+        "tags": [
+          "On-call/Alerts"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Read** (`on-call`) or **Channels Manage** (`on-call`) or **Incidents Read** (`on-call`) or **Incidents Manage** (`on-call`) |\n\n## Usage\n\n- A malformed ID fails the request with `InvalidParameter`; well-formed IDs not found in the account are left out of `items`.\n- The response is not paginated: `total` is always `0`, `has_next_page` is always `false`, and `search_after_ctx` is omitted.",
+          "href": "/en/api-reference/on-call/alerts/alert-read-list-by-ids",
+          "metadata": {
+            "sidebarTitle": "List alerts by IDs"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "has_next_page": false,
-                    "items": [
-                      {
-                        "alert_id": "663a1b2c3d4e5f6789abcdef",
-                        "title": "CPU usage > 90%"
-                      }
-                    ],
-                    "total": 0
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/AlertListResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "total": 0,
+                    "has_next_page": false,
+                    "items": [
+                      {
+                        "alert_id": "663a1b2c3d4e5f6789abcdef",
+                        "title": "CPU usage > 90%"
+                      }
+                    ]
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -34059,6 +35162,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -34066,65 +35172,64 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "List alerts by IDs",
-        "tags": [
-          "On-call/Alerts"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Read** (`on-call`) |\n\n## Usage\n\n- All provided `alert_ids` must belong to the caller's account; any invalid ID causes the entire request to fail.",
-          "href": "/en/api-reference/on-call/alerts/alert-read-list-by-ids",
-          "metadata": {
-            "sidebarTitle": "List alerts by IDs"
-          }
-        }
-      }
-    },
-    "/alert/merge": {
-      "post": {
-        "description": "Associate one or more alerts with an existing incident. If a source alert previously belonged to a different incident and that incident becomes empty after the merge, it will be automatically closed.",
-        "operationId": "alert-write-merge",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/AlertListByIDsRequest"
+              },
               "example": {
                 "alert_ids": [
                   "663a1b2c3d4e5f6789abcdef"
-                ],
-                "incident_id": "663a000000000000deadbeef"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/AlertMergeRequest"
+                ]
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/alert/merge": {
+      "post": {
+        "operationId": "alert-write-merge",
+        "summary": "Merge alerts into an incident",
+        "description": "Move one or more alerts into an existing incident and close source incidents left empty.",
+        "tags": [
+          "On-call/Alerts"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Every `alert_ids` entry and the `incident_id` must belong to the account; an unknown ID returns `InvalidParameter`.\n- Alerts already in the target incident are skipped. A source incident left with no alerts is closed.\n- `title` and `owner_id` update the target incident only when they differ from its current values.\n- Only one incident change runs per account at a time; a concurrent call returns `RequestTooFrequently`.",
+          "href": "/en/api-reference/on-call/alerts/alert-write-merge",
+          "metadata": {
+            "sidebarTitle": "Merge alerts into an incident"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/EmptyResponse"
+                          "$ref": "#/components/schemas/EmptyObject"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -34132,6 +35237,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -34139,47 +35247,66 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Merge alerts into an incident",
-        "tags": [
-          "On-call/Alerts"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Read** (`on-call`) |\n\n## Usage\n\n- All `alert_ids` and the `incident_id` must belong to the caller's account.\n- Optionally set `title` and `owner_id` to update the target incident at the same time.",
-          "href": "/en/api-reference/on-call/alerts/alert-write-merge",
-          "metadata": {
-            "sidebarTitle": "Merge alerts into an incident"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/AlertMergeRequest"
+              },
+              "example": {
+                "alert_ids": [
+                  "663a1b2c3d4e5f6789abcdef"
+                ],
+                "incident_id": "663a000000000000deadbeef"
+              }
+            }
           }
         }
       }
     },
     "/alert/pipeline/info": {
       "post": {
-        "description": "Return the alert processing pipeline configured for a specific integration.",
         "operationId": "alert-read-pipeline-info",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "integration_id": 10001
-              },
-              "schema": {
-                "$ref": "#/components/schemas/AlertPipelineInfoRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "Get alert pipeline",
+        "description": "Return the alert processing pipeline configured for a specific integration.",
+        "tags": [
+          "On-call/Alerts"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Read** (`on-call`) or **Channels Manage** (`on-call`) or **Integrations Read** (`on-call`) or **Integrations Manage** (`on-call`) |\n\n## Usage\n\n- When the integration has no pipeline, the response carries only `request_id` and the `data` field is omitted.\n- `integration_id` may be any account-level or channel-owned integration of the account; an unknown ID returns `InvalidParameter`.",
+          "href": "/en/api-reference/on-call/alerts/alert-read-pipeline-info",
+          "metadata": {
+            "sidebarTitle": "Get alert pipeline"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/AlertPipelineItem"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
-                    "created_at": 1710000000,
-                    "creator_id": 80011,
                     "integration_id": 10001,
                     "rules": [
                       {
+                        "kind": "title_reset",
                         "if": [
                           {
                             "key": "labels.env",
@@ -34189,43 +35316,27 @@
                             ]
                           }
                         ],
-                        "kind": "title_reset",
                         "settings": {
                           "title": "[TPL]{{.Labels.service}} / {{.Labels.check}}"
                         }
                       },
                       {
-                        "if": null,
                         "kind": "severity_reset",
+                        "if": null,
                         "settings": {
                           "severity": "Warning"
                         }
                       }
                     ],
                     "status": "enabled",
-                    "updated_at": 1712000000,
-                    "updated_by": 80011
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/AlertPipelineItem"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                    "creator_id": 80011,
+                    "updated_by": 80011,
+                    "created_at": 1710000000,
+                    "updated_at": 1712000000
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -34233,6 +35344,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -34240,52 +35354,65 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Get alert pipeline",
-        "tags": [
-          "On-call/Alerts"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Integrations Read** (`on-call`) |\n\n## Usage\n\n- Returns `null` data if no pipeline has been configured for the given integration.\n- Requires the caller to have access to the integration.",
-          "href": "/en/api-reference/on-call/alerts/alert-read-pipeline-info",
-          "metadata": {
-            "sidebarTitle": "Get alert pipeline"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/AlertPipelineInfoRequest"
+              },
+              "example": {
+                "integration_id": 10001
+              }
+            }
           }
         }
       }
     },
     "/alert/pipeline/list": {
       "post": {
-        "description": "Return the alert processing pipelines configured for multiple integrations.",
         "operationId": "alert-read-pipeline-list",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "integration_ids": [
-                  10001,
-                  10002
-                ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/AlertPipelineListRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "List alert pipelines",
+        "description": "Return the alert processing pipelines configured for multiple integrations.",
+        "tags": [
+          "On-call/Alerts"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Integrations Read** (`on-call`) or **Integrations Manage** (`on-call`) |\n\n## Usage\n\n- Every `integration_ids` entry must be an integration of the account; one unknown ID fails the whole request with `InvalidParameter`.\n- `items` holds one entry per integration that has a pipeline; integrations without one are absent.",
+          "href": "/en/api-reference/on-call/alerts/alert-read-pipeline-list",
+          "metadata": {
+            "sidebarTitle": "List alert pipelines"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/AlertPipelineListResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "items": [
                       {
-                        "created_at": 1710000000,
-                        "creator_id": 80011,
                         "integration_id": 10001,
                         "rules": [
                           {
+                            "kind": "alert_inhibit",
                             "if": [
                               {
                                 "key": "labels.cluster",
@@ -34295,14 +35422,13 @@
                                 ]
                               }
                             ],
-                            "kind": "alert_inhibit",
                             "settings": {
                               "equals": [
-                                "service"
+                                "labels.service"
                               ],
                               "source_filters": [
                                 {
-                                  "key": "alert_severity",
+                                  "key": "severity",
                                   "oper": "IN",
                                   "vals": [
                                     "Critical"
@@ -34313,31 +35439,91 @@
                           }
                         ],
                         "status": "enabled",
-                        "updated_at": 1712000000,
-                        "updated_by": 80011
+                        "creator_id": 80011,
+                        "updated_by": 80011,
+                        "created_at": 1710000000,
+                        "updated_at": 1712000000
                       }
                     ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "429": {
+            "$ref": "#/components/responses/TooManyRequests"
+          },
+          "500": {
+            "$ref": "#/components/responses/ServerError"
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/AlertPipelineListRequest"
+              },
+              "example": {
+                "integration_ids": [
+                  10001,
+                  10002
+                ]
+              }
+            }
+          }
+        }
+      }
+    },
+    "/alert/pipeline/upsert": {
+      "post": {
+        "operationId": "alert-write-pipeline-upsert",
+        "summary": "Create or update alert pipeline",
+        "description": "Set the alert processing pipeline for an integration. Replaces the existing configuration entirely.",
+        "tags": [
+          "On-call/Alerts"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) or **Integrations Manage** (`on-call`) |\n\n## Usage\n\n- Replaces the integration's whole rule list with `rules`; an empty array removes every rule. At most 50 rules.\n- Rules run in array order on each incoming event of the integration before it becomes an alert; `alert_drop`, or an `alert_inhibit` that matches, discards the event and stops processing.\n- `integration_id` may be an account-level or a channel-owned integration; an ID not in the account returns `InvalidParameter`.\n- Write access also requires object permission: the account owner, an administrator, the integration creator, or a member of its team (for a channel-owned integration, a member of the channel's team); with no team, any caller with the API permission may write.\n- An `alert_inhibit` rule requires the Standard plan or higher; otherwise the call returns `NoLicense`.\n- On success the response carries only `request_id`; the `data` field is omitted.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "href": "/en/api-reference/on-call/alerts/alert-write-pipeline-upsert",
+          "metadata": {
+            "sidebarTitle": "Create or update alert pipeline"
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/AlertPipelineListResponse"
+                          "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -34345,6 +35531,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -34352,30 +35541,18 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "List alert pipelines",
-        "tags": [
-          "On-call/Alerts"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Integrations Read** (`on-call`) |\n\n## Usage\n\n- All `integration_ids` must be accessible to the caller.",
-          "href": "/en/api-reference/on-call/alerts/alert-read-pipeline-list",
-          "metadata": {
-            "sidebarTitle": "List alert pipelines"
-          }
-        }
-      }
-    },
-    "/alert/pipeline/upsert": {
-      "post": {
-        "description": "Set the alert processing pipeline for an integration. Replaces the existing configuration entirely.",
-        "operationId": "alert-write-pipeline-upsert",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/AlertPipelineUpsertRequest"
+              },
               "example": {
                 "integration_id": 10001,
                 "rules": [
                   {
+                    "kind": "title_reset",
                     "if": [
                       {
                         "key": "labels.env",
@@ -34385,53 +35562,80 @@
                         ]
                       }
                     ],
-                    "kind": "title_reset",
                     "settings": {
                       "title": "[TPL]{{.Labels.service}} / {{.Labels.check}}"
                     }
                   },
                   {
-                    "if": null,
                     "kind": "severity_reset",
+                    "if": null,
                     "settings": {
                       "severity": "Warning"
                     }
                   }
                 ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/AlertPipelineUpsertRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/audit/operation/list": {
+      "post": {
+        "operationId": "audit-read-operation-list",
+        "summary": "List auditable operation types",
+        "description": "Return all operation names that are recorded in the audit log, for use as `operations` filter values.",
+        "tags": [
+          "Platform/Audit logs"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Audit Read** (`organization`) |\n\n## Usage\n\n- Use the `name` values from this response as `operations` filter values in `POST /audit/search`.\n- `name_cn` is the Chinese label shown in the console, returned in Chinese regardless of the request language; `name` is the stable value to filter on.",
+          "href": "/en/api-reference/platform/audit-logs/audit-read-operation-list",
+          "metadata": {
+            "sidebarTitle": "List auditable operation types"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": null,
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/EmptyResponse"
+                          "$ref": "#/components/schemas/AuditOperationListResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "items": [
+                      {
+                        "name": "template:write:create",
+                        "name_cn": "创建模板"
+                      },
+                      {
+                        "name": "template:write:delete",
+                        "name_cn": "删除模板"
+                      },
+                      {
+                        "name": "incident:write:acknowledge",
+                        "name_cn": "认领故障"
+                      }
+                    ]
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -34439,6 +35643,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -34446,75 +35653,82 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Create or update alert pipeline",
-        "tags": [
-          "On-call/Alerts"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Integrations Manage** (`on-call`) |\n\n## Usage\n\n- Maximum 50 rules per pipeline.\n- Each rule has a `kind` (one of `title_reset`, `description_reset`, `severity_reset`, `alert_drop`, `alert_inhibit`), an optional `if` filter, and `settings` specific to the kind.\n- The `alert_inhibit` kind requires the Standard license or higher.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
-          "href": "/en/api-reference/on-call/alerts/alert-write-pipeline-upsert",
-          "metadata": {
-            "sidebarTitle": "Create or update alert pipeline"
-          }
-        }
-      }
-    },
-    "/audit/operation/list": {
-      "post": {
-        "description": "Return all operation names that are recorded in the audit log, for use as `operations` filter values.",
-        "operationId": "audit-read-operation-list",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {},
               "schema": {
                 "$ref": "#/components/schemas/AuditOperationListRequest"
-              }
+              },
+              "example": {}
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/audit/search": {
+      "post": {
+        "operationId": "audit-read-search",
+        "summary": "Search audit logs",
+        "description": "Return a cursor-paginated list of audit log entries within a time range.",
+        "tags": [
+          "Platform/Audit logs"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Audit Read** (`organization`) |\n\n## Usage\n\n- Time range is required. Maximum span is 90 days. Both `start_time` and `end_time` are Unix epoch **seconds**.\n- Use `search_after_ctx` from the previous response to fetch the next page. The token is opaque — do not construct it manually.\n- The retention window depends on the account's license. Queries beyond the retention boundary silently return an empty result rather than an error.\n- Pass an explicit `limit` (1–99) for predictable paging; when it is omitted or 0 the server chooses the page size, which may be the whole result set. Entries are returned newest first.",
+          "href": "/en/api-reference/platform/audit-logs/audit-read-search",
+          "metadata": {
+            "sidebarTitle": "Search audit logs"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "items": [
-                      {
-                        "name": "template:write:create",
-                        "name_cn": "创建模板"
-                      },
-                      {
-                        "name": "template:write:delete",
-                        "name_cn": "删除模板"
-                      },
-                      {
-                        "name": "incident:write:acknowledge",
-                        "name_cn": "认领故障"
-                      }
-                    ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/AuditOperationListResponse"
+                          "$ref": "#/components/schemas/AuditSearchResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "total": 2,
+                    "search_after_ctx": "",
+                    "docs": [
+                      {
+                        "created_at": 1712700123456,
+                        "account_id": 10023,
+                        "member_id": 80011,
+                        "member_name": "Alice",
+                        "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                        "ip": "203.0.113.42",
+                        "operation": "template:write:create",
+                        "operation_name": "创建模板",
+                        "body": "{\"template_name\":\"Prod default\"}",
+                        "params": [],
+                        "is_dangerous": false,
+                        "is_write": true,
+                        "principal_kind": "member",
+                        "credential_type": "",
+                        "credential_id": 0
+                      }
+                    ]
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -34522,6 +35736,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -34529,90 +35746,71 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "List auditable operation types",
-        "tags": [
-          "Platform/Audit logs"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Audit Read** (`organization`) |\n\n## Usage\n\n- Use the `name` values from this response as `operations` filter values in `POST /audit/search`.\n- `name_cn` is the human-readable Chinese label shown in the console; `name` is the stable wire value to filter on.",
-          "href": "/en/api-reference/platform/audit-logs/audit-read-operation-list",
-          "metadata": {
-            "sidebarTitle": "List auditable operation types"
-          }
-        }
-      }
-    },
-    "/audit/search": {
-      "post": {
-        "description": "Return a cursor-paginated list of audit log entries within a time range.",
-        "operationId": "audit-read-search",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/AuditSearchRequest"
+              },
               "example": {
+                "start_time": 1712620800,
                 "end_time": 1712707200,
                 "limit": 20,
                 "operations": [
                   "template:write:create",
                   "template:write:delete"
-                ],
-                "start_time": 1712620800
-              },
-              "schema": {
-                "$ref": "#/components/schemas/AuditSearchRequest"
+                ]
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/calendar/create": {
+      "post": {
+        "operationId": "calendarCreate",
+        "summary": "Create calendar",
+        "description": "Create a personal service calendar with its weekly workdays and linked holiday calendars.",
+        "tags": [
+          "On-call/Calendars"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Calendars Manage** (`on-call`) |\n\n## Usage\n\n- A limit of 5 calendars is checked only when the caller is the account owner: once the account holds 5 calendars, the owner's create call returns `InvalidParameter`. Calls made by other members are not counted against this limit.\n- `cal_name` must be unique within the account, `timezone` must be a valid IANA name, and a nonzero `team_id` must be a team of the account; otherwise the call returns `InvalidParameter`.\n- Every call is recorded in the account audit log.",
+          "href": "/en/api-reference/on-call/calendars/calendar-create",
+          "metadata": {
+            "sidebarTitle": "Create calendar"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "docs": [
-                      {
-                        "account_id": 10023,
-                        "body": "{\"template_name\":\"Prod default\"}",
-                        "created_at": 1712700123456,
-                        "credential_id": 0,
-                        "credential_type": "",
-                        "ip": "203.0.113.42",
-                        "is_dangerous": false,
-                        "is_write": true,
-                        "member_id": 80011,
-                        "member_name": "Alice",
-                        "operation": "template:write:create",
-                        "operation_name": "创建模板",
-                        "params": [],
-                        "principal_kind": "member",
-                        "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                      }
-                    ],
-                    "search_after_ctx": "",
-                    "total": 2
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/AuditSearchResponse"
+                          "$ref": "#/components/schemas/CalendarCreateResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "cal_id": "cal.QiNvtdKs4Wj52kZhT3LafM",
+                    "cal_name": "API Test Calendar"
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -34620,6 +35818,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -34627,26 +35828,13 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Search audit logs",
-        "tags": [
-          "Platform/Audit logs"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Audit Read** (`organization`) |\n\n## Usage\n\n- Time range is required. Maximum span is 90 days. Both `start_time` and `end_time` are Unix epoch **seconds**.\n- Use `search_after_ctx` from the previous response to fetch the next page. The token is opaque — do not construct it manually.\n- The retention window depends on the account's license. Queries beyond the retention boundary silently return an empty result rather than an error.\n- `limit` accepts 0–99; omitting it (or 0) returns all matching rows in the window with no page-size cap. Rows are returned newest first.",
-          "href": "/en/api-reference/platform/audit-logs/audit-read-search",
-          "metadata": {
-            "sidebarTitle": "Search audit logs"
-          }
-        }
-      }
-    },
-    "/calendar/create": {
-      "post": {
-        "description": "Create a personal service calendar. Each account is limited to 5 calendars unless the Flashcat-Break-Cal-Limit header is set.",
-        "operationId": "calendarCreate",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CalendarCreateRequest"
+              },
               "example": {
                 "cal_name": "Production On-Call Calendar",
                 "description": "Calendar for production on-call team",
@@ -34658,43 +35846,53 @@
                   4,
                   5
                 ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/CalendarCreateRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/calendar/delete": {
+      "post": {
+        "operationId": "calendarDelete",
+        "summary": "Delete calendar",
+        "description": "Delete a personal service calendar and its events when no rule references it.",
+        "tags": [
+          "On-call/Calendars"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Calendars Manage** (`on-call`) |\n\n## Usage\n\n- If escalation rules or silence rules still use the calendar, the call returns HTTP 400 with `error.code` = `ReferenceExist` and `data.refs` listing them.\n- The calendar's own events are deleted together with it.\n- Only personal calendars can be changed, and only by the account owner, an administrator, the calendar creator, or a member of the calendar's team; other callers get `AccessDenied`.\n- Every call is recorded in the account audit log.",
+          "href": "/en/api-reference/on-call/calendars/calendar-delete",
+          "metadata": {
+            "sidebarTitle": "Delete calendar"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "cal_id": "cal.QiNvtdKs4Wj52kZhT3LafM",
-                    "cal_name": "API Test Calendar"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/CalendarCreateResponse"
+                          "$ref": "#/components/schemas/CalendarEmptyObject"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -34702,6 +35900,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -34709,62 +35910,62 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Create calendar",
-        "tags": [
-          "On-call/Calendars"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Calendars Manage** (`on-call`) |",
-          "href": "/en/api-reference/on-call/calendars/calendar-create",
-          "metadata": {
-            "sidebarTitle": "Create calendar"
-          }
-        }
-      }
-    },
-    "/calendar/delete": {
-      "post": {
-        "description": "Delete a personal service calendar. The call fails when referenced by escalation or silence rules.",
-        "operationId": "calendarDelete",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {
-                "cal_id": "cal.QiNvtdKs4Wj52kZhT3LafM"
-              },
               "schema": {
                 "$ref": "#/components/schemas/CalendarIDRequest"
+              },
+              "example": {
+                "cal_id": "cal.QiNvtdKs4Wj52kZhT3LafM"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/calendar/event/delete": {
+      "post": {
+        "operationId": "calEventDelete",
+        "summary": "Delete calendar event",
+        "description": "Delete one personal-calendar event by ID, or clear the calendar's own events from a date range.",
+        "tags": [
+          "On-call/Calendars"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Calendars Manage** (`on-call`) |\n\n## Usage\n\n- Pass either `event_id`, or both `start_at` and `end_at` (dates in `YYYY-MM-DD`, covering [`start_at`, `end_at`)); any other combination returns `InvalidParameter`.\n- Cleared days fall back to the linked holiday calendars and the weekly workdays.\n- Only personal calendars can be changed, and only by the account owner, an administrator, the calendar creator, or a member of the calendar's team; other callers get `AccessDenied`.\n- Every call is recorded in the account audit log.",
+          "href": "/en/api-reference/on-call/calendars/cal-event-delete",
+          "metadata": {
+            "sidebarTitle": "Delete calendar event"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/CalendarEmptyObject"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -34772,6 +35973,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -34779,140 +35983,85 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Delete calendar",
-        "tags": [
-          "On-call/Calendars"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Calendars Manage** (`on-call`) |",
-          "href": "/en/api-reference/on-call/calendars/calendar-delete",
-          "metadata": {
-            "sidebarTitle": "Delete calendar"
-          }
-        }
-      }
-    },
-    "/calendar/event/delete": {
-      "post": {
-        "description": "Delete one event of a personal calendar by event_id, or clear the calendar's own events off the days [start_at, end_at). Pass either event_id or both start_at and end_at. Cleared days fall back to the linked holiday calendars and the weekly workdays.",
-        "operationId": "calEventDelete",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CalEventIDRequest"
+              },
               "example": {
                 "cal_id": "cal.QiNvtdKs4Wj52kZhT3LafM",
                 "event_id": "cale.KyG9XWTCU5CucbwukEVBQ4"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/CalEventIDRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/calendar/event/list": {
+      "post": {
+        "operationId": "calEventList",
+        "summary": "List calendar events",
+        "description": "Return a personal calendar's events for a year, month or day, plus the resolved state of each day.",
+        "tags": [
+          "On-call/Calendars"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- `year` defaults to the current year; without `month` the whole year is returned, and `day` requires `month`.\n- `items` merges the calendar's own events (`cale.*` IDs), one generated `non_work.YYYYMMDD` entry per non-working weekday when `workdays` is set, and the events of the linked holiday calendars; `total` counts all of them.\n- `days` gives the resolved state of every day in the scope.\n- Only personal calendars (`cal_id` starting with `cal.`) are supported; other IDs return `InvalidParameter`.",
+          "href": "/en/api-reference/on-call/calendars/cal-event-list",
+          "metadata": {
+            "sidebarTitle": "List calendar events"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/CalendarEmptyObject"
+                          "$ref": "#/components/schemas/CalEventListResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
-                }
-              }
-            },
-            "description": "Success"
-          },
-          "400": {
-            "$ref": "#/components/responses/BadRequest"
-          },
-          "401": {
-            "$ref": "#/components/responses/Unauthorized"
-          },
-          "429": {
-            "$ref": "#/components/responses/TooManyRequests"
-          },
-          "500": {
-            "$ref": "#/components/responses/ServerError"
-          }
-        },
-        "summary": "Delete calendar event",
-        "tags": [
-          "On-call/Calendars"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Calendars Manage** (`on-call`) |",
-          "href": "/en/api-reference/on-call/calendars/cal-event-delete",
-          "metadata": {
-            "sidebarTitle": "Delete calendar event"
-          }
-        }
-      }
-    },
-    "/calendar/event/list": {
-      "post": {
-        "description": "Return events for a personal calendar within a year/month/day scope. When month and day are both omitted the whole year is returned. The response also carries days, the resolved state of every day in the scope.",
-        "operationId": "calEventList",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "cal_id": "cal.QiNvtdKs4Wj52kZhT3LafM",
-                "month": 5,
-                "year": 2024
-              },
-              "schema": {
-                "$ref": "#/components/schemas/CalEventListRequest"
-              }
-            }
-          },
-          "required": true
-        },
-        "responses": {
-          "200": {
-            "content": {
-              "application/json": {
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "items": [
                       {
                         "account_id": 2451002751131,
-                        "cal_id": "cal.QiNvtdKs4Wj52kZhT3LafM",
-                        "created_at": 1775972034,
                         "creator_id": 2476444212131,
+                        "cal_id": "cal.QiNvtdKs4Wj52kZhT3LafM",
+                        "event_id": "cale.KyG9XWTCU5CucbwukEVBQ4",
+                        "summary": "Test Holiday",
                         "description": "A test holiday event",
+                        "start_at": "2026-05-01",
                         "end_at": "2026-05-02",
-                        "event_id": "cale.KyG9XWTCU5CucbwukEVBQ4",
                         "is_off": true,
-                        "start_at": "2026-05-01",
-                        "summary": "Test Holiday",
+                        "created_at": 1775972034,
                         "updated_at": 1775972034
                       },
                       {
                         "account_id": 2451002751131,
-                        "cal_id": "cal.QiNvtdKs4Wj52kZhT3LafM",
-                        "created_at": 0,
                         "creator_id": 2451002751131,
+                        "cal_id": "cal.QiNvtdKs4Wj52kZhT3LafM",
+                        "event_id": "non_work.20260502",
+                        "summary": "non-working day (Saturday)",
                         "description": "",
+                        "start_at": "2026-05-02",
                         "end_at": "2026-05-03",
-                        "event_id": "non_work.20260502",
                         "is_off": true,
-                        "start_at": "2026-05-02",
-                        "summary": "non-working day (Saturday)",
+                        "created_at": 0,
                         "updated_at": 0
                       }
                     ],
@@ -34937,27 +36086,10 @@
                         "is_off": false
                       }
                     }
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/CalEventListResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -34965,6 +36097,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -34972,71 +36107,68 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "List calendar events",
-        "tags": [
-          "On-call/Calendars"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |",
-          "href": "/en/api-reference/on-call/calendars/cal-event-list",
-          "metadata": {
-            "sidebarTitle": "List calendar events"
-          }
-        }
-      }
-    },
-    "/calendar/event/upsert": {
-      "post": {
-        "description": "Create or update an event the calendar owns (a day off or a working-day override) over the days [start_at, end_at). Omit event_id to create a new event; a given event_id must be an existing event of this calendar. The write clears the calendar's other own events off the same days: an event fully inside the range is deleted, one partly inside is shortened, and one spanning the range is split in two, so the latest write decides those days. end_at must be later than start_at.",
-        "operationId": "calEventUpsert",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CalEventListRequest"
+              },
               "example": {
                 "cal_id": "cal.QiNvtdKs4Wj52kZhT3LafM",
-                "description": "International Workers Day holiday",
-                "end_at": "2024-05-06",
-                "is_off": true,
-                "start_at": "2024-05-01",
-                "summary": "Labour Day"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/CalEventUpsertRequest"
+                "year": 2024,
+                "month": 5
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/calendar/event/upsert": {
+      "post": {
+        "operationId": "calEventUpsert",
+        "summary": "Upsert calendar event",
+        "description": "Create or update one of a personal calendar's own events: a day off or a working-day override.",
+        "tags": [
+          "On-call/Calendars"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Calendars Manage** (`on-call`) |\n\n## Usage\n\n- The event covers the days [`start_at`, `end_at`), dates in `YYYY-MM-DD`; `end_at` must be later than `start_at`.\n- Omit `event_id` to create an event; a given `event_id` must be an existing event of this calendar.\n- The write clears the calendar's other own events off the same days: an event fully inside the range is deleted, one partly inside is shortened, and one spanning the range is split in two, so the latest write decides those days.\n- Only personal calendars can be changed, and only by the account owner, an administrator, the calendar creator, or a member of the calendar's team; other callers get `AccessDenied`.\n- Every call is recorded in the account audit log.",
+          "href": "/en/api-reference/on-call/calendars/cal-event-upsert",
+          "metadata": {
+            "sidebarTitle": "Upsert calendar event"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "cal_id": "cal.QiNvtdKs4Wj52kZhT3LafM",
-                    "event_id": "cale.KyG9XWTCU5CucbwukEVBQ4",
-                    "summary": "Test Holiday"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/CalEventUpsertResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "cal_id": "cal.QiNvtdKs4Wj52kZhT3LafM",
+                    "event_id": "cale.KyG9XWTCU5CucbwukEVBQ4",
+                    "summary": "Test Holiday"
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -35044,6 +36176,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -35051,54 +36186,71 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Upsert calendar event",
-        "tags": [
-          "On-call/Calendars"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Calendars Manage** (`on-call`) |",
-          "href": "/en/api-reference/on-call/calendars/cal-event-upsert",
-          "metadata": {
-            "sidebarTitle": "Upsert calendar event"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CalEventUpsertRequest"
+              },
+              "example": {
+                "cal_id": "cal.QiNvtdKs4Wj52kZhT3LafM",
+                "summary": "Labour Day",
+                "start_at": "2024-05-01",
+                "end_at": "2024-05-06",
+                "is_off": true,
+                "description": "International Workers Day holiday"
+              }
+            }
           }
         }
       }
     },
     "/calendar/info": {
       "post": {
-        "description": "Return details of a service calendar.",
         "operationId": "calendarInfo",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "cal_id": "cal.eh9gvPtWeH3xXgKeVSRxRg"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/CalendarIDRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "Get calendar info",
+        "description": "Return the details of one service calendar of the account by its ID.",
+        "tags": [
+          "On-call/Calendars"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- An unknown `cal_id` returns `InvalidParameter`.",
+          "href": "/en/api-reference/on-call/calendars/calendar-info",
+          "metadata": {
+            "sidebarTitle": "Get calendar info"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/CalendarItem"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "account_id": 2451002751131,
+                    "team_id": 2477033058131,
                     "cal_id": "cal.eh9gvPtWeH3xXgKeVSRxRg",
                     "cal_name": "Stock Exchange Calendar",
-                    "created_at": 1702455630,
-                    "creator_id": 2476444212131,
                     "description": "A stock market trading calendar example",
-                    "kind": "personal",
-                    "status": "enabled",
-                    "team_id": 2477033058131,
                     "timezone": "Asia/Shanghai",
-                    "updated_at": 1775529526,
-                    "updated_by": 3790925372131,
+                    "kind": "personal",
                     "workdays": [
                       0,
                       1,
@@ -35107,28 +36259,16 @@
                       4,
                       5,
                       6
-                    ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/CalendarItem"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                    ],
+                    "created_at": 1702455630,
+                    "updated_at": 1775529526,
+                    "creator_id": 2476444212131,
+                    "updated_by": 3790925372131,
+                    "status": "enabled"
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -35136,6 +36276,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -35143,56 +36286,68 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Get calendar info",
-        "tags": [
-          "On-call/Calendars"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |",
-          "href": "/en/api-reference/on-call/calendars/calendar-info",
-          "metadata": {
-            "sidebarTitle": "Get calendar info"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CalendarIDRequest"
+              },
+              "example": {
+                "cal_id": "cal.eh9gvPtWeH3xXgKeVSRxRg"
+              }
+            }
           }
         }
       }
     },
     "/calendar/list": {
       "post": {
-        "description": "Return the list of service calendars visible to the current account.",
         "operationId": "calendarList",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "kind": "personal"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/CalendarListRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "List calendars",
+        "description": "Return the list of service calendars visible to the current account.",
+        "tags": [
+          "On-call/Calendars"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Without `kind`, personal calendars are returned. `region.official.holiday` returns public holiday calendars, filtered to the caller's locale unless `no_locale` is `true`; use their `cal_id` in `extra_cal_ids`.\n- The list is not paginated; `total` equals the number of items.",
+          "href": "/en/api-reference/on-call/calendars/calendar-list",
+          "metadata": {
+            "sidebarTitle": "List calendars"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/CalendarListResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "items": [
                       {
                         "account_id": 2451002751131,
+                        "team_id": 2477033058131,
                         "cal_id": "cal.eh9gvPtWeH3xXgKeVSRxRg",
                         "cal_name": "Stock Exchange Calendar",
-                        "created_at": 1702455630,
-                        "creator_id": 2476444212131,
                         "description": "A stock market trading calendar example",
-                        "kind": "personal",
-                        "status": "enabled",
-                        "team_id": 2477033058131,
                         "timezone": "Asia/Shanghai",
-                        "updated_at": 1775529526,
-                        "updated_by": 3790925372131,
+                        "kind": "personal",
                         "workdays": [
                           0,
                           1,
@@ -35201,48 +36356,108 @@
                           4,
                           5,
                           6
-                        ]
+                        ],
+                        "created_at": 1702455630,
+                        "updated_at": 1775529526,
+                        "creator_id": 2476444212131,
+                        "updated_by": 3790925372131,
+                        "status": "enabled"
                       },
                       {
                         "account_id": 2451002751131,
+                        "team_id": 0,
                         "cal_id": "cal.VZYkchxJhGELSF4jzkUAud",
                         "cal_name": "HK Stock Exchange Calendar",
-                        "created_at": 1702968470,
-                        "creator_id": 2451002751131,
                         "description": "Hong Kong Stock Exchange trading days calendar",
+                        "timezone": "Asia/Shanghai",
+                        "kind": "personal",
                         "extra_cal_ids": [
                           "zh-cn.china.official"
                         ],
-                        "kind": "personal",
-                        "status": "enabled",
-                        "team_id": 0,
-                        "timezone": "Asia/Shanghai",
+                        "created_at": 1702968470,
                         "updated_at": 1775188967,
-                        "updated_by": 3790925372131
+                        "creator_id": 2451002751131,
+                        "updated_by": 3790925372131,
+                        "status": "enabled"
                       }
                     ],
                     "total": 8
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "429": {
+            "$ref": "#/components/responses/TooManyRequests"
+          },
+          "500": {
+            "$ref": "#/components/responses/ServerError"
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CalendarListRequest"
+              },
+              "example": {
+                "kind": "personal"
+              }
+            }
+          }
+        }
+      }
+    },
+    "/calendar/update": {
+      "post": {
+        "operationId": "calendarUpdate",
+        "summary": "Update calendar",
+        "description": "Update a personal service calendar; only the fields you send are changed.",
+        "tags": [
+          "On-call/Calendars"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Calendars Manage** (`on-call`) |\n\n## Usage\n\n- Send at least one field besides `cal_id`; otherwise the call returns `InvalidParameter`.\n- `workdays` and `extra_cal_ids` replace the stored lists when sent (an empty array clears them); `team_id: 0` removes the team.\n- `cal_name` must stay unique within the account.\n- Only personal calendars can be changed, and only by the account owner, an administrator, the calendar creator, or a member of the calendar's team; other callers get `AccessDenied`.\n- On success the response carries only `request_id`; the `data` field is omitted.\n- Every call is recorded in the account audit log.",
+          "href": "/en/api-reference/on-call/calendars/calendar-update",
+          "metadata": {
+            "sidebarTitle": "Update calendar"
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/CalendarListResponse"
+                          "$ref": "#/components/schemas/CalendarEmptyObject"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -35250,6 +36465,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -35257,26 +36475,13 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "List calendars",
-        "tags": [
-          "On-call/Calendars"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |",
-          "href": "/en/api-reference/on-call/calendars/calendar-list",
-          "metadata": {
-            "sidebarTitle": "List calendars"
-          }
-        }
-      }
-    },
-    "/calendar/update": {
-      "post": {
-        "description": "Update a personal service calendar. Only non-null fields are updated.",
-        "operationId": "calendarUpdate",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CalendarUpdateRequest"
+              },
               "example": {
                 "cal_id": "cal.QiNvtdKs4Wj52kZhT3LafM",
                 "cal_name": "Production On-Call Calendar (Updated)",
@@ -35288,40 +36493,79 @@
                   4,
                   5
                 ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/CalendarUpdateRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/change/list": {
+      "post": {
+        "operationId": "change-read-list",
+        "summary": "List changes",
+        "description": "Query change records within a time window, with filtering, search, and pagination.",
+        "tags": [
+          "On-call/Changes"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- `start_time` and `end_time` are both required: `start_time` must be less than `end_time`, and the window can span at most 31 days.\n- A change matches when its `[start_time, last_time]` range overlaps the query window.\n- Set `include_events` to `true` to attach each change's underlying events in `events`.",
+          "href": "/en/api-reference/on-call/changes/change-read-list",
+          "metadata": {
+            "sidebarTitle": "List changes"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/CalendarEmptyObject"
+                          "$ref": "#/components/schemas/ListChangeResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "total": 1,
+                    "has_next_page": false,
+                    "items": [
+                      {
+                        "change_id": "664a1b2c3d4e5f6a7b8c9d0e",
+                        "account_id": 10001,
+                        "channel_id": 5001,
+                        "channel_name": "Production",
+                        "channel_status": "enabled",
+                        "integration_id": 362,
+                        "integration_name": "GitHub Deploy",
+                        "title": "Deploy api-server v2.3.1",
+                        "description": "Rolling deploy to production cluster",
+                        "change_key": "deploy-api-server-2311",
+                        "change_status": "Done",
+                        "start_time": 1716962400,
+                        "last_time": 1716962700,
+                        "end_time": 1716963000,
+                        "labels": {
+                          "service": "api-server",
+                          "env": "prod"
+                        },
+                        "link": "https://github.com/acme/api-server/actions/runs/123"
+                      }
+                    ]
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -35329,6 +36573,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -35336,97 +36583,74 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Update calendar",
-        "tags": [
-          "On-call/Calendars"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Calendars Manage** (`on-call`) |",
-          "href": "/en/api-reference/on-call/calendars/calendar-update",
-          "metadata": {
-            "sidebarTitle": "Update calendar"
-          }
-        }
-      }
-    },
-    "/change/list": {
-      "post": {
-        "description": "Query change records within a time window, with filtering, search, and pagination.",
-        "operationId": "change-read-list",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ListChangeRequest"
+              },
               "example": {
-                "asc": false,
+                "start_time": 1716960000,
                 "end_time": 1717046400,
-                "include_events": false,
+                "p": 1,
+                "limit": 10,
                 "integration_ids": [
                   362
                 ],
-                "limit": 10,
                 "orderby": "start_time",
-                "p": 1,
-                "start_time": 1716960000
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ListChangeRequest"
+                "asc": false,
+                "include_events": false
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/channel/create": {
+      "post": {
+        "operationId": "channelCreate",
+        "summary": "Create channel",
+        "description": "Create a channel, optionally with a default escalation rule and channel-exclusive integrations.",
+        "tags": [
+          "On-call/Channels"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |\n\n## Usage\n\n- `channel_name` must be unique within the account; a duplicate returns `InvalidParameter`.\n- `group.method` `p` requires the Standard license or higher and `i` requires the Pro license. Creating a channel beyond the plan's channel quota also returns `NoLicense`.\n- When `escalate_rule` is set, an enabled escalation rule named `Default` is created with one level that notifies `escalate_rule.target` once.\n- Each ID in `plugin_ids` creates one channel-exclusive integration of that integration type, named after the type.\n- When `is_external_report_enabled` is `true`, the response also carries `external_report_token`.\n- Every call is recorded in the account audit log.",
+          "href": "/en/api-reference/on-call/channels/channel-create",
+          "metadata": {
+            "sidebarTitle": "Create channel"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "has_next_page": false,
-                    "items": [
-                      {
-                        "account_id": 10001,
-                        "change_id": "664a1b2c3d4e5f6a7b8c9d0e",
-                        "change_key": "deploy-api-server-2311",
-                        "change_status": "Done",
-                        "channel_id": 5001,
-                        "channel_name": "Production",
-                        "channel_status": "enabled",
-                        "description": "Rolling deploy to production cluster",
-                        "end_time": 1716963000,
-                        "integration_id": 362,
-                        "integration_name": "GitHub Deploy",
-                        "labels": {
-                          "env": "prod",
-                          "service": "api-server"
-                        },
-                        "last_time": 1716962700,
-                        "link": "https://github.com/acme/api-server/actions/runs/123",
-                        "start_time": 1716962400,
-                        "title": "Deploy api-server v2.3.1"
-                      }
-                    ],
-                    "total": 1
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/ListChangeResponse"
+                          "$ref": "#/components/schemas/ChannelCreateResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "channel_id": 6294542005131,
+                    "channel_name": "Production Alerts"
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -35434,6 +36658,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -35441,74 +36668,76 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "List changes",
-        "tags": [
-          "On-call/Changes"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n",
-          "href": "/en/api-reference/on-call/changes/change-read-list",
-          "metadata": {
-            "sidebarTitle": "List changes"
-          }
-        }
-      }
-    },
-    "/channel/create": {
-      "post": {
-        "description": "Create a new channel for incident management.",
-        "operationId": "channelCreate",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CreateChannelRequest"
+              },
               "example": {
-                "auto_resolve_mode": "trigger",
-                "auto_resolve_timeout": 86400,
+                "team_id": 3521074710131,
                 "channel_name": "Production Alerts",
                 "description": "Handles all production environment alerts",
                 "group": {
                   "method": "p",
+                  "equals": [
+                    [
+                      "labels.service"
+                    ]
+                  ],
                   "time_window": 10,
                   "window_type": "tumbling"
                 },
-                "team_id": 3521074710131
-              },
-              "schema": {
-                "$ref": "#/components/schemas/CreateChannelRequest"
+                "auto_resolve_timeout": 86400,
+                "auto_resolve_mode": "trigger"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/channel/delete": {
+      "post": {
+        "operationId": "channelDelete",
+        "summary": "Delete channel",
+        "description": "Delete a disabled channel together with its rules and channel-exclusive integrations.",
+        "tags": [
+          "On-call/Channels"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |\n\n## Usage\n\n- Only a `disabled` channel can be deleted; any other status returns `InvalidParameter`.\n- If a shared integration's routing rule still targets the channel (in a case or the default branch), the call returns HTTP 400 with `error.code` `ReferenceExist` and the referencing integrations in `data.refs`. Remove the channel from those routes with `POST /route/upsert` first.\n- All escalation, silence, drop, inhibit and subscribe rules of the channel and its channel-exclusive integrations are deleted. The channel itself is soft-deleted: `POST /channel/info` still returns it with `status` `deleted`.\n- An unknown `channel_id` returns `InvalidParameter`.\n- The caller must also be able to edit the channel: the account owner or an admin, the channel creator, or a member of its managing teams (of its owning team when `managing_team_ids` is empty). Otherwise the call returns `AccessDenied`.\n- Every call is recorded in the account audit log.",
+          "href": "/en/api-reference/on-call/channels/channel-delete",
+          "metadata": {
+            "sidebarTitle": "Delete channel"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "channel_id": 6294542005131,
-                    "channel_name": "API Test Channel"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/ChannelCreateResponse"
+                          "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -35516,6 +36745,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -35523,62 +36755,62 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Create channel",
-        "tags": [
-          "On-call/Channels"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |",
-          "href": "/en/api-reference/on-call/channels/channel-create",
-          "metadata": {
-            "sidebarTitle": "Create channel"
-          }
-        }
-      }
-    },
-    "/channel/delete": {
-      "post": {
-        "description": "Delete a channel. Only a `disabled` channel can be deleted; all of its escalation, silence, drop and inhibit rules are deleted with it. The call fails when an integration route still references the channel.",
-        "operationId": "channelDelete",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {
-                "channel_id": 3521074710131
-              },
               "schema": {
                 "$ref": "#/components/schemas/ChannelIDRequest"
+              },
+              "example": {
+                "channel_id": 3521074710131
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/channel/disable": {
+      "post": {
+        "operationId": "channelDisable",
+        "summary": "Disable channel",
+        "description": "Disable a channel; while disabled it discards all incoming alert events.",
+        "tags": [
+          "On-call/Channels"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |\n\n## Usage\n\n- Only an `enabled` channel can be disabled; any other status returns `InvalidParameter`.\n- Rules and integrations are kept. Alert processing may take up to about one minute to see the new status.\n- An unknown `channel_id` returns `InvalidParameter`.\n- The caller must also be able to edit the channel: the account owner or an admin, the channel creator, or a member of its managing teams (of its owning team when `managing_team_ids` is empty). Otherwise the call returns `AccessDenied`.\n- Every call is recorded in the account audit log.",
+          "href": "/en/api-reference/on-call/channels/channel-disable",
+          "metadata": {
+            "sidebarTitle": "Disable channel"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -35586,6 +36818,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -35593,62 +36828,62 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Delete channel",
-        "tags": [
-          "On-call/Channels"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |",
-          "href": "/en/api-reference/on-call/channels/channel-delete",
-          "metadata": {
-            "sidebarTitle": "Delete channel"
-          }
-        }
-      }
-    },
-    "/channel/disable": {
-      "post": {
-        "description": "Disable a channel to stop incident routing without deleting it; a disabled channel discards incoming events. Only an `enabled` channel can be disabled.",
-        "operationId": "channelDisable",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {
-                "channel_id": 3521074710131
-              },
               "schema": {
                 "$ref": "#/components/schemas/ChannelIDRequest"
+              },
+              "example": {
+                "channel_id": 3521074710131
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/channel/enable": {
+      "post": {
+        "operationId": "channelEnable",
+        "summary": "Enable channel",
+        "description": "Enable a disabled channel so it processes incoming alert events again.",
+        "tags": [
+          "On-call/Channels"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |\n\n## Usage\n\n- Only a `disabled` channel can be enabled; any other status returns `InvalidParameter`.\n- An unknown `channel_id` returns `InvalidParameter`.\n- The caller must also be able to edit the channel: the account owner or an admin, the channel creator, or a member of its managing teams (of its owning team when `managing_team_ids` is empty). Otherwise the call returns `AccessDenied`.\n- Every call is recorded in the account audit log.",
+          "href": "/en/api-reference/on-call/channels/channel-enable",
+          "metadata": {
+            "sidebarTitle": "Enable channel"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -35656,6 +36891,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -35663,62 +36901,65 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Disable channel",
-        "tags": [
-          "On-call/Channels"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |",
-          "href": "/en/api-reference/on-call/channels/channel-disable",
-          "metadata": {
-            "sidebarTitle": "Disable channel"
-          }
-        }
-      }
-    },
-    "/channel/enable": {
-      "post": {
-        "description": "Enable a channel to resume incident routing. Only a `disabled` channel can be enabled.",
-        "operationId": "channelEnable",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {
-                "channel_id": 3521074710131
-              },
               "schema": {
                 "$ref": "#/components/schemas/ChannelIDRequest"
+              },
+              "example": {
+                "channel_id": 3521074710131
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/channel/escalate/rule/create": {
+      "post": {
+        "operationId": "channelEscalateRuleCreate",
+        "summary": "Create escalation rule",
+        "description": "Create an escalation rule that decides who is notified about a channel's incidents, and how.",
+        "tags": [
+          "On-call/Channels"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |\n\n## Usage\n\n- Rules are evaluated in ascending `priority`. The first enabled rule whose `time_filters` and `filters` match a new incident takes it; later rules are skipped. Omit `priority` to place the rule after all existing ones.\n- `template_id` must be an existing notification template, every member in `person_ids` must exist and every team in `team_ids` must have members; otherwise `InvalidParameter`.\n- The new rule is `enabled`.\n- An unknown `channel_id` returns `InvalidParameter`.\n- The caller must also be able to edit the channel: the account owner or an admin, the channel creator, or a member of its managing teams (of its owning team when `managing_team_ids` is empty). Otherwise the call returns `AccessDenied`.\n- Every call is recorded in the account audit log.",
+          "href": "/en/api-reference/on-call/channels/channel-escalate-rule-create",
+          "metadata": {
+            "sidebarTitle": "Create escalation rule"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/EmptyResponse"
+                          "$ref": "#/components/schemas/RuleCreateResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "rule_id": "69db2f72a0fe7db6448b1506",
+                    "rule_name": "On-call escalation"
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -35726,6 +36967,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -35733,84 +36977,81 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Enable channel",
-        "tags": [
-          "On-call/Channels"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |",
-          "href": "/en/api-reference/on-call/channels/channel-enable",
-          "metadata": {
-            "sidebarTitle": "Enable channel"
-          }
-        }
-      }
-    },
-    "/channel/escalate/rule/create": {
-      "post": {
-        "description": "Create an escalation rule defining who gets notified and when during an incident.",
-        "operationId": "channelEscalateRuleCreate",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CreateEscalationRuleRequest"
+              },
               "example": {
                 "channel_id": 3521074710131,
+                "rule_name": "On-call escalation",
+                "template_id": "6321aad26c12104586a88916",
                 "description": "Notify primary on-call, then escalate to secondary after 30 minutes",
                 "layers": [
                   {
-                    "escalate_window": 30,
-                    "force_escalate": false,
-                    "max_times": 3,
-                    "notify_step": 10,
                     "target": {
-                      "by": {
-                        "follow_preference": true
-                      },
                       "person_ids": [
                         3790925372131
-                      ]
-                    }
+                      ],
+                      "by": {
+                        "follow_preference": true
+                      }
+                    },
+                    "max_times": 3,
+                    "notify_step": 10,
+                    "escalate_window": 30,
+                    "force_escalate": false
                   }
-                ],
-                "rule_name": "On-call escalation",
-                "template_id": "6321aad26c12104586a88916"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/CreateEscalationRuleRequest"
+                ]
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/channel/escalate/rule/delete": {
+      "post": {
+        "operationId": "channelEscalateRuleDelete",
+        "summary": "Delete escalation rule",
+        "description": "Delete a disabled escalation rule so it no longer appears in the channel's rule list.",
+        "tags": [
+          "On-call/Channels"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |\n\n## Usage\n\n- Only a `disabled` rule can be deleted; any other status returns `InvalidParameter`.\n- The rule is soft-deleted: it disappears from the list, but `POST /channel/escalate/rule/info` still returns it with `status` `deleted`.\n- An unknown `channel_id` or `rule_id` returns `InvalidParameter`.\n- The caller must also be able to edit the channel: the account owner or an admin, the channel creator, or a member of its managing teams (of its owning team when `managing_team_ids` is empty). Otherwise the call returns `AccessDenied`.\n- Every call is recorded in the account audit log.",
+          "href": "/en/api-reference/on-call/channels/channel-escalate-rule-delete",
+          "metadata": {
+            "sidebarTitle": "Delete escalation rule"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "rule_id": "69db2f72a0fe7db6448b1506",
-                    "rule_name": "Test escalation rule"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/RuleCreateResponse"
+                          "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -35818,6 +37059,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -35825,63 +37069,63 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Create escalation rule",
-        "tags": [
-          "On-call/Channels"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |",
-          "href": "/en/api-reference/on-call/channels/channel-escalate-rule-create",
-          "metadata": {
-            "sidebarTitle": "Create escalation rule"
-          }
-        }
-      }
-    },
-    "/channel/escalate/rule/delete": {
-      "post": {
-        "description": "Delete an escalation rule. Only a `disabled` rule can be deleted.",
-        "operationId": "channelEscalateRuleDelete",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ChannelRuleIDRequest"
+              },
               "example": {
                 "channel_id": 3521074710131,
                 "rule_id": "6621b23f4a2c5e0012ab34cd"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ChannelRuleIDRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/channel/escalate/rule/disable": {
+      "post": {
+        "operationId": "channelEscalateRuleDisable",
+        "summary": "Disable escalation rule",
+        "description": "Disable an escalation rule without deleting it.",
+        "tags": [
+          "On-call/Channels"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |\n\n## Usage\n\n- Only an `enabled` rule can be disabled; any other status returns `InvalidParameter`.\n- A disabled rule takes no new incidents, and incidents already assigned through it stop receiving its notifications and escalations.\n- An unknown `channel_id` or `rule_id` returns `InvalidParameter`.\n- The caller must also be able to edit the channel: the account owner or an admin, the channel creator, or a member of its managing teams (of its owning team when `managing_team_ids` is empty). Otherwise the call returns `AccessDenied`.\n- Every call is recorded in the account audit log.",
+          "href": "/en/api-reference/on-call/channels/channel-escalate-rule-disable",
+          "metadata": {
+            "sidebarTitle": "Disable escalation rule"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -35889,6 +37133,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -35896,63 +37143,63 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Delete escalation rule",
-        "tags": [
-          "On-call/Channels"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |",
-          "href": "/en/api-reference/on-call/channels/channel-escalate-rule-delete",
-          "metadata": {
-            "sidebarTitle": "Delete escalation rule"
-          }
-        }
-      }
-    },
-    "/channel/escalate/rule/disable": {
-      "post": {
-        "description": "Disable an escalation rule without deleting it. Only an `enabled` rule can be disabled.",
-        "operationId": "channelEscalateRuleDisable",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ChannelRuleIDRequest"
+              },
               "example": {
                 "channel_id": 3521074710131,
                 "rule_id": "6621b23f4a2c5e0012ab34cd"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ChannelRuleIDRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/channel/escalate/rule/enable": {
+      "post": {
+        "operationId": "channelEscalateRuleEnable",
+        "summary": "Enable escalation rule",
+        "description": "Enable a disabled escalation rule so it can take new incidents again.",
+        "tags": [
+          "On-call/Channels"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |\n\n## Usage\n\n- Only a `disabled` rule can be enabled; any other status returns `InvalidParameter`.\n- An unknown `channel_id` or `rule_id` returns `InvalidParameter`.\n- The caller must also be able to edit the channel: the account owner or an admin, the channel creator, or a member of its managing teams (of its owning team when `managing_team_ids` is empty). Otherwise the call returns `AccessDenied`.\n- Every call is recorded in the account audit log.",
+          "href": "/en/api-reference/on-call/channels/channel-escalate-rule-enable",
+          "metadata": {
+            "sidebarTitle": "Enable escalation rule"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -35960,6 +37207,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -35967,63 +37217,95 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Disable escalation rule",
-        "tags": [
-          "On-call/Channels"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |",
-          "href": "/en/api-reference/on-call/channels/channel-escalate-rule-disable",
-          "metadata": {
-            "sidebarTitle": "Disable escalation rule"
-          }
-        }
-      }
-    },
-    "/channel/escalate/rule/enable": {
-      "post": {
-        "description": "Enable a disabled escalation rule. Only a `disabled` rule can be enabled.",
-        "operationId": "channelEscalateRuleEnable",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ChannelRuleIDRequest"
+              },
               "example": {
                 "channel_id": 3521074710131,
                 "rule_id": "6621b23f4a2c5e0012ab34cd"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ChannelRuleIDRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/channel/escalate/rule/info": {
+      "post": {
+        "operationId": "channelEscalateRuleInfo",
+        "summary": "Get escalation rule detail",
+        "description": "Return one escalation rule of a channel, including its levels, time windows and filters.",
+        "tags": [
+          "On-call/Channels"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Read** (`on-call`) or **Channels Manage** (`on-call`) or **Incidents Read** (`on-call`) or **Incidents Manage** (`on-call`) |\n\n## Usage\n\n- A deleted rule is still returned, with `status` `deleted`.\n- An unknown `channel_id` or `rule_id` returns `InvalidParameter`.",
+          "href": "/en/api-reference/on-call/channels/channel-escalate-rule-info",
+          "metadata": {
+            "sidebarTitle": "Get escalation rule detail"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/EmptyResponse"
+                          "$ref": "#/components/schemas/EscalateRuleItem"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "account_id": 2451002751131,
+                    "channel_id": 6193426913131,
+                    "priority": 0,
+                    "aggr_window": 0,
+                    "rule_name": "Default",
+                    "description": "",
+                    "layers": [
+                      {
+                        "max_times": 1,
+                        "notify_step": 10,
+                        "target": {
+                          "person_ids": [
+                            3790925372131
+                          ],
+                          "by": {
+                            "follow_preference": true
+                          },
+                          "webhooks": null
+                        },
+                        "escalate_window": 30,
+                        "force_escalate": false
+                      }
+                    ],
+                    "time_filters": [],
+                    "filters": [],
+                    "status": "enabled",
+                    "template_id": "6321aad26c12104586a88916",
+                    "rule_id": "69bd0ce95a238693176c1d66",
+                    "updated_by": 3790925372131,
+                    "created_at": 1773997289,
+                    "updated_at": 1773997289
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -36031,6 +37313,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -36038,95 +37323,99 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Enable escalation rule",
-        "tags": [
-          "On-call/Channels"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |",
-          "href": "/en/api-reference/on-call/channels/channel-escalate-rule-enable",
-          "metadata": {
-            "sidebarTitle": "Enable escalation rule"
-          }
-        }
-      }
-    },
-    "/channel/escalate/rule/info": {
-      "post": {
-        "description": "Retrieve detailed information for a specific escalation rule.",
-        "operationId": "channelEscalateRuleInfo",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ChannelRuleIDRequest"
+              },
               "example": {
                 "channel_id": 1001,
                 "rule_id": "6621b23f4a2c5e0012ab34d0"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ChannelRuleIDRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/channel/escalate/rule/list": {
+      "post": {
+        "operationId": "channelEscalateRuleList",
+        "summary": "List escalation rules",
+        "description": "List a channel's escalation rules in the order they are evaluated.",
+        "tags": [
+          "On-call/Channels"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Read** (`on-call`) or **Channels Manage** (`on-call`) or **Incidents Read** (`on-call`) or **Incidents Manage** (`on-call`) |\n\n## Usage\n\n- An unknown `channel_id` returns `InvalidParameter`.",
+          "href": "/en/api-reference/on-call/channels/channel-escalate-rule-list",
+          "metadata": {
+            "sidebarTitle": "List escalation rules"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "account_id": 2451002751131,
-                    "aggr_window": 0,
-                    "channel_id": 6193426913131,
-                    "created_at": 1773997289,
-                    "description": "",
-                    "filters": [],
-                    "layers": [
-                      {
-                        "escalate_window": 30,
-                        "force_escalate": false,
-                        "max_times": 1,
-                        "notify_step": 10,
-                        "target": {
-                          "by": {
-                            "follow_preference": true
-                          },
-                          "person_ids": [
-                            3790925372131
-                          ],
-                          "webhooks": null
-                        }
-                      }
-                    ],
-                    "priority": 0,
-                    "rule_id": "69bd0ce95a238693176c1d66",
-                    "rule_name": "Default",
-                    "status": "enabled",
-                    "template_id": "6321aad26c12104586a88916",
-                    "time_filters": [],
-                    "updated_at": 1773997289,
-                    "updated_by": 3790925372131
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/EscalateRuleItem"
+                          "$ref": "#/components/schemas/ListEscalationRulesResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "items": [
+                      {
+                        "account_id": 2451002751131,
+                        "channel_id": 6193426913131,
+                        "priority": 0,
+                        "aggr_window": 0,
+                        "rule_name": "Default",
+                        "description": "",
+                        "layers": [
+                          {
+                            "max_times": 1,
+                            "notify_step": 10,
+                            "target": {
+                              "person_ids": [
+                                3790925372131
+                              ],
+                              "by": {
+                                "follow_preference": true
+                              },
+                              "webhooks": null
+                            },
+                            "escalate_window": 30,
+                            "force_escalate": false
+                          }
+                        ],
+                        "time_filters": [],
+                        "filters": [],
+                        "status": "enabled",
+                        "template_id": "6321aad26c12104586a88916",
+                        "rule_id": "69bd0ce95a238693176c1d66",
+                        "updated_by": 3790925372131,
+                        "created_at": 1773997289,
+                        "updated_at": 1773997289
+                      }
+                    ]
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -36134,6 +37423,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -36141,98 +37433,62 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Get escalation rule detail",
-        "tags": [
-          "On-call/Channels"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Read** (`on-call`) |",
-          "href": "/en/api-reference/on-call/channels/channel-escalate-rule-info",
-          "metadata": {
-            "sidebarTitle": "Get escalation rule detail"
-          }
-        }
-      }
-    },
-    "/channel/escalate/rule/list": {
-      "post": {
-        "description": "List all escalation rules for a channel.",
-        "operationId": "channelEscalateRuleList",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {
-                "channel_id": 1001
-              },
               "schema": {
                 "$ref": "#/components/schemas/ChannelScopedListRequest"
+              },
+              "example": {
+                "channel_id": 1001
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/channel/escalate/rule/update": {
+      "post": {
+        "operationId": "channelEscalateRuleUpdate",
+        "summary": "Update escalation rule",
+        "description": "Replace the configuration of an existing escalation rule.",
+        "tags": [
+          "On-call/Channels"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |\n\n## Usage\n\n- Full replacement: omitted `description`, `aggr_window`, `time_filters` and `filters` are reset to empty or `0`. Only `priority` keeps its current value when omitted.\n- Validation is the same as for create. The rule's `status` is not changed; use the enable and disable endpoints.\n- An unknown `channel_id` or `rule_id` returns `InvalidParameter`.\n- The caller must also be able to edit the channel: the account owner or an admin, the channel creator, or a member of its managing teams (of its owning team when `managing_team_ids` is empty). Otherwise the call returns `AccessDenied`.\n- Every call is recorded in the account audit log.",
+          "href": "/en/api-reference/on-call/channels/channel-escalate-rule-update",
+          "metadata": {
+            "sidebarTitle": "Update escalation rule"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "items": [
-                      {
-                        "account_id": 2451002751131,
-                        "aggr_window": 0,
-                        "channel_id": 6193426913131,
-                        "created_at": 1773997289,
-                        "description": "",
-                        "filters": [],
-                        "layers": [
-                          {
-                            "escalate_window": 30,
-                            "force_escalate": false,
-                            "max_times": 1,
-                            "notify_step": 10,
-                            "target": {
-                              "by": {
-                                "follow_preference": true
-                              },
-                              "person_ids": [
-                                3790925372131
-                              ],
-                              "webhooks": null
-                            }
-                          }
-                        ],
-                        "priority": 0,
-                        "rule_id": "69bd0ce95a238693176c1d66",
-                        "rule_name": "Default",
-                        "status": "enabled",
-                        "template_id": "6321aad26c12104586a88916",
-                        "time_filters": [],
-                        "updated_at": 1773997289,
-                        "updated_by": 3790925372131
-                      }
-                    ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/ListEscalationRulesResponse"
+                          "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -36240,6 +37496,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -36247,31 +37506,24 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "List escalation rules",
-        "tags": [
-          "On-call/Channels"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Read** (`on-call`) |",
-          "href": "/en/api-reference/on-call/channels/channel-escalate-rule-list",
-          "metadata": {
-            "sidebarTitle": "List escalation rules"
-          }
-        }
-      }
-    },
-    "/channel/escalate/rule/update": {
-      "post": {
-        "description": "Update an existing escalation rule configuration.",
-        "operationId": "channelEscalateRuleUpdate",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/UpdateEscalationRuleRequest"
+              },
               "example": {
                 "channel_id": 1001,
+                "rule_id": "6621b23f4a2c5e0012ab34d0",
+                "template_id": "6621b23f4a2c5e0012ab34d1",
+                "rule_name": "Default escalation",
                 "layers": [
                   {
                     "target": {
+                      "person_ids": [
+                        42
+                      ],
                       "by": {
                         "critical": [
                           "voice"
@@ -36279,50 +37531,62 @@
                         "warning": [
                           "sms"
                         ]
-                      },
-                      "person_ids": [
-                        42
-                      ]
+                      }
                     }
                   }
-                ],
-                "rule_id": "6621b23f4a2c5e0012ab34d0",
-                "rule_name": "Default escalation",
-                "template_id": "6621b23f4a2c5e0012ab34d1"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/UpdateEscalationRuleRequest"
+                ]
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/channel/info": {
+      "post": {
+        "operationId": "channelInfo",
+        "summary": "Get channel detail",
+        "description": "Return one channel's full configuration with counts of its active incidents from the last 30 days.",
+        "tags": [
+          "On-call/Channels"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Deleted channels are still returned, with `status` `deleted`.\n- A private channel (`is_private: true`) returns `AccessDenied` unless the caller is the account owner or an admin, its creator, or a member of its owning or managing teams.\n- `team_name`, `creator_name` and `is_starred` are not returned here; use `POST /channel/list` for them.\n- An unknown `channel_id` returns `InvalidParameter`.",
+          "href": "/en/api-reference/on-call/channels/channel-info",
+          "metadata": {
+            "sidebarTitle": "Get channel detail"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/EmptyResponse"
+                          "$ref": "#/components/schemas/ChannelItem"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "channel_id": 1001,
+                    "channel_name": "Production Alerts",
+                    "status": "enabled",
+                    "team_id": 10
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -36330,6 +37594,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -36337,67 +37604,70 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Update escalation rule",
-        "tags": [
-          "On-call/Channels"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |",
-          "href": "/en/api-reference/on-call/channels/channel-escalate-rule-update",
-          "metadata": {
-            "sidebarTitle": "Update escalation rule"
-          }
-        }
-      }
-    },
-    "/channel/info": {
-      "post": {
-        "description": "Retrieve detailed information for a specific channel.",
-        "operationId": "channelInfo",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {
-                "channel_id": 1001
-              },
               "schema": {
                 "$ref": "#/components/schemas/ChannelInfoRequest"
+              },
+              "example": {
+                "channel_id": 1001
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/channel/infos": {
+      "post": {
+        "operationId": "channelInfos",
+        "summary": "Batch get channels",
+        "description": "Return the ID, name and status of up to 1,000 channels in one call.",
+        "tags": [
+          "On-call/Channels"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- IDs that do not exist are skipped. Deleted channels are included, with `status` `deleted`.\n- Items are ordered by channel creation, not by the order of `channel_ids`.\n- Private channels are included regardless of the caller's team membership.",
+          "href": "/en/api-reference/on-call/channels/channel-infos",
+          "metadata": {
+            "sidebarTitle": "Batch get channels"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "channel_id": 1001,
-                    "channel_name": "Production Alerts",
-                    "status": "enabled",
-                    "team_id": 10
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/ChannelItem"
+                          "$ref": "#/components/schemas/ChannelInfosResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "items": [
+                      {
+                        "channel_id": 1001,
+                        "channel_name": "Production Alerts",
+                        "status": "enabled"
+                      }
+                    ]
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -36405,6 +37675,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -36412,73 +37685,68 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Get channel detail",
-        "tags": [
-          "On-call/Channels"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |",
-          "href": "/en/api-reference/on-call/channels/channel-info",
-          "metadata": {
-            "sidebarTitle": "Get channel detail"
-          }
-        }
-      }
-    },
-    "/channel/infos": {
-      "post": {
-        "description": "Retrieve multiple channels by their IDs.",
-        "operationId": "channelInfos",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ChannelInfosRequest"
+              },
               "example": {
                 "channel_ids": [
                   1001,
                   1002
                 ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ChannelInfosRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/channel/inhibit/rule/create": {
+      "post": {
+        "operationId": "channelInhibitRuleCreate",
+        "summary": "Create inhibit rule",
+        "description": "Create an inhibit rule that mutes alert events while a related source alert is still active.",
+        "tags": [
+          "On-call/Channels"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |\n\n## Usage\n\n- Requires the Standard license or higher; otherwise the call returns `NoLicense`.\n- An incoming event is inhibited when it matches `target_filters` and the same channel has an active (not recovered) alert with a different `alert_key` that matches `source_filters`, started within the 10 minutes before the event, and has the same value for every key in `equals`.\n- The rule never fires when `equals` or `source_filters` is empty, or when the incoming event has no value for a label listed in `equals`.\n- Inhibit rules are checked after drop and silence rules; the first matching inhibit rule is applied.\n- An unknown `channel_id` returns `InvalidParameter`.\n- The caller must also be able to edit the channel: the account owner or an admin, the channel creator, or a member of its managing teams (of its owning team when `managing_team_ids` is empty). Otherwise the call returns `AccessDenied`.\n- Every call is recorded in the account audit log.",
+          "href": "/en/api-reference/on-call/channels/channel-inhibit-rule-create",
+          "metadata": {
+            "sidebarTitle": "Create inhibit rule"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "items": [
-                      {
-                        "channel_id": 1001,
-                        "channel_name": "Production Alerts",
-                        "status": "enabled"
-                      }
-                    ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/ChannelInfosResponse"
+                          "$ref": "#/components/schemas/RuleCreateResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "rule_id": "69db2f69a0fe7db6448b1504",
+                    "rule_name": "Suppress Info when Critical fires"
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -36486,6 +37754,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -36493,35 +37764,21 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Batch get channels",
-        "tags": [
-          "On-call/Channels"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |",
-          "href": "/en/api-reference/on-call/channels/channel-infos",
-          "metadata": {
-            "sidebarTitle": "Batch get channels"
-          }
-        }
-      }
-    },
-    "/channel/inhibit/rule/create": {
-      "post": {
-        "description": "Create an inhibit rule to suppress lower-priority alerts when higher-priority ones are firing.",
-        "operationId": "channelInhibitRuleCreate",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CreateInhibitRuleRequest"
+              },
               "example": {
                 "channel_id": 3521074710131,
+                "rule_name": "Suppress Info when Critical fires",
                 "description": "When a Critical alert fires, suppress matching Info alerts",
                 "equals": [
                   "labels.cluster",
                   "labels.service"
                 ],
-                "is_directly_discard": false,
-                "rule_name": "Suppress Info when Critical fires",
                 "source_filters": [
                   [
                     {
@@ -36543,44 +37800,55 @@
                       ]
                     }
                   ]
-                ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/CreateInhibitRuleRequest"
+                ],
+                "is_directly_discard": false
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/channel/inhibit/rule/delete": {
+      "post": {
+        "operationId": "channelInhibitRuleDelete",
+        "summary": "Delete inhibit rule",
+        "description": "Delete a disabled inhibit rule so it no longer appears in the channel's rule list.",
+        "tags": [
+          "On-call/Channels"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |\n\n## Usage\n\n- Only a `disabled` rule can be deleted; any other status returns `InvalidParameter`.\n- An unknown `channel_id` or `rule_id` returns `InvalidParameter`.\n- The caller must also be able to edit the channel: the account owner or an admin, the channel creator, or a member of its managing teams (of its owning team when `managing_team_ids` is empty). Otherwise the call returns `AccessDenied`.\n- Every call is recorded in the account audit log.",
+          "href": "/en/api-reference/on-call/channels/channel-inhibit-rule-delete",
+          "metadata": {
+            "sidebarTitle": "Delete inhibit rule"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "rule_id": "69db2f69a0fe7db6448b1504",
-                    "rule_name": "Test inhibit rule"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/RuleCreateResponse"
+                          "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -36588,6 +37856,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -36595,63 +37866,63 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Create inhibit rule",
-        "tags": [
-          "On-call/Channels"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |",
-          "href": "/en/api-reference/on-call/channels/channel-inhibit-rule-create",
-          "metadata": {
-            "sidebarTitle": "Create inhibit rule"
-          }
-        }
-      }
-    },
-    "/channel/inhibit/rule/delete": {
-      "post": {
-        "description": "Delete an inhibit rule. Only a `disabled` rule can be deleted.",
-        "operationId": "channelInhibitRuleDelete",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ChannelRuleIDRequest"
+              },
               "example": {
                 "channel_id": 3521074710131,
                 "rule_id": "6621b23f4a2c5e0012ab34cd"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ChannelRuleIDRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/channel/inhibit/rule/disable": {
+      "post": {
+        "operationId": "channelInhibitRuleDisable",
+        "summary": "Disable inhibit rule",
+        "description": "Disable an inhibit rule without deleting it.",
+        "tags": [
+          "On-call/Channels"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |\n\n## Usage\n\n- Only an `enabled` rule can be disabled; any other status returns `InvalidParameter`.\n- An unknown `channel_id` or `rule_id` returns `InvalidParameter`.\n- The caller must also be able to edit the channel: the account owner or an admin, the channel creator, or a member of its managing teams (of its owning team when `managing_team_ids` is empty). Otherwise the call returns `AccessDenied`.\n- Every call is recorded in the account audit log.",
+          "href": "/en/api-reference/on-call/channels/channel-inhibit-rule-disable",
+          "metadata": {
+            "sidebarTitle": "Disable inhibit rule"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
-                }
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
+                }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -36659,6 +37930,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -36666,63 +37940,63 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Delete inhibit rule",
-        "tags": [
-          "On-call/Channels"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |",
-          "href": "/en/api-reference/on-call/channels/channel-inhibit-rule-delete",
-          "metadata": {
-            "sidebarTitle": "Delete inhibit rule"
-          }
-        }
-      }
-    },
-    "/channel/inhibit/rule/disable": {
-      "post": {
-        "description": "Disable an inhibit rule without deleting it. Only an `enabled` rule can be disabled.",
-        "operationId": "channelInhibitRuleDisable",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ChannelRuleIDRequest"
+              },
               "example": {
                 "channel_id": 3521074710131,
                 "rule_id": "6621b23f4a2c5e0012ab34cd"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ChannelRuleIDRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/channel/inhibit/rule/enable": {
+      "post": {
+        "operationId": "channelInhibitRuleEnable",
+        "summary": "Enable inhibit rule",
+        "description": "Enable a disabled inhibit rule so it mutes matching alert events again.",
+        "tags": [
+          "On-call/Channels"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |\n\n## Usage\n\n- Requires the Standard license or higher; otherwise the call returns `NoLicense`.\n- Only a `disabled` rule can be enabled; any other status returns `InvalidParameter`.\n- An unknown `channel_id` or `rule_id` returns `InvalidParameter`.\n- The caller must also be able to edit the channel: the account owner or an admin, the channel creator, or a member of its managing teams (of its owning team when `managing_team_ids` is empty). Otherwise the call returns `AccessDenied`.\n- Every call is recorded in the account audit log.",
+          "href": "/en/api-reference/on-call/channels/channel-inhibit-rule-enable",
+          "metadata": {
+            "sidebarTitle": "Enable inhibit rule"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -36730,6 +38004,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -36737,138 +38014,77 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Disable inhibit rule",
-        "tags": [
-          "On-call/Channels"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |",
-          "href": "/en/api-reference/on-call/channels/channel-inhibit-rule-disable",
-          "metadata": {
-            "sidebarTitle": "Disable inhibit rule"
-          }
-        }
-      }
-    },
-    "/channel/inhibit/rule/enable": {
-      "post": {
-        "description": "Enable a disabled inhibit rule. Only a `disabled` rule can be enabled.",
-        "operationId": "channelInhibitRuleEnable",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ChannelRuleIDRequest"
+              },
               "example": {
                 "channel_id": 3521074710131,
                 "rule_id": "6621b23f4a2c5e0012ab34cd"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ChannelRuleIDRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/channel/inhibit/rule/list": {
+      "post": {
+        "operationId": "channelInhibitRuleList",
+        "summary": "List inhibit rules",
+        "description": "List a channel's inhibit rules, oldest first.",
+        "tags": [
+          "On-call/Channels"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Read** (`on-call`) or **Channels Manage** (`on-call`) |\n\n## Usage\n\n- An unknown `channel_id` returns `InvalidParameter`.",
+          "href": "/en/api-reference/on-call/channels/channel-inhibit-rule-list",
+          "metadata": {
+            "sidebarTitle": "List inhibit rules"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/EmptyResponse"
+                          "$ref": "#/components/schemas/ListInhibitRulesResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
-                }
-              }
-            },
-            "description": "Success"
-          },
-          "400": {
-            "$ref": "#/components/responses/BadRequest"
-          },
-          "401": {
-            "$ref": "#/components/responses/Unauthorized"
-          },
-          "429": {
-            "$ref": "#/components/responses/TooManyRequests"
-          },
-          "500": {
-            "$ref": "#/components/responses/ServerError"
-          }
-        },
-        "summary": "Enable inhibit rule",
-        "tags": [
-          "On-call/Channels"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |",
-          "href": "/en/api-reference/on-call/channels/channel-inhibit-rule-enable",
-          "metadata": {
-            "sidebarTitle": "Enable inhibit rule"
-          }
-        }
-      }
-    },
-    "/channel/inhibit/rule/list": {
-      "post": {
-        "description": "List all inhibit rules configured for a channel.",
-        "operationId": "channelInhibitRuleList",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "channel_id": 1001
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ChannelScopedListRequest"
-              }
-            }
-          },
-          "required": true
-        },
-        "responses": {
-          "200": {
-            "content": {
-              "application/json": {
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "items": [
                       {
                         "account_id": 2451002751131,
                         "channel_id": 5967964835131,
-                        "created_at": 1773979184,
-                        "description": "",
-                        "equals": [
-                          "data_source_id",
-                          "labels._account_id"
-                        ],
-                        "is_directly_discard": false,
-                        "rule_id": "69bcc630b9e63df36603e425",
                         "rule_name": "Suppress downstream alerts",
+                        "description": "",
                         "source_filters": [
                           [
                             {
                               "key": "severity",
                               "oper": "IN",
                               "vals": [
-                                "Info"
+                                "Critical"
                               ]
                             }
                           ]
                         ],
-                        "status": "enabled",
                         "target_filters": [
                           [
                             {
@@ -36880,31 +38096,95 @@
                             }
                           ]
                         ],
-                        "updated_at": 1773979184,
-                        "updated_by": 3790925372131
+                        "equals": [
+                          "labels.cluster",
+                          "labels.service"
+                        ],
+                        "is_directly_discard": false,
+                        "status": "enabled",
+                        "rule_id": "69bcc630b9e63df36603e425",
+                        "updated_by": 3790925372131,
+                        "created_at": 1773979184,
+                        "updated_at": 1773979184
                       }
                     ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "429": {
+            "$ref": "#/components/responses/TooManyRequests"
+          },
+          "500": {
+            "$ref": "#/components/responses/ServerError"
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ChannelScopedListRequest"
+              },
+              "example": {
+                "channel_id": 1001
+              }
+            }
+          }
+        }
+      }
+    },
+    "/channel/inhibit/rule/update": {
+      "post": {
+        "operationId": "channelInhibitRuleUpdate",
+        "summary": "Update inhibit rule",
+        "description": "Replace the configuration of an existing inhibit rule.",
+        "tags": [
+          "On-call/Channels"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |\n\n## Usage\n\n- Full replacement: omitted `source_filters` and `target_filters` become empty, an omitted `is_directly_discard` becomes `false`, and an omitted `description` becomes empty.\n- An unknown `channel_id` or `rule_id` returns `InvalidParameter`.\n- The caller must also be able to edit the channel: the account owner or an admin, the channel creator, or a member of its managing teams (of its owning team when `managing_team_ids` is empty). Otherwise the call returns `AccessDenied`.\n- Every call is recorded in the account audit log.",
+          "href": "/en/api-reference/on-call/channels/channel-inhibit-rule-update",
+          "metadata": {
+            "sidebarTitle": "Update inhibit rule"
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/ListInhibitRulesResponse"
+                          "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -36912,6 +38192,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -36919,67 +38202,77 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "List inhibit rules",
-        "tags": [
-          "On-call/Channels"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Read** (`on-call`) |",
-          "href": "/en/api-reference/on-call/channels/channel-inhibit-rule-list",
-          "metadata": {
-            "sidebarTitle": "List inhibit rules"
-          }
-        }
-      }
-    },
-    "/channel/inhibit/rule/update": {
-      "post": {
-        "description": "Update an existing inhibit rule configuration.",
-        "operationId": "channelInhibitRuleUpdate",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/UpdateInhibitRuleRequest"
+              },
               "example": {
                 "channel_id": 1001,
+                "rule_id": "6621b23f4a2c5e0012ab34ce",
+                "rule_name": "Suppress downstream",
                 "equals": [
                   "labels.cluster"
-                ],
-                "rule_id": "6621b23f4a2c5e0012ab34ce",
-                "rule_name": "Suppress downstream"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/UpdateInhibitRuleRequest"
+                ]
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/channel/list": {
+      "post": {
+        "operationId": "channelList",
+        "summary": "List channels",
+        "description": "List the channels visible to the caller, with filters, sorting and pagination.",
+        "tags": [
+          "On-call/Channels"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Without filters, every channel in the account is returned except private channels the caller cannot access. Deleted channels are never returned.\n- Setting both `is_my_team` and `is_my_starred` to `true` returns `InvalidParameter`. `is_my_managed` takes precedence over both. With `is_my_managed` or `is_my_team`, `team_ids` is ignored.\n- With `is_brief: true`, items carry only `channel_id`, `channel_name`, `description`, `status` and `is_starred`, and all matches are returned in one page.\n- Always pass `p`. When it is omitted the first page is returned, but `has_next_page` is then `true` whenever anything matches.",
+          "href": "/en/api-reference/on-call/channels/channel-list",
+          "metadata": {
+            "sidebarTitle": "List channels"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/EmptyResponse"
+                          "$ref": "#/components/schemas/ListChannelsResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "total": 42,
+                    "has_next_page": true,
+                    "items": [
+                      {
+                        "channel_id": 1001,
+                        "channel_name": "Production Alerts",
+                        "status": "enabled"
+                      }
+                    ]
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -36987,6 +38280,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -36994,75 +38290,68 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Update inhibit rule",
-        "tags": [
-          "On-call/Channels"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |",
-          "href": "/en/api-reference/on-call/channels/channel-inhibit-rule-update",
-          "metadata": {
-            "sidebarTitle": "Update inhibit rule"
-          }
-        }
-      }
-    },
-    "/channel/list": {
-      "post": {
-        "description": "List channels accessible to the current user with optional filters.",
-        "operationId": "channelList",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ListChannelsRequest"
+              },
               "example": {
-                "asc": false,
+                "p": 1,
                 "limit": 20,
                 "orderby": "created_at",
-                "p": 1
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ListChannelsRequest"
+                "asc": false
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/channel/silence/rule/create": {
+      "post": {
+        "operationId": "channelSilenceRuleCreate",
+        "summary": "Create silence rule",
+        "description": "Create a silence rule that mutes or drops matching alert events during a time window.",
+        "tags": [
+          "On-call/Channels"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |\n\n## Usage\n\n- Set exactly one of `time_filter` (one-off window) or `time_filters` (recurring windows), and give `filters` at least one condition; otherwise `InvalidParameter`.\n- Each incoming event is checked against drop rules first, then silence rules, then inhibit rules. The first enabled silence rule whose window covers the current time and whose `filters` match is applied.\n- With `from_incident_id`, only one enabled silence rule may exist per incident; creating a second returns `InvalidParameter`.\n- An unknown `channel_id` returns `InvalidParameter`.\n- The caller must also be able to edit the channel: the account owner or an admin, the channel creator, or a member of its managing teams (of its owning team when `managing_team_ids` is empty). Otherwise the call returns `AccessDenied`.\n- Every call is recorded in the account audit log.",
+          "href": "/en/api-reference/on-call/channels/channel-silence-rule-create",
+          "metadata": {
+            "sidebarTitle": "Create silence rule"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "has_next_page": true,
-                    "items": [
-                      {
-                        "channel_id": 1001,
-                        "channel_name": "Production Alerts",
-                        "status": "enabled"
-                      }
-                    ],
-                    "total": 42
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/ListChannelsResponse"
+                          "$ref": "#/components/schemas/RuleCreateResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "rule_id": "69db2f66a0fe7db6448b1503",
+                    "rule_name": "Maintenance window silence"
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -37070,6 +38359,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -37077,29 +38369,21 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "List channels",
-        "tags": [
-          "On-call/Channels"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |",
-          "href": "/en/api-reference/on-call/channels/channel-list",
-          "metadata": {
-            "sidebarTitle": "List channels"
-          }
-        }
-      }
-    },
-    "/channel/silence/rule/create": {
-      "post": {
-        "description": "Create a silence rule to suppress notifications matching specified conditions.",
-        "operationId": "channelSilenceRuleCreate",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CreateSilenceRuleRequest"
+              },
               "example": {
                 "channel_id": 3521074710131,
+                "rule_name": "Maintenance window silence",
                 "description": "Silence all Info alerts during planned maintenance",
+                "time_filter": {
+                  "start_time": 1773388800,
+                  "end_time": 1773414000
+                },
                 "filters": [
                   [
                     {
@@ -37111,49 +38395,54 @@
                     }
                   ]
                 ],
-                "is_directly_discard": false,
-                "rule_name": "Maintenance window silence",
-                "time_filter": {
-                  "end_time": 1773414000,
-                  "start_time": 1773388800
-                }
-              },
-              "schema": {
-                "$ref": "#/components/schemas/CreateSilenceRuleRequest"
+                "is_directly_discard": false
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/channel/silence/rule/delete": {
+      "post": {
+        "operationId": "channelSilenceRuleDelete",
+        "summary": "Delete silence rule",
+        "description": "Delete a disabled silence rule so it no longer appears in the channel's rule list.",
+        "tags": [
+          "On-call/Channels"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |\n\n## Usage\n\n- Only a `disabled` rule can be deleted; any other status returns `InvalidParameter`.\n- An unknown `channel_id` or `rule_id` returns `InvalidParameter`.\n- The caller must also be able to edit the channel: the account owner or an admin, the channel creator, or a member of its managing teams (of its owning team when `managing_team_ids` is empty). Otherwise the call returns `AccessDenied`.\n- Every call is recorded in the account audit log.",
+          "href": "/en/api-reference/on-call/channels/channel-silence-rule-delete",
+          "metadata": {
+            "sidebarTitle": "Delete silence rule"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "rule_id": "69db2f66a0fe7db6448b1503",
-                    "rule_name": "Test silence rule"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/RuleCreateResponse"
+                          "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -37161,6 +38450,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -37168,63 +38460,63 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Create silence rule",
-        "tags": [
-          "On-call/Channels"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |",
-          "href": "/en/api-reference/on-call/channels/channel-silence-rule-create",
-          "metadata": {
-            "sidebarTitle": "Create silence rule"
-          }
-        }
-      }
-    },
-    "/channel/silence/rule/delete": {
-      "post": {
-        "description": "Delete a silence rule. Only a `disabled` rule can be deleted.",
-        "operationId": "channelSilenceRuleDelete",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ChannelRuleIDRequest"
+              },
               "example": {
                 "channel_id": 3521074710131,
                 "rule_id": "6621b23f4a2c5e0012ab34cd"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ChannelRuleIDRequest"
               }
             }
-          },
-          "required": true
-        },
-        "responses": {
-          "200": {
-            "content": {
-              "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
+          }
+        }
+      }
+    },
+    "/channel/silence/rule/disable": {
+      "post": {
+        "operationId": "channelSilenceRuleDisable",
+        "summary": "Disable silence rule",
+        "description": "Disable a silence rule without deleting it.",
+        "tags": [
+          "On-call/Channels"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |\n\n## Usage\n\n- Only an `enabled` rule can be disabled; any other status returns `InvalidParameter`.\n- An unknown `channel_id` or `rule_id` returns `InvalidParameter`.\n- The caller must also be able to edit the channel: the account owner or an admin, the channel creator, or a member of its managing teams (of its owning team when `managing_team_ids` is empty). Otherwise the call returns `AccessDenied`.\n- Every call is recorded in the account audit log.",
+          "href": "/en/api-reference/on-call/channels/channel-silence-rule-disable",
+          "metadata": {
+            "sidebarTitle": "Disable silence rule"
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -37232,6 +38524,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -37239,63 +38534,63 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Delete silence rule",
-        "tags": [
-          "On-call/Channels"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |",
-          "href": "/en/api-reference/on-call/channels/channel-silence-rule-delete",
-          "metadata": {
-            "sidebarTitle": "Delete silence rule"
-          }
-        }
-      }
-    },
-    "/channel/silence/rule/disable": {
-      "post": {
-        "description": "Disable a silence rule without deleting it. Only an `enabled` rule can be disabled.",
-        "operationId": "channelSilenceRuleDisable",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ChannelRuleIDRequest"
+              },
               "example": {
                 "channel_id": 3521074710131,
                 "rule_id": "6621b23f4a2c5e0012ab34cd"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ChannelRuleIDRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/channel/silence/rule/enable": {
+      "post": {
+        "operationId": "channelSilenceRuleEnable",
+        "summary": "Enable silence rule",
+        "description": "Enable a disabled silence rule so it silences matching alert events again.",
+        "tags": [
+          "On-call/Channels"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |\n\n## Usage\n\n- Only a `disabled` rule can be enabled; any other status returns `InvalidParameter`.\n- An unknown `channel_id` or `rule_id` returns `InvalidParameter`.\n- The caller must also be able to edit the channel: the account owner or an admin, the channel creator, or a member of its managing teams (of its owning team when `managing_team_ids` is empty). Otherwise the call returns `AccessDenied`.\n- Every call is recorded in the account audit log.",
+          "href": "/en/api-reference/on-call/channels/channel-silence-rule-enable",
+          "metadata": {
+            "sidebarTitle": "Enable silence rule"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -37303,6 +38598,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -37310,63 +38608,96 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Disable silence rule",
-        "tags": [
-          "On-call/Channels"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |",
-          "href": "/en/api-reference/on-call/channels/channel-silence-rule-disable",
-          "metadata": {
-            "sidebarTitle": "Disable silence rule"
-          }
-        }
-      }
-    },
-    "/channel/silence/rule/enable": {
-      "post": {
-        "description": "Enable a disabled silence rule. Only a `disabled` rule can be enabled.",
-        "operationId": "channelSilenceRuleEnable",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ChannelRuleIDRequest"
+              },
               "example": {
                 "channel_id": 3521074710131,
                 "rule_id": "6621b23f4a2c5e0012ab34cd"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ChannelRuleIDRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/channel/silence/rule/list": {
+      "post": {
+        "operationId": "channelSilenceRuleList",
+        "summary": "List silence rules",
+        "description": "List a channel's silence rules and whether each one is in effect right now.",
+        "tags": [
+          "On-call/Channels"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Read** (`on-call`) or **Channels Manage** (`on-call`) or **Incidents Read** (`on-call`) or **Incidents Manage** (`on-call`) |\n\n## Usage\n\n- Listing also permanently removes one-off-window rules that are due for automatic cleanup (see `is_auto_delete`), so they no longer appear. Rules with recurring `time_filters` are never removed this way.\n- An unknown `channel_id` returns `InvalidParameter`.",
+          "href": "/en/api-reference/on-call/channels/channel-silence-rule-list",
+          "metadata": {
+            "sidebarTitle": "List silence rules"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/EmptyResponse"
+                          "$ref": "#/components/schemas/ListSilenceRulesResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "items": [
+                      {
+                        "account_id": 2451002751131,
+                        "channel_id": 5967964835131,
+                        "rule_name": "Silence Info alerts",
+                        "description": "",
+                        "from_incident_id": "000000000000000000000000",
+                        "time_filters": [],
+                        "time_filter": {
+                          "start_time": 1773388800,
+                          "end_time": 1773414000
+                        },
+                        "filters": [
+                          [
+                            {
+                              "key": "severity",
+                              "oper": "IN",
+                              "vals": [
+                                "Info"
+                              ]
+                            }
+                          ]
+                        ],
+                        "is_directly_discard": true,
+                        "status": "enabled",
+                        "rule_id": "69b3c426b4a6f5abf1f54873",
+                        "updated_by": 3790925372131,
+                        "created_at": 1773388838,
+                        "updated_at": 1773388838,
+                        "is_effective": false
+                      }
+                    ]
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -37374,6 +38705,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -37381,95 +38715,62 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Enable silence rule",
-        "tags": [
-          "On-call/Channels"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |",
-          "href": "/en/api-reference/on-call/channels/channel-silence-rule-enable",
-          "metadata": {
-            "sidebarTitle": "Enable silence rule"
-          }
-        }
-      }
-    },
-    "/channel/silence/rule/list": {
-      "post": {
-        "description": "List all silence rules configured for a channel.",
-        "operationId": "channelSilenceRuleList",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {
-                "channel_id": 1001
-              },
               "schema": {
                 "$ref": "#/components/schemas/ChannelScopedListRequest"
+              },
+              "example": {
+                "channel_id": 1001
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/channel/silence/rule/update": {
+      "post": {
+        "operationId": "channelSilenceRuleUpdate",
+        "summary": "Update silence rule",
+        "description": "Replace the configuration of an existing silence rule.",
+        "tags": [
+          "On-call/Channels"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |\n\n## Usage\n\n- The same time window and `filters` requirements as create apply. Switching between `time_filter` and `time_filters` clears the other one.\n- `description`, `is_directly_discard` and `is_auto_delete` are always overwritten, so omitting them resets them to empty or `false`. `from_incident_id` cannot be changed.\n- An unknown `channel_id` or `rule_id` returns `InvalidParameter`.\n- The caller must also be able to edit the channel: the account owner or an admin, the channel creator, or a member of its managing teams (of its owning team when `managing_team_ids` is empty). Otherwise the call returns `AccessDenied`.\n- Every call is recorded in the account audit log.",
+          "href": "/en/api-reference/on-call/channels/channel-silence-rule-update",
+          "metadata": {
+            "sidebarTitle": "Update silence rule"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "items": [
-                      {
-                        "account_id": 2451002751131,
-                        "channel_id": 5967964835131,
-                        "created_at": 1773388838,
-                        "description": "",
-                        "filters": [
-                          [
-                            {
-                              "key": "severity",
-                              "oper": "IN",
-                              "vals": [
-                                "Info"
-                              ]
-                            }
-                          ]
-                        ],
-                        "from_incident_id": "000000000000000000000000",
-                        "is_directly_discard": true,
-                        "is_effective": false,
-                        "rule_id": "69b3c426b4a6f5abf1f54873",
-                        "rule_name": "Silence Info alerts",
-                        "status": "enabled",
-                        "time_filter": {
-                          "end_time": 1773414000,
-                          "start_time": 1773388800
-                        },
-                        "time_filters": [],
-                        "updated_at": 1773388838,
-                        "updated_by": 3790925372131
-                      }
-                    ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/ListSilenceRulesResponse"
+                          "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -37477,6 +38778,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -37484,28 +38788,21 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "List silence rules",
-        "tags": [
-          "On-call/Channels"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Read** (`on-call`) |",
-          "href": "/en/api-reference/on-call/channels/channel-silence-rule-list",
-          "metadata": {
-            "sidebarTitle": "List silence rules"
-          }
-        }
-      }
-    },
-    "/channel/silence/rule/update": {
-      "post": {
-        "description": "Update an existing silence rule configuration.",
-        "operationId": "channelSilenceRuleUpdate",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/UpdateSilenceRuleRequest"
+              },
               "example": {
                 "channel_id": 1001,
+                "rule_id": "6621b23f4a2c5e0012ab34cd",
+                "rule_name": "Mute during maintenance",
+                "time_filter": {
+                  "start_time": 1710000000,
+                  "end_time": 1710086400
+                },
                 "filters": [
                   [
                     {
@@ -37516,47 +38813,57 @@
                       ]
                     }
                   ]
-                ],
-                "rule_id": "6621b23f4a2c5e0012ab34cd",
-                "rule_name": "Mute during maintenance",
-                "time_filter": {
-                  "end_time": 1710086400,
-                  "start_time": 1710000000
-                }
-              },
-              "schema": {
-                "$ref": "#/components/schemas/UpdateSilenceRuleRequest"
+                ]
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/channel/unsubscribe/rule/create": {
+      "post": {
+        "operationId": "channelUnsubscribeRuleCreate",
+        "summary": "Create drop rule",
+        "description": "Create a drop rule that discards matching alert events before any alert or incident is created.",
+        "tags": [
+          "On-call/Channels"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Drop rules are checked first, before silence and inhibit rules. An event matching any enabled drop rule is discarded: no alert, incident or notification is produced.\n- Without `filters`, or with an empty list, the rule matches nothing.\n- An unknown `channel_id` returns `InvalidParameter`.\n- The caller must also be able to edit the channel: the account owner or an admin, the channel creator, or a member of its managing teams (of its owning team when `managing_team_ids` is empty). Otherwise the call returns `AccessDenied`.\n- Every call is recorded in the account audit log.",
+          "href": "/en/api-reference/on-call/channels/channel-unsubscribe-rule-create",
+          "metadata": {
+            "sidebarTitle": "Create drop rule"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/EmptyResponse"
+                          "$ref": "#/components/schemas/RuleCreateResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "rule_id": "69db2f6ba0fe7db6448b1505",
+                    "rule_name": "Drop test environment alerts"
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -37564,6 +38871,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -37571,28 +38881,16 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Update silence rule",
-        "tags": [
-          "On-call/Channels"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |",
-          "href": "/en/api-reference/on-call/channels/channel-silence-rule-update",
-          "metadata": {
-            "sidebarTitle": "Update silence rule"
-          }
-        }
-      }
-    },
-    "/channel/unsubscribe/rule/create": {
-      "post": {
-        "description": "Create a drop rule to filter out unwanted alerts before they become incidents.",
-        "operationId": "channelUnsubscribeRuleCreate",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CreateDropRuleRequest"
+              },
               "example": {
                 "channel_id": 3521074710131,
+                "rule_name": "Drop test environment alerts",
                 "description": "Discard all alerts from the test environment before they create incidents",
                 "filters": [
                   [
@@ -37605,45 +38903,54 @@
                       ]
                     }
                   ]
-                ],
-                "rule_name": "Drop test environment alerts"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/CreateDropRuleRequest"
+                ]
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/channel/unsubscribe/rule/delete": {
+      "post": {
+        "operationId": "channelUnsubscribeRuleDelete",
+        "summary": "Delete drop rule",
+        "description": "Delete a disabled drop rule so it no longer appears in the channel's rule list.",
+        "tags": [
+          "On-call/Channels"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Only a `disabled` rule can be deleted; any other status returns `InvalidParameter`.\n- An unknown `channel_id` or `rule_id` returns `InvalidParameter`.\n- The caller must also be able to edit the channel: the account owner or an admin, the channel creator, or a member of its managing teams (of its owning team when `managing_team_ids` is empty). Otherwise the call returns `AccessDenied`.\n- Every call is recorded in the account audit log.",
+          "href": "/en/api-reference/on-call/channels/channel-unsubscribe-rule-delete",
+          "metadata": {
+            "sidebarTitle": "Delete drop rule"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "rule_id": "69db2f6ba0fe7db6448b1505",
-                    "rule_name": "Test drop rule"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/RuleCreateResponse"
+                          "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -37651,6 +38958,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -37658,63 +38968,63 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Create drop rule",
-        "tags": [
-          "On-call/Channels"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |",
-          "href": "/en/api-reference/on-call/channels/channel-unsubscribe-rule-create",
-          "metadata": {
-            "sidebarTitle": "Create drop rule"
-          }
-        }
-      }
-    },
-    "/channel/unsubscribe/rule/delete": {
-      "post": {
-        "description": "Delete a drop rule. Only a `disabled` rule can be deleted.",
-        "operationId": "channelUnsubscribeRuleDelete",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ChannelRuleIDRequest"
+              },
               "example": {
                 "channel_id": 3521074710131,
                 "rule_id": "6621b23f4a2c5e0012ab34cd"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ChannelRuleIDRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/channel/unsubscribe/rule/disable": {
+      "post": {
+        "operationId": "channelUnsubscribeRuleDisable",
+        "summary": "Disable drop rule",
+        "description": "Disable a drop rule without deleting it.",
+        "tags": [
+          "On-call/Channels"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Only an `enabled` rule can be disabled; any other status returns `InvalidParameter`.\n- An unknown `channel_id` or `rule_id` returns `InvalidParameter`.\n- The caller must also be able to edit the channel: the account owner or an admin, the channel creator, or a member of its managing teams (of its owning team when `managing_team_ids` is empty). Otherwise the call returns `AccessDenied`.\n- Every call is recorded in the account audit log.",
+          "href": "/en/api-reference/on-call/channels/channel-unsubscribe-rule-disable",
+          "metadata": {
+            "sidebarTitle": "Disable drop rule"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -37722,6 +39032,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -37729,134 +39042,63 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Delete drop rule",
-        "tags": [
-          "On-call/Channels"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |",
-          "href": "/en/api-reference/on-call/channels/channel-unsubscribe-rule-delete",
-          "metadata": {
-            "sidebarTitle": "Delete drop rule"
-          }
-        }
-      }
-    },
-    "/channel/unsubscribe/rule/disable": {
-      "post": {
-        "description": "Disable a drop rule without deleting it. Only an `enabled` rule can be disabled.",
-        "operationId": "channelUnsubscribeRuleDisable",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ChannelRuleIDRequest"
+              },
               "example": {
                 "channel_id": 3521074710131,
                 "rule_id": "6621b23f4a2c5e0012ab34cd"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ChannelRuleIDRequest"
               }
             }
-          },
-          "required": true
-        },
-        "responses": {
-          "200": {
-            "content": {
-              "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/EmptyResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
-                }
-              }
-            },
-            "description": "Success"
-          },
-          "400": {
-            "$ref": "#/components/responses/BadRequest"
-          },
-          "401": {
-            "$ref": "#/components/responses/Unauthorized"
-          },
-          "429": {
-            "$ref": "#/components/responses/TooManyRequests"
-          },
-          "500": {
-            "$ref": "#/components/responses/ServerError"
-          }
-        },
-        "summary": "Disable drop rule",
-        "tags": [
-          "On-call/Channels"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |",
-          "href": "/en/api-reference/on-call/channels/channel-unsubscribe-rule-disable",
-          "metadata": {
-            "sidebarTitle": "Disable drop rule"
           }
         }
       }
     },
     "/channel/unsubscribe/rule/enable": {
       "post": {
-        "description": "Enable a disabled drop rule. Only a `disabled` rule can be enabled.",
         "operationId": "channelUnsubscribeRuleEnable",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "channel_id": 3521074710131,
-                "rule_id": "6621b23f4a2c5e0012ab34cd"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ChannelRuleIDRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "Enable drop rule",
+        "description": "Enable a disabled drop rule so it discards matching alert events again.",
+        "tags": [
+          "On-call/Channels"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Only a `disabled` rule can be enabled; any other status returns `InvalidParameter`.\n- An unknown `channel_id` or `rule_id` returns `InvalidParameter`.\n- The caller must also be able to edit the channel: the account owner or an admin, the channel creator, or a member of its managing teams (of its owning team when `managing_team_ids` is empty). Otherwise the call returns `AccessDenied`.\n- Every call is recorded in the account audit log.",
+          "href": "/en/api-reference/on-call/channels/channel-unsubscribe-rule-enable",
+          "metadata": {
+            "sidebarTitle": "Enable drop rule"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -37864,6 +39106,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -37871,47 +39116,65 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Enable drop rule",
-        "tags": [
-          "On-call/Channels"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |",
-          "href": "/en/api-reference/on-call/channels/channel-unsubscribe-rule-enable",
-          "metadata": {
-            "sidebarTitle": "Enable drop rule"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ChannelRuleIDRequest"
+              },
+              "example": {
+                "channel_id": 3521074710131,
+                "rule_id": "6621b23f4a2c5e0012ab34cd"
+              }
+            }
           }
         }
       }
     },
     "/channel/unsubscribe/rule/list": {
       "post": {
-        "description": "List drop rules for a channel.",
         "operationId": "channelUnsubscribeRuleList",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "channel_id": 1001
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ChannelScopedListRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "List drop rules",
+        "description": "List a channel's drop rules, oldest first.",
+        "tags": [
+          "On-call/Channels"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- An unknown `channel_id` returns `InvalidParameter`.",
+          "href": "/en/api-reference/on-call/channels/channel-unsubscribe-rule-list",
+          "metadata": {
+            "sidebarTitle": "List drop rules"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/ListDropRulesResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "items": [
                       {
                         "account_id": 2451002751131,
                         "channel_id": 5967964835131,
-                        "created_at": 1773978928,
+                        "rule_name": "Drop test alerts",
                         "description": "",
                         "filters": [
                           [
@@ -37924,34 +39187,17 @@
                             }
                           ]
                         ],
-                        "rule_id": "69bcc530b9e63df36603e421",
-                        "rule_name": "Drop test alerts",
                         "status": "enabled",
-                        "updated_at": 1773978928,
-                        "updated_by": 3790925372131
+                        "rule_id": "69bcc530b9e63df36603e421",
+                        "updated_by": 3790925372131,
+                        "created_at": 1773978928,
+                        "updated_at": 1773978928
                       }
                     ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/ListDropRulesResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -37959,6 +39205,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -37966,75 +39215,62 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "List drop rules",
-        "tags": [
-          "On-call/Channels"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |",
-          "href": "/en/api-reference/on-call/channels/channel-unsubscribe-rule-list",
-          "metadata": {
-            "sidebarTitle": "List drop rules"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ChannelScopedListRequest"
+              },
+              "example": {
+                "channel_id": 1001
+              }
+            }
           }
         }
       }
     },
     "/channel/unsubscribe/rule/update": {
       "post": {
-        "description": "Update an existing drop rule configuration.",
         "operationId": "channelUnsubscribeRuleUpdate",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "channel_id": 1001,
-                "filters": [
-                  [
-                    {
-                      "key": "labels.env",
-                      "oper": "IN",
-                      "vals": [
-                        "test"
-                      ]
-                    }
-                  ]
-                ],
-                "rule_id": "6621b23f4a2c5e0012ab34cf",
-                "rule_name": "Drop test alerts"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/UpdateDropRuleRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "Update drop rule",
+        "description": "Replace the name, description and conditions of an existing drop rule.",
+        "tags": [
+          "On-call/Channels"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Full replacement: an omitted `description` becomes empty, and an omitted `filters` clears all conditions so the rule matches nothing.\n- An unknown `channel_id` or `rule_id` returns `InvalidParameter`.\n- The caller must also be able to edit the channel: the account owner or an admin, the channel creator, or a member of its managing teams (of its owning team when `managing_team_ids` is empty). Otherwise the call returns `AccessDenied`.\n- Every call is recorded in the account audit log.",
+          "href": "/en/api-reference/on-call/channels/channel-unsubscribe-rule-update",
+          "metadata": {
+            "sidebarTitle": "Update drop rule"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -38042,6 +39278,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -38049,66 +39288,77 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Update drop rule",
-        "tags": [
-          "On-call/Channels"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |",
-          "href": "/en/api-reference/on-call/channels/channel-unsubscribe-rule-update",
-          "metadata": {
-            "sidebarTitle": "Update drop rule"
-          }
-        }
-      }
-    },
-    "/channel/update": {
-      "post": {
-        "description": "Update an existing channel's configuration and settings.",
-        "operationId": "channelUpdate",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/UpdateDropRuleRequest"
+              },
               "example": {
                 "channel_id": 1001,
-                "channel_name": "Production Alerts (v2)",
-                "description": "Updated description"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/UpdateChannelRequest"
+                "rule_id": "6621b23f4a2c5e0012ab34cf",
+                "rule_name": "Drop test alerts",
+                "filters": [
+                  [
+                    {
+                      "key": "labels.env",
+                      "oper": "IN",
+                      "vals": [
+                        "test"
+                      ]
+                    }
+                  ]
+                ]
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/channel/update": {
+      "post": {
+        "operationId": "channelUpdate",
+        "summary": "Update channel",
+        "description": "Update a channel's settings; only the fields present in the request are changed.",
+        "tags": [
+          "On-call/Channels"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |\n\n## Usage\n\n- Omitted or `null` fields keep their current value. `group`, `flapping` and `event_group` each replace the whole stored object.\n- Pass `managing_team_ids: []` to remove all managing teams.\n- `auto_resolve_mode` is applied only together with `auto_resolve_timeout`; when `auto_resolve_timeout` is sent without `auto_resolve_mode`, the mode resets to `trigger`.\n- Setting `is_external_report_enabled` to `true` generates a new `external_report_token` on every call and the previous token stops working; `false` clears the token.\n- A `channel_name` used by another channel returns `InvalidParameter`; `group.method` `p` or `i` without the matching license returns `NoLicense`.\n- The caller must also be able to edit the channel: the account owner or an admin, the channel creator, or a member of its managing teams (of its owning team when `managing_team_ids` is empty). Otherwise the call returns `AccessDenied`.\n- Every call is recorded in the account audit log.",
+          "href": "/en/api-reference/on-call/channels/channel-update",
+          "metadata": {
+            "sidebarTitle": "Update channel"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "external_report_token": ""
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/UpdateChannelResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "external_report_token": ""
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -38116,6 +39366,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -38123,66 +39376,70 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Update channel",
-        "tags": [
-          "On-call/Channels"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) |",
-          "href": "/en/api-reference/on-call/channels/channel-update",
-          "metadata": {
-            "sidebarTitle": "Update channel"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/UpdateChannelRequest"
+              },
+              "example": {
+                "channel_id": 3521074710131,
+                "channel_name": "Production Alerts (v2)",
+                "description": "Updated description"
+              }
+            }
           }
         }
       }
     },
     "/datasource/im/person/try-link": {
       "post": {
-        "description": "Try to automatically link unbound members to their IM accounts for one integration.",
         "operationId": "datasourceImPersonTryLink",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "integration_id": 6113996590131
-              },
-              "schema": {
-                "$ref": "#/components/schemas/TryLinkPersonRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "Attempt IM person linking",
+        "description": "Try to automatically link unbound members to their IM accounts for one integration.",
+        "tags": [
+          "On-call/Integrations"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Integrations Manage** (`on-call`) |\n\n## Usage\n\n- Looks up every account member not yet linked to this integration's IM app by email and phone; only Feishu, DingTalk and WeCom integrations are supported, other types return `InvalidParameter`.\n- A disabled integration returns `InvalidParameter`.\n- Returns `RequestLocked` while another linking run for the same integration is in progress, and `InvalidParameter` when the IM platform refuses the lookup (missing contact permissions or rejected credentials).\n- `new_linked_person_ids` is an empty array when nobody could be newly linked.",
+          "href": "/en/api-reference/on-call/integrations/datasource-im-person-try-link",
+          "metadata": {
+            "sidebarTitle": "Attempt IM person linking"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "new_linked_person_ids": [
-                      5348648172131
-                    ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/TryLinkPersonResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "new_linked_person_ids": [
+                      5348648172131
+                    ],
+                    "unmatched_count": 2,
+                    "no_contact_count": 1
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -38190,6 +39447,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -38197,88 +39457,90 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Attempt IM person linking",
-        "tags": [
-          "On-call/Integrations"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Integrations Manage** (`on-call`) |\n\n## Usage\n\n- The server uses member email and phone values to find matching users in DingTalk, Feishu, or WeCom.\n- When no member can be linked, the response either carries an empty `new_linked_person_ids` array or omits the `data` field entirely.",
-          "href": "/en/api-reference/on-call/integrations/datasource-im-person-try-link",
-          "metadata": {
-            "sidebarTitle": "Attempt IM person linking"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/TryLinkPersonRequest"
+              },
+              "example": {
+                "integration_id": 6113996590131
+              }
+            }
           }
         }
       }
     },
     "/datasource/im/war-room-enabled/list": {
       "post": {
-        "description": "List IM integrations that have the war-room feature enabled for the account.",
         "operationId": "im-war-room-enabled-list",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {},
-              "schema": {
-                "type": "object"
-              }
-            }
-          },
-          "required": true
+        "summary": "List war-room-enabled IM integrations",
+        "description": "List IM integrations that have the war-room feature enabled for the account.",
+        "tags": [
+          "On-call/IM integrations"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Read** (`on-call`) or **Channels Manage** (`on-call`) or **Incidents Read** (`on-call`) or **Incidents Manage** (`on-call`) or **Integrations Read** (`on-call`) or **Integrations Manage** (`on-call`) |\n\n## Usage\n\n- Returns enabled and disabled Feishu, DingTalk, WeCom, Slack, and Microsoft Teams integrations whose settings have `war_room_enabled` set to `true`; deleted integrations are excluded.\n- Secret values inside `settings` are masked as `******`.",
+          "href": "/en/api-reference/on-call/integrations/im-war-room-enabled-list",
+          "metadata": {
+            "sidebarTitle": "List war-room-enabled IM integrations"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/ListWarRoomEnabledResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "items": [
                       {
+                        "data_source_id": 362,
                         "account_id": 10001,
+                        "team_id": 0,
+                        "plugin_id": 101,
+                        "name": "Feishu Ops",
+                        "status": "enabled",
                         "category": "im",
-                        "created_at": 1716962400,
-                        "creator_id": 20001,
-                        "data_source_id": 362,
+                        "plugin_type": "feishu_app",
+                        "plugin_type_name": "Feishu",
                         "description": "Feishu war-room integration",
-                        "exclusive_data_source_id": 0,
-                        "integration_id": 362,
                         "integration_key": "ik_8f3a2b1c9d0e",
-                        "last_time": 0,
-                        "name": "Feishu Ops",
-                        "no_editable": false,
-                        "plugin_id": 101,
-                        "plugin_type": "feishu",
-                        "plugin_type_name": "Feishu",
                         "ref_id": "",
                         "settings": {
                           "war_room_enabled": true
                         },
-                        "status": "enabled",
-                        "team_id": 0,
+                        "no_editable": false,
+                        "creator_id": 20001,
+                        "updated_by": 20001,
+                        "created_at": 1716962400,
                         "updated_at": 1716962700,
-                        "updated_by": 20001
+                        "last_time": 0,
+                        "exclusive_data_source_id": 0,
+                        "integration_id": 362
                       }
                     ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/ListWarRoomEnabledResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -38286,6 +39548,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -38293,80 +39558,78 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "List war-room-enabled IM integrations",
-        "tags": [
-          "On-call/IM integrations"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n",
-          "href": "/en/api-reference/on-call/integrations/im-war-room-enabled-list",
-          "metadata": {
-            "sidebarTitle": "List war-room-enabled IM integrations"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object"
+              },
+              "example": {}
+            }
           }
         }
       }
     },
     "/enrichment/info": {
       "post": {
-        "description": "Return the enrichment rule set configured for a specific integration.",
         "operationId": "enrichment-read-info",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "integration_id": 5001
-              },
-              "schema": {
-                "$ref": "#/components/schemas/EnrichmentInfoRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "Get enrichment rules",
+        "description": "Return the enrichment rule set configured for a specific integration.",
+        "tags": [
+          "On-call/Alert enrichment"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Read** (`on-call`) or **Channels Manage** (`on-call`) or **Integrations Read** (`on-call`) or **Integrations Manage** (`on-call`) |\n\n## Usage\n\n- `integration_id` must be an existing integration of the account; otherwise `InvalidParameter`.\n- Returns `data: null` when the integration has no rule set.",
+          "href": "/en/api-reference/on-call/alert-enrichment/enrichment-read-info",
+          "metadata": {
+            "sidebarTitle": "Get enrichment rules"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "created_at": 1710000000,
-                    "creator_id": 80011,
-                    "integration_id": 5001,
-                    "rules": [
-                      {
-                        "kind": "extraction",
-                        "settings": {
-                          "override": true,
-                          "pattern": "^(prod|staging|dev).*$",
-                          "result_label": "environment",
-                          "source_field": "labels.env"
-                        }
-                      }
-                    ],
-                    "status": "enabled",
-                    "updated_at": 1710000000,
-                    "updated_by": 80011
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EnrichmentItem"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "integration_id": 5001,
+                    "rules": [
+                      {
+                        "kind": "extraction",
+                        "settings": {
+                          "source_field": "labels.env",
+                          "result_label": "environment",
+                          "pattern": "^(prod|staging|dev).*$",
+                          "override": true
+                        }
+                      }
+                    ],
+                    "status": "enabled",
+                    "updated_by": 80011,
+                    "creator_id": 80011,
+                    "created_at": 1710000000,
+                    "updated_at": 1710000000
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -38374,6 +39637,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -38381,77 +39647,74 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Get enrichment rules",
-        "tags": [
-          "On-call/Alert enrichment"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Read** (`on-call`) or **Channels Manage** (`on-call`) or **Integrations Read** (`on-call`) or **Integrations Manage** (`on-call`) |\n\n## Usage\n\n- Returns `null` if no enrichment rules have been configured for the integration.",
-          "href": "/en/api-reference/on-call/alert-enrichment/enrichment-read-info",
-          "metadata": {
-            "sidebarTitle": "Get enrichment rules"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/EnrichmentInfoRequest"
+              },
+              "example": {
+                "integration_id": 5001
+              }
+            }
           }
         }
       }
     },
     "/enrichment/list": {
       "post": {
-        "description": "Return the enrichment rule sets for a list of integration IDs.",
         "operationId": "enrichment-read-list",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "integration_ids": [
-                  5001,
-                  5002
-                ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/EnrichmentListRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "List enrichment rules",
+        "description": "Return the enrichment rule sets for a list of integration IDs.",
+        "tags": [
+          "On-call/Alert enrichment"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Integrations Read** (`on-call`) or **Integrations Manage** (`on-call`) |\n\n## Usage\n\n- Every ID must be an existing integration of the account; otherwise `InvalidParameter`.\n- Integrations that have no rule set are left out of `items`.",
+          "href": "/en/api-reference/on-call/alert-enrichment/enrichment-read-list",
+          "metadata": {
+            "sidebarTitle": "List enrichment rules"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "items": [
-                      {
-                        "created_at": 1710000000,
-                        "creator_id": 80011,
-                        "integration_id": 5001,
-                        "rules": [],
-                        "status": "enabled",
-                        "updated_at": 1710000000,
-                        "updated_by": 80011
-                      }
-                    ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EnrichmentListResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "items": [
+                      {
+                        "integration_id": 5001,
+                        "rules": [],
+                        "status": "enabled",
+                        "updated_by": 80011,
+                        "creator_id": 80011,
+                        "created_at": 1710000000,
+                        "updated_at": 1710000000
+                      }
+                    ]
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -38459,6 +39722,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -38466,73 +39732,68 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "List enrichment rules",
-        "tags": [
-          "On-call/Alert enrichment"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Integrations Read** (`on-call`) or **Integrations Manage** (`on-call`) |",
-          "href": "/en/api-reference/on-call/alert-enrichment/enrichment-read-list",
-          "metadata": {
-            "sidebarTitle": "List enrichment rules"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/EnrichmentListRequest"
+              },
+              "example": {
+                "integration_ids": [
+                  5001,
+                  5002
+                ]
+              }
+            }
           }
         }
       }
     },
     "/enrichment/mapping/api/create": {
       "post": {
-        "description": "Create a new external HTTP API endpoint used to enrich alerts via HTTP lookup.",
         "operationId": "mapping-api-write-create",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "api_name": "CMDB API",
-                "description": "Query CMDB for host metadata",
-                "headers": {
-                  "X-Token": "mytoken"
-                },
-                "insecure_skip_verify": false,
-                "retry_count": 1,
-                "timeout": 2,
-                "url": "https://cmdb.example.com/api/lookup"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/MappingAPICreateRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "Create mapping API",
+        "description": "Register an external HTTP API that enrichment rules call to look up alert labels.",
+        "tags": [
+          "On-call/Alert enrichment"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Mappings Manage** (`on-call`) |\n\n## Usage\n\n- An enrichment rule with `mapping_type` = `api` sends `POST <url>` with the configured `headers` and the JSON body `{\"result_label_keys\": [...], \"event\": {...}}` (the alert event). The API must answer HTTP 200 with `{\"result_labels\": {\"<label>\": \"<value>\"}}`.\n- `url` must use `http` or `https`; in SaaS the host must not resolve to an internal IP address.\n- `timeout` is the total request timeout in seconds (1–3, default 2); `retry_count` is the number of retries after a failure (0–1, default 0).\n- In SaaS, sensitive header names are rejected: `Authorization`, `Proxy-Authorization`, `Cookie`, `X-Api-Key`, `X-Access-Token`, `X-Forwarded-For`, `X-Real-Ip`, `True-Client-Ip`, `X-Client-Ip`, `Host`, `X-Forwarded-Host`, `X-Forwarded-Proto`, `X-Internal-Id`, `X-User-Id`, `Transfer-Encoding`, `Upgrade`, `Connection` (case-insensitive).\n- `api_name` must be unique among non-deleted mapping APIs; an account holds at most 50 non-deleted mapping APIs. A non-zero `team_id` must be an existing team.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "href": "/en/api-reference/on-call/alert-enrichment/mapping-api-write-create",
+          "metadata": {
+            "sidebarTitle": "Create mapping API"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "api_id": "665f1a2b3c4d5e6f7a8b9c02",
-                    "api_name": "CMDB API"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/MappingAPICreateResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "api_id": "665f1a2b3c4d5e6f7a8b9c02",
+                    "api_name": "CMDB API"
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -38540,6 +39801,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -38547,62 +39811,70 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Create mapping API",
-        "tags": [
-          "On-call/Alert enrichment"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Mappings Manage** (`on-call`) |\n\n## Usage\n\n- `url` must start with `http://` or `https://` and cannot resolve to an internal IP (in SaaS mode).\n- `timeout` is the HTTP read timeout in seconds (1–3, default 2).\n- `retry_count` is the number of retries on failure (0–1, default 0).\n- Headers with security-sensitive names (e.g. `authorization`, `cookie`) are rejected in SaaS mode.\n- An account can have at most 50 mapping APIs.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
-          "href": "/en/api-reference/on-call/alert-enrichment/mapping-api-write-create",
-          "metadata": {
-            "sidebarTitle": "Create mapping API"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/MappingAPICreateRequest"
+              },
+              "example": {
+                "api_name": "CMDB API",
+                "description": "Query CMDB for host metadata",
+                "url": "https://cmdb.example.com/api/lookup",
+                "headers": {
+                  "X-Token": "mytoken"
+                },
+                "timeout": 2,
+                "retry_count": 1,
+                "insecure_skip_verify": false
+              }
+            }
           }
         }
       }
     },
     "/enrichment/mapping/api/delete": {
       "post": {
-        "description": "Delete a mapping API. Deletion is blocked if the API is referenced by any enrichment rule.",
         "operationId": "mapping-api-write-delete",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "api_id": "665f1a2b3c4d5e6f7a8b9c02"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/MappingAPIIDRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "Delete mapping API",
+        "description": "Soft-delete a mapping API; refused while an enrichment rule uses it.",
+        "tags": [
+          "On-call/Alert enrichment"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Mappings Manage** (`on-call`) |\n\n## Usage\n\n- The mapping API is soft-deleted (`status` becomes `deleted`) and enrichment rules stop calling it.\n- If an integration's enrichment rule uses it (`mapping_type` = `api`), the call returns HTTP 400 `ReferenceExist` with `data.refs` listing up to 20 integrations (`kind` = `integration`).\n- An unknown `api_id` returns `InvalidParameter`.\n- Only an account admin, the mapping API creator, or a member of the mapping API's owning team may call this; others get `AccessDenied`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "href": "/en/api-reference/on-call/alert-enrichment/mapping-api-write-delete",
+          "metadata": {
+            "sidebarTitle": "Delete mapping API"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -38610,6 +39882,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -38617,73 +39892,79 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Delete mapping API",
-        "tags": [
-          "On-call/Alert enrichment"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Mappings Manage** (`on-call`) |\n\n## Usage\n\n- If the API is still referenced, the response returns HTTP 400 with a `refs` list.\n- Only the API creator, account admin, or team member can delete the API.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
-          "href": "/en/api-reference/on-call/alert-enrichment/mapping-api-write-delete",
-          "metadata": {
-            "sidebarTitle": "Delete mapping API"
-          }
-        }
-      }
-    },
-    "/enrichment/mapping/api/info": {
-      "post": {
-        "description": "Return detail of a single mapping API by its ID.",
-        "operationId": "mapping-api-read-info",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {
-                "api_id": "665f1a2b3c4d5e6f7a8b9c02"
-              },
               "schema": {
                 "$ref": "#/components/schemas/MappingAPIIDRequest"
+              },
+              "example": {
+                "api_id": "665f1a2b3c4d5e6f7a8b9c02"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/enrichment/mapping/api/info": {
+      "post": {
+        "operationId": "mapping-api-read-info",
+        "summary": "Get mapping API detail",
+        "description": "Return detail of a single mapping API by its ID.",
+        "tags": [
+          "On-call/Alert enrichment"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Returns `data: null` when no mapping API with this ID exists in the account.\n- A soft-deleted mapping API is still returned, with `status` = `deleted`.\n- There is no team check: any caller in the account can read any mapping API, including its `headers` in plain text.",
+          "href": "/en/api-reference/on-call/alert-enrichment/mapping-api-read-info",
+          "metadata": {
+            "sidebarTitle": "Get mapping API detail"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "api_id": "665f1a2b3c4d5e6f7a8b9c02",
-                    "api_name": "CMDB API",
-                    "created_at": 1710000000,
-                    "creator_id": 80011,
-                    "insecure_skip_verify": false,
-                    "retry_count": 1,
-                    "status": "enabled",
-                    "timeout": 2,
-                    "updated_at": 1710000000,
-                    "url": "https://cmdb.example.com/api/lookup"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/MappingAPIItem"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "api_id": "665f1a2b3c4d5e6f7a8b9c02",
+                    "api_name": "CMDB API",
+                    "description": "Query CMDB for host metadata",
+                    "url": "https://cmdb.example.com/api/lookup",
+                    "headers": {
+                      "X-Token": "example-token"
+                    },
+                    "timeout": 2,
+                    "retry_count": 1,
+                    "insecure_skip_verify": false,
+                    "status": "enabled",
+                    "team_id": 0,
+                    "creator_id": 80011,
+                    "updated_by": 80011,
+                    "created_at": 1710000000,
+                    "updated_at": 1710000000
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -38691,6 +39972,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -38698,81 +39982,84 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Get mapping API detail",
-        "tags": [
-          "On-call/Alert enrichment"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Returns `null` if the API does not exist.",
-          "href": "/en/api-reference/on-call/alert-enrichment/mapping-api-read-info",
-          "metadata": {
-            "sidebarTitle": "Get mapping API detail"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/MappingAPIIDRequest"
+              },
+              "example": {
+                "api_id": "665f1a2b3c4d5e6f7a8b9c02"
+              }
+            }
           }
         }
       }
     },
     "/enrichment/mapping/api/list": {
       "post": {
-        "description": "Return all mapping APIs configured for the account.",
         "operationId": "mapping-api-read-list",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {},
-              "schema": {
-                "$ref": "#/components/schemas/EmptyRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "List mapping APIs",
+        "description": "Return all mapping APIs of the account, newest first.",
+        "tags": [
+          "On-call/Alert enrichment"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Mappings Read** (`on-call`) or **Mappings Manage** (`on-call`) |\n\n## Usage\n\n- Returns every non-deleted mapping API in one response, without pagination; `total` is the number of items.\n- Mapping APIs of all teams are returned, with their `headers` in plain text.",
+          "href": "/en/api-reference/on-call/alert-enrichment/mapping-api-read-list",
+          "metadata": {
+            "sidebarTitle": "List mapping APIs"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/MappingAPIListResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
+                    "total": 1,
                     "items": [
                       {
                         "api_id": "665f1a2b3c4d5e6f7a8b9c02",
                         "api_name": "CMDB API",
-                        "created_at": 1710000000,
-                        "creator_id": 80011,
                         "description": "Query CMDB for host metadata",
+                        "url": "https://cmdb.example.com/api/lookup",
                         "headers": {
-                          "Authorization": "Bearer eyJhbGciOiJIUzI1NiJ9.example-token"
+                          "X-Token": "example-token"
                         },
-                        "insecure_skip_verify": false,
+                        "timeout": 2,
                         "retry_count": 1,
+                        "insecure_skip_verify": false,
                         "status": "enabled",
                         "team_id": 0,
-                        "timeout": 2,
-                        "updated_at": 1710000000,
-                        "url": "https://cmdb.example.com/api/lookup"
+                        "creator_id": 80011,
+                        "updated_by": 80011,
+                        "created_at": 1710000000,
+                        "updated_at": 1710000000
                       }
-                    ],
-                    "total": 1
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/MappingAPIListResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                    ]
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -38780,6 +40067,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -38787,64 +40077,60 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "List mapping APIs",
-        "tags": [
-          "On-call/Alert enrichment"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Mappings Read** (`on-call`) or **Mappings Manage** (`on-call`) |",
-          "href": "/en/api-reference/on-call/alert-enrichment/mapping-api-read-list",
-          "metadata": {
-            "sidebarTitle": "List mapping APIs"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/EmptyRequest"
+              },
+              "example": {}
+            }
           }
         }
       }
     },
     "/enrichment/mapping/api/update": {
       "post": {
-        "description": "Update configuration of an existing mapping API.",
         "operationId": "mapping-api-write-update",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "api_id": "665f1a2b3c4d5e6f7a8b9c02",
-                "retry_count": 1,
-                "timeout": 3
-              },
-              "schema": {
-                "$ref": "#/components/schemas/MappingAPIUpdateRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "Update mapping API",
+        "description": "Update configuration of an existing mapping API.",
+        "tags": [
+          "On-call/Alert enrichment"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Mappings Manage** (`on-call`) |\n\n## Usage\n\n- Fields left out keep their current values. `headers`, when sent, replaces the whole header map; send `{}` to remove all headers. `team_id` `0` removes the team.\n- The fields you send are validated as on create (`url` scheme and internal-address check, header rules, `timeout` 1–3, `retry_count` 0–1); `description` is cut to 500 characters.\n- An unknown `api_id` returns `InvalidParameter`; a new `api_name` must not be used by another mapping API.\n- Only an account admin, the mapping API creator, or a member of the mapping API's owning team may call this; others get `AccessDenied`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "href": "/en/api-reference/on-call/alert-enrichment/mapping-api-write-update",
+          "metadata": {
+            "sidebarTitle": "Update mapping API"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -38852,6 +40138,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -38859,66 +40148,64 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Update mapping API",
-        "tags": [
-          "On-call/Alert enrichment"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Mappings Manage** (`on-call`) |\n\n## Usage\n\n- Only the API creator, account admin, or team member can update the API.\n- All updatable fields are optional — only provided fields are changed.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
-          "href": "/en/api-reference/on-call/alert-enrichment/mapping-api-write-update",
-          "metadata": {
-            "sidebarTitle": "Update mapping API"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/MappingAPIUpdateRequest"
+              },
+              "example": {
+                "api_id": "665f1a2b3c4d5e6f7a8b9c02",
+                "timeout": 3,
+                "retry_count": 1
+              }
+            }
           }
         }
       }
     },
     "/enrichment/mapping/data/delete": {
       "post": {
-        "description": "Delete up to 100 mapping data rows by their keys.",
         "operationId": "mapping-data-write-delete",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "keys": [
-                  "server01",
-                  "server02"
-                ],
-                "schema_id": "665f1a2b3c4d5e6f7a8b9c01"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/MappingDataDeleteRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "Delete mapping data rows",
+        "description": "Delete up to 100 mapping data rows by their keys.",
+        "tags": [
+          "On-call/Alert enrichment"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Mappings Manage** (`on-call`) |\n\n## Usage\n\n- `keys` are the row `key` values returned by `/enrichment/mapping/data/list` or `/enrichment/mapping/data/upsert`; keys that match no row are ignored.\n- The schema must exist and not be deleted; otherwise `InvalidParameter`.\n- Only an account admin, the schema creator, or a member of the schema's owning team may call this; others get `AccessDenied`.\n- Data writes to one schema (upsert, delete, truncate, CSV upload) run one at a time; a call made while another is running returns `RequestTooFrequently`.",
+          "href": "/en/api-reference/on-call/alert-enrichment/mapping-data-write-delete",
+          "metadata": {
+            "sidebarTitle": "Delete mapping data rows"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -38926,6 +40213,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -38933,49 +40223,53 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Delete mapping data rows",
-        "tags": [
-          "On-call/Alert enrichment"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Mappings Manage** (`on-call`) |",
-          "href": "/en/api-reference/on-call/alert-enrichment/mapping-data-write-delete",
-          "metadata": {
-            "sidebarTitle": "Delete mapping data rows"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/MappingDataDeleteRequest"
+              },
+              "example": {
+                "schema_id": "665f1a2b3c4d5e6f7a8b9c01",
+                "keys": [
+                  "server01",
+                  "server02"
+                ]
+              }
+            }
           }
         }
       }
     },
     "/enrichment/mapping/data/download": {
       "post": {
-        "description": "Export all data rows of a mapping schema as a CSV file download.",
         "operationId": "mapping-data-read-download",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "schema_id": "665f1a2b3c4d5e6f7a8b9c01"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/MappingSchemaIDRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "Download mapping data as CSV",
+        "description": "Export all data rows of a mapping schema as a CSV file download.",
+        "tags": [
+          "On-call/Alert enrichment"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **60 requests/minute**; **3 requests/second** per account |\n| Permissions | **Integrations Read** (`on-call`) or **Integrations Manage** (`on-call`) or **Mappings Read** (`on-call`) or **Mappings Manage** (`on-call`) |\n\n## Usage\n\n- The response is a CSV stream (`Content-Type: application/octet-stream`), not JSON. The file name in `Content-Disposition` is the schema name with spaces replaced by `_`.\n- The first row lists `source_labels` followed by `result_labels`; each following row is one data row, most recently written first.\n- The schema must exist and not be deleted; otherwise a JSON `InvalidParameter` error is returned.",
+          "href": "/en/api-reference/on-call/alert-enrichment/mapping-data-read-download",
+          "metadata": {
+            "sidebarTitle": "Download mapping data as CSV"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success. CSV attachment stream, not a JSON envelope.",
             "content": {
               "application/octet-stream": {
-                "example": "host,owner,team\nserver01,alice,sre\nserver02,bob,backend\n",
                 "schema": {
-                  "description": "CSV file stream (`Content-Type: application/octet-stream`, `Content-Disposition: attachment; filename=<schema_name>.csv`). The header row lists the schema's source_labels followed by result_labels in order; each subsequent row is one mapping document.",
+                  "type": "string",
                   "format": "binary",
-                  "type": "string"
-                }
+                  "description": "CSV file stream (`Content-Type: application/octet-stream`, `Content-Disposition: attachment; filename=<schema_name>.csv`). The header row lists the schema's source_labels followed by result_labels in order; each subsequent row is one mapping document."
+                },
+                "example": "host,owner,team,service\nserver01,alice,sre,api\n"
               }
-            },
-            "description": "Success. CSV attachment stream, not a JSON envelope."
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -38983,6 +40277,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -38990,82 +40287,156 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Download mapping data as CSV",
-        "tags": [
-          "On-call/Alert enrichment"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Integrations Read** (`on-call`) or **Integrations Manage** (`on-call`) or **Mappings Read** (`on-call`) or **Mappings Manage** (`on-call`) |\n\n## Usage\n\n- The response is a CSV file with `Content-Disposition: attachment` header.\n- The CSV header row matches the schema's source and result labels in order.",
-          "href": "/en/api-reference/on-call/alert-enrichment/mapping-data-read-download",
-          "metadata": {
-            "sidebarTitle": "Download mapping data as CSV"
-          }
-        }
-      }
-    },
-    "/enrichment/mapping/data/list": {
-      "post": {
-        "description": "Return paginated mapping data rows for a schema, with optional exact-match filtering on source label values.",
-        "operationId": "mapping-data-read-list",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/MappingSchemaIDRequest"
+              },
               "example": {
-                "asc": false,
-                "limit": 20,
-                "orderby": "updated_at",
-                "p": 1,
                 "schema_id": "665f1a2b3c4d5e6f7a8b9c01"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/MappingDataListRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/enrichment/mapping/data/list": {
+      "post": {
+        "operationId": "mapping-data-read-list",
+        "summary": "List mapping data",
+        "description": "Return paginated mapping data rows for a schema, with optional exact-match filtering on source label values.",
+        "tags": [
+          "On-call/Alert enrichment"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Integrations Read** (`on-call`) or **Integrations Manage** (`on-call`) or **Mappings Read** (`on-call`) or **Mappings Manage** (`on-call`) |\n\n## Usage\n\n- The schema must exist and not be deleted; otherwise `InvalidParameter`.\n- `query` filters by exact source label values. Keys that are not source labels are dropped; if any key remains, every source label must be given, otherwise `InvalidParameter`.\n- Page-based navigation (`p`, `limit`) reaches at most 10,000 rows (`p * limit <= 10000`); go further with `search_after_ctx`.\n- `total` counts at most 1,000 matching rows; `used_cnt` is the schema's full row count.",
+          "href": "/en/api-reference/on-call/alert-enrichment/mapping-data-read-list",
+          "metadata": {
+            "sidebarTitle": "List mapping data"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/MappingDataListResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
-                    "has_next_page": false,
                     "items": [
                       {
-                        "created_at": 1710000000,
+                        "key": "02b8754747905747f7f76d802202d214",
                         "fields": {
                           "host": "server01",
                           "owner": "alice",
-                          "service": "api",
-                          "team": "sre"
+                          "team": "sre",
+                          "service": "api"
                         },
-                        "key": "server01",
+                        "created_at": 1710000000,
                         "updated_at": 1710000000
                       }
                     ],
-                    "total": 1
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
+                    "total": 1,
+                    "has_next_page": false,
+                    "used_cnt": 1
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "429": {
+            "$ref": "#/components/responses/TooManyRequests"
+          },
+          "500": {
+            "$ref": "#/components/responses/ServerError"
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/MappingDataListRequest"
+              },
+              "example": {
+                "schema_id": "665f1a2b3c4d5e6f7a8b9c01",
+                "orderby": "updated_at",
+                "asc": false,
+                "p": 1,
+                "limit": 20
+              }
+            }
+          }
+        }
+      }
+    },
+    "/enrichment/mapping/data/truncate": {
+      "post": {
+        "operationId": "mapping-data-write-truncate",
+        "summary": "Truncate mapping data",
+        "description": "Delete all data rows in a mapping schema.",
+        "tags": [
+          "On-call/Alert enrichment"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Mappings Manage** (`on-call`) |\n\n## Usage\n\n- Permanently deletes every data row of the schema; the schema itself is kept.\n- The schema must exist and not be deleted; otherwise `InvalidParameter`.\n- Only an account admin, the schema creator, or a member of the schema's owning team may call this; others get `AccessDenied`.\n- Data writes to one schema (upsert, delete, truncate, CSV upload) run one at a time; a call made while another is running returns `RequestTooFrequently`.",
+          "href": "/en/api-reference/on-call/alert-enrichment/mapping-data-write-truncate",
+          "metadata": {
+            "sidebarTitle": "Truncate mapping data"
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/MappingDataListResponse"
+                          "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -39073,6 +40444,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -39080,62 +40454,62 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "List mapping data",
-        "tags": [
-          "On-call/Alert enrichment"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Integrations Read** (`on-call`) or **Integrations Manage** (`on-call`) or **Mappings Read** (`on-call`) or **Mappings Manage** (`on-call`) |\n\n## Usage\n\n- If `query` is provided, all source labels must be specified — partial source label queries are rejected.\n- Pagination uses cursor-based (`search_after_ctx`) or page-based (`p`, `limit`) navigation. `limit` defaults to 20, max 100.\n- The `search_after_ctx` token from a response can be passed back to retrieve the next page.",
-          "href": "/en/api-reference/on-call/alert-enrichment/mapping-data-read-list",
-          "metadata": {
-            "sidebarTitle": "List mapping data"
-          }
-        }
-      }
-    },
-    "/enrichment/mapping/data/truncate": {
-      "post": {
-        "description": "Delete all data rows in a mapping schema.",
-        "operationId": "mapping-data-write-truncate",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {
-                "schema_id": "665f1a2b3c4d5e6f7a8b9c01"
-              },
               "schema": {
                 "$ref": "#/components/schemas/MappingSchemaIDRequest"
+              },
+              "example": {
+                "schema_id": "665f1a2b3c4d5e6f7a8b9c01"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/enrichment/mapping/data/upload": {
+      "post": {
+        "operationId": "mapping-data-write-upload",
+        "summary": "Upload mapping data via CSV",
+        "description": "Upload a CSV file to bulk-load mapping data. By default the existing data is truncated before loading the new rows.",
+        "tags": [
+          "On-call/Alert enrichment"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **60 requests/minute**; **3 requests/second** per account |\n| Permissions | **Mappings Manage** (`on-call`) |\n\n## Usage\n\n- Send `multipart/form-data` with the CSV in the `file` field; `schema_id` and `do_not_truncate_first` are query parameters. The file may be at most 100 MB.\n- The first CSV row is the header and must contain every source and result label; other columns are dropped. Values longer than 2,048 bytes are rejected, and byte-order marks are stripped. A file with no data rows returns `InvalidParameter`.\n- By default all existing rows are deleted before the import. With `do_not_truncate_first=TRUE` existing rows are kept and rows with the same source label values are replaced.\n- Rows with the same source label values are merged; the later row wins.\n- The schema row limit (10,000 rows by default, higher for some accounts) is checked against the row count after the import; exceeding it returns `InvalidParameter`.\n- Rows are written in batches of 100. If a batch fails, the truncation and the batches before it stay applied.\n- The schema must exist and not be deleted; otherwise `InvalidParameter`.\n- Only an account admin, the schema creator, or a member of the schema's owning team may call this; others get `AccessDenied`.\n- Data writes to one schema (upsert, delete, truncate, CSV upload) run one at a time; a call made while another is running returns `RequestTooFrequently`.",
+          "href": "/en/api-reference/on-call/alert-enrichment/mapping-data-write-upload",
+          "metadata": {
+            "sidebarTitle": "Upload mapping data via CSV"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -39143,6 +40517,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -39150,94 +40527,99 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Truncate mapping data",
-        "tags": [
-          "On-call/Alert enrichment"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Mappings Manage** (`on-call`) |\n\n## Usage\n\n- This is an irreversible bulk-delete operation.\n- High-risk operation. Console JWT callers must pass a second-factor code; `app_key` callers bypass the MFA prompt but remain audited — treat the key as a secret.",
-          "href": "/en/api-reference/on-call/alert-enrichment/mapping-data-write-truncate",
-          "metadata": {
-            "sidebarTitle": "Truncate mapping data"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "multipart/form-data": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "file": {
+                    "type": "string",
+                    "format": "binary",
+                    "description": "CSV file, max 100 MB. The header row must include all of the schema's source/result label names."
+                  }
+                },
+                "required": [
+                  "file"
+                ]
+              }
+            }
           }
-        }
-      }
-    },
-    "/enrichment/mapping/data/upload": {
-      "post": {
-        "description": "Upload a CSV file to bulk-load mapping data. By default the existing data is truncated before loading the new rows.",
-        "operationId": "mapping-data-write-upload",
+        },
         "parameters": [
           {
-            "description": "ID of the target mapping schema (ObjectID hex).",
-            "example": "665f1a2b3c4d5e6f7a8b9c01",
-            "in": "query",
             "name": "schema_id",
+            "in": "query",
             "required": true,
             "schema": {
-              "pattern": "^[0-9a-fA-F]{24}$",
-              "type": "string"
-            }
+              "type": "string",
+              "pattern": "^[0-9a-fA-F]{24}$"
+            },
+            "description": "ID of the target mapping schema (ObjectID hex).",
+            "example": "665f1a2b3c4d5e6f7a8b9c01"
           },
           {
-            "description": "Pass `TRUE` (case-insensitive) to append instead of replacing. When omitted and the schema already has data, the server truncates existing rows before importing.",
-            "in": "query",
             "name": "do_not_truncate_first",
+            "in": "query",
             "required": false,
             "schema": {
+              "type": "string",
               "enum": [
                 "TRUE"
-              ],
-              "type": "string"
-            }
+              ]
+            },
+            "description": "Pass `TRUE` (case-insensitive) to append instead of replacing. When omitted and the schema already has data, the server truncates existing rows before importing."
           }
+        ]
+      }
+    },
+    "/enrichment/mapping/data/upsert": {
+      "post": {
+        "operationId": "mapping-data-write-upsert",
+        "summary": "Upsert mapping data rows",
+        "description": "Insert or update up to 1000 data rows in a mapping schema. Each row must contain all source and result labels.",
+        "tags": [
+          "On-call/Alert enrichment"
         ],
-        "requestBody": {
-          "content": {
-            "multipart/form-data": {
-              "schema": {
-                "properties": {
-                  "file": {
-                    "description": "CSV file, max 100 MB. The header row must include all of the schema's source/result label names.",
-                    "format": "binary",
-                    "type": "string"
-                  }
-                },
-                "required": [
-                  "file"
-                ],
-                "type": "object"
-              }
-            }
-          },
-          "required": true
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Mappings Manage** (`on-call`) |\n\n## Usage\n\n- A row is identified by its source label values. A row whose values match an existing row replaces it entirely, and its `created_at` and `updated_at` are reset.\n- Each row must contain every source and result label (otherwise `InvalidParameter`); other keys are dropped. Values longer than 2,048 bytes are rejected.\n- Rows with the same source label values in one request are merged; the later row wins.\n- A schema holds at most 10,000 rows by default (higher for some accounts). A request that would grow the schema beyond the limit returns `InvalidParameter`; replacing existing rows is still allowed.\n- Rows are written in batches of 100; if a batch fails, the batches before it stay written.\n- The schema must exist and not be deleted; otherwise `InvalidParameter`.\n- Only an account admin, the schema creator, or a member of the schema's owning team may call this; others get `AccessDenied`.\n- Data writes to one schema (upsert, delete, truncate, CSV upload) run one at a time; a call made while another is running returns `RequestTooFrequently`.",
+          "href": "/en/api-reference/on-call/alert-enrichment/mapping-data-write-upsert",
+          "metadata": {
+            "sidebarTitle": "Upsert mapping data rows"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/EmptyResponse"
+                          "$ref": "#/components/schemas/MappingDataUpsertResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "keys": [
+                      "server01",
+                      "server02"
+                    ]
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -39245,6 +40627,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -39252,81 +40637,79 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Upload mapping data via CSV",
-        "tags": [
-          "On-call/Alert enrichment"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **20 requests/minute**; **2 requests/second** per account |\n| Permissions | **Mappings Manage** (`on-call`) |\n\n## Usage\n\n- The request must use `Content-Type: multipart/form-data`. The file field name is `file` and `schema_id` is a query parameter.\n- CSV header row must include all source and result label names.\n- Maximum file size: 100 MB.\n- By default the schema's existing data is truncated before import. Pass query param `do_not_truncate_first=TRUE` to append instead.\n- Duplicate source label value combinations in the CSV cause a 400 error.",
-          "href": "/en/api-reference/on-call/alert-enrichment/mapping-data-write-upload",
-          "metadata": {
-            "sidebarTitle": "Upload mapping data via CSV"
-          }
-        }
-      }
-    },
-    "/enrichment/mapping/data/upsert": {
-      "post": {
-        "description": "Insert or update up to 1000 data rows in a mapping schema. Each row must contain all source and result labels.",
-        "operationId": "mapping-data-write-upsert",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/MappingDataUpsertRequest"
+              },
               "example": {
+                "schema_id": "665f1a2b3c4d5e6f7a8b9c01",
                 "docs": [
                   {
                     "host": "server01",
                     "owner": "alice",
-                    "service": "api",
-                    "team": "sre"
+                    "team": "sre",
+                    "service": "api"
                   },
                   {
                     "host": "server02",
                     "owner": "bob",
-                    "service": "gateway",
-                    "team": "platform"
+                    "team": "platform",
+                    "service": "gateway"
                   }
-                ],
-                "schema_id": "665f1a2b3c4d5e6f7a8b9c01"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/MappingDataUpsertRequest"
+                ]
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/enrichment/mapping/schema/create": {
+      "post": {
+        "operationId": "mapping-schema-write-create",
+        "summary": "Create mapping schema",
+        "description": "Create a mapping schema that defines the lookup labels and the result labels to fill.",
+        "tags": [
+          "On-call/Alert enrichment"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Mappings Manage** (`on-call`) |\n\n## Usage\n\n- Requires the Pro plan or higher; otherwise `NoLicense`.\n- `schema_name` must be unique among the account's non-deleted schemas.\n- `source_labels` (1–3) form the lookup key; `result_labels` (1–10) are written to alerts on a match. Label names must match `^[a-zA-Z_][a-zA-Z0-9_]*$`, be unique within each list, and not appear in both lists. Neither list can be changed later.\n- An account holds at most 20 non-deleted mapping schemas by default (some accounts have a higher limit); exceeding it returns `InvalidParameter`.\n- Concurrent create calls in one account return `RequestTooFrequently`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "href": "/en/api-reference/on-call/alert-enrichment/mapping-schema-write-create",
+          "metadata": {
+            "sidebarTitle": "Create mapping schema"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "keys": [
-                      "server01",
-                      "server02"
-                    ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/MappingDataUpsertResponse"
+                          "$ref": "#/components/schemas/MappingSchemaCreateResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "schema_id": "665f1a2b3c4d5e6f7a8b9c01",
+                    "schema_name": "CMDB Lookup"
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -39334,6 +40717,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -39341,74 +40727,71 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Upsert mapping data rows",
-        "tags": [
-          "On-call/Alert enrichment"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Mappings Manage** (`on-call`) |\n\n## Usage\n\n- Each doc must contain values for all labels defined in `source_labels` and `result_labels`.\n- Values for unknown labels are silently dropped.\n- Each value must be at most 2048 characters.\n- Upsert is keyed on the combination of source label values — existing rows with the same source key are updated.\n- A schema can hold at most 10,000 rows by default.\n- The operation is locked per schema; concurrent upserts to the same schema may fail with `ErrRequestTooFrequently`.",
-          "href": "/en/api-reference/on-call/alert-enrichment/mapping-data-write-upsert",
-          "metadata": {
-            "sidebarTitle": "Upsert mapping data rows"
-          }
-        }
-      }
-    },
-    "/enrichment/mapping/schema/create": {
-      "post": {
-        "description": "Create a new mapping schema defining source lookup labels and the result labels to populate. Requires a Pro plan.",
-        "operationId": "mapping-schema-write-create",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/MappingSchemaCreateRequest"
+              },
               "example": {
+                "schema_name": "CMDB Lookup",
                 "description": "Enrich alerts with CMDB data",
+                "source_labels": [
+                  "host"
+                ],
                 "result_labels": [
                   "owner",
                   "team",
                   "service"
-                ],
-                "schema_name": "CMDB Lookup",
-                "source_labels": [
-                  "host"
                 ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/MappingSchemaCreateRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/enrichment/mapping/schema/delete": {
+      "post": {
+        "operationId": "mapping-schema-write-delete",
+        "summary": "Delete mapping schema",
+        "description": "Delete a mapping schema and all of its data rows; refused while an enrichment rule or robot webhook uses it.",
+        "tags": [
+          "On-call/Alert enrichment"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Mappings Manage** (`on-call`) |\n\n## Usage\n\n- The schema is soft-deleted (`status` becomes `deleted`) and all of its data rows are removed permanently.\n- If an integration's enrichment rule, or a Feishu, WeCom or Zoom robot webhook in an escalation rule, references the schema, the call returns HTTP 400 `ReferenceExist` with `data.refs` (each item has `kind` = `integration` or `escalate_rule`, `name`, `href`); at most 20 integrations are listed.\n- An unknown `schema_id` returns `InvalidParameter`.\n- Only an account admin, the schema creator, or a member of the schema's owning team may call this; others get `AccessDenied`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "href": "/en/api-reference/on-call/alert-enrichment/mapping-schema-write-delete",
+          "metadata": {
+            "sidebarTitle": "Delete mapping schema"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "schema_id": "665f1a2b3c4d5e6f7a8b9c01",
-                    "schema_name": "CMDB Lookup"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/MappingSchemaCreateResponse"
+                          "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -39416,6 +40799,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -39423,62 +40809,80 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Create mapping schema",
-        "tags": [
-          "On-call/Alert enrichment"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Mappings Manage** (`on-call`) |\n\n## Usage\n\n- Schema names must be unique within an account.\n- `source_labels` (1–3 labels) are used as lookup keys; `result_labels` (1–10 labels) are the labels written on match.\n- Label names must match `^[a-zA-Z_][a-zA-Z0-9_]*$` and be unique within each list.\n- `source_labels` and `result_labels` must not overlap.\n- An account can have at most 20 mapping schemas.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
-          "href": "/en/api-reference/on-call/alert-enrichment/mapping-schema-write-create",
-          "metadata": {
-            "sidebarTitle": "Create mapping schema"
-          }
-        }
-      }
-    },
-    "/enrichment/mapping/schema/delete": {
-      "post": {
-        "description": "Delete a mapping schema and all its associated data. Deletion is blocked if the schema is referenced by any enrichment rule or webhook.",
-        "operationId": "mapping-schema-write-delete",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {
-                "schema_id": "665f1a2b3c4d5e6f7a8b9c01"
-              },
               "schema": {
                 "$ref": "#/components/schemas/MappingSchemaIDRequest"
+              },
+              "example": {
+                "schema_id": "665f1a2b3c4d5e6f7a8b9c01"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/enrichment/mapping/schema/info": {
+      "post": {
+        "operationId": "mapping-schema-read-info",
+        "summary": "Get mapping schema detail",
+        "description": "Return detail of a single mapping schema by its ID.",
+        "tags": [
+          "On-call/Alert enrichment"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Integrations Read** (`on-call`) or **Integrations Manage** (`on-call`) or **Mappings Read** (`on-call`) or **Mappings Manage** (`on-call`) |\n\n## Usage\n\n- Returns `data: null` when no schema with this ID exists in the account.\n- A soft-deleted schema is still returned, with `status` = `deleted`.",
+          "href": "/en/api-reference/on-call/alert-enrichment/mapping-schema-read-info",
+          "metadata": {
+            "sidebarTitle": "Get mapping schema detail"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/EmptyResponse"
+                          "$ref": "#/components/schemas/MappingSchemaItem"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "schema_id": "665f1a2b3c4d5e6f7a8b9c01",
+                    "schema_name": "CMDB Lookup",
+                    "description": "Enrich alerts with CMDB data",
+                    "source_labels": [
+                      "host"
+                    ],
+                    "result_labels": [
+                      "owner",
+                      "team",
+                      "service"
+                    ],
+                    "status": "enabled",
+                    "team_id": 0,
+                    "creator_id": 80011,
+                    "updated_by": 80011,
+                    "created_at": 1710000000,
+                    "updated_at": 1710000000
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -39486,6 +40890,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -39493,79 +40900,85 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Delete mapping schema",
-        "tags": [
-          "On-call/Alert enrichment"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Mappings Manage** (`on-call`) |\n\n## Usage\n\n- If the schema is still referenced, the response returns HTTP 400 with a `refs` list of blocking references.\n- Only the schema creator, account admin, or team member can delete the schema.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.\n- High-risk operation. Console JWT callers must pass a second-factor code; `app_key` callers bypass the MFA prompt but remain audited — treat the key as a secret.",
-          "href": "/en/api-reference/on-call/alert-enrichment/mapping-schema-write-delete",
-          "metadata": {
-            "sidebarTitle": "Delete mapping schema"
-          }
-        }
-      }
-    },
-    "/enrichment/mapping/schema/info": {
-      "post": {
-        "description": "Return detail of a single mapping schema by its ID.",
-        "operationId": "mapping-schema-read-info",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {
-                "schema_id": "665f1a2b3c4d5e6f7a8b9c01"
-              },
               "schema": {
                 "$ref": "#/components/schemas/MappingSchemaIDRequest"
+              },
+              "example": {
+                "schema_id": "665f1a2b3c4d5e6f7a8b9c01"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/enrichment/mapping/schema/list": {
+      "post": {
+        "operationId": "mapping-schema-read-list",
+        "summary": "List mapping schemas",
+        "description": "Return all mapping schemas of the account, newest first.",
+        "tags": [
+          "On-call/Alert enrichment"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Read** (`on-call`) or **Channels Manage** (`on-call`) or **Integrations Read** (`on-call`) or **Integrations Manage** (`on-call`) or **Mappings Read** (`on-call`) or **Mappings Manage** (`on-call`) |\n\n## Usage\n\n- Returns every non-deleted schema of the account in one response, without pagination; `total` is the number of items.\n- Schemas of all teams are returned; there is no team filter.",
+          "href": "/en/api-reference/on-call/alert-enrichment/mapping-schema-read-list",
+          "metadata": {
+            "sidebarTitle": "List mapping schemas"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "created_at": 1710000000,
-                    "creator_id": 80011,
-                    "description": "Enrich alerts with CMDB data",
-                    "result_labels": [
-                      "owner",
-                      "team",
-                      "service"
-                    ],
-                    "schema_id": "665f1a2b3c4d5e6f7a8b9c01",
-                    "schema_name": "CMDB Lookup",
-                    "source_labels": [
-                      "host"
-                    ],
-                    "status": "enabled",
-                    "team_id": 0,
-                    "updated_at": 1710000000
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/MappingSchemaItem"
+                          "$ref": "#/components/schemas/MappingSchemaListResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "total": 1,
+                    "items": [
+                      {
+                        "schema_id": "665f1a2b3c4d5e6f7a8b9c01",
+                        "schema_name": "CMDB Lookup",
+                        "description": "Enrich alerts with CMDB data",
+                        "source_labels": [
+                          "host"
+                        ],
+                        "result_labels": [
+                          "owner",
+                          "team",
+                          "service"
+                        ],
+                        "status": "enabled",
+                        "team_id": 0,
+                        "creator_id": 80011,
+                        "updated_by": 80011,
+                        "created_at": 1710000000,
+                        "updated_at": 1710000000
+                      }
+                    ]
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -39573,6 +40986,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -39580,82 +40996,60 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Get mapping schema detail",
-        "tags": [
-          "On-call/Alert enrichment"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Integrations Read** (`on-call`) or **Integrations Manage** (`on-call`) or **Mappings Read** (`on-call`) or **Mappings Manage** (`on-call`) |\n\n## Usage\n\n- Returns `null` if the schema does not exist.",
-          "href": "/en/api-reference/on-call/alert-enrichment/mapping-schema-read-info",
-          "metadata": {
-            "sidebarTitle": "Get mapping schema detail"
-          }
-        }
-      }
-    },
-    "/enrichment/mapping/schema/list": {
-      "post": {
-        "description": "Return all mapping schemas for the account, sorted by creation time ascending.",
-        "operationId": "mapping-schema-read-list",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {},
               "schema": {
                 "$ref": "#/components/schemas/EmptyRequest"
-              }
+              },
+              "example": {}
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/enrichment/mapping/schema/update": {
+      "post": {
+        "operationId": "mapping-schema-write-update",
+        "summary": "Update mapping schema",
+        "description": "Update the name, description, or owning team of a mapping schema. Source and result labels cannot be changed after creation.",
+        "tags": [
+          "On-call/Alert enrichment"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Mappings Manage** (`on-call`) |\n\n## Usage\n\n- Fields left out keep their current values; `team_id` `0` removes the team.\n- An unknown `schema_id` returns `InvalidParameter`; a new `schema_name` must not be used by another schema.\n- Only an account admin, the schema creator, or a member of the schema's owning team may call this; others get `AccessDenied`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "href": "/en/api-reference/on-call/alert-enrichment/mapping-schema-write-update",
+          "metadata": {
+            "sidebarTitle": "Update mapping schema"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "items": [
-                      {
-                        "created_at": 1710000000,
-                        "creator_id": 80011,
-                        "description": "Enrich alerts with CMDB data",
-                        "result_labels": [
-                          "owner",
-                          "team",
-                          "service"
-                        ],
-                        "schema_id": "665f1a2b3c4d5e6f7a8b9c01",
-                        "schema_name": "CMDB Lookup",
-                        "source_labels": [
-                          "host"
-                        ],
-                        "status": "enabled",
-                        "team_id": 0,
-                        "updated_at": 1710000000
-                      }
-                    ],
-                    "total": 1
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/MappingSchemaListResponse"
+                          "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -39663,6 +41057,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -39670,64 +41067,64 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "List mapping schemas",
-        "tags": [
-          "On-call/Alert enrichment"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Read** (`on-call`) or **Channels Manage** (`on-call`) or **Integrations Read** (`on-call`) or **Integrations Manage** (`on-call`) or **Mappings Read** (`on-call`) or **Mappings Manage** (`on-call`) |",
-          "href": "/en/api-reference/on-call/alert-enrichment/mapping-schema-read-list",
-          "metadata": {
-            "sidebarTitle": "List mapping schemas"
-          }
-        }
-      }
-    },
-    "/enrichment/mapping/schema/update": {
-      "post": {
-        "description": "Update the name, description, or owning team of a mapping schema. Source and result labels cannot be changed after creation.",
-        "operationId": "mapping-schema-write-update",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {
-                "description": "Updated description",
-                "schema_id": "665f1a2b3c4d5e6f7a8b9c01",
-                "schema_name": "CMDB Lookup v2"
-              },
               "schema": {
                 "$ref": "#/components/schemas/MappingSchemaUpdateRequest"
+              },
+              "example": {
+                "schema_id": "665f1a2b3c4d5e6f7a8b9c01",
+                "schema_name": "CMDB Lookup v2",
+                "description": "Updated description"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/enrichment/upsert": {
+      "post": {
+        "operationId": "enrichment-write-upsert",
+        "summary": "Upsert enrichment rules",
+        "description": "Create or replace the whole enrichment rule set of an integration.",
+        "tags": [
+          "On-call/Alert enrichment"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) or **Integrations Manage** (`on-call`) |\n\n## Usage\n\n- `rules` replaces the stored rule set as a whole; send `[]` to remove all rules.\n- The integration must exist (`InvalidParameter` otherwise) and the caller must be allowed to edit it: an account admin, the integration's creator, someone who can edit its channel (for an integration inside a channel), or a member of its owning team. Integrations with no team and no channel can be edited by any member. Others get `AccessDenied`.\n- Rules run in array order on every incoming alert and change event, and each rule sees the labels written by the rules before it. A rule whose `if` conditions do not all match is skipped; a rule that fails at run time (no regex match, lookup miss, API error) is skipped without affecting the event.\n- Condition keys in `if` must be alert or change event keys (for example `title`, `description`, `labels.<name>`); other keys return `InvalidParameter`.\n- `schema_id` and `api_id` are not checked on save; a rule pointing at a missing or deleted schema or API does nothing at run time. `mapping` rules with `mapping_type` = `api` run for alert events only.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "href": "/en/api-reference/on-call/alert-enrichment/enrichment-write-upsert",
+          "metadata": {
+            "sidebarTitle": "Upsert enrichment rules"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -39735,6 +41132,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -39742,81 +41142,84 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Update mapping schema",
-        "tags": [
-          "On-call/Alert enrichment"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Mappings Manage** (`on-call`) |\n\n## Usage\n\n- Only the schema creator, account admin, or team member can update the schema.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
-          "href": "/en/api-reference/on-call/alert-enrichment/mapping-schema-write-update",
-          "metadata": {
-            "sidebarTitle": "Update mapping schema"
-          }
-        }
-      }
-    },
-    "/enrichment/upsert": {
-      "post": {
-        "description": "Create or fully replace the enrichment rule set for an integration. The entire `rules` array is replaced atomically.",
-        "operationId": "enrichment-write-upsert",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/EnrichmentUpsertRequest"
+              },
               "example": {
                 "integration_id": 5001,
                 "rules": [
                   {
                     "kind": "extraction",
                     "settings": {
-                      "override": true,
-                      "pattern": "(?P<result>prod|staging|dev)",
+                      "source_field": "labels.env",
                       "result_label": "environment",
-                      "source_field": "labels.env"
+                      "pattern": "(?P<result>prod|staging|dev)",
+                      "override": true
                     }
                   },
                   {
                     "kind": "composition",
                     "settings": {
-                      "override": false,
                       "result_label": "full_env",
-                      "template": "{{.Labels.region}}-{{.Labels.environment}}"
+                      "template": "{{.Labels.region}}-{{.Labels.environment}}",
+                      "override": false
                     }
                   }
                 ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/EnrichmentUpsertRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/field/create": {
+      "post": {
+        "operationId": "field-write-create",
+        "summary": "Create field",
+        "description": "Create a new incident custom field on the account.",
+        "tags": [
+          "On-call/Alert enrichment"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Custom Fields Manage** (`on-call`) |\n\n## Usage\n\n- Requires the Standard plan or higher; otherwise `NoLicense`.\n- An account holds at most 15 non-deleted custom fields by default (some accounts have a higher limit); exceeding it returns `InvalidParameter`.\n- `field_name` is 1–39 characters matching `^[a-zA-Z_][a-zA-Z0-9_]*$`, unique, and immutable. The name of a deleted field can be reused only with the same `field_type` and `value_type`. `display_name` must be unique among non-deleted fields.\n- Type rules: `checkbox` requires `value_type=bool` and no `options`; `single_select`/`multi_select` require `value_type=string` and a non-empty list of unique `options`; `text` requires `value_type=string` and no `options`.\n- The response contains only `field_id` and `field_name`; use `/field/info` for the full object.\n- Concurrent create calls in one account return `RequestTooFrequently`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "href": "/en/api-reference/on-call/alert-enrichment/field-write-create",
+          "metadata": {
+            "sidebarTitle": "Create field"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/EmptyResponse"
+                          "$ref": "#/components/schemas/CreateFieldResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "field_id": "66e9d3a4f7c2b04a1c8a91b3",
+                    "field_name": "severity_class"
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -39824,6 +41227,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -39831,187 +41237,117 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Upsert enrichment rules",
-        "tags": [
-          "On-call/Alert enrichment"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Manage** (`on-call`) or **Integrations Manage** (`on-call`) |\n\n## Usage\n\n- Enrichment rules are evaluated in order.\n- Each rule has a `kind`: `extraction` (regex/gjson extraction), `composition` (template-based label composition), `mapping` (lookup via mapping schema or API), or `drop` (remove labels).\n- The optional `if` field is an `AndFilters` condition: if it does not match, the rule is skipped.\n- For `kind: extraction`: `source_field` must be `title`, `description`, or a `labels.*` key; specify exactly one of `pattern` (RE2 regex — its capture groups are joined with a space and written to `result_label`) or `g_json` (GJson path).\n- For `kind: composition`: `template` is a Go text/template rendered against the event struct, e.g. `{{.Title}}`, `{{.Description}}`, `{{.Labels.key}}`.\n- For `kind: mapping`: `mapping_type` is `schema` (default) or `api`; provide `schema_id` or `api_id` accordingly.\n- For `kind: drop`: `drop_labels` lists the label keys to remove.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
-          "href": "/en/api-reference/on-call/alert-enrichment/enrichment-write-upsert",
-          "metadata": {
-            "sidebarTitle": "Upsert enrichment rules"
-          }
-        }
-      }
-    },
-    "/field/create": {
-      "post": {
-        "description": "Create a new incident custom field on the account.",
-        "operationId": "field-write-create",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CreateFieldRequest"
+              },
               "example": {
-                "default_value": "Medium",
-                "description": "Business severity tier.",
-                "display_name": "Severity Class",
                 "field_name": "severity_class",
+                "display_name": "Severity Class",
+                "description": "Business severity tier.",
                 "field_type": "single_select",
+                "value_type": "string",
                 "options": [
                   "Critical",
                   "High",
                   "Medium",
                   "Low"
                 ],
-                "value_type": "string"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/CreateFieldRequest"
+                "default_value": "Medium"
               }
             }
-          },
-          "required": true
-        },
-        "responses": {
-          "200": {
-            "content": {
-              "application/json": {
-                "example": {
-                  "data": {
-                    "field_id": "66e9d3a4f7c2b04a1c8a91b3",
-                    "field_name": "severity_class"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/CreateFieldResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
-                }
-              }
-            },
-            "description": "Success"
-          },
-          "400": {
-            "$ref": "#/components/responses/BadRequest"
-          },
-          "401": {
-            "$ref": "#/components/responses/Unauthorized"
-          },
-          "429": {
-            "$ref": "#/components/responses/TooManyRequests"
-          },
-          "500": {
-            "$ref": "#/components/responses/ServerError"
-          }
-        },
-        "summary": "Create field",
-        "tags": [
-          "On-call/Alert enrichment"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |\n\n## Usage\n\n- Maximum **15** custom fields per account.\n- `field_name` must match `^[a-zA-Z_][a-zA-Z0-9_]{0,39}$` and is immutable after creation; `display_name` must also be unique within the account.\n- Type-specific rules: `checkbox` requires `value_type=bool` and no `options`; `single_select`/`multi_select` require `value_type=string` and a non-empty unique `options` list; `text` requires `value_type=string` and no `options`.\n- Response contains only `field_id` and `field_name`; use `/field/info` to fetch the full object.\n- Audited — changes are recorded in the audit log.",
-          "href": "/en/api-reference/on-call/alert-enrichment/field-write-create",
-          "metadata": {
-            "sidebarTitle": "Create field"
           }
         }
       }
     },
     "/field/delete": {
       "post": {
-        "description": "Delete an incident custom field and asynchronously strip it from existing incidents.",
         "operationId": "field-write-delete",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "field_id": "66e9d3a4f7c2b04a1c8a91b3"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/DeleteFieldRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "Delete field",
+        "description": "Delete an incident custom field and asynchronously strip it from existing incidents.",
+        "tags": [
+          "On-call/Alert enrichment"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Custom Fields Manage** (`on-call`) |\n\n## Usage\n\n- If a custom form references the field, the call returns HTTP 400 `ReferenceExist` with the referencing forms in `data.refs`; remove the references first.\n- The field is marked deleted right away. A background job then removes its value from existing incidents and finally removes the field record.\n- Deleting an already-deleted field succeeds without change; an unknown `field_id` returns `InvalidParameter`.\n- The `field_name` can be reused later only with the same `field_type` and `value_type`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "href": "/en/api-reference/on-call/alert-enrichment/field-write-delete",
+          "metadata": {
+            "sidebarTitle": "Delete field"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "type": "object"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
+            "description": "Invalid request or the field is still referenced by a custom form.",
             "content": {
               "application/json": {
+                "schema": {
+                  "oneOf": [
+                    {
+                      "$ref": "#/components/schemas/ErrorResponse"
+                    },
+                    {
+                      "$ref": "#/components/schemas/FieldDeleteReferenceError"
+                    }
+                  ]
+                },
                 "examples": {
                   "fieldStillReferenced": {
                     "value": {
+                      "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                      "error": {
+                        "code": "ReferenceExist",
+                        "message": "There still are associated resources, deletion is blocked."
+                      },
                       "data": {
                         "refs": [
                           {
-                            "href": "https://console.flashcat.cloud/forms/resolve",
                             "kind": "custom_form",
-                            "name": "Resolve incident"
+                            "name": "Resolve incident",
+                            "href": "https://console.flashcat.cloud/forms/resolve"
                           }
                         ]
-                      },
-                      "error": {
-                        "code": "ReferenceExist",
-                        "message": "There still are associated resources, deletion is blocked."
-                      },
-                      "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
+                      }
                     }
                   }
-                },
-                "schema": {
-                  "oneOf": [
-                    {
-                      "$ref": "#/components/schemas/ErrorResponse"
-                    },
-                    {
-                      "$ref": "#/components/schemas/FieldDeleteReferenceError"
-                    }
-                  ]
                 }
               }
-            },
-            "description": "Invalid request or the field is still referenced by a custom form."
+            }
           },
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -40019,82 +41355,82 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Delete field",
-        "tags": [
-          "On-call/Alert enrichment"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |\n\n## Usage\n\n- The field is marked deleted synchronously; clearing its values from historical incidents runs in the background and may take time on large datasets.\n- Re-creating a field with the same `field_name` is only allowed if `field_type` and `value_type` match the deleted entry.\n- Deletion is rejected with `ReferenceExist` and the referencing custom forms in `data.refs` until no form uses the field.\n- Audited — changes are recorded in the audit log.",
-          "href": "/en/api-reference/on-call/alert-enrichment/field-write-delete",
-          "metadata": {
-            "sidebarTitle": "Delete field"
-          }
-        }
-      }
-    },
-    "/field/info": {
-      "post": {
-        "description": "Return the configuration of a single incident custom field by ID.",
-        "operationId": "field-read-info",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/DeleteFieldRequest"
+              },
               "example": {
                 "field_id": "66e9d3a4f7c2b04a1c8a91b3"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/FieldInfoRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/field/info": {
+      "post": {
+        "operationId": "field-read-info",
+        "summary": "Get field detail",
+        "description": "Return the configuration of a single incident custom field by ID.",
+        "tags": [
+          "On-call/Alert enrichment"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Custom Fields Read** (`on-call`) or **Custom Fields Manage** (`on-call`) |\n\n## Usage\n\n- An unknown `field_id` returns `InvalidParameter`. A deleted field is returned with `status` = `deleted` until the background cleanup started by `/field/delete` finishes; after that its ID is unknown.\n- The shape of `options` and `default_value` depends on `field_type`; see the `FieldItem` schema.",
+          "href": "/en/api-reference/on-call/alert-enrichment/field-read-info",
+          "metadata": {
+            "sidebarTitle": "Get field detail"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/FieldItem"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "account_id": 80001,
-                    "created_at": 1710000000,
-                    "creator_id": 80011,
-                    "default_value": "Medium",
-                    "description": "Business severity tier.",
-                    "display_name": "Severity Class",
                     "field_id": "66e9d3a4f7c2b04a1c8a91b3",
                     "field_name": "severity_class",
+                    "display_name": "Severity Class",
+                    "description": "Business severity tier.",
                     "field_type": "single_select",
+                    "value_type": "string",
                     "options": [
                       "Critical",
                       "High",
                       "Medium",
                       "Low"
                     ],
+                    "default_value": "Medium",
                     "status": "enabled",
-                    "updated_at": 1710000000,
+                    "creator_id": 80011,
                     "updated_by": 80011,
-                    "value_type": "string"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/FieldItem"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                    "created_at": 1710000000,
+                    "updated_at": 1710000000
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -40102,6 +41438,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -40109,88 +41448,86 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Get field detail",
-        "tags": [
-          "On-call/Alert enrichment"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Read** (`on-call`) or **Incidents Manage** (`on-call`) |\n\n## Usage\n\n- An unknown `field_id` yields a 400 error. A soft-deleted field is still returned, with `status` = `deleted` and `deleted_at` set.\n- The shape of `options` and `default_value` varies by `field_type` — see the `FieldItem` schema.",
-          "href": "/en/api-reference/on-call/alert-enrichment/field-read-info",
-          "metadata": {
-            "sidebarTitle": "Get field detail"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/FieldInfoRequest"
+              },
+              "example": {
+                "field_id": "66e9d3a4f7c2b04a1c8a91b3"
+              }
+            }
           }
         }
       }
     },
     "/field/list": {
       "post": {
-        "description": "Return all incident custom fields configured for the account.",
         "operationId": "field-read-list",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "asc": false,
-                "orderby": "updated_at",
-                "query": "severity"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/FieldListRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "List fields",
+        "description": "Return all incident custom fields configured for the account.",
+        "tags": [
+          "On-call/Alert enrichment"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Custom Fields Read** (`on-call`) or **Custom Fields Manage** (`on-call`) or **Channels Read** (`on-call`) or **Channels Manage** (`on-call`) or **Incidents Read** (`on-call`) or **Incidents Manage** (`on-call`) or **Integrations Read** (`on-call`) or **Integrations Manage** (`on-call`) or **Templates Read** (`on-call`) or **Templates Manage** (`on-call`) |\n\n## Usage\n\n- All non-deleted fields are returned in one response, without pagination or `total`. Sorted by `orderby` (default `created_at`), newest first unless `asc` is `true`.\n- `query` is a case-insensitive regular expression on `field_name`; an invalid expression is matched as literal text.",
+          "href": "/en/api-reference/on-call/alert-enrichment/field-read-list",
+          "metadata": {
+            "sidebarTitle": "List fields"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/FieldListResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "items": [
                       {
                         "account_id": 80001,
-                        "created_at": 1710000000,
-                        "creator_id": 80011,
-                        "default_value": "Medium",
-                        "description": "Business severity tier.",
-                        "display_name": "Severity Class",
                         "field_id": "66e9d3a4f7c2b04a1c8a91b3",
                         "field_name": "severity_class",
+                        "display_name": "Severity Class",
+                        "description": "Business severity tier.",
                         "field_type": "single_select",
+                        "value_type": "string",
                         "options": [
                           "Critical",
                           "High",
                           "Medium",
                           "Low"
                         ],
+                        "default_value": "Medium",
                         "status": "enabled",
-                        "updated_at": 1710000000,
+                        "creator_id": 80011,
                         "updated_by": 80011,
-                        "value_type": "string"
+                        "created_at": 1710000000,
+                        "updated_at": 1710000000
                       }
                     ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/FieldListResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -40198,6 +41535,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -40205,71 +41545,64 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "List fields",
-        "tags": [
-          "On-call/Alert enrichment"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Read** (`on-call`) or **Incidents Manage** (`on-call`) |\n\n## Usage\n\n- All non-deleted fields are returned in a single response — there is no pagination and no `total` counter.\n- `query` matches against `field_name` only; invalid regular expressions are auto-escaped to a literal substring match.",
-          "href": "/en/api-reference/on-call/alert-enrichment/field-read-list",
-          "metadata": {
-            "sidebarTitle": "List fields"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/FieldListRequest"
+              },
+              "example": {
+                "orderby": "updated_at",
+                "asc": false,
+                "query": "severity"
+              }
+            }
           }
         }
       }
     },
     "/field/update": {
       "post": {
-        "description": "Update mutable attributes of an existing incident custom field.",
         "operationId": "field-write-update",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "default_value": "Medium",
-                "description": "Business severity tier.",
-                "display_name": "Severity Class",
-                "field_id": "66e9d3a4f7c2b04a1c8a91b3",
-                "options": [
-                  "Critical",
-                  "High",
-                  "Medium",
-                  "Low"
-                ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/UpdateFieldRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "Update field",
+        "description": "Update mutable attributes of an existing incident custom field.",
+        "tags": [
+          "On-call/Alert enrichment"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Custom Fields Manage** (`on-call`) |\n\n## Usage\n\n- `display_name`, `description`, `options` and `default_value` are all overwritten with the request values on every call; a field left out is cleared. Always send the full desired values.\n- `field_name`, `field_type` and `value_type` cannot change; `options` and `default_value` must satisfy the type rules of create.\n- An unknown `field_id` returns `InvalidParameter`; `display_name` must stay unique among non-deleted fields.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "href": "/en/api-reference/on-call/alert-enrichment/field-write-update",
+          "metadata": {
+            "sidebarTitle": "Update field"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "type": "object"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -40277,6 +41610,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -40284,64 +41620,71 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Update field",
-        "tags": [
-          "On-call/Alert enrichment"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |\n\n## Usage\n\n- Only `display_name`, `description`, `options`, and `default_value` can be changed; `field_name`, `field_type`, and `value_type` are immutable.\n- `options` and `default_value` must remain consistent with the field's existing type — same rules as create.\n- Audited — changes are recorded in the audit log.",
-          "href": "/en/api-reference/on-call/alert-enrichment/field-write-update",
-          "metadata": {
-            "sidebarTitle": "Update field"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/UpdateFieldRequest"
+              },
+              "example": {
+                "field_id": "66e9d3a4f7c2b04a1c8a91b3",
+                "display_name": "Severity Class",
+                "description": "Business severity tier.",
+                "options": [
+                  "Critical",
+                  "High",
+                  "Medium",
+                  "Low"
+                ],
+                "default_value": "Medium"
+              }
+            }
           }
         }
       }
     },
     "/incident/ack": {
       "post": {
-        "description": "Acknowledge an incident to indicate you are actively working on it.",
         "operationId": "incidentAck",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "incident_ids": [
-                  "69da451ef77b1b51f40e83ee"
-                ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/AckIncidentRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "Acknowledge incident",
+        "description": "Acknowledge an incident to indicate you are actively working on it.",
+        "tags": [
+          "On-call/Incidents"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Incidents Manage** or **Channels Manage** (`on-call`) |\n\n## Usage\n\n- When an acknowledgement form applies, `custom_fields`, `summary`, and `images` must match its visible elements and required rules.\n- For a batch, form values are accepted only when every selected incident resolves to the same form; otherwise acknowledge incidents individually.\n- The legacy `values` and `custom_values` properties are rejected; use `custom_fields`.\n- The calling member becomes a responder if not already one, and the incident moves to `Processing`. Acknowledging an incident you have already acknowledged changes nothing.\n- A closed incident or an unknown ID fails the whole call with `InvalidParameter`.",
+          "href": "/en/api-reference/on-call/incidents/incident-ack",
+          "metadata": {
+            "sidebarTitle": "Acknowledge incident"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -40349,6 +41692,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -40356,123 +41702,121 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Acknowledge incident",
-        "tags": [
-          "On-call/Incidents"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |\n\n## Usage\n\n- When an acknowledgement form applies, `custom_fields`, `summary`, and `images` must match its visible elements and required rules.\n- For a batch, form values are accepted only when every selected incident resolves to the same form; otherwise acknowledge incidents individually.\n- The legacy `values` and `custom_values` properties are rejected; use `custom_fields`.\n- Audited — changes are recorded in the audit log.",
-          "href": "/en/api-reference/on-call/incidents/incident-ack",
-          "metadata": {
-            "sidebarTitle": "Acknowledge incident"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/AckIncidentRequest"
+              },
+              "example": {
+                "incident_ids": [
+                  "69da451ef77b1b51f40e83ee"
+                ]
+              }
+            }
           }
         }
       }
     },
     "/incident/alert/list": {
       "post": {
-        "description": "List all alerts merged into a specific incident.",
         "operationId": "incidentAlertList",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "incident_id": "69da451ef77b1b51f40e83ee",
-                "include_events": true,
-                "is_active": true,
-                "limit": 100,
-                "p": 1
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ListIncidentAlertsRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "List alerts of incident",
+        "description": "List all alerts merged into a specific incident.",
+        "tags": [
+          "On-call/Incidents"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Read** or **Incidents Manage** or **Channels Read** or **Channels Manage** (`on-call`) |\n\n## Usage\n\n- Set `include_events=true` only when you need a preview of each alert's raw events.\n- Event previews are capped at the 20 newest events per alert. Use `POST /alert/event/list` for a full paginated event history.\n- `event_cnt` still reports the total number of raw events merged into each alert.\n- `p` defaults to 1; `limit` omitted or `0` returns up to 1,000 alerts per page.",
+          "href": "/en/api-reference/on-call/incidents/incident-alert-list",
+          "metadata": {
+            "sidebarTitle": "List alerts of incident"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "items": [
-                      {
-                        "account_id": 2451002751131,
-                        "alert_id": "69da451df77b1b51f40e83de",
-                        "alert_key": "100128:prom-203.0.113.107:A:1579244238440766834:anydata",
-                        "alert_severity": "Critical",
-                        "alert_status": "Critical",
-                        "channel_id": 2551105804131,
-                        "channel_name": "Ops Channel",
-                        "channel_status": "enabled",
-                        "created_at": 1775912221,
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/ListIncidentAlertsResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "total": 1,
+                    "items": [
+                      {
+                        "alert_id": "69da451df77b1b51f40e83de",
+                        "integration_id": 2490562293131,
                         "data_source_id": 2490562293131,
-                        "data_source_name": "FlashMonit",
-                        "data_source_ref_id": "a_2451002751131",
-                        "data_source_type": "monit.alert",
+                        "channel_id": 2551105804131,
+                        "account_id": 2451002751131,
                         "description": "",
+                        "title": "CPU usage high - web-server-01",
+                        "title_rule": "",
+                        "alert_key": "100128:prom-203.0.113.107:A:1579244238440766834:anydata",
+                        "alert_severity": "Critical",
+                        "alert_status": "Critical",
+                        "start_time": 1775912219,
+                        "last_time": 1775969819,
                         "end_time": 0,
+                        "labels": {
+                          "check": "cpu_usage_high",
+                          "resource": "web-server-01"
+                        },
+                        "ever_muted": false,
+                        "created_at": 1775912221,
+                        "updated_at": 1775969821,
+                        "integration_name": "FlashMonit",
+                        "integration_type": "monit.alert",
+                        "integration_ref_id": "a_2451002751131",
+                        "channel_name": "Ops Channel",
+                        "channel_status": "enabled",
+                        "responder_name": "",
+                        "responder_email": "",
+                        "incident": {
+                          "incident_id": "69da451ef77b1b51f40e83ee",
+                          "title": "CPU usage high - web-server-01",
+                          "progress": "Triggered"
+                        },
                         "event_cnt": 17,
+                        "images": null,
+                        "data_source_name": "FlashMonit",
+                        "data_source_type": "monit.alert",
+                        "data_source_ref_id": "a_2451002751131",
                         "events": [
                           {
-                            "alert_id": "69da451df77b1b51f40e83de",
                             "event_id": "69da451df77b1b51f40e83df",
+                            "alert_id": "69da451df77b1b51f40e83de",
+                            "title": "CPU usage > 90%",
                             "event_severity": "Critical",
                             "event_status": "Critical",
                             "event_time": 1712650000,
                             "labels": {
                               "host": "web-01"
-                            },
-                            "title": "CPU usage > 90%"
+                            }
                           }
-                        ],
-                        "ever_muted": false,
-                        "images": null,
-                        "incident": {
-                          "incident_id": "69da451ef77b1b51f40e83ee",
-                          "progress": "Triggered",
-                          "title": "CPU usage high - web-server-01"
-                        },
-                        "integration_id": 2490562293131,
-                        "integration_name": "FlashMonit",
-                        "integration_ref_id": "a_2451002751131",
-                        "integration_type": "monit.alert",
-                        "labels": {
-                          "check": "cpu_usage_high",
-                          "resource": "web-server-01"
-                        },
-                        "last_time": 1775969819,
-                        "responder_email": "",
-                        "responder_name": "",
-                        "start_time": 1775912219,
-                        "title": "CPU usage high - web-server-01",
-                        "title_rule": "",
-                        "updated_at": 1775969821
+                        ]
                       }
-                    ],
-                    "total": 1
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/ListIncidentAlertsResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                    ]
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -40480,6 +41824,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -40487,68 +41834,66 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "List alerts of incident",
-        "tags": [
-          "On-call/Incidents"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Read** (`on-call`) |\n\n## Usage\n\n- Set `include_events=true` only when you need a preview of each alert's raw events.\n- Event previews are capped at the 20 newest events per alert. Use `POST /alert/event/list` for a full paginated event history.\n- `event_cnt` still reports the total number of raw events merged into each alert.",
-          "href": "/en/api-reference/on-call/incidents/incident-alert-list",
-          "metadata": {
-            "sidebarTitle": "List alerts of incident"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ListIncidentAlertsRequest"
+              },
+              "example": {
+                "incident_id": "69da451ef77b1b51f40e83ee",
+                "is_active": true,
+                "limit": 100,
+                "p": 1,
+                "include_events": true
+              }
+            }
           }
         }
       }
     },
     "/incident/assign": {
       "post": {
-        "description": "Dispatch an incident to a specific escalation level or responder.",
         "operationId": "incidentAssign",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "assigned_to": {
-                  "person_ids": [
-                    2476444212131
-                  ],
-                  "type": "assign"
-                },
-                "incident_id": "69da451ef77b1b51f40e83ee"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/AssignIncidentRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "Assign incident",
+        "description": "Reassign incidents to members or an escalation rule, replacing the current responders.",
+        "tags": [
+          "On-call/Incidents"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Incidents Manage** or **Channels Manage** (`on-call`) |\n\n## Usage\n\n- Responders not in the new target are removed; responders who stay keep their acknowledgement. If none of the remaining responders has acknowledged, the incident returns to `Triggered`. Any snooze is cleared.\n- When `assigned_to` sets none of `person_ids`, `escalate_rule_id`, and `emails`, the server re-runs the channel's escalation rule matching instead.\n- Closed incidents are skipped without error.\n- The server fills `assigned_at`, `id`, and `escalate_rule_name`, and derives `type` when it is omitted.",
+          "href": "/en/api-reference/on-call/incidents/incident-assign",
+          "metadata": {
+            "sidebarTitle": "Assign incident"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -40556,6 +41901,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -40563,66 +41911,68 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Assign incident",
-        "tags": [
-          "On-call/Incidents"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |",
-          "href": "/en/api-reference/on-call/incidents/incident-assign",
-          "metadata": {
-            "sidebarTitle": "Assign incident"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/AssignIncidentRequest"
+              },
+              "example": {
+                "incident_id": "69da451ef77b1b51f40e83ee",
+                "assigned_to": {
+                  "person_ids": [
+                    2476444212131
+                  ],
+                  "type": "assign"
+                }
+              }
+            }
           }
         }
       }
     },
     "/incident/comment": {
       "post": {
-        "description": "Add a text comment to the incident timeline.",
         "operationId": "incidentComment",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "comment": "Root cause identified. [@Jane Doe](flashduty://ref/member/2476444212131) please verify the fix.",
-                "comment_type_id": "6a5895d672a064bc2d3ddfc2",
-                "incident_ids": [
-                  "69da451ef77b1b51f40e83ee"
-                ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/CommentIncidentRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "Add comment to incident",
+        "description": "Add a text comment to the incident timeline.",
+        "tags": [
+          "On-call/Incidents"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Incidents Manage** or **Channels Manage** (`on-call`) |\n\n## Usage\n\n- To mention a member, embed a markdown link in `comment` in the form `[@Display Name](flashduty://ref/member/<member_id>)`. Mentioned members receive a dedicated personal notification, which is not affected by `mute_reply`.\n- Plain `@name` text without the link syntax does not create a mention.\n- The server rewrites each mention's display label to the member's canonical name.\n- Returns `RequestTooFrequently` while another resolve, reopen, merge, comment, or delete is running in the same account; retry after a short delay.",
+          "href": "/en/api-reference/on-call/incidents/incident-comment",
+          "metadata": {
+            "sidebarTitle": "Add comment to incident"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -40630,6 +41980,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -40637,76 +41990,79 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Add comment to incident",
-        "tags": [
-          "On-call/Incidents"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |\n\n## Usage\n\n- To mention a member, embed a markdown link in `comment` in the form `[@Display Name](flashduty://ref/member/<member_id>)`. Mentioned members receive a dedicated personal notification, which is not affected by `mute_reply`.\n- Plain `@name` text without the link syntax does not create a mention.\n- The server rewrites each mention's display label to the member's canonical name.",
-          "href": "/en/api-reference/on-call/incidents/incident-comment",
-          "metadata": {
-            "sidebarTitle": "Add comment to incident"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CommentIncidentRequest"
+              },
+              "example": {
+                "incident_ids": [
+                  "69da451ef77b1b51f40e83ee"
+                ],
+                "comment": "Root cause identified. [@Jane Doe](flashduty://ref/member/2476444212131) please verify the fix.",
+                "comment_type_id": "6a5895d672a064bc2d3ddfc2"
+              }
+            }
           }
         }
       }
     },
     "/incident/comment-type/create": {
       "post": {
-        "description": "Create a comment type that can be attached to incident comments.",
         "operationId": "incidentCommentTypeCreate",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "color": "#30A46C",
-                "name": "Key finding"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/CreateIncidentCommentTypeRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "Create a comment type",
+        "description": "Create a comment type that can be attached to incident comments.",
+        "tags": [
+          "On-call/Incidents"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Comment Types Manage** (`on-call`) |\n\n## Usage\n\n- The new type is appended to the end of the display ordering.\n- The name must be unique within the account (case-insensitive, after trimming whitespace).\n- An account can have at most 10 comment types.\n- This permission is admin-only by default; custom roles must be granted it explicitly.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "href": "/en/api-reference/on-call/incidents/incident-comment-type-create",
+          "metadata": {
+            "sidebarTitle": "Create a comment type"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "comment_type_id": "6a5895d672a064bc2d3ddfc2",
-                    "item": {
-                      "account_id": 2451002751131,
-                      "color": "#30A46C",
-                      "comment_type_id": "6a5895d672a064bc2d3ddfc2",
-                      "created_at": 1784190422,
-                      "creator_id": 5068740052131,
-                      "name": "Key finding",
-                      "position": 1,
-                      "updated_at": 1784207748,
-                      "updated_by": 5068740052131
-                    }
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/CreateIncidentCommentTypeResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "comment_type_id": "6a5895d672a064bc2d3ddfc2",
+                    "item": {
+                      "comment_type_id": "6a5895d672a064bc2d3ddfc2",
+                      "account_id": 2451002751131,
+                      "name": "Key finding",
+                      "color": "#30A46C",
+                      "position": 3,
+                      "creator_id": 5068740052131,
+                      "updated_by": 5068740052131,
+                      "created_at": 1784190422,
+                      "updated_at": 1784190422
+                    }
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -40714,6 +42070,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -40721,62 +42080,63 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Create a comment type",
-        "tags": [
-          "On-call/Incidents"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Comment Types Manage** (`on-call`) |\n\n## Usage\n\n- The new type is appended to the end of the display ordering.\n- The name must be unique within the account (case-insensitive, after trimming whitespace).\n- An account can have at most 10 comment types.\n- This permission is admin-only by default; custom roles must be granted it explicitly.",
-          "href": "/en/api-reference/on-call/incidents/incident-comment-type-create",
-          "metadata": {
-            "sidebarTitle": "Create a comment type"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CreateIncidentCommentTypeRequest"
+              },
+              "example": {
+                "name": "Key finding",
+                "color": "#30A46C"
+              }
+            }
           }
         }
       }
     },
     "/incident/comment-type/delete": {
       "post": {
-        "description": "Delete a comment type. Comments that used it keep their text but lose the type label.",
         "operationId": "incidentCommentTypeDelete",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "comment_type_id": "6a5895b572a064bc2d3ddfc0"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/DeleteIncidentCommentTypeRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "Delete a comment type",
+        "description": "Permanently delete a comment type; comments that used it keep their text but lose the label.",
+        "tags": [
+          "On-call/Incidents"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Comment Types Manage** (`on-call`) |\n\n## Usage\n\n- Hard delete — the comment type is removed permanently and cannot be restored.\n- Existing comments that referenced the type lose the type label but are not otherwise affected.\n- This permission is admin-only by default; custom roles must be granted it explicitly.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "href": "/en/api-reference/on-call/incidents/incident-comment-type-delete",
+          "metadata": {
+            "sidebarTitle": "Delete a comment type"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -40784,6 +42144,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -40791,85 +42154,87 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Delete a comment type",
-        "tags": [
-          "On-call/Incidents"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Comment Types Manage** (`on-call`) |\n\n## Usage\n\n- Hard delete — the comment type is removed permanently and cannot be restored.\n- Existing comments that referenced the type lose the type label but are not otherwise affected.\n- This permission is admin-only by default; custom roles must be granted it explicitly.",
-          "href": "/en/api-reference/on-call/incidents/incident-comment-type-delete",
-          "metadata": {
-            "sidebarTitle": "Delete a comment type"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/DeleteIncidentCommentTypeRequest"
+              },
+              "example": {
+                "comment_type_id": "6a5895b572a064bc2d3ddfc0"
+              }
+            }
           }
         }
       }
     },
     "/incident/comment-type/list": {
       "post": {
-        "description": "Retrieve all comment types of the account, ordered by their display position.",
         "operationId": "incidentCommentTypeList",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {},
-              "schema": {
-                "$ref": "#/components/schemas/ListIncidentCommentTypesRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "List comment types",
+        "description": "Retrieve all comment types of the account, ordered by their display position.",
+        "tags": [
+          "On-call/Incidents"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Read** (`on-call`) or **Comment Types Manage** (`on-call`) |\n\n## Usage\n\n- Returns the full list in one call — there is no pagination.\n- An account can have at most 10 comment types.",
+          "href": "/en/api-reference/on-call/incidents/incident-comment-type-list",
+          "metadata": {
+            "sidebarTitle": "List comment types"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/ListIncidentCommentTypesResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "items": [
                       {
-                        "account_id": 2451002751131,
-                        "color": "#30A46C",
                         "comment_type_id": "6a5895d672a064bc2d3ddfc2",
-                        "created_at": 1784190422,
-                        "creator_id": 5068740052131,
+                        "account_id": 2451002751131,
                         "name": "Key finding",
+                        "color": "#30A46C",
                         "position": 1,
-                        "updated_at": 1784207748,
-                        "updated_by": 5068740052131
+                        "creator_id": 5068740052131,
+                        "updated_by": 5068740052131,
+                        "created_at": 1784190422,
+                        "updated_at": 1784207748
                       },
                       {
-                        "account_id": 2451002751131,
-                        "color": "#998000",
                         "comment_type_id": "6a5895b572a064bc2d3ddfc0",
-                        "created_at": 1784190389,
-                        "creator_id": 5068740052131,
+                        "account_id": 2451002751131,
                         "name": "Hypothesis",
+                        "color": "#998000",
                         "position": 2,
-                        "updated_at": 1785141535,
-                        "updated_by": 3790925372131
+                        "creator_id": 5068740052131,
+                        "updated_by": 3790925372131,
+                        "created_at": 1784190389,
+                        "updated_at": 1785141535
                       }
                     ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/ListIncidentCommentTypesResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -40877,6 +42242,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -40884,65 +42252,60 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "List comment types",
-        "tags": [
-          "On-call/Incidents"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Read** (`on-call`) |\n\n## Usage\n\n- Returns the full list in one call — there is no pagination.\n- An account can have at most 10 comment types.",
-          "href": "/en/api-reference/on-call/incidents/incident-comment-type-list",
-          "metadata": {
-            "sidebarTitle": "List comment types"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ListIncidentCommentTypesRequest"
+              },
+              "example": {}
+            }
           }
         }
       }
     },
     "/incident/comment-type/reorder": {
       "post": {
-        "description": "Set the display order of all comment types by passing every type ID in the desired order.",
         "operationId": "incidentCommentTypeReorder",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "comment_type_ids": [
-                  "6a5895b572a064bc2d3ddfc0",
-                  "6a5895d672a064bc2d3ddfc2"
-                ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ReorderIncidentCommentTypesRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "Reorder comment types",
+        "description": "Set the display order of all comment types by passing every type ID in the desired order.",
+        "tags": [
+          "On-call/Incidents"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Comment Types Manage** (`on-call`) |\n\n## Usage\n\n- Full-set reorder — `comment_type_ids` must contain every comment type of the account, each exactly once, in the desired order.\n- Positions are reassigned starting from 1: the first ID in the array becomes position 1.\n- This permission is admin-only by default; custom roles must be granted it explicitly.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "href": "/en/api-reference/on-call/incidents/incident-comment-type-reorder",
+          "metadata": {
+            "sidebarTitle": "Reorder comment types"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -40950,6 +42313,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -40957,63 +42323,65 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Reorder comment types",
-        "tags": [
-          "On-call/Incidents"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Comment Types Manage** (`on-call`) |\n\n## Usage\n\n- Full-set reorder — `comment_type_ids` must contain every comment type of the account, each exactly once, in the desired order.\n- Positions are reassigned starting from 1: the first ID in the array becomes position 1.\n- This permission is admin-only by default; custom roles must be granted it explicitly.",
-          "href": "/en/api-reference/on-call/incidents/incident-comment-type-reorder",
-          "metadata": {
-            "sidebarTitle": "Reorder comment types"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ReorderIncidentCommentTypesRequest"
+              },
+              "example": {
+                "comment_type_ids": [
+                  "6a5895b572a064bc2d3ddfc0",
+                  "6a5895d672a064bc2d3ddfc2"
+                ]
+              }
+            }
           }
         }
       }
     },
     "/incident/comment-type/update": {
       "post": {
-        "description": "Update the name and/or color of an existing account comment type.",
         "operationId": "incidentCommentTypeUpdate",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "color": "#B7791F",
-                "comment_type_id": "6a5895b572a064bc2d3ddfc0"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/UpdateIncidentCommentTypeRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "Update a comment type",
+        "description": "Update the name and/or color of an existing account comment type.",
+        "tags": [
+          "On-call/Incidents"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Comment Types Manage** (`on-call`) |\n\n## Usage\n\n- Partial update — only the provided fields are changed, but at least one of `name` or `color` must be provided.\n- The name must remain unique within the account (case-insensitive, after trimming whitespace).\n- This permission is admin-only by default; custom roles must be granted it explicitly.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "href": "/en/api-reference/on-call/incidents/incident-comment-type-update",
+          "metadata": {
+            "sidebarTitle": "Update a comment type"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -41021,6 +42389,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -41028,99 +42399,66 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Update a comment type",
-        "tags": [
-          "On-call/Incidents"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Comment Types Manage** (`on-call`) |\n\n## Usage\n\n- Partial update — only the provided fields are changed, but at least one of `name` or `color` must be provided.\n- The name must remain unique within the account (case-insensitive, after trimming whitespace).\n- This permission is admin-only by default; custom roles must be granted it explicitly.",
-          "href": "/en/api-reference/on-call/incidents/incident-comment-type-update",
-          "metadata": {
-            "sidebarTitle": "Update a comment type"
-          }
-        }
-      }
-    },
-    "/incident/create": {
-      "post": {
-        "description": "Manually create a new incident and assign responders.",
-        "operationId": "incidentCreate",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {
-                "assigned_to": {
-                  "person_ids": [
-                    2476444212131
-                  ]
-                },
-                "channel_id": 2551105804131,
-                "incident_severity": "Critical",
-                "title": "Database connection timeout on prod-db-01"
-              },
               "schema": {
-                "$ref": "#/components/schemas/CreateIncidentRequest"
-              }
-            },
-            "multipart/form-data": {
-              "encoding": {
-                "data": {
-                  "contentType": "application/json"
-                }
+                "$ref": "#/components/schemas/UpdateIncidentCommentTypeRequest"
               },
-              "schema": {
-                "properties": {
-                  "data": {
-                    "description": "JSON-encoded CreateIncidentRequest payload.",
-                    "type": "string"
-                  },
-                  "images": {
-                    "description": "Image files attached to the new incident.",
-                    "items": {
-                      "format": "binary",
-                      "type": "string"
-                    },
-                    "type": "array"
-                  }
-                },
-                "required": [
-                  "data"
-                ],
-                "type": "object"
+              "example": {
+                "comment_type_id": "6a5895b572a064bc2d3ddfc0",
+                "color": "#B7791F"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/incident/create": {
+      "post": {
+        "operationId": "incidentCreate",
+        "summary": "Create incident",
+        "description": "Manually create a new incident and assign responders.",
+        "tags": [
+          "On-call/Incidents"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) or **Channels Manage** (`on-call`) |\n\n## Usage\n\n- Without an account create form, only `incident_severity` is required.\n- When the account has a create form, `title` (non-blank), `channel_id` and `assigned_to` become required, `fields` may contain only custom fields visible in the form, and the form's required fields must be filled.\n- Images can be attached only when the create form contains an image-upload element (at most 10 images): send `multipart/form-data` with the JSON request in `data` and files in `images`; the whole request must not exceed 50 MiB.\n- Assignment runs after the incident is created. Without `assigned_to`, the channel's escalation rules decide; a standalone incident with no `assigned_to` gets no responders. If assignment fails (for example an out-of-range `layer_idx`), the incident is still created, without responders.",
+          "href": "/en/api-reference/on-call/incidents/incident-create",
+          "metadata": {
+            "sidebarTitle": "Create incident"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "incident_id": "69db2ef1a0fe7db6448b14f1",
-                    "title": "API test incident for docs"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/CreateIncidentResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "incident_id": "69db2ef1a0fe7db6448b14f1",
+                    "title": "API test incident for docs"
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -41128,6 +42466,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -41135,65 +42476,96 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Create incident",
-        "tags": [
-          "On-call/Incidents"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |\n\n## Usage\n\n- When an account create form applies, its visible custom fields and required system values must be supplied.\n- To attach images, send `multipart/form-data` with the JSON request in `data` and files in `images`; the complete request must not exceed 50 MiB.\n- Audited — changes are recorded in the audit log.",
-          "href": "/en/api-reference/on-call/incidents/incident-create",
-          "metadata": {
-            "sidebarTitle": "Create incident"
-          }
-        }
-      }
-    },
-    "/incident/custom-action/do": {
-      "post": {
-        "description": "Execute a custom action configured for an incident.",
-        "operationId": "incidentCustomActionDo",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {
-                "incident_id": "69da451ef77b1b51f40e83ee",
-                "integration_id": 2490562293131
+              "schema": {
+                "$ref": "#/components/schemas/CreateIncidentRequest"
               },
+              "example": {
+                "incident_severity": "Critical",
+                "title": "Database connection timeout on prod-db-01",
+                "channel_id": 2551105804131,
+                "assigned_to": {
+                  "person_ids": [
+                    2476444212131
+                  ]
+                }
+              }
+            },
+            "multipart/form-data": {
               "schema": {
-                "$ref": "#/components/schemas/DoIncidentCustomActionRequest"
+                "type": "object",
+                "required": [
+                  "data"
+                ],
+                "properties": {
+                  "data": {
+                    "type": "string",
+                    "description": "JSON-encoded CreateIncidentRequest payload."
+                  },
+                  "images": {
+                    "type": "array",
+                    "items": {
+                      "type": "string",
+                      "format": "binary"
+                    },
+                    "description": "Image files attached to the new incident."
+                  }
+                }
+              },
+              "encoding": {
+                "data": {
+                  "contentType": "application/json"
+                }
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/incident/custom-action/do": {
+      "post": {
+        "operationId": "incidentCustomActionDo",
+        "summary": "Execute custom action",
+        "description": "Execute a custom action configured for an incident.",
+        "tags": [
+          "On-call/Incidents"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Incidents Manage** or **Channels Manage** (`on-call`) |\n\n## Usage\n\n- The integration must be an enabled custom action integration whose channels include the incident's channel; otherwise the call fails with `InvalidParameter`.\n- The server posts the incident payload to the action's URL with a 2-second timeout. If that request fails, the call still returns HTTP 200 with the error in `data.message`; on success `data` is `null`.\n- A successful run adds an `i_custom` timeline entry.",
+          "href": "/en/api-reference/on-call/incidents/incident-custom-action-do",
+          "metadata": {
+            "sidebarTitle": "Execute custom action"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "message": ""
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/DoIncidentCustomActionResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": null
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -41201,6 +42573,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -41208,64 +42583,63 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Execute custom action",
-        "tags": [
-          "On-call/Incidents"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |",
-          "href": "/en/api-reference/on-call/incidents/incident-custom-action-do",
-          "metadata": {
-            "sidebarTitle": "Execute custom action"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/DoIncidentCustomActionRequest"
+              },
+              "example": {
+                "incident_id": "69da451ef77b1b51f40e83ee",
+                "integration_id": 2490562293131
+              }
+            }
           }
         }
       }
     },
     "/incident/disable-merge": {
       "post": {
-        "description": "Disable automatic merging for a specific incident.",
         "operationId": "incidentDisableMerge",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "incident_ids": [
-                  "69da451ef77b1b51f40e83ee"
-                ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/DisableIncidentMergeRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "Disable incident merge",
+        "description": "Stop new alerts and events from being merged into the given incidents.",
+        "tags": [
+          "On-call/Incidents"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Later events no longer merge into the incidents' existing alerts, and alert grouping no longer adds new alerts to these incidents.\n- IDs that do not match an incident are ignored.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "href": "/en/api-reference/on-call/incidents/incident-disable-merge",
+          "metadata": {
+            "sidebarTitle": "Disable incident merge"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -41273,6 +42647,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -41280,120 +42657,120 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Disable incident merge",
-        "tags": [
-          "On-call/Incidents"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |",
-          "href": "/en/api-reference/on-call/incidents/incident-disable-merge",
-          "metadata": {
-            "sidebarTitle": "Disable incident merge"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/DisableIncidentMergeRequest"
+              },
+              "example": {
+                "incident_ids": [
+                  "69da451ef77b1b51f40e83ee"
+                ]
+              }
+            }
           }
         }
       }
     },
     "/incident/feed": {
       "post": {
-        "description": "Retrieve the timeline feed for a specific incident, including state changes, comments and system events.",
         "operationId": "incidentFeed",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "incident_id": "69da451ef77b1b51f40e83ee",
-                "limit": 20,
-                "p": 1
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ListIncidentFeedRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "Get incident timeline",
+        "description": "List an incident's timeline entries, such as state changes, assignments, notifications, comments, and work item events.",
+        "tags": [
+          "On-call/Incidents"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Read** or **Incidents Manage** or **Channels Read** or **Channels Manage** (`on-call`) |\n\n## Usage\n\n- For `i_comm` entries, `detail.comment_type` is resolved from the current account-level comment type definition at read time, so it reflects the type's latest name and color.\n- Only entries recorded on the incident itself are returned; alert-level entries are read through the alert endpoints.\n- Entries are ordered by creation time, newest first unless `asc` is `true`. Paginate with `p` and `limit`; `has_next_page` tells whether another page exists, and no total count is returned.\n- For `i_notify` entries, `failed_reason` is a localized message describing a delivery failure, filled in at read time.",
+          "href": "/en/api-reference/on-call/incidents/incident-feed",
+          "metadata": {
+            "sidebarTitle": "Get incident timeline"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/ListIncidentFeedResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "has_next_page": true,
                     "items": [
                       {
-                        "account_id": 2451002751131,
-                        "created_at": 1785495329402,
-                        "creator_id": 5329873302131,
+                        "ref_id": "6a5f1e28807515413b384bce",
+                        "type": "i_wi_created",
                         "detail": {
+                          "work_item_id": "wi_68MHnkWBiyjrh6uhkxUyiZ",
+                          "item_type": "follow_up",
+                          "title": "Follow-up: schedule database failover drill",
+                          "status": "open",
                           "assignee_ids": [
                             3790925372131,
                             4756301322131
                           ],
-                          "item_type": "follow_up",
-                          "post_mortem_id": "51d65cd9525c369379ba471b5512df63",
-                          "status": "open",
-                          "title": "Follow-up: schedule database failover drill",
-                          "work_item_id": "wi_68MHnkWBiyjrh6uhkxUyiZ"
+                          "post_mortem_id": "51d65cd9525c369379ba471b5512df63"
                         },
-                        "ref_id": "6a5f1e28807515413b384bce",
-                        "type": "i_wi_created",
+                        "account_id": 2451002751131,
+                        "creator_id": 5329873302131,
+                        "created_at": 1785495329402,
                         "updated_at": 1785495329402
                       },
                       {
-                        "account_id": 2451002751131,
-                        "created_at": 1785496333926,
-                        "creator_id": 3790925372131,
+                        "ref_id": "6a5f1e28807515413b384bce",
+                        "type": "i_comm",
                         "detail": {
                           "comment": "Root cause identified: connection pool exhaustion on the primary database.",
+                          "comment_type_id": "6a5895d672a064bc2d3ddfc2",
                           "comment_type": {
-                            "color": "#30A46C",
                             "id": "6a5895d672a064bc2d3ddfc2",
-                            "name": "Key finding"
-                          },
-                          "comment_type_id": "6a5895d672a064bc2d3ddfc2"
+                            "name": "Key finding",
+                            "color": "#30A46C"
+                          }
                         },
-                        "ref_id": "6a5f1e28807515413b384bce",
-                        "type": "i_comm",
+                        "account_id": 2451002751131,
+                        "creator_id": 3790925372131,
+                        "created_at": 1785496333926,
                         "updated_at": 1785496333926
                       },
                       {
-                        "account_id": 2451002751131,
-                        "created_at": 1785496384806,
-                        "creator_id": 3790925372131,
+                        "ref_id": "6a5f1e28807515413b384bce",
+                        "type": "i_wi_completed",
                         "detail": {
-                          "from_status": "open",
+                          "work_item_id": "wi_68MHnkWBiyjrh6uhkxUyiZ",
                           "item_type": "follow_up",
-                          "post_mortem_id": "51d65cd9525c369379ba471b5512df63",
                           "title": "Follow-up: schedule database failover drill",
+                          "from_status": "open",
                           "to_status": "done",
-                          "work_item_id": "wi_68MHnkWBiyjrh6uhkxUyiZ"
+                          "post_mortem_id": "51d65cd9525c369379ba471b5512df63"
                         },
-                        "ref_id": "6a5f1e28807515413b384bce",
-                        "type": "i_wi_completed",
+                        "account_id": 2451002751131,
+                        "creator_id": 3790925372131,
+                        "created_at": 1785496384806,
                         "updated_at": 1785496384806
                       }
                     ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/ListIncidentFeedResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -41401,6 +42778,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -41408,64 +42788,64 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Get incident timeline",
-        "tags": [
-          "On-call/Incidents"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Read** (`on-call`) |\n\n## Usage\n\n- For `i_comm` entries, `detail.comment_type` is resolved from the current account-level comment type definition at read time, so it reflects the type's latest name and color.",
-          "href": "/en/api-reference/on-call/incidents/incident-feed",
-          "metadata": {
-            "sidebarTitle": "Get incident timeline"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ListIncidentFeedRequest"
+              },
+              "example": {
+                "incident_id": "69da451ef77b1b51f40e83ee",
+                "p": 1,
+                "limit": 20
+              }
+            }
           }
         }
       }
     },
     "/incident/field/reset": {
       "post": {
-        "description": "Update a custom field value on an incident.",
         "operationId": "incidentFieldReset",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "field_name": "affected_service",
-                "field_value": "payment-service",
-                "incident_id": "69da451ef77b1b51f40e83ee"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ResetIncidentFieldRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "Update incident custom field",
+        "description": "Update a custom field value on an incident.",
+        "tags": [
+          "On-call/Incidents"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) or **Channels Manage** (`on-call`) |\n\n## Usage\n\n- The field must exist and be enabled on the account; `field_value` must match its type and options.\n- Omitting `field_value` or sending `null` clears the field on the incident.\n- If the value equals the current one, nothing changes.\n- A change adds a field-change entry to the incident timeline and triggers the same notifications and webhooks as a console edit.",
+          "href": "/en/api-reference/on-call/incidents/incident-field-reset",
+          "metadata": {
+            "sidebarTitle": "Update incident custom field"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -41473,6 +42853,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -41480,140 +42863,143 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Update incident custom field",
-        "tags": [
-          "On-call/Incidents"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |",
-          "href": "/en/api-reference/on-call/incidents/incident-field-reset",
-          "metadata": {
-            "sidebarTitle": "Update incident custom field"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ResetIncidentFieldRequest"
+              },
+              "example": {
+                "incident_id": "69da451ef77b1b51f40e83ee",
+                "field_name": "affected_service",
+                "field_value": "payment-service"
+              }
+            }
           }
         }
       }
     },
     "/incident/info": {
       "post": {
-        "description": "Retrieve detailed information for a single incident including timeline, alerts, responders and custom fields.",
         "operationId": "incidentInfo",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "incident_id": "69da451ef77b1b51f40e83ee"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/IncidentInfoRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "Get incident detail",
+        "description": "Get one incident by ID or short number, with responders, assignment, custom fields, and alert counts.",
+        "tags": [
+          "On-call/Incidents"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Read** or **Incidents Manage** or **Channels Read** or **Channels Manage** (`on-call`) |\n\n## Usage\n\n- `num` is not unique; when several incidents share it, the most recent one is returned. Prefer `incident_id`.\n- This endpoint does not fill `alerts` or the `account_*` fields. Use `POST /incident/alert/list` for alerts and `POST /incident/feed` for the timeline.\n- Image tokens starting with `img_` in `images` are replaced with download URLs.\n- An unknown incident returns `InvalidParameter`.",
+          "href": "/en/api-reference/on-call/incidents/incident-info",
+          "metadata": {
+            "sidebarTitle": "Get incident detail"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/IncidentInfo"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
+                    "incident_id": "69da451ef77b1b51f40e83ee",
                     "account_id": 2451002751131,
-                    "account_locale": "",
-                    "account_name": "",
-                    "account_time_zone": "",
-                    "ack_time": 0,
-                    "active_alert_cnt": 1,
-                    "ai_summary": "",
-                    "alert_cnt": 1,
-                    "alert_event_cnt": 17,
-                    "assigned_to": {
-                      "assigned_at": 1775972128,
-                      "escalate_rule_id": "000000000000000000000000",
-                      "escalate_rule_name": "",
-                      "id": "MvQfH9Dc8eNS8k79jmrWn6",
-                      "layer_idx": 0,
-                      "person_ids": [
-                        2476444212131
-                      ],
-                      "type": "assign"
-                    },
                     "channel_id": 2551105804131,
-                    "channel_name": "Ops Channel",
-                    "channel_status": "enabled",
-                    "close_time": 0,
-                    "closer_id": 0,
-                    "created_at": 1775912222,
-                    "creator_id": 0,
-                    "dedup_key": "100128:prom-203.0.113.107:A:1579244238440766834:anydata",
-                    "description": "",
-                    "detail_url": "https://app.flashcat.cloud/incident/detail/69da451ef77b1b51f40e83ee",
-                    "end_time": 0,
-                    "equals_md5": "",
-                    "ever_muted": false,
-                    "fields": {},
-                    "frequency": "frequent",
-                    "group_method": "n",
-                    "images": null,
-                    "impact": "",
-                    "incident_id": "69da451ef77b1b51f40e83ee",
-                    "incident_severity": "Critical",
-                    "incident_status": "Critical",
+                    "team_id": 2477033058131,
                     "integration_id": 2490562293131,
                     "integration_ids": [
                       2490562293131
                     ],
-                    "integration_type": "monit.alert",
                     "integration_types": [
                       "monit.alert"
                     ],
-                    "labels": {
-                      "check": "cpu_usage_high",
-                      "env": "production",
-                      "resource": "web-server-01"
-                    },
+                    "dedup_key": "100128:prom-203.0.113.107:A:1579244238440766834:anydata",
+                    "equals_md5": "",
+                    "start_time": 1775912219,
+                    "end_time": 0,
                     "last_time": 1775969819,
-                    "manual_overrides": [
-                      "title"
-                    ],
-                    "num": "0E83EE",
+                    "ack_time": 0,
+                    "close_time": 0,
+                    "creator_id": 0,
+                    "closer_id": 0,
                     "owner_id": 0,
-                    "post_mortem_id": "",
+                    "incident_status": "Critical",
+                    "incident_severity": "Critical",
                     "progress": "Triggered",
+                    "title": "CPU usage high - web-server-01",
+                    "description": "",
+                    "ai_summary": "",
+                    "impact": "",
+                    "root_cause": "",
                     "resolution": "",
+                    "num": "0E83EE",
+                    "frequency": "frequent",
+                    "created_at": 1775912222,
+                    "updated_at": 1775972145,
+                    "snoozed_before": 0,
+                    "group_method": "n",
+                    "ever_muted": false,
+                    "has_unfinished_work_item": false,
+                    "labels": {
+                      "check": "cpu_usage_high",
+                      "resource": "web-server-01",
+                      "env": "production"
+                    },
+                    "fields": {},
+                    "assigned_to": {
+                      "person_ids": [
+                        2476444212131
+                      ],
+                      "escalate_rule_id": "000000000000000000000000",
+                      "layer_idx": 0,
+                      "type": "assign",
+                      "assigned_at": 1775972128,
+                      "id": "MvQfH9Dc8eNS8k79jmrWn6",
+                      "escalate_rule_name": ""
+                    },
+                    "alert_cnt": 1,
+                    "active_alert_cnt": 1,
+                    "alert_event_cnt": 17,
                     "responders": [
                       {
-                        "acknowledged_at": 0,
+                        "person_id": 2476444212131,
                         "assigned_at": 1775972128,
-                        "person_id": 2476444212131
+                        "acknowledged_at": 0
                       }
                     ],
-                    "root_cause": "",
+                    "account_name": "",
+                    "account_locale": "",
+                    "account_time_zone": "",
+                    "channel_name": "Ops Channel",
+                    "channel_status": "enabled",
+                    "detail_url": "https://app.flashcat.cloud/incident/detail/69da451ef77b1b51f40e83ee",
                     "silence_url": "https://app.flashcat.cloud/channel/detail/2551105804131?tab=alertSuppression&fromIncidentId=69da451ef77b1b51f40e83ee",
-                    "snoozed_before": 0,
-                    "start_time": 1775912219,
-                    "team_id": 2477033058131,
-                    "title": "CPU usage high - web-server-01",
-                    "updated_at": 1775972145
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/IncidentInfo"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                    "integration_type": "monit.alert",
+                    "post_mortem_id": "",
+                    "images": null,
+                    "manual_overrides": [
+                      "title"
+                    ]
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -41621,6 +43007,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -41628,155 +43017,148 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Get incident detail",
-        "tags": [
-          "On-call/Incidents"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Read** (`on-call`) |",
-          "href": "/en/api-reference/on-call/incidents/incident-info",
-          "metadata": {
-            "sidebarTitle": "Get incident detail"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/IncidentInfoRequest"
+              },
+              "example": {
+                "incident_id": "69da451ef77b1b51f40e83ee"
+              }
+            }
           }
         }
       }
     },
     "/incident/list": {
       "post": {
-        "description": "Query a paginated list of incidents with filters by channel, severity, status, responder, and time range.",
         "operationId": "incidentList",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "channel_ids": [
-                  2551105804131
-                ],
-                "end_time": 1712000000,
-                "incident_severity": "Critical,Warning",
-                "limit": 20,
-                "p": 1,
-                "progress": "Triggered,Processing",
-                "start_time": 1711900800
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ListIncidentsRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "List incidents",
+        "description": "Query a paginated list of incidents with filters by channel, severity, status, responder, and time range.",
+        "tags": [
+          "On-call/Incidents"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Read** or **Incidents Manage** or **Channels Read** or **Channels Manage** or **Templates Read** or **Templates Manage** (`on-call`) |\n\n## Usage\n\n- Only incidents in channels the caller can access are returned.\n- `start_time` and `end_time` filter on incident start time and may span at most 31 days. A `start_time` earlier than the account's data retention period is moved up to the retention boundary; an `end_time` before that boundary fails with `InvalidParameter`.\n- Results are sorted by `start_time`, newest first unless `asc` is `true`.\n- Paginate with `p` and `limit`, or pass the previous response's `search_after_ctx`, in which case `p` is ignored.\n- `total` is capped at 1,000. With `p`/`limit` paging, `has_next_page` turns `false` once `p` × `limit` reaches 1,000 even if more incidents match. To read further, pass the `search_after_ctx` returned with every non-empty page; in cursor mode `has_next_page` reflects whether more rows really exist.\n- Without `progress`, incidents in every progress state are returned.",
+          "href": "/en/api-reference/on-call/incidents/incident-list",
+          "metadata": {
+            "sidebarTitle": "List incidents"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/IncidentListResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
+                    "total": 88,
                     "has_next_page": true,
+                    "search_after_ctx": "69da451ef77b1b51f40e83eb",
                     "items": [
                       {
+                        "incident_id": "69da451ef77b1b51f40e83ee",
                         "account_id": 2451002751131,
-                        "account_locale": "",
-                        "account_name": "",
-                        "account_time_zone": "",
-                        "ack_time": 0,
-                        "active_alert_cnt": 1,
-                        "ai_summary": "",
-                        "alert_cnt": 1,
-                        "alert_event_cnt": 17,
-                        "assigned_to": {
-                          "assigned_at": 1775972128,
-                          "escalate_rule_id": "000000000000000000000000",
-                          "escalate_rule_name": "",
-                          "id": "MvQfH9Dc8eNS8k79jmrWn6",
-                          "layer_idx": 0,
-                          "person_ids": [
-                            2476444212131
-                          ],
-                          "type": "assign"
-                        },
                         "channel_id": 2551105804131,
-                        "channel_name": "Ops Channel",
-                        "channel_status": "enabled",
-                        "close_time": 0,
-                        "closer_id": 0,
-                        "created_at": 1775912222,
-                        "creator_id": 0,
-                        "dedup_key": "100128:prom-203.0.113.107:A:1579244238440766834:anydata",
-                        "description": "",
-                        "detail_url": "https://app.flashcat.cloud/incident/detail/69da451ef77b1b51f40e83ee",
-                        "end_time": 0,
-                        "equals_md5": "",
-                        "ever_muted": false,
-                        "fields": {},
-                        "frequency": "frequent",
-                        "group_method": "n",
-                        "images": null,
-                        "impact": "",
-                        "incident_id": "69da451ef77b1b51f40e83ee",
-                        "incident_severity": "Critical",
-                        "incident_status": "Critical",
+                        "team_id": 2477033058131,
                         "integration_id": 2490562293131,
                         "integration_ids": [
                           2490562293131
                         ],
-                        "integration_type": "monit.alert",
                         "integration_types": [
                           "monit.alert"
                         ],
-                        "labels": {
-                          "check": "cpu_usage_high",
-                          "env": "production",
-                          "resource": "web-server-01"
-                        },
+                        "dedup_key": "100128:prom-203.0.113.107:A:1579244238440766834:anydata",
+                        "equals_md5": "",
+                        "start_time": 1775912219,
+                        "end_time": 0,
                         "last_time": 1775969819,
-                        "manual_overrides": [
-                          "title"
-                        ],
-                        "num": "0E83EE",
+                        "ack_time": 0,
+                        "close_time": 0,
+                        "creator_id": 0,
+                        "closer_id": 0,
                         "owner_id": 0,
-                        "post_mortem_id": "",
+                        "incident_status": "Critical",
+                        "incident_severity": "Critical",
                         "progress": "Triggered",
+                        "title": "CPU usage high - web-server-01",
+                        "description": "",
+                        "ai_summary": "",
+                        "impact": "",
+                        "root_cause": "",
                         "resolution": "",
+                        "num": "0E83EE",
+                        "frequency": "frequent",
+                        "created_at": 1775912222,
+                        "updated_at": 1775972145,
+                        "snoozed_before": 0,
+                        "group_method": "n",
+                        "ever_muted": false,
+                        "has_unfinished_work_item": false,
+                        "labels": {
+                          "check": "cpu_usage_high",
+                          "resource": "web-server-01",
+                          "env": "production"
+                        },
+                        "fields": {},
+                        "assigned_to": {
+                          "person_ids": [
+                            2476444212131
+                          ],
+                          "escalate_rule_id": "000000000000000000000000",
+                          "layer_idx": 0,
+                          "type": "assign",
+                          "assigned_at": 1775972128,
+                          "id": "MvQfH9Dc8eNS8k79jmrWn6",
+                          "escalate_rule_name": ""
+                        },
+                        "alert_cnt": 1,
+                        "active_alert_cnt": 1,
+                        "alert_event_cnt": 17,
                         "responders": [
                           {
-                            "acknowledged_at": 0,
+                            "person_id": 2476444212131,
                             "assigned_at": 1775972128,
-                            "person_id": 2476444212131
+                            "acknowledged_at": 0
                           }
                         ],
-                        "root_cause": "",
+                        "account_name": "",
+                        "account_locale": "",
+                        "account_time_zone": "",
+                        "channel_name": "Ops Channel",
+                        "channel_status": "enabled",
+                        "detail_url": "https://app.flashcat.cloud/incident/detail/69da451ef77b1b51f40e83ee",
                         "silence_url": "https://app.flashcat.cloud/channel/detail/2551105804131?tab=alertSuppression&fromIncidentId=69da451ef77b1b51f40e83ee",
-                        "snoozed_before": 0,
-                        "start_time": 1775912219,
-                        "team_id": 2477033058131,
-                        "title": "CPU usage high - web-server-01",
-                        "updated_at": 1775972145
+                        "integration_type": "monit.alert",
+                        "post_mortem_id": "",
+                        "images": null,
+                        "manual_overrides": [
+                          "title"
+                        ]
                       }
-                    ],
-                    "search_after_ctx": "69da451ef77b1b51f40e83eb",
-                    "total": 88
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/IncidentListResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                    ]
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -41784,6 +43166,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -41791,134 +43176,140 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "List incidents",
-        "tags": [
-          "On-call/Incidents"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Read** (`on-call`) |",
-          "href": "/en/api-reference/on-call/incidents/incident-list",
-          "metadata": {
-            "sidebarTitle": "List incidents"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ListIncidentsRequest"
+              },
+              "example": {
+                "start_time": 1711900800,
+                "end_time": 1712000000,
+                "progress": "Triggered,Processing",
+                "incident_severity": "Critical,Warning",
+                "channel_ids": [
+                  2551105804131
+                ],
+                "limit": 20,
+                "p": 1
+              }
+            }
           }
         }
       }
     },
     "/incident/list-by-ids": {
       "post": {
-        "description": "Retrieve multiple incidents by their IDs in a single request.",
         "operationId": "incidentListByIds",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "incident_ids": [
-                  "69da451ef77b1b51f40e83ee",
-                  "69da451ef77b1b51f40e83ef"
-                ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ListIncidentsByIdsRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "List incidents by IDs",
+        "description": "Retrieve multiple incidents by their IDs in a single request.",
+        "tags": [
+          "On-call/Incidents"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Read** or **Incidents Manage** or **Channels Read** (`on-call`) |\n\n## Usage\n\n- IDs that do not match an incident are omitted; `total` is the number of incidents found and `has_next_page` is always `false`.\n- Results are sorted by `start_time`, newest first.\n- This endpoint does not fill `integration_type` or `assigned_to.escalate_rule_name`.",
+          "href": "/en/api-reference/on-call/incidents/incident-list-by-ids",
+          "metadata": {
+            "sidebarTitle": "List incidents by IDs"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "has_next_page": false,
-                    "items": [
-                      {
-                        "account_id": 2451002751131,
-                        "account_locale": "",
-                        "account_name": "",
-                        "account_time_zone": "",
-                        "ack_time": 0,
-                        "active_alert_cnt": 1,
-                        "ai_summary": "",
-                        "alert_cnt": 1,
-                        "alert_event_cnt": 17,
-                        "assigned_to": {
-                          "assigned_at": 0,
-                          "escalate_rule_id": "000000000000000000000000",
-                          "escalate_rule_name": "",
-                          "id": "",
-                          "layer_idx": 0,
-                          "type": ""
-                        },
-                        "channel_id": 2551105804131,
-                        "channel_name": "Ops Channel",
-                        "channel_status": "enabled",
-                        "close_time": 0,
-                        "closer_id": 0,
-                        "created_at": 1775912222,
-                        "creator_id": 0,
-                        "dedup_key": "100128:prom-203.0.113.107:A:1579244238440766834:anydata",
-                        "description": "",
-                        "detail_url": "https://app.flashcat.cloud/incident/detail/69da451ef77b1b51f40e83ee",
-                        "end_time": 0,
-                        "equals_md5": "",
-                        "ever_muted": false,
-                        "fields": {},
-                        "frequency": "frequent",
-                        "group_method": "n",
-                        "images": null,
-                        "impact": "",
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/IncidentListResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "total": 1,
+                    "has_next_page": false,
+                    "items": [
+                      {
                         "incident_id": "69da451ef77b1b51f40e83ee",
-                        "incident_severity": "Critical",
-                        "incident_status": "Critical",
+                        "account_id": 2451002751131,
+                        "channel_id": 2551105804131,
+                        "team_id": 2477033058131,
                         "integration_id": 2490562293131,
                         "integration_ids": [
                           2490562293131
                         ],
-                        "integration_type": "monit.alert",
                         "integration_types": [
                           "monit.alert"
                         ],
-                        "labels": {},
+                        "dedup_key": "100128:prom-203.0.113.107:A:1579244238440766834:anydata",
+                        "equals_md5": "",
+                        "start_time": 1775912219,
+                        "end_time": 0,
                         "last_time": 1775969819,
-                        "manual_overrides": null,
-                        "num": "0E83EE",
+                        "ack_time": 0,
+                        "close_time": 0,
+                        "creator_id": 0,
+                        "closer_id": 0,
                         "owner_id": 0,
-                        "post_mortem_id": "",
+                        "incident_status": "Critical",
+                        "incident_severity": "Critical",
                         "progress": "Triggered",
+                        "title": "CPU usage high - web-server-01",
+                        "description": "",
+                        "ai_summary": "",
+                        "impact": "",
+                        "root_cause": "",
                         "resolution": "",
+                        "num": "0E83EE",
+                        "frequency": "frequent",
+                        "created_at": 1775912222,
+                        "updated_at": 1775972145,
+                        "snoozed_before": 0,
+                        "group_method": "n",
+                        "ever_muted": false,
+                        "has_unfinished_work_item": false,
+                        "labels": {},
+                        "fields": {},
+                        "assigned_to": {
+                          "escalate_rule_id": "000000000000000000000000",
+                          "layer_idx": 0,
+                          "type": "",
+                          "assigned_at": 0,
+                          "id": "",
+                          "escalate_rule_name": ""
+                        },
+                        "alert_cnt": 1,
+                        "active_alert_cnt": 1,
+                        "alert_event_cnt": 17,
                         "responders": [],
-                        "root_cause": "",
+                        "account_name": "",
+                        "account_locale": "",
+                        "account_time_zone": "",
+                        "channel_name": "Ops Channel",
+                        "channel_status": "enabled",
+                        "detail_url": "https://app.flashcat.cloud/incident/detail/69da451ef77b1b51f40e83ee",
                         "silence_url": "https://app.flashcat.cloud/channel/detail/2551105804131?tab=alertSuppression&fromIncidentId=69da451ef77b1b51f40e83ee",
-                        "snoozed_before": 0,
-                        "start_time": 1775912219,
-                        "team_id": 2477033058131,
-                        "title": "CPU usage high - web-server-01",
-                        "updated_at": 1775972145
+                        "integration_type": "monit.alert",
+                        "post_mortem_id": "",
+                        "images": null,
+                        "manual_overrides": null
                       }
-                    ],
-                    "total": 2
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/IncidentListResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                    ]
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -41926,6 +43317,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -41933,67 +43327,65 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "List incidents by IDs",
-        "tags": [
-          "On-call/Incidents"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Read** (`on-call`) |",
-          "href": "/en/api-reference/on-call/incidents/incident-list-by-ids",
-          "metadata": {
-            "sidebarTitle": "List incidents by IDs"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ListIncidentsByIdsRequest"
+              },
+              "example": {
+                "incident_ids": [
+                  "69da451ef77b1b51f40e83ee",
+                  "69da451ef77b1b51f40e83ef"
+                ]
+              }
+            }
           }
         }
       }
     },
     "/incident/merge": {
       "post": {
-        "description": "Merge one or more incidents into a target incident.",
         "operationId": "incidentMerge",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "comment": "Merging related database connectivity incidents into one.",
-                "source_incident_ids": [
-                  "69da451ef77b1b51f40e83ef",
-                  "69da451ef77b1b51f40e83f0"
-                ],
-                "target_incident_id": "69da451ef77b1b51f40e83ee"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/MergeIncidentsRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "Merge incidents",
+        "description": "Merge one or more incidents into a target incident.",
+        "tags": [
+          "On-call/Incidents"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Incidents Manage** or **Channels Manage** (`on-call`) |\n\n## Usage\n\n- All alerts of the source incidents move to the target incident, and the target gains the sources' integrations.\n- Source incidents that are still open are closed. With `remove_source_incidents: true` they are then permanently deleted; otherwise they stay closed with an `i_merge` timeline entry that points to the target.\n- The target's progress, responders, and assignment do not change; `title`, when set, replaces the target's title.\n- Returns `RequestTooFrequently` while another resolve, reopen, merge, comment, or delete is running in the same account; retry after a short delay.",
+          "href": "/en/api-reference/on-call/incidents/incident-merge",
+          "metadata": {
+            "sidebarTitle": "Merge incidents"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -42001,6 +43393,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -42008,65 +43403,69 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Merge incidents",
-        "tags": [
-          "On-call/Incidents"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |",
-          "href": "/en/api-reference/on-call/incidents/incident-merge",
-          "metadata": {
-            "sidebarTitle": "Merge incidents"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/MergeIncidentsRequest"
+              },
+              "example": {
+                "source_incident_ids": [
+                  "69da451ef77b1b51f40e83ef",
+                  "69da451ef77b1b51f40e83f0"
+                ],
+                "target_incident_id": "69da451ef77b1b51f40e83ee",
+                "comment": "Merging related database connectivity incidents into one."
+              }
+            }
           }
         }
       }
     },
     "/incident/past/list": {
       "post": {
-        "description": "List historical incidents related to the current incident for reference during triage.",
         "operationId": "incidentPastList",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "incident_id": "69da451ef77b1b51f40e83ee",
-                "limit": 5
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ListPastIncidentsRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "List past incidents",
+        "description": "List closed incidents in the same channel that resemble a given incident, to reuse past root causes and resolutions.",
+        "tags": [
+          "On-call/Incidents"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **100 requests/minute**; **5 requests/second** per account |\n| Permissions | **Incidents Read** or **Incidents Manage** or **Channels Read** or **Channels Manage** (`on-call`) |\n\n## Usage\n\n- Requires the Professional edition or higher; otherwise the call fails with `NoLicense`.\n- Candidates are closed incidents in the same channel that started within the 30 days before the reference incident started and whose semantic similarity exceeds the channel's similarity threshold.\n- Results list incidents with longer `root_cause` plus `resolution` text first, then higher `score`, then more recent `start_time`.\n- `limit` defaults to 5 when omitted or `0`.\n- An empty `items` array means no similar incident was found, or the reference incident has not been indexed for similarity search yet.\n- The reference incident must belong to a channel; otherwise the call fails with `InvalidParameter`.",
+          "href": "/en/api-reference/on-call/incidents/incident-past-list",
+          "metadata": {
+            "sidebarTitle": "List past incidents"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "items": []
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/ListPastIncidentsResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "items": []
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -42074,6 +43473,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -42081,69 +43483,62 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "List past incidents",
-        "tags": [
-          "On-call/Incidents"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **100 requests/minute**; **20 requests/second** per account |\n| Permissions | **Incidents Read** (`on-call`) |",
-          "href": "/en/api-reference/on-call/incidents/incident-past-list",
-          "metadata": {
-            "sidebarTitle": "List past incidents"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ListPastIncidentsRequest"
+              },
+              "example": {
+                "incident_id": "69da451ef77b1b51f40e83ee",
+                "limit": 5
+              }
+            }
           }
         }
       }
     },
     "/incident/post-mortem/basics/reset": {
       "post": {
-        "description": "Replace the incident facts stored in a post-mortem report.",
         "operationId": "postmortem-write-reset-basics",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "incidents_earliest_start_seconds": 1761133512,
-                "incidents_highest_severity": "Warning",
-                "incidents_latest_close_seconds": 1761133632,
-                "incidents_total_duration_seconds": 120,
-                "post_mortem_id": "8104935102bf89dc01ac638a5261fe7e",
-                "responder_ids": [
-                  3790925372131
-                ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ResetPostMortemBasicsRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "Update post-mortem basics",
+        "description": "Overwrite the incident facts (severity, times, responders) stored on a post-mortem report.",
+        "tags": [
+          "On-call/Incidents"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Requires the On-call Pro license.\n- The caller must be an account owner or admin, or a member of the report's team; otherwise the call returns `AccessDenied`.\n- Full overwrite: omitted `incidents_latest_close_seconds` and `incidents_total_duration_seconds` become 0, and omitted `responder_ids` clears the responders.\n- IDs in `responder_ids` that do not resolve to a person are dropped; each stored responder gets the current time as `assigned_at` and `acknowledged_at` = 0.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "href": "/en/api-reference/on-call/incidents/postmortem-write-reset-basics",
+          "metadata": {
+            "sidebarTitle": "Update post-mortem basics"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -42151,6 +43546,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -42158,73 +43556,77 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Update post-mortem basics",
-        "tags": [
-          "On-call/Incidents"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |\n\n## Usage\n\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
-          "href": "/en/api-reference/on-call/incidents/postmortem-write-reset-basics",
-          "metadata": {
-            "sidebarTitle": "Update post-mortem basics"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ResetPostMortemBasicsRequest"
+              },
+              "example": {
+                "post_mortem_id": "d3c9a7f2e5b14c8a9f0e6b2d4a1c7e35",
+                "incidents_highest_severity": "Critical",
+                "incidents_earliest_start_seconds": 1773890000,
+                "incidents_latest_close_seconds": 1773897200,
+                "incidents_total_duration_seconds": 7200,
+                "responder_ids": [
+                  3790925372131
+                ]
+              }
+            }
           }
         }
       }
     },
     "/incident/post-mortem/content/reset": {
       "post": {
-        "description": "Replace the body of a drafting post-mortem report with Markdown.",
         "operationId": "incident-post-mortem-write-reset-content",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "expected_revision": 11,
-                "idempotency_key": "postmortem-reset-8104935102-11",
-                "markdown": "# Database saturation incident\n\nThe database pool was exhausted; added saturation alert.",
-                "post_mortem_id": "8104935102bf89dc01ac638a5261fe7e"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ResetPostMortemContentRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "Reset post-mortem content",
+        "description": "Replace the body of a drafting post-mortem report with Markdown.",
+        "tags": [
+          "On-call/Incidents"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Requires the On-call Pro license.\n- The caller must be an account owner or admin, or a member of the report's team; otherwise the call returns `AccessDenied`.\n- The report must be drafting and its current revision must equal `expected_revision`; otherwise the API returns `409 Conflict`.\n- Reuse an `idempotency_key` only for the same report, revision, and Markdown content; different reuse returns `409 Conflict`.\n- While another reset of the same report is still running, the call returns `RequestTooFrequently`; retry later.\n- A successful reset disconnects the previous collaboration (Yjs) room. Reconnect to the new generation room `post-mortem-{accountId}-{postMortemId}-g{N}` (generation 0 has no `-g` suffix). The reset cannot be rolled back.\n- Markdown content is limited to 4 MiB.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "href": "/en/api-reference/on-call/incidents/incident-post-mortem-write-reset-content",
+          "metadata": {
+            "sidebarTitle": "Reset post-mortem content"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "generation": 2,
-                    "markdown_bytes": 88,
-                    "markdown_sha256": "70d764e77e68f8fbfa14d72a235ac07b0110768b8380c8e3436459ebaf02a7c0",
-                    "post_mortem_id": "8104935102bf89dc01ac638a5261fe7e",
-                    "previous_generation": 1,
-                    "previous_revision": 11,
-                    "revision": 12
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/PostMortemContentResetResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "post_mortem_id": "d3c9a7f2e5b14c8a9f0e6b2d4a1c7e35",
+                    "generation": 2,
+                    "revision": 12,
+                    "previous_generation": 1,
+                    "previous_revision": 11,
+                    "markdown_bytes": 88,
+                    "markdown_sha256": "70d764e77e68f8fbfa14d72a235ac07b0110768b8380c8e3436459ebaf02a7c0"
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -42236,136 +43638,66 @@
             "$ref": "#/components/responses/Forbidden"
           },
           "409": {
+            "description": "The report is not drafting, the revision is stale, or the idempotency key was reused for a different request.",
             "content": {
               "application/json": {
-                "example": {
-                  "error": {
-                    "code": "Conflict",
-                    "message": "expected_revision conflict: request has 11 but current revision is 12"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
+                  "type": "object",
+                  "required": [
+                    "request_id",
+                    "error"
+                  ],
                   "properties": {
+                    "request_id": {
+                      "type": "string"
+                    },
                     "error": {
+                      "type": "object",
+                      "required": [
+                        "code",
+                        "message"
+                      ],
                       "properties": {
                         "code": {
+                          "type": "string",
                           "enum": [
                             "Conflict"
-                          ],
-                          "type": "string"
+                          ]
                         },
                         "message": {
                           "type": "string"
                         }
-                      },
-                      "required": [
-                        "code",
-                        "message"
-                      ],
-                      "type": "object"
-                    },
-                    "request_id": {
-                      "type": "string"
+                      }
                     }
-                  },
-                  "required": [
-                    "request_id",
-                    "error"
-                  ],
-                  "type": "object"
+                  }
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "error": {
+                    "code": "Conflict",
+                    "message": "expected_revision conflict: request has 11 but current revision is 12"
+                  }
                 }
               }
-            },
-            "description": "The report is not drafting, the revision is stale, or the idempotency key was reused for a different request."
+            }
           },
           "413": {
+            "description": "Markdown content exceeds the 4 MiB limit.",
             "content": {
               "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "error": {
                     "code": "EntityTooLarge",
                     "message": "markdown exceeds maximum size"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "$ref": "#/components/schemas/ErrorResponse"
+                  }
                 }
               }
-            },
-            "description": "Markdown content exceeds the 4 MiB limit."
-          },
-          "429": {
-            "$ref": "#/components/responses/TooManyRequests"
-          },
-          "500": {
-            "$ref": "#/components/responses/ServerError"
-          }
-        },
-        "summary": "Reset post-mortem content",
-        "tags": [
-          "On-call/Incidents"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | Edit access to the target report is required. |\n\n## Usage\n\n- The report must be drafting and its current revision must equal `expected_revision`; otherwise the API returns `409 Conflict`.\n- Reuse an `idempotency_key` only for the same report, revision, and Markdown content; different reuse returns `409 Conflict`.\n- A successful reset disconnects the previous collaboration (Yjs) room. Reconnect to the new generation room `post-mortem-{accountId}-{postMortemId}-g{N}` (generation 0 has no `-g` suffix). The reset cannot be rolled back.\n- Markdown content is limited to 4 MiB.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
-          "href": "/en/api-reference/on-call/incidents/incident-post-mortem-write-reset-content",
-          "metadata": {
-            "sidebarTitle": "Reset post-mortem content"
-          }
-        }
-      }
-    },
-    "/incident/post-mortem/delete": {
-      "post": {
-        "description": "Delete a post-mortem report.",
-        "operationId": "incidentPostMortemDelete",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "post_mortem_id": "8104935102bf89dc01ac638a5261fe7e"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/DeletePostMortemRequest"
-              }
             }
           },
-          "required": true
-        },
-        "responses": {
-          "200": {
-            "content": {
-              "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/EmptyResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
-                }
-              }
-            },
-            "description": "Success"
-          },
-          "400": {
-            "$ref": "#/components/responses/BadRequest"
-          },
-          "401": {
-            "$ref": "#/components/responses/Unauthorized"
-          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -42373,63 +43705,64 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Delete post-mortem",
-        "tags": [
-          "On-call/Incidents"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |",
-          "href": "/en/api-reference/on-call/incidents/incident-post-mortem-delete",
-          "metadata": {
-            "sidebarTitle": "Delete post-mortem"
-          }
-        }
-      }
-    },
-    "/incident/post-mortem/follow-ups/reset": {
-      "post": {
-        "description": "Replace the follow-up action items on a post-mortem report.",
-        "operationId": "postmortem-write-reset-follow-ups",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {
-                "follow_ups": "- Add database saturation alert\n- Review cache TTL rollout",
-                "post_mortem_id": "8104935102bf89dc01ac638a5261fe7e"
-              },
               "schema": {
-                "$ref": "#/components/schemas/ResetPostMortemFollowUpsRequest"
+                "$ref": "#/components/schemas/ResetPostMortemContentRequest"
+              },
+              "example": {
+                "post_mortem_id": "d3c9a7f2e5b14c8a9f0e6b2d4a1c7e35",
+                "markdown": "# Database saturation incident\n\nThe database pool was exhausted; added saturation alert.",
+                "expected_revision": 11,
+                "idempotency_key": "postmortem-reset-d3c9a7f2-11"
               }
-            }
-          },
-          "required": true
+            }
+          }
+        }
+      }
+    },
+    "/incident/post-mortem/delete": {
+      "post": {
+        "operationId": "incidentPostMortemDelete",
+        "summary": "Delete post-mortem",
+        "description": "Permanently delete a post-mortem report together with its uploaded media.",
+        "tags": [
+          "On-call/Incidents"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Requires the Professional edition or higher; otherwise the call fails with `NoLicense`.\n- The caller must be an account owner or admin, or a member of the post-mortem's team; otherwise the call fails with `AccessDenied`.\n- Linked incidents are unlinked, so their `post_mortem_id` becomes empty.\n- An unknown `post_mortem_id` returns `ResourceNotFound`.\n- On success the response has no `data` field.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "href": "/en/api-reference/on-call/incidents/incident-post-mortem-delete",
+          "metadata": {
+            "sidebarTitle": "Delete post-mortem"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -42437,6 +43770,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -42444,98 +43780,61 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/DeletePostMortemRequest"
+              },
+              "example": {
+                "post_mortem_id": "8104935102bf89dc01ac638a5261fe7e"
+              }
+            }
+          }
+        }
+      }
+    },
+    "/incident/post-mortem/follow-ups/reset": {
+      "post": {
+        "operationId": "postmortem-write-reset-follow-ups",
         "summary": "Update post-mortem follow-ups",
+        "description": "Replace the free-text follow-ups string stored on a post-mortem report.",
         "tags": [
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |\n\n## Usage\n\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Requires the On-call Pro license.\n- The caller must be an account owner or admin, or a member of the report's team; otherwise the call returns `AccessDenied`.\n- Works in any report status. Omitting `follow_ups` or sending `\"\"` clears the string.\n- When `follow_ups` is a JSON array in the console's follow-up format, its entries are also synced into structured follow-up work items (`source_kind` = `legacy_follow_up`); other text leaves the structured items unchanged.\n- To manage individual follow-ups, prefer the `/incident/work-item/*` endpoints.\n- The caller is added to the report's `author_ids`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/on-call/incidents/postmortem-write-reset-follow-ups",
           "metadata": {
             "sidebarTitle": "Update post-mortem follow-ups"
           }
-        }
-      }
-    },
-    "/incident/post-mortem/info": {
-      "get": {
-        "description": "Retrieve a post-mortem report by its `post_mortem_id`. List reports via `/incident/post-mortem/list` first — each row carries the incident it covers — then fetch the full report here by that id.",
-        "operationId": "incidentPostMortemInfo",
-        "parameters": [
-          {
-            "description": "Post-mortem ID. Deterministic hash derived from account ID and the set of linked incident IDs.",
-            "in": "query",
-            "name": "post_mortem_id",
-            "required": true,
-            "schema": {
-              "type": "string"
-            }
-          }
-        ],
+        },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "basics": {
-                      "incidents_earliest_start_seconds": 1761133512,
-                      "incidents_highest_severity": "Warning",
-                      "incidents_latest_close_seconds": 1761133632,
-                      "incidents_total_duration_seconds": 120,
-                      "responders": [
-                        {
-                          "acknowledged_at": 0,
-                          "assigned_at": 1761133515,
-                          "person_id": 3790925372131
-                        }
-                      ]
-                    },
-                    "content": {
-                      "content": "{\"type\":\"doc\",\"content\":[]}"
-                    },
-                    "follow_ups": "",
-                    "meta": {
-                      "account_id": 2451002751131,
-                      "author_ids": [
-                        2477273692131
-                      ],
-                      "channel_id": 3047621227131,
-                      "channel_name": "Ops Channel",
-                      "created_at_seconds": 1773900354,
-                      "incident_ids": [
-                        "69bb9233331067560c718ecd"
-                      ],
-                      "is_private": false,
-                      "media_count": 0,
-                      "post_mortem_id": "8104935102bf89dc01ac638a5261fe7e",
-                      "status": "published",
-                      "team_id": 2477033058131,
-                      "template_id": "post_mortem_default_tmpl_en-us",
-                      "title": "Postmortem1",
-                      "updated_at_seconds": 1773909012
-                    }
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/PostMortemItem"
+                          "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -42543,6 +43842,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -42550,55 +43852,92 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ResetPostMortemFollowUpsRequest"
+              },
+              "example": {
+                "post_mortem_id": "d3c9a7f2e5b14c8a9f0e6b2d4a1c7e35",
+                "follow_ups": "- Add database saturation alert\n- Review cache TTL rollout"
+              }
+            }
+          }
+        }
+      }
+    },
+    "/incident/post-mortem/info": {
+      "get": {
+        "operationId": "incidentPostMortemInfo",
         "summary": "Get post-mortem",
+        "description": "Get the full content and auto-aggregated basics of a post-mortem report by its ID.",
         "tags": [
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Read** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Get `post_mortem_id` from `POST /incident/post-mortem/list`, or from an incident's `post_mortem_id`.\n- Private post-mortems can be read only by account owners, admins, and members of the post-mortem's team; others get `AccessDenied`.\n- An unknown `post_mortem_id` returns `ResourceNotFound`.",
           "href": "/en/api-reference/on-call/incidents/incident-post-mortem-info",
           "metadata": {
             "sidebarTitle": "Get post-mortem"
           }
-        }
-      }
-    },
-    "/incident/post-mortem/init": {
-      "post": {
-        "description": "Create a post-mortem draft from one or more incidents and a template.",
-        "operationId": "postmortem-write-init",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "incident_ids": [
-                  "69bb9233331067560c718ecd"
-                ],
-                "template_id": "post_mortem_default_tmpl_en-us"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/InitPostMortemRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/PostMortemItem"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
+                    "meta": {
+                      "account_id": 2451002751131,
+                      "title": "Postmortem1",
+                      "status": "published",
+                      "post_mortem_id": "8104935102bf89dc01ac638a5261fe7e",
+                      "template_id": "post_mortem_default_tmpl_en-us",
+                      "incident_ids": [
+                        "69bb9233331067560c718ecd"
+                      ],
+                      "media_count": 0,
+                      "author_ids": [
+                        2477273692131
+                      ],
+                      "team_id": 2477033058131,
+                      "channel_id": 3047621227131,
+                      "is_private": false,
+                      "generation": 0,
+                      "revision": 12,
+                      "channel_name": "Ops Channel",
+                      "created_at_seconds": 1773900354,
+                      "updated_at_seconds": 1773909012
+                    },
                     "basics": {
-                      "incidents_earliest_start_seconds": 1761133512,
                       "incidents_highest_severity": "Warning",
+                      "incidents_earliest_start_seconds": 1761133512,
                       "incidents_latest_close_seconds": 1761133632,
                       "incidents_total_duration_seconds": 120,
                       "responders": [
                         {
-                          "acknowledged_at": 0,
+                          "person_id": 3790925372131,
                           "assigned_at": 1761133515,
-                          "person_id": 3790925372131
+                          "acknowledged_at": 0
                         }
                       ]
                     },
@@ -42606,47 +43945,11 @@
                       "content": "{\"type\":\"doc\",\"content\":[]}"
                     },
                     "follow_ups": "",
-                    "meta": {
-                      "account_id": 2451002751131,
-                      "author_ids": [
-                        2477273692131
-                      ],
-                      "channel_id": 3047621227131,
-                      "channel_name": "Ops Channel",
-                      "created_at_seconds": 1773900354,
-                      "incident_ids": [
-                        "69bb9233331067560c718ecd"
-                      ],
-                      "is_private": false,
-                      "media_count": 0,
-                      "post_mortem_id": "8104935102bf89dc01ac638a5261fe7e",
-                      "status": "published",
-                      "team_id": 2477033058131,
-                      "template_id": "post_mortem_default_tmpl_en-us",
-                      "title": "Postmortem1",
-                      "updated_at_seconds": 1773909012
-                    }
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/PostMortemItem"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                    "has_active_incident": false
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -42654,6 +43957,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -42661,89 +43967,101 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "parameters": [
+          {
+            "name": "post_mortem_id",
+            "in": "query",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Post-mortem ID: a 32-character hex string derived from the account ID and the linked incident IDs."
+          }
+        ]
+      }
+    },
+    "/incident/post-mortem/init": {
+      "post": {
+        "operationId": "postmortem-write-init",
         "summary": "Initialize post-mortem",
+        "description": "Create a post-mortem draft from one or more incidents and a template.",
         "tags": [
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |\n\n## Usage\n\n- Links at most 10 incidents to one post-mortem report.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Requires the On-call Pro license.\n- The report ID is derived from the account and the sorted `incident_ids`; calling again with the same incidents returns the existing report unchanged.\n- Fails with `InvalidParameter` when any incident is already linked to a different post-mortem.\n- Team, channel and privacy are copied from the channel of the first incident loaded; an incident without a channel cannot start a report.\n- The title is the incident titles joined by `, ` (at most 512 characters), or the template name when all titles are empty.\n- A new report starts as `drafting` with an empty body; its basics (severity, times, responders) are computed from the incidents.\n- Converted follow-ups of these incidents that are not yet bound to a report are bound to it.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/on-call/incidents/postmortem-write-init",
           "metadata": {
             "sidebarTitle": "Initialize post-mortem"
           }
-        }
-      }
-    },
-    "/incident/post-mortem/list": {
-      "post": {
-        "description": "List post-mortem reports with optional filters.",
-        "operationId": "incidentPostMortemList",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "limit": 20,
-                "p": 1,
-                "status": "published"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ListPostMortemsRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "has_next_page": false,
-                    "items": [
-                      {
-                        "account_id": 2451002751131,
-                        "author_ids": [
-                          2477273692131
-                        ],
-                        "channel_id": 3047621227131,
-                        "channel_name": "Ops Channel",
-                        "created_at_seconds": 1773900354,
-                        "incident_ids": [
-                          "69bb9233331067560c718ecd"
-                        ],
-                        "is_private": false,
-                        "media_count": 0,
-                        "post_mortem_id": "8104935102bf89dc01ac638a5261fe7e",
-                        "status": "published",
-                        "team_id": 2477033058131,
-                        "template_id": "post_mortem_default_tmpl_en-us",
-                        "title": "Postmortem1",
-                        "updated_at_seconds": 1773909012
-                      }
-                    ],
-                    "total": 3
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/ListPostMortemsResponse"
+                          "$ref": "#/components/schemas/PostMortemItem"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "meta": {
+                      "account_id": 2451002751131,
+                      "title": "Database connection timeout on prod-db-01",
+                      "status": "drafting",
+                      "post_mortem_id": "d3c9a7f2e5b14c8a9f0e6b2d4a1c7e35",
+                      "template_id": "post_mortem_default_tmpl_en-us",
+                      "incident_ids": [
+                        "69bb9233331067560c718ecd"
+                      ],
+                      "media_count": 0,
+                      "author_ids": [
+                        3790925372131
+                      ],
+                      "team_id": 2477033058131,
+                      "channel_id": 2551105804131,
+                      "is_private": false,
+                      "generation": 0,
+                      "revision": 0,
+                      "channel_name": "Ops Channel",
+                      "created_at_seconds": 1773900354,
+                      "updated_at_seconds": 1773900354
+                    },
+                    "basics": {
+                      "incidents_highest_severity": "Critical",
+                      "incidents_earliest_start_seconds": 1773890000,
+                      "incidents_latest_close_seconds": 1773897200,
+                      "incidents_total_duration_seconds": 7200,
+                      "responders": [
+                        {
+                          "person_id": 3790925372131,
+                          "assigned_at": 1773890012,
+                          "acknowledged_at": 1773890100
+                        }
+                      ]
+                    },
+                    "content": {
+                      "content": ""
+                    },
+                    "follow_ups": "",
+                    "has_active_incident": false
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -42751,6 +44069,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -42758,63 +44079,92 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/InitPostMortemRequest"
+              },
+              "example": {
+                "incident_ids": [
+                  "69bb9233331067560c718ecd"
+                ],
+                "template_id": "post_mortem_default_tmpl_en-us"
+              }
+            }
+          }
+        }
+      }
+    },
+    "/incident/post-mortem/list": {
+      "post": {
+        "operationId": "incidentPostMortemList",
         "summary": "List post-mortems",
+        "description": "List post-mortem reports, optionally filtered by status, team, channel, and creation time.",
         "tags": [
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Read** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Account owners and admins see all post-mortems; other members see public ones plus private ones that belong to their own teams.\n- Results are sorted by `order_by` (default `created_at_seconds`), descending unless `asc` is `true`.\n- Items carry metadata only; fetch the full report with `GET /incident/post-mortem/info`.",
           "href": "/en/api-reference/on-call/incidents/incident-post-mortem-list",
           "metadata": {
             "sidebarTitle": "List post-mortems"
           }
-        }
-      }
-    },
-    "/incident/post-mortem/status/reset": {
-      "post": {
-        "description": "Set a post-mortem report to drafting or published.",
-        "operationId": "postmortem-write-reset-status",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "post_mortem_id": "8104935102bf89dc01ac638a5261fe7e",
-                "status": "published"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ResetPostMortemStatusRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/EmptyResponse"
+                          "$ref": "#/components/schemas/ListPostMortemsResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "total": 3,
+                    "has_next_page": false,
+                    "items": [
+                      {
+                        "account_id": 2451002751131,
+                        "title": "Postmortem1",
+                        "status": "published",
+                        "post_mortem_id": "8104935102bf89dc01ac638a5261fe7e",
+                        "template_id": "post_mortem_default_tmpl_en-us",
+                        "incident_ids": [
+                          "69bb9233331067560c718ecd"
+                        ],
+                        "media_count": 0,
+                        "author_ids": [
+                          2477273692131
+                        ],
+                        "team_id": 2477033058131,
+                        "channel_id": 3047621227131,
+                        "is_private": false,
+                        "generation": 0,
+                        "revision": 12,
+                        "channel_name": "Ops Channel",
+                        "created_at_seconds": 1773900354,
+                        "updated_at_seconds": 1773909012
+                      }
+                    ]
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -42822,6 +44172,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -42829,62 +44182,63 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ListPostMortemsRequest"
+              },
+              "example": {
+                "status": "published",
+                "p": 1,
+                "limit": 20
+              }
+            }
+          }
+        }
+      }
+    },
+    "/incident/post-mortem/status/reset": {
+      "post": {
+        "operationId": "postmortem-write-reset-status",
         "summary": "Update post-mortem status",
+        "description": "Set a post-mortem report to drafting or published.",
         "tags": [
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |\n\n## Usage\n\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Requires the On-call Pro license.\n- The caller must be an account owner or admin, or a member of the report's team; otherwise the call returns `AccessDenied`.\n- Status can move both ways. Only a `drafting` report accepts `POST /incident/post-mortem/content/reset`.\n- Publishing deletes uploaded media files that the report body no longer references.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/on-call/incidents/postmortem-write-reset-status",
           "metadata": {
             "sidebarTitle": "Update post-mortem status"
           }
-        }
-      }
-    },
-    "/incident/post-mortem/template/delete": {
-      "post": {
-        "description": "Delete a custom post-mortem template.",
-        "operationId": "postmortem-write-delete-template",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "template_id": "post_mortem_custom_tmpl_01"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/DeletePostMortemTemplateRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -42892,6 +44246,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -42899,70 +44256,62 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ResetPostMortemStatusRequest"
+              },
+              "example": {
+                "post_mortem_id": "d3c9a7f2e5b14c8a9f0e6b2d4a1c7e35",
+                "status": "published"
+              }
+            }
+          }
+        }
+      }
+    },
+    "/incident/post-mortem/template/delete": {
+      "post": {
+        "operationId": "postmortem-write-delete-template",
         "summary": "Delete post-mortem template",
+        "description": "Delete a custom post-mortem template.",
         "tags": [
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |\n\n## Usage\n\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Requires the On-call Pro license.\n- Built-in templates (`post_mortem_default_tmpl_*`) cannot be deleted; an unknown ID returns `ResourceNotFound`.\n- Requires being an account owner or admin, or a member of the template's team.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/on-call/incidents/postmortem-write-delete-template",
           "metadata": {
             "sidebarTitle": "Delete post-mortem template"
           }
-        }
-      }
-    },
-    "/incident/post-mortem/template/info": {
-      "get": {
-        "description": "Return one post-mortem template by ID.",
-        "operationId": "postmortem-read-template-info",
-        "parameters": [
-          {
-            "description": "Template ID.",
-            "in": "query",
-            "name": "template_id",
-            "required": true,
-            "schema": {
-              "type": "string"
-            }
-          }
-        ],
+        },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "account_id": 2451002751131,
-                    "content": "[{\"type\":\"heading\",\"content\":\"Summary\"}]",
-                    "content_markdown": "## Summary\nDescribe what happened.",
-                    "created_at_seconds": 1773900000,
-                    "description": "Default sections for post-mortem reports.",
-                    "name": "Default post-mortem report",
-                    "team_id": 2477033058131,
-                    "template_id": "post_mortem_default_tmpl_en-us",
-                    "updated_at_seconds": 1773903600
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/PostMortemTemplate"
+                          "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -42970,6 +44319,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -42977,81 +44329,72 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/DeletePostMortemTemplateRequest"
+              },
+              "example": {
+                "template_id": "kQ3vXn8pR2mT7wYbZc4dEf"
+              }
+            }
+          }
+        }
+      }
+    },
+    "/incident/post-mortem/template/info": {
+      "get": {
+        "operationId": "postmortem-read-template-info",
         "summary": "Get post-mortem template detail",
+        "description": "Return one post-mortem template by ID.",
         "tags": [
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Read** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Requires the On-call Pro license.\n- Accepts the built-in IDs `post_mortem_default_tmpl_zh-cn` and `post_mortem_default_tmpl_en-us` regardless of request language; an unknown ID returns `ResourceNotFound`.",
           "href": "/en/api-reference/on-call/incidents/postmortem-read-template-info",
           "metadata": {
             "sidebarTitle": "Get post-mortem template detail"
           }
-        }
-      }
-    },
-    "/incident/post-mortem/template/list": {
-      "post": {
-        "description": "Return built-in and custom post-mortem templates for the account.",
-        "operationId": "postmortem-read-list-templates",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "asc": false,
-                "limit": 20,
-                "order_by": "created_at_seconds",
-                "p": 1
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ListPostMortemTemplatesRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "has_next_page": false,
-                    "items": [
-                      {
-                        "account_id": 2451002751131,
-                        "content": "[{\"type\":\"heading\",\"content\":\"Summary\"}]",
-                        "content_markdown": "## Summary\nDescribe what happened.",
-                        "created_at_seconds": 1773900000,
-                        "description": "Default sections for post-mortem reports.",
-                        "name": "Default post-mortem report",
-                        "team_id": 2477033058131,
-                        "template_id": "post_mortem_default_tmpl_en-us",
-                        "updated_at_seconds": 1773903600
-                      }
-                    ],
-                    "total": 2
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/ListPostMortemTemplatesResponse"
+                          "$ref": "#/components/schemas/PostMortemTemplate"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "account_id": 0,
+                    "template_id": "post_mortem_default_tmpl_en-us",
+                    "name": "Default Post Mortem Report Template",
+                    "description": "Standard post-mortem template with common sections",
+                    "content": "[{\"type\":\"heading\",\"props\":{\"level\":2},\"content\":\"Summary\"}]",
+                    "content_markdown": "## Summary\n> Provide a high-level description of the incident.",
+                    "team_id": 0,
+                    "created_at_seconds": 0,
+                    "updated_at_seconds": 0
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -43059,6 +44402,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -43066,76 +44412,87 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "parameters": [
+          {
+            "name": "template_id",
+            "in": "query",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Template ID: a built-in ID such as `post_mortem_default_tmpl_en-us`, or a custom template ID from `POST /incident/post-mortem/template/list`."
+          }
+        ]
+      }
+    },
+    "/incident/post-mortem/template/list": {
+      "post": {
+        "operationId": "postmortem-read-list-templates",
         "summary": "List post-mortem templates",
+        "description": "Return the built-in post-mortem template followed by the account's custom templates.",
         "tags": [
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Read** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Requires the On-call Pro license.\n- The built-in template always comes first and matches the request language: Chinese returns `post_mortem_default_tmpl_zh-cn`, anything else `post_mortem_default_tmpl_en-us`. `total` includes it.\n- Custom templates are sorted by `created_at_seconds`, newest first unless `asc` is true.\n- Paginate with `p` and `limit`; `p` × `limit` must not exceed 10,000.\n- Built-in templates have `account_id`, `team_id` and both timestamps set to 0.",
           "href": "/en/api-reference/on-call/incidents/postmortem-read-list-templates",
           "metadata": {
             "sidebarTitle": "List post-mortem templates"
           }
-        }
-      }
-    },
-    "/incident/post-mortem/template/upsert": {
-      "post": {
-        "description": "Create a custom post-mortem template or update an existing one.",
-        "operationId": "postmortem-write-upsert-template",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "content": "[{\"type\":\"heading\",\"content\":\"Summary\"}]",
-                "content_markdown": "## Summary\nDescribe what happened.",
-                "description": "Template for production incident reviews.",
-                "name": "Production incident template",
-                "team_id": 2477033058131
-              },
-              "schema": {
-                "$ref": "#/components/schemas/UpsertPostMortemTemplateRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "account_id": 2451002751131,
-                    "content": "[{\"type\":\"heading\",\"content\":\"Summary\"}]",
-                    "content_markdown": "## Summary\nDescribe what happened.",
-                    "created_at_seconds": 1773900000,
-                    "description": "Default sections for post-mortem reports.",
-                    "name": "Default post-mortem report",
-                    "team_id": 2477033058131,
-                    "template_id": "post_mortem_default_tmpl_en-us",
-                    "updated_at_seconds": 1773903600
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/PostMortemTemplate"
+                          "$ref": "#/components/schemas/ListPostMortemTemplatesResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "total": 2,
+                    "has_next_page": false,
+                    "items": [
+                      {
+                        "account_id": 0,
+                        "template_id": "post_mortem_default_tmpl_en-us",
+                        "name": "Default Post Mortem Report Template",
+                        "description": "Standard post-mortem template with common sections",
+                        "content": "[{\"type\":\"heading\",\"props\":{\"level\":2},\"content\":\"Summary\"}]",
+                        "content_markdown": "## Summary\n> Provide a high-level description of the incident.",
+                        "team_id": 0,
+                        "created_at_seconds": 0,
+                        "updated_at_seconds": 0
+                      },
+                      {
+                        "account_id": 2451002751131,
+                        "template_id": "kQ3vXn8pR2mT7wYbZc4dEf",
+                        "name": "Production incident template",
+                        "description": "Template for production incident reviews.",
+                        "content": "[{\"type\":\"heading\",\"props\":{\"level\":2},\"content\":\"Summary\"}]",
+                        "content_markdown": "## Summary\nDescribe what happened.",
+                        "team_id": 2477033058131,
+                        "created_at_seconds": 1773900000,
+                        "updated_at_seconds": 1773903600
+                      }
+                    ]
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -43143,6 +44500,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -43150,63 +44510,75 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ListPostMortemTemplatesRequest"
+              },
+              "example": {
+                "p": 1,
+                "limit": 20,
+                "order_by": "created_at_seconds",
+                "asc": false
+              }
+            }
+          }
+        }
+      }
+    },
+    "/incident/post-mortem/template/upsert": {
+      "post": {
+        "operationId": "postmortem-write-upsert-template",
         "summary": "Create or update post-mortem template",
+        "description": "Create a custom post-mortem template, or replace an existing one identified by `template_id`.",
         "tags": [
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |\n\n## Usage\n\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Requires the On-call Pro license.\n- Omit `template_id` to create: `team_id` must name an existing team, and the server generates the template ID.\n- With `template_id`, the existing custom template is replaced; an unknown ID returns `ResourceNotFound`. Updating requires being an account owner or admin, or a member of the template's team.\n- All text fields are replaced: an omitted `description` or `content_markdown` becomes empty. On update, `team_id` moves the template to that team; omit it or send 0 to keep the current team.\n- Built-in templates (`post_mortem_default_tmpl_*`) cannot be modified.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/on-call/incidents/postmortem-write-upsert-template",
           "metadata": {
             "sidebarTitle": "Create or update post-mortem template"
           }
-        }
-      }
-    },
-    "/incident/post-mortem/title/reset": {
-      "post": {
-        "description": "Replace the title of a post-mortem report.",
-        "operationId": "postmortem-write-reset-title",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "post_mortem_id": "8104935102bf89dc01ac638a5261fe7e",
-                "title": "Production API latency incident"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ResetPostMortemTitleRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/EmptyResponse"
+                          "$ref": "#/components/schemas/PostMortemTemplate"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "account_id": 2451002751131,
+                    "template_id": "kQ3vXn8pR2mT7wYbZc4dEf",
+                    "name": "Production incident template",
+                    "description": "Template for production incident reviews.",
+                    "content": "[{\"type\":\"heading\",\"props\":{\"level\":2},\"content\":\"Summary\"}]",
+                    "content_markdown": "## Summary\nDescribe what happened.",
+                    "team_id": 2477033058131,
+                    "created_at_seconds": 1773900000,
+                    "updated_at_seconds": 1773903600
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -43214,6 +44586,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -43221,64 +44596,65 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/UpsertPostMortemTemplateRequest"
+              },
+              "example": {
+                "team_id": 2477033058131,
+                "name": "Production incident template",
+                "description": "Template for production incident reviews.",
+                "content": "[{\"type\":\"heading\",\"props\":{\"level\":2},\"content\":\"Summary\"}]",
+                "content_markdown": "## Summary\nDescribe what happened."
+              }
+            }
+          }
+        }
+      }
+    },
+    "/incident/post-mortem/title/reset": {
+      "post": {
+        "operationId": "postmortem-write-reset-title",
         "summary": "Update post-mortem title",
+        "description": "Replace the title of a post-mortem report.",
         "tags": [
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |\n\n## Usage\n\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Requires the On-call Pro license.\n- The caller must be an account owner or admin, or a member of the report's team; otherwise the call returns `AccessDenied`.\n- The caller is added to the report's `author_ids`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/on-call/incidents/postmortem-write-reset-title",
           "metadata": {
             "sidebarTitle": "Update post-mortem title"
           }
-        }
-      }
-    },
-    "/incident/remove": {
-      "post": {
-        "description": "Permanently delete an incident and all associated data.",
-        "operationId": "incidentRemove",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "incident_ids": [
-                  "69da451ef77b1b51f40e83ee"
-                ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/RemoveIncidentRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -43286,6 +44662,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -43293,65 +44672,63 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ResetPostMortemTitleRequest"
+              },
+              "example": {
+                "post_mortem_id": "d3c9a7f2e5b14c8a9f0e6b2d4a1c7e35",
+                "title": "Production API latency incident"
+              }
+            }
+          }
+        }
+      }
+    },
+    "/incident/remove": {
+      "post": {
+        "operationId": "incidentRemove",
         "summary": "Delete an incident",
+        "description": "Permanently delete incidents together with their alerts, raw events, and timelines.",
         "tags": [
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Incidents Manage** or **Channels Manage** (`on-call`) |\n\n## Usage\n\n- Deletion cannot be undone. Analytics statistics of the deleted incidents are removed in the background.\n- Fails with `InvalidParameter` if any incident belongs to a channel the caller cannot access.\n- IDs that do not match an incident are ignored.\n- Returns `RequestTooFrequently` while another resolve, reopen, merge, comment, or delete is running in the same account; retry after a short delay.",
           "href": "/en/api-reference/on-call/incidents/incident-remove",
           "metadata": {
             "sidebarTitle": "Delete an incident"
           }
-        }
-      }
-    },
-    "/incident/reopen": {
-      "post": {
-        "description": "Reopen a previously resolved incident.",
-        "operationId": "incidentReopen",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "incident_ids": [
-                  "69da451ef77b1b51f40e83ee"
-                ],
-                "reason": "Monitoring detected the issue recurred after the initial fix."
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ReopenIncidentRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -43359,6 +44736,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -43366,64 +44746,64 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/RemoveIncidentRequest"
+              },
+              "example": {
+                "incident_ids": [
+                  "69da451ef77b1b51f40e83ee"
+                ]
+              }
+            }
+          }
+        }
+      }
+    },
+    "/incident/reopen": {
+      "post": {
+        "operationId": "incidentReopen",
         "summary": "Reopen incident",
+        "description": "Reopen closed incidents and dispatch them again from the first escalation level.",
         "tags": [
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Incidents Manage** or **Channels Manage** (`on-call`) |\n\n## Usage\n\n- Every incident must be `Closed`; otherwise the whole call fails with `InvalidParameter`.\n- Reopened incidents return to `Triggered`, with `ack_time`, `close_time`, `closer_id`, and every responder's acknowledgement reset.\n- Each incident is reassigned to its previous assignment target starting at the first escalation level, with `assigned_to.type` set to `reopen`.\n- Returns `RequestTooFrequently` while another resolve, reopen, merge, comment, or delete is running in the same account; retry after a short delay.",
           "href": "/en/api-reference/on-call/incidents/incident-reopen",
           "metadata": {
             "sidebarTitle": "Reopen incident"
           }
-        }
-      }
-    },
-    "/incident/reset": {
-      "post": {
-        "description": "Update one or more editable fields of an incident in a single call, including title, description, impact, root cause, resolution, and severity. At least one field must be provided.",
-        "operationId": "incidentReset",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "incident_id": "69da451ef77b1b51f40e83ee",
-                "incident_severity": "Critical",
-                "title": "Database connection timeout - prod-db-01 primary"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/UpdateIncidentFieldsRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -43431,6 +44811,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -43438,66 +44821,65 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Update incident fields",
-        "tags": [
-          "On-call/Incidents"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |",
-          "href": "/en/api-reference/on-call/incidents/incident-reset",
-          "metadata": {
-            "sidebarTitle": "Update incident fields"
-          }
-        }
-      }
-    },
-    "/incident/resolve": {
-      "post": {
-        "description": "Mark an incident as resolved.",
-        "operationId": "incidentResolve",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ReopenIncidentRequest"
+              },
               "example": {
                 "incident_ids": [
                   "69da451ef77b1b51f40e83ee"
                 ],
-                "resolution": "Deployed hotfix v2.3.1 and restarted the affected service.",
-                "root_cause": "Memory leak in the connection pool caused by a missing cleanup call."
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ResolveIncidentRequest"
+                "reason": "Monitoring detected the issue recurred after the initial fix."
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/incident/reset": {
+      "post": {
+        "operationId": "incidentReset",
+        "summary": "Update incident fields",
+        "description": "Update an incident's title, description, impact, root cause, resolution, or severity in one call.",
+        "tags": [
+          "On-call/Incidents"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Incidents Manage** or **Channels Manage** (`on-call`) |\n\n## Usage\n\n- At least one field must be provided. Omitted fields and empty strings keep their current values, so this endpoint cannot clear a field.\n- Values equal to the current ones are skipped. Each changed field adds its own timeline entry (`i_r_title`, `i_r_desc`, `i_r_impact`, `i_r_rc`, `i_r_rsltn`, or `i_r_severity`).\n- Changing `title`, `description`, or `incident_severity` adds that field to `manual_overrides`; after that, alerts merged into the incident no longer overwrite it.\n- Closed incidents can be updated as well.",
+          "href": "/en/api-reference/on-call/incidents/incident-reset",
+          "metadata": {
+            "sidebarTitle": "Update incident fields"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -43505,73 +44887,74 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
           "500": {
             "$ref": "#/components/responses/ServerError"
           }
-        },
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/UpdateIncidentFieldsRequest"
+              },
+              "example": {
+                "incident_id": "69da451ef77b1b51f40e83ee",
+                "title": "Database connection timeout - prod-db-01 primary",
+                "incident_severity": "Critical"
+              }
+            }
+          }
+        }
+      }
+    },
+    "/incident/resolve": {
+      "post": {
+        "operationId": "incidentResolve",
         "summary": "Resolve incident",
+        "description": "Close one or more incidents, optionally recording root cause, resolution, and resolution form values.",
         "tags": [
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |\n\n## Usage\n\n- When a resolution form applies, `custom_fields`, `summary`, and `images` must match its visible elements and required rules.\n- For a batch, form values are accepted only when every selected incident resolves to the same form; otherwise resolve incidents individually.\n- The legacy `values` and `custom_values` properties are rejected; use `custom_fields`.\n- Audited — changes are recorded in the audit log.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Incidents Manage** or **Channels Manage** (`on-call`) |\n\n## Usage\n\n- When a resolution form applies, `custom_fields`, `summary`, and `images` must match its visible elements and required rules.\n- For a batch, form values are accepted only when every selected incident resolves to the same form; otherwise resolve incidents individually.\n- The legacy `values` and `custom_values` properties are rejected; use `custom_fields`.\n- Incidents that are already closed are skipped without error; an unknown ID fails the whole call with `InvalidParameter`.\n- Resolving a `Triggered` incident first acknowledges it on behalf of the caller.\n- After closing, unfinished action items of the incident are converted to follow-ups, and later events no longer merge into the incident's existing alerts.\n- Returns `RequestTooFrequently` while another resolve, reopen, merge, comment, or delete is running in the same account; retry after a short delay.",
           "href": "/en/api-reference/on-call/incidents/incident-resolve",
           "metadata": {
             "sidebarTitle": "Resolve incident"
           }
-        }
-      }
-    },
-    "/incident/responder/add": {
-      "post": {
-        "description": "Add a responder to an existing incident.",
-        "operationId": "incidentResponderAdd",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "incident_id": "69da451ef77b1b51f40e83ee",
-                "person_ids": [
-                  2476444212131,
-                  2476444212132
-                ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/AddIncidentResponderRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -43579,6 +44962,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -43586,85 +44972,66 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ResolveIncidentRequest"
+              },
+              "example": {
+                "incident_ids": [
+                  "69da451ef77b1b51f40e83ee"
+                ],
+                "root_cause": "Memory leak in the connection pool caused by a missing cleanup call.",
+                "resolution": "Deployed hotfix v2.3.1 and restarted the affected service."
+              }
+            }
+          }
+        }
+      }
+    },
+    "/incident/responder/add": {
+      "post": {
+        "operationId": "incidentResponderAdd",
         "summary": "Add incident responder",
+        "description": "Add members as responders to an open incident and notify them.",
         "tags": [
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Incidents Manage** or **Channels Manage** (`on-call`) |\n\n## Usage\n\n- Existing responders are kept, and IDs that are already responders are skipped. To replace the responder set, use `POST /incident/assign`.\n- Closed incidents are rejected with `InvalidParameter`.\n- Member IDs that do not exist in the account are ignored.\n- New responders are notified according to `notify`; by default each follows their personal notification preference.",
           "href": "/en/api-reference/on-call/incidents/incident-responder-add",
           "metadata": {
             "sidebarTitle": "Add incident responder"
           }
-        }
-      }
-    },
-    "/incident/sdp/request/list": {
-      "post": {
-        "description": "List synchronization mappings between ServiceDeskPlus requests and Flashduty incidents.",
-        "operationId": "incident-service-desk-plus-request-read-list",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "channel_ids": [
-                  12345
-                ],
-                "end_time": 1779600000,
-                "limit": 20,
-                "start_time": 1779513600,
-                "status": "success"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ServiceDeskPlusRequestListRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "has_next_page": false,
-                    "items": [
-                      {
-                        "channel_id": 12345,
-                        "channel_name": "Payments",
-                        "created_at": 1779514631,
-                        "incident_id": "685d7f4e51b9a9a6d4d0c123",
-                        "incident_title": "Checkout API 5xx rate increased",
-                        "integration_id": 98765,
-                        "request_id": "100000000001",
-                        "request_link": "https://servicedesk.example.com/app/itdesk/ui/requests/100000000001/details",
-                        "status": "success"
-                      }
-                    ],
-                    "search_after_ctx": "",
-                    "total": 1
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/ServiceDeskPlusRequestListResponse"
+                          "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -43672,6 +45039,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -43679,65 +45049,83 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/AddIncidentResponderRequest"
+              },
+              "example": {
+                "incident_id": "69da451ef77b1b51f40e83ee",
+                "person_ids": [
+                  2476444212131,
+                  2476444212132
+                ]
+              }
+            }
+          }
+        }
+      }
+    },
+    "/incident/sdp/request/list": {
+      "post": {
+        "operationId": "incident-service-desk-plus-request-read-list",
         "summary": "Get ServiceDeskPlus linked incidents",
+        "description": "List synchronization mappings between ServiceDeskPlus requests and Flashduty incidents.",
         "tags": [
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Read** (`on-call`) |\n\n## Usage\n\n- Use this endpoint to inspect synchronization mappings between ServiceDeskPlus requests and Flashduty incidents, including the external request link and sync status.\n- When `incident_id` is not provided, `start_time` and `end_time` are required Unix-second timestamps; the time window cannot exceed 30 days.\n- `status` accepts only `success` and `failed`, representing successful and failed synchronization records.\n- Results are sorted by the internal record ID. Set `asc` to `true` for ascending order; otherwise records are returned descending. Pass the returned `search_after_ctx` to continue pagination.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Read** or **Incidents Manage** or **Channels Read** or **Channels Manage** (`on-call`) |\n\n## Usage\n\n- Use this endpoint to inspect synchronization mappings between ServiceDeskPlus requests and Flashduty incidents, including the external request link and sync status.\n- When `incident_id` is not provided, `start_time` and `end_time` are required Unix-second timestamps; the time window cannot exceed 30 days.\n- `status` accepts only `success` and `failed`, representing successful and failed synchronization records.\n- Results are sorted by the internal record ID. Set `asc` to `true` for ascending order; otherwise records are returned descending.\n- Pagination uses only `search_after_ctx`: pass the value returned by the previous response; `p` is ignored.",
           "href": "/en/api-reference/on-call/incidents/incident-service-desk-plus-request-read-list",
           "metadata": {
             "sidebarTitle": "Get ServiceDeskPlus linked incidents"
           }
-        }
-      }
-    },
-    "/incident/snooze": {
-      "post": {
-        "description": "Temporarily snooze notifications for an incident until a specified time.",
-        "operationId": "incidentSnooze",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "incident_ids": [
-                  "69da451ef77b1b51f40e83ee"
-                ],
-                "minutes": 60
-              },
-              "schema": {
-                "$ref": "#/components/schemas/SnoozeIncidentRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/EmptyResponse"
+                          "$ref": "#/components/schemas/ServiceDeskPlusRequestListResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "items": [
+                      {
+                        "created_at": 1779514631,
+                        "status": "success",
+                        "request_id": "100000000001",
+                        "request_link": "https://servicedesk.example.com/app/itdesk/ui/requests/100000000001/details",
+                        "integration_id": 98765,
+                        "incident_id": "685d7f4e51b9a9a6d4d0c123",
+                        "incident_title": "Checkout API 5xx rate increased",
+                        "channel_id": 12345,
+                        "channel_name": "Payments"
+                      }
+                    ],
+                    "total": 1,
+                    "has_next_page": false,
+                    "search_after_ctx": ""
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -43745,6 +45133,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -43752,64 +45143,68 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ServiceDeskPlusRequestListRequest"
+              },
+              "example": {
+                "start_time": 1779513600,
+                "end_time": 1779600000,
+                "status": "success",
+                "channel_ids": [
+                  12345
+                ],
+                "limit": 20
+              }
+            }
+          }
+        }
+      }
+    },
+    "/incident/snooze": {
+      "post": {
+        "operationId": "incidentSnooze",
         "summary": "Snooze incident",
+        "description": "Pause notifications for acknowledged incidents for a given number of minutes.",
         "tags": [
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Incidents Manage** or **Channels Manage** (`on-call`) |\n\n## Usage\n\n- Only incidents in `Processing` progress can be snoozed; any other progress fails the whole call with `InvalidParameter`.\n- Notifications resume automatically after `minutes` elapse, or earlier through `POST /incident/wake`. The snooze end time is stored in the incident's `snoozed_before` (Unix seconds).\n- The snooze is also cleared when the incident is reassigned or returns to `Triggered`.",
           "href": "/en/api-reference/on-call/incidents/incident-snooze",
           "metadata": {
             "sidebarTitle": "Snooze incident"
           }
-        }
-      }
-    },
-    "/incident/unack": {
-      "post": {
-        "description": "Remove the acknowledge status from an incident.",
-        "operationId": "incidentUnack",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "incident_ids": [
-                  "69da451ef77b1b51f40e83ee"
-                ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/UnackIncidentRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -43817,6 +45212,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -43824,64 +45222,65 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/SnoozeIncidentRequest"
+              },
+              "example": {
+                "incident_ids": [
+                  "69da451ef77b1b51f40e83ee"
+                ],
+                "minutes": 60
+              }
+            }
+          }
+        }
+      }
+    },
+    "/incident/unack": {
+      "post": {
+        "operationId": "incidentUnack",
         "summary": "Unacknowledge incident",
+        "description": "Withdraw the calling member's acknowledgement of one or more incidents.",
         "tags": [
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Incidents Manage** or **Channels Manage** (`on-call`) |\n\n## Usage\n\n- Only the calling member's acknowledgement is removed. The incident returns to `Triggered`, and any snooze is cleared, only when no other responder still has it acknowledged.\n- Every incident must be in `Processing`; a `Triggered` or `Closed` incident fails the whole call with `InvalidParameter`.",
           "href": "/en/api-reference/on-call/incidents/incident-unack",
           "metadata": {
             "sidebarTitle": "Unacknowledge incident"
           }
-        }
-      }
-    },
-    "/incident/wake": {
-      "post": {
-        "description": "Cancel the snooze on an incident and resume notifications.",
-        "operationId": "incidentWake",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "incident_ids": [
-                  "69da451ef77b1b51f40e83ee"
-                ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/WakeIncidentRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -43889,6 +45288,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -43896,68 +45298,64 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/UnackIncidentRequest"
+              },
+              "example": {
+                "incident_ids": [
+                  "69da451ef77b1b51f40e83ee"
+                ]
+              }
+            }
+          }
+        }
+      }
+    },
+    "/incident/wake": {
+      "post": {
+        "operationId": "incidentWake",
         "summary": "Wake incident",
+        "description": "End the snooze on incidents so that their notifications resume immediately.",
         "tags": [
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Incidents Manage** or **Channels Manage** (`on-call`) |\n\n## Usage\n\n- Incidents whose snooze has already ended are skipped; a closed incident fails the whole call with `InvalidParameter`.",
           "href": "/en/api-reference/on-call/incidents/incident-wake",
           "metadata": {
             "sidebarTitle": "Wake incident"
           }
-        }
-      }
-    },
-    "/incident/war-room/add-member": {
-      "post": {
-        "description": "Add one or more members to the IM war room bound to an incident integration.",
-        "operationId": "incident-write-add-war-room-member",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "chat_id": "oc_5ce6d572455d361153b7cb51da133945",
-                "integration_id": 362,
-                "member_ids": [
-                  20001,
-                  20002
-                ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/AddWarRoomMemberRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": "ok",
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "description": "Returns the literal \"ok\" on success.",
-                          "type": "string"
+                          "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -43965,6 +45363,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -43972,68 +45373,65 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/WakeIncidentRequest"
+              },
+              "example": {
+                "incident_ids": [
+                  "69da451ef77b1b51f40e83ee"
+                ]
+              }
+            }
+          }
+        }
+      }
+    },
+    "/incident/war-room/add-member": {
+      "post": {
+        "operationId": "incident-write-add-war-room-member",
         "summary": "Add war-room member",
+        "description": "Add members to an existing incident war room on Feishu (Lark), DingTalk, WeCom, or Slack.",
         "tags": [
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) or **Channels Manage** (`on-call`) |\n\n## Usage\n\n- Requires the On-call Pro license.\n- `chat_id` must identify a war room created through Flashduty on integration `integration_id`; otherwise the call returns `ResourceNotFound`.\n- Only Feishu (Lark), DingTalk, WeCom and Slack integrations support war rooms; other integrations return `InvalidParameter`.\n- Every ID in `member_ids` must be a person in the account; one unknown ID fails the whole request.\n- On success `data` is the string `ok`.",
           "href": "/en/api-reference/on-call/incidents/incident-write-add-war-room-member",
           "metadata": {
             "sidebarTitle": "Add war-room member"
           }
-        }
-      }
-    },
-    "/incident/war-room/create": {
-      "post": {
-        "description": "Create a war room channel for collaborative incident response.",
-        "operationId": "incidentWarRoomCreate",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "add_observers": true,
-                "incident_id": "69da451ef77b1b51f40e83ee",
-                "integration_id": 2490562293131
-              },
-              "schema": {
-                "$ref": "#/components/schemas/CreateWarRoomRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "chat_id": "oc_a0553eda9014c2de1b3a8f75b4e0c000",
-                    "chat_name": "Incident #0E83EE war room",
-                    "share_link": ""
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/WarRoom"
+                          "type": "string",
+                          "description": "Returns the literal \"ok\" on success."
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": "ok"
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -44041,6 +45439,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -44048,77 +45449,71 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/AddWarRoomMemberRequest"
+              },
+              "example": {
+                "integration_id": 2551105804131,
+                "chat_id": "oc_5ce6d572455d361153b7cb51da133945",
+                "member_ids": [
+                  3790925372131,
+                  5068740052131
+                ]
+              }
+            }
+          }
+        }
+      }
+    },
+    "/incident/war-room/create": {
+      "post": {
+        "operationId": "incidentWarRoomCreate",
         "summary": "Create war room",
+        "description": "Create an IM group chat as the war room for an incident and invite members into it.",
         "tags": [
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Incidents Manage** or **Channels Manage** (`on-call`) |\n\n## Usage\n\n- Requires the Professional edition or higher; otherwise the call fails with `NoLicense`.\n- The IM integration must be enabled with war room turned on. Feishu, DingTalk, WeCom (self-built app only), and Slack are supported.\n- An incident can have only one war room. Calling again with the same `integration_id` returns the existing group (with an empty `share_link`); a different `integration_id` fails with `InvalidParameter`.\n- A concurrent creation for the same incident returns `RequestTooFrequently`.\n- A successful creation adds an `i_wr_create` timeline entry.",
           "href": "/en/api-reference/on-call/incidents/incident-war-room-create",
           "metadata": {
             "sidebarTitle": "Create war room"
           }
-        }
-      }
-    },
-    "/incident/war-room/default-observers": {
-      "post": {
-        "description": "Return historical responders suggested as default observers when opening a war room.",
-        "operationId": "incident-read-get-war-room-default-observers",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "incident_id": "664a1b2c3d4e5f6a7b8c9d0e"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/GetWarRoomDefaultObserversRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "observers": [
-                      {
-                        "account_id": 10001,
-                        "as": "responder",
-                        "avatar": "https://cdn.flashcat.cloud/avatar/20001.png",
-                        "email": "alice@acme.com",
-                        "locale": "zh-CN",
-                        "person_id": 20001,
-                        "person_name": "Alice Chen",
-                        "phone": "+8613800000000",
-                        "status": "active",
-                        "time_zone": "Asia/Shanghai"
-                      }
-                    ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/GetWarRoomDefaultObserversResponse"
+                          "$ref": "#/components/schemas/WarRoom"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "chat_id": "oc_a0553eda9014c2de1b3a8f75b4e0c000",
+                    "chat_name": "Incident #0E83EE war room",
+                    "share_link": ""
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -44126,6 +45521,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -44133,63 +45531,78 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CreateWarRoomRequest"
+              },
+              "example": {
+                "incident_id": "69da451ef77b1b51f40e83ee",
+                "integration_id": 2490562293131,
+                "add_observers": true
+              }
+            }
+          }
+        }
+      }
+    },
+    "/incident/war-room/default-observers": {
+      "post": {
+        "operationId": "incident-read-get-war-room-default-observers",
         "summary": "Get war-room default observers",
+        "description": "Return people assigned to an incident earlier who are no longer responders, as suggested war-room observers.",
         "tags": [
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Requires the On-call Pro license.\n- Observers are people who were assigned to or added as responders on the incident at some point (per its timeline) and are not current responders.\n- An empty `observers` array means there is no such person.\n- Returns `ResourceNotFound` when the incident does not exist.",
           "href": "/en/api-reference/on-call/incidents/incident-read-get-war-room-default-observers",
           "metadata": {
             "sidebarTitle": "Get war-room default observers"
           }
-        }
-      }
-    },
-    "/incident/war-room/delete": {
-      "post": {
-        "description": "Delete an incident war room.",
-        "operationId": "incidentWarRoomDelete",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "incident_id": "69da451ef77b1b51f40e83ee",
-                "integration_id": 2490562293131
-              },
-              "schema": {
-                "$ref": "#/components/schemas/DeleteWarRoomRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/EmptyResponse"
+                          "$ref": "#/components/schemas/GetWarRoomDefaultObserversResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "observers": [
+                      {
+                        "account_id": 2451002751131,
+                        "person_id": 3790925372131,
+                        "person_name": "Alice Chen",
+                        "avatar": "https://example.com/avatars/3790925372131.png",
+                        "email": "alice@example.com",
+                        "locale": "zh-CN",
+                        "time_zone": "Asia/Shanghai",
+                        "as": "member",
+                        "status": "enabled"
+                      }
+                    ]
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -44197,6 +45610,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -44204,67 +45620,61 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/GetWarRoomDefaultObserversRequest"
+              },
+              "example": {
+                "incident_id": "69bb9233331067560c718ecd"
+              }
+            }
+          }
+        }
+      }
+    },
+    "/incident/war-room/delete": {
+      "post": {
+        "operationId": "incidentWarRoomDelete",
         "summary": "Delete war room",
+        "description": "Dissolve an incident's war room group on the IM platform and unlink it from the incident.",
         "tags": [
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Incidents Manage** or **Channels Manage** (`on-call`) |\n\n## Usage\n\n- The war room record is removed first; a failure to dissolve the group on the IM side (for example, it was already dissolved) is ignored.\n- Succeeds without changes when the incident has no war room on that integration.\n- To only unlink a war room whose IM integration is disabled or deleted, set `unlink_only: true` and pass its `chat_id`. This mode is limited to account owners and admins, fails with `InvalidParameter` while the integration is enabled, and does not dissolve the group.\n- On success the response has no `data` field.",
           "href": "/en/api-reference/on-call/incidents/incident-war-room-delete",
           "metadata": {
             "sidebarTitle": "Delete war room"
           }
-        }
-      }
-    },
-    "/incident/war-room/detail": {
-      "post": {
-        "description": "Retrieve the war room configuration and members for an incident.",
-        "operationId": "incidentWarRoomDetail",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "chat_id": "oc_a0553eda9014c2de1b3a8f75b4e0c000",
-                "integration_id": 2490562293131
-              },
-              "schema": {
-                "$ref": "#/components/schemas/GetWarRoomDetailRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "chat_id": "oc_a0553eda9014c2de1b3a8f75b4e0c000",
-                    "chat_name": "Incident #0E83EE war room",
-                    "share_link": ""
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/WarRoom"
+                          "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -44272,6 +45682,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -44279,64 +45692,67 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/DeleteWarRoomRequest"
+              },
+              "example": {
+                "incident_id": "69da451ef77b1b51f40e83ee",
+                "integration_id": 2490562293131
+              }
+            }
+          }
+        }
+      }
+    },
+    "/incident/war-room/detail": {
+      "post": {
+        "operationId": "incidentWarRoomDetail",
         "summary": "Get war room detail",
+        "description": "Fetch the current name and join link of a war room group from the IM platform.",
         "tags": [
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Read** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Read** or **Incidents Manage** or **Channels Read** (`on-call`) |\n\n## Usage\n\n- Supported for Feishu, DingTalk, WeCom, and Slack IM integrations; other integrations fail with `InvalidParameter`.\n- If the IM platform lookup fails (for example, the group was dissolved outside Flashduty), the call still succeeds and every field is an empty string.",
           "href": "/en/api-reference/on-call/incidents/incident-war-room-detail",
           "metadata": {
             "sidebarTitle": "Get war room detail"
           }
-        }
-      }
-    },
-    "/incident/war-room/list": {
-      "post": {
-        "description": "List all war rooms associated with an incident.",
-        "operationId": "incidentWarRoomList",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "incident_id": "69da451ef77b1b51f40e83ee"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ListWarRoomsRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "items": []
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/ListWarRoomsResponse"
+                          "$ref": "#/components/schemas/WarRoom"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "chat_id": "oc_a0553eda9014c2de1b3a8f75b4e0c000",
+                    "chat_name": "Incident #0E83EE war room",
+                    "share_link": ""
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -44344,6 +45760,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -44351,107 +45770,77 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/GetWarRoomDetailRequest"
+              },
+              "example": {
+                "integration_id": 2490562293131,
+                "chat_id": "oc_a0553eda9014c2de1b3a8f75b4e0c000"
+              }
+            }
+          }
+        }
+      }
+    },
+    "/incident/war-room/list": {
+      "post": {
+        "operationId": "incidentWarRoomList",
         "summary": "List war rooms",
+        "description": "List the IM war room groups linked to an incident.",
         "tags": [
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Read** (`on-call`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Read** or **Incidents Manage** or **Channels Read** or **Channels Manage** (`on-call`) |\n\n## Usage\n\n- War rooms whose IM integration is disabled or deleted are still returned, with `integration_unavailable` set to `true`.\n- Use `chat_id` and `integration_id` with `POST /incident/war-room/detail` to read the group's current name and join link.",
           "href": "/en/api-reference/on-call/incidents/incident-war-room-list",
           "metadata": {
             "sidebarTitle": "List war rooms"
           }
-        }
-      }
-    },
-    "/incident/work-item/assignees/reset": {
-      "post": {
-        "description": "Replace a work item's entire assignee set.",
-        "operationId": "incidentWorkItemResetAssignees",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "assignee_ids": [
-                  3790925372131,
-                  5068740052131
-                ],
-                "version": 2,
-                "work_item_id": "wi_9fK2mNqRtVwXyZaBcDeFgH"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ResetWorkItemAssigneesRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "added_assignee_ids": [
-                      5068740052131
-                    ],
-                    "item": {
-                      "assignee_ids": [
-                        3790925372131,
-                        4756301322131,
-                        5068740052131
-                      ],
-                      "assignees": [
-                        {
-                          "id": 3790925372131,
-                          "type": "person"
-                        },
-                        {
-                          "id": 4756301322131,
-                          "type": "person"
-                        },
-                        {
-                          "id": 5068740052131,
-                          "type": "person"
-                        }
-                      ],
-                      "created_at_seconds": 1785495329,
-                      "created_by": 5329873302131,
-                      "incident_id": "6a5f1e28807515413b384bce",
-                      "item_type": "follow_up",
-                      "post_mortem_id": "51d65cd9525c369379ba471b5512df63",
-                      "source_kind": "native",
-                      "status": "done",
-                      "title": "Follow-ups assigned to Bowen and Weili",
-                      "updated_at_seconds": 1785496384,
-                      "updated_by": 3790925372131,
-                      "version": 2,
-                      "work_item_id": "wi_68MHnkWBiyjrh6uhkxUyiZ"
-                    },
-                    "removed_assignee_ids": [
-                      4756301322131
-                    ]
-                  },
-                  "request_id": "01J8XQ3E5Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/WorkItemMutationResult"
+                          "$ref": "#/components/schemas/ListWarRoomsResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "items": [
+                      {
+                        "account_id": 2451002751131,
+                        "integration_id": 2490562293131,
+                        "created_by": 2476444212131,
+                        "chat_id": "oc_a0553eda9014c2de1b3a8f75b4e0c000",
+                        "incident_id": "69da451ef77b1b51f40e83ee",
+                        "status": "enabled",
+                        "created_at": 1775972300,
+                        "plugin_type": "feishu_app",
+                        "chat_name": "Incident #0E83EE war room"
+                      }
+                    ]
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -44459,6 +45848,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -44466,99 +45858,198 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ListWarRoomsRequest"
+              },
+              "example": {
+                "incident_id": "69da451ef77b1b51f40e83ee"
+              }
+            }
+          }
+        }
+      }
+    },
+    "/incident/work-item/assignees/reset": {
+      "post": {
+        "operationId": "incidentWorkItemResetAssignees",
         "summary": "Reset work item assignees",
+        "description": "Replace a work item's entire assignee set.",
         "tags": [
           "On-call/Incidents"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |\n\n## Usage\n\n- Requires the On-call Pro license.\n- Full replacement of the assignee set — an empty array clears all assignees.\n- Set either `assignees` or the legacy `assignee_ids`, not both (sending both returns an error). An `ai_sre` entry omits `id`.\n- Only newly added assignees are notified; removals never notify.\n- Audited — changes are recorded in the audit log.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Requires the On-call Pro license.\n- Full replacement of the assignee set. Send `assignees` or the legacy `assignee_ids` (not both); omitting both returns an error, and `[]` or `null` clears all assignees.\n- Person assignees must be active members who can already read the incident or post-mortem — assignment never grants access.\n- Only newly added person assignees are notified; removals never notify. Newly adding `ai_sre` starts an AI SRE session for the item.\n- When the set does not change, `version` is not incremented.\n- Optimistic locking — `version` must equal the item's current version; a mismatch returns `RequestLocked` (HTTP 423). Re-read the item and retry.\n- The caller needs edit access to the item's anchor: the post-mortem when the item is bound to one, otherwise the incident.\n- A `follow_up` item can be changed only while its incident is closed.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/on-call/incidents/incident-work-item-reset-assignees",
           "metadata": {
             "sidebarTitle": "Reset work item assignees"
           }
-        }
-      }
-    },
-    "/incident/work-item/complete": {
-      "post": {
-        "description": "Mark a work item as completed by setting a client-defined target status.",
-        "operationId": "incidentWorkItemComplete",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "idempotency_key": "complete-wi-20260731-0001",
-                "target_status": "done",
-                "version": 2,
-                "work_item_id": "wi_9fK2mNqRtVwXyZaBcDeFgH"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/CompleteWorkItemRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/WorkItemMutationResult"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01J8XQ3E5Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "item": {
+                      "work_item_id": "wi_9fK2mNqRtVwXyZaBcDeFgH",
+                      "item_type": "action",
+                      "incident_id": "6a5f1e28807515413b384bce",
+                      "title": "Roll back the v2.14 deployment on web-server-01 and web-server-02",
+                      "description": "CPU saturation started right after the v2.14 rollout; roll back and watch the error rate.",
+                      "status": "in_progress",
+                      "priority": "high",
+                      "source_kind": "native",
+                      "version": 3,
                       "assignee_ids": [
                         3790925372131,
-                        4756301322131,
                         5068740052131
                       ],
                       "assignees": [
                         {
-                          "id": 3790925372131,
-                          "type": "person"
-                        },
-                        {
-                          "id": 4756301322131,
-                          "type": "person"
+                          "type": "person",
+                          "id": 3790925372131
                         },
                         {
-                          "id": 5068740052131,
-                          "type": "person"
+                          "type": "person",
+                          "id": 5068740052131
                         }
                       ],
-                      "created_at_seconds": 1785495329,
-                      "created_by": 5329873302131,
-                      "incident_id": "6a5f1e28807515413b384bce",
-                      "item_type": "follow_up",
-                      "post_mortem_id": "51d65cd9525c369379ba471b5512df63",
-                      "source_kind": "native",
-                      "status": "done",
-                      "title": "Follow-ups assigned to Bowen and Weili",
-                      "updated_at_seconds": 1785496384,
+                      "created_by": 3790925372131,
                       "updated_by": 3790925372131,
-                      "version": 2,
-                      "work_item_id": "wi_68MHnkWBiyjrh6uhkxUyiZ"
-                    }
-                  },
-                  "request_id": "01J8XQ3E5Z7JM2NTFQ5YJ8P9R4"
-                },
+                      "created_at_seconds": 1785496400,
+                      "updated_at_seconds": 1785497000
+                    },
+                    "added_assignee_ids": [
+                      5068740052131
+                    ]
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "429": {
+            "$ref": "#/components/responses/TooManyRequests"
+          },
+          "500": {
+            "$ref": "#/components/responses/ServerError"
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ResetWorkItemAssigneesRequest"
+              },
+              "example": {
+                "work_item_id": "wi_9fK2mNqRtVwXyZaBcDeFgH",
+                "version": 2,
+                "assignee_ids": [
+                  3790925372131,
+                  5068740052131
+                ]
+              }
+            }
+          }
+        }
+      }
+    },
+    "/incident/work-item/complete": {
+      "post": {
+        "operationId": "incidentWorkItemComplete",
+        "summary": "Complete a work item",
+        "description": "Mark a work item as done; only its current assignees can do this.",
+        "tags": [
+          "On-call/Incidents"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Requires the On-call Pro license.\n- `target_status` must be `done`.\n- Only a current person assignee can complete the item (account owners and admins are not implicit assignees); an item assigned to AI SRE can also be completed by the AI SRE session working on it. The caller also needs read access to the incident or post-mortem.\n- A `follow_up` item can be changed only while its incident is closed.\n- Repeating the call with the same `idempotency_key` returns the item with `idempotent_replay: true`.\n- Optimistic locking — `version` must equal the item's current version; a mismatch returns `RequestLocked` (HTTP 423). Re-read the item and retry.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "href": "/en/api-reference/on-call/incidents/incident-work-item-complete",
+          "metadata": {
+            "sidebarTitle": "Complete a work item"
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/WorkItemMutationResult"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01J8XQ3E5Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "item": {
+                      "work_item_id": "wi_9fK2mNqRtVwXyZaBcDeFgH",
+                      "item_type": "action",
+                      "incident_id": "6a5f1e28807515413b384bce",
+                      "title": "Roll back the v2.14 deployment on web-server-01 and web-server-02",
+                      "description": "CPU saturation started right after the v2.14 rollout; roll back and watch the error rate.",
+                      "status": "done",
+                      "priority": "high",
+                      "source_kind": "native",
+                      "version": 3,
+                      "assignee_ids": [
+                        3790925372131
+                      ],
+                      "assignees": [
+                        {
+                          "type": "person",
+                          "id": 3790925372131
+                        }
+                      ],
+                      "created_by": 3790925372131,
+                      "updated_by": 3790925372131,
+                      "created_at_seconds": 1785496400,
+                      "updated_at_seconds": 1785497600
+                    }
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -44566,6 +46057,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -44573,99 +46067,93 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Complete a work item",
-        "tags": [
-          "On-call/Incidents"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |\n\n## Usage\n\n- Requires the On-call Pro license.\n- Only current assignees can complete a work item.\n- `target_status` is a client-defined string — there is no fixed state machine.\n- The same `idempotency_key` with the same `target_status` replays idempotently; the same key with a different `target_status` returns an error.\n- Audited — changes are recorded in the audit log.",
-          "href": "/en/api-reference/on-call/incidents/incident-work-item-complete",
-          "metadata": {
-            "sidebarTitle": "Complete a work item"
-          }
-        }
-      }
-    },
-    "/incident/work-item/convert": {
-      "post": {
-        "description": "Convert an incident action item into a post-mortem follow-up in place.",
-        "operationId": "incidentWorkItemConvert",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CompleteWorkItemRequest"
+              },
               "example": {
-                "idempotency_key": "convert-wi-20260731-0001",
-                "target_status": "open",
+                "work_item_id": "wi_9fK2mNqRtVwXyZaBcDeFgH",
                 "version": 2,
-                "work_item_id": "wi_9fK2mNqRtVwXyZaBcDeFgH"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ConvertWorkItemRequest"
+                "target_status": "done",
+                "idempotency_key": "complete-wi-20260731-0001"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/incident/work-item/convert": {
+      "post": {
+        "operationId": "incidentWorkItemConvert",
+        "summary": "Convert a work item to a follow-up",
+        "description": "Convert an incident action item into a post-mortem follow-up in place.",
+        "tags": [
+          "On-call/Incidents"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Requires the On-call Pro license.\n- Converts an `action` into a post-mortem `follow_up` in place — the `work_item_id` does not change.\n- Converting an item that is already a `follow_up` changes nothing and returns `idempotent_replay: true`.\n- If the incident already has a post-mortem, the item is bound to it, which requires edit access to that report; otherwise bind it later with `POST /incident/work-item/post-mortem/bind`.\n- The caller needs edit access to the item's anchor: the post-mortem when the item is bound to one, otherwise the incident.\n- Optimistic locking — `version` must equal the item's current version; a mismatch returns `RequestLocked` (HTTP 423). Re-read the item and retry.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "href": "/en/api-reference/on-call/incidents/incident-work-item-convert",
+          "metadata": {
+            "sidebarTitle": "Convert a work item to a follow-up"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "item": {
-                      "assignee_ids": [
-                        3790925372131,
-                        4756301322131,
-                        5068740052131
-                      ],
-                      "assignees": [
-                        {
-                          "id": 3790925372131,
-                          "type": "person"
-                        },
-                        {
-                          "id": 4756301322131,
-                          "type": "person"
-                        },
-                        {
-                          "id": 5068740052131,
-                          "type": "person"
-                        }
-                      ],
-                      "created_at_seconds": 1785495329,
-                      "created_by": 5329873302131,
-                      "incident_id": "6a5f1e28807515413b384bce",
-                      "item_type": "follow_up",
-                      "post_mortem_id": "51d65cd9525c369379ba471b5512df63",
-                      "source_kind": "native",
-                      "status": "done",
-                      "title": "Follow-ups assigned to Bowen and Weili",
-                      "updated_at_seconds": 1785496384,
-                      "updated_by": 3790925372131,
-                      "version": 2,
-                      "work_item_id": "wi_68MHnkWBiyjrh6uhkxUyiZ"
-                    }
-                  },
-                  "request_id": "01J8XQ3E5Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/WorkItemMutationResult"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01J8XQ3E5Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "item": {
+                      "work_item_id": "wi_9fK2mNqRtVwXyZaBcDeFgH",
+                      "item_type": "follow_up",
+                      "incident_id": "6a5f1e28807515413b384bce",
+                      "post_mortem_id": "51d65cd9525c369379ba471b5512df63",
+                      "title": "Roll back the v2.14 deployment on web-server-01 and web-server-02",
+                      "description": "CPU saturation started right after the v2.14 rollout; roll back and watch the error rate.",
+                      "status": "open",
+                      "priority": "high",
+                      "source_kind": "native",
+                      "version": 3,
+                      "assignee_ids": [
+                        3790925372131
+                      ],
+                      "assignees": [
+                        {
+                          "type": "person",
+                          "id": 3790925372131
+                        }
+                      ],
+                      "created_by": 3790925372131,
+                      "updated_by": 3790925372131,
+                      "converted_by": 3790925372131,
+                      "converted_at_seconds": 1785497600,
+                      "created_at_seconds": 1785496400,
+                      "updated_at_seconds": 1785497600
+                    }
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -44673,6 +46161,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -44680,97 +46171,93 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Convert a work item to a follow-up",
-        "tags": [
-          "On-call/Incidents"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |\n\n## Usage\n\n- Requires the On-call Pro license.\n- Converts an `action` item into a post-mortem `follow_up` in place — the `work_item_id` does not change.\n- Converting an item that is already a `follow_up` returns `idempotent_replay: true`.\n- If a post-mortem already exists for the incident, the converted item auto-binds to it.\n- Audited — changes are recorded in the audit log.",
-          "href": "/en/api-reference/on-call/incidents/incident-work-item-convert",
-          "metadata": {
-            "sidebarTitle": "Convert a work item to a follow-up"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ConvertWorkItemRequest"
+              },
+              "example": {
+                "work_item_id": "wi_9fK2mNqRtVwXyZaBcDeFgH",
+                "version": 2,
+                "target_status": "open",
+                "idempotency_key": "convert-wi-20260731-0001"
+              }
+            }
           }
         }
       }
     },
     "/incident/work-item/create": {
       "post": {
-        "description": "Create an action on an active incident or a follow-up on one of its post-mortems.",
         "operationId": "incidentWorkItemCreate",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "assignee_ids": [
-                  3790925372131
-                ],
-                "description": "CPU saturation started right after the v2.14 rollout; roll back and watch the error rate.",
-                "idempotency_key": "create-wi-20260731-0001",
-                "incident_id": "6a5f1e28807515413b384bce",
-                "item_type": "action",
-                "priority": "high",
-                "status": "open",
-                "title": "Roll back the v2.14 deployment on web-server-01"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/CreateWorkItemRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "Create a work item",
+        "description": "Create an action on an open incident, or a follow-up on a closed incident.",
+        "tags": [
+          "On-call/Incidents"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Requires the On-call Pro license.\n- `action`: the incident must not be closed, the caller needs edit access to it, and `post_mortem_id` must be empty.\n- `follow_up`: the incident must be closed. With `post_mortem_id`, the caller needs edit access to that report and the incident must be linked to it. Without it, the caller needs edit access to the incident, and the server binds the incident's post-mortem if one exists; otherwise the item stays unbound until a report is created.\n- Set either `assignees` (entries `{type, id?}`; `type` is `person` or `ai_sre`, and an `ai_sre` entry omits `id`) or the legacy `assignee_ids` (all `person`), not both — sending both returns an error.\n- Person assignees must be active members who can already read the incident or post-mortem — assignment never grants access.\n- Newly added person assignees are notified; assigning `ai_sre` starts an AI SRE session that works on the item.\n- Retrying with the same `idempotency_key` from the same caller returns the original item with `idempotent_replay: true`; if that item was deleted, the call returns `RequestLocked`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "href": "/en/api-reference/on-call/incidents/incident-work-item-create",
+          "metadata": {
+            "sidebarTitle": "Create a work item"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/WorkItemCreateResult"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01J8XQ3E5Z7JM2NTFQ5YJ8P9R4",
                   "data": {
-                    "added_assignee_ids": [
-                      3790925372131
-                    ],
                     "item": {
+                      "work_item_id": "wi_9fK2mNqRtVwXyZaBcDeFgH",
+                      "item_type": "action",
+                      "incident_id": "6a5f1e28807515413b384bce",
+                      "title": "Roll back the v2.14 deployment on web-server-01",
+                      "description": "CPU saturation started right after the v2.14 rollout; roll back and watch the error rate.",
+                      "status": "open",
+                      "priority": "high",
+                      "source_kind": "native",
+                      "version": 1,
                       "assignee_ids": [
                         3790925372131
                       ],
                       "assignees": [
                         {
-                          "id": 3790925372131,
-                          "type": "person"
+                          "type": "person",
+                          "id": 3790925372131
                         }
                       ],
-                      "created_at_seconds": 1785496400,
                       "created_by": 3790925372131,
-                      "incident_id": "6a5f1e28807515413b384bce",
-                      "item_type": "action",
-                      "source_kind": "native",
-                      "status": "open",
-                      "title": "Roll back the v2.14 deployment on web-server-01",
-                      "updated_at_seconds": 1785496400,
                       "updated_by": 3790925372131,
-                      "version": 1,
-                      "work_item_id": "wi_9fK2mNqRtVwXyZaBcDeFgH"
-                    }
-                  },
-                  "request_id": "01J8XQ3E5Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
+                      "created_at_seconds": 1785496400,
+                      "updated_at_seconds": 1785496400
                     },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/WorkItemCreateResult"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                    "added_assignee_ids": [
+                      3790925372131
+                    ]
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -44778,6 +46265,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -44785,63 +46275,71 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Create a work item",
-        "tags": [
-          "On-call/Incidents"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |\n\n## Usage\n\n- Requires the On-call Pro license.\n- An `action` anchors to an active incident and must NOT set `post_mortem_id`; a `follow_up` REQUIRES the `post_mortem_id` of a post-mortem linked to `incident_id`.\n- Set either `assignees` or the legacy `assignee_ids`, not both. `assignees` entries are `{type, id?}` with `type` `person` or `ai_sre`; an `ai_sre` entry omits `id`. `assignee_ids` is equivalent to an all-`person` list. Sending both returns an error.\n- Person assignees must be active members who can already read the anchor incident or post-mortem — assignment never grants access.\n- Newly added assignees are notified.\n- Retrying with the same (`creator`, `idempotency_key`) replays the original item with `idempotent_replay: true` instead of creating a duplicate.\n- Audited — changes are recorded in the audit log.",
-          "href": "/en/api-reference/on-call/incidents/incident-work-item-create",
-          "metadata": {
-            "sidebarTitle": "Create a work item"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CreateWorkItemRequest"
+              },
+              "example": {
+                "item_type": "action",
+                "title": "Roll back the v2.14 deployment on web-server-01",
+                "description": "CPU saturation started right after the v2.14 rollout; roll back and watch the error rate.",
+                "status": "open",
+                "priority": "high",
+                "incident_id": "6a5f1e28807515413b384bce",
+                "assignee_ids": [
+                  3790925372131
+                ],
+                "idempotency_key": "create-wi-20260731-0001"
+              }
+            }
           }
         }
       }
     },
     "/incident/work-item/delete": {
       "post": {
-        "description": "Soft-delete a work item.",
         "operationId": "incidentWorkItemDelete",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "version": 2,
-                "work_item_id": "wi_9fK2mNqRtVwXyZaBcDeFgH"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/DeleteWorkItemRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "Delete a work item",
+        "description": "Soft-delete a work item so it no longer appears in work item lists.",
+        "tags": [
+          "On-call/Incidents"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Requires the On-call Pro license.\n- Soft delete — the item no longer appears in listings but is retained; its create `idempotency_key` cannot be reused.\n- Optimistic locking — `version` must equal the item's current version; a mismatch returns `RequestLocked` (HTTP 423). Re-read the item and retry.\n- The caller needs edit access to the item's anchor: the post-mortem when the item is bound to one, otherwise the incident.\n- A `follow_up` item can be changed only while its incident is closed.\n- On success `data` is an empty object.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "href": "/en/api-reference/on-call/incidents/incident-work-item-delete",
+          "metadata": {
+            "sidebarTitle": "Delete a work item"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01J8XQ3E5Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/WorkItemMutationResult"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01J8XQ3E5Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -44849,6 +46347,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -44856,124 +46357,125 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Delete a work item",
-        "tags": [
-          "On-call/Incidents"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |\n\n## Usage\n\n- Requires the On-call Pro license.\n- Soft delete — the item no longer appears in listings but is retained.\n- Optimistic locking — `version` must match the item's current version; a mismatch returns a conflict error.\n- Audited — changes are recorded in the audit log.",
-          "href": "/en/api-reference/on-call/incidents/incident-work-item-delete",
-          "metadata": {
-            "sidebarTitle": "Delete a work item"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/DeleteWorkItemRequest"
+              },
+              "example": {
+                "work_item_id": "wi_9fK2mNqRtVwXyZaBcDeFgH",
+                "version": 3
+              }
+            }
           }
         }
       }
     },
     "/incident/work-item/list": {
       "post": {
-        "description": "List incident work items (actions and post-mortem follow-ups) with cursor pagination.",
         "operationId": "incidentWorkItemList",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "incident_id": "6a5f1e28807515413b384bce",
-                "limit": 50
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ListWorkItemRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "List work items",
+        "description": "List incident work items (actions and post-mortem follow-ups) with cursor pagination.",
+        "tags": [
+          "On-call/Incidents"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- At least one of `incident_id`, `post_mortem_id`, `assignee_id`, or `assignee_type` = `ai_sre` is required.\n- Filtering by `incident_id` or `post_mortem_id` requires read access to that incident or report; listing by `incident_id` also includes follow-ups bound to the incident's post-mortem when the caller can read it.\n- Listing by `assignee_id` alone requires being that member or an account owner or admin. Without `incident_id` and `post_mortem_id`, callers who are not owner or admin see only items whose incident or report they can read.\n- Sorted by `updated_at_seconds` descending. Pass the previous response's `next_cursor` as `cursor` until `has_more` is false.",
+          "href": "/en/api-reference/on-call/incidents/incident-work-item-list",
+          "metadata": {
+            "sidebarTitle": "List work items"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/WorkItemListResult"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01J8XQ3E5Z7JM2NTFQ5YJ8P9R4",
                   "data": {
-                    "has_more": true,
                     "items": [
                       {
+                        "work_item_id": "wi_68MHnkWBiyjrh6uhkxUyiZ",
+                        "item_type": "follow_up",
+                        "incident_id": "6a5f1e28807515413b384bce",
+                        "post_mortem_id": "51d65cd9525c369379ba471b5512df63",
+                        "title": "Add a saturation alert for the orders database pool",
+                        "status": "done",
+                        "priority": "medium",
+                        "source_kind": "native",
+                        "version": 3,
                         "assignee_ids": [
                           3790925372131,
-                          4756301322131,
                           5068740052131
                         ],
                         "assignees": [
                           {
-                            "id": 3790925372131,
-                            "type": "person"
-                          },
-                          {
-                            "id": 4756301322131,
-                            "type": "person"
+                            "type": "person",
+                            "id": 3790925372131
                           },
                           {
-                            "id": 5068740052131,
-                            "type": "person"
+                            "type": "person",
+                            "id": 5068740052131
                           }
                         ],
+                        "created_by": 4756301322131,
+                        "updated_by": 3790925372131,
+                        "converted_by": 4756301322131,
+                        "converted_at_seconds": 1785495900,
                         "created_at_seconds": 1785495329,
-                        "created_by": 5329873302131,
-                        "incident_id": "6a5f1e28807515413b384bce",
+                        "updated_at_seconds": 1785496384
+                      },
+                      {
+                        "work_item_id": "wi_dMRYTeZHivE5vf87PQEeFX",
                         "item_type": "follow_up",
+                        "incident_id": "6a5f1e28807515413b384bce",
                         "post_mortem_id": "51d65cd9525c369379ba471b5512df63",
+                        "title": "Document the cache TTL rollback procedure",
+                        "status": "open",
+                        "priority": "low",
                         "source_kind": "native",
-                        "status": "done",
-                        "title": "Follow-ups assigned to Bowen and Weili",
-                        "updated_at_seconds": 1785496384,
-                        "updated_by": 3790925372131,
                         "version": 2,
-                        "work_item_id": "wi_68MHnkWBiyjrh6uhkxUyiZ"
-                      },
-                      {
                         "assignee_ids": [
                           5068740052131
                         ],
                         "assignees": [
                           {
-                            "id": 5068740052131,
-                            "type": "person"
+                            "type": "person",
+                            "id": 5068740052131
                           }
                         ],
-                        "created_at_seconds": 1785495164,
                         "created_by": 3790925372131,
-                        "incident_id": "6a5f1e28807515413b384bce",
-                        "item_type": "follow_up",
-                        "post_mortem_id": "51d65cd9525c369379ba471b5512df63",
-                        "source_kind": "native",
-                        "status": "open",
-                        "title": "Check whether this to-do notifies Bowen",
-                        "updated_at_seconds": 1785495164,
                         "updated_by": 3790925372131,
-                        "version": 1,
-                        "work_item_id": "wi_dMRYTeZHivE5vf87PQEeFX"
+                        "converted_by": 3790925372131,
+                        "converted_at_seconds": 1785495200,
+                        "created_at_seconds": 1785495164,
+                        "updated_at_seconds": 1785495200
                       }
                     ],
-                    "next_cursor": "MTc4NTQ5NTE2NHx3aV9kTVJZVGVaSGl2RTV2Zjg3UFFFZUZY"
-                  },
-                  "request_id": "01J8XQ3E5Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/WorkItemListResult"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                    "next_cursor": "MTc4NTQ5NTIwMHx3aV9kTVJZVGVaSGl2RTV2Zjg3UFFFZUZY",
+                    "has_more": true
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -44981,6 +46483,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -44988,124 +46493,124 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "List work items",
-        "tags": [
-          "On-call/Incidents"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Read** (`on-call`) |\n\n## Usage\n\n- At least one of `incident_id`, `post_mortem_id`, `assignee_id`, or `assignee_type` = `ai_sre` is required.\n- `assignee_type` = `ai_sre` lists items assigned to AI SRE and can be used on its own.\n- Cursor pagination sorted by `updated_at_seconds` descending — pass the previous response's `next_cursor` as `cursor` until `has_more` is false.\n- Listing by `incident_id` also includes follow-ups anchored on the incident's post-mortem.\n- Listing by `assignee_id` alone requires being that assignee or an account admin.",
-          "href": "/en/api-reference/on-call/incidents/incident-work-item-list",
-          "metadata": {
-            "sidebarTitle": "List work items"
-          }
-        }
-      }
-    },
-    "/incident/work-item/post-mortem/bind": {
-      "post": {
-        "description": "Bulk-bind an incident's converted-but-unbound follow-ups to a post-mortem.",
-        "operationId": "incidentWorkItemBindPostMortem",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ListWorkItemRequest"
+              },
               "example": {
-                "idempotency_key": "bind-wi-20260731-0001",
                 "incident_id": "6a5f1e28807515413b384bce",
-                "post_mortem_id": "51d65cd9525c369379ba471b5512df63"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/BindWorkItemPostMortemRequest"
+                "limit": 2
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/incident/work-item/post-mortem/bind": {
+      "post": {
+        "operationId": "incidentWorkItemBindPostMortem",
+        "summary": "Bind work items to a post-mortem",
+        "description": "Bulk-bind an incident's converted-but-unbound follow-ups to a post-mortem.",
+        "tags": [
+          "On-call/Incidents"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Requires the On-call Pro license.\n- Binds every item of the incident that was converted from an action and is not yet bound to any post-mortem.\n- The caller needs edit access to the post-mortem, and `incident_id` must be linked to it.\n- `items` holds the items bound by this call and may be empty; `next_cursor` is not set and `has_more` is false.\n- Retrying with the same `idempotency_key` returns the items bound earlier with `idempotent_replay: true`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "href": "/en/api-reference/on-call/incidents/incident-work-item-bind-post-mortem",
+          "metadata": {
+            "sidebarTitle": "Bind work items to a post-mortem"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/WorkItemListResult"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01J8XQ3E5Z7JM2NTFQ5YJ8P9R4",
                   "data": {
-                    "has_more": false,
                     "items": [
                       {
+                        "work_item_id": "wi_68MHnkWBiyjrh6uhkxUyiZ",
+                        "item_type": "follow_up",
+                        "incident_id": "6a5f1e28807515413b384bce",
+                        "post_mortem_id": "51d65cd9525c369379ba471b5512df63",
+                        "title": "Add a saturation alert for the orders database pool",
+                        "status": "done",
+                        "priority": "medium",
+                        "source_kind": "native",
+                        "version": 3,
                         "assignee_ids": [
                           3790925372131,
-                          4756301322131,
                           5068740052131
                         ],
                         "assignees": [
                           {
-                            "id": 3790925372131,
-                            "type": "person"
-                          },
-                          {
-                            "id": 4756301322131,
-                            "type": "person"
+                            "type": "person",
+                            "id": 3790925372131
                           },
                           {
-                            "id": 5068740052131,
-                            "type": "person"
+                            "type": "person",
+                            "id": 5068740052131
                           }
                         ],
+                        "created_by": 4756301322131,
+                        "updated_by": 3790925372131,
+                        "converted_by": 4756301322131,
+                        "converted_at_seconds": 1785495900,
                         "created_at_seconds": 1785495329,
-                        "created_by": 5329873302131,
-                        "incident_id": "6a5f1e28807515413b384bce",
+                        "updated_at_seconds": 1785496384
+                      },
+                      {
+                        "work_item_id": "wi_dMRYTeZHivE5vf87PQEeFX",
                         "item_type": "follow_up",
+                        "incident_id": "6a5f1e28807515413b384bce",
                         "post_mortem_id": "51d65cd9525c369379ba471b5512df63",
+                        "title": "Document the cache TTL rollback procedure",
+                        "status": "open",
+                        "priority": "low",
                         "source_kind": "native",
-                        "status": "done",
-                        "title": "Follow-ups assigned to Bowen and Weili",
-                        "updated_at_seconds": 1785496384,
-                        "updated_by": 3790925372131,
                         "version": 2,
-                        "work_item_id": "wi_68MHnkWBiyjrh6uhkxUyiZ"
-                      },
-                      {
                         "assignee_ids": [
                           5068740052131
                         ],
                         "assignees": [
                           {
-                            "id": 5068740052131,
-                            "type": "person"
+                            "type": "person",
+                            "id": 5068740052131
                           }
                         ],
-                        "created_at_seconds": 1785495164,
                         "created_by": 3790925372131,
-                        "incident_id": "6a5f1e28807515413b384bce",
-                        "item_type": "follow_up",
-                        "post_mortem_id": "51d65cd9525c369379ba471b5512df63",
-                        "source_kind": "native",
-                        "status": "open",
-                        "title": "Check whether this to-do notifies Bowen",
-                        "updated_at_seconds": 1785495164,
                         "updated_by": 3790925372131,
-                        "version": 1,
-                        "work_item_id": "wi_dMRYTeZHivE5vf87PQEeFX"
+                        "converted_by": 3790925372131,
+                        "converted_at_seconds": 1785495200,
+                        "created_at_seconds": 1785495164,
+                        "updated_at_seconds": 1785495200
                       }
-                    ]
-                  },
-                  "request_id": "01J8XQ3E5Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/WorkItemListResult"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                    ],
+                    "has_more": false
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -45113,6 +46618,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -45120,99 +46628,89 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Bind work items to a post-mortem",
-        "tags": [
-          "On-call/Incidents"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |\n\n## Usage\n\n- Requires the On-call Pro license.\n- Binds ALL of the incident's converted-but-unbound follow-ups to the given post-mortem in one call.\n- `items` holds the newly bound batch; `next_cursor` and `has_more` are not set.\n- Idempotent by `idempotency_key` — retrying with the same key replays the original result.\n- Audited — changes are recorded in the audit log.",
-          "href": "/en/api-reference/on-call/incidents/incident-work-item-bind-post-mortem",
-          "metadata": {
-            "sidebarTitle": "Bind work items to a post-mortem"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/BindWorkItemPostMortemRequest"
+              },
+              "example": {
+                "post_mortem_id": "51d65cd9525c369379ba471b5512df63",
+                "incident_id": "6a5f1e28807515413b384bce",
+                "idempotency_key": "bind-wi-20260731-0001"
+              }
+            }
           }
         }
       }
     },
     "/incident/work-item/update": {
       "post": {
-        "description": "Partially update a work item's title, description, status, or priority.",
         "operationId": "incidentWorkItemUpdate",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "status": "in_progress",
-                "title": "Roll back the v2.14 deployment on web-server-01 and web-server-02",
-                "version": 1,
-                "work_item_id": "wi_9fK2mNqRtVwXyZaBcDeFgH"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/UpdateWorkItemRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "Update a work item",
+        "description": "Partially update a work item's title, description, status, or priority.",
+        "tags": [
+          "On-call/Incidents"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Requires the On-call Pro license.\n- Partial patch: omitted fields and fields sent as `null` stay unchanged. Send `\"\"` to clear `description` or `priority`; `title` and `status` cannot be empty.\n- Optimistic locking — `version` must equal the item's current version; a mismatch returns `RequestLocked` (HTTP 423). Re-read the item and retry.\n- When nothing would change, the current item is returned without checking `version` and without incrementing it.\n- The caller needs edit access to the item's anchor: the post-mortem when the item is bound to one, otherwise the incident.\n- A `follow_up` item can be changed only while its incident is closed.\n- Assignees, `item_type`, and the incident/post-mortem anchors cannot be changed here — use the dedicated endpoints.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "href": "/en/api-reference/on-call/incidents/incident-work-item-update",
+          "metadata": {
+            "sidebarTitle": "Update a work item"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
-              "application/json": {
-                "example": {
-                  "data": {
-                    "item": {
-                      "assignee_ids": [
-                        3790925372131,
-                        4756301322131,
-                        5068740052131
-                      ],
-                      "assignees": [
-                        {
-                          "id": 3790925372131,
-                          "type": "person"
-                        },
-                        {
-                          "id": 4756301322131,
-                          "type": "person"
-                        },
-                        {
-                          "id": 5068740052131,
-                          "type": "person"
-                        }
-                      ],
-                      "created_at_seconds": 1785495329,
-                      "created_by": 5329873302131,
-                      "incident_id": "6a5f1e28807515413b384bce",
-                      "item_type": "follow_up",
-                      "post_mortem_id": "51d65cd9525c369379ba471b5512df63",
-                      "source_kind": "native",
-                      "status": "done",
-                      "title": "Follow-ups assigned to Bowen and Weili",
-                      "updated_at_seconds": 1785496384,
-                      "updated_by": 3790925372131,
-                      "version": 2,
-                      "work_item_id": "wi_68MHnkWBiyjrh6uhkxUyiZ"
-                    }
-                  },
-                  "request_id": "01J8XQ3E5Z7JM2NTFQ5YJ8P9R4"
-                },
+              "application/json": {
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/WorkItemMutationResult"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01J8XQ3E5Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "item": {
+                      "work_item_id": "wi_9fK2mNqRtVwXyZaBcDeFgH",
+                      "item_type": "action",
+                      "incident_id": "6a5f1e28807515413b384bce",
+                      "title": "Roll back the v2.14 deployment on web-server-01 and web-server-02",
+                      "description": "CPU saturation started right after the v2.14 rollout; roll back and watch the error rate.",
+                      "status": "in_progress",
+                      "priority": "high",
+                      "source_kind": "native",
+                      "version": 2,
+                      "assignee_ids": [
+                        3790925372131
+                      ],
+                      "assignees": [
+                        {
+                          "type": "person",
+                          "id": 3790925372131
+                        }
+                      ],
+                      "created_by": 3790925372131,
+                      "updated_by": 3790925372131,
+                      "created_at_seconds": 1785496400,
+                      "updated_at_seconds": 1785496700
+                    }
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -45220,6 +46718,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -45227,95 +46728,92 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Update a work item",
-        "tags": [
-          "On-call/Incidents"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |\n\n## Usage\n\n- Requires the On-call Pro license.\n- Partial patch: omitted fields stay unchanged; an explicit `null` clears the field.\n- Optimistic locking — `version` must match the item's current version; a mismatch returns a conflict error.\n- Assignees, `item_type`, and the incident/post-mortem anchors cannot be changed here — use the dedicated endpoints.\n- Audited — changes are recorded in the audit log.",
-          "href": "/en/api-reference/on-call/incidents/incident-work-item-update",
-          "metadata": {
-            "sidebarTitle": "Update a work item"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/UpdateWorkItemRequest"
+              },
+              "example": {
+                "work_item_id": "wi_9fK2mNqRtVwXyZaBcDeFgH",
+                "version": 1,
+                "title": "Roll back the v2.14 deployment on web-server-01 and web-server-02",
+                "status": "in_progress"
+              }
+            }
           }
         }
       }
     },
     "/insight/account": {
       "post": {
-        "description": "Return aggregated incident insight metrics for the entire account.",
         "operationId": "insightByAccount",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "aggregate_unit": "day",
-                "end_time": 1712604800,
-                "severities": [
-                  "Critical",
-                  "Warning"
-                ],
-                "start_time": 1712000000
-              },
-              "schema": {
-                "$ref": "#/components/schemas/InsightQueryRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "Get account-level insight",
+        "description": "Return incident and alert metrics for the whole account, one row per time bucket.",
+        "tags": [
+          "On-call/Analytics"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Analytics Read** (`on-call`) |\n\n## Usage\n\n- One row per time bucket for the whole account. `responder_ids` and `incident_ids` are ignored; use `/insight/responder` or `/insight/incident/list` for those.\n- Incidents are counted by creation time. Rows are sorted by `ts` from newest to oldest, and a bucket (or dimension value) with no incidents produces no row — missing rows mean zero. `split_hours: true` returns up to three rows per bucket, one per `hours` value.\n- `total_alert_cnt`, `total_alert_event_cnt` and `noise_reduction_pct` honor only the time range, team, channel and severity filters; `query`, `labels`, `fields` and the duration filters apply to incident metrics only.\n- Members who are neither the account owner nor an admin only get data from channels they can access; other channels are silently excluded.\n- With `is_my_team: true`, `team_ids` is narrowed to the caller's teams; a caller who belongs to no team gets an empty result.",
+          "href": "/en/api-reference/on-call/analytics/insight-by-account",
+          "metadata": {
+            "sidebarTitle": "Get account-level insight"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/DimensionInsightResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "items": [
                       {
-                        "acknowledgement_pct": 100,
-                        "mean_seconds_to_ack": 1658854.5,
-                        "mean_seconds_to_close": 1874757,
-                        "noise_reduction_pct": 0,
-                        "total_alert_cnt": 0,
-                        "total_alert_event_cnt": 0,
-                        "total_engaged_seconds": 3317709,
+                        "ts": 1740844800,
                         "total_incident_cnt": 2,
                         "total_incidents_acknowledged": 2,
-                        "total_incidents_auto_closed": 0,
                         "total_incidents_closed": 2,
-                        "total_incidents_escalated": 0,
+                        "total_incidents_auto_closed": 0,
                         "total_incidents_manually_closed": 2,
-                        "total_incidents_manually_escalated": 0,
-                        "total_incidents_reassigned": 2,
                         "total_incidents_timeout_closed": 0,
+                        "total_incidents_escalated": 0,
+                        "total_incidents_manually_escalated": 0,
                         "total_incidents_timeout_escalated": 0,
+                        "total_incidents_reassigned": 2,
                         "total_interruptions": 3,
                         "total_notifications": 6,
+                        "total_engaged_seconds": 3317709,
                         "total_seconds_to_ack": 3317709,
                         "total_seconds_to_close": 3749514,
-                        "ts": 1740844800
+                        "mean_seconds_to_ack": 1658854.5,
+                        "mean_seconds_to_close": 1874757,
+                        "noise_reduction_pct": 0,
+                        "acknowledgement_pct": 100,
+                        "total_alert_cnt": 0,
+                        "total_alert_event_cnt": 0
                       }
                     ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/DimensionInsightResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -45323,6 +46821,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -45330,45 +46831,64 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Get account-level insight",
-        "tags": [
-          "On-call/Analytics"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Analytics Read** (`on-call`) |",
-          "href": "/en/api-reference/on-call/analytics/insight-by-account",
-          "metadata": {
-            "sidebarTitle": "Get account-level insight"
-          }
-        }
-      }
-    },
-    "/insight/alert/topk-by-label": {
-      "post": {
-        "description": "Return the top-K alert groups aggregated either by `check` or by `resource` label over the specified time range.",
-        "operationId": "insightTopkAlertsByLabel",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/InsightQueryRequest"
+              },
               "example": {
+                "start_time": 1712000000,
                 "end_time": 1712604800,
-                "k": 10,
-                "label": "check",
-                "orderby": "total_alert_cnt",
-                "start_time": 1712000000
-              },
-              "schema": {
-                "$ref": "#/components/schemas/InsightTopkAlertByLabelRequest"
+                "aggregate_unit": "day",
+                "severities": [
+                  "Critical",
+                  "Warning"
+                ]
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/insight/alert/topk-by-label": {
+      "post": {
+        "operationId": "insightTopkAlertsByLabel",
+        "summary": "Get top-K alerts grouped by check or resource",
+        "description": "Return the top-K alert groups aggregated either by `check` or by `resource` label over the specified time range.",
+        "tags": [
+          "On-call/Analytics"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Analytics Read** (`on-call`) |\n\n## Usage\n\n- Only the time range, `team_ids`, `channel_ids`, `severities`, `is_my_team` and `split_hours` filter the result; other filter fields and `aggregate_unit` are ignored.\n- Alerts are counted in hourly buckets, so the effective range is aligned to whole hours.\n- With `split_hours: true`, the top `k` is computed separately for each of `work`, `sleep` and `off`, so up to 3 × `k` rows come back.\n- Members who are neither the account owner nor an admin only get data from channels they can access; other channels are silently excluded.",
+          "href": "/en/api-reference/on-call/analytics/insight-topk-alerts-by-label",
+          "metadata": {
+            "sidebarTitle": "Get top-K alerts grouped by check or resource"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/InsightAlertByLabelResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "items": [
                       {
@@ -45387,27 +46907,10 @@
                         "total_alert_event_cnt": 231
                       }
                     ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/InsightAlertByLabelResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -45415,6 +46918,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -45422,96 +46928,95 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Get top-K alerts grouped by check or resource",
-        "tags": [
-          "On-call/Analytics"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Analytics Read** (`on-call`) |",
-          "href": "/en/api-reference/on-call/analytics/insight-topk-alerts-by-label",
-          "metadata": {
-            "sidebarTitle": "Get top-K alerts grouped by check or resource"
-          }
-        }
-      }
-    },
-    "/insight/channel": {
-      "post": {
-        "description": "Return insight metrics aggregated by channel.",
-        "operationId": "insightByChannel",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/InsightTopkAlertByLabelRequest"
+              },
               "example": {
-                "aggregate_unit": "day",
-                "channel_ids": [
-                  4321322010131
-                ],
+                "start_time": 1712000000,
                 "end_time": 1712604800,
-                "start_time": 1712000000
-              },
-              "schema": {
-                "$ref": "#/components/schemas/InsightQueryRequest"
+                "label": "check",
+                "k": 10,
+                "orderby": "total_alert_cnt"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/insight/channel": {
+      "post": {
+        "operationId": "insightByChannel",
+        "summary": "Get channel insight",
+        "description": "Return incident and alert metrics grouped by channel, one row per channel per time bucket.",
+        "tags": [
+          "On-call/Analytics"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Analytics Read** (`on-call`) |\n\n## Usage\n\n- One row per channel per time bucket. `responder_ids` and `incident_ids` are ignored.\n- Incidents are counted by creation time. Rows are sorted by `ts` from newest to oldest, and a bucket (or dimension value) with no incidents produces no row — missing rows mean zero. `split_hours: true` returns up to three rows per bucket, one per `hours` value.\n- `total_alert_cnt`, `total_alert_event_cnt` and `noise_reduction_pct` honor only the time range, team, channel and severity filters; `query`, `labels`, `fields` and the duration filters apply to incident metrics only.\n- Members who are neither the account owner nor an admin only get data from channels they can access; other channels are silently excluded.\n- With `is_my_team: true`, `team_ids` is narrowed to the caller's teams; a caller who belongs to no team gets an empty result.",
+          "href": "/en/api-reference/on-call/analytics/insight-by-channel",
+          "metadata": {
+            "sidebarTitle": "Get channel insight"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/DimensionInsightResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "items": [
                       {
-                        "acknowledgement_pct": 100,
+                        "ts": 1740844800,
                         "channel_id": 4321322010131,
                         "channel_name": "Production Alerts",
-                        "mean_seconds_to_ack": 1658854.5,
-                        "mean_seconds_to_close": 1874757,
-                        "noise_reduction_pct": 0,
-                        "total_alert_cnt": 0,
-                        "total_alert_event_cnt": 0,
-                        "total_engaged_seconds": 3317709,
                         "total_incident_cnt": 2,
                         "total_incidents_acknowledged": 2,
-                        "total_incidents_auto_closed": 0,
                         "total_incidents_closed": 2,
-                        "total_incidents_escalated": 0,
+                        "total_incidents_auto_closed": 0,
                         "total_incidents_manually_closed": 2,
-                        "total_incidents_manually_escalated": 0,
-                        "total_incidents_reassigned": 2,
                         "total_incidents_timeout_closed": 0,
+                        "total_incidents_escalated": 0,
+                        "total_incidents_manually_escalated": 0,
                         "total_incidents_timeout_escalated": 0,
+                        "total_incidents_reassigned": 2,
                         "total_interruptions": 3,
                         "total_notifications": 6,
+                        "total_engaged_seconds": 3317709,
                         "total_seconds_to_ack": 3317709,
                         "total_seconds_to_close": 3749514,
-                        "ts": 1740844800
+                        "mean_seconds_to_ack": 1658854.5,
+                        "mean_seconds_to_close": 1874757,
+                        "noise_reduction_pct": 0,
+                        "acknowledgement_pct": 100,
+                        "total_alert_cnt": 0,
+                        "total_alert_event_cnt": 0
                       }
                     ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/DimensionInsightResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -45519,6 +47024,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -45526,57 +47034,54 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Get channel insight",
-        "tags": [
-          "On-call/Analytics"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Analytics Read** (`on-call`) |",
-          "href": "/en/api-reference/on-call/analytics/insight-by-channel",
-          "metadata": {
-            "sidebarTitle": "Get channel insight"
-          }
-        }
-      }
-    },
-    "/insight/channel/export": {
-      "post": {
-        "description": "Export channel insight metrics as a CSV file — one row per channel (and per time/hour bucket when `aggregate_unit`/`split_hours` is used). The response is a CSV stream delivered with `Content-Disposition: attachment` — it is not a JSON envelope. `time_zone` defaults to UTC. Rows without a valid channel ID are skipped. Valid `export_fields` keys: channel_id, channel_name, total_incident_cnt, total_incidents_acknowledged, total_incidents_closed, total_incidents_auto_closed, total_incidents_manually_closed, total_incidents_timeout_closed, total_incidents_escalated, total_incidents_manually_escalated, total_incidents_timeout_escalated, total_incidents_reassigned, total_interruptions, total_notifications, total_engaged_seconds, mean_seconds_to_ack, mean_seconds_to_close, noise_reduction_pct, acknowledgement_pct, total_alert_cnt, total_alert_event_cnt, hours. The `hours` column is included by default only when `split_hours` is true. For compatibility, incident-export column keys are also accepted but produce empty columns.",
-        "operationId": "insightChannelExport",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/InsightQueryRequest"
+              },
               "example": {
+                "start_time": 1712000000,
+                "end_time": 1712604800,
                 "channel_ids": [
                   4321322010131
                 ],
-                "end_time": 1712604800,
-                "severities": [
-                  "Critical",
-                  "Warning"
-                ],
-                "start_time": 1712000000
-              },
-              "schema": {
-                "$ref": "#/components/schemas/InsightQueryRequest"
+                "aggregate_unit": "day"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/insight/channel/export": {
+      "post": {
+        "operationId": "insightChannelExport",
+        "summary": "Export channel insight",
+        "description": "Export channel insight metrics as a CSV file with the same rows as `/insight/channel`.",
+        "tags": [
+          "On-call/Analytics"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **100 requests/day**; **20 requests/minute**; **10 requests/second** per account |\n| Permissions | **Analytics Read** (`on-call`) |\n\n## Usage\n\n- The response is a CSV file (`Content-Type: application/octet-stream`), not a JSON envelope. Validation errors are returned as JSON before any CSV bytes are written.\n- Takes the same filters as `/insight/channel`. Rows without a channel ID are skipped. The file has no time-bucket column, so with `aggregate_unit` the rows of different buckets cannot be told apart; export one bucket per request if you need the split.\n- `export_fields` sets the columns and their order: channel_id, channel_name, total_incident_cnt, total_incidents_acknowledged, total_incidents_closed, total_incidents_auto_closed, total_incidents_manually_closed, total_incidents_timeout_closed, total_incidents_escalated, total_incidents_manually_escalated, total_incidents_timeout_escalated, total_incidents_reassigned, total_interruptions, total_notifications, total_engaged_seconds, mean_seconds_to_ack, mean_seconds_to_close, noise_reduction_pct, acknowledgement_pct, total_alert_cnt, total_alert_event_cnt, hours. Unknown or duplicate keys are rejected. When it is omitted, all columns are exported, and `hours` is included only when `split_hours` is true.\n- The incident-snapshot keys (progress, assigned_to, raw_assigned_to, escalate_rule_name, responders, raw_responders, ackers, owner_id, owner_name, creator_id, creator_name, closer_id, closer_name, snooze_status, snoozed_before, ever_muted, frequency, is_rare, alert_cnt, active_alert_cnt, alert_event_cnt, description, labels, fields) are also accepted for compatibility and produce empty columns.\n- Column headers are localized (request locale, then the member's, then the account's). Time buckets follow `time_zone` (UTC when omitted).",
+          "href": "/en/api-reference/on-call/analytics/insight-channel-export",
+          "metadata": {
+            "sidebarTitle": "Export channel insight"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/octet-stream": {
-                "example": "channel_id,channel_name,total_incident_cnt,total_incidents_closed\n4321322010131,Production Alerts,12,10\n",
                 "schema": {
-                  "description": "CSV file stream (`Content-Type: application/octet-stream`, `Content-Disposition: attachment; filename=channel_export_yyyyMMdd_HHmmss.csv`). The first row holds localized column headers. Columns default to the full field set, or the keys given in `export_fields`.",
+                  "type": "string",
                   "format": "binary",
-                  "type": "string"
-                }
+                  "description": "CSV file (`Content-Type: application/octet-stream`, `Content-Disposition: attachment; filename*=UTF-8''channel_export_yyyyMMdd_HHmmss.csv`). The first row holds localized column headers."
+                },
+                "example": "channel_id,channel_name,total_incident_cnt,total_incidents_closed\n4321322010131,Production Alerts,12,10\n"
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -45584,6 +47089,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -45591,62 +47099,57 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Export channel insight",
-        "tags": [
-          "On-call/Analytics"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **100 requests/day**; **20 requests/minute**; **10 requests/second** per account |\n| Permissions | **Analytics Read** (`on-call`) |",
-          "href": "/en/api-reference/on-call/analytics/insight-channel-export",
-          "metadata": {
-            "sidebarTitle": "Export channel insight"
-          }
-        }
-      }
-    },
-    "/insight/incident/export": {
-      "post": {
-        "description": "Export the filtered incident analytics list as a CSV file. The response is a CSV stream delivered with `Content-Disposition: attachment` — it is not a JSON envelope. CSV headers and formatted values use the request locale, falling back to the member locale and then the account locale. `time_zone` defaults to the account time zone, then `Asia/Shanghai`. Export stops after at most 100,000 rows. Valid `export_fields` keys: incident_id, title, severity, progress, channel_id, channel_name, team_id, team_name, created_at, alert_cnt, active_alert_cnt, alert_event_cnt, seconds_to_ack, seconds_to_close, closed_by, owner_id, owner_name, creator_id, creator_name, closer_id, closer_name, engaged_seconds, hours, notifications, interruptions, acknowledgements, ackers, assignments, reassignments, escalations, manual_escalations, timeout_escalations, assigned_to, raw_assigned_to, escalate_rule_name, responders, raw_responders, snooze_status, snoozed_before, ever_muted, frequency, is_rare, description, labels, fields. When `export_fields` is omitted, all columns are exported.",
-        "operationId": "insightIncidentExport",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/InsightQueryRequest"
+              },
               "example": {
-                "description_html_to_text": true,
+                "start_time": 1712000000,
                 "end_time": 1712604800,
-                "export_fields": [
-                  "incident_id",
-                  "title",
-                  "severity",
-                  "created_at",
-                  "seconds_to_close"
+                "channel_ids": [
+                  4321322010131
                 ],
                 "severities": [
                   "Critical",
                   "Warning"
-                ],
-                "start_time": 1712000000
-              },
-              "schema": {
-                "$ref": "#/components/schemas/InsightIncidentExportRequest"
+                ]
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/insight/incident/export": {
+      "post": {
+        "operationId": "insightIncidentExport",
+        "summary": "Export insight incidents",
+        "description": "Export the incidents matched by the analytics filters as a CSV file, one row per incident.",
+        "tags": [
+          "On-call/Analytics"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **100 requests/day**; **20 requests/minute**; **10 requests/second** per account |\n| Permissions | **Analytics Read** (`on-call`) |\n\n## Usage\n\n- The response is a CSV file (`Content-Type: application/octet-stream`), not a JSON envelope. Validation errors are returned as JSON before any CSV bytes are written.\n- Takes the same filters and sort order as `/insight/incident/list`. Export stops once more than 100,000 rows have been written.\n- `start_time` is moved forward to the earliest date kept by the account's data retention; a range that ends before that date is rejected.\n- `export_fields` sets the columns and their order: incident_id, title, severity, progress, channel_id, channel_name, team_id, team_name, created_at, alert_cnt, active_alert_cnt, alert_event_cnt, seconds_to_ack, seconds_to_close, closed_by, owner_id, owner_name, creator_id, creator_name, closer_id, closer_name, engaged_seconds, hours, notifications, interruptions, acknowledgements, ackers, assignments, reassignments, escalations, manual_escalations, timeout_escalations, assigned_to, raw_assigned_to, escalate_rule_name, responders, raw_responders, snooze_status, snoozed_before, ever_muted, frequency, is_rare, description, labels, fields. Unknown or duplicate keys are rejected; when omitted, every column except the aliases `owner_id`, `creator_id`, `closer_id`, `snoozed_before` and `is_rare` is exported.\n- `description_html_to_text: true` strips HTML from the `description` column.\n- Headers and formatted values use the request locale, then the member's, then the account's. Times are rendered in `time_zone`, falling back to the account time zone and then `Asia/Shanghai`.",
+          "href": "/en/api-reference/on-call/analytics/insight-incident-export",
+          "metadata": {
+            "sidebarTitle": "Export insight incidents"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/octet-stream": {
-                "example": "incident_id,title,severity,created_at\n6a86b5d6f72de50ae1ce2ffb,CPU usage above 90%,Critical,2026-01-01 10:00:00 +0800 CST\n",
                 "schema": {
-                  "description": "CSV file stream (`Content-Type: application/octet-stream`, `Content-Disposition: attachment; filename=incident_export_yyyyMMdd_HHmmss.csv`). The first row holds localized column headers. Columns default to the full incident field set, or the keys given in `export_fields`.",
+                  "type": "string",
                   "format": "binary",
-                  "type": "string"
-                }
+                  "description": "CSV file (`Content-Type: application/octet-stream`, `Content-Disposition: attachment; filename*=UTF-8''incident_export_yyyyMMdd_HHmmss.csv`). The first row holds localized column headers."
+                },
+                "example": "incident_id,title,severity,created_at\n6a86b5d6f72de50ae1ce2ffb,CPU usage above 90%,Critical,2026-01-01 10:00:00 +0800 CST\n"
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -45654,6 +47157,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -45661,123 +47167,130 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Export insight incidents",
-        "tags": [
-          "On-call/Analytics"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **100 requests/day**; **20 requests/minute**; **10 requests/second** per account |\n| Permissions | **Analytics Read** (`on-call`) |",
-          "href": "/en/api-reference/on-call/analytics/insight-incident-export",
-          "metadata": {
-            "sidebarTitle": "Export insight incidents"
-          }
-        }
-      }
-    },
-    "/insight/incident/list": {
-      "post": {
-        "description": "Return a paged list of incidents with per-incident handling metrics used by the analytics dashboard.",
-        "operationId": "insightIncidentList",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/InsightIncidentExportRequest"
+              },
               "example": {
+                "start_time": 1712000000,
                 "end_time": 1712604800,
-                "limit": 20,
-                "p": 1,
                 "severities": [
-                  "Critical"
+                  "Critical",
+                  "Warning"
                 ],
-                "start_time": 1712000000
-              },
-              "schema": {
-                "$ref": "#/components/schemas/InsightIncidentListRequest"
+                "export_fields": [
+                  "incident_id",
+                  "title",
+                  "severity",
+                  "created_at",
+                  "seconds_to_close"
+                ],
+                "description_html_to_text": true
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/insight/incident/list": {
+      "post": {
+        "operationId": "insightIncidentList",
+        "summary": "List insight incidents",
+        "description": "Return a paged list of incidents with per-incident handling metrics used by the analytics dashboard.",
+        "tags": [
+          "On-call/Analytics"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Analytics Read** (`on-call`) |\n\n## Usage\n\n- Sorted by incident creation time, newest first by default (`asc: true` for oldest first).\n- Page with `p` + `limit` (at most 10,000 records reachable) or, for deeper reads, pass the previous page's `search_after_ctx` back. When `search_after_ctx` is sent, `total` counts only the incidents after the cursor.\n- `responder_ids` keeps incidents in which any of the given members was a responder.\n- Members who are neither the account owner nor an admin only get data from channels they can access; other channels are silently excluded.\n- With `is_my_team: true`, `team_ids` is narrowed to the caller's teams; a caller who belongs to no team gets an empty result.",
+          "href": "/en/api-reference/on-call/analytics/insight-incident-list",
+          "metadata": {
+            "sidebarTitle": "List insight incidents"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/InsightIncidentListResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
+                    "total": 2363,
                     "has_next_page": true,
+                    "search_after_ctx": "6a86b5d6f72de50ae1ce2ffb",
                     "items": [
                       {
-                        "acknowledgements": 1,
-                        "active_alert_cnt": 0,
-                        "alert_cnt": 3,
-                        "alert_event_cnt": 5,
-                        "assigned_to": {
-                          "assigned_at": 1787213270,
-                          "escalate_rule_id": "66138789904a9027583dbc4e",
-                          "escalate_rule_name": "On-call Policy",
-                          "id": "b8tyUoRvCv4wsPndFRpmNL",
-                          "layer_idx": 0,
-                          "type": "assign"
-                        },
-                        "assignments": 1,
+                        "incident_id": "6a86b5d6f72de50ae1ce2ffb",
+                        "title": "CPU usage above 90% on prod-web-01",
+                        "description": "CPU usage stayed above the threshold for 5 minutes",
+                        "team_id": 2477033058131,
+                        "team_name": "SRE Team",
                         "channel_id": 3047621227131,
                         "channel_name": "Production Alerts",
-                        "closed_by": "manually",
-                        "closer_id": 2477273692131,
-                        "closer_name": "alice",
+                        "progress": "Closed",
+                        "severity": "Critical",
                         "created_at": 1787213270,
+                        "alert_cnt": 3,
+                        "active_alert_cnt": 0,
+                        "alert_event_cnt": 5,
+                        "closed_by": "manually",
                         "creator_id": 2477273692131,
                         "creator_name": "alice",
-                        "description": "CPU usage stayed above the threshold for 5 minutes",
+                        "closer_id": 2477273692131,
+                        "closer_name": "alice",
+                        "seconds_to_ack": 14,
+                        "seconds_to_close": 1830,
                         "engaged_seconds": 1816,
-                        "escalations": 0,
                         "hours": "work",
-                        "incident_id": "6a86b5d6f72de50ae1ce2ffb",
-                        "interruptions": 1,
-                        "manual_escalations": 0,
-                        "notifications": 2,
-                        "progress": "Closed",
-                        "reassignments": 0,
                         "responders": [
                           {
-                            "acknowledged_at": 1787213284,
-                            "assigned_at": 1787213270,
-                            "email": "alice@example.com",
                             "person_id": 2477273692131,
-                            "person_name": "alice"
+                            "assigned_at": 1787213270,
+                            "acknowledged_at": 1787213284,
+                            "person_name": "alice",
+                            "email": "alice@example.com"
                           }
                         ],
-                        "seconds_to_ack": 14,
-                        "seconds_to_close": 1830,
-                        "severity": "Critical",
-                        "team_id": 2477033058131,
-                        "team_name": "SRE Team",
+                        "assigned_to": {
+                          "escalate_rule_id": "66138789904a9027583dbc4e",
+                          "layer_idx": 0,
+                          "type": "assign",
+                          "assigned_at": 1787213270,
+                          "id": "b8tyUoRvCv4wsPndFRpmNL",
+                          "escalate_rule_name": "On-call Policy"
+                        },
+                        "notifications": 2,
+                        "interruptions": 1,
+                        "assignments": 1,
+                        "reassignments": 0,
+                        "acknowledgements": 1,
+                        "escalations": 0,
                         "timeout_escalations": 0,
-                        "title": "CPU usage above 90% on prod-web-01"
+                        "manual_escalations": 0
                       }
-                    ],
-                    "search_after_ctx": "6a86b5d6f72de50ae1ce2ffb",
-                    "total": 2363
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/InsightIncidentListResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                    ]
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -45785,6 +47298,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -45792,87 +47308,88 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "List insight incidents",
-        "tags": [
-          "On-call/Analytics"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Analytics Read** (`on-call`) |",
-          "href": "/en/api-reference/on-call/analytics/insight-incident-list",
-          "metadata": {
-            "sidebarTitle": "List insight incidents"
-          }
-        }
-      }
-    },
-    "/insight/responder": {
-      "post": {
-        "description": "Return insight metrics aggregated by responder.",
-        "operationId": "insightByResponder",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/InsightIncidentListRequest"
+              },
               "example": {
-                "aggregate_unit": "day",
+                "start_time": 1712000000,
                 "end_time": 1712604800,
-                "responder_ids": [
-                  3790925372131
-                ],
-                "start_time": 1712000000
-              },
-              "schema": {
-                "$ref": "#/components/schemas/InsightQueryRequest"
+                "p": 1,
+                "limit": 20,
+                "severities": [
+                  "Critical"
+                ]
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/insight/responder": {
+      "post": {
+        "operationId": "insightByResponder",
+        "summary": "Get responder insight",
+        "description": "Return per-responder incident handling metrics, one row per responder per time bucket.",
+        "tags": [
+          "On-call/Analytics"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Analytics Read** (`on-call`) |\n\n## Usage\n\n- One row per responder per time bucket; `responder_ids` limits which responders are returned. `seconds_to_close_from`/`seconds_to_close_to` and `incident_ids` are ignored.\n- Incidents are counted by creation time. Rows are sorted by `ts` from newest to oldest, and a bucket (or dimension value) with no incidents produces no row — missing rows mean zero. `split_hours: true` returns up to three rows per bucket, one per `hours` value.\n- Members who are neither the account owner nor an admin only get data from channels they can access; other channels are silently excluded.\n- With `is_my_team: true`, `team_ids` is narrowed to the caller's teams; a caller who belongs to no team gets an empty result.",
+          "href": "/en/api-reference/on-call/analytics/insight-by-responder",
+          "metadata": {
+            "sidebarTitle": "Get responder insight"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/ResponderInsightResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "items": [
                       {
-                        "acknowledgement_pct": 100,
-                        "mean_seconds_to_ack": 2265624,
+                        "ts": 1740844800,
                         "responder_id": 3790925372131,
                         "responder_name": "alice",
-                        "total_engaged_seconds": 10,
                         "total_incident_cnt": 1,
                         "total_incidents_acknowledged": 1,
-                        "total_incidents_escalated": 0,
-                        "total_incidents_manually_escalated": 0,
                         "total_incidents_reassigned": 0,
+                        "total_incidents_escalated": 0,
                         "total_incidents_timeout_escalated": 0,
+                        "total_incidents_manually_escalated": 0,
                         "total_interruptions": 1,
                         "total_notifications": 2,
+                        "total_engaged_seconds": 10,
                         "total_seconds_to_ack": 2265624,
-                        "ts": 1740844800
+                        "mean_seconds_to_ack": 2265624,
+                        "acknowledgement_pct": 100
                       }
                     ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/ResponderInsightResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -45880,6 +47397,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -45887,57 +47407,54 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Get responder insight",
-        "tags": [
-          "On-call/Analytics"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Analytics Read** (`on-call`) |",
-          "href": "/en/api-reference/on-call/analytics/insight-by-responder",
-          "metadata": {
-            "sidebarTitle": "Get responder insight"
-          }
-        }
-      }
-    },
-    "/insight/responder/export": {
-      "post": {
-        "description": "Export responder insight metrics as a CSV file — one row per responder (and per time/hour bucket when `aggregate_unit`/`split_hours` is used). The response is a CSV stream delivered with `Content-Disposition: attachment` — it is not a JSON envelope. `time_zone` defaults to UTC. Rows without a valid responder ID are skipped. Valid `export_fields` keys: responder_id, responder_name, total_incident_cnt, total_incidents_acknowledged, total_incidents_reassigned, total_incidents_escalated, total_incidents_manually_escalated, total_incidents_timeout_escalated, total_interruptions, total_notifications, total_engaged_seconds, mean_seconds_to_ack, acknowledgement_pct, hours. The `hours` column is included by default only when `split_hours` is true. For compatibility, incident-export column keys are also accepted but produce empty columns.",
-        "operationId": "insightResponderExport",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/InsightQueryRequest"
+              },
               "example": {
+                "start_time": 1712000000,
                 "end_time": 1712604800,
                 "responder_ids": [
                   3790925372131
                 ],
-                "severities": [
-                  "Critical",
-                  "Warning"
-                ],
-                "start_time": 1712000000
-              },
-              "schema": {
-                "$ref": "#/components/schemas/InsightQueryRequest"
+                "aggregate_unit": "day"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/insight/responder/export": {
+      "post": {
+        "operationId": "insightResponderExport",
+        "summary": "Export responder insight",
+        "description": "Export responder insight metrics as a CSV file with the same rows as `/insight/responder`.",
+        "tags": [
+          "On-call/Analytics"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **100 requests/day**; **20 requests/minute**; **10 requests/second** per account |\n| Permissions | **Analytics Read** (`on-call`) |\n\n## Usage\n\n- The response is a CSV file (`Content-Type: application/octet-stream`), not a JSON envelope. Validation errors are returned as JSON before any CSV bytes are written.\n- Takes the same filters as `/insight/responder`. Rows without a responder ID are skipped. The file has no time-bucket column, so with `aggregate_unit` the rows of different buckets cannot be told apart; export one bucket per request if you need the split.\n- `export_fields` sets the columns and their order: responder_id, responder_name, total_incident_cnt, total_incidents_acknowledged, total_incidents_reassigned, total_incidents_escalated, total_incidents_manually_escalated, total_incidents_timeout_escalated, total_interruptions, total_notifications, total_engaged_seconds, mean_seconds_to_ack, acknowledgement_pct, hours. Unknown or duplicate keys are rejected. When it is omitted, all columns are exported, and `hours` is included only when `split_hours` is true.\n- The incident-snapshot keys (progress, assigned_to, raw_assigned_to, escalate_rule_name, responders, raw_responders, ackers, owner_id, owner_name, creator_id, creator_name, closer_id, closer_name, snooze_status, snoozed_before, ever_muted, frequency, is_rare, alert_cnt, active_alert_cnt, alert_event_cnt, description, labels, fields) are also accepted for compatibility and produce empty columns.\n- Column headers are localized (request locale, then the member's, then the account's). Time buckets follow `time_zone` (UTC when omitted).",
+          "href": "/en/api-reference/on-call/analytics/insight-responder-export",
+          "metadata": {
+            "sidebarTitle": "Export responder insight"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/octet-stream": {
-                "example": "responder_id,responder_name,total_incident_cnt,total_incidents_acknowledged\n3790925372131,alice,5,4\n",
                 "schema": {
-                  "description": "CSV file stream (`Content-Type: application/octet-stream`, `Content-Disposition: attachment; filename=responder_export_yyyyMMdd_HHmmss.csv`). The first row holds localized column headers. Columns default to the full field set, or the keys given in `export_fields`.",
+                  "type": "string",
                   "format": "binary",
-                  "type": "string"
-                }
+                  "description": "CSV file (`Content-Type: application/octet-stream`, `Content-Disposition: attachment; filename*=UTF-8''responder_export_yyyyMMdd_HHmmss.csv`). The first row holds localized column headers."
+                },
+                "example": "responder_id,responder_name,total_incident_cnt,total_incidents_acknowledged\n3790925372131,alice,5,4\n"
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -45945,6 +47462,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -45952,96 +47472,99 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Export responder insight",
-        "tags": [
-          "On-call/Analytics"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **100 requests/day**; **20 requests/minute**; **10 requests/second** per account |\n| Permissions | **Analytics Read** (`on-call`) |",
-          "href": "/en/api-reference/on-call/analytics/insight-responder-export",
-          "metadata": {
-            "sidebarTitle": "Export responder insight"
-          }
-        }
-      }
-    },
-    "/insight/team": {
-      "post": {
-        "description": "Return insight metrics aggregated by team.",
-        "operationId": "insightByTeam",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/InsightQueryRequest"
+              },
               "example": {
-                "aggregate_unit": "day",
-                "end_time": 1712604800,
                 "start_time": 1712000000,
-                "team_ids": [
-                  4295771902131
+                "end_time": 1712604800,
+                "responder_ids": [
+                  3790925372131
+                ],
+                "severities": [
+                  "Critical",
+                  "Warning"
                 ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/InsightQueryRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/insight/team": {
+      "post": {
+        "operationId": "insightByTeam",
+        "summary": "Get team insight",
+        "description": "Return incident and alert metrics grouped by team, one row per team per time bucket.",
+        "tags": [
+          "On-call/Analytics"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Analytics Read** (`on-call`) |\n\n## Usage\n\n- One row per team per time bucket. Incidents without a team are aggregated into a row that has no `team_id`. `responder_ids` and `incident_ids` are ignored.\n- Incidents are counted by creation time. Rows are sorted by `ts` from newest to oldest, and a bucket (or dimension value) with no incidents produces no row — missing rows mean zero. `split_hours: true` returns up to three rows per bucket, one per `hours` value.\n- `total_alert_cnt`, `total_alert_event_cnt` and `noise_reduction_pct` honor only the time range, team, channel and severity filters; `query`, `labels`, `fields` and the duration filters apply to incident metrics only.\n- Members who are neither the account owner nor an admin only get data from channels they can access; other channels are silently excluded.\n- With `is_my_team: true`, `team_ids` is narrowed to the caller's teams; a caller who belongs to no team gets an empty result.",
+          "href": "/en/api-reference/on-call/analytics/insight-by-team",
+          "metadata": {
+            "sidebarTitle": "Get team insight"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/DimensionInsightResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "items": [
                       {
-                        "acknowledgement_pct": 100,
-                        "mean_seconds_to_ack": 1658854.5,
-                        "mean_seconds_to_close": 1874757,
-                        "noise_reduction_pct": 0,
+                        "ts": 1740844800,
                         "team_id": 4295771902131,
                         "team_name": "SRE Team",
-                        "total_alert_cnt": 0,
-                        "total_alert_event_cnt": 0,
-                        "total_engaged_seconds": 3317709,
                         "total_incident_cnt": 2,
                         "total_incidents_acknowledged": 2,
-                        "total_incidents_auto_closed": 0,
                         "total_incidents_closed": 2,
-                        "total_incidents_escalated": 0,
+                        "total_incidents_auto_closed": 0,
                         "total_incidents_manually_closed": 2,
-                        "total_incidents_manually_escalated": 0,
-                        "total_incidents_reassigned": 2,
                         "total_incidents_timeout_closed": 0,
+                        "total_incidents_escalated": 0,
+                        "total_incidents_manually_escalated": 0,
                         "total_incidents_timeout_escalated": 0,
+                        "total_incidents_reassigned": 2,
                         "total_interruptions": 3,
                         "total_notifications": 6,
+                        "total_engaged_seconds": 3317709,
                         "total_seconds_to_ack": 3317709,
                         "total_seconds_to_close": 3749514,
-                        "ts": 1740844800
+                        "mean_seconds_to_ack": 1658854.5,
+                        "mean_seconds_to_close": 1874757,
+                        "noise_reduction_pct": 0,
+                        "acknowledgement_pct": 100,
+                        "total_alert_cnt": 0,
+                        "total_alert_event_cnt": 0
                       }
                     ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/DimensionInsightResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -46049,6 +47572,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -46056,57 +47582,54 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Get team insight",
-        "tags": [
-          "On-call/Analytics"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Analytics Read** (`on-call`) |",
-          "href": "/en/api-reference/on-call/analytics/insight-by-team",
-          "metadata": {
-            "sidebarTitle": "Get team insight"
-          }
-        }
-      }
-    },
-    "/insight/team/export": {
-      "post": {
-        "description": "Export team insight metrics as a CSV file — one row per team (and per time/hour bucket when `aggregate_unit`/`split_hours` is used). The response is a CSV stream delivered with `Content-Disposition: attachment` — it is not a JSON envelope. `time_zone` defaults to UTC. Rows without a valid team ID are skipped. Valid `export_fields` keys: team_id, team_name, total_incident_cnt, total_incidents_acknowledged, total_incidents_closed, total_incidents_auto_closed, total_incidents_manually_closed, total_incidents_timeout_closed, total_incidents_escalated, total_incidents_manually_escalated, total_incidents_timeout_escalated, total_incidents_reassigned, total_interruptions, total_notifications, total_engaged_seconds, mean_seconds_to_ack, mean_seconds_to_close, noise_reduction_pct, acknowledgement_pct, total_alert_cnt, total_alert_event_cnt, hours. The `hours` column is included by default only when `split_hours` is true. For compatibility, incident-export column keys are also accepted but produce empty columns.",
-        "operationId": "insightTeamExport",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/InsightQueryRequest"
+              },
               "example": {
-                "end_time": 1712604800,
-                "severities": [
-                  "Critical",
-                  "Warning"
-                ],
                 "start_time": 1712000000,
+                "end_time": 1712604800,
                 "team_ids": [
                   4295771902131
-                ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/InsightQueryRequest"
+                ],
+                "aggregate_unit": "day"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/insight/team/export": {
+      "post": {
+        "operationId": "insightTeamExport",
+        "summary": "Export team insight",
+        "description": "Export team insight metrics as a CSV file with the same rows as `/insight/team`.",
+        "tags": [
+          "On-call/Analytics"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **100 requests/day**; **20 requests/minute**; **10 requests/second** per account |\n| Permissions | **Analytics Read** (`on-call`) |\n\n## Usage\n\n- The response is a CSV file (`Content-Type: application/octet-stream`), not a JSON envelope. Validation errors are returned as JSON before any CSV bytes are written.\n- Takes the same filters as `/insight/team`. Rows without a team ID (incidents without a team) are skipped. The file has no time-bucket column, so with `aggregate_unit` the rows of different buckets cannot be told apart; export one bucket per request if you need the split.\n- `export_fields` sets the columns and their order: team_id, team_name, total_incident_cnt, total_incidents_acknowledged, total_incidents_closed, total_incidents_auto_closed, total_incidents_manually_closed, total_incidents_timeout_closed, total_incidents_escalated, total_incidents_manually_escalated, total_incidents_timeout_escalated, total_incidents_reassigned, total_interruptions, total_notifications, total_engaged_seconds, mean_seconds_to_ack, mean_seconds_to_close, noise_reduction_pct, acknowledgement_pct, total_alert_cnt, total_alert_event_cnt, hours. Unknown or duplicate keys are rejected. When it is omitted, all columns are exported, and `hours` is included only when `split_hours` is true.\n- The incident-snapshot keys (progress, assigned_to, raw_assigned_to, escalate_rule_name, responders, raw_responders, ackers, owner_id, owner_name, creator_id, creator_name, closer_id, closer_name, snooze_status, snoozed_before, ever_muted, frequency, is_rare, alert_cnt, active_alert_cnt, alert_event_cnt, description, labels, fields) are also accepted for compatibility and produce empty columns.\n- Column headers are localized (request locale, then the member's, then the account's). Time buckets follow `time_zone` (UTC when omitted).",
+          "href": "/en/api-reference/on-call/analytics/insight-team-export",
+          "metadata": {
+            "sidebarTitle": "Export team insight"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/octet-stream": {
-                "example": "team_id,team_name,total_incident_cnt,total_incidents_closed\n4295771902131,SRE Team,12,10\n",
                 "schema": {
-                  "description": "CSV file stream (`Content-Type: application/octet-stream`, `Content-Disposition: attachment; filename=team_export_yyyyMMdd_HHmmss.csv`). The first row holds localized column headers. Columns default to the full field set, or the keys given in `export_fields`.",
+                  "type": "string",
                   "format": "binary",
-                  "type": "string"
-                }
+                  "description": "CSV file (`Content-Type: application/octet-stream`, `Content-Disposition: attachment; filename*=UTF-8''team_export_yyyyMMdd_HHmmss.csv`). The first row holds localized column headers."
+                },
+                "example": "team_id,team_name,total_incident_cnt,total_incidents_closed\n4295771902131,SRE Team,12,10\n"
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -46114,6 +47637,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -46121,62 +47647,70 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Export team insight",
-        "tags": [
-          "On-call/Analytics"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **100 requests/day**; **20 requests/minute**; **10 requests/second** per account |\n| Permissions | **Analytics Read** (`on-call`) |",
-          "href": "/en/api-reference/on-call/analytics/insight-team-export",
-          "metadata": {
-            "sidebarTitle": "Export team insight"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/InsightQueryRequest"
+              },
+              "example": {
+                "start_time": 1712000000,
+                "end_time": 1712604800,
+                "team_ids": [
+                  4295771902131
+                ],
+                "severities": [
+                  "Critical",
+                  "Warning"
+                ]
+              }
+            }
           }
         }
       }
     },
     "/member/delete": {
       "post": {
-        "description": "Remove a member from the organization by ID, email, phone, or name.",
         "operationId": "memberDelete",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "member_id": 5068740052131
-              },
-              "schema": {
-                "$ref": "#/components/schemas/MemberDeleteRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "Delete member",
+        "description": "Remove a member from the organization by ID, email, phone, or name.",
+        "tags": [
+          "Platform/Members"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Members Manage** (`organization`) |\n\n## Usage\n\n- Identify the member with one of the lookup fields; when several are sent, the first non-empty one wins in the order `member_id`, `member_name`, `email`, `phone`, `ref_id`.\n- Unless `is_force` is true, the call fails with `400 ReferenceExist` while the member belongs to a team, is a direct target of an escalation rule, or is in a schedule; `data.refs` lists each reference. A forced delete skips this check and leaves those references in place.\n- Deletion is soft: the member's status becomes `deleted`, any license seat the member holds is released, and the member's SSO identity links are removed. The member still resolves through `POST /person/infos`.\n- Members provisioned through SSO cannot be deleted while the SSO configuration marks them non-editable; the call returns `400`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "href": "/en/api-reference/platform/members/member-delete",
+          "metadata": {
+            "sidebarTitle": "Delete member"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/MemberEmptyObject"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -46184,6 +47718,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -46191,39 +47728,58 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Delete member",
-        "tags": [
-          "Platform/Members"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Members Manage** (`organization`) |\n\n## Usage\n\n- By default (`is_force=false`), the system checks whether the member is referenced by other resources (e.g., escalation rules, schedules). If references exist, the API returns error code `ReferenceExist` with the reference list in `data.refs`. Set `is_force=true` to skip the reference check and force delete.\n- Members provisioned via SSO with `sso_user_non_editable=true` cannot be deleted through this API. Disable that SSO restriction first.\n- This operation is recorded in the audit log.",
-          "href": "/en/api-reference/platform/members/member-delete",
-          "metadata": {
-            "sidebarTitle": "Delete member"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/MemberDeleteRequest"
+              },
+              "example": {
+                "member_id": 5068740052131
+              }
+            }
           }
         }
       }
     },
     "/member/info": {
       "post": {
-        "description": "Return the profile of the member the credential belongs to. Requires a member-scoped credential — calls authenticated as the account principal (e.g. an account-level app key) are rejected with a 400.",
         "operationId": "memberInfo",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {},
-              "schema": {
-                "$ref": "#/components/schemas/MemberInfoRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "Get current member info",
+        "description": "Return the profile and account context of the member who owns the credential.",
+        "tags": [
+          "Platform/Members"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — but see the credential requirement under Usage |\n\n## Usage\n\n- Requires a member credential; calls made with the account owner's credentials return `400 BadRequest`. Use `POST /account/info` for the account owner.\n- `time_zone` is the member's own setting (empty string = follow the account), `account_time_zone` is the account's setting, and `resolved_time_zone` is the zone to render times in.",
+          "href": "/en/api-reference/platform/members/member-info",
+          "metadata": {
+            "sidebarTitle": "Get current member info"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/MemberInfoResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "account_avatar": "",
                     "account_email": "alice@example.com",
@@ -46246,28 +47802,83 @@
                     "member_name": "Alice",
                     "phone": "+86185****0300",
                     "phone_verified": true,
-                    "time_zone": "Asia/Shanghai"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
+                    "time_zone": "Asia/Shanghai",
+                    "resolved_time_zone": "Asia/Shanghai"
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "429": {
+            "$ref": "#/components/responses/TooManyRequests"
+          },
+          "500": {
+            "$ref": "#/components/responses/ServerError"
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/MemberInfoRequest"
+              },
+              "example": {}
+            }
+          }
+        }
+      }
+    },
+    "/member/info/reset": {
+      "post": {
+        "operationId": "memberResetInfo",
+        "summary": "Reset member info",
+        "description": "Identify a member and reset the specified profile fields.",
+        "tags": [
+          "Platform/Members"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Identify the member with one of `member_id`, `member_name`, `email`, `phone`, or `ref_id`. If multiple identifiers are present, the server checks them in that order.\n- The caller must be the account owner, the member themself, or hold the Admin role; otherwise the call returns `403 AccessDenied`.\n- Put the fields to write under `updates`: `member_name`, `password`, `phone`, `country_code`, `email`, `avatar`, `locale`, `time_zone`, or `ref_id`. Omitted or `null` fields keep their current value; `updates` must carry at least one field.\n- A new `member_name`, `email`, or `phone` must not belong to another member of the account; a conflict returns `400`. A changed `email` or `phone` is marked unverified unless `from` is `api` and the account has member invitations disabled.\n- `updates.time_zone` set to an empty string clears the member's own time zone, so the member follows the account's.\n- `updates.country_code` is an ISO 3166-1 alpha-2 region code (e.g. \"CN\", \"US\"). It is an independently updatable field: `updates.phone` is not required, and the new region is stored even when the phone is unchanged. An explicit empty string is rejected with a 400.\n- When `updates.phone` has no \"+\" prefix, it is parsed with `updates.country_code` as the region hint, falling back to the member's stored region and then to \"CN\". Legacy digit calling codes such as \"86\" remain accepted only as parsing hints — stored values are always ISO region codes.\n- The top-level `country_code` is only a parsing hint for the identifying `phone`; it is never stored.\n- Fields are written one at a time; if a later field fails validation, the fields written before it in the same call stay saved.\n- Members provisioned through SSO cannot be changed while the SSO configuration marks them non-editable.\n- Concurrent profile updates or invitations in the same account can return `429 RequestTooFrequently`; retry after a moment.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "href": "/en/api-reference/platform/members/member-reset-info",
+          "metadata": {
+            "sidebarTitle": "Reset member info"
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/MemberInfoResponse"
+                          "$ref": "#/components/schemas/MemberEmptyObject"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -46275,6 +47886,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -46282,67 +47896,78 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Get current member info",
-        "tags": [
-          "Platform/Members"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — but the credential must belong to a member; account-principal credentials (e.g. an account-level app key) are rejected with a 400 |",
-          "href": "/en/api-reference/platform/members/member-info",
-          "metadata": {
-            "sidebarTitle": "Get current member info"
-          }
-        }
-      }
-    },
-    "/member/info/reset": {
-      "post": {
-        "description": "Identify a member and reset the specified profile fields.",
-        "operationId": "memberResetInfo",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/MemberResetInfoRequest"
+              },
               "example": {
                 "member_id": 2476444212131,
                 "updates": {
-                  "locale": "zh-CN",
                   "member_name": "Alice Chen",
+                  "locale": "zh-CN",
                   "time_zone": "Asia/Shanghai"
                 }
-              },
-              "schema": {
-                "$ref": "#/components/schemas/MemberResetInfoRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/member/invite": {
+      "post": {
+        "operationId": "memberInvite",
+        "summary": "Invite members",
+        "description": "Batch invite new members to the organization by email or phone.",
+        "tags": [
+          "Platform/Members"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Members Manage** (`organization`) |\n\n## Usage\n\n- Each entry needs `email`, or `member_name` together with `phone`.\n- Entries whose email or phone already belongs to a member of the account are skipped silently; `items` lists only the members created by this call and is `null` when none were created.\n- New members are created in `pending` status and are sent an invitation by email or SMS.\n- Emails are stored in lower case. If the account restricts member email domains, an address outside the allowlist returns `400`; duplicate emails or phones within one request also return `400`.\n- `country_code` must be an ISO 3166-1 alpha-2 region code (e.g. \"CN\"). It is validated and normalized to upper case before storage; invalid values are rejected with a 400.\n- When a member's `phone` has no \"+\" prefix, it is parsed with that member's `country_code` as the region hint (defaults to \"CN\" when omitted).\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "href": "/en/api-reference/platform/members/member-invite",
+          "metadata": {
+            "sidebarTitle": "Invite members"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/MemberEmptyObject"
+                          "$ref": "#/components/schemas/MemberInviteResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "items": [
+                      {
+                        "member_id": 5068740052131,
+                        "member_name": "Charlie"
+                      },
+                      {
+                        "member_id": 5068740052132,
+                        "member_name": "Dave"
+                      }
+                    ]
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -46350,6 +47975,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -46357,90 +47985,124 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Reset member info",
-        "tags": [
-          "Platform/Members"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Identify the member with one of `member_id`, `member_name`, `email`, `phone`, or `ref_id`. If multiple identifiers are present, the server checks them in that order.\n- `updates.country_code` is an ISO 3166-1 alpha-2 region code (e.g. \"CN\", \"US\"). It is an independently updatable field: `updates.phone` is not required, and the new region is stored even when the phone is unchanged. An explicit empty string is rejected with a 400.\n- When `updates.phone` has no \"+\" prefix, it is parsed with `updates.country_code` as the region hint, falling back to the member's stored region and then to \"CN\". Legacy digit calling codes such as \"86\" remain accepted only as parsing hints — stored values are always ISO region codes.\n- The top-level `country_code` is only a parsing hint for the identifying `phone`; it is never stored.\n- Put the profile fields to write under `updates`: `member_name`, `password`, `phone`, `country_code`, `email`, `avatar`, `locale`, `time_zone`, or `ref_id`.\n- Members provisioned by SSO cannot be changed when SSO marks them as externally managed.\n- `updates` must carry at least one field; an object with every field omitted is rejected.",
-          "href": "/en/api-reference/platform/members/member-reset-info",
-          "metadata": {
-            "sidebarTitle": "Reset member info"
-          }
-        }
-      }
-    },
-    "/member/invite": {
-      "post": {
-        "description": "Batch invite new members to the organization by email or phone.",
-        "operationId": "memberInvite",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/MemberInviteRequest"
+              },
               "example": {
                 "members": [
                   {
+                    "member_name": "Charlie",
                     "email": "charlie@example.com",
                     "locale": "en-US",
-                    "member_name": "Charlie",
+                    "time_zone": "Asia/Shanghai",
                     "role_ids": [
                       6
-                    ],
-                    "time_zone": "Asia/Shanghai"
+                    ]
                   },
                   {
-                    "country_code": "CN",
-                    "locale": "zh-CN",
                     "member_name": "Dave",
                     "phone": "13800138000",
+                    "country_code": "CN",
+                    "locale": "zh-CN",
                     "time_zone": "Asia/Shanghai"
                   }
                 ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/MemberInviteRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/member/list": {
+      "post": {
+        "operationId": "memberList",
+        "summary": "List members",
+        "description": "Return a paginated list of organization members.",
+        "tags": [
+          "Platform/Members"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Returns members in `enabled` or `pending` status. Removed members and the account owner are not listed; resolve their IDs with `POST /person/infos`.\n- `role_id` returns the members holding that role; `member_id` returns at most that one member.",
+          "href": "/en/api-reference/platform/members/member-list",
+          "metadata": {
+            "sidebarTitle": "List members"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "items": [
-                      {
-                        "member_id": 5068740052131,
-                        "member_name": "Charlie"
-                      },
-                      {
-                        "member_id": 5068740052132,
-                        "member_name": "Dave"
-                      }
-                    ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/MemberInviteResponse"
+                          "$ref": "#/components/schemas/MemberListResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "p": 1,
+                    "limit": 5,
+                    "total": 148,
+                    "items": [
+                      {
+                        "account_id": 2451002751131,
+                        "member_id": 5068740052131,
+                        "member_name": "Bob",
+                        "country_code": "",
+                        "phone": "+86151****6519",
+                        "email": "bob@example.com",
+                        "phone_verified": true,
+                        "email_verified": true,
+                        "avatar": "",
+                        "status": "enabled",
+                        "account_role_ids": [
+                          2,
+                          6
+                        ],
+                        "created_at": 1752030749,
+                        "updated_at": 1775962064,
+                        "ref_id": "",
+                        "is_external": false
+                      },
+                      {
+                        "account_id": 2451002751131,
+                        "member_id": 2476444212131,
+                        "member_name": "Alice",
+                        "country_code": "CN",
+                        "phone": "+86185****0300",
+                        "email": "alice@example.com",
+                        "phone_verified": true,
+                        "email_verified": true,
+                        "avatar": "/image/avatar1.png",
+                        "status": "enabled",
+                        "account_role_ids": [
+                          6
+                        ],
+                        "created_at": 1701399971,
+                        "updated_at": 1775809507,
+                        "ref_id": "",
+                        "is_external": false
+                      }
+                    ]
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -46448,6 +48110,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -46455,108 +48120,63 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Invite members",
-        "tags": [
-          "Platform/Members"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Members Manage** (`organization`) |\n\n## Usage\n\n- `country_code` must be an ISO 3166-1 alpha-2 region code (e.g. \"CN\"). It is validated and normalized to upper case before storage; invalid values are rejected with a 400.\n- When a member's `phone` has no \"+\" prefix, it is parsed with that member's `country_code` as the region hint (defaults to \"CN\" when omitted).",
-          "href": "/en/api-reference/platform/members/member-invite",
-          "metadata": {
-            "sidebarTitle": "Invite members"
-          }
-        }
-      }
-    },
-    "/member/list": {
-      "post": {
-        "description": "Return a paginated list of organization members.",
-        "operationId": "memberList",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {
-                "limit": 5,
-                "p": 1
-              },
               "schema": {
                 "$ref": "#/components/schemas/MemberListRequest"
+              },
+              "example": {
+                "p": 1,
+                "limit": 5
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/member/role/grant": {
+      "post": {
+        "operationId": "memberGrantRole",
+        "summary": "Grant role to member",
+        "description": "Add one or more roles to a member's existing role assignments.",
+        "tags": [
+          "Platform/Members"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Members Manage** (`organization`) |\n\n## Usage\n\n- Role IDs that do not exist are ignored; if none of them exist, the call succeeds without changes.\n- Roles the member already holds are kept once; no duplicates are added.\n- Members provisioned through SSO cannot be changed while the SSO configuration marks them non-editable; the call returns `400`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "href": "/en/api-reference/platform/members/member-grant-role",
+          "metadata": {
+            "sidebarTitle": "Grant role to member"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "items": [
-                      {
-                        "account_id": 2451002751131,
-                        "account_role_ids": [
-                          2,
-                          6
-                        ],
-                        "avatar": "",
-                        "country_code": "",
-                        "created_at": 1752030749,
-                        "email": "bob@example.com",
-                        "email_verified": true,
-                        "is_external": false,
-                        "member_id": 5068740052131,
-                        "member_name": "Bob",
-                        "phone": "+86151****6519",
-                        "phone_verified": true,
-                        "ref_id": "",
-                        "status": "enabled",
-                        "updated_at": 1775962064
-                      },
-                      {
-                        "account_id": 2451002751131,
-                        "account_role_ids": [
-                          6
-                        ],
-                        "avatar": "/image/avatar1.png",
-                        "country_code": "CN",
-                        "created_at": 1701399971,
-                        "email": "alice@example.com",
-                        "email_verified": true,
-                        "is_external": false,
-                        "member_id": 2476444212131,
-                        "member_name": "Alice",
-                        "phone": "+86185****0300",
-                        "phone_verified": true,
-                        "ref_id": "",
-                        "status": "enabled",
-                        "updated_at": 1775809507
-                      }
-                    ],
-                    "limit": 5,
-                    "p": 1,
-                    "total": 148
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/MemberListResponse"
+                          "$ref": "#/components/schemas/MemberEmptyObject"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -46564,6 +48184,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -46571,65 +48194,65 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "List members",
-        "tags": [
-          "Platform/Members"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |",
-          "href": "/en/api-reference/platform/members/member-list",
-          "metadata": {
-            "sidebarTitle": "List members"
-          }
-        }
-      }
-    },
-    "/member/role/grant": {
-      "post": {
-        "description": "Add role assignments to a member. Role IDs that do not exist are silently ignored; if none resolve, the call is a no-op success.",
-        "operationId": "memberGrantRole",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/MemberRoleGrantRequest"
+              },
               "example": {
                 "member_id": 5068740052131,
                 "role_ids": [
                   6
                 ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/MemberRoleGrantRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/member/role/revoke": {
+      "post": {
+        "operationId": "memberRevokeRole",
+        "summary": "Revoke role from member",
+        "description": "Remove one or more roles from a member's role assignments.",
+        "tags": [
+          "Platform/Members"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Members Manage** (`organization`) |\n\n## Usage\n\n- Role IDs that do not exist are ignored; if none of them exist, the call succeeds without changes.\n- Revoking every role leaves the member with no roles; it does not fall back to Viewer.\n- Members provisioned through SSO cannot be changed while the SSO configuration marks them non-editable; the call returns `400`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "href": "/en/api-reference/platform/members/member-revoke-role",
+          "metadata": {
+            "sidebarTitle": "Revoke role from member"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/MemberEmptyObject"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -46637,6 +48260,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -46644,65 +48270,65 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Grant role to member",
-        "tags": [
-          "Platform/Members"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Members Manage** (`organization`) |",
-          "href": "/en/api-reference/platform/members/member-grant-role",
-          "metadata": {
-            "sidebarTitle": "Grant role to member"
-          }
-        }
-      }
-    },
-    "/member/role/revoke": {
-      "post": {
-        "description": "Remove role assignments from a member. Role IDs that do not exist are silently ignored; if none resolve, the call is a no-op success.",
-        "operationId": "memberRevokeRole",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/MemberRoleRevokeRequest"
+              },
               "example": {
                 "member_id": 5068740052131,
                 "role_ids": [
                   6
                 ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/MemberRoleRevokeRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/member/role/update": {
+      "post": {
+        "operationId": "memberUpdateRole",
+        "summary": "Update member roles",
+        "description": "Replace a member's role assignments with the given set of roles.",
+        "tags": [
+          "Platform/Members"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Members Manage** (`organization`) |\n\n## Usage\n\n- An empty or omitted `role_ids` assigns the built-in Viewer role (`8`).\n- Role IDs that do not exist are dropped; if none of the given IDs exist, the member ends up with no roles.\n- Members provisioned through SSO cannot be changed while the SSO configuration marks them non-editable; the call returns `400`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "href": "/en/api-reference/platform/members/member-update-role",
+          "metadata": {
+            "sidebarTitle": "Update member roles"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/MemberEmptyObject"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -46710,6 +48336,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -46717,66 +48346,88 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Revoke role from member",
-        "tags": [
-          "Platform/Members"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Members Manage** (`organization`) |",
-          "href": "/en/api-reference/platform/members/member-revoke-role",
-          "metadata": {
-            "sidebarTitle": "Revoke role from member"
-          }
-        }
-      }
-    },
-    "/member/role/update": {
-      "post": {
-        "description": "Replace all role assignments for a member at once. Role IDs that do not exist are silently dropped; an empty `role_ids` resets the member to the built-in Viewer role (ID 8).",
-        "operationId": "memberUpdateRole",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/MemberRoleUpdateRequest"
+              },
               "example": {
                 "member_id": 5068740052131,
                 "role_ids": [
                   2,
                   6
                 ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/MemberRoleUpdateRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/monit/datasource/create": {
+      "post": {
+        "operationId": "monit-datasource-write-create",
+        "summary": "Create datasource",
+        "description": "Create a monitoring datasource of one of 15 supported types and bind it to a Monitors edge cluster.",
+        "tags": [
+          "Monitors/Data sources"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Datasources Manage** (`monit`) |\n\n## Usage\n\n- `type_ident` must be one of: `prometheus`, `loki`, `mysql`, `oracle`, `postgres`, `clickhouse`, `elasticsearch`, `sls`, `tencent_cls`, `victorialogs`, `redis_node`, `redis_sentinel`, `mongodb_mongod`, `mongodb_mongos`, `kafka`. The last five (`redis_node`, `redis_sentinel`, `mongodb_mongod`, `mongodb_mongos`, `kafka`) are diagnostic-only: they cannot evaluate alerts, so `alerting_enabled` must not be `true`.\n- `name` must be unique within the account across all types; a duplicate fails with `InvalidParameter`.\n- `edge_cluster_name` must be an existing Monitors edge cluster of the account; that cluster evaluates rules and runs queries for the datasource.\n- Put the type-specific settings in `payload.<type_ident>`. For `elasticsearch`, `payload.elasticsearch.deployment` is required (`cloud` or `self-managed`). `tencent_cls` requires every edge instance in the cluster to run Monitors edge v0.66.0 or later.\n- Omitted `enabled` defaults to `true`; omitted `alerting_enabled` defaults to `true` for alerting types and `false` for diagnostic-only types. Explicit `null` for either is rejected.\n- `manage_team_id` and `readonly_team_ids` restrict who can manage or query the datasource; omit both to leave it open to every member.\n- Responses return credentials of non-diagnostic types (for example Prometheus Basic Auth passwords) as stored. Diagnostic passwords and Kafka private keys are returned only when they are `${env:NAME}` references. Treat responses as sensitive.\n- Every call is recorded in the account audit log.",
+          "href": "/en/api-reference/monitors/data-sources/monit-datasource-write-create",
+          "metadata": {
+            "sidebarTitle": "Create datasource"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/MemberEmptyObject"
+                          "$ref": "#/components/schemas/DataSourceItem"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "id": 10,
+                    "account_id": 10023,
+                    "type_ident": "prometheus",
+                    "name": "Prometheus Prod",
+                    "enabled": true,
+                    "note": "Production Prometheus",
+                    "address": "http://prometheus.example.com:9090",
+                    "payload": {
+                      "prometheus": {
+                        "basic_auth_enabled": false,
+                        "basic_auth_username": "",
+                        "basic_auth_password": "",
+                        "tls_skip_verify": false
+                      }
+                    },
+                    "edge_cluster_name": "default",
+                    "updated_at": 1712000000,
+                    "alerting_enabled": true,
+                    "manage_team_id": null,
+                    "readonly_team_ids": null,
+                    "creator_id": 20001
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -46784,6 +48435,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -46791,79 +48445,71 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Update member roles",
-        "tags": [
-          "Platform/Members"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Members Manage** (`organization`) |",
-          "href": "/en/api-reference/platform/members/member-update-role",
-          "metadata": {
-            "sidebarTitle": "Update member roles"
-          }
-        }
-      }
-    },
-    "/monit/datasource/create": {
-      "post": {
-        "description": "Create a new monitoring data source. The `payload` must include the type-specific configuration block. Supports diagnostic types redis_node, redis_sentinel, mongodb_mongod, mongodb_mongos and kafka; enabled and alerting_enabled are independent.",
-        "operationId": "monit-datasource-write-create",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/DataSourceUpsertRequest"
+              },
               "example": {
-                "address": "http://prometheus.example.com:9090",
-                "edge_cluster_name": "default",
+                "type_ident": "prometheus",
                 "name": "Prometheus Prod",
                 "note": "Production Prometheus",
+                "address": "http://prometheus.example.com:9090",
+                "edge_cluster_name": "default",
                 "payload": {
                   "prometheus": {
                     "basic_auth_enabled": false
                   }
-                },
-                "type_ident": "prometheus"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/DataSourceUpsertRequest"
+                }
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/monit/datasource/delete": {
+      "post": {
+        "operationId": "monit-datasource-write-delete",
+        "summary": "Delete datasource",
+        "description": "Delete a datasource by ID; alert rules that reference it are not blocked.",
+        "tags": [
+          "Monitors/Data sources"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Datasources Manage** (`monit`) |\n\n## Usage\n\n- Alert rules that reference the datasource are not blocked or edited; their open alerts on it are closed automatically.\n- Deleting an ID that does not exist succeeds as a no-op; an ID in another account returns `ResourceNotFound`.\n- Only the account owner, Admin members, the creator and members of the managing team can delete a datasource (anyone with the permission when no managing team is set); others get `AccessDenied`.\n- Every call is recorded in the account audit log.",
+          "href": "/en/api-reference/monitors/data-sources/monit-datasource-write-delete",
+          "metadata": {
+            "sidebarTitle": "Delete datasource"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "alerting_enabled": true,
-                    "edge_cluster_name": "default",
-                    "enabled": true,
-                    "id": 10,
-                    "name": "Prometheus Prod",
-                    "type_ident": "prometheus",
-                    "updated_at": 1712000000
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/DataSourceItem"
+                          "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -46871,6 +48517,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -46878,151 +48527,84 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Create datasource",
-        "tags": [
-          "Monitors/Data sources"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Datasources Manage** (`monit`) |\n\n## Usage\n\n- `type_ident` must be one of: `prometheus`, `loki`, `mysql`, `oracle`, `postgres`, `clickhouse`, `elasticsearch`, `sls`, `tencent_cls`, `victorialogs`, `redis_node`, `redis_sentinel`, `mongodb_mongod`, `mongodb_mongos`, `kafka`.\n- `edge_cluster_name` specifies which Monitors edge cluster evaluates rules using this datasource.\n- For `elasticsearch`, set `payload.elasticsearch.deployment` to `cloud` or `self-managed`.\n- Every call is recorded in the account audit log. Use credential fields only for connection credentials.\n\nSee the request/response schemas for all supported types and credential handling. Diagnostic-only types cannot enable alerting. On create omitted enabled defaults to true; on update omission preserves the current value. Explicit null for enabled or alerting_enabled is invalid. Diagnostic passwords and Kafka private keys are omitted from responses unless they are environment references; omit these secrets on update to preserve them, or send an empty string to clear. Other datasource credentials may be returned and must be handled as sensitive.",
-          "href": "/en/api-reference/monitors/data-sources/monit-datasource-write-create",
-          "metadata": {
-            "sidebarTitle": "Create datasource"
-          }
-        }
-      }
-    },
-    "/monit/datasource/delete": {
-      "post": {
-        "description": "Delete a data source by ID. Alert rules referencing this datasource are not blocked: the datasource is removed from their monitoring scope and their open alerts on it are closed automatically.",
-        "operationId": "monit-datasource-write-delete",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {
-                "id": 10
-              },
               "schema": {
                 "$ref": "#/components/schemas/IDRequest"
+              },
+              "example": {
+                "id": 10
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/monit/datasource/info": {
+      "post": {
+        "operationId": "monit-datasource-read-info",
+        "summary": "Get datasource detail",
+        "description": "Return one datasource by ID, including its full `payload` configuration.",
+        "tags": [
+          "Monitors/Data sources"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Datasources Read** (`monit`) |\n\n## Usage\n\n- Requires manage access to the datasource (see `manage_team_id`); members who can only query it get `AccessDenied`. Use `/monit/datasource/list` for the datasources you can query.\n- The response is sensitive: `payload` holds connection settings, and credentials of non-diagnostic types are returned as stored. Diagnostic passwords and Kafka private keys are returned only when they are `${env:NAME}` references; `tencent_cls` `secret_key` is returned as an empty string unless it is a `${env:NAME}` reference.\n- An unknown ID, or one in another account, returns `ResourceNotFound`.",
+          "href": "/en/api-reference/monitors/data-sources/monit-datasource-read-info",
+          "metadata": {
+            "sidebarTitle": "Get datasource detail"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/EmptyResponse"
+                          "$ref": "#/components/schemas/DataSourceItem"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
-                }
-              }
-            },
-            "description": "Success"
-          },
-          "400": {
-            "$ref": "#/components/responses/BadRequest"
-          },
-          "401": {
-            "$ref": "#/components/responses/Unauthorized"
-          },
-          "429": {
-            "$ref": "#/components/responses/TooManyRequests"
-          },
-          "500": {
-            "$ref": "#/components/responses/ServerError"
-          }
-        },
-        "summary": "Delete datasource",
-        "tags": [
-          "Monitors/Data sources"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Datasources Manage** (`monit`) |\n\n## Usage\n\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
-          "href": "/en/api-reference/monitors/data-sources/monit-datasource-write-delete",
-          "metadata": {
-            "sidebarTitle": "Delete datasource"
-          }
-        }
-      }
-    },
-    "/monit/datasource/info": {
-      "post": {
-        "description": "Retrieve full details of a single data source by its ID, including the `payload` configuration with its configured connection and authentication settings; treat the response as sensitive and avoid logging or forwarding it. Supports diagnostic types redis_node, redis_sentinel, mongodb_mongod, mongodb_mongos and kafka; enabled and alerting_enabled are independent.",
-        "operationId": "monit-datasource-read-info",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "id": 10
-              },
-              "schema": {
-                "$ref": "#/components/schemas/IDRequest"
-              }
-            }
-          },
-          "required": true
-        },
-        "responses": {
-          "200": {
-            "content": {
-              "application/json": {
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
-                    "account_id": 10023,
-                    "address": "http://prometheus.example.com:9090",
-                    "alerting_enabled": true,
-                    "edge_cluster_name": "default",
-                    "enabled": true,
                     "id": 10,
+                    "account_id": 10023,
+                    "type_ident": "prometheus",
                     "name": "Prometheus Prod",
+                    "enabled": true,
                     "note": "Production Prometheus",
+                    "address": "http://prometheus.example.com:9090",
                     "payload": {
                       "prometheus": {
                         "basic_auth_enabled": false,
-                        "basic_auth_password": "",
                         "basic_auth_username": "",
+                        "basic_auth_password": "",
                         "tls_skip_verify": false
                       }
                     },
-                    "type_ident": "prometheus",
-                    "updated_at": 1712000000
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/DataSourceItem"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                    "edge_cluster_name": "default",
+                    "updated_at": 1712000000,
+                    "alerting_enabled": true,
+                    "manage_team_id": null,
+                    "readonly_team_ids": null,
+                    "creator_id": 20001
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -47030,6 +48612,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -47037,76 +48622,80 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Get datasource detail",
-        "tags": [
-          "Monitors/Data sources"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Datasources Read** (`monit`) |\n\nSee the request/response schemas for all supported types and credential handling. Diagnostic-only types cannot enable alerting. On create omitted enabled defaults to true; on update omission preserves the current value. Explicit null for enabled or alerting_enabled is invalid. Diagnostic passwords and Kafka private keys are omitted from responses unless they are environment references; omit these secrets on update to preserve them, or send an empty string to clear. Other datasource credentials may be returned and must be handled as sensitive.",
-          "href": "/en/api-reference/monitors/data-sources/monit-datasource-read-info",
-          "metadata": {
-            "sidebarTitle": "Get datasource detail"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/IDRequest"
+              },
+              "example": {
+                "id": 10
+              }
+            }
           }
         }
       }
     },
     "/monit/datasource/list": {
       "post": {
-        "description": "Return all data sources for the current account. Optionally filter by `type_ident`. Supports diagnostic types redis_node, redis_sentinel, mongodb_mongod, mongodb_mongos and kafka; enabled and alerting_enabled are independent.",
         "operationId": "monit-datasource-read-list",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "type": "prometheus"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/DataSourceListRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "List datasources",
+        "description": "List the account's datasources that the caller can query, optionally filtered by type or exact name.",
+        "tags": [
+          "Monitors/Data sources"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Datasources Read** (`monit`) |\n\n## Usage\n\n- Omit `type` and `name` to return every datasource you can query; `type` and `name` are exact-match filters. An unrecognized `type` returns an empty array. The result is not paginated.\n- Only datasources the caller can query are returned (see `readonly_team_ids`); each item carries `my_perm` (`manage` or `readonly`).\n- `payload` is always `null` in list items. Use `/monit/datasource/info` to read the configuration of a datasource you can manage.",
+          "href": "/en/api-reference/monitors/data-sources/monit-datasource-read-list",
+          "metadata": {
+            "sidebarTitle": "List datasources"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": [
-                    {
-                      "account_id": 10023,
-                      "address": "http://prometheus.example.com:9090",
-                      "alerting_enabled": true,
-                      "edge_cluster_name": "default",
-                      "enabled": true,
-                      "id": 10,
-                      "name": "Prometheus Prod",
-                      "note": "Production Prometheus",
-                      "payload": null,
-                      "type_ident": "prometheus",
-                      "updated_at": 1712000000
-                    }
-                  ],
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/DataSourceListResponse"
                         }
-                      },
-                      "type": "object"
+                      }
+                    }
+                  ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": [
+                    {
+                      "id": 10,
+                      "account_id": 10023,
+                      "type_ident": "prometheus",
+                      "name": "Prometheus Prod",
+                      "enabled": true,
+                      "note": "Production Prometheus",
+                      "address": "http://prometheus.example.com:9090",
+                      "payload": null,
+                      "edge_cluster_name": "default",
+                      "updated_at": 1712000000,
+                      "alerting_enabled": true,
+                      "manage_team_id": null,
+                      "readonly_team_ids": null,
+                      "creator_id": 20001,
+                      "my_perm": "manage"
                     }
                   ]
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -47114,6 +48703,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -47121,68 +48713,65 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "List datasources",
-        "tags": [
-          "Monitors/Data sources"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Datasources Read** (`monit`) |\n\n## Usage\n\n- Omit `type_ident` to return all types.\n- Sensitive credential fields (passwords, keys) are not returned in the list response.\n\nSee the request/response schemas for all supported types and credential handling. Diagnostic-only types cannot enable alerting. On create omitted enabled defaults to true; on update omission preserves the current value. Explicit null for enabled or alerting_enabled is invalid. Diagnostic passwords and Kafka private keys are omitted from responses unless they are environment references; omit these secrets on update to preserve them, or send an empty string to clear. Other datasource credentials may be returned and must be handled as sensitive.",
-          "href": "/en/api-reference/monitors/data-sources/monit-datasource-read-list",
-          "metadata": {
-            "sidebarTitle": "List datasources"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/DataSourceListRequest"
+              },
+              "example": {
+                "type": "prometheus"
+              }
+            }
           }
         }
       }
     },
     "/monit/datasource/sls/logstores": {
       "post": {
-        "description": "List logstores within an SLS project for the specified SLS datasource.",
         "operationId": "monit-datasource-read-sls-logstores",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "id": 10,
-                "offset": 0,
-                "project": "project-a",
-                "size": 50
-              },
-              "schema": {
-                "$ref": "#/components/schemas/SLSLogstoresRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "List SLS logstores",
+        "description": "List logstores within an SLS project for the specified SLS datasource.",
+        "tags": [
+          "Monitors/Data sources"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Datasources Read** (`monit`) |\n\n## Usage\n\n- The datasource identified by `id` must be of type `sls`; other types fail with `InvalidParameter`.\n- Supply `project` to select the SLS project whose logstores to list; use `offset` and `size` to paginate. The response is a plain array of logstore names.\n- The request is relayed to the Monitors edge cluster of the datasource, which calls Alibaba Cloud with the stored credentials; it times out after 30 seconds. Fails with `InvalidParameter` when no edge instance of that cluster is online, and with HTTP 503 `ServiceUnavailable` when the edge version does not support metadata discovery.",
+          "href": "/en/api-reference/monitors/data-sources/monit-datasource-read-sls-logstores",
+          "metadata": {
+            "sidebarTitle": "List SLS logstores"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": [
-                    "logstore-1",
-                    "logstore-2"
-                  ],
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/SLSLogstoresResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": [
+                    "logstore-1",
+                    "logstore-2"
+                  ]
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -47190,6 +48779,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -47197,88 +48789,88 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "List SLS logstores",
-        "tags": [
-          "Monitors/Data sources"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Datasources Read** (`monit`) |\n\n## Usage\n\n- The datasource identified by `id` must be of type `sls`.\n- Supply `project` to select the SLS project whose logstores to list.",
-          "href": "/en/api-reference/monitors/data-sources/monit-datasource-read-sls-logstores",
-          "metadata": {
-            "sidebarTitle": "List SLS logstores"
-          }
-        }
-      }
-    },
-    "/monit/datasource/sls/projects": {
-      "post": {
-        "description": "List Alibaba Cloud SLS (Simple Log Service) projects available in the specified SLS datasource.",
-        "operationId": "monit-datasource-read-sls-projects",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/SLSLogstoresRequest"
+              },
               "example": {
                 "id": 10,
+                "project": "project-a",
                 "offset": 0,
-                "query": "",
                 "size": 50
-              },
-              "schema": {
-                "$ref": "#/components/schemas/SLSProjectsRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/monit/datasource/sls/projects": {
+      "post": {
+        "operationId": "monit-datasource-read-sls-projects",
+        "summary": "List SLS projects",
+        "description": "List Alibaba Cloud SLS (Simple Log Service) projects available in the specified SLS datasource.",
+        "tags": [
+          "Monitors/Data sources"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Datasources Read** (`monit`) |\n\n## Usage\n\n- The datasource identified by `id` must be of type `sls`; other types fail with `InvalidParameter`.\n- Use `query` to filter the project list and `offset` and `size` to paginate; `count` is the number of projects in the page and `total` the number matching the filter.\n- The request is relayed to the Monitors edge cluster of the datasource, which calls Alibaba Cloud with the stored credentials; it times out after 30 seconds. Fails with `InvalidParameter` when no edge instance of that cluster is online, and with HTTP 503 `ServiceUnavailable` when the edge version does not support metadata discovery.",
+          "href": "/en/api-reference/monitors/data-sources/monit-datasource-read-sls-projects",
+          "metadata": {
+            "sidebarTitle": "List SLS projects"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/SLSProjectsResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
-                    "count": 2,
                     "projects": [
                       {
-                        "createTime": "1710000000",
+                        "projectName": "project-a",
                         "description": "Production logs",
-                        "lastModifyTime": "1712000000",
+                        "status": "Normal",
                         "owner": "",
-                        "projectName": "project-a",
                         "region": "cn-shanghai",
-                        "status": "Normal"
+                        "createTime": "1710000000",
+                        "lastModifyTime": "1712000000"
                       },
                       {
-                        "createTime": "1710000000",
+                        "projectName": "project-b",
                         "description": "Staging logs",
-                        "lastModifyTime": "1712000000",
+                        "status": "Normal",
                         "owner": "",
-                        "projectName": "project-b",
                         "region": "cn-shanghai",
-                        "status": "Normal"
+                        "createTime": "1710000000",
+                        "lastModifyTime": "1712000000"
                       }
                     ],
+                    "count": 2,
                     "total": 2
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/SLSProjectsResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -47286,6 +48878,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -47293,15 +48888,20 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "List SLS projects",
-        "tags": [
-          "Monitors/Data sources"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Datasources Read** (`monit`) |\n\n## Usage\n\n- The datasource identified by `id` must be of type `sls`.\n- Use `query` to filter projects by name prefix. Use `offset` and `size` for pagination.",
-          "href": "/en/api-reference/monitors/data-sources/monit-datasource-read-sls-projects",
-          "metadata": {
-            "sidebarTitle": "List SLS projects"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/SLSProjectsRequest"
+              },
+              "example": {
+                "id": 10,
+                "query": "",
+                "offset": 0,
+                "size": 50
+              }
+            }
           }
         }
       }
@@ -47389,7 +48989,7 @@
                               {
                                 "labels": {
                                   "__name__": "up",
-                                  "instance": "10.101.214.50:7070"
+                                  "instance": "203.0.113.10:9090"
                                 },
                                 "value": 1
                               }
@@ -47513,7 +49113,7 @@
           "Monitors/Data sources"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **2,000 requests/minute**; **32 requests/second** per account |\n| Permissions | **Datasources Read** (`monit`) |\n\nUse datasource IDs from `/monit/datasource/list`. Disabled datasources return `datasource_disabled`; `alerting_enabled=false` does not block tools. Errors use non-2xx HTTP status and `error.code`, `error.message`, `error.reason`. `tool_not_supported` indicates the selected executor does not provide this tool; it is not a vendor permission error. Never retry through another Edge or the legacy diagnose endpoint automatically.\n\n## Usage\n\n- Two tool families share this entry: diagnostic tools defined by the executing Edge (e.g. `mysql.overview`, `prometheus.metric_trends`) and query tools named `<type>.query`. The tool prefix must match the datasource type.\n- Query tools require the Edge cluster to support Explore queries (protocol milestone v0.68.0); diagnostic tools require the v0.71.0 base invoke protocol. Unsupported clusters fail with `edge_upgrade_required`, `mixed_edge_versions`, or `edge_version_unknown`; never fall back to `/monit/query/data` or another endpoint automatically.\n- For query tools, `params` follows the per-datasource schema named in the `tool` field description. `expr` and `execution` are always required. `limit`/`direction` only bound raw-log retrieval, never SQL rows or scanned data. Unknown extension fields are tolerated but never executed or forwarded.\n- Query `data` is the complete Explore result: `format` is `explore_result.v1` and `result.kind` is `samples`, `frames`, or `logs`; log results keep `applied_limit` and `has_more`. Query results never synthesize `summary` or `truncated`.\n- Request body limit 128 KiB; complete success response limit 10 MiB for both families; diagnostic tool timeout at most 25 seconds.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **2,000 requests/minute**; **32 requests/second** per account |\n| Permissions | **Datasources Read** (`monit`) |\n\nUse datasource IDs from `/monit/datasource/list`. Disabled datasources return `datasource_disabled`; `alerting_enabled=false` does not block tools. Errors use non-2xx HTTP status and `error.code`, `error.message`, `error.reason`. `tool_not_supported` indicates the selected executor does not provide this tool; it is not a vendor permission error. Never retry through another Edge or the legacy diagnose endpoint automatically.\n\n## Usage\n\n- The caller needs query access to the datasource (see `readonly_team_ids` on the datasource); without it the call fails with 403 `access_denied`. A datasource in another account returns 404 `datasource_not_found`.\n- Diagnostic tools exist only for datasource types `mysql`, `postgres`, `redis_node`, `redis_sentinel`, `mongodb_mongod`, `mongodb_mongos`, `kafka`, `elasticsearch`, `prometheus`, `loki` and `victorialogs`; `oracle`, `clickhouse`, `sls` and `tencent_cls` support only their `<type>.query` tool. Other combinations fail with `invalid_request`.\n- Two tool families share this entry: diagnostic tools defined by the executing Edge (e.g. `mysql.overview`, `prometheus.metric_trends`) and query tools named `<type>.query`. The tool prefix must match the datasource type.\n- Query tools require the Edge cluster to support Explore queries (protocol milestone v0.68.0); diagnostic tools require the v0.71.0 base invoke protocol. Unsupported clusters fail with `edge_upgrade_required`, `mixed_edge_versions`, or `edge_version_unknown`; never fall back to `/monit/query/data` or another endpoint automatically.\n- For query tools, `params` follows the per-datasource schema named in the `tool` field description. `expr` and `execution` are always required. `limit`/`direction` only bound raw-log retrieval, never SQL rows or scanned data. Unknown extension fields are tolerated but never executed or forwarded.\n- Query `data` is the complete Explore result: `format` is `explore_result.v1` and `result.kind` is `samples`, `frames`, or `logs`; log results keep `applied_limit` and `has_more`. Query results never synthesize `summary` or `truncated`.\n- Request body limit 128 KiB; complete success response limit 10 MiB for both families; diagnostic tool timeout at most 25 seconds.",
           "href": "/en/api-reference/monitors/data-sources/monit-datasource-tools-invoke",
           "metadata": {
             "sidebarTitle": "Invoke datasource tool"
@@ -47523,65 +49123,67 @@
     },
     "/monit/datasource/update": {
       "post": {
-        "description": "Update an existing data source. Supply `id` plus the fields to change. Supports diagnostic types redis_node, redis_sentinel, mongodb_mongod, mongodb_mongos and kafka; enabled and alerting_enabled are independent.",
         "operationId": "monit-datasource-write-update",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "address": "http://prometheus-v2.example.com:9090",
-                "edge_cluster_name": "default",
-                "id": 10,
-                "name": "Prometheus Prod v2",
-                "note": "Updated",
-                "payload": {
-                  "prometheus": {
-                    "basic_auth_enabled": false
-                  }
-                },
-                "type_ident": "prometheus"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/DataSourceUpsertRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "Update datasource",
+        "description": "Update a datasource by ID, replacing its name, note, address, payload and edge cluster.",
+        "tags": [
+          "Monitors/Data sources"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Datasources Manage** (`monit`) |\n\n## Usage\n\n- This is a full replace, not a patch: send `type_ident`, `name`, `edge_cluster_name`, `payload` and (except for Elasticsearch `cloud`) `address` on every call. `note`, `address` and `payload` overwrite the stored values, so an omitted `note` is cleared.\n- Omitting `enabled`, `alerting_enabled`, `manage_team_id` or `readonly_team_ids` keeps the current value. `null` for `enabled` or `alerting_enabled` is rejected; `null` for the two team fields clears them.\n- Secrets: for the diagnostic types, omit the password (and the Kafka `tls_key`) to keep the stored value or send an empty string to clear it. For `tencent_cls`, an omitted or empty `secret_key` keeps the stored key. Other types need their credentials resent.\n- Setting `enabled` or `alerting_enabled` to `false`, or changing `type_ident` or `edge_cluster_name`, closes open alerts of the rules that use this datasource. Renaming it closes open alerts of rules whose `ds_list` name pattern no longer matches the new name.\n- Turning `alerting_enabled` off fails with HTTP 409 `UndonedOrderExist` while an enabled alert rule still selects the datasource.\n- Only the account owner, Admin members, the creator and members of the managing team can update a datasource (anyone with the permission when no managing team is set); others get `AccessDenied`. An unknown ID, or one in another account, returns `ResourceNotFound`.\n- Every call is recorded in the account audit log.",
+          "href": "/en/api-reference/monitors/data-sources/monit-datasource-write-update",
+          "metadata": {
+            "sidebarTitle": "Update datasource"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "alerting_enabled": true,
-                    "edge_cluster_name": "default",
-                    "enabled": true,
-                    "id": 10,
-                    "name": "Prometheus Prod v2",
-                    "type_ident": "prometheus",
-                    "updated_at": 1712100000
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/DataSourceItem"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "id": 10,
+                    "account_id": 10023,
+                    "type_ident": "prometheus",
+                    "name": "Prometheus Prod v2",
+                    "enabled": true,
+                    "note": "Updated",
+                    "address": "http://prometheus-v2.example.com:9090",
+                    "payload": {
+                      "prometheus": {
+                        "basic_auth_enabled": false,
+                        "basic_auth_username": "",
+                        "basic_auth_password": "",
+                        "tls_skip_verify": false
+                      }
+                    },
+                    "edge_cluster_name": "default",
+                    "updated_at": 1712100000,
+                    "alerting_enabled": true,
+                    "manage_team_id": null,
+                    "readonly_team_ids": null,
+                    "creator_id": 20001
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -47589,6 +49191,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -47596,15 +49201,27 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Update datasource",
-        "tags": [
-          "Monitors/Data sources"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Datasources Manage** (`monit`) |\n\n## Usage\n\n- Every call is recorded in the account audit log. Use credential fields only for connection credentials.\n\nSee the request/response schemas for all supported types and credential handling. Diagnostic-only types cannot enable alerting. On create omitted enabled defaults to true; on update omission preserves the current value. Explicit null for enabled or alerting_enabled is invalid. Diagnostic passwords and Kafka private keys are omitted from responses unless they are environment references; omit these secrets on update to preserve them, or send an empty string to clear. Other datasource credentials may be returned and must be handled as sensitive.",
-          "href": "/en/api-reference/monitors/data-sources/monit-datasource-write-update",
-          "metadata": {
-            "sidebarTitle": "Update datasource"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/DataSourceUpsertRequest"
+              },
+              "example": {
+                "id": 10,
+                "type_ident": "prometheus",
+                "name": "Prometheus Prod v2",
+                "note": "Updated",
+                "address": "http://prometheus-v2.example.com:9090",
+                "edge_cluster_name": "default",
+                "payload": {
+                  "prometheus": {
+                    "basic_auth_enabled": false
+                  }
+                }
+              }
+            }
           }
         }
       }
@@ -47615,75 +49232,71 @@
         "operationId": "monit-prometheus-read-label-values",
         "parameters": [
           {
-            "description": "Label name to enumerate values for, for example `job`.",
-            "in": "path",
             "name": "label_name",
+            "in": "path",
             "required": true,
             "schema": {
               "type": "string"
-            }
+            },
+            "description": "Label name to enumerate values for, for example `job`."
           },
           {
-            "description": "Data source ID to query. Must reference a Prometheus-compatible data source owned by the authenticated account.",
-            "in": "header",
             "name": "X-DSID",
-            "required": true,
+            "in": "header",
+            "required": false,
             "schema": {
               "type": "string"
-            }
+            },
+            "description": "Data source ID to query, as a decimal string. Must reference a Prometheus data source owned by the authenticated account. When omitted, the request is served by the platform's own Prometheus instead of one of your data sources."
           }
         ],
         "responses": {
           "200": {
+            "description": "Native Prometheus label-values response returned by the data source.",
             "content": {
               "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PrometheusLabelValuesResponse"
+                },
                 "example": {
+                  "status": "success",
                   "data": [
                     "api",
                     "db",
                     "worker"
-                  ],
-                  "status": "success"
-                },
-                "schema": {
-                  "$ref": "#/components/schemas/PrometheusLabelValuesResponse"
+                  ]
                 }
               }
-            },
-            "description": "Native Prometheus label-values response returned by the data source."
+            }
           },
           "400": {
+            "description": "The `X-DSID` header is not a number, the data source is not a Prometheus data source, or no monit-edge is registered for the data source's cluster. Returned as `text/plain`.",
             "content": {
               "text/plain": {
                 "schema": {
                   "type": "string"
                 }
               }
-            },
-            "description": "The `X-DSID` header is missing or invalid, the data source does not exist, or it is not a Prometheus data source. Returned as `text/plain`."
+            }
           },
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
-          "500": {
-            "content": {
-              "text/plain": {
-                "schema": {
-                  "type": "string"
-                }
-              }
-            },
-            "description": "The data source lookup or the proxied request failed. Returned as `text/plain`."
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
           },
-          "503": {
+          "429": {
+            "$ref": "#/components/responses/TooManyRequests"
+          },
+          "500": {
+            "description": "The data source does not exist or belongs to another account (message `data source not found`), or the data source lookup or proxied request failed. Returned as `text/plain`.",
             "content": {
               "text/plain": {
                 "schema": {
                   "type": "string"
                 }
               }
-            },
-            "description": "No monit-edge in the data source's cluster supports the data source resource proxy. Returned as `text/plain`; upgrade monit-edge."
+            }
           }
         },
         "summary": "List Prometheus label values",
@@ -47691,7 +49304,7 @@
           "Monitors/Data sources"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | Any valid `app_key` (read-only; not gated by a specific permission class) |\n| Edge requirement | Supported deployments require **monit-edge v0.35.0 or later** |\n\n## Usage\n\n- Pass the target data source in the `X-DSID` header. It must be a Prometheus-compatible data source owned by the authenticated account; use `/monit/datasource/list` to obtain its ID.\n- The 200 body is the data source's native Prometheus HTTP API payload, **not** the standard `{ request_id, data }` envelope. Failures raised before the data source is reached are returned as `text/plain` with the matching 4xx or 5xx status.\n- When `X-DSID` is omitted, the request falls back to the platform's own Prometheus proxy. Send the header to query a specific data source.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | Any valid `app_key` (read-only; not gated by a specific permission class) |\n| Edge requirement | Querying a specific data source requires **monit-edge v0.35.0 or later** |\n\n## Usage\n\n- Pass the target data source ID in the `X-DSID` header. It must belong to the authenticated account and be a Prometheus data source; use `/monit/datasource/list` to obtain its ID.\n- The 200 body is the data source's native Prometheus HTTP API payload, **not** the standard `{ request_id, data }` envelope. Query-string parameters are forwarded unchanged, so Prometheus's own parameters such as `match[]`, `start`, and `end` work.\n- When `X-DSID` is omitted, or any monit-edge of the data source's cluster is older than v0.35.0, the request is answered by the platform's own Prometheus instead of your data source. Send the header and keep monit-edge up to date to get your data source's values.\n- Failures raised before the data source is reached are returned as `text/plain` with the matching 4xx or 5xx status. A status of 400 or above returned by the data source itself is passed through with its own body.",
           "href": "/en/api-reference/monitors/data-sources/monit-prometheus-read-label-values",
           "metadata": {
             "sidebarTitle": "List Prometheus label values"
@@ -47704,41 +49317,56 @@
         "description": "Run an Explore query against a configured data source and return frames, samples, or logs.",
         "operationId": "monit-read-query-explore",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/QueryExploreRequest"
+              },
               "example": {
-                "args": {},
                 "datasource_id": 101,
+                "expr": "rate(http_requests_total[5m])",
+                "args": {},
                 "execution": {
-                  "from_ms": 1787187600000,
                   "kind": "range",
+                  "from_ms": 1787187600000,
+                  "to_ms": 1787191200000,
                   "max_data_points": 1200,
-                  "min_step_seconds": 15,
-                  "to_ms": 1787191200000
-                },
-                "expr": "rate(http_requests_total[5m])"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/QueryExploreRequest"
+                  "min_step_seconds": 15
+                }
               }
             }
-          },
-          "required": true
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/ExploreData"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
-                    "execution": {
-                      "effective_step_seconds": 60,
-                      "kind": "range"
-                    },
                     "format": "explore_result.v1",
                     "result": {
+                      "kind": "frames",
                       "frames": [
                         {
+                          "kind": "time_series",
                           "fields": [
                             {
                               "name": "time",
@@ -47749,136 +49377,111 @@
                               ]
                             },
                             {
+                              "name": "value",
+                              "type": "float",
                               "labels": {
                                 "job": "api"
                               },
-                              "name": "value",
-                              "type": "float",
                               "values": [
                                 1.25,
                                 null
                               ]
                             }
-                          ],
-                          "kind": "time_series"
+                          ]
                         }
-                      ],
-                      "kind": "frames"
-                    }
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
+                      ]
                     },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/ExploreData"
-                        }
-                      },
-                      "type": "object"
+                    "execution": {
+                      "kind": "range",
+                      "effective_step_seconds": 60
                     }
-                  ]
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
+            "description": "Standard HTTP error. `error.reason` is `invalid_request` for malformed or out-of-range parameters, a disabled data source, an unsupported data source type, or a data source without an Edge cluster. A data source ID that does not exist returns code `ResourceNotFound` without a `reason`.",
             "content": {
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ErrorResponse"
                 }
               }
-            },
-            "description": "Standard HTTP error; error.reason: invalid_request."
+            }
           },
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
           "403": {
+            "description": "The caller is not allowed to query this data source. `error.code` is `AccessDenied`; there is no `error.reason`.",
             "content": {
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ErrorResponse"
                 }
               }
-            },
-            "description": "Standard HTTP error; error.reason: access_denied."
-          },
-          "404": {
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/ErrorResponse"
-                }
-              }
-            },
-            "description": "Standard HTTP error; error.reason: datasource_not_found."
+            }
           },
           "413": {
+            "description": "Standard HTTP error. `error.reason`: `too_many_rows`, `source_too_large`, or `result_too_large`. A request body above 256 KiB also returns 413, without a `reason`.",
             "content": {
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ErrorResponse"
                 }
               }
-            },
-            "description": "Standard HTTP error; error.reason: source_too_large, result_too_large."
+            }
           },
           "429": {
+            "description": "Standard HTTP error; error.reason: overloaded.",
             "content": {
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ErrorResponse"
                 }
               }
-            },
-            "description": "Standard HTTP error; error.reason: overloaded."
+            }
           },
           "499": {
+            "description": "Standard HTTP error; error.reason: canceled.",
             "content": {
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ErrorResponse"
                 }
               }
-            },
-            "description": "Standard HTTP error; error.reason: canceled."
+            }
           },
           "500": {
+            "description": "Standard HTTP error; error.reason: internal.",
             "content": {
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ErrorResponse"
                 }
               }
-            },
-            "description": "Standard HTTP error; error.reason: internal."
+            }
           },
           "503": {
+            "description": "Standard HTTP error. `error.reason`: `no_active_edge`, `edge_version_unknown`, `edge_upgrade_required`, `mixed_edge_versions`, or `edge_unavailable`.",
             "content": {
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ErrorResponse"
                 }
               }
-            },
-            "description": "Standard HTTP error; error.reason: no_active_edge, edge_upgrade_required, mixed_edge_versions, edge_unavailable."
+            }
           },
           "504": {
+            "description": "Standard HTTP error; error.reason: timeout.",
             "content": {
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ErrorResponse"
                 }
               }
-            },
-            "description": "Standard HTTP error; error.reason: timeout."
+            }
           }
         },
         "summary": "Run Explore query",
@@ -47886,7 +49489,7 @@
           "Monitors/Diagnostics"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **100 requests/minute**; **16 requests/second** per account |\n| Permissions | **Datasources Read** (`monit`) |\n| Edge requirement | Supported deployments require **monit-edge v0.68.0 or later** |\n\n## Usage\n\n- Use this endpoint when you need the data source's native result shape; `/monit/query/data` returns the stable `query_result.v1` contract instead. Dispatch on `data.result.kind` (`frames`, `samples`, or `logs`) here.\n- `execution.kind` decides which companion fields are accepted: `instant` needs only `to_ms`, `range` requires `from_ms`, `to_ms`, and `max_data_points`, and `window` takes `from_ms` and `to_ms`. `step_seconds` is not accepted; the step is derived from `max_data_points` and `min_step_seconds`.\n- `args` carries macro substitutions such as Grafana-style variables; every value is a string.\n- A `logs` result is capped at 1,000 entries and reports `applied_limit` plus `has_more`. Time-series and sample results are capped at 1,000 items each and the whole success response at 8 MiB.\n- Query execution may take up to 35 seconds across WebAPI forwarding and Edge execution. Configure client timeouts to at least 40 seconds.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **100 requests/minute**; **16 requests/second** per account |\n| Permissions | **Datasources Read** (`monit`) |\n| Edge requirement | Supported deployments require **monit-edge v0.68.0 or later** |\n\n## Usage\n\n- Use this endpoint when you need the data source's native result shape; `/monit/query/data` returns the stable `query_result.v1` contract instead. Dispatch on `data.result.kind` (`frames`, `samples`, or `logs`) here.\n- The data source is identified by `datasource_id`. It must belong to the account, be enabled, have an Edge cluster, and be one of `prometheus`, `elasticsearch`, `loki`, `clickhouse`, `mysql`, `oracle`, `postgres`, `sls`, `victorialogs`, or `tencent_cls`. When the data source restricts querying to certain teams, only members of those teams, its managing team, and account owners or admins can query it.\n- `execution.kind` decides which companion fields are accepted: `instant` needs `to_ms` (`from_ms` is optional), `range` requires `from_ms`, `to_ms`, and `max_data_points`, and `window` requires `from_ms` and `to_ms`. When both times are given, `from_ms` must be less than `to_ms`. `step_seconds` is not accepted; the step is derived from `max_data_points` and `min_step_seconds`.\n- `args` is required (send `{}` when unused) and carries macro substitutions such as Grafana-style variables; every value is a string. Unknown or duplicate JSON keys are rejected.\n- A `logs` result is capped at 1,000 entries (100 for `sls`) and reports `applied_limit` plus `has_more`. A `frames` result holds at most 1,000 frames, 1,000 table rows in total, and 100,000 values in total; a `samples` result holds at most 1,000 samples. The request body is limited to 256 KiB and the whole success response to 10 MiB.\n- Failures use the standard error envelope. `error.reason` is a stable machine-readable value; a data source ID that does not exist returns HTTP 400 with code `ResourceNotFound` and no `reason`.\n- Query execution may take up to 35 seconds across WebAPI forwarding and Edge execution. Configure client timeouts to at least 40 seconds.",
           "href": "/en/api-reference/monitors/diagnostics/monit-read-query-explore",
           "metadata": {
             "sidebarTitle": "Run Explore query"
@@ -47896,30 +49499,58 @@
     },
     "/monit/query/data": {
       "post": {
-        "description": "Run a synchronous ad-hoc query against a configured data source and return a stable `query_result.v1` result whose natural shape is frames, records, or samples. This public API requires monit-edge v0.65.0 or later.",
         "operationId": "monit-read-query-data",
+        "summary": "Query structured data",
+        "description": "Run a synchronous ad-hoc query against a data source and return a `query_result.v1` result as frames, records, or samples.",
+        "tags": [
+          "Monitors/Diagnostics"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **100 requests/minute**; **5 requests/second** per account |\n| Permissions | Any valid `app_key` (read-only; not gated by a specific permission class) |\n| Edge requirement | Supported deployments require **monit-edge v0.65.0 or later** |\n\n## Usage\n\n- The data source is identified by `ds_type` plus `ds_name`, not by ID. It must belong to the account and be enabled. When the data source restricts querying to certain teams, only members of those teams, its managing team, and account owners or admins can query it; others get `AccessDenied`.\n- Treat **monit-edge v0.65.0** as the minimum supported Edge version for this public API. WebAPI retains migration adapters for older Edge versions: query.v2 results may still preserve frames, records, or samples, while legacy rows can expose only the information they retained. These adapters do not change the support floor; older protocols lack query.v3 cancellation and error-lifecycle semantics, and data already lost by legacy rows cannot be recovered.\n- The public response format is always `query_result.v1` and is independent of the internal Edge query protocol. Dispatch on `result.kind` (`frames`, `records`, or `samples`); do not infer the result shape from `ds_type` or the Edge version.\n- A `frames` result may contain multiple table or time-series frames. Field values are columnar and all fields in one frame have the same length.\n- A `records` result may contain nested JSON and null records. Integer literals outside JavaScript's safe integer range are returned as decimal strings.\n- A `samples` result contains label sets and instant values. A value may be a number or one of the strings `NaN`, `+Inf`, and `-Inf`.\n- Prometheus expressions are syntax-checked before the query is dispatched; an invalid expression returns HTTP 400.\n- The request body is limited to 256 KiB and the complete success response to 10 MiB; either limit returns HTTP 413. A result with more than 1,000 rows fails with HTTP 400. Narrow the time range, reduce fields, or aggregate at the source.\n- Query failures use non-2xx HTTP status codes and the standard error envelope.\n- Query execution may take up to 35 seconds across WebAPI forwarding and Edge execution. Configure client timeouts to at least 40 seconds and propagate cancellation when the caller abandons a query.",
+          "href": "/en/api-reference/monitors/diagnostics/monit-read-query-data",
+          "metadata": {
+            "sidebarTitle": "Query structured data"
+          }
+        },
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {
-                "args": {},
-                "delay_seconds": 0,
-                "ds_name": "prod-prom",
-                "ds_type": "prometheus",
-                "expr": "sum by (job) (rate(http_requests_total[5m]))"
-              },
               "schema": {
                 "$ref": "#/components/schemas/QueryDataRequest"
+              },
+              "example": {
+                "ds_type": "prometheus",
+                "ds_name": "prod-prom",
+                "expr": "sum by (job) (rate(http_requests_total[5m]))",
+                "delay_seconds": 0,
+                "args": {}
               }
             }
-          },
-          "required": true
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/QueryDataResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "format": "query_result.v1",
                     "result": {
@@ -47933,27 +49564,10 @@
                         }
                       ]
                     }
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/QueryDataResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -47965,27 +49579,27 @@
             "$ref": "#/components/responses/Forbidden"
           },
           "413": {
+            "description": "The request or final response exceeds its size limit.",
             "content": {
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ErrorResponse"
                 }
               }
-            },
-            "description": "The request or final response exceeds its size limit."
+            }
           },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
           "499": {
+            "description": "The client canceled the query.",
             "content": {
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ErrorResponse"
                 }
               }
-            },
-            "description": "The client canceled the query."
+            }
           },
           "500": {
             "$ref": "#/components/responses/ServerError"
@@ -47994,81 +49608,68 @@
             "$ref": "#/components/responses/ServiceUnavailable"
           },
           "504": {
+            "description": "The query timed out.",
             "content": {
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ErrorResponse"
                 }
               }
-            },
-            "description": "The query timed out."
-          }
-        },
-        "summary": "Query structured data",
-        "tags": [
-          "Monitors/Diagnostics"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **100 requests/minute**; **5 requests/second** per account |\n| Permissions | Any valid `app_key` (read-only; not gated by a specific permission class) |\n| Edge requirement | Supported deployments require **monit-edge v0.65.0 or later** |\n\n## Usage\n\n- Treat **monit-edge v0.65.0** as the minimum supported Edge version for this public API. WebAPI retains migration adapters for older Edge versions: query.v2 results may still preserve frames, records, or samples, while legacy rows can expose only the information they retained. These adapters do not change the support floor; older protocols lack query.v3 cancellation and error-lifecycle semantics, and data already lost by legacy rows cannot be recovered.\n- The public response format is always `query_result.v1` and is independent of the internal Edge query protocol. Dispatch on `result.kind` (`frames`, `records`, or `samples`); do not infer the result shape from `ds_type` or the Edge version.\n- A `frames` result may contain multiple table or time-series frames. Field values are columnar and all fields in one frame have the same length.\n- A `records` result may contain nested JSON and null records. Integer literals outside JavaScript's safe integer range are returned as decimal strings.\n- A `samples` result contains label sets and instant values. A value may be a number or one of the strings `NaN`, `+Inf`, and `-Inf`.\n- The final success response is limited to 8 MiB and query results are limited to 1,000 rows. Narrow the time range, reduce fields, or aggregate at the source when a request exceeds a limit.\n- Query failures use non-2xx HTTP status codes and the standard error envelope. Do not transparently fall back to the deprecated `/monit/query/rows` endpoint.\n- Query execution may take up to 35 seconds across WebAPI forwarding and Edge execution. Configure client timeouts to at least 40 seconds and propagate cancellation when the caller abandons a query.",
-          "href": "/en/api-reference/monitors/diagnostics/monit-read-query-data",
-          "metadata": {
-            "sidebarTitle": "Query structured data"
+            }
           }
         }
       }
     },
     "/monit/rule/audit/detail": {
       "post": {
-        "description": "Return the audit record (including the `content` field, a JSON string of the rule snapshot at that point in time).",
         "operationId": "monit-rule-read-audit-detail",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "id": 9001
-              },
-              "schema": {
-                "$ref": "#/components/schemas/AuditRecordIDRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "Get rule audit snapshot",
+        "description": "Return one audit record of an alert rule, including the rule snapshot stored in `content`.",
+        "tags": [
+          "Monitors/Alert rules"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Pass the audit record `id` (not the rule `id`) from `POST /monit/rule/audits`. An unknown ID returns `InvalidParameter` (`alert rule audit not found`).\n- `content` is a JSON string — parse it to get the rule snapshot; its shape depends on the operation that wrote the record (see `content` below).\n- To read a record, the caller must be able to manage the rule's folder (account owner or admin, creator of the folder or one of its ancestors, or member of the team bound to the folder or an ancestor); otherwise the call returns `AccessDenied`. Records of a deleted rule can no longer be read: the call returns `InvalidParameter` (`alert rule not found`).",
+          "href": "/en/api-reference/monitors/alert-rules/monit-rule-read-audit-detail",
+          "metadata": {
+            "sidebarTitle": "Get rule audit snapshot"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "account_id": 10023,
-                    "action": "update",
-                    "alert_rule_id": 50001,
-                    "content": "{\"id\":50001,\"name\":\"CPU High\"}",
-                    "created_at": 1712000000,
-                    "creator_id": 80011,
-                    "creator_name": "Alice",
-                    "id": 9001
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/AlertRuleAudit"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "id": 9001,
+                    "account_id": 888,
+                    "alert_rule_id": 50001,
+                    "action": "update",
+                    "content": "{\"id\":50001,\"account_id\":888,\"folder_id\":100,\"name\":\"CPU High\",\"enabled\":true,\"updated_at\":1712003600}",
+                    "creator_id": 66,
+                    "creator_name": "zhangsan",
+                    "created_at": 1712003600
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -48076,6 +49677,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -48083,72 +49687,81 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Get rule audit snapshot",
-        "tags": [
-          "Monitors/Alert rules"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Alerting Rules Read** (`monit`) |\n\n## Usage\n\n- Pass the audit record `id` (not the rule `id`) from `POST /monit/rule/audits`.\n- `content` is a JSON string — parse it to get the full rule snapshot.",
-          "href": "/en/api-reference/monitors/alert-rules/monit-rule-read-audit-detail",
-          "metadata": {
-            "sidebarTitle": "Get rule audit snapshot"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/AuditRecordIDRequest"
+              },
+              "example": {
+                "id": 9001
+              }
+            }
           }
         }
       }
     },
     "/monit/rule/audits": {
       "post": {
-        "description": "Return the change history (audit records) for an alert rule.",
         "operationId": "monit-rule-read-audits",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "id": 50001
-              },
-              "schema": {
-                "$ref": "#/components/schemas/RuleIDRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "List rule change history",
+        "description": "Return the change history (audit records) for an alert rule.",
+        "tags": [
+          "Monitors/Alert rules"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Records are ordered newest first and omit `content`; read one snapshot with `POST /monit/rule/audit/detail`.\n- A record is written on every create, full update, field update and move. Deleting a rule writes no record, and the history of a deleted rule can no longer be listed: the call returns `InvalidParameter` (`alert rule not found`).\n- The caller must be able to manage the rule's folder (account owner or admin, creator of the folder or one of its ancestors, or member of the team bound to the folder or an ancestor); otherwise the call returns `AccessDenied`.",
+          "href": "/en/api-reference/monitors/alert-rules/monit-rule-read-audits",
+          "metadata": {
+            "sidebarTitle": "List rule change history"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": [
-                    {
-                      "account_id": 10023,
-                      "action": "update",
-                      "alert_rule_id": 50001,
-                      "created_at": 1712000000,
-                      "creator_id": 80011,
-                      "creator_name": "Alice",
-                      "id": 9001
-                    }
-                  ],
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/RuleAuditListResponse"
                         }
-                      },
-                      "type": "object"
+                      }
+                    }
+                  ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": [
+                    {
+                      "id": 9001,
+                      "account_id": 888,
+                      "alert_rule_id": 50001,
+                      "action": "update",
+                      "creator_id": 66,
+                      "creator_name": "zhangsan",
+                      "created_at": 1712003600
+                    },
+                    {
+                      "id": 8990,
+                      "account_id": 888,
+                      "alert_rule_id": 50001,
+                      "action": "create",
+                      "creator_id": 66,
+                      "creator_name": "zhangsan",
+                      "created_at": 1712000000
                     }
                   ]
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -48156,6 +49769,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -48163,62 +49779,64 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "List rule change history",
-        "tags": [
-          "Monitors/Alert rules"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Alerting Rules Read** (`monit`) |",
-          "href": "/en/api-reference/monitors/alert-rules/monit-rule-read-audits",
-          "metadata": {
-            "sidebarTitle": "List rule change history"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/RuleIDRequest"
+              },
+              "example": {
+                "id": 50001
+              }
+            }
           }
         }
       }
     },
     "/monit/rule/counter/channel": {
       "post": {
-        "description": "Return an object mapping channel name to the number of rules routing alerts to that channel. If a channel name cannot be resolved, the channel ID (as a string) is used as the key.",
         "operationId": "monit-rule-read-counter-channel",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {},
-              "schema": {
-                "$ref": "#/components/schemas/RuleEmptyRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "Get rule counts by channel",
+        "description": "Return how many alert rules route alerts to each collaboration space, keyed by space name.",
+        "tags": [
+          "Monitors/Alert rules"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Monits Overview Read** (`monit`) |\n\n## Usage\n\n- Only rules with a non-empty `channel_ids` are counted; a rule routed to several spaces is counted once under each of them.\n- When a space ID cannot be resolved to a name, the ID (as a string) is used as the key. Spaces that share the same name are merged into one key.\n- Returns an empty object `{}` when no rule routes to a space.",
+          "href": "/en/api-reference/monitors/alert-rules/monit-rule-read-counter-channel",
+          "metadata": {
+            "sidebarTitle": "Get rule counts by channel"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "Production": 8
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/RuleCounterChannelResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "Production": 8
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -48226,6 +49844,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -48233,67 +49854,73 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Get rule counts by channel",
-        "tags": [
-          "Monitors/Alert rules"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Alerting Rules Read** (`monit`) |",
-          "href": "/en/api-reference/monitors/alert-rules/monit-rule-read-counter-channel",
-          "metadata": {
-            "sidebarTitle": "Get rule counts by channel"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/RuleEmptyRequest"
+              },
+              "example": {}
+            }
           }
         }
       }
     },
     "/monit/rule/counter/total": {
       "post": {
-        "description": "Return the stored time series of the total rule count across the account — one sample per `clock` timestamp.",
         "operationId": "monit-rule-read-counter-total",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {},
-              "schema": {
-                "$ref": "#/components/schemas/RuleEmptyRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "Get rule counter time series",
+        "description": "Return the stored time series of the total rule count across the account — one sample per `clock` timestamp.",
+        "tags": [
+          "Monitors/Alert rules"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Monits Overview Read** (`monit`) |\n\n## Usage\n\n- Each item is a historical snapshot: `num` is the total number of alert rules in the account (enabled and disabled) at `clock` (Unix timestamp in seconds).\n- A snapshot is recorded roughly every 12 hours (an hourly job adds one when none exists in the last 12 hours). All snapshots are returned oldest first; the array is empty until the first snapshot is recorded.",
+          "href": "/en/api-reference/monitors/alert-rules/monit-rule-read-counter-total",
+          "metadata": {
+            "sidebarTitle": "Get rule counter time series"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": [
-                    {
-                      "account_id": 10023,
-                      "clock": 1712000000,
-                      "id": 1,
-                      "num": 50
-                    }
-                  ],
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/RuleCounterTotalResponse"
                         }
-                      },
-                      "type": "object"
+                      }
+                    }
+                  ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": [
+                    {
+                      "id": 1,
+                      "account_id": 888,
+                      "num": 48,
+                      "clock": 1711956000
+                    },
+                    {
+                      "id": 2,
+                      "account_id": 888,
+                      "num": 50,
+                      "clock": 1712000000
                     }
                   ]
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -48301,6 +49928,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -48308,62 +49938,60 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Get rule counter time series",
-        "tags": [
-          "Monitors/Alert rules"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Alerting Rules Read** (`monit`) |\n\n## Usage\n\n- Each item is a historical snapshot: `num` is the total rule count at the given `clock` (Unix epoch seconds).",
-          "href": "/en/api-reference/monitors/alert-rules/monit-rule-read-counter-total",
-          "metadata": {
-            "sidebarTitle": "Get rule counter time series"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/RuleEmptyRequest"
+              },
+              "example": {}
+            }
           }
         }
       }
     },
     "/monit/rule/delete": {
       "post": {
-        "description": "Delete a single alert rule by its ID.",
         "operationId": "monit-rule-write-delete",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "id": 50001
-              },
-              "schema": {
-                "$ref": "#/components/schemas/RuleIDRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "Delete alert rule",
+        "description": "Delete a single alert rule by its ID.",
+        "tags": [
+          "Monitors/Alert rules"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Alerting Rules Manage** (`monit`) |\n\n## Usage\n\n- The rule's active alerts are cleared as part of the deletion.\n- Deleting an ID that does not exist succeeds with an empty `data`, so retries are safe.\n- The caller must be able to manage the rule's folder (account owner or admin, creator of the folder or one of its ancestors, or member of the team bound to the folder or an ancestor); otherwise the call returns `AccessDenied`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "href": "/en/api-reference/monitors/alert-rules/monit-rule-write-delete",
+          "metadata": {
+            "sidebarTitle": "Delete alert rule"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/RuleEmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -48371,6 +49999,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -48378,65 +50009,62 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Delete alert rule",
-        "tags": [
-          "Monitors/Alert rules"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Alerting Rules Manage** (`monit`) |\n\n## Usage\n\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
-          "href": "/en/api-reference/monitors/alert-rules/monit-rule-write-delete",
-          "metadata": {
-            "sidebarTitle": "Delete alert rule"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/RuleIDRequest"
+              },
+              "example": {
+                "id": 50001
+              }
+            }
           }
         }
       }
     },
     "/monit/rule/delete/batch": {
       "post": {
-        "description": "Delete multiple alert rules in a single request.",
         "operationId": "monit-rule-write-delete-batch",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "ids": [
-                  50001,
-                  50002
-                ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/RuleIDsRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "Batch delete alert rules",
+        "description": "Delete multiple alert rules in a single request.",
+        "tags": [
+          "Monitors/Alert rules"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **100 requests/minute**; **5 requests/second** per account |\n| Permissions | **Alerting Rules Manage** (`monit`) |\n\n## Usage\n\n- IDs are processed in order and the call stops at the first error; rules deleted before the error stay deleted, so fix the cause and re-send the remaining IDs.\n- IDs that do not exist are skipped without error. Each deleted rule's active alerts are cleared.\n- `ids` must contain at least one ID. For every rule, the caller must be able to manage its folder (account owner or admin, creator of the folder or one of its ancestors, or member of the team bound to the folder or an ancestor); otherwise the call returns `AccessDenied`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "href": "/en/api-reference/monitors/alert-rules/monit-rule-write-delete-batch",
+          "metadata": {
+            "sidebarTitle": "Batch delete alert rules"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/RuleEmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -48444,6 +50072,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -48451,74 +50082,90 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Batch delete alert rules",
-        "tags": [
-          "Monitors/Alert rules"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **30 requests/minute**; **5 requests/second** per account |\n| Permissions | **Alerting Rules Manage** (`monit`) |\n\n## Usage\n\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
-          "href": "/en/api-reference/monitors/alert-rules/monit-rule-write-delete-batch",
-          "metadata": {
-            "sidebarTitle": "Batch delete alert rules"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/RuleIDsRequest"
+              },
+              "example": {
+                "ids": [
+                  50001,
+                  50002
+                ]
+              }
+            }
           }
         }
       }
     },
     "/monit/rule/list/basic": {
       "post": {
-        "description": "Return the basic information of all alert rules in a folder. For full rule details, call `POST /monit/rule/v2/info`.",
         "operationId": "monit-rule-read-list",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "folder_id": 100
-              },
-              "schema": {
-                "$ref": "#/components/schemas/RuleListRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "List alert rules",
+        "description": "Return basic information for the alert rules in a folder; call `POST /monit/rule/v2/info` for full details.",
+        "tags": [
+          "Monitors/Alert rules"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Alerting Rules Read** or **Alerting Rules Manage** (`monit`) |\n\n## Usage\n\n- `folder_id` must be an existing folder: `0` or an unknown ID returns `InvalidParameter`, and a folder the caller cannot manage (account owner or admin, creator of the folder or an ancestor, or member of the team bound to it or an ancestor) returns `AccessDenied`. There is no account-wide listing.\n- By default only the rules directly in the folder are returned, sorted by name, with `active_alert_count` and `runtime_state` filled.\n- With `include_descendants: true` the call searches the folder and all its descendant folders and returns at most `limit` rules sorted by name; only `id`, `folder_id` and `name` are filled and the other fields carry zero values (`labels` is `null`, `runtime_state` is omitted).\n- `triggered` is `true` exactly when `active_alert_count > 0`.",
+          "href": "/en/api-reference/monitors/alert-rules/monit-rule-read-list",
+          "metadata": {
+            "sidebarTitle": "List alert rules"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": [
-                    {
-                      "active_alert_count": 2,
-                      "created_at": 1710000000,
-                      "ds_type": "prometheus",
-                      "enabled": true,
-                      "folder_id": 100,
-                      "id": 50001,
-                      "name": "CPU High",
-                      "runtime_state": "normal",
-                      "triggered": true
-                    }
-                  ],
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/RuleBasicListResponse"
                         }
+                      }
+                    }
+                  ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": [
+                    {
+                      "id": 50001,
+                      "account_id": 888,
+                      "folder_id": 100,
+                      "name": "CPU High",
+                      "labels": {
+                        "team": "sre"
                       },
-                      "type": "object"
+                      "ds_type": "prometheus",
+                      "enabled": true,
+                      "debug_log_enabled": false,
+                      "cron_pattern": "0 * * * * *",
+                      "timezone": "Asia/Shanghai",
+                      "delay_seconds": 0,
+                      "creator_id": 66,
+                      "creator_name": "zhangsan",
+                      "updater_id": 66,
+                      "updater_name": "zhangsan",
+                      "created_at": 1710000000,
+                      "updated_at": 1712000000,
+                      "triggered": true,
+                      "active_alert_count": 2,
+                      "runtime_state": "normal"
                     }
                   ]
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -48526,6 +50173,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -48533,71 +50183,71 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "List alert rules",
-        "tags": [
-          "Monitors/Alert rules"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Alerting Rules Read** (`monit`) |\n\n## Usage\n\n- Set `folder_id` to `0` to list all rules across all folders visible to the current user.\n- The `triggered` field indicates whether the rule has any currently active alerts.",
-          "href": "/en/api-reference/monitors/alert-rules/monit-rule-read-list",
-          "metadata": {
-            "sidebarTitle": "List alert rules"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/RuleListRequest"
+              },
+              "example": {
+                "folder_id": 100
+              }
+            }
           }
         }
       }
     },
     "/monit/rule/move": {
       "post": {
-        "description": "Move one or more alert rules to a different folder.",
         "operationId": "monit-rule-write-move",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "dest_folder_id": 200,
-                "ids": [
-                  50001,
-                  50002
-                ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/RuleMoveRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "Move alert rules to folder",
+        "description": "Move one or more alert rules to a different folder.",
+        "tags": [
+          "Monitors/Alert rules"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Alerting Rules Manage** (`monit`) |\n\n## Usage\n\n- `dest_folder_id` must be an existing folder that the caller must be able to manage the folder (account owner or admin, creator of the folder or one of its ancestors, or member of the team bound to the folder or an ancestor); otherwise the whole call fails with `AccessDenied` and nothing is moved.\n- The result has one entry per requested ID, in request order. A moved rule's `message` is a localized success text (`Move successfully` / `移动成功`); a rule that is not moved stays in its folder and its `message` carries the error.\n- A rule is not moved when a rule with the same name already exists in the destination folder, when the caller cannot manage its current folder, or when the ID does not exist (its `name` is then `id: <id>`).\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "href": "/en/api-reference/monitors/alert-rules/monit-rule-write-move",
+          "metadata": {
+            "sidebarTitle": "Move alert rules to folder"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": [
-                    {
-                      "message": "",
-                      "name": "CPU High"
-                    }
-                  ],
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/RuleNameMessageListResponse"
                         }
-                      },
-                      "type": "object"
+                      }
+                    }
+                  ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": [
+                    {
+                      "name": "CPU High",
+                      "message": "Move successfully"
+                    },
+                    {
+                      "name": "Disk High",
+                      "message": "alert rule name already exists in this folder"
                     }
                   ]
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -48605,6 +50255,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -48612,78 +50265,75 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Move alert rules to folder",
-        "tags": [
-          "Monitors/Alert rules"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Alerting Rules Manage** (`monit`) |\n\n## Usage\n\n- Rules whose names already exist in the destination folder are skipped. Inspect each result's `message` to identify conflicts.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
-          "href": "/en/api-reference/monitors/alert-rules/monit-rule-write-move",
-          "metadata": {
-            "sidebarTitle": "Move alert rules to folder"
-          }
-        }
-      }
-    },
-    "/monit/rule/update/fields": {
-      "post": {
-        "description": "Update specific fields across multiple alert rules at once. Only the fields listed in `fields` are applied.",
-        "operationId": "monit-rule-write-fields-update",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/RuleMoveRequest"
+              },
               "example": {
-                "enabled": false,
-                "fields": [
-                  "enabled"
-                ],
                 "ids": [
                   50001,
                   50002
-                ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/RuleFieldsUpdateRequest"
+                ],
+                "dest_folder_id": 200
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/monit/rule/update/fields": {
+      "post": {
+        "operationId": "monit-rule-write-fields-update",
+        "summary": "Batch update rule fields",
+        "description": "Update the fields listed in `fields` on multiple alert rules in one call.",
+        "tags": [
+          "Monitors/Alert rules"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Alerting Rules Manage** (`monit`) |\n\n## Usage\n\n- Each listed field takes the value of the same-named request field; a listed field whose value is omitted is set to its zero value (for example, listing `labels` without `labels` or `labels_patch` removes all labels). Unlisted fields keep their current values.\n- An unknown name in `fields`, a `labels_patch` / `annotations_patch` whose field is not listed in `fields`, or sending `labels` together with `labels_patch` (or `annotations` with `annotations_patch`) fails the whole call with `InvalidParameter`.\n- Rules are updated one by one and the result has one entry per ID: `message` is empty on success, otherwise it carries that rule's error (validation failure, no access to its folder, or an unknown ID, whose `name` is then `id: <id>`).\n- Setting `enabled` to `false` clears the rules' active alerts. Unless the call only disables rules (`fields` is exactly `[\"enabled\"]` with `enabled: false`), it fails with `AccessDenied` when the account exceeds its alert rule license limit, and non-admin callers need read-only access to every datasource each rule selects.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "href": "/en/api-reference/monitors/alert-rules/monit-rule-write-fields-update",
+          "metadata": {
+            "sidebarTitle": "Batch update rule fields"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": [
-                    {
-                      "message": "",
-                      "name": "CPU High"
-                    },
-                    {
-                      "message": "",
-                      "name": "Disk High"
-                    }
-                  ],
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/RuleNameMessageListResponse"
                         }
-                      },
-                      "type": "object"
+                      }
+                    }
+                  ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": [
+                    {
+                      "name": "CPU High",
+                      "message": ""
+                    },
+                    {
+                      "name": "Disk High",
+                      "message": ""
                     }
                   ]
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -48691,6 +50341,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -48698,15 +50351,24 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Batch update rule fields",
-        "tags": [
-          "Monitors/Alert rules"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Alerting Rules Manage** (`monit`) |\n\n## Usage\n\n- Include the field names you want to update in the `fields` array, e.g. `[\"enabled\", \"channel_ids\"]`.\n- Only the specified fields are updated; others are left unchanged.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
-          "href": "/en/api-reference/monitors/alert-rules/monit-rule-write-fields-update",
-          "metadata": {
-            "sidebarTitle": "Batch update rule fields"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/RuleFieldsUpdateRequest"
+              },
+              "example": {
+                "ids": [
+                  50001,
+                  50002
+                ],
+                "fields": [
+                  "enabled"
+                ],
+                "enabled": false
+              }
+            }
           }
         }
       }
@@ -48720,7 +50382,7 @@
           "Monitors/Alert rules"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Alerting Rules Read** (`monit`) |\n\n## Usage\n\n- `id` is required and must not be `0`; otherwise the call returns `InvalidParameter`.\n- A missing rule returns `InvalidParameter` (`alert rule not found`).",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Alerting Rules Read** or **Alerting Rules Manage** (`monit`) |\n\n## Usage\n\n- `id` is required and must not be `0`; otherwise the call returns `InvalidParameter`.\n- A missing rule, or a rule of another account, returns `InvalidParameter` (`alert rule not found`).\n- No folder-level check applies: any caller with the permission above can read every rule in the account.",
           "href": "/en/api-reference/monitors/alert-rules/monit-rule-read-info-v2",
           "metadata": {
             "sidebarTitle": "Get alert rule detail (V2)"
@@ -48762,6 +50424,7 @@
                     "enabled": true,
                     "debug_log_enabled": false,
                     "rule_configs": {
+                      "relate_queries": [],
                       "queries": [
                         {
                           "name": "A",
@@ -48822,6 +50485,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -48853,7 +50519,7 @@
           "Monitors/Alert rules"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Alerting Rules Manage** (`monit`) |\n\n## Usage\n\n- `name`, `ds_type`, `enabled`, `cron_pattern`, and `rule_configs.queries` are required; either `ds_list` (supports wildcards) or `ds_ids` must be non-empty.\n- `enabled` must be passed explicitly (including `false`); omitting it returns `InvalidParameter`.\n- `id`, `account_id`, `creator_*`, `updater_*`, `created_at`, and `updated_at` are assigned by the server; client-supplied values are ignored.\n- `name` must be unique within `folder_id`; a duplicate returns `InvalidParameter`.\n- `channel_ids` can be empty; alerts will then route through the global integration.\n- The request body tolerates additional unknown fields (forward compatibility); they are ignored.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Alerting Rules Manage** (`monit`) |\n\n## Usage\n\n- `folder_id`, `name`, `ds_type`, `enabled`, `cron_pattern` and `rule_configs.queries` are required, and at least one of `ds_list` (wildcards supported) or `ds_ids` must be non-empty.\n- `enabled` must be passed explicitly (including `false`); omitting it returns `InvalidParameter`.\n- `folder_id` must be an existing folder (otherwise `InvalidParameter`) and the caller must be able to manage the folder (account owner or admin, creator of the folder or one of its ancestors, or member of the team bound to the folder or an ancestor) (otherwise `AccessDenied`).\n- `name` must be unique within `folder_id`; a duplicate returns `InvalidParameter`.\n- When `enabled` is `true`, `ds_type` must be a datasource type that supports alerting and every ID in `ds_ids` must be an enabled datasource with alerting turned on; otherwise the call returns `InvalidParameter`.\n- Callers other than the account owner or admins need read-only access to every datasource listed in `ds_ids` or currently matched by `ds_list`; otherwise the call returns `AccessDenied` (`no permission to reference datasource \"<name>\"`).\n- The call fails with `AccessDenied` when creating the rule would exceed the account's alert rule license limit.\n- `id`, `account_id`, `creator_*`, `updater_*`, `created_at`, and `updated_at` are assigned by the server; client-supplied values are ignored.\n- `channel_ids` can be empty; alerts will then route through the global integration.\n- The request body may not exceed 1 MiB; a larger body returns HTTP 413 (`EntityTooLarge`). Additional unknown fields are ignored (forward compatibility).\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/monitors/alert-rules/monit-rule-write-create-v2",
           "metadata": {
             "sidebarTitle": "Create alert rule (V2)"
@@ -48895,6 +50561,7 @@
                     "enabled": true,
                     "debug_log_enabled": false,
                     "rule_configs": {
+                      "relate_queries": [],
                       "queries": [
                         {
                           "name": "A",
@@ -48955,6 +50622,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -49013,7 +50683,7 @@
           "Monitors/Alert rules"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Alerting Rules Manage** (`monit`) |\n\n## Usage\n\n- `id` is required and the rule must already exist; otherwise the call returns `InvalidParameter`.\n- This is a full-field replacement: except for the cases below, fields you omit are stored as zero values. Fetch the full configuration via `/monit/rule/v2/info` before modifying it.\n- `enabled` must be passed explicitly (including `false`); omitting it returns `InvalidParameter`. Setting it to `false` clears the rule's active alerts.\n- `investigation_targets` is the exception: omit it to keep the current value, pass `[]` to clear, or pass a value to replace it entirely.\n- `folder_id` cannot be changed through this operation; use `/monit/rule/move` to move the rule to another folder.\n- `account_id`, `creator_*`, `updater_*`, `created_at`, and `updated_at` are maintained by the server; client-supplied values are ignored.\n- `name` must be unique within `folder_id`; a duplicate returns `InvalidParameter`.\n- The request body tolerates additional unknown fields (forward compatibility); they are ignored.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Alerting Rules Manage** (`monit`) |\n\n## Usage\n\n- `id` is required and the rule must already exist; otherwise the call returns `InvalidParameter`.\n- This is a full-field replacement: except for the cases below, fields you omit are stored as zero values (then normalized, e.g. `repeat_interval` becomes 3600). Fetch the full configuration via `/monit/rule/v2/info` before modifying it.\n- `enabled` must be passed explicitly (including `false`); omitting it returns `InvalidParameter`. Setting it to `false` clears the rule's active alerts.\n- `investigation_targets` is the exception: omit it to keep the current value, pass `[]` to clear, or pass a value to replace it entirely.\n- `folder_id` cannot be changed through this operation; use `/monit/rule/move` to move the rule to another folder.\n- The caller must be able to manage the rule's folder (account owner or admin, creator of the folder or one of its ancestors, or member of the team bound to the folder or an ancestor); otherwise the call returns `AccessDenied`.\n- `name` must be unique within the rule's folder; a duplicate returns `InvalidParameter`.\n- When `enabled` is `true`, `ds_type` must be a datasource type that supports alerting and every ID in `ds_ids` must be an enabled datasource with alerting turned on; otherwise the call returns `InvalidParameter`.\n- Callers other than the account owner or admins need read-only access to every datasource listed in `ds_ids` or currently matched by `ds_list`; otherwise the call returns `AccessDenied` (`no permission to reference datasource \"<name>\"`).\n- The call fails with `AccessDenied` when the account already exceeds its alert rule license limit.\n- If the rule is modified by another request while this one is processed, the call returns HTTP 409 (`UndonedOrderExist`, `alert rule was modified; reload and retry`); fetch the rule again and retry.\n- `account_id`, `creator_*`, `updater_*`, `created_at`, and `updated_at` are maintained by the server; client-supplied values are ignored.\n- The request body may not exceed 1 MiB; a larger body returns HTTP 413 (`EntityTooLarge`). Additional unknown fields are ignored (forward compatibility).\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/monitors/alert-rules/monit-rule-write-update-v2",
           "metadata": {
             "sidebarTitle": "Update alert rule (V2)"
@@ -49055,6 +50725,7 @@
                     "enabled": true,
                     "debug_log_enabled": false,
                     "rule_configs": {
+                      "relate_queries": [],
                       "queries": [
                         {
                           "name": "A",
@@ -49115,6 +50786,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -49167,66 +50841,66 @@
     },
     "/oncall/license/list": {
       "post": {
-        "description": "List people with active fixed or temporary On-call licenses in the current account.",
         "operationId": "oncall-license-read-license-list",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {},
-              "schema": {
-                "$ref": "#/components/schemas/EmptyRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "List On-call licenses",
+        "description": "List people with active fixed or temporary On-call licenses in the current account.",
+        "tags": [
+          "On-call/Licenses"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- `items` contains only people with an active fixed or temporary On-call license.\n- For temporary licenses, `updated_by`, `created_at`, and `updated_at` are `0`.",
+          "href": "/en/api-reference/on-call/licenses/oncall-license-read-license-list",
+          "metadata": {
+            "sidebarTitle": "List On-call licenses"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/LicenseListResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01J0D5Y31GY2TWAHRP3Q8K4M6N",
                   "data": {
+                    "total": 2,
                     "items": [
                       {
-                        "created_at": 1719792000,
                         "person_id": 80011,
                         "person_name": "Yuki Zhang",
                         "type": "fixed",
-                        "updated_at": 1719878400,
-                        "updated_by": 80001
+                        "updated_by": 80001,
+                        "created_at": 1719792000,
+                        "updated_at": 1719878400
                       },
                       {
-                        "created_at": 0,
                         "person_id": 80012,
                         "person_name": "Alex Chen",
                         "type": "temporary",
-                        "updated_at": 0,
-                        "updated_by": 0
+                        "updated_by": 0,
+                        "created_at": 0,
+                        "updated_at": 0
                       }
                     ],
-                    "release_limited": false,
-                    "total": 2
-                  },
-                  "request_id": "01J0D5Y31GY2TWAHRP3Q8K4M6N"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/LicenseListResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                    "release_limited": false
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -49234,6 +50908,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -49241,91 +50918,86 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "List On-call licenses",
-        "tags": [
-          "On-call/Licenses"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- `items` contains only people with an active fixed or temporary On-call license.\n- For temporary licenses, `updated_by`, `created_at`, and `updated_at` are `0`.",
-          "href": "/en/api-reference/on-call/licenses/oncall-license-read-license-list",
-          "metadata": {
-            "sidebarTitle": "List On-call licenses"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/EmptyRequest"
+              },
+              "example": {}
+            }
           }
         }
       }
     },
     "/person/infos": {
       "post": {
-        "description": "Return profile information for a batch of person IDs (members or accounts).",
         "operationId": "personInfos",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "person_ids": [
-                  2476444212131,
-                  3790925372131
-                ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/PersonInfosRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "Batch get persons",
+        "description": "Return profile information for a batch of person IDs (members or accounts).",
+        "tags": [
+          "Platform/Members"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Including the account ID returns the account owner, with `as` `account`. Other IDs are looked up among the account's members, including removed ones (`status` `deleted`), so IDs saved in older records still resolve.\n- Duplicate IDs are deduplicated; IDs that match neither are omitted.",
+          "href": "/en/api-reference/platform/members/person-infos",
+          "metadata": {
+            "sidebarTitle": "Batch get persons"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/PersonInfosResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "items": [
                       {
                         "account_id": 2451002751131,
-                        "as": "member",
-                        "avatar": "/image/avatar1.png",
-                        "email": "alice@example.com",
-                        "email_verified": true,
-                        "locale": "zh-CN",
                         "person_id": 2476444212131,
                         "person_name": "Alice",
+                        "avatar": "/image/avatar1.png",
+                        "locale": "zh-CN",
+                        "time_zone": "Asia/Shanghai",
+                        "email": "alice@example.com",
                         "phone_verified": false,
-                        "status": "enabled",
-                        "time_zone": "Asia/Shanghai"
+                        "email_verified": true,
+                        "as": "member",
+                        "status": "enabled"
                       },
                       {
                         "account_id": 2451002751131,
-                        "as": "member",
-                        "email": "bob@example.com",
-                        "email_verified": true,
                         "person_id": 3790925372131,
                         "person_name": "Bob",
+                        "email": "bob@example.com",
                         "phone_verified": false,
+                        "email_verified": true,
+                        "as": "member",
                         "status": "enabled"
                       }
                     ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/PersonInfosResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -49333,6 +51005,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -49340,62 +51015,65 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Batch get persons",
-        "tags": [
-          "Platform/Members"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |",
-          "href": "/en/api-reference/platform/members/person-infos",
-          "metadata": {
-            "sidebarTitle": "Batch get persons"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PersonInfosRequest"
+              },
+              "example": {
+                "person_ids": [
+                  2476444212131,
+                  3790925372131
+                ]
+              }
+            }
           }
         }
       }
     },
     "/role/delete": {
       "post": {
-        "description": "Delete a custom role. While members still hold the role, the call fails with `ReferenceExist` unless `is_force` is true.",
         "operationId": "role-write-delete",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "role_id": 150
-              },
-              "schema": {
-                "$ref": "#/components/schemas/RoleDeleteRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "Delete a role",
+        "description": "Delete a custom role, optionally revoking it from every member who still holds it.",
+        "tags": [
+          "Platform/Roles & permissions"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Roles Manage** (`organization`) |\n\n## Usage\n\n- While members still hold the role, the call fails with `400 ReferenceExist` and lists them in `data.refs` (`kind` `member`); set `is_force` to `true` to revoke the role from all of them and then delete it.\n- A role selected as a default role in the SSO configuration cannot be deleted, even with `is_force`; the call fails with `400 ReferenceExist` until it is unselected there.\n- A role ID that does not exist or was already deleted is ignored and the call succeeds.\n- Do not pass a built-in role ID (`2`, `6`, `8`): the built-in role itself is not deleted, but with `is_force: true` it is revoked from every member who holds it.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "href": "/en/api-reference/platform/roles-permissions/role-write-delete",
+          "metadata": {
+            "sidebarTitle": "Delete a role"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/PlatformEmptyObject"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -49413,62 +51091,62 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Delete a role",
-        "tags": [
-          "Platform/Roles & permissions"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Roles Manage** (`organization`) |\n\n## Usage\n\n- Built-in roles are synthetic and are never deleted; the call is a no-op for them.\n- While any member still holds the role, the default (`is_force=false`) call fails with error code `ReferenceExist` and the holders listed in `data.refs`. Set `is_force=true` to revoke the role from all holders and delete it in one call.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
-          "href": "/en/api-reference/platform/roles-permissions/role-write-delete",
-          "metadata": {
-            "sidebarTitle": "Delete a role"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/RoleDeleteRequest"
+              },
+              "example": {
+                "role_id": 150
+              }
+            }
           }
         }
       }
     },
     "/role/disable": {
       "post": {
-        "description": "Disable a custom role to prevent it from granting permissions.",
         "operationId": "role-write-disable",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "role_id": 150
-              },
-              "schema": {
-                "$ref": "#/components/schemas/RoleIDRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "Disable a role",
+        "description": "Set a custom role's status to disabled without deleting it.",
+        "tags": [
+          "Platform/Roles & permissions"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Roles Manage** (`organization`) |\n\n## Usage\n\n- Only a role in `enabled` status can be disabled; calling it on a role that is already disabled returns `400 InvalidParameter`.\n- The built-in roles (`2`, `6`, `8`) cannot be disabled: the call succeeds but changes nothing.\n- A role ID that does not exist or was deleted is ignored and the call succeeds.\n- Disabling does not revoke the role from the members who hold it.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "href": "/en/api-reference/platform/roles-permissions/role-write-disable",
+          "metadata": {
+            "sidebarTitle": "Disable a role"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/PlatformEmptyObject"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -49486,62 +51164,62 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Disable a role",
-        "tags": [
-          "Platform/Roles & permissions"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Roles Manage** (`organization`) |\n\n## Usage\n\n- Members who held this role lose its permissions immediately.\n- Built-in roles always remain enabled; enabling or disabling them is a silent no-op.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
-          "href": "/en/api-reference/platform/roles-permissions/role-write-disable",
-          "metadata": {
-            "sidebarTitle": "Disable a role"
-          }
-        }
-      }
-    },
-    "/role/enable": {
-      "post": {
-        "description": "Re-enable a previously disabled custom role.",
-        "operationId": "role-write-enable",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {
-                "role_id": 150
-              },
               "schema": {
                 "$ref": "#/components/schemas/RoleIDRequest"
+              },
+              "example": {
+                "role_id": 150
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/role/enable": {
+      "post": {
+        "operationId": "role-write-enable",
+        "summary": "Enable a role",
+        "description": "Re-enable a previously disabled custom role.",
+        "tags": [
+          "Platform/Roles & permissions"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Roles Manage** (`organization`) |\n\n## Usage\n\n- Only a role in `disabled` status can be enabled; calling it on an enabled role — including the built-in roles — returns `400 InvalidParameter`.\n- A role ID that does not exist or was deleted is ignored and the call succeeds.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "href": "/en/api-reference/platform/roles-permissions/role-write-enable",
+          "metadata": {
+            "sidebarTitle": "Enable a role"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/PlatformEmptyObject"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -49559,75 +51237,76 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Enable a role",
-        "tags": [
-          "Platform/Roles & permissions"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Roles Manage** (`organization`) |\n\n## Usage\n\n- Built-in roles always remain enabled; enabling or disabling them is a silent no-op.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
-          "href": "/en/api-reference/platform/roles-permissions/role-write-enable",
-          "metadata": {
-            "sidebarTitle": "Enable a role"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/RoleIDRequest"
+              },
+              "example": {
+                "role_id": 150
+              }
+            }
           }
         }
       }
     },
     "/role/info": {
       "post": {
-        "description": "Return the detail of a single role by its ID.",
         "operationId": "role-read-info",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "role_id": 2
-              },
-              "schema": {
-                "$ref": "#/components/schemas/RoleInfoRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "Get role detail",
+        "description": "Return the detail of a single role by its ID.",
+        "tags": [
+          "Platform/Roles & permissions"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- IDs `2`, `6`, and `8` return the built-in Admin, Responder, and Viewer roles; their `description` follows the request language.\n- A role ID that does not exist or was deleted returns `400 InvalidParameter`.",
+          "href": "/en/api-reference/platform/roles-permissions/role-read-info",
+          "metadata": {
+            "sidebarTitle": "Get role detail"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "created_at": 1700000000,
-                    "description": "Account admin with all permissions.",
-                    "editable": false,
-                    "permission_ids": [
-                      101,
-                      102,
-                      201
-                    ],
-                    "role_id": 2,
-                    "role_name": "Account Admin",
-                    "status": "enabled",
-                    "updated_at": 1700000000
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/RoleItem"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "role_id": 2,
+                    "role_name": "Admin",
+                    "description": "Account Administrator, has all account permissions and can assist the main account in managing all affairs.",
+                    "status": "enabled",
+                    "permission_ids": [
+                      101,
+                      102,
+                      201,
+                      701
+                    ],
+                    "editable": false,
+                    "created_at": 1653530940,
+                    "updated_at": 1653530940
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -49635,6 +51314,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -49642,77 +51324,119 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Get role detail",
-        "tags": [
-          "Platform/Roles & permissions"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |",
-          "href": "/en/api-reference/platform/roles-permissions/role-read-info",
-          "metadata": {
-            "sidebarTitle": "Get role detail"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/RoleInfoRequest"
+              },
+              "example": {
+                "role_id": 2
+              }
+            }
           }
         }
       }
     },
     "/role/list": {
       "post": {
-        "description": "Return all custom and built-in roles for the current account.",
         "operationId": "role-read-list",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "asc": false,
-                "orderby": "created_at"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/RoleListRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "List roles",
+        "description": "Return all custom and built-in roles for the current account.",
+        "tags": [
+          "Platform/Roles & permissions"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Custom roles (enabled and disabled) come first, sorted by `orderby`/`asc`; the three built-in roles — `2` Admin, `6` Responder, `8` Viewer — are appended at the end unless `no_global` is true, and are counted in `total`.\n- Built-in roles have `editable: false`, and their `description` follows the request language (`Accept-Language` header, or the `locale`/`lang` query parameter).",
+          "href": "/en/api-reference/platform/roles-permissions/role-read-list",
+          "metadata": {
+            "sidebarTitle": "List roles"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "items": [
-                      {
-                        "created_at": 1700000000,
-                        "description": "",
-                        "editable": false,
-                        "permission_ids": [],
-                        "role_id": 2,
-                        "role_name": "Account Admin",
-                        "status": "enabled",
-                        "updated_at": 1700000000
-                      }
-                    ],
-                    "total": 3
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/RoleListResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "total": 4,
+                    "items": [
+                      {
+                        "role_id": 150,
+                        "role_name": "On-call Manager",
+                        "description": "Manage on-call rotations and incidents.",
+                        "status": "enabled",
+                        "permission_ids": [
+                          501,
+                          502
+                        ],
+                        "editable": true,
+                        "created_at": 1710000000,
+                        "updated_at": 1712000000
+                      },
+                      {
+                        "role_id": 2,
+                        "role_name": "Admin",
+                        "description": "Account Administrator, has all account permissions and can assist the main account in managing all affairs.",
+                        "status": "enabled",
+                        "permission_ids": [
+                          101,
+                          102,
+                          201,
+                          701
+                        ],
+                        "editable": false,
+                        "created_at": 1653530940,
+                        "updated_at": 1653530940
+                      },
+                      {
+                        "role_id": 6,
+                        "role_name": "Responder",
+                        "description": "Responder, has standard permissions except billing center, member management, role management and single sign-on management, suitable for members handling daily operations.",
+                        "status": "enabled",
+                        "permission_ids": [
+                          201,
+                          701
+                        ],
+                        "editable": false,
+                        "created_at": 1653530940,
+                        "updated_at": 1653530940
+                      },
+                      {
+                        "role_id": 8,
+                        "role_name": "Viewer",
+                        "description": "Viewer, has most read-only permissions except audit and onboarding, suitable for members who only need to view data.",
+                        "status": "enabled",
+                        "permission_ids": [
+                          103
+                        ],
+                        "editable": false,
+                        "created_at": 1653530940,
+                        "updated_at": 1653530940
+                      }
+                    ]
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -49720,6 +51444,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -49727,66 +51454,63 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "List roles",
-        "tags": [
-          "Platform/Roles & permissions"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Built-in roles (`editable: false`) cannot be modified or deleted.",
-          "href": "/en/api-reference/platform/roles-permissions/role-read-list",
-          "metadata": {
-            "sidebarTitle": "List roles"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/RoleListRequest"
+              },
+              "example": {
+                "orderby": "created_at",
+                "asc": false
+              }
+            }
           }
         }
       }
     },
     "/role/member/grant": {
       "post": {
-        "description": "Assign a role to one or more members, giving them its permissions.",
         "operationId": "role-write-grant-role",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "member_ids": [
-                  80011,
-                  80012
-                ],
-                "role_id": 150
-              },
-              "schema": {
-                "$ref": "#/components/schemas/RoleGrantRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "Grant role to members",
+        "description": "Assign a role to one or more members, giving them its permissions.",
+        "tags": [
+          "Platform/Roles & permissions"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Roles Manage** (`organization`) |\n\n## Usage\n\n- Every ID in `member_ids` must be a member of the account, with no duplicates; otherwise the call returns `400` and nobody is changed.\n- `role_id` must be a built-in role or a custom role that has not been deleted (disabled roles are accepted); otherwise the call returns `400`.\n- Members provisioned through SSO cannot be changed while the SSO configuration marks them non-editable; the call returns `400`.\n- Members who already hold the role keep it unchanged.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "href": "/en/api-reference/platform/roles-permissions/role-write-grant-role",
+          "metadata": {
+            "sidebarTitle": "Grant role to members"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/PlatformEmptyObject"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -49804,65 +51528,66 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Grant role to members",
-        "tags": [
-          "Platform/Roles & permissions"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Roles Manage** (`organization`) |\n\n## Usage\n\n- Members who already have the role are silently skipped.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
-          "href": "/en/api-reference/platform/roles-permissions/role-write-grant-role",
-          "metadata": {
-            "sidebarTitle": "Grant role to members"
-          }
-        }
-      }
-    },
-    "/role/member/revoke": {
-      "post": {
-        "description": "Remove a role from one or more members, revoking the permissions it granted.",
-        "operationId": "role-write-revoke-role",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/RoleGrantRequest"
+              },
               "example": {
                 "member_ids": [
-                  80011
+                  80011,
+                  80012
                 ],
                 "role_id": 150
-              },
-              "schema": {
-                "$ref": "#/components/schemas/RoleGrantRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/role/member/revoke": {
+      "post": {
+        "operationId": "role-write-revoke-role",
+        "summary": "Revoke role from members",
+        "description": "Remove a role from one or more members, revoking the permissions it granted.",
+        "tags": [
+          "Platform/Roles & permissions"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Roles Manage** (`organization`) |\n\n## Usage\n\n- Every ID in `member_ids` must be a member of the account, with no duplicates; otherwise the call returns `400` and nobody is changed.\n- `role_id` must be a built-in role or a custom role that has not been deleted (disabled roles are accepted); otherwise the call returns `400`.\n- Members provisioned through SSO cannot be changed while the SSO configuration marks them non-editable; the call returns `400`.\n- Members who don't hold the role are left unchanged; revoking a member's last role leaves them with no roles.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "href": "/en/api-reference/platform/roles-permissions/role-write-revoke-role",
+          "metadata": {
+            "sidebarTitle": "Revoke role from members"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/PlatformEmptyObject"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -49880,70 +51605,71 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Revoke role from members",
-        "tags": [
-          "Platform/Roles & permissions"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Roles Manage** (`organization`) |\n\n## Usage\n\n- Members who don't have the role are silently skipped.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
-          "href": "/en/api-reference/platform/roles-permissions/role-write-revoke-role",
-          "metadata": {
-            "sidebarTitle": "Revoke role from members"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/RoleGrantRequest"
+              },
+              "example": {
+                "member_ids": [
+                  80011
+                ],
+                "role_id": 150
+              }
+            }
           }
         }
       }
     },
     "/role/permission/factor/list": {
       "post": {
-        "description": "Return all permission factors (API, button, menu, URL, visit) granted to the calling member, optionally filtered by type. Requires a member-scoped credential — calls authenticated as the account principal (e.g. an account-level app key) are rejected with a 400, because the account principal implicitly holds every permission.",
         "operationId": "role-read-list-permission-factor",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "factor_types": [
-                  "api"
-                ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/PermissionFactorListRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "List permission factors",
+        "description": "List the permission factors granted to the calling member through their roles.",
+        "tags": [
+          "Platform/Roles & permissions"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — but see the credential requirement under Usage |\n\n## Usage\n\n- Requires a member credential: calls made with the account owner's credentials return `400 InvalidParameter`, because the account owner implicitly holds every permission.\n- Factors come from all roles the calling member holds and are deduplicated; the order is not stable. A member with no roles gets an empty array.\n- `factor_types` filters by type (`api`, `button`, `visit`, `menu`, `url`); omit it to return all types. An unsupported type returns `400`.",
+          "href": "/en/api-reference/platform/roles-permissions/role-read-list-permission-factor",
+          "metadata": {
+            "sidebarTitle": "List permission factors"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": [
-                    {
-                      "factor_name": "template:read:info",
-                      "factor_type": "api",
-                      "source": "system"
-                    }
-                  ],
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/PermissionFactorListResponse"
                         }
-                      },
-                      "type": "object"
+                      }
+                    }
+                  ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": [
+                    {
+                      "factor_name": "template:read:info",
+                      "factor_type": "api",
+                      "source": "system"
                     }
                   ]
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -49951,6 +51677,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -49958,79 +51687,78 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "List permission factors",
-        "tags": [
-          "Platform/Roles & permissions"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — but the credential must belong to a member; account-principal credentials (e.g. an account-level app key) are rejected with a 400 |\n\n## Usage\n\n- Permission factors are the fine-grained controls that make up each permission.\n- `factor_types` accepts: `api`, `button`, `visit`, `menu`, `url`.",
-          "href": "/en/api-reference/platform/roles-permissions/role-read-list-permission-factor",
-          "metadata": {
-            "sidebarTitle": "List permission factors"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PermissionFactorListRequest"
+              },
+              "example": {
+                "factor_types": [
+                  "api"
+                ]
+              }
+            }
           }
         }
       }
     },
     "/role/permission/list": {
       "post": {
-        "description": "Return all available permissions, optionally filtered to those granted to specific roles.",
         "operationId": "role-read-list-permission",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "role_ids": [
-                  150
-                ],
-                "with_all": true
-              },
-              "schema": {
-                "$ref": "#/components/schemas/RolePermissionListRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "List permissions",
+        "description": "List permission entries and mark which of them the given roles grant.",
+        "tags": [
+          "Platform/Roles & permissions"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- With `with_all: true`, every permission is returned and `is_granted` marks the ones granted by any role in `role_ids`.\n- With `with_all` false (the default), only the permissions granted by `role_ids` are returned — a call without `role_ids` returns an empty list.\n- `permission_name`, `description`, and `class` follow the request language (`Accept-Language` header, or the `locale`/`lang` query parameter).",
+          "href": "/en/api-reference/platform/roles-permissions/role-read-list-permission",
+          "metadata": {
+            "sidebarTitle": "List permissions"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "items": [
-                      {
-                        "class": "On-call",
-                        "description": "View notification templates",
-                        "id": 501,
-                        "is_granted": true,
-                        "permission_name": "Templates Read",
-                        "permission_type": "read",
-                        "scope": "on-call",
-                        "source": "system",
-                        "status": "enabled"
-                      }
-                    ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/RolePermissionListResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "items": [
+                      {
+                        "id": 501,
+                        "permission_name": "Templates Read",
+                        "permission_type": "read",
+                        "description": "View notification templates",
+                        "class": "On-call",
+                        "scope": "on-call",
+                        "status": "enabled",
+                        "is_granted": true,
+                        "source": "system"
+                      }
+                    ]
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -50038,6 +51766,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -50045,70 +51776,68 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "List permissions",
-        "tags": [
-          "Platform/Roles & permissions"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Pass `role_ids` to filter permissions to those granted to those roles.\n- Pass `with_all: true` to include all permissions regardless of role filter, with `is_granted` set to indicate which are granted to the specified roles.",
-          "href": "/en/api-reference/platform/roles-permissions/role-read-list-permission",
-          "metadata": {
-            "sidebarTitle": "List permissions"
-          }
-        }
-      }
-    },
-    "/role/upsert": {
-      "post": {
-        "description": "Create a new custom role or update an existing one. Pass `role_id` to update.",
-        "operationId": "role-write-upsert",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/RolePermissionListRequest"
+              },
               "example": {
-                "description": "Manage on-call rotations and incidents.",
-                "permission_ids": [
-                  501,
-                  502
+                "role_ids": [
+                  150
                 ],
-                "role_name": "On-call Manager"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/RoleUpsertRequest"
+                "with_all": true
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/role/upsert": {
+      "post": {
+        "operationId": "role-write-upsert",
+        "summary": "Create or update a role",
+        "description": "Create a new custom role or update an existing one. Pass `role_id` to update.",
+        "tags": [
+          "Platform/Roles & permissions"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Roles Manage** (`organization`) |\n\n## Usage\n\n- Omit `role_id` (or set it to 0) to create a role; pass the ID of a custom role to update it.\n- `role_name` must be unique in the account, including the built-in names `Admin`, `Responder`, and `Viewer`; a conflict returns `400`.\n- An update overwrites `role_name`, `description`, and `permission_ids` together: omitting `description` clears it, and omitting `permission_ids` removes every permission from the role.\n- Updating a disabled role re-enables it.\n- Every ID in `permission_ids` must be a permission returned by `POST /role/permission/list` (with `with_all: true`); otherwise the call returns `400` and nothing changes.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "href": "/en/api-reference/platform/roles-permissions/role-write-upsert",
+          "metadata": {
+            "sidebarTitle": "Create or update a role"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "role_id": 150,
-                    "role_name": "On-call Manager"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/RoleUpsertResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "role_id": 150,
+                    "role_name": "On-call Manager"
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -50126,48 +51855,67 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Create or update a role",
-        "tags": [
-          "Platform/Roles & permissions"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Roles Manage** (`organization`) |\n\n## Usage\n\n- Omit `role_id` (or set to 0) to create; pass an existing ID to update.\n- `role_name` must be 1–39 characters and unique within the account.\n- `permission_ids` sets the full permission set for the role, replacing any previous assignment.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
-          "href": "/en/api-reference/platform/roles-permissions/role-write-upsert",
-          "metadata": {
-            "sidebarTitle": "Create or update a role"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/RoleUpsertRequest"
+              },
+              "example": {
+                "role_name": "On-call Manager",
+                "description": "Manage on-call rotations and incidents.",
+                "permission_ids": [
+                  501,
+                  502
+                ]
+              }
+            }
           }
         }
       }
     },
     "/route/info": {
       "post": {
-        "description": "Retrieve the routing rule configuration for a specific integration. Returns null when the integration has no routing rule configured.",
         "operationId": "routeInfo",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "integration_id": 6113996590131
-              },
-              "schema": {
-                "$ref": "#/components/schemas/RouteInfoRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "Get routing rule detail",
+        "description": "Return the routing rule of one shared integration.",
+        "tags": [
+          "On-call/Channels"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Integrations Read** (`on-call`) or **Integrations Manage** (`on-call`) |\n\n## Usage\n\n- When the integration has no routing rule, the response carries only `request_id`, with no `data` field.\n- A channel-exclusive or unknown `integration_id` returns `InvalidParameter`.",
+          "href": "/en/api-reference/on-call/channels/route-info",
+          "metadata": {
+            "sidebarTitle": "Get routing rule detail"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/RouteItem"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
+                    "integration_id": 6113996590131,
                     "cases": [
                       {
-                        "channel_ids": [
-                          2533748993131
-                        ],
-                        "fallthrough": false,
                         "if": [
                           {
                             "key": "labels.check",
@@ -50177,11 +51925,13 @@
                             ]
                           }
                         ],
+                        "channel_ids": [
+                          2533748993131
+                        ],
+                        "fallthrough": false,
                         "routing_mode": "standard"
                       },
                       {
-                        "channel_ids": null,
-                        "fallthrough": false,
                         "if": [
                           {
                             "key": "severity",
@@ -50191,43 +51941,27 @@
                             ]
                           }
                         ],
-                        "name_mapping_label": "labels.service",
-                        "routing_mode": "name_mapping"
+                        "channel_ids": null,
+                        "fallthrough": false,
+                        "routing_mode": "name_mapping",
+                        "name_mapping_label": "labels.service"
                       }
                     ],
-                    "created_at": 1774606136,
-                    "creator_id": 3790925372131,
                     "default": {
                       "channel_ids": [
                         3521074710131
                       ]
                     },
-                    "integration_id": 6113996590131,
                     "status": "enabled",
-                    "updated_at": 1774606136,
+                    "version": 6,
                     "updated_by": 3790925372131,
-                    "version": 6
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/RouteItem"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                    "creator_id": 3790925372131,
+                    "created_at": 1774606136,
+                    "updated_at": 1774606136
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -50235,6 +51969,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -50242,53 +51979,64 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Get routing rule detail",
-        "tags": [
-          "On-call/Channels"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Integrations Read** (`on-call`) or **Integrations Manage** (`on-call`) |",
-          "href": "/en/api-reference/on-call/channels/route-info",
-          "metadata": {
-            "sidebarTitle": "Get routing rule detail"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/RouteInfoRequest"
+              },
+              "example": {
+                "integration_id": 6113996590131
+              }
+            }
           }
         }
       }
     },
     "/route/list": {
       "post": {
-        "description": "Return routing rules for the specified integrations. Integrations without a configured rule are omitted from the response.",
         "operationId": "routeList",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "integration_ids": [
-                  6113996590131,
-                  6113996590132
-                ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ListRoutesRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "List routing rules",
+        "description": "Return the routing rules of several shared integrations in one call.",
+        "tags": [
+          "On-call/Channels"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Integrations Read** (`on-call`) or **Integrations Manage** (`on-call`) |\n\n## Usage\n\n- Integrations without a routing rule are omitted from `items`.\n- Every ID must be an existing shared integration; a single unknown or channel-exclusive ID fails the whole call with `InvalidParameter`.",
+          "href": "/en/api-reference/on-call/channels/route-list",
+          "metadata": {
+            "sidebarTitle": "List routing rules"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/ListRoutesResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "items": [
                       {
+                        "integration_id": 6113996590131,
                         "cases": [
                           {
-                            "channel_ids": [
-                              2533748993131
-                            ],
-                            "fallthrough": false,
                             "if": [
                               {
                                 "key": "labels.check",
@@ -50298,44 +52046,105 @@
                                 ]
                               }
                             ],
+                            "channel_ids": [
+                              2533748993131
+                            ],
+                            "fallthrough": false,
                             "routing_mode": "standard"
                           }
                         ],
-                        "created_at": 1774606136,
-                        "creator_id": 3790925372131,
                         "default": {
                           "channel_ids": [
                             3521074710131
                           ]
                         },
-                        "integration_id": 6113996590131,
                         "status": "enabled",
-                        "updated_at": 1774606136,
+                        "version": 6,
                         "updated_by": 3790925372131,
-                        "version": 6
+                        "creator_id": 3790925372131,
+                        "created_at": 1774606136,
+                        "updated_at": 1774606136
                       }
                     ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "429": {
+            "$ref": "#/components/responses/TooManyRequests"
+          },
+          "500": {
+            "$ref": "#/components/responses/ServerError"
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ListRoutesRequest"
+              },
+              "example": {
+                "integration_ids": [
+                  6113996590131,
+                  6113996590132
+                ]
+              }
+            }
+          }
+        }
+      }
+    },
+    "/route/upsert": {
+      "post": {
+        "operationId": "routeUpsert",
+        "summary": "Upsert routing rule",
+        "description": "Create or replace the routing rule that sends a shared integration's alerts to channels.",
+        "tags": [
+          "On-call/Channels"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Integrations Manage** (`on-call`) |\n\n## Usage\n\n- The whole rule is replaced: `cases`, `sections` or `default` missing from the request are removed. `version` increases on every call and the previous version is kept in the route history.\n- At least one of `cases` or `default` is required; a `default` with empty `channel_ids` counts as absent.\n- Only shared integrations have routing rules: a channel-exclusive or unknown `integration_id`, or a channel ID that does not exist, returns `InvalidParameter`.\n- When the integration belongs to a team, the caller must be the account owner or an admin, the integration's creator, or a member of that team; otherwise `AccessDenied`.\n- A successful response carries only `request_id`, with no `data` field.\n- Every call is recorded in the account audit log.",
+          "href": "/en/api-reference/on-call/channels/route-upsert",
+          "metadata": {
+            "sidebarTitle": "Upsert routing rule"
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/ListRoutesResponse"
+                          "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -50343,6 +52152,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -50350,33 +52162,17 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "List routing rules",
-        "tags": [
-          "On-call/Channels"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Integrations Read** (`on-call`) or **Integrations Manage** (`on-call`) |",
-          "href": "/en/api-reference/on-call/channels/route-list",
-          "metadata": {
-            "sidebarTitle": "List routing rules"
-          }
-        }
-      }
-    },
-    "/route/upsert": {
-      "post": {
-        "description": "Create or update routing rules for an integration to direct alerts to specific channels. At least one of `cases` or `default` must be provided.",
-        "operationId": "routeUpsert",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/UpsertRouteRequest"
+              },
               "example": {
+                "integration_id": 6113996590131,
                 "cases": [
                   {
-                    "channel_ids": [
-                      3521074710131
-                    ],
-                    "fallthrough": false,
                     "if": [
                       {
                         "key": "severity",
@@ -50386,6 +52182,10 @@
                         ]
                       }
                     ],
+                    "channel_ids": [
+                      3521074710131
+                    ],
+                    "fallthrough": false,
                     "routing_mode": "standard"
                   }
                 ],
@@ -50393,11 +52193,122 @@
                   "channel_ids": [
                     3521074710131
                   ]
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/rum/application/create": {
+      "post": {
+        "description": "Create a new RUM application. Returns the generated `application_id` and `client_token`.",
+        "operationId": "rum-application-write-create",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "example": {
+                "application_name": "My Web App",
+                "is_private": false,
+                "links": {
+                  "enabled": true,
+                  "systems": [
+                    {
+                      "enabled": true,
+                      "event_types": [
+                        "crash",
+                        "error"
+                      ],
+                      "icon_color": "#0F766E",
+                      "icon_text": "S3",
+                      "id": "s3-crash-logs",
+                      "name": "S3 Crash Logs",
+                      "url": "https://s3.example.com/logs?app=${application_id}&trace=${trace_id}"
+                    }
+                  ]
                 },
-                "integration_id": 6113996590131
+                "team_id": 2477033058131,
+                "type": "browser"
               },
               "schema": {
-                "$ref": "#/components/schemas/UpsertRouteRequest"
+                "$ref": "#/components/schemas/RumApplicationCreateRequest"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "example": {
+                  "data": {
+                    "application_id": "qLpu24Dz4CAzWsESPbJYWA",
+                    "application_name": "My Web App",
+                    "client_token": "e090078724855a4ca168c3884880dfbc131"
+                  },
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
+                },
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/RumApplicationCreateResponse"
+                        }
+                      },
+                      "type": "object"
+                    }
+                  ]
+                }
+              }
+            },
+            "description": "Success"
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "429": {
+            "$ref": "#/components/responses/TooManyRequests"
+          },
+          "500": {
+            "$ref": "#/components/responses/ServerError"
+          }
+        },
+        "summary": "Create application",
+        "tags": [
+          "RUM/Applications"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Applications Manage** (`rum`) |\n\n## Usage\n\n- `type` must be one of: `browser`, `ios`, `android`, `react-native`, `flutter`, `kotlin-multiplatform`, `roku`, `unity`, `miniprogram`, `harmony`, `electron`.\n- `client_token` is generated by the server and used to initialize the RUM SDK; it is also returned later by `POST /rum/application/info`.\n- When `tracing` is sent, `open_type` (`popup` or `tab`) and an `http`/`https` `endpoint` are required even if `enabled` is `false`.\n- `links.systems[].url` must start with `http` or `https`; each system needs a `name` and at least one `event_types` entry.\n- With `alerting.delivery_mode` `oncall` (the default on Flashduty cloud), the server creates or reuses the account's RUM alerting integration and returns its ID as `alerting.integration_id`.\n- The team in `team_id` is not checked against the caller's own team memberships.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "href": "/en/api-reference/rum/applications/rum-application-write-create",
+          "metadata": {
+            "sidebarTitle": "Create application"
+          }
+        }
+      }
+    },
+    "/rum/application/delete": {
+      "post": {
+        "description": "Delete a RUM application by `application_id`.",
+        "operationId": "rum-application-write-delete",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "example": {
+                "application_id": "qLpu24Dz4CAzWsESPbJYWA"
+              },
+              "schema": {
+                "$ref": "#/components/schemas/RumApplicationIDRequest"
               }
             }
           },
@@ -50436,169 +52347,8 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
-          "429": {
-            "$ref": "#/components/responses/TooManyRequests"
-          },
-          "500": {
-            "$ref": "#/components/responses/ServerError"
-          }
-        },
-        "summary": "Upsert routing rule",
-        "tags": [
-          "On-call/Channels"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Integrations Manage** (`on-call`) |",
-          "href": "/en/api-reference/on-call/channels/route-upsert",
-          "metadata": {
-            "sidebarTitle": "Upsert routing rule"
-          }
-        }
-      }
-    },
-    "/rum/application/create": {
-      "post": {
-        "description": "Create a new RUM application. Returns the generated `application_id` and `client_token`.",
-        "operationId": "rum-application-write-create",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "application_name": "My Web App",
-                "is_private": false,
-                "links": {
-                  "enabled": true,
-                  "systems": [
-                    {
-                      "enabled": true,
-                      "event_types": [
-                        "crash",
-                        "error"
-                      ],
-                      "icon_color": "#0F766E",
-                      "icon_text": "S3",
-                      "id": "s3-crash-logs",
-                      "name": "S3 Crash Logs",
-                      "url": "https://s3.example.com/logs?app=${application_id}&trace=${trace_id}"
-                    }
-                  ]
-                },
-                "team_id": 2477033058131,
-                "type": "browser"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/RumApplicationCreateRequest"
-              }
-            }
-          },
-          "required": true
-        },
-        "responses": {
-          "200": {
-            "content": {
-              "application/json": {
-                "example": {
-                  "data": {
-                    "application_id": "qLpu24Dz4CAzWsESPbJYWA",
-                    "application_name": "My Web App",
-                    "client_token": "e090078724855a4ca168c3884880dfbc131"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/RumApplicationCreateResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
-                }
-              }
-            },
-            "description": "Success"
-          },
-          "400": {
-            "$ref": "#/components/responses/BadRequest"
-          },
-          "401": {
-            "$ref": "#/components/responses/Unauthorized"
-          },
-          "429": {
-            "$ref": "#/components/responses/TooManyRequests"
-          },
-          "500": {
-            "$ref": "#/components/responses/ServerError"
-          }
-        },
-        "summary": "Create application",
-        "tags": [
-          "RUM/Applications"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Applications Manage** (`rum`) |\n\n## Usage\n\n- `type` must be one of: `browser`, `ios`, `android`, `react-native`, `flutter`, `kotlin-multiplatform`, `roku`, `unity`, `miniprogram`, `harmony`, `electron`.\n- `links.systems[].url` must start with `http` or `https`; `${var}` tokens are resolved from RUM event context.\n- `links.systems[].event_types` accepts: `crash`, `error`, `view`, `action`, `resource`, `session`, `all`.\n- `client_token` is auto-generated and used to initialize the RUM SDK.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
-          "href": "/en/api-reference/rum/applications/rum-application-write-create",
-          "metadata": {
-            "sidebarTitle": "Create application"
-          }
-        }
-      }
-    },
-    "/rum/application/delete": {
-      "post": {
-        "description": "Delete a RUM application by `application_id`.",
-        "operationId": "rum-application-write-delete",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "application_id": "qLpu24Dz4CAzWsESPbJYWA"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/RumApplicationIDRequest"
-              }
-            }
-          },
-          "required": true
-        },
-        "responses": {
-          "200": {
-            "content": {
-              "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/EmptyResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
-                }
-              }
-            },
-            "description": "Success"
-          },
-          "400": {
-            "$ref": "#/components/responses/BadRequest"
-          },
-          "401": {
-            "$ref": "#/components/responses/Unauthorized"
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
           },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
@@ -50612,7 +52362,7 @@
           "RUM/Applications"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Applications Manage** (`rum`) |\n\n## Usage\n\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Applications Manage** (`rum`) |\n\n## Usage\n\n- Deletion is a soft delete: the application disappears from list, info and infos, and later calls with its ID fail (`InvalidParameter`, or `ResourceNotFound` for remote-config operations). There is no restore operation.\n- The application's `client_token` stops being accepted by the data intake within about 5 minutes; data already collected is not removed.\n- The caller must be able to edit the application: the account owner, an account admin, the application's creator, or a member of its owning team; anyone else gets `AccessDenied`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/rum/applications/rum-application-write-delete",
           "metadata": {
             "sidebarTitle": "Delete application"
@@ -50649,7 +52399,8 @@
                         2490121812131
                       ],
                       "enabled": true,
-                      "integration_id": 4759595678131
+                      "integration_id": 4759595678131,
+                      "delivery_mode": "oncall"
                     },
                     "application_id": "WoyQQ3BohkdtPivubEvE8o",
                     "application_name": "flashcat-rum",
@@ -50685,7 +52436,13 @@
                     },
                     "type": "browser",
                     "updated_at": 1773398630657,
-                    "updated_by": 3790925372131
+                    "updated_by": 3790925372131,
+                    "repositories": [
+                      {
+                        "repo": "acme/web-app",
+                        "subdir": "apps/web"
+                      }
+                    ]
                   },
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 },
@@ -50714,6 +52471,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -50726,7 +52486,7 @@
           "RUM/Applications"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- An unknown or deleted `application_id` returns `InvalidParameter`.\n- A private application (`is_private: true`) is readable only by the account owner, account admins, its creator and members of its owning team; others get `AccessDenied`.",
           "href": "/en/api-reference/rum/applications/rum-application-read-info",
           "metadata": {
             "sidebarTitle": "Get application detail"
@@ -50769,7 +52529,8 @@
                             5967875767131
                           ],
                           "enabled": true,
-                          "integration_id": 4759595678131
+                          "integration_id": 4759595678131,
+                          "delivery_mode": "oncall"
                         },
                         "application_id": "eWbr4xk3ZRnLabRa6unqwD",
                         "application_name": "Flashduty DEV",
@@ -50792,7 +52553,8 @@
                         },
                         "type": "browser",
                         "updated_at": 1772096392711,
-                        "updated_by": 3122470302131
+                        "updated_by": 3122470302131,
+                        "repositories": []
                       },
                       {
                         "account_id": 2451002751131,
@@ -50801,7 +52563,8 @@
                             2490121812131
                           ],
                           "enabled": true,
-                          "integration_id": 4759595678131
+                          "integration_id": 4759595678131,
+                          "delivery_mode": "oncall"
                         },
                         "application_id": "WoyQQ3BohkdtPivubEvE8o",
                         "application_name": "flashcat-rum",
@@ -50837,7 +52600,8 @@
                         },
                         "type": "browser",
                         "updated_at": 1773398630657,
-                        "updated_by": 3790925372131
+                        "updated_by": 3790925372131,
+                        "repositories": []
                       }
                     ]
                   },
@@ -50868,6 +52632,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -50880,7 +52647,7 @@
           "RUM/Applications"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Maximum 200 IDs per request.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Duplicate IDs are collapsed; unknown or deleted IDs are skipped without an error, so `items` can be shorter than `application_ids`.\n- The order of `items` is not guaranteed to follow `application_ids`.",
           "href": "/en/api-reference/rum/applications/rum-application-read-infos",
           "metadata": {
             "sidebarTitle": "Batch get applications"
@@ -50923,7 +52690,8 @@
                             2490121812131
                           ],
                           "enabled": true,
-                          "integration_id": 4759595678131
+                          "integration_id": 4759595678131,
+                          "delivery_mode": "oncall"
                         },
                         "application_id": "WoyQQ3BohkdtPivubEvE8o",
                         "application_name": "flashcat-rum",
@@ -50959,7 +52727,8 @@
                         },
                         "type": "browser",
                         "updated_at": 1773398630657,
-                        "updated_by": 3790925372131
+                        "updated_by": 3790925372131,
+                        "repositories": []
                       },
                       {
                         "account_id": 2451002751131,
@@ -50969,7 +52738,8 @@
                             5967875767131
                           ],
                           "enabled": true,
-                          "integration_id": 4759595678131
+                          "integration_id": 4759595678131,
+                          "delivery_mode": "oncall"
                         },
                         "application_id": "eWbr4xk3ZRnLabRa6unqwD",
                         "application_name": "Flashduty DEV",
@@ -50992,7 +52762,8 @@
                         },
                         "type": "browser",
                         "updated_at": 1772096392711,
-                        "updated_by": 3122470302131
+                        "updated_by": 3122470302131,
+                        "repositories": []
                       }
                     ],
                     "total": 7
@@ -51024,6 +52795,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -51036,7 +52810,7 @@
           "RUM/Applications"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Use `is_my_team` to filter applications belonging to the current user's teams.\n- Default page size is 20, maximum is 100.\n- `orderby` accepts `created_at` or `updated_at`.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Private applications the caller cannot access are left out; the account owner and account admins see every application.\n- `is_my_team: true` keeps only applications owned by the caller's teams. If the caller belongs to no team, the filter is not applied.\n- `team_id`, `query` and `is_my_team` combine with AND.\n- Sorted by `updated_at` descending unless `orderby`/`asc` say otherwise.",
           "href": "/en/api-reference/rum/applications/rum-application-read-list",
           "metadata": {
             "sidebarTitle": "List applications"
@@ -51125,6 +52899,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -51137,7 +52914,7 @@
           "RUM/Applications"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Version `0` means the application has never been configured; SDKs then run entirely on their init values.\n- A change reaches a client when its next session starts unless activation is set to `immediate`.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Before the first publish, `version` and `updated_at` are `0` and `config` is `null`; SDKs then run entirely on their init values.\n- A change reaches a client when its next session starts unless `activation` is `immediate`.\n- An unknown or deleted `application_id` returns `ResourceNotFound`. A private application (`is_private: true`) is readable only by the account owner, account admins, its creator and members of its owning team; others get `AccessDenied`.",
           "href": "/en/api-reference/rum/applications/rum-application-remote-config-read-get",
           "metadata": {
             "sidebarTitle": "Get remote config detail"
@@ -51203,12 +52980,13 @@
                             }
                           ]
                         },
-                        "content_hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
-                        "reason": "Tighten replay sampling for the Q4 launch",
+                        "content_hash": "9f86d081884c7d65",
+                        "reason": "Re-apply the v7 sampling after the test",
                         "updated_at": 1773398630657,
                         "updated_by": 4441703362131,
                         "updated_by_name": "Alice Zhang",
-                        "version": 8
+                        "version": 8,
+                        "equivalent_to": 7
                       },
                       {
                         "config": {
@@ -51239,7 +53017,7 @@
                             }
                           ]
                         },
-                        "content_hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
+                        "content_hash": "9f86d081884c7d65",
                         "reason": "",
                         "updated_at": 1772398630657,
                         "updated_by": 4441703362131,
@@ -51276,6 +53054,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -51288,7 +53069,7 @@
           "RUM/Applications"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Newest first by default (`orderby=updated_at`, `asc=false`).\n- `content_hash` and `equivalent_to` identify versions whose content is identical, so the console can say \"this is an earlier version's content\" instead of showing a false difference.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Only the 50 most recent versions are kept; older versions are deleted when a new one is published and can no longer be listed or reverted to.\n- Newest first by default (`orderby=updated_at`, `asc=false`). An unrecognized `orderby` falls back to `updated_at`; ties are broken by `version`.\n- `content_hash` and `equivalent_to` identify versions with identical content, e.g. a revert that restored an earlier version.",
           "href": "/en/api-reference/rum/applications/rum-application-remote-config-read-history-list",
           "metadata": {
             "sidebarTitle": "List remote config history"
@@ -51350,6 +53131,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -51362,7 +53146,7 @@
           "RUM/Applications"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Applications Manage** (`rum`) |\n\n## Usage\n\n- History is never rewritten: the revert publishes the earlier version's content under a NEW version number.\n- An empty `reason` is filled in by the console as `rolled back to vN`.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Applications Manage** (`rum`) |\n\n## Usage\n\n- History is never rewritten: the revert publishes the earlier version's content under a new version number, which is returned.\n- `version` must still be in the retained history (the 50 most recent versions); otherwise the call returns `InvalidParameter` (`version not found`).\n- The restored content is validated against the current rules again and is rejected with `InvalidParameter` if it no longer passes.\n- The server does not generate a `reason`; an omitted `reason` is stored as an empty string.\n- The caller must be able to edit the application: the account owner, an account admin, the application's creator, or a member of its owning team; anyone else gets `AccessDenied`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/rum/applications/rum-application-remote-config-write-history-revert",
           "metadata": {
             "sidebarTitle": "Revert remote config"
@@ -51430,6 +53214,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -51442,7 +53229,7 @@
           "RUM/Applications"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Runs the same matcher as the engine, so the result matches what production clients receive.\n- Omit `config` to preview the currently live configuration.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Runs the same rule matcher the SDK config endpoint uses and publishes nothing.\n- Omit `config` to preview the live configuration; a supplied `config` is validated like an update and invalid drafts return `InvalidParameter`.\n- Rule conditions compare exact strings; a rule that tests `env`, `app_version` or `sdk` never matches when that field is omitted from the request.\n- If the configuration is disabled (`enabled: false`) or has never been published, `values` is empty and `hit_rule_index` is `-1`.",
           "href": "/en/api-reference/rum/applications/rum-application-remote-config-read-preview",
           "metadata": {
             "sidebarTitle": "Preview remote config"
@@ -51531,6 +53318,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -51543,7 +53333,7 @@
           "RUM/Applications"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Applications Manage** (`rum`) |\n\n## Usage\n\n- The client sends the complete object, not a patch: rule order is the priority, so a partial update has no unambiguous interpretation.\n- Each call allocates a new version and records a history row in the same transaction as the write.\n- Call `POST /rum/application/remote-config/preview` first to check what clients would receive.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Applications Manage** (`rum`) |\n\n## Usage\n\n- Send the complete configuration, not a patch: rule order is the priority, so a partial update has no unambiguous meaning.\n- Every call publishes a new version, even when the content is unchanged or `enabled` is `false`; only the 50 most recent versions are kept.\n- Call `POST /rum/application/remote-config/preview` first to check what clients would receive.\n- The caller must be able to edit the application: the account owner, an account admin, the application's creator, or a member of its owning team; anyone else gets `AccessDenied`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/rum/applications/rum-application-remote-config-write-update",
           "metadata": {
             "sidebarTitle": "Update remote config"
@@ -51553,7 +53343,7 @@
     },
     "/rum/application/update": {
       "post": {
-        "description": "Update an existing RUM application. All fields except `application_id` are optional — only provided fields are updated.",
+        "description": "Update selected fields of a RUM application; fields left out of the request keep their current values.",
         "operationId": "rum-application-write-update",
         "requestBody": {
           "content": {
@@ -51625,6 +53415,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -51637,7 +53430,7 @@
           "RUM/Applications"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Applications Manage** (`rum`) |\n\n## Usage\n\n- `links.systems[].url` must start with `http` or `https`; `${var}` tokens are resolved from RUM event context.\n- `links.systems[].event_types` accepts: `crash`, `error`, `view`, `action`, `resource`, `session`, `all`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Applications Manage** (`rum`) |\n\n## Usage\n\n- Only fields present in the request are changed. `alerting`, `tracing` and `links` replace the whole stored object when sent; `repositories` replaces the whole list.\n- When `tracing` is sent, `open_type` (`popup` or `tab`) and an `http`/`https` `endpoint` are required even if `enabled` is `false`.\n- `links.systems[].url` must start with `http` or `https`; each system needs a `name` and at least one `event_types` entry.\n- When `alerting` is sent with `delivery_mode` `oncall`, the existing `integration_id` is kept (or one is assigned); a client-supplied `integration_id` is ignored.\n- An unknown or deleted `application_id` returns `InvalidParameter`. The caller must be able to edit the application: the account owner, an account admin, the application's creator, or a member of its owning team; anyone else gets `AccessDenied`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/rum/applications/rum-application-write-update",
           "metadata": {
             "sidebarTitle": "Update application"
@@ -51653,7 +53446,7 @@
           "content": {
             "application/json": {
               "example": {
-                "application_id": "rum-app-prod",
+                "application_id": "WoyQQ3BohkdtPivubEvE8o",
                 "webhook_url": "https://hooks.example.com/rum-alerts"
               },
               "schema": {
@@ -51715,7 +53508,7 @@
           "RUM/Applications"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Applications Manage** (`rum`) |\n\n## Usage\n\n- The endpoint validates the URL before sending the sample event.\n- A failed delivery still returns HTTP 200 with `ok=false` and the delivery error in `message`.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- The URL must use `http` or `https`; on Flashduty cloud, hosts that resolve to private, loopback, link-local or reserved addresses are rejected with `InvalidParameter`.\n- The sample body has the same shape as real alert events: `account_id`, `data_source_type` (`rum.alert`), `title`, `event_severity`, `event_status`, `description`, `alert_key`, `labels`, and `event_time` (Unix seconds).\n- Each attempt times out after 10 seconds; transport errors, 5xx and 429 responses are retried up to 2 times.\n- A failed delivery still returns HTTP 200 with `ok: false` and the reason in `message`.\n- The caller must be able to edit the application: the account owner, an account admin, the application's creator, or a member of its owning team; anyone else gets `AccessDenied`.",
           "href": "/en/api-reference/rum/applications/rum-application-webhook-test",
           "metadata": {
             "sidebarTitle": "Test application webhook"
@@ -51736,8 +53529,7 @@
                   {
                     "format": "table",
                     "id": "errors_by_type",
-                    "sql": "SELECT error.type, count(*) AS errors FROM error GROUP BY error.type ORDER BY errors DESC LIMIT 10",
-                    "time_zone": "Asia/Shanghai"
+                    "sql": "SELECT error_type, count(*) AS errors FROM errors GROUP BY error_type ORDER BY errors DESC LIMIT 10"
                   }
                 ],
                 "start_time": 1712620800000
@@ -51759,23 +53551,23 @@
                       "data": {
                         "fields": [
                           {
-                            "name": "error.type",
-                            "nullable": false,
-                            "type": "String"
+                            "name": "error_type",
+                            "nullable": true,
+                            "type": "VARCHAR"
                           },
                           {
                             "name": "errors",
                             "nullable": false,
-                            "type": "UInt64"
+                            "type": "BIGINT"
                           }
                         ],
                         "values": [
                           [
                             "TypeError",
-                            1523
+                            "ReferenceError"
                           ],
                           [
-                            "ReferenceError",
+                            1523,
                             342
                           ]
                         ]
@@ -51809,6 +53601,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -51821,7 +53616,7 @@
           "RUM/Data query"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Send 1 to 10 queries in one request; each query `id` becomes a key in the response object.\n- `start_time` and `end_time` are required Unix epoch milliseconds. The maximum time range is 31 days.\n- Use `format: table` for tabular results, or `format: time_series` for bucketed time-series results.\n- For `time_series`, `interval` defaults to 3600 seconds and `max_points` defaults to 1226 when omitted.\n- `search_after_ctx` is returned by paginated table queries and can be sent back to continue scanning.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Send 1 to 10 queries in one request; each query `id` becomes a key in the response object.\n- `start_time` and `end_time` are Unix epoch milliseconds, at most 31 days apart. The server adds the time-range and account filters itself; you do not need them in `sql`.\n- `FROM` names a RUM scope table: `sessions`, `views`, `actions`, `errors`, `resources`, `long_tasks`, `vitals`, `issues` or `sourcemaps` (the singular form is also accepted). Column names are the `field_key` values returned by `POST /rum/field/list`.\n- A query whose top-level `AND` conditions pin `application_id` (`=` or `IN`) must name applications the caller can read: a private application the caller's team does not own fails the whole request with `AccessDenied`, an unknown one with `ResourceNotFound`, and one request may name at most 50 distinct applications. A query that names no application silently skips the private applications the caller cannot read.\n- Malformed SQL, an invalid `time_zone` or an out-of-range time window fails the whole request with `InvalidParameter`. A query that fails later (unknown table or column, invalid `dql`, invalid `search_after_ctx`, database error) only sets `error` on its own entry, with code `InternalError`; the other queries still return `data`.\n- `values` is column-major: `values[i]` holds every row's value of column `fields[i]`.\n- `table` queries return at most 1,000 rows; a missing `LIMIT` or one above 1,000 is replaced with 1,000. A non-aggregate query with `ORDER BY` and no `OFFSET` returns `search_after_ctx` when the page is full — send it back with the same `sql` to get the next page.\n- `time_series` queries get a `ts` column prepended (bucket start, Unix milliseconds), grouped and ordered by it. The bucket width, returned as `interval` in milliseconds, is the smallest step from a fixed ladder (1, 2, 5, 10, 20, 50, 100, 200, 500 ms; 1, 2, 5, 10, 15, 30 s; 1, 2, 5, 10, 15, 30 min; 1, 2, 3, 6, 12 h; 1, 2, 3, 7 d; 30, 60, 90, 180 d) that is at least both `interval` and the window length divided by `max_points`.\n- On large time windows an aggregate query may run on sampled data; the response then carries `sampling`, and `COUNT`, `SUM` and `COUNT(DISTINCT)` columns are already multiplied by `scale_factor`. Set `disable_sampling: true` to always query the full data.",
           "href": "/en/api-reference/rum/data-query/rum-read-data-query",
           "metadata": {
             "sidebarTitle": "Query RUM data"
@@ -51831,43 +53626,36 @@
     },
     "/rum/error-ingestion/rules/create": {
       "post": {
-        "description": "Create a new error ingestion rule that filters which errors are stored.",
+        "description": "Create a rule whose matching errors are kept out of issue grouping; matched errors are still stored.",
         "operationId": "rum-error-ingestion-rules-create",
         "requestBody": {
           "content": {
             "application/json": {
               "example": {
                 "application_id": "WoyQQ3BohkdtPivubEvE8o",
-                "description": "Only ingest TypeError/ReferenceError from production, excluding Safari.",
+                "description": "Keep cross-origin script errors, ResizeObserver warnings, and debug pages out of issues.",
                 "filters": [
                   [
                     {
-                      "key": "error.env",
+                      "key": "error.error_message",
                       "oper": "IN",
                       "vals": [
-                        "production"
-                      ]
-                    },
-                    {
-                      "key": "error.error_type",
-                      "oper": "IN",
-                      "vals": [
-                        "TypeError",
-                        "ReferenceError"
+                        "Script error.",
+                        "ResizeObserver loop*"
                       ]
                     }
                   ],
                   [
                     {
-                      "key": "error.browser_name",
-                      "oper": "NOTIN",
+                      "key": "error.view_url",
+                      "oper": "IN",
                       "vals": [
-                        "Safari"
+                        "https://example.com/debug/*"
                       ]
                     }
                   ]
                 ],
-                "rule_name": "Production console errors"
+                "rule_name": "Ignore browser noise"
               },
               "schema": {
                 "$ref": "#/components/schemas/RumErrorIngestionCreateRequest"
@@ -51883,7 +53671,7 @@
                 "example": {
                   "data": {
                     "rule_id": "9spXEVoMeZWujjz25yrgTe",
-                    "rule_name": "Production console errors"
+                    "rule_name": "Ignore browser noise"
                   },
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 },
@@ -51912,6 +53700,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -51924,7 +53715,7 @@
           "RUM/Error ingestion rules"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Create, update, enable, disable, and delete all snapshot the application's full current rule set into history first, so `history/list` reflects every mutation.\n- Every condition key in `filters` must be one of the supported `error.*` fields or a `context.*` path; unsupported keys are rejected with `InvalidParameter`.\n- New rules are created with status `enabled`; call `disable` afterward if the rule should start inactive.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- A matched error is still stored and queryable, but is not grouped into any issue, and its `issue_grouping_excluded` field is set to `true`.\n- Rules are matched against the error's raw type and message as reported by the SDK, before the server parses the stack trace.\n- Every condition key in `filters` must be one of the supported `error.*` fields or a `context.*` path; unsupported keys, unknown operators, empty `vals`, or invalid regexp/CIDR/number patterns return `InvalidParameter`.\n- New rules start with status `enabled`; call `disable` afterward if the rule should start inactive.\n- Each write first saves the application's whole rule set, as it was before the change, as a new history version.\n- Ingestion reads enabled rules from a per-application cache that lives 5 seconds, so the change applies to newly ingested errors within about 5 seconds.\n- Requires edit access to the application (account owner or admin, the application's creator, or a member of its team); otherwise returns `AccessDenied`. An unknown `application_id` returns `ResourceNotFound`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/rum/error-ingestion-rules/rum-error-ingestion-rules-create",
           "metadata": {
             "sidebarTitle": "Create an error ingestion rule"
@@ -51983,147 +53774,156 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
-          "429": {
-            "$ref": "#/components/responses/TooManyRequests"
-          },
-          "500": {
-            "$ref": "#/components/responses/ServerError"
-          }
-        },
-        "summary": "Delete an error ingestion rule",
-        "tags": [
-          "RUM/Error ingestion rules"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- The rule disappears from `list` immediately, but the enabled-rule set used for filtering is cached for up to 5 seconds, so errors ingested shortly after deletion can still be matched against it.\n- Returns `ResourceNotFound` if `rule_id` doesn't exist under `application_id`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
-          "href": "/en/api-reference/rum/error-ingestion-rules/rum-error-ingestion-rules-delete",
-          "metadata": {
-            "sidebarTitle": "Delete an error ingestion rule"
-          }
-        }
-      }
-    },
-    "/rum/error-ingestion/rules/disable": {
-      "post": {
-        "description": "Disable an error ingestion rule without deleting it.",
-        "operationId": "rum-error-ingestion-rules-disable",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "application_id": "WoyQQ3BohkdtPivubEvE8o",
-                "rule_id": "9spXEVoMeZWujjz25yrgTe"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/RumErrorIngestionRuleIDRequest"
-              }
-            }
-          },
-          "required": true
-        },
-        "responses": {
-          "200": {
-            "content": {
-              "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/RumErrorIngestionEmptyResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
-                }
-              }
-            },
-            "description": "Success"
-          },
-          "400": {
-            "$ref": "#/components/responses/BadRequest"
-          },
-          "401": {
-            "$ref": "#/components/responses/Unauthorized"
-          },
-          "429": {
-            "$ref": "#/components/responses/TooManyRequests"
-          },
-          "500": {
-            "$ref": "#/components/responses/ServerError"
-          }
-        },
-        "summary": "Disable an error ingestion rule",
-        "tags": [
-          "RUM/Error ingestion rules"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- A disabled rule is kept and still returned by `list`, but is skipped when matching incoming errors.\n- Returns `ResourceNotFound` if `rule_id` doesn't exist under `application_id`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
-          "href": "/en/api-reference/rum/error-ingestion-rules/rum-error-ingestion-rules-disable",
-          "metadata": {
-            "sidebarTitle": "Disable an error ingestion rule"
-          }
-        }
-      }
-    },
-    "/rum/error-ingestion/rules/enable": {
-      "post": {
-        "description": "Re-enable a previously disabled error ingestion rule.",
-        "operationId": "rum-error-ingestion-rules-enable",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "application_id": "WoyQQ3BohkdtPivubEvE8o",
-                "rule_id": "9spXEVoMeZWujjz25yrgTe"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/RumErrorIngestionRuleIDRequest"
-              }
-            }
-          },
-          "required": true
-        },
-        "responses": {
-          "200": {
-            "content": {
-              "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/RumErrorIngestionEmptyResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
-                }
-              }
-            },
-            "description": "Success"
-          },
-          "400": {
-            "$ref": "#/components/responses/BadRequest"
-          },
-          "401": {
-            "$ref": "#/components/responses/Unauthorized"
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "429": {
+            "$ref": "#/components/responses/TooManyRequests"
+          },
+          "500": {
+            "$ref": "#/components/responses/ServerError"
+          }
+        },
+        "summary": "Delete an error ingestion rule",
+        "tags": [
+          "RUM/Error ingestion rules"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- The rule disappears from `list` immediately and can't be enabled or updated again; to bring it back, revert to a history version that still contains it.\n- Returns `ResourceNotFound` if `rule_id` doesn't exist (or was deleted) under `application_id`.\n- Each write first saves the application's whole rule set, as it was before the change, as a new history version.\n- Ingestion reads enabled rules from a per-application cache that lives 5 seconds, so the change applies to newly ingested errors within about 5 seconds.\n- Requires edit access to the application (account owner or admin, the application's creator, or a member of its team); otherwise returns `AccessDenied`. An unknown `application_id` returns `ResourceNotFound`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "href": "/en/api-reference/rum/error-ingestion-rules/rum-error-ingestion-rules-delete",
+          "metadata": {
+            "sidebarTitle": "Delete an error ingestion rule"
+          }
+        }
+      }
+    },
+    "/rum/error-ingestion/rules/disable": {
+      "post": {
+        "description": "Disable an error ingestion rule without deleting it.",
+        "operationId": "rum-error-ingestion-rules-disable",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "example": {
+                "application_id": "WoyQQ3BohkdtPivubEvE8o",
+                "rule_id": "9spXEVoMeZWujjz25yrgTe"
+              },
+              "schema": {
+                "$ref": "#/components/schemas/RumErrorIngestionRuleIDRequest"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "example": {
+                  "data": {},
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
+                },
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/RumErrorIngestionEmptyResponse"
+                        }
+                      },
+                      "type": "object"
+                    }
+                  ]
+                }
+              }
+            },
+            "description": "Success"
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "429": {
+            "$ref": "#/components/responses/TooManyRequests"
+          },
+          "500": {
+            "$ref": "#/components/responses/ServerError"
+          }
+        },
+        "summary": "Disable an error ingestion rule",
+        "tags": [
+          "RUM/Error ingestion rules"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- A disabled rule is kept and still returned by `list`, but is skipped when matching incoming errors.\n- Returns `ResourceNotFound` if `rule_id` doesn't exist (or was deleted) under `application_id`.\n- Each write first saves the application's whole rule set, as it was before the change, as a new history version.\n- Ingestion reads enabled rules from a per-application cache that lives 5 seconds, so the change applies to newly ingested errors within about 5 seconds.\n- Requires edit access to the application (account owner or admin, the application's creator, or a member of its team); otherwise returns `AccessDenied`. An unknown `application_id` returns `ResourceNotFound`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "href": "/en/api-reference/rum/error-ingestion-rules/rum-error-ingestion-rules-disable",
+          "metadata": {
+            "sidebarTitle": "Disable an error ingestion rule"
+          }
+        }
+      }
+    },
+    "/rum/error-ingestion/rules/enable": {
+      "post": {
+        "description": "Re-enable a previously disabled error ingestion rule.",
+        "operationId": "rum-error-ingestion-rules-enable",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "example": {
+                "application_id": "WoyQQ3BohkdtPivubEvE8o",
+                "rule_id": "9spXEVoMeZWujjz25yrgTe"
+              },
+              "schema": {
+                "$ref": "#/components/schemas/RumErrorIngestionRuleIDRequest"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "example": {
+                  "data": {},
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
+                },
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/RumErrorIngestionEmptyResponse"
+                        }
+                      },
+                      "type": "object"
+                    }
+                  ]
+                }
+              }
+            },
+            "description": "Success"
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
           },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
@@ -52137,7 +53937,7 @@
           "RUM/Error ingestion rules"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Returns `ResourceNotFound` if `rule_id` doesn't exist under `application_id`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Enabling a rule that is already enabled succeeds and still writes a history version.\n- Returns `ResourceNotFound` if `rule_id` doesn't exist (or was deleted) under `application_id`.\n- Each write first saves the application's whole rule set, as it was before the change, as a new history version.\n- Ingestion reads enabled rules from a per-application cache that lives 5 seconds, so the change applies to newly ingested errors within about 5 seconds.\n- Requires edit access to the application (account owner or admin, the application's creator, or a member of its team); otherwise returns `AccessDenied`. An unknown `application_id` returns `ResourceNotFound`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/rum/error-ingestion-rules/rum-error-ingestion-rules-enable",
           "metadata": {
             "sidebarTitle": "Enable an error ingestion rule"
@@ -52182,38 +53982,31 @@
                             "created_at": 1786000000000,
                             "created_by": 1001,
                             "deleted_at": 0,
-                            "description": "Only ingest TypeError/ReferenceError from production, excluding Safari.",
+                            "description": "Keep cross-origin script errors, ResizeObserver warnings, and debug pages out of issues.",
                             "filters": [
                               [
                                 {
-                                  "key": "error.env",
-                                  "oper": "IN",
-                                  "vals": [
-                                    "production"
-                                  ]
-                                },
-                                {
-                                  "key": "error.error_type",
+                                  "key": "error.error_message",
                                   "oper": "IN",
                                   "vals": [
-                                    "TypeError",
-                                    "ReferenceError"
+                                    "Script error.",
+                                    "ResizeObserver loop*"
                                   ]
                                 }
                               ],
                               [
                                 {
-                                  "key": "error.browser_name",
-                                  "oper": "NOTIN",
+                                  "key": "error.view_url",
+                                  "oper": "IN",
                                   "vals": [
-                                    "Safari"
+                                    "https://example.com/debug/*"
                                   ]
                                 }
                               ]
                             ],
                             "id": 1044,
                             "rule_id": "9spXEVoMeZWujjz25yrgTe",
-                            "rule_name": "Production console errors",
+                            "rule_name": "Ignore browser noise",
                             "status": "enabled",
                             "updated_at": 1786000000000,
                             "updated_by": 1001
@@ -52261,6 +54054,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -52273,7 +54069,7 @@
           "RUM/Error ingestion rules"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- One history item is a full snapshot of every rule for the application at that point in time, not a diff of a single rule.\n- `p` is a zero-based page number, not a byte offset — the server computes `offset = p * limit` internally.\n- `orderby` accepts `updated_at` or `version`; any other value silently falls back to `updated_at`.\n- `limit` defaults to 20 and is capped at 100 server-side; values above 100 are silently clamped, values of 0 or below fall back to the default.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Each write first saves the rule set as it was before the change, so version N holds the rules just before the Nth change, and its `updated_by`/`updated_at` identify that change. The current rule set is returned by `list`, not here.\n- One history item is a full snapshot of every non-deleted rule for the application, not a diff of a single rule.\n- `p` is a zero-based page number: the server skips `p * limit` items.\n- `limit` defaults to 20 and is capped at 100; values above 100 are clamped, values of 0 or below fall back to the default.\n- Any member can read a public application; a private application requires edit access (account owner or admin, its creator, or a member of its team), otherwise `AccessDenied`. An unknown `application_id` returns `ResourceNotFound`.",
           "href": "/en/api-reference/rum/error-ingestion-rules/rum-error-ingestion-rules-history-list",
           "metadata": {
             "sidebarTitle": "List error ingestion rule history"
@@ -52332,6 +54128,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -52344,7 +54143,7 @@
           "RUM/Error ingestion rules"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Revert replaces the entire rule set for the application — rules created after the target version are removed, not merged.\n- The current state is snapshotted into history before the revert runs, so a revert can itself be undone by reverting again.\n- Returns `InvalidParameter` (not `ResourceNotFound`) when `version` doesn't exist for the application.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Version N holds the rules as they were just before the Nth change, so reverting to version N undoes change N and every later change.\n- Revert replaces the entire rule set for the application: rules that are not in the target version are removed, not merged.\n- Restored rules keep their `rule_id`, name, description, filters, and status; their `created_at` and `updated_at` are reset to the revert time.\n- The current state is saved as a new history version before the revert runs, so a revert can itself be undone by reverting again.\n- Returns `InvalidParameter` (not `ResourceNotFound`) when `version` doesn't exist for the application.\n- Ingestion reads enabled rules from a per-application cache that lives 5 seconds, so the change applies to newly ingested errors within about 5 seconds.\n- Requires edit access to the application (account owner or admin, the application's creator, or a member of its team); otherwise returns `AccessDenied`. An unknown `application_id` returns `ResourceNotFound`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/rum/error-ingestion-rules/rum-error-ingestion-rules-history-revert",
           "metadata": {
             "sidebarTitle": "Revert error ingestion rules to a history version"
@@ -52378,37 +54177,30 @@
                     "items": [
                       {
                         "created_at": 1786000000000,
-                        "description": "Only ingest TypeError/ReferenceError from production, excluding Safari.",
+                        "description": "Known browser noise and errors from internal debug pages.",
                         "filters": [
                           [
                             {
-                              "key": "error.env",
-                              "oper": "IN",
-                              "vals": [
-                                "production"
-                              ]
-                            },
-                            {
-                              "key": "error.error_type",
+                              "key": "error.error_message",
                               "oper": "IN",
                               "vals": [
-                                "TypeError",
-                                "ReferenceError"
+                                "Script error.",
+                                "ResizeObserver loop*"
                               ]
                             }
                           ],
                           [
                             {
-                              "key": "error.browser_name",
-                              "oper": "NOTIN",
+                              "key": "error.view_url",
+                              "oper": "IN",
                               "vals": [
-                                "Safari"
+                                "https://example.com/debug/*"
                               ]
                             }
                           ]
                         ],
                         "rule_id": "9spXEVoMeZWujjz25yrgTe",
-                        "rule_name": "Production console errors",
+                        "rule_name": "Ignore browser noise",
                         "status": "enabled",
                         "updated_at": 1786003600000
                       }
@@ -52441,6 +54233,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -52453,7 +54248,7 @@
           "RUM/Error ingestion rules"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Deleted rules are excluded; only rules with status `enabled` or `disabled` are returned.\n- Rules are ordered newest-created first.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Deleted rules are excluded; only rules with status `enabled` or `disabled` are returned.\n- Rules are ordered newest-created first. The list is not paginated.\n- Any member can read a public application; a private application requires edit access (account owner or admin, its creator, or a member of its team), otherwise `AccessDenied`. An unknown `application_id` returns `ResourceNotFound`.",
           "href": "/en/api-reference/rum/error-ingestion-rules/rum-error-ingestion-rules-list",
           "metadata": {
             "sidebarTitle": "List error ingestion rules"
@@ -52470,7 +54265,7 @@
             "application/json": {
               "example": {
                 "application_id": "WoyQQ3BohkdtPivubEvE8o",
-                "description": "Now also excludes staging traffic.",
+                "description": "Known browser noise and errors from internal debug pages.",
                 "rule_id": "9spXEVoMeZWujjz25yrgTe"
               },
               "schema": {
@@ -52513,6 +54308,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -52525,7 +54323,7 @@
           "RUM/Error ingestion rules"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Only fields present in the request are changed; omitted fields keep their current value.\n- Calling update with no fields set is a no-op that still returns success.\n- Returns `ResourceNotFound` if `rule_id` doesn't exist under `application_id`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Only fields present in the request are changed; omitted or `null` fields keep their current value.\n- Calling update with no fields set changes nothing and writes no history version, but still returns success.\n- New `filters` are validated the same way as on `create`; invalid ones return `InvalidParameter`.\n- Returns `ResourceNotFound` if `rule_id` doesn't exist (or was deleted) under `application_id`.\n- Each write first saves the application's whole rule set, as it was before the change, as a new history version.\n- Ingestion reads enabled rules from a per-application cache that lives 5 seconds, so the change applies to newly ingested errors within about 5 seconds.\n- Requires edit access to the application (account owner or admin, the application's creator, or a member of its team); otherwise returns `AccessDenied`. An unknown `application_id` returns `ResourceNotFound`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/rum/error-ingestion-rules/rum-error-ingestion-rules-update",
           "metadata": {
             "sidebarTitle": "Update an error ingestion rule"
@@ -52542,7 +54340,7 @@
             "application/json": {
               "example": {
                 "end_time": 1712707200000,
-                "facet_key": "error.type",
+                "facet_key": "error_type",
                 "limit": 10,
                 "scope": "error",
                 "start_time": 1712620800000
@@ -52602,6 +54400,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -52614,7 +54415,7 @@
           "RUM/Facets"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **100 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Use `POST /rum/field/list` with `is_facet: true` to discover available `facet_key` values for each scope.\n- The `scope` must be one of: `session`, `view`, `action`, `error`, `resource`, `long_task`, `vital`, `issue`, `sourcemap`.\n- Pass `dql` to further filter events before counting. DQL syntax follows the RUM query language.\n- Pass `sql` with a WHERE-clause only (no SELECT) for SQL-style filtering.\n- Default limit is 100; maximum is 100.\n- Time range is required (`start_time` / `end_time` in Unix epoch **milliseconds**). Maximum span is 31 days.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **100 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Use `POST /rum/field/list` with `is_facet: true` to discover `facet_key` values for each scope.\n- `facet_key` must be a facet field (`is_facet: true`) of the requested `scope` with `show_type: list` and a non-array `value_type`; otherwise the call returns `InvalidParameter`.\n- Events where `facet_key` is `null` are not counted. Pass `facet_value` to count only events equal to that value; its JSON type must match the field's `value_type`.\n- Pass `dql` to filter events before counting. Pass `sql` as a bare `WHERE` condition; the word `SELECT` anywhere in it (case-insensitive) is rejected.\n- `limit` defaults to 100; maximum is 100.\n- `start_time` / `end_time` are required Unix epoch **milliseconds**, at most 31 days apart.\n- For `scope: sourcemap`, `type` and `kind` choose which symbol store is counted.",
           "href": "/en/api-reference/rum/facets/rum-read-facet-count",
           "metadata": {
             "sidebarTitle": "Count facet value distribution"
@@ -52651,19 +54452,20 @@
                     "items": [
                       {
                         "account_id": 0,
-                        "description": "The type of the error.",
+                        "description": "Error type or class depending on the language. Examples: `TypeError`, `NotFoundError`.",
                         "edit_able": false,
                         "enum_values": [],
-                        "field_key": "error.type",
-                        "field_name": "Error type",
-                        "group": "Error",
+                        "field_key": "error_type",
+                        "field_name": "Error Type",
+                        "group": "error",
                         "is_facet": true,
                         "queryable": true,
                         "scopes": [
-                          "error"
+                          "error",
+                          "issue"
                         ],
                         "show_type": "list",
-                        "status": "active",
+                        "status": "enabled",
                         "unit_family": "",
                         "unit_name": "",
                         "value_type": "string"
@@ -52697,6 +54499,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -52719,7 +54524,7 @@
     },
     "/rum/issue/export": {
       "post": {
-        "description": "Export the filtered RUM error tracking issues as a CSV file. The response is a `text/csv` stream delivered with `Content-Disposition: attachment` — it is not a JSON envelope; non-console callers can read the `X-Export-Total` and `X-Export-Truncated` response headers.",
+        "description": "Export the issues matching the `POST /rum/issue/list` filters as a CSV file of at most 100 rows.",
         "operationId": "rum-issue-read-export",
         "requestBody": {
           "content": {
@@ -52787,6 +54592,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -52799,7 +54607,7 @@
           "RUM/Issues"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **200 requests/day**; **100 requests/minute**; **10 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- The response is a `text/csv` stream delivered with `Content-Disposition: attachment` — it is not wrapped in the standard envelope. The filename is `rum-issues-<timestamp>.csv`, stamped in the requested `time_zone`. Read `X-Export-Total` and `X-Export-Truncated` response headers instead of a body field.\n- The export reads the first 100 matching rows (`ExportMaxRows`); `X-Export-Truncated` is `true` when more issues match. `p` and `limit` are ignored.\n- The request filters are exactly those of `POST /rum/issue/list` — an export is \"what I am looking at, as a file\".\n- `export_fields` names the CSV columns in the order they appear. Unknown keys are rejected with a parameter error; an empty array uses the default column set.\n- `time_zone` must be a valid IANA zone name (e.g. `Asia/Shanghai`, `UTC`); timestamps are rendered in that zone and time columns carry the zone in their header. Invalid names are rejected.\n- `console_origin` is used to build the `issue_url` column; the service cannot infer it (SaaS, on-premises and dev releases answer on different origins).\n- Every call is recorded in the account's audit log with the caller's member ID, request payload, and resulting error (if any). Do not put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **200 requests/day**; **100 requests/minute**; **10 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- On success the body is a `text/csv` attachment named `rum-issues-<yyyyMMdd-HHmmss>.csv` (stamped in `time_zone`), not the JSON envelope. Validation and other errors still return the JSON error envelope.\n- `X-Export-Total` carries the number of matching issues; `X-Export-Truncated` is `true` when more than 100 matched and only the first 100 (in `orderby` order) were written. `p` and `limit` are ignored.\n- The filters behave exactly as in `POST /rum/issue/list`, including the exclusion of private applications the caller cannot access.\n- `export_fields` lists the columns in output order; unknown keys are rejected, duplicates are dropped, and an empty or omitted array exports every column except the `sample_first_*` group.\n- `sample_*` columns describe the latest error event of the issue inside `[start_time, end_time]`, `sample_first_*` the earliest; they are empty when the issue has no event in that window.\n- Header titles are English, or Chinese when the request locale is Chinese (`Accept-Language` header, or `locale` / `lang` query parameter). Time columns are rendered as `yyyy-MM-dd HH:mm:ss` in `time_zone`, carry the zone in their header, and are empty when the time is unset.\n- Cells starting with `=`, `+`, `-`, `@`, tab or carriage return are prefixed with `'` so spreadsheets do not evaluate them as formulas.\n- Every call is recorded in the account's audit log with the caller's member ID, request payload, and resulting error (if any). Do not put secrets in request fields.",
           "href": "/en/api-reference/rum/issues/rum-issue-read-export",
           "metadata": {
             "sidebarTitle": "Export issues as CSV"
@@ -52851,6 +54659,7 @@
                     },
                     "resolved_at": 0,
                     "resolved_by": 0,
+                    "resolve_mode": "version",
                     "service": "fd-console",
                     "session_count": 381,
                     "severity": "Info",
@@ -52894,6 +54703,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -52906,7 +54718,7 @@
           "RUM/Issues"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- `team_id` is the owning application's **current** team; `POST /rum/issue/list` and `POST /rum/issue/export` report the team recorded when the issue was first seen, which differs once the application moves to another team.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- `team_id` is the owning application's **current** team; `POST /rum/issue/list` and `POST /rum/issue/export` report the team recorded when the issue was first seen, which differs once the application moves to another team.\n- An unknown or deleted `issue_id` returns `InvalidParameter` (\"The specified issue does not exist\"), not `ResourceNotFound`.",
           "href": "/en/api-reference/rum/issues/rum-issue-read-info",
           "metadata": {
             "sidebarTitle": "Get issue detail"
@@ -52971,6 +54783,7 @@
                         },
                         "resolved_at": 0,
                         "resolved_by": 0,
+                        "resolve_mode": "version",
                         "service": "fd-console",
                         "session_count": 381,
                         "severity": "Info",
@@ -53009,6 +54822,7 @@
                         },
                         "resolved_at": 0,
                         "resolved_by": 0,
+                        "resolve_mode": "version",
                         "service": "fd-console",
                         "session_count": 1,
                         "severity": "Info",
@@ -53055,6 +54869,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -53067,7 +54884,7 @@
           "RUM/Issues"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- `start_time` and `end_time` are millisecond timestamps. Maximum range: 183 days.\n- `statuses` filters by issue status. Valid values: `for_review`, `reviewed`, `ignored`, `resolved`.\n- `orderby` accepts: `created_at`, `updated_at`, `session_count`, `error_count`, `severity`.\n- Use `dql` or `sql` for advanced filtering. Cannot provide both.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- `start_time` and `end_time` are millisecond timestamps. Maximum range: 183 days.\n- By default an issue matches when it was created inside the window; with `by_intersection=true` it matches when it was created before `end_time` and last seen at or after `start_time`.\n- Issues of private applications are excluded unless the caller is the account owner or an admin, created the application, or belongs to its team.\n- `statuses` filters by issue status. Valid values: `for_review`, `reviewed`, `ignored`, `resolved`.\n- `orderby` accepts: `created_at`, `updated_at` (default), `session_count`, `error_count`, `severity`. With `severity`, issues without a severity always sort last.\n- Use `dql` or `sql` for advanced filtering. Cannot provide both.",
           "href": "/en/api-reference/rum/issues/rum-issue-read-list",
           "metadata": {
             "sidebarTitle": "List issues"
@@ -53150,6 +54967,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -53162,7 +54982,7 @@
           "RUM/Issue preset severity rules"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- `filters.*.key` accepts only a fixed set of Error-level attributes; any other key returns `InvalidParameter`.\n- Pass at least one condition group: an empty `filters` array is accepted but produces a rule that can never match.\n- The new rule is created enabled and appended with the lowest evaluation precedence (`priority` = current max + 1); use the `reorder` operation to move it earlier.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- `filters.*.key` accepts only a fixed set of Error-level attributes; any other key returns `InvalidParameter`.\n- Pass at least one condition group: an empty `filters` array is accepted but produces a rule that can never match.\n- The new rule is created enabled and appended with the lowest evaluation precedence (`priority` = current max + 1); use the `reorder` operation to move it earlier.\n- Requires edit rights on the application (account owner or admin, the application's creator, or a member of its team); otherwise returns `AccessDenied`. An unknown `application_id` returns `ResourceNotFound`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/rum/issue-preset-severity-rules/rum-issue-preset-severity-rules-create",
           "metadata": {
             "sidebarTitle": "Create preset severity rule"
@@ -53193,7 +55013,6 @@
             "content": {
               "application/json": {
                 "example": {
-                  "data": {},
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 },
                 "schema": {
@@ -53221,76 +55040,81 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
-          "429": {
-            "$ref": "#/components/responses/TooManyRequests"
-          },
-          "500": {
-            "$ref": "#/components/responses/ServerError"
-          }
-        },
-        "summary": "Delete preset severity rule",
-        "tags": [
-          "RUM/Issue preset severity rules"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Returns `ResourceNotFound` if `rule_id` does not exist in the application.\n- Deletion is a soft delete: the rule stops being listed immediately, but enabled rules are cached for up to 5 seconds, so it can still be evaluated against errors ingested shortly afterwards. Its pre-delete state remains visible via the history endpoints.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
-          "href": "/en/api-reference/rum/issue-preset-severity-rules/rum-issue-preset-severity-rules-delete",
-          "metadata": {
-            "sidebarTitle": "Delete preset severity rule"
-          }
-        }
-      }
-    },
-    "/rum/issue/preset-severity/rules/disable": {
-      "post": {
-        "description": "Disable a preset severity rule.",
-        "operationId": "rum-issue-preset-severity-rules-disable",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "application_id": "WoyQQ3BohkdtPivubEvE8o",
-                "rule_id": "TAHUYnQmXKzgMS4TFVUKvz"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/RumPresetSeverityRuleIDRequest"
-              }
-            }
-          },
-          "required": true
-        },
-        "responses": {
-          "200": {
-            "content": {
-              "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/EmptyResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
-                }
-              }
-            },
-            "description": "Success"
-          },
-          "400": {
-            "$ref": "#/components/responses/BadRequest"
-          },
-          "401": {
-            "$ref": "#/components/responses/Unauthorized"
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "429": {
+            "$ref": "#/components/responses/TooManyRequests"
+          },
+          "500": {
+            "$ref": "#/components/responses/ServerError"
+          }
+        },
+        "summary": "Delete preset severity rule",
+        "tags": [
+          "RUM/Issue preset severity rules"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Returns `ResourceNotFound` if `rule_id` does not exist in the application.\n- Deletion is a soft delete: the rule stops being listed immediately, but enabled rules are cached for up to 5 seconds, so it can still be evaluated against errors ingested shortly afterwards. Its pre-delete state remains visible via the history endpoints.\n- Requires edit rights on the application (account owner or admin, the application's creator, or a member of its team); otherwise returns `AccessDenied`. An unknown `application_id` returns `ResourceNotFound`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "href": "/en/api-reference/rum/issue-preset-severity-rules/rum-issue-preset-severity-rules-delete",
+          "metadata": {
+            "sidebarTitle": "Delete preset severity rule"
+          }
+        }
+      }
+    },
+    "/rum/issue/preset-severity/rules/disable": {
+      "post": {
+        "description": "Disable a preset severity rule.",
+        "operationId": "rum-issue-preset-severity-rules-disable",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "example": {
+                "application_id": "WoyQQ3BohkdtPivubEvE8o",
+                "rule_id": "TAHUYnQmXKzgMS4TFVUKvz"
+              },
+              "schema": {
+                "$ref": "#/components/schemas/RumPresetSeverityRuleIDRequest"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
+                },
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/EmptyResponse"
+                        }
+                      },
+                      "type": "object"
+                    }
+                  ]
+                }
+              }
+            },
+            "description": "Success"
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
           },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
@@ -53304,7 +55128,7 @@
           "RUM/Issue preset severity rules"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Returns `ResourceNotFound` if `rule_id` does not exist in the application.\n- A disabled rule is skipped during evaluation but keeps its `priority` slot; the cache can take up to 5 seconds to reflect the change.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Returns `ResourceNotFound` if `rule_id` does not exist in the application.\n- A disabled rule is skipped during evaluation but keeps its `priority` slot; the cache can take up to 5 seconds to reflect the change.\n- Requires edit rights on the application (account owner or admin, the application's creator, or a member of its team); otherwise returns `AccessDenied`. An unknown `application_id` returns `ResourceNotFound`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/rum/issue-preset-severity-rules/rum-issue-preset-severity-rules-disable",
           "metadata": {
             "sidebarTitle": "Disable preset severity rule"
@@ -53335,7 +55159,6 @@
             "content": {
               "application/json": {
                 "example": {
-                  "data": {},
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 },
                 "schema": {
@@ -53363,6 +55186,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -53375,7 +55201,7 @@
           "RUM/Issue preset severity rules"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Returns `ResourceNotFound` if `rule_id` does not exist in the application.\n- Enabled rules are cached for up to 5 seconds, so the effect on newly ingested errors can lag by a few seconds.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Returns `ResourceNotFound` if `rule_id` does not exist in the application.\n- Enabled rules are cached for up to 5 seconds, so the effect on newly ingested errors can lag by a few seconds.\n- Requires edit rights on the application (account owner or admin, the application's creator, or a member of its team); otherwise returns `AccessDenied`. An unknown `application_id` returns `ResourceNotFound`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/rum/issue-preset-severity-rules/rum-issue-preset-severity-rules-enable",
           "metadata": {
             "sidebarTitle": "Enable preset severity rule"
@@ -53551,6 +55377,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -53563,7 +55392,7 @@
           "RUM/Issue preset severity rules"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Each entry is an application-level snapshot of every rule as it existed immediately *before* the mutation that produced it — not a diff. A fresh snapshot is written before every create/update/enable/disable/delete/reorder/revert call that actually changes something — an `update` carrying none of the mutable fields returns success without writing one — so `version=1` is typically an empty rule set captured just before the first rule was ever created.\n- `rules` items carry the full internal row (including `account_id`, `created_by`, `id`, `deleted_at`), which is a wider shape than the one returned by `rules/list`.\n- `limit` defaults to 20 and is silently capped at 100 rather than rejected.\n- `orderby` accepts only `updated_at` or `version`; any other value (including omitted) falls back to `updated_at` rather than erroring.\n- Results sort descending by default; pass `asc=true` for ascending order.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Each entry is an application-level snapshot of every rule as it existed immediately *before* the mutation that produced it — not a diff. A snapshot is written before every successful create/update/enable/disable/delete/reorder/revert call, even one that leaves the rules unchanged (for example enabling a rule that is already enabled); only an `update` carrying none of the mutable fields skips it. `version=1` is therefore typically an empty rule set captured just before the first rule was created.\n- `rules` items carry the full internal row (including `account_id`, `created_by`, `id`, `deleted_at`), which is a wider shape than the one returned by `rules/list`.\n- `limit` defaults to 20 and is silently capped at 100 rather than rejected.\n- `orderby` accepts only `updated_at` or `version`; any other value (including omitted) falls back to `updated_at` rather than erroring.\n- Results sort descending by default; pass `asc=true` for ascending order.\n- Rules of a private application can be read only by callers with edit rights on it (account owner or admin, its creator, or a member of its team); others get `AccessDenied`. An unknown `application_id` returns `ResourceNotFound`.",
           "href": "/en/api-reference/rum/issue-preset-severity-rules/rum-issue-preset-severity-rules-history-list",
           "metadata": {
             "sidebarTitle": "List preset severity rule history"
@@ -53594,7 +55423,6 @@
             "content": {
               "application/json": {
                 "example": {
-                  "data": {},
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 },
                 "schema": {
@@ -53622,6 +55450,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -53634,7 +55465,7 @@
           "RUM/Issue preset severity rules"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Replaces the entire current rule set with the snapshot's rows: `rule_id`, `priority`, `filters`, `severity`, `status`, and `created_by` are preserved from the snapshot, but `created_at`/`updated_at` are reset to the revert time and `updated_by` is set to the reverting user.\n- Returns `InvalidParameter` (not `ResourceNotFound`) when `version` does not correspond to an existing history snapshot for the application.\n- The revert itself is captured as a new history snapshot before it is applied, so a revert can itself be reverted.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Replaces the entire current rule set with the snapshot's rows: `rule_id`, `priority`, `filters`, `severity`, `status`, and `created_by` are preserved from the snapshot, but `created_at`/`updated_at` are reset to the revert time and `updated_by` is set to the reverting user.\n- Returns `InvalidParameter` (not `ResourceNotFound`) when `version` does not correspond to an existing history snapshot for the application.\n- The revert itself is captured as a new history snapshot before it is applied, so a revert can itself be reverted.\n- Requires edit rights on the application (account owner or admin, the application's creator, or a member of its team); otherwise returns `AccessDenied`. An unknown `application_id` returns `ResourceNotFound`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/rum/issue-preset-severity-rules/rum-issue-preset-severity-rules-history-revert",
           "metadata": {
             "sidebarTitle": "Revert preset severity rules to a history snapshot"
@@ -53744,6 +55575,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -53756,7 +55590,7 @@
           "RUM/Issue preset severity rules"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Rules are returned ordered by `priority` ascending, then `created_at` ascending — the same order they are evaluated in.\n- Only enabled rules are evaluated against incoming errors; the first enabled rule (in priority order) whose filters match an error wins and assigns its `severity`. Errors matching no enabled rule keep their default severity.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Rules are returned ordered by `priority` ascending, then `created_at` ascending — the same order they are evaluated in.\n- Only enabled rules are evaluated against incoming errors; the first enabled rule (in priority order) whose filters match an error wins and assigns its `severity`. Errors matching no enabled rule get a built-in severity: crashes are `Critical`, other errors are scored by environment and message keywords.\n- Severity is decided once, when an error creates a new issue; a rule change affects only errors ingested afterwards (enabled rules are cached for up to 5 seconds) and never re-grades existing issues.\n- Rules of a private application can be read only by callers with edit rights on it (account owner or admin, its creator, or a member of its team); others get `AccessDenied`. An unknown `application_id` returns `ResourceNotFound`.",
           "href": "/en/api-reference/rum/issue-preset-severity-rules/rum-issue-preset-severity-rules-list",
           "metadata": {
             "sidebarTitle": "List preset severity rules"
@@ -53788,7 +55622,6 @@
             "content": {
               "application/json": {
                 "example": {
-                  "data": {},
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 },
                 "schema": {
@@ -53816,6 +55649,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -53828,7 +55664,7 @@
           "RUM/Issue preset severity rules"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- This moves exactly one rule, not a full reordering: `drag_rule_id`'s `priority` is set to `target_rule_id`'s current `priority`, and every rule between the two original positions — the target rule itself included — shifts by one to close the gap.\n- Lower `priority` numbers are evaluated first; moving toward a lower-numbered target moves the rule earlier in evaluation order, and toward a higher-numbered target moves it later.\n- Returns `ResourceNotFound` if either `drag_rule_id` or `target_rule_id` does not exist in the application.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- This moves exactly one rule, not a full reordering: `drag_rule_id`'s `priority` is set to `target_rule_id`'s current `priority`, and every rule between the two original positions — the target rule itself included — shifts by one to close the gap.\n- Lower `priority` numbers are evaluated first; moving toward a lower-numbered target moves the rule earlier in evaluation order, and toward a higher-numbered target moves it later.\n- Returns `ResourceNotFound` if either `drag_rule_id` or `target_rule_id` does not exist in the application.\n- Requires edit rights on the application (account owner or admin, the application's creator, or a member of its team); otherwise returns `AccessDenied`. An unknown `application_id` returns `ResourceNotFound`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/rum/issue-preset-severity-rules/rum-issue-preset-severity-rules-reorder",
           "metadata": {
             "sidebarTitle": "Reorder preset severity rule"
@@ -53861,7 +55697,6 @@
             "content": {
               "application/json": {
                 "example": {
-                  "data": {},
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 },
                 "schema": {
@@ -53889,6 +55724,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -53901,7 +55739,7 @@
           "RUM/Issue preset severity rules"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Only fields present in the request are changed; omitted fields keep their current value.\n- Returns `ResourceNotFound` if `rule_id` does not exist in the application.\n- If `filters` is provided it replaces the entire filter structure and is revalidated against the same allowed key set as `create`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Only fields present in the request are changed; omitted fields keep their current value.\n- Returns `ResourceNotFound` if `rule_id` does not exist in the application.\n- If `filters` is provided it replaces the entire filter structure and is revalidated against the same allowed key set as `create`.\n- Requires edit rights on the application (account owner or admin, the application's creator, or a member of its team); otherwise returns `AccessDenied`. An unknown `application_id` returns `ResourceNotFound`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/rum/issue-preset-severity-rules/rum-issue-preset-severity-rules-update",
           "metadata": {
             "sidebarTitle": "Update preset severity rule"
@@ -53960,6 +55798,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -53972,7 +55813,7 @@
           "RUM/Issues"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- `status` valid values: `for_review`, `reviewed`, `ignored`, `resolved`.\n- `suspected_cause` valid values: `api.failed_request`, `network.error`, `code.exception`, `code.invalid_object_access`, `code.invalid_argument`, `unknown`.\n- Setting `status` to `resolved` also stamps `resolved_at` and `resolved_by` on the issue; moving a resolved issue back to another status clears them.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Only the fields you send are applied; sending a `status` equal to the current one changes nothing.\n- Setting `status` to `resolved` on an unresolved issue stamps `resolved_at` and `resolved_by` and clears `regression`; moving a resolved issue to another status clears `resolved_at` and `resolved_by`.\n- `resolve_mode` is applied only together with `status: resolved`, and defaults to `any` when omitted there; send it with `status: resolved` on an already resolved issue to change only the mode.\n- When the application's alerting is enabled, resolving an issue sends its recovery alert right away.\n- Setting `suspected_cause` marks the cause as user-set (`suspected_cause.source` = `user`, `person_id` = caller), and automatic analysis no longer overwrites it.\n- An unknown `issue_id` returns `InvalidParameter` (\"The specified issue does not exist\").\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/rum/issues/rum-issue-write-update",
           "metadata": {
             "sidebarTitle": "Update issue"
@@ -54056,6 +55897,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -54068,7 +55912,7 @@
           "RUM/Resources"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Returns `ResourceNotFound` when the account has no RUM resource provisioned yet, or when the resource's status is `deleted`/`destroyed`.\n- `no_cache=true` bypasses the short-lived cache of the resource record itself (plan version, quotas, status). The `used_cnt` figures come from a separate hourly cache that this flag does not affect, so they can lag behind live usage either way.\n- The used-count fields reflect the current 30-day billing window (`window_start_time` to `window_end_time`), not lifetime totals.\n- `expired_at` is only populated on on-premises deployments, from the license expiry date; it is omitted entirely for SaaS accounts.\n- For `version=free` accounts, `session_limit_reached` is `true` once usage exceeds the combined free quota across all applications (per-app free quota × application count); it stays `false` while the account has no applications yet.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Returns `ResourceNotFound` when the account has no RUM resource provisioned yet, or when the resource's status is `deleted`/`destroyed`.\n- `no_cache=true` bypasses the short-lived cache of the resource record itself (plan version, quotas, status). The `used_cnt` figures come from a separate hourly cache that this flag does not affect, so they can lag behind live usage either way.\n- The used-count fields reflect the current 30-day billing window (`window_start_time` to `window_end_time`), not lifetime totals.\n- A negative `free_cnt` means the quota is unlimited.\n- `expired_at` is only populated on on-premises deployments, from the license expiry date; it is omitted entirely for SaaS accounts.\n- For `version=free` accounts, `session_limit_reached` becomes `true` once investigate or replay usage reaches the per-application free quota × the number of applications (measure sessions are not counted); it stays `false` while the account has no applications.",
           "href": "/en/api-reference/rum/resources/rum-resource-read-info",
           "metadata": {
             "sidebarTitle": "Get RUM resource info"
@@ -54115,8 +55959,6 @@
                     },
                     "views": [
                       {
-                        "container_source": "",
-                        "container_view_id": "",
                         "end": 1752480600000,
                         "is_active": false,
                         "loading_type": "initial_load",
@@ -54156,6 +55998,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -54168,7 +56013,7 @@
           "RUM/Session replay"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Returns `InvalidParameter` if the session does not exist, or if it has no replay data recorded (`session_has_replay` is false).\n- Returns `InvalidParameter` if no views are found within the session's time window.\n- Pass `ts` to disambiguate when a `session_id` has been reused across different time windows.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Returns `InvalidParameter` if the session does not exist, or if it has no replay data recorded (`session_has_replay` is false).\n- Returns `InvalidParameter` if no view with replay data is found between the session start and 4 hours after its recorded end.\n- `ts` must equal the session's start time exactly (Unix milliseconds); any other value makes the session lookup miss and returns `InvalidParameter`.\n- All timestamps are client times; no clock-skew correction is applied (`server_time_delta` is always `0`).",
           "href": "/en/api-reference/rum/session-replay/rum-session-replay-read-metadata",
           "metadata": {
             "sidebarTitle": "Get session replay metadata"
@@ -54184,7 +56029,7 @@
           "content": {
             "application/json": {
               "example": {
-                "limit": 20,
+                "limit": 2,
                 "session_id": "0a4a2e64-8a4f-4b9a-9c1e-3a2f9e6d7c81",
                 "url_mode": true
               },
@@ -54202,8 +56047,8 @@
                 "example": {
                   "data": {
                     "items": [
-                      "https://rum-replay.flashcat.cloud/short-term/2451002751131/0a4a2e64-8a4f-4b9a-9c1e-3a2f9e6d7c81/segments/1752480001234?X-Amz-Signature=example",
-                      "https://rum-replay.flashcat.cloud/short-term/2451002751131/0a4a2e64-8a4f-4b9a-9c1e-3a2f9e6d7c81/segments/1752480032456?X-Amz-Signature=example"
+                      "https://replay-storage.example.com/short-term/2451002751131/0a4a2e64-8a4f-4b9a-9c1e-3a2f9e6d7c81/segments/1752480001234?X-Amz-Signature=example",
+                      "https://replay-storage.example.com/short-term/2451002751131/0a4a2e64-8a4f-4b9a-9c1e-3a2f9e6d7c81/segments/1752480032456?X-Amz-Signature=example"
                     ],
                     "search_after_ctx": "c2hvcnQtdGVybS8yNDUxMDAyNzUxMTMxLzBhNGEyZTY0LThhNGYtNGI5YS05YzFlLTNhMmY5ZTZkN2M4MS9zZWdtZW50cy8xNzUyNDgwMDMyNDU2"
                   },
@@ -54248,6 +56093,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -54260,7 +56108,7 @@
           "RUM/Session replay"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- When `url_mode` is `false` (default), the response streams `application/x-ndjson` — one decompressed replay segment JSON object per line — and is **not** wrapped in the standard envelope. The pagination cursor for the next call is returned in the `X-Search-After-Ctx` response header instead of a body field.\n- When `url_mode` is `true`, the response is a normal JSON envelope containing presigned download URLs (valid 1 hour) instead of the raw segment bytes.\n- Pass `ts` to seek to the most recent full-snapshot segment at or before that time, instead of paging from the start of the session.\n- `limit` accepts 1-99; values of 100 or more are rejected.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- When `url_mode` is `false` (default), the response streams `application/x-ndjson` — one decompressed replay segment JSON object per line — and is **not** wrapped in the standard envelope. The pagination cursor for the next call is returned in the `X-Search-After-Ctx` response header instead of a body field. A segment that cannot be read is skipped silently.\n- When `url_mode` is `true`, the response is a normal JSON envelope containing presigned download URLs (valid 1 hour) for the zlib-compressed segment objects.\n- Pass `ts` (without `search_after_ctx`) to start from the last full-snapshot segment at or before that time, searching up to 4 hours back; if none is found, paging starts from the beginning.\n- A cursor is returned whenever a page is full (`limit` segments), so the last page can be empty.\n- `limit` accepts 1-99; values of 100 or more are rejected.",
           "href": "/en/api-reference/rum/session-replay/rum-session-replay-read-segments",
           "metadata": {
             "sidebarTitle": "List session replay segments"
@@ -54270,57 +56118,52 @@
     },
     "/safari/a2a-agent/create": {
       "post": {
-        "description": "Register a new A2A remote agent from its agent-card URL.",
         "operationId": "remote-agent-write-create",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "agent_name": "deploy-bot",
-                "auth_type": "bearer",
-                "card_url": "https://agents.example.com/deploy-bot/card",
-                "environments": [
-                  "env_8s7Hn2kLpQ3xYbVc4Wd2m"
-                ],
-                "instructions": "Inspect deployment pipelines and propose rollbacks when a canary fails health checks.",
-                "streaming": true,
-                "team_id": 0
-              },
-              "schema": {
-                "$ref": "#/components/schemas/A2AAgentCreateRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "Create A2A agent",
+        "description": "Register a new A2A remote agent from its agent-card URL.",
+        "tags": [
+          "AI SRE/A2A agents"
+        ],
+        "security": [
+          {
+            "AppKeyAuth": []
+          }
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Agent Manage** (`ai-sre`) |\n\n## Usage\n\n- `instructions` is required: a Markdown document with optional `summary` frontmatter and a non-empty body, at most 51,200 bytes. The deprecated `description` field is still accepted; if both are sent they must match exactly.\n- `agent_name` must not contain `@` or be `general` / `explore` (reserved by built-in agents), and must be unique within its scope (account-wide or one team); violations return `InvalidParameter`.\n- `card_url` must be an absolute `http`/`https` URL with a host. When an execution environment for the agent is online, the server fetches the agent card through it (a `card_url` with no path gets `/.well-known/agent-card.json` appended) and rejects a card that is not valid JSON or declares no A2A 1.x interface with protocol binding `JSONRPC` or `HTTP+JSON`; an unreachable card, a non-2xx response, or no online environment does not block the call.\n- `auth_type=bearer` sends `auth_config.token` as `Authorization: Bearer <token>`; `auth_type=api_key` sends `auth_config.api_key` in the header named by `auth_config.header`; with `none` or an empty value no shared credential header is sent.\n- Each `environments` entry must be `cloud` or the ID of a BYOC runner that is account-scoped or belongs to one of the caller's teams; duplicates are dropped and an empty string is rejected. Omitted or empty means all environments.\n- Creating into a team (`team_id > 0`) requires the caller to belong to that team; only the account owner or an admin may create at account scope (`team_id=0`).\n- A new agent starts with `status=enabled`.\n- Every call is recorded in the account audit log.\n",
+          "href": "/en/api-reference/ai-sre/a2a-agents/remote-agent-write-create",
+          "metadata": {
+            "sidebarTitle": "Create A2A agent"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "agent_id": "a2a_6mWqZ2pK9nLcR3tY8uVb4D"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/ResponseEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/A2AAgentCreateResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "agent_id": "a2a_6mWqZ2pK9nLcR3tY8uVb4D"
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -54338,68 +56181,78 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/A2AAgentCreateRequest"
+              },
+              "example": {
+                "agent_name": "deploy-bot",
+                "instructions": "Inspect deployment pipelines and propose rollbacks when a canary fails health checks.",
+                "card_url": "https://agents.example.com/deploy-bot/card",
+                "auth_type": "bearer",
+                "auth_config": {
+                  "token": "sk-agent-token-example-9f2c"
+                },
+                "streaming": true,
+                "team_id": 0,
+                "environments": [
+                  "env_8s7Hn2kLpQ3xYbVc4Wd2m"
+                ]
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/a2a-agent/delete": {
+      "post": {
+        "operationId": "remote-agent-write-delete",
+        "summary": "Delete A2A agent",
+        "description": "Soft-delete an A2A agent by ID.",
+        "tags": [
+          "AI SRE/A2A agents"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "Create A2A agent",
-        "tags": [
-          "AI SRE/A2A agents"
-        ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Agent Manage** (`ai-sre`) |\n\n## Usage\n\n- `instructions` is required; a deprecated `description` field is still accepted for legacy clients and, if both are sent, must exactly match `instructions`.\n- `card_url` must be an absolute `http`/`https` URL with a non-empty host (reachability is enforced by the execution environment, not here); `auth_type` accepts only `none`, `api_key`, or `bearer`.\n- `environments` restricts where the agent can run: a list of `cloud` and/or BYOC runner environment IDs; omitted or empty means all environments, and each runner must be visible to the caller.\n- Creating into a team (`team_id > 0`) requires the caller to actually belong to that team; only the account owner/admin may create at account scope (`team_id=0`).\n- Every call is recorded in the account audit log.\n",
-          "href": "/en/api-reference/ai-sre/a2a-agents/remote-agent-write-create",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Agent Manage** (`ai-sre`) |\n\n## Usage\n\n- Soft delete: the agent disappears from list and get immediately, can no longer be dispatched, and its name becomes free again in its scope.\n- Requires edit rights on the agent's current team: an account-scoped agent (`team_id=0`) can be changed only by the account owner or an admin, a team agent only by members of that team (owners and admins included only if they belong to it).\n- Returns `ResourceNotFound` if the agent does not exist or is already deleted.\n- Every call is recorded in the account audit log.\n",
+          "href": "/en/api-reference/ai-sre/a2a-agents/remote-agent-write-delete",
           "metadata": {
-            "sidebarTitle": "Create A2A agent"
+            "sidebarTitle": "Delete A2A agent"
           }
-        }
-      }
-    },
-    "/safari/a2a-agent/delete": {
-      "post": {
-        "description": "Soft-delete an A2A agent by ID.",
-        "operationId": "remote-agent-write-delete",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "agent_id": "a2a_6mWqZ2pK9nLcR3tY8uVb4D"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/A2AAgentIDRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": null,
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/ResponseEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "description": "Always null on success.",
-                          "type": "null"
+                          "type": "null",
+                          "description": "Not returned on success; the body carries only `request_id`."
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -54417,68 +56270,67 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/A2AAgentIDRequest"
+              },
+              "example": {
+                "agent_id": "a2a_6mWqZ2pK9nLcR3tY8uVb4D"
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/a2a-agent/disable": {
+      "post": {
+        "operationId": "remote-agent-write-disable",
+        "summary": "Disable A2A agent",
+        "description": "Disable an enabled A2A agent.",
+        "tags": [
+          "AI SRE/A2A agents"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "Delete A2A agent",
-        "tags": [
-          "AI SRE/A2A agents"
-        ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Agent Manage** (`ai-sre`) |\n\n## Usage\n\n- Delete is a soft delete; the agent stops appearing in list/get and can no longer be dispatched once removed.\n- Requires edit permission (`access.CanEdit`) on the agent's team.\n- Every call is recorded in the account audit log.\n",
-          "href": "/en/api-reference/ai-sre/a2a-agents/remote-agent-write-delete",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Agent Manage** (`ai-sre`) |\n\n## Usage\n\n- Requires edit rights on the agent's current team: an account-scoped agent (`team_id=0`) can be changed only by the account owner or an admin, a team agent only by members of that team (owners and admins included only if they belong to it).\n- Returns `InvalidParameter` if the agent is already disabled.\n- A disabled agent is no longer offered to AI SRE sessions; its configuration is kept.\n- Every call is recorded in the account audit log.\n",
+          "href": "/en/api-reference/ai-sre/a2a-agents/remote-agent-write-disable",
           "metadata": {
-            "sidebarTitle": "Delete A2A agent"
+            "sidebarTitle": "Disable A2A agent"
           }
-        }
-      }
-    },
-    "/safari/a2a-agent/disable": {
-      "post": {
-        "description": "Disable an enabled A2A agent.",
-        "operationId": "remote-agent-write-disable",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "agent_id": "a2a_6mWqZ2pK9nLcR3tY8uVb4D"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/A2AAgentIDRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": null,
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/ResponseEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "description": "Always null on success.",
-                          "type": "null"
+                          "type": "null",
+                          "description": "Not returned on success; the body carries only `request_id`."
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -54496,68 +56348,67 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/A2AAgentIDRequest"
+              },
+              "example": {
+                "agent_id": "a2a_6mWqZ2pK9nLcR3tY8uVb4D"
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/a2a-agent/enable": {
+      "post": {
+        "operationId": "remote-agent-write-enable",
+        "summary": "Enable A2A agent",
+        "description": "Enable a disabled A2A agent.",
+        "tags": [
+          "AI SRE/A2A agents"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "Disable A2A agent",
-        "tags": [
-          "AI SRE/A2A agents"
-        ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Agent Manage** (`ai-sre`) |\n\n## Usage\n\n- Requires edit permission (`access.CanEdit`) on the agent's team.\n- Returns `InvalidParameter` if the agent is already disabled.\n- Every call is recorded in the account audit log.\n",
-          "href": "/en/api-reference/ai-sre/a2a-agents/remote-agent-write-disable",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Agent Manage** (`ai-sre`) |\n\n## Usage\n\n- Requires edit rights on the agent's current team: an account-scoped agent (`team_id=0`) can be changed only by the account owner or an admin, a team agent only by members of that team (owners and admins included only if they belong to it).\n- Returns `InvalidParameter` if the agent is already enabled.\n- Once enabled, the agent is offered to AI SRE sessions again.\n- Every call is recorded in the account audit log.\n",
+          "href": "/en/api-reference/ai-sre/a2a-agents/remote-agent-write-enable",
           "metadata": {
-            "sidebarTitle": "Disable A2A agent"
+            "sidebarTitle": "Enable A2A agent"
           }
-        }
-      }
-    },
-    "/safari/a2a-agent/enable": {
-      "post": {
-        "description": "Enable a disabled A2A agent.",
-        "operationId": "remote-agent-write-enable",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "agent_id": "a2a_6mWqZ2pK9nLcR3tY8uVb4D"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/A2AAgentIDRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": null,
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/ResponseEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "description": "Always null on success.",
-                          "type": "null"
+                          "type": "null",
+                          "description": "Not returned on success; the body carries only `request_id`."
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -54575,92 +56426,90 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/A2AAgentIDRequest"
+              },
+              "example": {
+                "agent_id": "a2a_6mWqZ2pK9nLcR3tY8uVb4D"
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/a2a-agent/get": {
+      "post": {
+        "operationId": "remote-agent-read-get",
+        "summary": "Get A2A agent detail",
+        "description": "Return one A2A agent's configuration by ID, with auth secrets masked.",
+        "tags": [
+          "AI SRE/A2A agents"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "Enable A2A agent",
-        "tags": [
-          "AI SRE/A2A agents"
-        ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Agent Manage** (`ai-sre`) |\n\n## Usage\n\n- Requires edit permission (`access.CanEdit`) on the agent's team, not just visibility into it.\n- Returns `InvalidParameter` if the agent is already enabled.\n- Every call is recorded in the account audit log.\n",
-          "href": "/en/api-reference/ai-sre/a2a-agents/remote-agent-write-enable",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Values of the `api_key`, `token`, and `client_secret` keys in `auth_config`, and of any other key whose value is stored encrypted, are masked: longer than 8 characters shows the first and last 4 characters around `****`, otherwise `****`.\n- `card_resolve_timeout` and `task_timeout` are always `0` today — the API does not yet expose a way to set them.\n- Returns `ResourceNotFound` if the agent does not exist or is deleted.\n",
+          "href": "/en/api-reference/ai-sre/a2a-agents/remote-agent-read-get",
           "metadata": {
-            "sidebarTitle": "Enable A2A agent"
+            "sidebarTitle": "Get A2A agent detail"
           }
-        }
-      }
-    },
-    "/safari/a2a-agent/get": {
-      "post": {
-        "description": "Get one A2A agent by ID.",
-        "operationId": "remote-agent-read-get",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "agent_id": "a2a_6mWqZ2pK9nLcR3tY8uVb4D"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/A2AAgentIDRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "account_id": 10023,
-                    "agent_card_name": "Deploy Bot",
-                    "agent_card_skills": [
-                      "rollback",
-                      "diff"
-                    ],
-                    "agent_id": "a2a_6mWqZ2pK9nLcR3tY8uVb4D",
-                    "agent_name": "deploy-bot",
-                    "auth_mode": "shared",
-                    "auth_type": "bearer",
-                    "can_edit": true,
-                    "card_resolve_timeout": 0,
-                    "card_url": "https://agents.example.com/deploy-bot/card",
-                    "created_at": 1716960000000,
-                    "created_by": 80011,
-                    "environments": [
-                      "env_8s7Hn2kLpQ3xYbVc4Wd2m"
-                    ],
-                    "instructions": "Inspect deployment pipelines and propose rollbacks when a canary fails health checks.",
-                    "status": "enabled",
-                    "streaming": true,
-                    "task_timeout": 0,
-                    "team_id": 0,
-                    "updated_at": 1717046400000
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/ResponseEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/A2AAgentItem"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "agent_id": "a2a_6mWqZ2pK9nLcR3tY8uVb4D",
+                    "account_id": 10023,
+                    "team_id": 0,
+                    "can_edit": true,
+                    "environments": [
+                      "env_8s7Hn2kLpQ3xYbVc4Wd2m"
+                    ],
+                    "agent_name": "deploy-bot",
+                    "instructions": "Inspect deployment pipelines and propose rollbacks when a canary fails health checks.",
+                    "card_url": "https://agents.example.com/deploy-bot/card",
+                    "auth_type": "bearer",
+                    "auth_config": {
+                      "token": "sk-a****9f2c"
+                    },
+                    "streaming": true,
+                    "status": "enabled",
+                    "card_resolve_timeout": 0,
+                    "task_timeout": 0,
+                    "auth_mode": "shared",
+                    "created_by": 80011,
+                    "created_at": 1716960000000,
+                    "updated_at": 1717046400000
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -54668,6 +56517,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -54675,99 +56527,95 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/A2AAgentIDRequest"
+              },
+              "example": {
+                "agent_id": "a2a_6mWqZ2pK9nLcR3tY8uVb4D"
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/a2a-agent/list": {
+      "post": {
+        "operationId": "remote-agent-read-list",
+        "summary": "List A2A agents",
+        "description": "List A2A agents visible to the caller across account and team scopes, with pagination.",
+        "tags": [
+          "AI SRE/A2A agents"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "Get A2A agent detail",
-        "tags": [
-          "AI SRE/A2A agents"
-        ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- `card_resolve_timeout` and `task_timeout` are always `0` today — the API does not yet expose a way to set them.\n",
-          "href": "/en/api-reference/ai-sre/a2a-agents/remote-agent-read-get",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Pagination uses `offset`/`limit` (not `p`/`limit`); `limit` of 0 or less falls back to 20. Results are ordered by creation time, newest first.\n- Visibility follows real team membership for every caller, owner and admins included: account-scoped rows plus rows of teams the caller belongs to; `team_ids` entries outside that set are ignored.\n- `scope=account` returns only account-scoped rows; `scope=team` returns only team rows; `all` (default) returns team rows plus account-scoped rows unless `include_account=false`.\n- `query` performs a case-insensitive substring search across agent name, instructions, card URL, agent ID, and card name.\n- `can_edit` on each row tells whether the caller may update, enable, disable, or delete that agent.\n",
+          "href": "/en/api-reference/ai-sre/a2a-agents/remote-agent-read-list",
           "metadata": {
-            "sidebarTitle": "Get A2A agent detail"
+            "sidebarTitle": "List A2A agents"
           }
-        }
-      }
-    },
-    "/safari/a2a-agent/list": {
-      "post": {
-        "description": "List A2A agents visible to the caller across account and team scopes, with pagination.",
-        "operationId": "remote-agent-read-list",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "include_account": true,
-                "limit": 20,
-                "offset": 0
-              },
-              "schema": {
-                "$ref": "#/components/schemas/A2AAgentListRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ResponseEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/A2AAgentListResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "items": [
                       {
-                        "account_id": 10023,
-                        "agent_card_name": "Deploy Bot",
-                        "agent_card_skills": [
-                          "rollback",
-                          "diff"
-                        ],
                         "agent_id": "a2a_6mWqZ2pK9nLcR3tY8uVb4D",
-                        "agent_name": "deploy-bot",
-                        "auth_mode": "shared",
-                        "auth_type": "bearer",
+                        "account_id": 10023,
+                        "team_id": 0,
                         "can_edit": true,
-                        "card_resolve_timeout": 0,
-                        "card_url": "https://agents.example.com/deploy-bot/card",
-                        "created_at": 1716960000000,
-                        "created_by": 80011,
                         "environments": [
                           "env_8s7Hn2kLpQ3xYbVc4Wd2m"
                         ],
+                        "agent_name": "deploy-bot",
                         "instructions": "Inspect deployment pipelines and propose rollbacks when a canary fails health checks.",
-                        "status": "enabled",
+                        "card_url": "https://agents.example.com/deploy-bot/card",
+                        "auth_type": "bearer",
+                        "auth_config": {
+                          "token": "sk-a****9f2c"
+                        },
                         "streaming": true,
+                        "status": "enabled",
+                        "card_resolve_timeout": 0,
                         "task_timeout": 0,
-                        "team_id": 0,
+                        "auth_mode": "shared",
+                        "created_by": 80011,
+                        "created_at": 1716960000000,
                         "updated_at": 1717046400000
                       }
                     ],
                     "total": 1
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/ResponseEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/A2AAgentListResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -54775,6 +56623,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -54782,69 +56633,69 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/A2AAgentListRequest"
+              },
+              "example": {
+                "offset": 0,
+                "limit": 20,
+                "include_account": true
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/a2a-agent/update": {
+      "post": {
+        "operationId": "remote-agent-write-update",
+        "summary": "Update A2A agent",
+        "description": "Apply a partial update to an A2A agent. Omit a field to leave it unchanged.",
+        "tags": [
+          "AI SRE/A2A agents"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "List A2A agents",
-        "tags": [
-          "AI SRE/A2A agents"
-        ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Pagination uses `offset`/`limit` (not `p`/`limit`).\n- `scope=account` restricts to account-scoped agents; `scope=team` restricts to the caller's visible teams; the default `all` combines both, subject to `include_account`.\n- `query` performs a case-insensitive substring search across agent name, instructions, card URL, agent ID, and the resolved card name.\n- `card_resolve_timeout` and `task_timeout` are always `0` today — the API does not yet expose a way to set them.\n",
-          "href": "/en/api-reference/ai-sre/a2a-agents/remote-agent-read-list",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Agent Manage** (`ai-sre`) |\n\n## Usage\n\n- Requires edit rights on the agent's current team: an account-scoped agent (`team_id=0`) can be changed only by the account owner or an admin, a team agent only by members of that team (owners and admins included only if they belong to it).\n- Moving to another team (`team_id > 0`) requires membership in the destination team; moving to account scope (`team_id=0`) requires the account owner or an admin. If `environments` is not sent with a team change, the current runner entries must still be selectable by the caller or the update is rejected.\n- `auth_config` replaces the whole map: keys left out are removed. For `api_key`, `token`, and `client_secret`, sending back the masked value from get keeps the stored secret, while an empty string clears it.\n- When `auth_mode` is sent, `secret_schema` is overwritten with the value sent alongside it (empty if omitted). `oauth_metadata` is cleared when `auth_mode` or `card_url` actually changes, unless a non-empty `oauth_metadata` is sent; an empty `oauth_metadata` alone leaves the stored value.\n- Changing `card_url` re-runs the agent card compatibility check described on create; changing `agent_name` re-applies its naming rules.\n- Every call is recorded in the account audit log.\n",
+          "href": "/en/api-reference/ai-sre/a2a-agents/remote-agent-write-update",
           "metadata": {
-            "sidebarTitle": "List A2A agents"
+            "sidebarTitle": "Update A2A agent"
           }
-        }
-      }
-    },
-    "/safari/a2a-agent/update": {
-      "post": {
-        "description": "Apply a partial update to an A2A agent. Omit a field to leave it unchanged.",
-        "operationId": "remote-agent-write-update",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "agent_id": "a2a_6mWqZ2pK9nLcR3tY8uVb4D",
-                "instructions": "Inspect deployment pipelines and propose rollbacks."
-              },
-              "schema": {
-                "$ref": "#/components/schemas/A2AAgentUpdateRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": null,
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/ResponseEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "description": "Always null on success.",
-                          "type": "null"
+                          "type": "null",
+                          "description": "Not returned on success; the body carries only `request_id`."
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -54862,68 +56713,81 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/A2AAgentUpdateRequest"
+              },
+              "example": {
+                "agent_id": "a2a_6mWqZ2pK9nLcR3tY8uVb4D",
+                "instructions": "Inspect deployment pipelines and propose rollbacks."
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/artifact/gallery/delete": {
+      "post": {
+        "operationId": "artifact-write-delete",
+        "summary": "Remove artifact from gallery",
+        "description": "Detach an artifact from the gallery; the source file stays with its session.",
+        "tags": [
+          "AI SRE/Artifacts"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "Update A2A agent",
-        "tags": [
-          "AI SRE/A2A agents"
-        ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Agent Manage** (`ai-sre`) |\n\n## Usage\n\n- Requires edit permission (`access.CanEdit`) on the agent's *current* team before any field may change.\n- Reassigning `team_id` requires rights on the destination team; if the team changes without also sending a new environment binding, the existing runner binding must remain selectable by the caller or the update is rejected.\n- Changing `auth_mode` always rewrites `secret_schema` together with it; omitting `oauth_metadata` alongside a new `auth_mode` clears it to empty.\n- Sending back a masked or empty value for a sensitive `auth_config` key (`api_key`, `token`, `client_secret`) keeps the stored secret instead of overwriting it.\n- Every call is recorded in the account audit log.\n",
-          "href": "/en/api-reference/ai-sre/a2a-agents/remote-agent-write-update",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- This removes the artifact from the gallery; it does not delete the file. The file stays with its source session and can be published again, which restores the same `artifact_id`.\n- Requires `can_edit` on the artifact (the creator, any member of its owning team, or anyone who can manage its source session); otherwise the call fails with `AccessDenied`.\n- If public sharing was on, the public objects are deleted in the same operation and the link stops resolving. All members' pins on the artifact are removed.\n- If the source session has been deleted, the file itself is permanently removed 30 days after the artifact is removed from the gallery.\n- Every call is recorded in the account audit log.\n",
+          "href": "/en/api-reference/ai-sre/artifacts/artifact-write-delete",
           "metadata": {
-            "sidebarTitle": "Update A2A agent"
+            "sidebarTitle": "Remove artifact from gallery"
           }
-        }
-      }
-    },
-    "/safari/artifact/gallery/delete": {
-      "post": {
-        "description": "Detach an artifact from the gallery; the source file stays with its session.",
-        "operationId": "artifact-write-delete",
+        },
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {
-                "artifact_id": "art_CWQzDU2PXSRJvKDhQbuMKu"
-              },
               "schema": {
                 "$ref": "#/components/schemas/ArtifactIdRequest"
+              },
+              "example": {
+                "artifact_id": "art_CWQzDU2PXSRJvKDhQbuMKu"
               }
             }
-          },
-          "required": true
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": null,
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/ResponseEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "description": "Always null on success.",
-                          "type": "null"
+                          "type": "null",
+                          "description": "Not returned on success; the body carries only `request_id`."
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -54931,86 +56795,89 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
           "500": {
             "$ref": "#/components/responses/ServerError"
           }
-        },
+        }
+      }
+    },
+    "/safari/artifact/gallery/file-state": {
+      "post": {
+        "operationId": "artifact-read-get-file-state",
+        "summary": "Get file publish state",
+        "description": "Check which presented files already have a live published artifact.",
+        "tags": [
+          "AI SRE/Artifacts"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "Remove artifact from gallery",
-        "tags": [
-          "AI SRE/Artifacts"
-        ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- This is a detach, not a byte delete: the underlying presented file stays with the source session and can be published again.\n- If public sharing was enabled, the public objects are destroyed in the same operation and the link stops resolving.\n- Every call is recorded in the account audit log.\n",
-          "href": "/en/api-reference/ai-sre/artifacts/artifact-write-delete",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Use it to find out whether files produced in a session are already in the gallery, e.g. before calling `/safari/artifact/gallery/publish-from-file`.\n- Matching is by the file's session and workspace path, not by the exact `file_id`: an older version of a republished file still reports the live artifact.\n- Files with no live artifact, and IDs that do not exist in the account, are simply absent from `items`; match results by the echoed `file_id`.\n",
+          "href": "/en/api-reference/ai-sre/artifacts/artifact-read-get-file-state",
           "metadata": {
-            "sidebarTitle": "Remove artifact from gallery"
+            "sidebarTitle": "Get file publish state"
           }
-        }
-      }
-    },
-    "/safari/artifact/gallery/file-state": {
-      "post": {
-        "description": "Check which presented files already have a live published artifact.",
-        "operationId": "artifact-read-get-file-state",
+        },
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ArtifactFileStateRequest"
+              },
               "example": {
                 "file_ids": [
                   "pf_SdhEA5fbZJGnHzwrNJMMSB",
                   "pf_9kLm2nQpRsTuVwXyZaBcDe"
                 ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ArtifactFileStateRequest"
               }
             }
-          },
-          "required": true
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "items": [
-                      {
-                        "artifact_id": "art_VnfrWic8UbB9q3EfYR4Gmg",
-                        "file_id": "pf_SdhEA5fbZJGnHzwrNJMMSB",
-                        "gallery_path": "/ai-sre/artifacts/art_VnfrWic8UbB9q3EfYR4Gmg",
-                        "title": "SK 海力士 2026 Q2 财报深度分析"
-                      }
-                    ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/ResponseEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/ArtifactFileStateResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "items": [
+                      {
+                        "file_id": "pf_SdhEA5fbZJGnHzwrNJMMSB",
+                        "artifact_id": "art_VnfrWic8UbB9q3EfYR4Gmg",
+                        "title": "Checkout API latency postmortem",
+                        "gallery_path": "/ai-sre/artifacts/art_VnfrWic8UbB9q3EfYR4Gmg"
+                      }
+                    ]
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -55018,96 +56885,100 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
           "500": {
             "$ref": "#/components/responses/ServerError"
           }
-        },
+        }
+      }
+    },
+    "/safari/artifact/gallery/get": {
+      "post": {
+        "operationId": "artifact-read-get",
+        "summary": "Get artifact detail",
+        "description": "Get one published artifact by ID, including its source file, owner and public-share state.",
+        "tags": [
+          "AI SRE/Artifacts"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "Get file publish state",
-        "tags": [
-          "AI SRE/Artifacts"
-        ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- At most 50 `file_ids` per call; duplicates and empty strings are ignored.\n- Files with no live published artifact are simply absent from `items` — match results by the echoed `file_id`.\n",
-          "href": "/en/api-reference/ai-sre/artifacts/artifact-read-get-file-state",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Any member of the account can read any artifact by ID, including personal artifacts of other members; `is_mine` and `can_edit` are computed for the `app_key` owner.\n- An unknown or removed artifact fails with `ResourceNotFound`.\n- When `share_enabled` is true and `file_id` differs from `share_file_id`, the public snapshot is stale; refresh it with `/safari/artifact/gallery/share/sync`.\n",
+          "href": "/en/api-reference/ai-sre/artifacts/artifact-read-get",
           "metadata": {
-            "sidebarTitle": "Get file publish state"
+            "sidebarTitle": "Get artifact detail"
           }
-        }
-      }
-    },
-    "/safari/artifact/gallery/get": {
-      "post": {
-        "description": "Get a single published artifact by ID.",
-        "operationId": "artifact-read-get",
+        },
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {
-                "artifact_id": "art_VnfrWic8UbB9q3EfYR4Gmg"
-              },
               "schema": {
                 "$ref": "#/components/schemas/ArtifactIdRequest"
+              },
+              "example": {
+                "artifact_id": "art_VnfrWic8UbB9q3EfYR4Gmg"
               }
             }
-          },
-          "required": true
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "artifact_id": "art_VnfrWic8UbB9q3EfYR4Gmg",
-                    "can_edit": true,
-                    "content_type": "text/html",
-                    "created_at": 1785293373899,
-                    "creator_name": "yushuangyu",
-                    "file_id": "pf_SdhEA5fbZJGnHzwrNJMMSB",
-                    "is_mine": true,
-                    "name": "sk-hynix-q2-2026-report.html",
-                    "person_id": 2476444212131,
-                    "public_url": "https://console.flashcat.cloud/share/artifact/art_VnfrWic8UbB9q3EfYR4Gmg",
-                    "session_id": "sess_VCbVPZrq9YoyBu8sNCmqUy",
-                    "session_title": "分析海力士财报并发布报告",
-                    "share_enabled": true,
-                    "share_file_id": "pf_SdhEA5fbZJGnHzwrNJMMSB",
-                    "shared_at": 1785747928665,
-                    "shared_by": 3790925372131,
-                    "size": 18996,
-                    "team_id": 2477033058131,
-                    "team_name": "研发团队",
-                    "title": "SK 海力士 2026 Q2 财报深度分析",
-                    "updated_at": 1785747910219
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/ResponseEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/PublishedArtifactItem"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "artifact_id": "art_VnfrWic8UbB9q3EfYR4Gmg",
+                    "title": "Checkout API latency postmortem",
+                    "team_id": 4012,
+                    "team_name": "SRE",
+                    "person_id": 2476001,
+                    "creator_name": "Alice",
+                    "is_mine": true,
+                    "can_edit": true,
+                    "session_id": "sess_VCbVPZrq9YoyBu8sNCmqUy",
+                    "session_title": "Investigate checkout API latency spike",
+                    "file_id": "pf_SdhEA5fbZJGnHzwrNJMMSB",
+                    "name": "checkout-latency-postmortem.html",
+                    "size": 18996,
+                    "content_type": "text/html",
+                    "created_at": 1785293373899,
+                    "updated_at": 1785747910219,
+                    "pinned_at": 1785750000000,
+                    "share_enabled": true,
+                    "public_url": "https://console.flashcat.cloud/share/artifact/art_VnfrWic8UbB9q3EfYR4Gmg",
+                    "shared_by": 2476001,
+                    "shared_at": 1785747928665,
+                    "share_file_id": "pf_SdhEA5fbZJGnHzwrNJMMSB"
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -55115,121 +56986,125 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
           "500": {
             "$ref": "#/components/responses/ServerError"
           }
-        },
+        }
+      }
+    },
+    "/safari/artifact/gallery/list": {
+      "post": {
+        "operationId": "artifact-read-list",
+        "summary": "List artifacts",
+        "description": "List published artifacts visible to the caller, with pagination and title search.",
+        "tags": [
+          "AI SRE/Artifacts"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "Get artifact detail",
-        "tags": [
-          "AI SRE/Artifacts"
-        ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Visibility is account-wide: any valid `app_key` can read any artifact in the account. `is_mine` and `can_edit` are computed relative to the key owner.\n- When `share_enabled` is true and `file_id` differs from `share_file_id`, the public snapshot is stale — refresh it with `/safari/artifact/gallery/share/sync`.\n",
-          "href": "/en/api-reference/ai-sre/artifacts/artifact-read-get",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- `scope` selects `all` (default: the caller's own personal artifacts plus artifacts of every team the caller belongs to), `personal` (only the caller's own personal artifacts), or `team` (only artifacts owned by the caller's teams). An unknown value is treated as `all`.\n- Visibility uses the `app_key` owner's identity and real team membership; account owners and admins see no extra artifacts here. To open any artifact in the account by ID, use `/safari/artifact/gallery/get`.\n- The caller's pinned artifacts always come first; the rest are sorted by `updated_at` descending unless `orderby`/`asc` say otherwise.\n",
+          "href": "/en/api-reference/ai-sre/artifacts/artifact-read-list",
           "metadata": {
-            "sidebarTitle": "Get artifact detail"
+            "sidebarTitle": "List artifacts"
           }
-        }
-      }
-    },
-    "/safari/artifact/gallery/list": {
-      "post": {
-        "description": "List published artifacts visible to the caller, with pagination and title search.",
-        "operationId": "artifact-read-list",
+        },
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {
-                "limit": 20,
-                "page": 1,
-                "scope": "all"
-              },
               "schema": {
                 "$ref": "#/components/schemas/ArtifactListRequest"
+              },
+              "example": {
+                "scope": "all",
+                "page": 1,
+                "limit": 20
               }
             }
-          },
-          "required": true
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ResponseEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/ArtifactListResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "items": [
                       {
                         "artifact_id": "art_VnfrWic8UbB9q3EfYR4Gmg",
+                        "title": "Checkout API latency postmortem",
+                        "team_id": 4012,
+                        "team_name": "SRE",
+                        "person_id": 2476001,
+                        "creator_name": "Alice",
+                        "is_mine": true,
                         "can_edit": true,
+                        "session_id": "sess_VCbVPZrq9YoyBu8sNCmqUy",
+                        "session_title": "Investigate checkout API latency spike",
+                        "file_id": "pf_SdhEA5fbZJGnHzwrNJMMSB",
+                        "name": "checkout-latency-postmortem.html",
+                        "size": 18996,
                         "content_type": "text/html",
                         "created_at": 1785293373899,
-                        "creator_name": "yushuangyu",
-                        "file_id": "pf_SdhEA5fbZJGnHzwrNJMMSB",
-                        "is_mine": true,
-                        "name": "sk-hynix-q2-2026-report.html",
-                        "person_id": 2476444212131,
-                        "public_url": "https://console.flashcat.cloud/share/artifact/art_VnfrWic8UbB9q3EfYR4Gmg",
-                        "session_id": "sess_VCbVPZrq9YoyBu8sNCmqUy",
-                        "session_title": "分析海力士财报并发布报告",
+                        "updated_at": 1785747910219,
+                        "pinned_at": 1785750000000,
                         "share_enabled": true,
-                        "share_file_id": "pf_SdhEA5fbZJGnHzwrNJMMSB",
+                        "public_url": "https://console.flashcat.cloud/share/artifact/art_VnfrWic8UbB9q3EfYR4Gmg",
+                        "shared_by": 2476001,
                         "shared_at": 1785747928665,
-                        "shared_by": 3790925372131,
-                        "size": 18996,
-                        "team_id": 2477033058131,
-                        "team_name": "研发团队",
-                        "title": "SK 海力士 2026 Q2 财报深度分析",
-                        "updated_at": 1785747910219
+                        "share_file_id": "pf_SdhEA5fbZJGnHzwrNJMMSB"
                       },
                       {
                         "artifact_id": "art_CWQzDU2PXSRJvKDhQbuMKu",
-                        "can_edit": true,
-                        "content_type": "application/pdf",
-                        "created_at": 1785229432881,
-                        "creator_name": "牛伟利",
-                        "file_id": "pf_Jnc4E5YBcWLGzunB4ntP9s",
+                        "title": "Weekly alert noise report",
+                        "team_id": 4012,
+                        "team_name": "SRE",
+                        "person_id": 2476002,
+                        "creator_name": "Bob",
                         "is_mine": false,
-                        "name": "rum_recommendation.pdf",
-                        "person_id": 3790925372131,
+                        "can_edit": true,
                         "session_id": "sess_QXUC9C2PYWP5EE7vETR3UD",
-                        "session_title": "生成 RUM 文档多格式",
+                        "session_title": "Summarize last week's alert noise",
+                        "file_id": "pf_Jnc4E5YBcWLGzunB4ntP9s",
+                        "name": "alert-noise-weekly.pdf",
                         "size": 137107,
-                        "team_id": 2477033058131,
-                        "team_name": "研发团队",
-                        "title": "rum_recommendation",
+                        "content_type": "application/pdf",
+                        "created_at": 1785229432881,
                         "updated_at": 1785741344822
                       }
                     ],
                     "total": 17
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/ResponseEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/ArtifactListResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -55237,79 +57112,82 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
           "500": {
             "$ref": "#/components/responses/ServerError"
           }
-        },
+        }
+      }
+    },
+    "/safari/artifact/gallery/publish-from-file": {
+      "post": {
+        "operationId": "artifact-write-publish",
+        "summary": "Publish file as artifact",
+        "description": "Publish a session-produced file to the artifact gallery.",
+        "tags": [
+          "AI SRE/Artifacts"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "List artifacts",
-        "tags": [
-          "AI SRE/Artifacts"
-        ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- `scope` selects `all` (default — the caller's own personal artifacts plus every team the caller belongs to), `personal` (only the caller's own), or `team` (only team-owned artifacts of the caller's teams).\n- `team_ids` narrows further to specific teams, intersected with the caller's visibility — teams the caller does not belong to return nothing.\n- Default sort is `updated_at` descending; set `orderby` to `created_at` to change the field and `asc: true` to flip direction.\n- For an `app_key` call, visibility is evaluated against the key owner's identity — the list shows that member's personal artifacts and their teams' artifacts.\n",
-          "href": "/en/api-reference/ai-sre/artifacts/artifact-read-list",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Any account member who can see the file may publish it. Republishing a file whose path already has a live artifact replaces that artifact and requires `can_edit` on it.\n- Allowed file types: HTML/Markdown, images, PDF, text/data/code files, and zip/tar archives, matched by extension. Other types, files over 16 MiB, and files no longer retrievable (runner offline or file expired) fail with `InvalidParameter`.\n- Publishing is an upsert keyed by the source session and workspace path: republishing replaces the title and bytes under a fresh `file_id` and keeps the `artifact_id`, which makes an existing public snapshot stale until synced. Republishing a removed artifact restores it with the same `artifact_id`, with sharing off.\n- A new artifact takes its creator and personal/team scope from the source session (its owner and team); move it afterwards with `/safari/artifact/gallery/update` if needed.\n- Every call is recorded in the account audit log.\n",
+          "href": "/en/api-reference/ai-sre/artifacts/artifact-write-publish",
           "metadata": {
-            "sidebarTitle": "List artifacts"
+            "sidebarTitle": "Publish file as artifact"
           }
-        }
-      }
-    },
-    "/safari/artifact/gallery/publish-from-file": {
-      "post": {
-        "description": "Publish a session-produced file to the artifact gallery.",
-        "operationId": "artifact-write-publish",
+        },
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {
-                "file_id": "pf_SdhEA5fbZJGnHzwrNJMMSB",
-                "title": "SK 海力士 2026 Q2 财报深度分析"
-              },
               "schema": {
                 "$ref": "#/components/schemas/ArtifactPublishFromFileRequest"
+              },
+              "example": {
+                "file_id": "pf_SdhEA5fbZJGnHzwrNJMMSB",
+                "title": "Checkout API latency postmortem"
               }
             }
-          },
-          "required": true
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "artifact_id": "art_VnfrWic8UbB9q3EfYR4Gmg",
-                    "gallery_path": "/ai-sre/artifacts/art_VnfrWic8UbB9q3EfYR4Gmg",
-                    "title": "SK 海力士 2026 Q2 财报深度分析"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/ResponseEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/ArtifactPublishResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "artifact_id": "art_VnfrWic8UbB9q3EfYR4Gmg",
+                    "title": "Checkout API latency postmortem",
+                    "gallery_path": "/ai-sre/artifacts/art_VnfrWic8UbB9q3EfYR4Gmg"
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -55317,80 +57195,83 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
           "500": {
             "$ref": "#/components/responses/ServerError"
           }
-        },
+        }
+      }
+    },
+    "/safari/artifact/gallery/share/enable": {
+      "post": {
+        "operationId": "artifact-write-share-enable",
+        "summary": "Enable public sharing",
+        "description": "Turn on anonymous public sharing for an artifact and return its public link.",
+        "tags": [
+          "AI SRE/Artifacts"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "Publish file as artifact",
-        "tags": [
-          "AI SRE/Artifacts"
-        ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Allowed file types: HTML/Markdown, images, PDF, text/data/code files, and zip/tar archives, matched by extension. Files over 16 MiB are rejected.\n- Publishing is an upsert keyed by the source session and workspace path — republishing the same file replaces the artifact's bytes under a fresh `file_id`, which makes an existing public snapshot stale until synced.\n- The artifact inherits personal/team scope from the source session; move it afterwards with `/safari/artifact/gallery/update` if needed.\n- Every call is recorded in the account audit log.\n",
-          "href": "/en/api-reference/ai-sre/artifacts/artifact-write-publish",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- The public link is anonymous: anyone with it can view the content, and the link may be forwarded. The content is copied to public CDN objects, so viewing the link does not go through this API.\n- Requires `can_edit` on the artifact (the creator, any member of its owning team, or anyone who can manage its source session); otherwise the call fails with `AccessDenied`.\n- Idempotent: enabling an already-shared artifact returns the existing state unchanged, and re-enabling after a revoke brings the same link back, because the link is keyed by artifact ID.\n- Artifacts over 16 MiB cannot be shared; the call fails with `InvalidParameter`. On deployments where public sharing is not configured, the call fails with `InternalError`.\n- Sharing is a snapshot: later republishes do not update the public content until you call `/safari/artifact/gallery/share/sync`.\n- Every call is recorded in the account audit log.\n",
+          "href": "/en/api-reference/ai-sre/artifacts/artifact-write-share-enable",
           "metadata": {
-            "sidebarTitle": "Publish file as artifact"
+            "sidebarTitle": "Enable public sharing"
           }
-        }
-      }
-    },
-    "/safari/artifact/gallery/share/enable": {
-      "post": {
-        "description": "Turn on anonymous public sharing for an artifact and return its public link.",
-        "operationId": "artifact-write-share-enable",
+        },
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {
-                "artifact_id": "art_VnfrWic8UbB9q3EfYR4Gmg"
-              },
               "schema": {
                 "$ref": "#/components/schemas/ArtifactIdRequest"
+              },
+              "example": {
+                "artifact_id": "art_VnfrWic8UbB9q3EfYR4Gmg"
               }
             }
-          },
-          "required": true
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "artifact_id": "art_VnfrWic8UbB9q3EfYR4Gmg",
-                    "public_url": "https://console.flashcat.cloud/share/artifact/art_VnfrWic8UbB9q3EfYR4Gmg",
-                    "share_enabled": true,
-                    "shared_at": 1785747928665,
-                    "shared_by": 2476444212131
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/ResponseEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/ArtifactShareState"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "artifact_id": "art_VnfrWic8UbB9q3EfYR4Gmg",
+                    "share_enabled": true,
+                    "public_url": "https://console.flashcat.cloud/share/artifact/art_VnfrWic8UbB9q3EfYR4Gmg",
+                    "shared_by": 2476001,
+                    "shared_at": 1785747928665
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -55398,75 +57279,77 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
           "500": {
             "$ref": "#/components/responses/ServerError"
           }
-        },
+        }
+      }
+    },
+    "/safari/artifact/gallery/share/revoke": {
+      "post": {
+        "operationId": "artifact-write-share-revoke",
+        "summary": "Revoke public sharing",
+        "description": "Turn off public sharing; the link stops resolving immediately.",
+        "tags": [
+          "AI SRE/Artifacts"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "Enable public sharing",
-        "tags": [
-          "AI SRE/Artifacts"
-        ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- The public link is anonymous — anyone with it can view the content, and the link may be forwarded. Content is copied to public CDN objects; the gallery API is not involved when the link is viewed.\n- Idempotent: enabling an already-shared artifact returns the existing link unchanged, and re-enabling after a revoke brings the same link back — the link is keyed by artifact ID.\n- Artifacts over 16 MiB cannot be shared; the call fails with `InvalidParameter`.\n- Sharing is a snapshot: later republishes do not update the public content until you call `/safari/artifact/gallery/share/sync`.\n- Every call is recorded in the account audit log.\n",
-          "href": "/en/api-reference/ai-sre/artifacts/artifact-write-share-enable",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- The public CDN objects are deleted and the link stops resolving. Succeeds without changes when the artifact is not shared.\n- Requires `can_edit` on the artifact (the creator, any member of its owning team, or anyone who can manage its source session); otherwise the call fails with `AccessDenied`.\n- Re-enabling later returns the same `public_url`: the link is keyed by artifact ID, so revoking does not rotate the link.\n- Every call is recorded in the account audit log.\n",
+          "href": "/en/api-reference/ai-sre/artifacts/artifact-write-share-revoke",
           "metadata": {
-            "sidebarTitle": "Enable public sharing"
+            "sidebarTitle": "Revoke public sharing"
           }
-        }
-      }
-    },
-    "/safari/artifact/gallery/share/revoke": {
-      "post": {
-        "description": "Turn off public sharing; the link stops resolving immediately.",
-        "operationId": "artifact-write-share-revoke",
+        },
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {
-                "artifact_id": "art_VnfrWic8UbB9q3EfYR4Gmg"
-              },
               "schema": {
                 "$ref": "#/components/schemas/ArtifactIdRequest"
+              },
+              "example": {
+                "artifact_id": "art_VnfrWic8UbB9q3EfYR4Gmg"
               }
             }
-          },
-          "required": true
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": null,
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/ResponseEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "description": "Always null on success.",
-                          "type": "null"
+                          "type": "null",
+                          "description": "Not returned on success; the body carries only `request_id`."
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -55474,80 +57357,83 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
           "500": {
             "$ref": "#/components/responses/ServerError"
           }
-        },
+        }
+      }
+    },
+    "/safari/artifact/gallery/share/sync": {
+      "post": {
+        "operationId": "artifact-write-share-sync",
+        "summary": "Update shared snapshot",
+        "description": "Refresh the public snapshot of a shared artifact with its latest content.",
+        "tags": [
+          "AI SRE/Artifacts"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "Revoke public sharing",
-        "tags": [
-          "AI SRE/Artifacts"
-        ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- The public CDN objects are deleted, so the link stops resolving; this is a no-op when the artifact is not shared.\n- Re-enabling later returns the same `public_url` — the link is keyed by artifact ID, so revoke is not a way to rotate the link.\n- Every call is recorded in the account audit log.\n",
-          "href": "/en/api-reference/ai-sre/artifacts/artifact-write-share-revoke",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Fails with `InvalidParameter` when sharing is not enabled; enable it first. On deployments where public sharing is not configured, the call fails with `InternalError`.\n- Requires `can_edit` on the artifact (the creator, any member of its owning team, or anyone who can manage its source session); otherwise the call fails with `AccessDenied`.\n- The link never changes; only the snapshot content and `shared_at` are refreshed, and `shared_by` keeps the member who enabled sharing.\n- Check `share_file_id != file_id` on the artifact detail to detect a stale snapshot before syncing.\n- Every call is recorded in the account audit log.\n",
+          "href": "/en/api-reference/ai-sre/artifacts/artifact-write-share-sync",
           "metadata": {
-            "sidebarTitle": "Revoke public sharing"
+            "sidebarTitle": "Update shared snapshot"
           }
-        }
-      }
-    },
-    "/safari/artifact/gallery/share/sync": {
-      "post": {
-        "description": "Refresh the public snapshot of a shared artifact with its latest content.",
-        "operationId": "artifact-write-share-sync",
+        },
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {
-                "artifact_id": "art_VnfrWic8UbB9q3EfYR4Gmg"
-              },
               "schema": {
                 "$ref": "#/components/schemas/ArtifactIdRequest"
+              },
+              "example": {
+                "artifact_id": "art_VnfrWic8UbB9q3EfYR4Gmg"
               }
             }
-          },
-          "required": true
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "artifact_id": "art_VnfrWic8UbB9q3EfYR4Gmg",
-                    "public_url": "https://console.flashcat.cloud/share/artifact/art_VnfrWic8UbB9q3EfYR4Gmg",
-                    "share_enabled": true,
-                    "shared_at": 1785829900000,
-                    "shared_by": 2476444212131
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/ResponseEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/ArtifactShareState"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "artifact_id": "art_VnfrWic8UbB9q3EfYR4Gmg",
+                    "share_enabled": true,
+                    "public_url": "https://console.flashcat.cloud/share/artifact/art_VnfrWic8UbB9q3EfYR4Gmg",
+                    "shared_by": 2476001,
+                    "shared_at": 1785829900000
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -55555,97 +57441,101 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
           "500": {
             "$ref": "#/components/responses/ServerError"
           }
-        },
+        }
+      }
+    },
+    "/safari/artifact/gallery/update": {
+      "post": {
+        "operationId": "artifact-write-update",
+        "summary": "Update artifact",
+        "description": "Rename an artifact or transfer it between personal and team scope.",
+        "tags": [
+          "AI SRE/Artifacts"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "Update shared snapshot",
-        "tags": [
-          "AI SRE/Artifacts"
-        ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Fails with `InvalidParameter` when sharing is not enabled — enable it first.\n- The link never changes; only the snapshot bytes and `shared_at` are refreshed.\n- Use `share_file_id != file_id` on the artifact detail to detect a stale snapshot before syncing.\n- Every call is recorded in the account audit log.\n",
-          "href": "/en/api-reference/ai-sre/artifacts/artifact-write-share-sync",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Only the provided fields change; omit `title` or `team_id` to keep them.\n- Requires `can_edit` on the artifact (the creator, any member of its owning team, or anyone who can manage its source session); otherwise the call fails with `AccessDenied`.\n- `team_id: 0` (move to personal) is allowed only for the creator; a positive `team_id` requires the caller (for `app_key` calls, the key owner) to be a member of that team.\n- Returns the full artifact after the update.\n- Every call is recorded in the account audit log.\n",
+          "href": "/en/api-reference/ai-sre/artifacts/artifact-write-update",
           "metadata": {
-            "sidebarTitle": "Update shared snapshot"
+            "sidebarTitle": "Update artifact"
           }
-        }
-      }
-    },
-    "/safari/artifact/gallery/update": {
-      "post": {
-        "description": "Rename an artifact or transfer it between personal and team scope.",
-        "operationId": "artifact-write-update",
+        },
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {
-                "artifact_id": "art_VnfrWic8UbB9q3EfYR4Gmg",
-                "title": "SK 海力士 2026 Q2 财报深度分析（终稿）"
-              },
               "schema": {
                 "$ref": "#/components/schemas/ArtifactUpdateRequest"
-              }
-            }
-          },
-          "required": true
-        },
-        "responses": {
-          "200": {
-            "content": {
-              "application/json": {
-                "example": {
-                  "data": {
-                    "artifact_id": "art_VnfrWic8UbB9q3EfYR4Gmg",
-                    "can_edit": true,
-                    "content_type": "text/html",
-                    "created_at": 1785293373899,
-                    "creator_name": "yushuangyu",
-                    "file_id": "pf_SdhEA5fbZJGnHzwrNJMMSB",
-                    "is_mine": true,
-                    "name": "sk-hynix-q2-2026-report.html",
-                    "person_id": 2476444212131,
-                    "public_url": "https://console.flashcat.cloud/share/artifact/art_VnfrWic8UbB9q3EfYR4Gmg",
-                    "session_id": "sess_VCbVPZrq9YoyBu8sNCmqUy",
-                    "session_title": "分析海力士财报并发布报告",
-                    "share_enabled": true,
-                    "share_file_id": "pf_SdhEA5fbZJGnHzwrNJMMSB",
-                    "shared_at": 1785747928665,
-                    "shared_by": 3790925372131,
-                    "size": 18996,
-                    "team_id": 2477033058131,
-                    "team_name": "研发团队",
-                    "title": "SK 海力士 2026 Q2 财报深度分析（终稿）",
-                    "updated_at": 1785829000000
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
+              },
+              "example": {
+                "artifact_id": "art_VnfrWic8UbB9q3EfYR4Gmg",
+                "title": "Checkout API latency postmortem (final)"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/ResponseEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/PublishedArtifactItem"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "artifact_id": "art_VnfrWic8UbB9q3EfYR4Gmg",
+                    "title": "Checkout API latency postmortem (final)",
+                    "team_id": 4012,
+                    "team_name": "SRE",
+                    "person_id": 2476001,
+                    "creator_name": "Alice",
+                    "is_mine": true,
+                    "can_edit": true,
+                    "session_id": "sess_VCbVPZrq9YoyBu8sNCmqUy",
+                    "session_title": "Investigate checkout API latency spike",
+                    "file_id": "pf_SdhEA5fbZJGnHzwrNJMMSB",
+                    "name": "checkout-latency-postmortem.html",
+                    "size": 18996,
+                    "content_type": "text/html",
+                    "created_at": 1785293373899,
+                    "updated_at": 1785829000000,
+                    "pinned_at": 1785750000000,
+                    "share_enabled": true,
+                    "public_url": "https://console.flashcat.cloud/share/artifact/art_VnfrWic8UbB9q3EfYR4Gmg",
+                    "shared_by": 2476001,
+                    "shared_at": 1785747928665,
+                    "share_file_id": "pf_SdhEA5fbZJGnHzwrNJMMSB"
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -55653,81 +57543,84 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
           "500": {
             "$ref": "#/components/responses/ServerError"
           }
-        },
+        }
+      }
+    },
+    "/safari/artifact/sign": {
+      "post": {
+        "operationId": "artifact-read-sign",
+        "summary": "Create signed file URLs",
+        "description": "Create short-lived signed URLs to download or preview a presented file.",
+        "tags": [
+          "AI SRE/Artifacts"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "Update artifact",
-        "tags": [
-          "AI SRE/Artifacts"
-        ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Only the provided fields change — omit `title` or `team_id` to leave them unchanged.\n- `team_id: 0` moves the artifact to personal scope (only the creator can manage it); a positive `team_id` requires the caller (for `app_key` calls, the key owner) to be a member of that team.\n- Returns the full artifact after the update.\n- Every call is recorded in the account audit log.\n",
-          "href": "/en/api-reference/ai-sre/artifacts/artifact-write-update",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Works for any file of a live gallery artifact in the account; for other session files the caller needs access to the source session (or a valid `share_token`). A missing file and a file the caller cannot reach both fail with `ResourceNotFound`.\n- Both URLs expire after `expires_in` seconds (300). Sign again to get fresh URLs.\n- The URLs are relative: prepend `https://api.flashcat.cloud` and call them with `GET /safari/artifact/stream`, authenticated as the same member that signed them. The token is bound to the account and that member, so it does not work for anyone else.\n",
+          "href": "/en/api-reference/ai-sre/artifacts/artifact-read-sign",
           "metadata": {
-            "sidebarTitle": "Update artifact"
+            "sidebarTitle": "Create signed file URLs"
           }
-        }
-      }
-    },
-    "/safari/artifact/sign": {
-      "post": {
-        "description": "Create short-lived signed URLs to download or preview a presented file.",
-        "operationId": "artifact-read-sign",
+        },
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {
-                "file_id": "pf_SdhEA5fbZJGnHzwrNJMMSB"
-              },
               "schema": {
                 "$ref": "#/components/schemas/ArtifactSignRequest"
+              },
+              "example": {
+                "file_id": "pf_SdhEA5fbZJGnHzwrNJMMSB"
               }
             }
-          },
-          "required": true
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "content_type": "text/html",
-                    "download_url": "/safari/artifact/stream?mode=download&t=cGZfU2RoRUE1ZmJaSkduSHp3ck5KTU1TQnxzZXNzX1ZDYlZQWnJxOVlveUJ1OHNOQ21xVXl8MjQ1MTAwMjc1MTEzMXwyNDc2NDQ0MjEyMTMxfDB8MHwxNzg4NTI5NjI2NTU0.hPQHab0MBNbnrHYwc6VwDJbGonIamfWUr0yeSmLHYAs",
-                    "expires_in": 300,
-                    "name": "sk-hynix-q2-2026-report.html",
-                    "preview_url": "/safari/artifact/stream?mode=preview&t=cGZfU2RoRUE1ZmJaSkduSHp3ck5KTU1TQnxzZXNzX1ZDYlZQWnJxOVlveUJ1OHNOQ21xVXl8MjQ1MTAwMjc1MTEzMXwyNDc2NDQ0MjEyMTMxfDB8MHwxNzg4NTI5NjI2NTU0.hPQHab0MBNbnrHYwc6VwDJbGonIamfWUr0yeSmLHYAs",
-                    "size": 18996
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/ResponseEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/SignedURLs"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "download_url": "/safari/artifact/stream?mode=download&t=eyJmaWxlX2lkIjoicGZfU2RoRUE1ZmJaSkduSHp3ck5KTU1TQiJ9.c2lnbmF0dXJl",
+                    "preview_url": "/safari/artifact/stream?mode=preview&t=eyJmaWxlX2lkIjoicGZfU2RoRUE1ZmJaSkduSHp3ck5KTU1TQiJ9.c2lnbmF0dXJl",
+                    "expires_in": 300,
+                    "name": "checkout-latency-postmortem.html",
+                    "size": 18996,
+                    "content_type": "text/html"
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -55735,74 +57628,98 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
           "500": {
             "$ref": "#/components/responses/ServerError"
           }
-        },
+        }
+      }
+    },
+    "/safari/artifact/stream": {
+      "get": {
+        "operationId": "artifact-read-stream",
+        "summary": "Download or preview a file",
+        "description": "Download or preview a file's bytes using a signed token.",
+        "tags": [
+          "AI SRE/Artifacts"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "Create signed file URLs",
-        "tags": [
-          "AI SRE/Artifacts"
-        ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Both URLs expire after `expires_in` seconds (300). Sign again to get fresh URLs.\n- Returned URLs are relative — prepend `https://api.flashcat.cloud` before use, then follow them with `GET /safari/artifact/stream`.\n- The signed token is bound to the calling account and the app_key owner's identity, so a leaked URL does not work for another account or member.\n",
-          "href": "/en/api-reference/ai-sre/artifacts/artifact-read-sign",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Take the full URL from `/safari/artifact/sign`; authenticate with an `app_key` of the same member that signed it. An expired or foreign token fails with `ResourceNotFound`.\n- Files in object storage return `302` to a presigned URL valid for 5 minutes; follow redirects. CSV files in `download` mode, and files kept on a runner, are streamed directly with `200`.\n- `download` mode of a CSV file prepends a UTF-8 byte order mark (if missing) and sets `Content-Type: text/csv; charset=utf-8` so spreadsheet apps open it correctly.\n- A file kept on a runner that is no longer reachable returns `410` with a plain-text message; re-run the task to regenerate the file.\n- Responses carry `Cache-Control: private, no-store`.\n",
+          "href": "/en/api-reference/ai-sre/artifacts/artifact-read-stream",
           "metadata": {
-            "sidebarTitle": "Create signed file URLs"
+            "sidebarTitle": "Download or preview a file"
           }
-        }
-      }
-    },
-    "/safari/artifact/stream": {
-      "get": {
-        "description": "Download or preview a file's bytes using a signed token.",
-        "operationId": "artifact-read-stream",
+        },
         "parameters": [
           {
-            "description": "Signed token issued by `POST /safari/artifact/sign`. Bound to the calling account and person; valid for 5 minutes.",
-            "in": "query",
             "name": "t",
+            "in": "query",
             "required": true,
             "schema": {
               "type": "string"
-            }
+            },
+            "description": "Signed token issued by `POST /safari/artifact/sign`. Bound to the calling account and person; valid for 5 minutes."
           },
           {
-            "description": "`download` (default) serves the file as an attachment; `preview` serves it inline for browser display. Any other value falls back to `download`.",
-            "in": "query",
             "name": "mode",
+            "in": "query",
             "required": false,
             "schema": {
-              "default": "download",
+              "type": "string",
               "enum": [
                 "download",
                 "preview"
               ],
-              "type": "string"
-            }
+              "default": "download"
+            },
+            "description": "`download` (default) serves the file as an attachment; `preview` serves it inline for browser display. Any other value falls back to `download`."
           }
         ],
         "responses": {
           "200": {
+            "description": "File bytes, returned directly for files kept on a runner and for CSV files in `download` mode. `Content-Disposition` is `attachment` or `inline` according to `mode`.",
             "content": {
               "application/octet-stream": {
                 "schema": {
-                  "format": "binary",
-                  "type": "string"
+                  "type": "string",
+                  "format": "binary"
                 }
               }
-            },
-            "description": "File bytes, proxied, when the file is hosted on a self-hosted runner. Content-Disposition follows `mode`."
+            }
           },
           "302": {
-            "description": "Redirect to a short-lived presigned object-storage URL when the file lives in S3-compatible storage. Follow the `Location` header; no body."
+            "description": "Redirect to a presigned object-storage URL valid for 5 minutes (files in object storage). The `Location` header carries the URL.",
+            "headers": {
+              "Location": {
+                "description": "Presigned object-storage URL.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            }
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "410": {
+            "description": "The runner holding the file is no longer available; the body is a plain-text message. Re-run the task to regenerate the file.",
+            "content": {
+              "text/plain": {
+                "schema": {
+                  "type": "string"
+                }
+              }
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -55816,75 +57733,76 @@
           "500": {
             "$ref": "#/components/responses/ServerError"
           }
-        },
+        }
+      }
+    },
+    "/safari/automation/rule/create": {
+      "post": {
+        "operationId": "automation-rule-write-create",
+        "summary": "Create Automation rule",
+        "description": "Create an Automation rule with schedule, HTTP POST, On-call incident, and war room triggers.",
+        "tags": [
+          "AI SRE/Automations"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "Download or preview a file",
-        "tags": [
-          "AI SRE/Artifacts"
-        ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **100 requests/minute**; **10 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Success has two forms: a `302` redirect to a short-lived presigned object-storage URL (files stored in S3-compatible storage), or a `200` binary stream (files hosted on a self-hosted runner). Follow redirects.\n- Responses carry `Cache-Control: private, no-store` — they are never cached by the gateway.\n",
-          "href": "/en/api-reference/ai-sre/artifacts/artifact-read-stream",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Automation Manage** (`ai-sre`) |\n\n## Usage\n\n- Omit `team_id` or send `0` for a personal rule. A team rule requires the caller to be a member of that team; account owners and admins get no exemption.\n- A rule's scope is fixed at creation: Update Automation rule rejects any `team_id` that differs from the stored value. Create a new rule to run the same task under another scope.\n- `cron_expr` is required even when only other triggers are used; send a valid expression with `schedule_trigger_enabled=false`.\n- `cron_expr` is evaluated in `timezone` if provided, else the caller's member timezone, else the account timezone, else `Asia/Shanghai`.\n- `http_post_trigger_enabled=true` creates an enabled HTTP POST trigger. `http_post_token` is returned only in this response; save it. Fire the trigger with `POST` to `http_post_trigger_url` and the header `Authorization: Bearer <http_post_token>`; the optional JSON body `{\"text\": \"...\"}` is limited to 256 KB.\n- If any `oncall_incident_*` field is sent, both `oncall_incident_channel_ids` and `oncall_incident_severities` must be non-empty. Matching incidents start runs with `trigger_kind=oncall_incident`.\n- If `war_room_trigger_enabled=true` or `war_room_channel_ids` is sent, both `war_room_channel_ids` and `war_room_severities` must be non-empty. When a war room (IM group chat) is created for a matching incident, the agent runs inside that group chat and the run has `trigger_kind=war_room_created`.\n- Runs started through the API execute in the web console (`execution_place=web_console`); `run_in=current-chat` is accepted only from a live IM conversation with the AI SRE agent and is rejected here.\n- The response is the created rule; `can_edit` is always `true` for the creator.\n- Every call is recorded in the account audit log.\n",
+          "href": "/en/api-reference/ai-sre/automations/automation-rule-write-create",
           "metadata": {
-            "sidebarTitle": "Download or preview a file"
+            "sidebarTitle": "Create Automation rule"
           }
-        }
-      }
-    },
-    "/safari/automation/rule/create": {
-      "post": {
-        "description": "Create an Automation rule with schedule, HTTP POST, and On-call incident triggers.",
-        "operationId": "automation-rule-write-create",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "cron_expr": "0 9 * * 1",
-                "enabled": true,
-                "http_post_trigger_enabled": true,
-                "name": "Weekly on-call review",
-                "oncall_incident_channel_ids": [
-                  456
-                ],
-                "oncall_incident_severities": [
-                  "Critical",
-                  "Warning"
-                ],
-                "oncall_incident_trigger_enabled": true,
-                "prompt": "Summarize last week's alert noise and escalation load.",
-                "schedule_trigger_enabled": true,
-                "team_id": 123,
-                "timezone": "Asia/Shanghai"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/AutomationRuleCreateRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ResponseEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/AutomationRuleItem"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
+                    "rule_id": "arule_7NnLzY2Qp8xS4kUaV3mR6b",
                     "account_id": 10023,
-                    "can_edit": true,
-                    "created_at": 1780367971228,
-                    "cron_expr": "0 9 * * 1",
+                    "team_id": 123,
+                    "owner_id": 80011,
+                    "name": "Weekly on-call review",
                     "enabled": true,
-                    "environment_id": "",
+                    "run_scope": "team",
+                    "cron_expr": "0 9 * * 1",
+                    "timezone": "Asia/Shanghai",
+                    "prompt": "Summarize last week's alert noise and escalation load.",
                     "environment_kind": "",
-                    "http_post_token": "sat_yQ9p8V7n6M5k4J3h2G1f0E9d8C7b6A5z4Y3x2W1v0U",
-                    "http_post_trigger_enabled": true,
+                    "environment_id": "",
+                    "schedule_trigger_id": "atrig_6aKp3wT9mQ2xVc8bR1nY7z",
+                    "schedule_trigger_enabled": true,
                     "http_post_trigger_id": "atrig_2bLq4xT8mP1sWd9cN3rF6y",
                     "http_post_trigger_url": "/safari/automation/triggers/atrig_2bLq4xT8mP1sWd9cN3rF6y/fire",
-                    "name": "Weekly on-call review",
+                    "http_post_trigger_enabled": true,
+                    "can_edit": true,
+                    "created_at": 1780367971228,
+                    "updated_at": 1780367971228,
+                    "http_post_token": "sat_yQ9p8V7n6M5k4J3h2G1f0E9d8C7b6A5z4Y3x2W1v0U",
+                    "schedule_next_fire_at_ms": 1780630800000,
+                    "oncall_incident_trigger_id": "atrig_9cVb2mN7qKs4dEa8T1rY5p",
+                    "oncall_incident_trigger_enabled": true,
                     "oncall_incident_channel_ids": [
                       456
                     ],
@@ -55892,39 +57810,19 @@
                       "Critical",
                       "Warning"
                     ],
-                    "oncall_incident_trigger_enabled": true,
-                    "oncall_incident_trigger_id": "atrig_9cVb2mN7qKs4dEa8T1rY5p",
-                    "owner_id": 80011,
-                    "prompt": "Summarize last week's alert noise and escalation load.",
-                    "rule_id": "arule_7NnLzY2Qp8xS4kUaV3mR6b",
-                    "run_scope": "team",
-                    "schedule_next_fire_at_ms": 1780630800000,
-                    "schedule_trigger_enabled": true,
-                    "schedule_trigger_id": "atrig_6aKp3wT9mQ2xVc8bR1nY7z",
-                    "team_id": 123,
-                    "timezone": "Asia/Shanghai",
-                    "updated_at": 1780367971228
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/ResponseEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/AutomationRuleItem"
-                        }
-                      },
-                      "type": "object"
+                    "oncall_incident_merge_similar": true,
+                    "war_room_trigger_enabled": false,
+                    "execution_place": "web_console",
+                    "execution_location": {
+                      "place": "web_console",
+                      "run_scope": "team",
+                      "team_id": 123,
+                      "description": "Web console"
                     }
-                  ]
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -55942,68 +57840,82 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/AutomationRuleCreateRequest"
+              },
+              "example": {
+                "name": "Weekly on-call review",
+                "team_id": 123,
+                "enabled": true,
+                "cron_expr": "0 9 * * 1",
+                "timezone": "Asia/Shanghai",
+                "schedule_trigger_enabled": true,
+                "prompt": "Summarize last week's alert noise and escalation load.",
+                "http_post_trigger_enabled": true,
+                "oncall_incident_trigger_enabled": true,
+                "oncall_incident_channel_ids": [
+                  456
+                ],
+                "oncall_incident_severities": [
+                  "Critical",
+                  "Warning"
+                ]
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/automation/rule/delete": {
+      "post": {
+        "operationId": "automation-rule-write-delete",
+        "summary": "Delete Automation rule",
+        "description": "Delete an Automation rule together with all of its triggers and their subscriptions.",
+        "tags": [
+          "AI SRE/Automations"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "Create Automation rule",
-        "tags": [
-          "AI SRE/Automations"
-        ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | Valid `app_key`; management operations require the caller to manage the target rule |\n\n## Usage\n\n- A caller may create personal rules and rules for any team in the current account; `team_id` can be reassigned later via update (converting a team rule to personal is owner-only; moving into a team requires the caller to belong to it).\n- `cron_expr` is evaluated in `timezone` if provided, else the caller's member timezone, else the account timezone, else the server default (Asia/Shanghai).\n- `http_post_trigger_enabled=true` creates and enables an HTTP POST trigger; the response's `http_post_token` is a one-time value returned only on creation — save it immediately.\n- `oncall_incident_trigger_enabled=true` requires at least one `oncall_incident_channel_ids` entry and one `oncall_incident_severities` value; matching incidents run with `trigger_kind=oncall_incident`.\n- Every call is recorded in the account audit log.\n",
-          "href": "/en/api-reference/ai-sre/automations/automation-rule-write-create",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Automation Manage** (`ai-sre`) |\n\n## Usage\n\n- Deleting a rule also removes its schedule, HTTP POST, On-call incident, and war room triggers; the HTTP POST trigger token stops working.\n- Manage rights: a personal rule (`team_id=0`) can be managed only by its owner; a team rule only by members of that team. Account owners and admins get no exemption and must join the team. Others get `403`.\n- While another update, delete, or manual run of the same rule is in progress, the call fails with HTTP `423` and `code: \"RequestLocked\"`; retry later.\n- Every call is recorded in the account audit log.\n",
+          "href": "/en/api-reference/ai-sre/automations/automation-rule-write-delete",
           "metadata": {
-            "sidebarTitle": "Create Automation rule"
+            "sidebarTitle": "Delete Automation rule"
           }
-        }
-      }
-    },
-    "/safari/automation/rule/delete": {
-      "post": {
-        "description": "Delete an Automation rule.",
-        "operationId": "automation-rule-write-delete",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "rule_id": "arule_7NnLzY2Qp8xS4kUaV3mR6b"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/AutomationRuleIDRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": null,
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/ResponseEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "description": "Always null on success.",
-                          "type": "null"
+                          "type": "null",
+                          "description": "Not returned on success; the body carries only `request_id`."
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -56021,58 +57933,87 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/AutomationRuleIDRequest"
+              },
+              "example": {
+                "rule_id": "arule_7NnLzY2Qp8xS4kUaV3mR6b"
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/automation/rule/get": {
+      "post": {
+        "operationId": "automation-rule-read-get",
+        "summary": "Get Automation rule",
+        "description": "Get one Automation rule by ID, including its trigger settings and execution destination.",
+        "tags": [
+          "AI SRE/Automations"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "Delete Automation rule",
-        "tags": [
-          "AI SRE/Automations"
-        ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | Valid `app_key`; management operations require the caller to manage the target rule |\n\n## Usage\n\n- Deleting a rule also removes its schedule, HTTP POST, and On-call incident triggers; a deleted HTTP POST trigger's token stops working immediately.\n- Every call is recorded in the account audit log.\n",
-          "href": "/en/api-reference/ai-sre/automations/automation-rule-write-delete",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Automation Read** (`ai-sre`) |\n\n## Usage\n\n- Manage rights: a personal rule (`team_id=0`) can be managed only by its owner; a team rule only by members of that team. Account owners and admins get no exemption and must join the team. Callers without manage rights get `403` even if the rule shows up in their list.\n- `last_run` is never set on this endpoint; use List Automation rules or List Automation runs for run status.\n- `http_post_token` is never returned here; it appears only when a token is issued (create, enabling a new HTTP POST trigger, or rotation).\n",
+          "href": "/en/api-reference/ai-sre/automations/automation-rule-read-get",
           "metadata": {
-            "sidebarTitle": "Delete Automation rule"
+            "sidebarTitle": "Get Automation rule"
           }
-        }
-      }
-    },
-    "/safari/automation/rule/get": {
-      "post": {
-        "description": "Get one Automation rule by ID.",
-        "operationId": "automation-rule-read-get",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "rule_id": "arule_7NnLzY2Qp8xS4kUaV3mR6b"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/AutomationRuleIDRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ResponseEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/AutomationRuleItem"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
+                    "rule_id": "arule_7NnLzY2Qp8xS4kUaV3mR6b",
                     "account_id": 10023,
-                    "can_edit": true,
-                    "created_at": 1780367971228,
-                    "cron_expr": "0 9 * * 1",
+                    "team_id": 123,
+                    "owner_id": 80011,
+                    "name": "Weekly on-call review",
                     "enabled": true,
-                    "environment_id": "",
+                    "run_scope": "team",
+                    "cron_expr": "0 9 * * 1",
+                    "timezone": "Asia/Shanghai",
+                    "prompt": "Summarize last week's alert noise and escalation load.",
                     "environment_kind": "",
-                    "http_post_trigger_enabled": true,
+                    "environment_id": "",
+                    "schedule_trigger_id": "atrig_6aKp3wT9mQ2xVc8bR1nY7z",
+                    "schedule_trigger_enabled": true,
                     "http_post_trigger_id": "atrig_2bLq4xT8mP1sWd9cN3rF6y",
                     "http_post_trigger_url": "/safari/automation/triggers/atrig_2bLq4xT8mP1sWd9cN3rF6y/fire",
-                    "name": "Weekly on-call review",
+                    "http_post_trigger_enabled": true,
+                    "can_edit": true,
+                    "created_at": 1780367971228,
+                    "updated_at": 1780367971228,
+                    "schedule_next_fire_at_ms": 1780630800000,
+                    "oncall_incident_trigger_id": "atrig_9cVb2mN7qKs4dEa8T1rY5p",
+                    "oncall_incident_trigger_enabled": true,
                     "oncall_incident_channel_ids": [
                       456
                     ],
@@ -56080,39 +58021,19 @@
                       "Critical",
                       "Warning"
                     ],
-                    "oncall_incident_trigger_enabled": true,
-                    "oncall_incident_trigger_id": "atrig_9cVb2mN7qKs4dEa8T1rY5p",
-                    "owner_id": 80011,
-                    "prompt": "Summarize last week's alert noise and escalation load.",
-                    "rule_id": "arule_7NnLzY2Qp8xS4kUaV3mR6b",
-                    "run_scope": "team",
-                    "schedule_next_fire_at_ms": 1780630800000,
-                    "schedule_trigger_enabled": true,
-                    "schedule_trigger_id": "atrig_6aKp3wT9mQ2xVc8bR1nY7z",
-                    "team_id": 123,
-                    "timezone": "Asia/Shanghai",
-                    "updated_at": 1780367971228
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/ResponseEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/AutomationRuleItem"
-                        }
-                      },
-                      "type": "object"
+                    "oncall_incident_merge_similar": true,
+                    "war_room_trigger_enabled": false,
+                    "execution_place": "web_console",
+                    "execution_location": {
+                      "place": "web_console",
+                      "run_scope": "team",
+                      "team_id": 123,
+                      "description": "Web console"
                     }
-                  ]
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -56130,61 +58051,90 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/AutomationRuleIDRequest"
+              },
+              "example": {
+                "rule_id": "arule_7NnLzY2Qp8xS4kUaV3mR6b"
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/automation/rule/list": {
+      "post": {
+        "operationId": "automation-rule-read-list",
+        "summary": "List Automation rules",
+        "description": "List Automation rules visible to the caller, newest update first, with pagination and filters.",
+        "tags": [
+          "AI SRE/Automations"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "Get Automation rule",
-        "tags": [
-          "AI SRE/Automations"
-        ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | Valid `app_key`; caller must manage the target rule |\n\n## Usage\n\n- Manage rights mean the personal rule owner; for team rules, an account admin or a member of the rule's team.\n",
-          "href": "/en/api-reference/ai-sre/automations/automation-rule-read-get",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Automation Read** (`ai-sre`) |\n\n## Usage\n\n- Visible rules: the caller's own personal rules plus rules of teams the caller belongs to. Account owners and admins see only the teams they belong to, never other people's personal rules.\n- `scope=personal` returns only the caller's personal rules; `scope=team` only rules of the caller's teams. `team_ids` narrows the result further and never expands access.\n- Results are sorted by `updated_at` descending. Each item carries `last_run` (the most recent run) when the rule has ever run.\n- `can_edit` on each item tells whether the caller can manage (get, update, delete, run) that rule.\n",
+          "href": "/en/api-reference/ai-sre/automations/automation-rule-read-list",
           "metadata": {
-            "sidebarTitle": "Get Automation rule"
+            "sidebarTitle": "List Automation rules"
           }
-        }
-      }
-    },
-    "/safari/automation/rule/list": {
-      "post": {
-        "description": "List Automation rules visible to the caller.",
-        "operationId": "automation-rule-read-list",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "limit": 20,
-                "scope": "all"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/AutomationRuleListRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ResponseEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/AutomationRuleListResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
+                    "total": 1,
                     "rules": [
                       {
+                        "rule_id": "arule_7NnLzY2Qp8xS4kUaV3mR6b",
                         "account_id": 10023,
-                        "can_edit": true,
-                        "created_at": 1780367971228,
-                        "cron_expr": "0 9 * * 1",
+                        "team_id": 123,
+                        "owner_id": 80011,
+                        "name": "Weekly on-call review",
                         "enabled": true,
-                        "environment_id": "",
+                        "run_scope": "team",
+                        "cron_expr": "0 9 * * 1",
+                        "timezone": "Asia/Shanghai",
+                        "prompt": "Summarize last week's alert noise and escalation load.",
                         "environment_kind": "",
-                        "http_post_trigger_enabled": true,
+                        "environment_id": "",
+                        "schedule_trigger_id": "atrig_6aKp3wT9mQ2xVc8bR1nY7z",
+                        "schedule_trigger_enabled": true,
                         "http_post_trigger_id": "atrig_2bLq4xT8mP1sWd9cN3rF6y",
                         "http_post_trigger_url": "/safari/automation/triggers/atrig_2bLq4xT8mP1sWd9cN3rF6y/fire",
-                        "name": "Weekly on-call review",
+                        "http_post_trigger_enabled": true,
+                        "can_edit": true,
+                        "created_at": 1780367971228,
+                        "updated_at": 1780367971228,
+                        "schedule_next_fire_at_ms": 1780630800000,
+                        "oncall_incident_trigger_id": "atrig_9cVb2mN7qKs4dEa8T1rY5p",
+                        "oncall_incident_trigger_enabled": true,
                         "oncall_incident_channel_ids": [
                           456
                         ],
@@ -56192,42 +58142,26 @@
                           "Critical",
                           "Warning"
                         ],
-                        "oncall_incident_trigger_enabled": true,
-                        "oncall_incident_trigger_id": "atrig_9cVb2mN7qKs4dEa8T1rY5p",
-                        "owner_id": 80011,
-                        "prompt": "Summarize last week's alert noise and escalation load.",
-                        "rule_id": "arule_7NnLzY2Qp8xS4kUaV3mR6b",
-                        "run_scope": "team",
-                        "schedule_next_fire_at_ms": 1780630800000,
-                        "schedule_trigger_enabled": true,
-                        "schedule_trigger_id": "atrig_6aKp3wT9mQ2xVc8bR1nY7z",
-                        "team_id": 123,
-                        "timezone": "Asia/Shanghai",
-                        "updated_at": 1780367971228
-                      }
-                    ],
-                    "total": 1
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/ResponseEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/AutomationRuleListResponse"
+                        "oncall_incident_merge_similar": true,
+                        "war_room_trigger_enabled": false,
+                        "execution_place": "web_console",
+                        "execution_location": {
+                          "place": "web_console",
+                          "run_scope": "team",
+                          "team_id": 123,
+                          "description": "Web console"
+                        },
+                        "last_run": {
+                          "run_id": "trun_5oDvqiG64uur6sBNsTc4u",
+                          "status": "succeeded",
+                          "started_at": 1780630800000
                         }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                      }
+                    ]
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -56245,49 +58179,69 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/AutomationRuleListRequest"
+              },
+              "example": {
+                "scope": "all",
+                "limit": 20
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/automation/rule/run": {
+      "post": {
+        "operationId": "automation-rule-write-run",
+        "summary": "Run Automation rule",
+        "description": "Run an Automation rule once right now, regardless of its triggers or enabled state.",
+        "tags": [
+          "AI SRE/Automations"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "List Automation rules",
-        "tags": [
-          "AI SRE/Automations"
-        ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | Valid `app_key`; results are filtered to the caller's visible scope |\n\n## Usage\n\n- `all` returns your personal rules plus team rules you can access.\n- Account admins see all team rules in list results, but not other users' personal rules.\n- `team_ids` narrows the visible set and never expands access.\n",
-          "href": "/en/api-reference/ai-sre/automations/automation-rule-read-list",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **100 requests/minute**; **5 requests/second** per account |\n| Permissions | **Automation Manage** (`ai-sre`) |\n\n## Usage\n\n- A manual run does not require the rule to be enabled. It fails with `400` before any run is created if the rule's configuration is invalid (for example a BYOC runner the rule's scope may not use), or if the only enabled trigger is the war room trigger (such a rule has no web console run).\n- A personal rule whose owner has left the account is disabled automatically and the call returns `400`.\n- At most one manual run per rule per minute; a second call within that window returns `429` with `code: \"RequestTooFrequently\"`.\n- Manage rights: a personal rule (`team_id=0`) can be managed only by its owner; a team rule only by members of that team. Account owners and admins get no exemption and must join the team.\n- While another update, delete, or manual run of the same rule is in progress, the call fails with HTTP `423` and `code: \"RequestLocked\"`; retry later.\n- The call returns once the agent session has started, not when the run finishes. Track completion with List Automation runs (`trigger_kind=manual`).\n- `run.session_id` is omitted for rules that execute in an IM chat (`execution_place=im`).\n- Every call is recorded in the account audit log.\n",
+          "href": "/en/api-reference/ai-sre/automations/automation-rule-write-run",
           "metadata": {
-            "sidebarTitle": "List Automation rules"
+            "sidebarTitle": "Run Automation rule"
           }
-        }
-      }
-    },
-    "/safari/automation/rule/run": {
-      "post": {
-        "description": "Manually run an Automation rule immediately, outside its schedule.",
-        "operationId": "automation-rule-write-run",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "rule_id": "arule_7NnLzY2Qp8xS4kUaV3mR6b"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/AutomationRuleIDRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ResponseEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/ManualRunRuleResult"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
+                    "rule_id": "arule_7NnLzY2Qp8xS4kUaV3mR6b",
+                    "trigger_kind": "manual",
                     "preflight": {
-                      "app_name": "ai-sre",
+                      "ok": true,
                       "checks": [
                         "rule_loaded",
                         "actor_authorized",
@@ -56295,38 +58249,19 @@
                         "runtime_scope_resolved",
                         "rule_config_valid"
                       ],
-                      "ok": true,
-                      "owner_id": 80011,
                       "scope": "team",
-                      "team_id": 123
+                      "owner_id": 80011,
+                      "team_id": 123,
+                      "app_name": "ai-sre"
                     },
-                    "rule_id": "arule_7NnLzY2Qp8xS4kUaV3mR6b",
                     "run": {
                       "run_id": "trun_5oDvqiG64uur6sBNsTc4u",
                       "session_id": "sess_f8oDvqiG64uur6sBNsTc4u"
-                    },
-                    "trigger_kind": "manual"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/ResponseEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/ManualRunRuleResult"
-                        }
-                      },
-                      "type": "object"
                     }
-                  ]
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -56344,70 +58279,88 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/AutomationRuleIDRequest"
+              },
+              "example": {
+                "rule_id": "arule_7NnLzY2Qp8xS4kUaV3mR6b"
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/automation/rule/update": {
+      "post": {
+        "operationId": "automation-rule-write-update",
+        "summary": "Update Automation rule",
+        "description": "Update an Automation rule's fields and trigger settings; omitted fields keep their current values.",
+        "tags": [
+          "AI SRE/Automations"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "Run Automation rule",
-        "tags": [
-          "AI SRE/Automations"
-        ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **100 requests/minute**; **5 requests/second** per account |\n| Permissions | Valid `app_key`; caller must manage the target rule |\n\n## Usage\n\n- Rate-limited to at most once per minute per rule; a second call within that window returns `429` with `code: \"RequestTooFrequently\"`.\n- Only enabled rules can run manually; a disabled or misconfigured rule fails preflight with a `400` error before any run is created.\n- The call returns once the underlying agent session starts, not once the run finishes; the run continues asynchronously — use List Automation runs to check completion status.\n- `trigger_kind` is always `manual` for runs started this way, distinguishing them from `schedule`, `http_post`, and `oncall_incident` runs in run history.\n- Every call is recorded in the account audit log.\n",
-          "href": "/en/api-reference/ai-sre/automations/automation-rule-write-run",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Automation Manage** (`ai-sre`) |\n\n## Usage\n\n- Omitted or `null` fields are left unchanged. Empty arrays for `*_channel_ids` / `*_severities` also keep the stored lists.\n- `team_id` cannot change: sending a value different from the stored one returns `400`. Resending the current value is accepted.\n- `cron_expr` and `timezone` can be sent independently; the other keeps its stored value. Sending `timezone: \"\"` stores `UTC`.\n- Sending `environment_kind` without `environment_id` clears the stored `environment_id`.\n- `http_post_trigger_enabled=true` creates the HTTP POST trigger when the rule has none and returns its token. `rotate_http_post_trigger_token=true` issues a new token (the old one stops working) and requires the trigger to be enabled. A new token is returned only in this response.\n- Creating an On-call incident or war room trigger through update needs both its channel IDs and severities.\n- Manage rights: a personal rule (`team_id=0`) can be managed only by its owner; a team rule only by members of that team. Account owners and admins get no exemption and must join the team.\n- While another update, delete, or manual run of the same rule is in progress, the call fails with HTTP `423` and `code: \"RequestLocked\"`; retry later.\n- Every call is recorded in the account audit log.\n",
+          "href": "/en/api-reference/ai-sre/automations/automation-rule-write-update",
           "metadata": {
-            "sidebarTitle": "Run Automation rule"
+            "sidebarTitle": "Update Automation rule"
           }
-        }
-      }
-    },
-    "/safari/automation/rule/update": {
-      "post": {
-        "description": "Update mutable Automation rule fields, including HTTP POST and On-call incident trigger settings.",
-        "operationId": "automation-rule-write-update",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "cron_expr": "15 9 * * 1",
-                "enabled": true,
-                "oncall_incident_channel_ids": [
-                  456
-                ],
-                "oncall_incident_severities": [
-                  "Critical",
-                  "Warning"
-                ],
-                "oncall_incident_trigger_enabled": true,
-                "rotate_http_post_trigger_token": true,
-                "rule_id": "arule_7NnLzY2Qp8xS4kUaV3mR6b"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/AutomationRuleUpdateRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ResponseEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/AutomationRuleItem"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
+                    "rule_id": "arule_7NnLzY2Qp8xS4kUaV3mR6b",
                     "account_id": 10023,
-                    "can_edit": true,
-                    "created_at": 1780367971228,
-                    "cron_expr": "0 9 * * 1",
+                    "team_id": 123,
+                    "owner_id": 80011,
+                    "name": "Weekly on-call review",
                     "enabled": true,
-                    "environment_id": "",
+                    "run_scope": "team",
+                    "cron_expr": "0 9 * * 1",
+                    "timezone": "Asia/Shanghai",
+                    "prompt": "Summarize last week's alert noise and escalation load.",
                     "environment_kind": "",
-                    "http_post_token": "sat_yQ9p8V7n6M5k4J3h2G1f0E9d8C7b6A5z4Y3x2W1v0U",
-                    "http_post_trigger_enabled": true,
+                    "environment_id": "",
+                    "schedule_trigger_id": "atrig_6aKp3wT9mQ2xVc8bR1nY7z",
+                    "schedule_trigger_enabled": true,
                     "http_post_trigger_id": "atrig_2bLq4xT8mP1sWd9cN3rF6y",
                     "http_post_trigger_url": "/safari/automation/triggers/atrig_2bLq4xT8mP1sWd9cN3rF6y/fire",
-                    "name": "Weekly on-call review",
+                    "http_post_trigger_enabled": true,
+                    "can_edit": true,
+                    "created_at": 1780367971228,
+                    "updated_at": 1780367971228,
+                    "http_post_token": "sat_yQ9p8V7n6M5k4J3h2G1f0E9d8C7b6A5z4Y3x2W1v0U",
+                    "schedule_next_fire_at_ms": 1780630800000,
+                    "oncall_incident_trigger_id": "atrig_9cVb2mN7qKs4dEa8T1rY5p",
+                    "oncall_incident_trigger_enabled": true,
                     "oncall_incident_channel_ids": [
                       456
                     ],
@@ -56415,39 +58368,19 @@
                       "Critical",
                       "Warning"
                     ],
-                    "oncall_incident_trigger_enabled": true,
-                    "oncall_incident_trigger_id": "atrig_9cVb2mN7qKs4dEa8T1rY5p",
-                    "owner_id": 80011,
-                    "prompt": "Summarize last week's alert noise and escalation load.",
-                    "rule_id": "arule_7NnLzY2Qp8xS4kUaV3mR6b",
-                    "run_scope": "team",
-                    "schedule_next_fire_at_ms": 1780630800000,
-                    "schedule_trigger_enabled": true,
-                    "schedule_trigger_id": "atrig_6aKp3wT9mQ2xVc8bR1nY7z",
-                    "team_id": 123,
-                    "timezone": "Asia/Shanghai",
-                    "updated_at": 1780367971228
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/ResponseEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/AutomationRuleItem"
-                        }
-                      },
-                      "type": "object"
+                    "oncall_incident_merge_similar": true,
+                    "war_room_trigger_enabled": false,
+                    "execution_place": "web_console",
+                    "execution_location": {
+                      "place": "web_console",
+                      "run_scope": "team",
+                      "team_id": 123,
+                      "description": "Web console"
                     }
-                  ]
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -56465,96 +58398,106 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/AutomationRuleUpdateRequest"
+              },
+              "example": {
+                "rule_id": "arule_7NnLzY2Qp8xS4kUaV3mR6b",
+                "enabled": true,
+                "cron_expr": "15 9 * * 1",
+                "rotate_http_post_trigger_token": true,
+                "oncall_incident_trigger_enabled": true,
+                "oncall_incident_severities": [
+                  "Critical",
+                  "Warning"
+                ],
+                "oncall_incident_channel_ids": [
+                  456
+                ]
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/automation/run/list": {
+      "post": {
+        "operationId": "automation-run-read-list",
+        "summary": "List Automation runs",
+        "description": "List the run history of one Automation rule, newest first, with status, trigger, and time filters.",
+        "tags": [
+          "AI SRE/Automations"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "Update Automation rule",
-        "tags": [
-          "AI SRE/Automations"
-        ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | Valid `app_key`; management operations require the caller to manage the target rule |\n\n## Usage\n\n- Omitted or `null` fields are left unchanged. `team_id` reassigns the rule's scope: `0` converts a team rule to personal (owner-only), `>0` moves it into a team the caller belongs to.\n- `cron_expr` and `timezone` can be updated independently — sending only one keeps the other at its current stored value.\n- `rotate_http_post_trigger_token=true` issues a fresh webhook token, returned only in this response.\n- To trigger from On-call incidents, send `oncall_incident_trigger_enabled`, `oncall_incident_channel_ids`, and `oncall_incident_severities`; matching events run with `trigger_kind=oncall_incident`.\n- Every call is recorded in the account audit log.\n",
-          "href": "/en/api-reference/ai-sre/automations/automation-rule-write-update",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Automation Read** (`ai-sre`) |\n\n## Usage\n\n- Manage rights: a personal rule (`team_id=0`) can be managed only by its owner; a team rule only by members of that team. Account owners and admins get no exemption and must join the team. Others get `403`.\n- Run history is kept for 180 days; earlier `started_after_ms` values are raised to that floor.\n- Results are sorted by `started_at` descending.\n- For runs that executed in an IM chat (`execution_place=im`), `session_id`, `joined_session_id`, and `result_json` are withheld.\n",
+          "href": "/en/api-reference/ai-sre/automations/automation-run-read-list",
           "metadata": {
-            "sidebarTitle": "Update Automation rule"
+            "sidebarTitle": "List Automation runs"
           }
-        }
-      }
-    },
-    "/safari/automation/run/list": {
-      "post": {
-        "description": "List run history for a rule the caller can manage.",
-        "operationId": "automation-run-read-list",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "limit": 20,
-                "rule_id": "arule_7NnLzY2Qp8xS4kUaV3mR6b",
-                "trigger_kind": "schedule"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/AutomationRunListRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ResponseEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/AutomationRunListResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
+                    "total": 1,
                     "runs": [
                       {
+                        "run_id": "trun_5oDvqiG64uur6sBNsTc4u",
+                        "session_id": "sess_f8oDvqiG64uur6sBNsTc4u",
+                        "session_name": "Weekly on-call review",
+                        "kind": "automation_rule",
                         "account_id": 10023,
+                        "rule_id": "arule_7NnLzY2Qp8xS4kUaV3mR6b",
+                        "trigger_kind": "schedule",
+                        "execution_place": "web_console",
+                        "occurrence_key": "atrig_6aKp3wT9mQ2xVc8bR1nY7z:1780630800000",
+                        "status": "succeeded",
                         "attempts": 1,
+                        "started_at": 1780630800000,
                         "completed_at": 1780630923456,
-                        "created_at": 1780630800000,
                         "duration_ms": 123456,
                         "error_code": "",
                         "error_message": "",
-                        "kind": "automation_rule",
-                        "occurrence_key": "atrig_6aKp3wT9mQ2xVc8bR1nY7z:1780630800000",
+                        "stats_json": {},
                         "result_json": {
                           "session_id": "sess_f8oDvqiG64uur6sBNsTc4u"
                         },
-                        "rule_id": "arule_7NnLzY2Qp8xS4kUaV3mR6b",
-                        "run_id": "trun_5oDvqiG64uur6sBNsTc4u",
-                        "session_id": "sess_f8oDvqiG64uur6sBNsTc4u",
-                        "session_name": "Weekly on-call review",
-                        "started_at": 1780630800000,
-                        "stats_json": {},
-                        "status": "succeeded",
-                        "trigger_kind": "schedule",
+                        "created_at": 1780630800000,
                         "updated_at": 1780630923456
                       }
-                    ],
-                    "total": 1
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/ResponseEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/AutomationRunListResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                    ]
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -56572,77 +58515,85 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "security": [
-          {
-            "AppKeyAuth": []
-          }
-        ],
-        "summary": "List Automation runs",
-        "tags": [
-          "AI SRE/Automations"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | Valid `app_key`; caller must manage the target rule |\n\n## Usage\n\n- Run history is visible only when the caller can manage the rule: the personal rule owner; for team rules, an account admin or a member of the rule's team.\n",
-          "href": "/en/api-reference/ai-sre/automations/automation-run-read-list",
-          "metadata": {
-            "sidebarTitle": "List Automation runs"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/AutomationRunListRequest"
+              },
+              "example": {
+                "rule_id": "arule_7NnLzY2Qp8xS4kUaV3mR6b",
+                "limit": 20,
+                "trigger_kind": "schedule"
+              }
+            }
           }
         }
       }
     },
     "/safari/automation/template/list": {
       "post": {
-        "description": "List preset Automation templates for the requested locale.",
         "operationId": "automation-template-read-list",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "locale": "en-US"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/AutomationTemplateListRequest"
-              }
-            }
-          },
-          "required": true
-        },
-        "responses": {
-          "200": {
-            "content": {
-              "application/json": {
-                "example": {
-                  "data": {
-                    "templates": [
-                      {
-                        "description": "Analyze incidents, alerts, response activity, notification load, and related changes from the past week.",
-                        "enabled": false,
-                        "icon": "chart-no-axes-combined",
-                        "name": "Weekly Insights",
-                        "prompt": "Generate a weekly insights report. Analyze incidents, alerts, response activity, notification load, and related changes from the past week. Focus on what happened this week, which signals deserve attention, and which improvement actions are most valuable. Do not modify any Flashduty business state.\n"
-                      }
-                    ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
+        "summary": "List Automation templates",
+        "description": "List built-in Automation templates that prefill the create-rule form, in Chinese or English.",
+        "tags": [
+          "AI SRE/Automations"
+        ],
+        "security": [
+          {
+            "AppKeyAuth": []
+          }
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Automation Read** (`ai-sre`) |\n\n## Usage\n\n- Templates are fixed by the platform and are the same for every account.\n- Language: a `locale` containing `zh` returns Chinese templates, one containing `en` returns English; any other non-empty value returns Chinese. When `locale` is omitted, the `locale`/`lang` query parameter or the `Accept-Language` header decides.\n- Each template is a partial create request: pass its fields to Create Automation rule and add what only you can supply (`cron_expr` when the template has none, `timezone`, channel IDs).\n",
+          "href": "/en/api-reference/ai-sre/automations/automation-template-read-list",
+          "metadata": {
+            "sidebarTitle": "List Automation templates"
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/ResponseEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/AutomationTemplateListResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "templates": [
+                      {
+                        "name": "Weekly Insights",
+                        "description": "Analyze incidents, alerts, response activity, notification load, and related changes from the past week.",
+                        "icon": "chart-no-axes-combined",
+                        "category": "Insights",
+                        "enabled": false,
+                        "prompt": "Generate a weekly insights report. Analyze incidents, alerts, response activity, notification load, and related changes from the past week. Focus on what happened this week, which signals deserve attention, and which improvement actions are most valuable. Do not modify any Flashduty business state.\n",
+                        "schedule_trigger_enabled": true,
+                        "cron_expr": "0 9 * * 1",
+                        "http_post_trigger_enabled": false,
+                        "oncall_incident_trigger_enabled": false,
+                        "war_room_trigger_enabled": false
+                      }
+                    ]
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -56660,67 +58611,70 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/AutomationTemplateListRequest"
+              },
+              "example": {
+                "locale": "en-US"
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/knowledge/file/delete": {
+      "post": {
+        "operationId": "knowledge-file-write-delete",
+        "summary": "Delete knowledge file",
+        "description": "Delete a knowledge file by its relative path.",
+        "tags": [
+          "AI SRE/Knowledge"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "List Automation templates",
-        "tags": [
-          "AI SRE/Automations"
-        ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | Valid `app_key`; results are filtered to the caller's visible scope |\n",
-          "href": "/en/api-reference/ai-sre/automations/automation-template-read-list",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Knowledge Manage** (`ai-sre`) |\n\n## Usage\n\n- Deleting a file that does not exist succeeds with `status` = `ok`.\n- When other files in the knowledge still reference the target via @ref, the delete fails with `ReferenceExist` naming the referrers; set `force` to delete anyway (the referrers are then returned in `warnings`).\n- Pass `expected_version` to delete only if nobody changed the knowledge since your last read; on mismatch the call returns HTTP 200 with `status` = `conflict`.\n- Omitting `pack_id` targets the account knowledge; editing account knowledge requires the account owner or an admin, editing team knowledge requires membership of that team.\n- Every call is recorded in the account audit log.\n",
+          "href": "/en/api-reference/ai-sre/knowledge/knowledge-file-write-delete",
           "metadata": {
-            "sidebarTitle": "List Automation templates"
+            "sidebarTitle": "Delete knowledge file"
           }
-        }
-      }
-    },
-    "/safari/knowledge/file/delete": {
-      "post": {
-        "description": "Delete a knowledge file by its relative path.",
-        "operationId": "knowledge-file-write-delete",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "rel_path": "tmp/openapi-delete-example.md"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/KnowledgeFileDeleteRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/ResponseEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/KnowledgeFileDeleteResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "status": "ok",
+                    "version": 136
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -56738,79 +58692,80 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/KnowledgeFileDeleteRequest"
+              },
+              "example": {
+                "rel_path": "tmp/openapi-delete-example.md"
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/knowledge/file/get": {
+      "post": {
+        "operationId": "knowledge-file-read-get",
+        "summary": "Get knowledge file",
+        "description": "Return a knowledge file's metadata and its base64-encoded content.",
+        "tags": [
+          "AI SRE/Knowledge"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "Delete knowledge file",
-        "tags": [
-          "AI SRE/Knowledge"
-        ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Knowledge Manage** (`ai-sre`) |\n\n## Usage\n\n- Deleting is idempotent — removing a file that does not exist succeeds.\n- When other knowledge files still reference the target, the delete fails with `ReferenceExist` listing the referrers; set `force` to proceed (the referrers are returned as warnings).\n- Omitting `pack_id` targets the account-scope knowledge; editing the account knowledge requires account owner/admin, editing team knowledge requires team membership.\n- Every call is recorded in the account audit log.\n",
-          "href": "/en/api-reference/ai-sre/knowledge/knowledge-file-write-delete",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Content is returned base64-encoded in `content_b64`.\n- A path with no file is not an error: the response has `file` = `null`, an empty `content_b64`, and the current `version`. An unknown `pack_id` returns `ResourceNotFound`.\n- Omitting `pack_id` targets the account knowledge (readable by every member); team knowledge is readable only by members of that team.\n- Keep the returned `version` and pass it as `expected_version` when writing the file back, to avoid overwriting someone else's change.\n",
+          "href": "/en/api-reference/ai-sre/knowledge/knowledge-file-read-get",
           "metadata": {
-            "sidebarTitle": "Delete knowledge file"
+            "sidebarTitle": "Get knowledge file"
           }
-        }
-      }
-    },
-    "/safari/knowledge/file/get": {
-      "post": {
-        "description": "Return a knowledge file's metadata and its base64-encoded content.",
-        "operationId": "knowledge-file-read-get",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "rel_path": "tmp/openapi-example.md"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/KnowledgeFileGetRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "content_b64": "IyBPcGVuQVBJIGV4YW1wbGUKVGVtcCBmaWxlIGZvciBBUEkgZG9jcyBleGFtcGxlLgo=",
-                    "file": {
-                      "checksum": "a0775f9b3f392cd0560b21ad2f579ae4a5d6b1282b9eb145688ba2de717a816d",
-                      "content_type": "text/markdown",
-                      "file_id": "kfl_gctXKRG45aFQGgxSFr59WY",
-                      "pack_id": "kpk_kE49k3FhecfJBwutbshEEc",
-                      "rel_path": "tmp/openapi-example.md",
-                      "size_bytes": 50,
-                      "updated_at_ms": 1786458764961,
-                      "updated_by": 2476444212131
-                    }
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/ResponseEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/KnowledgeFileGetResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "file": {
+                      "file_id": "kfl_gctXKRG45aFQGgxSFr59WY",
+                      "pack_id": "kpk_kE49k3FhecfJBwutbshEEc",
+                      "rel_path": "tmp/openapi-example.md",
+                      "content_type": "text/markdown",
+                      "size_bytes": 50,
+                      "checksum": "a0775f9b3f392cd0560b21ad2f579ae4a5d6b1282b9eb145688ba2de717a816d",
+                      "updated_by": 2476444212131,
+                      "updated_at_ms": 1786458764961
+                    },
+                    "content_b64": "IyBPcGVuQVBJIGV4YW1wbGUKVGVtcCBmaWxlIGZvciBBUEkgZG9jcyBleGFtcGxlLgo=",
+                    "version": 135
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -56818,6 +58773,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -56825,91 +58783,92 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/KnowledgeFileGetRequest"
+              },
+              "example": {
+                "rel_path": "tmp/openapi-example.md"
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/knowledge/file/list": {
+      "post": {
+        "operationId": "knowledge-file-read-list",
+        "summary": "List knowledge files",
+        "description": "List knowledge files with metadata such as size and checksum.",
+        "tags": [
+          "AI SRE/Knowledge"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "Get knowledge file",
-        "tags": [
-          "AI SRE/Knowledge"
-        ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Content is returned in `content_b64` (base64); knowledge files are guaranteed UTF-8 text.\n- Omitting `pack_id` targets the account-scope knowledge; reading team-scope knowledge requires team membership.\n- A missing file returns `ResourceNotFound` (HTTP 400).\n",
-          "href": "/en/api-reference/ai-sre/knowledge/knowledge-file-read-get",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Omitting `pack_id` targets the caller's account knowledge (created empty if absent). An unknown `pack_id` returns `ResourceNotFound`.\n- Account knowledge is readable by every member; team knowledge only by members of that team.\n- `p`/`limit` are accepted but ignored: the response always contains every file. Use `POST /safari/knowledge/file/get` to read a file's content.\n",
+          "href": "/en/api-reference/ai-sre/knowledge/knowledge-file-read-list",
           "metadata": {
-            "sidebarTitle": "Get knowledge file"
+            "sidebarTitle": "List knowledge files"
           }
-        }
-      }
-    },
-    "/safari/knowledge/file/list": {
-      "post": {
-        "description": "List knowledge files with metadata such as size and checksum.",
-        "operationId": "knowledge-file-read-list",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "pack_id": "kpk_kE49k3FhecfJBwutbshEEc"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/KnowledgeFileListRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ResponseEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/KnowledgeFileListResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "files": [
                       {
-                        "checksum": "fccc276c0d7fbae2e9508285cdde0f8475169634e89e466dac2e59f176c9be2f",
-                        "content_type": "text/markdown",
                         "file_id": "kfl_QvT4g3c8zAHxTthuT6hGne",
                         "pack_id": "kpk_kE49k3FhecfJBwutbshEEc",
                         "rel_path": "aliyun.md",
+                        "content_type": "text/markdown",
                         "size_bytes": 1436,
-                        "updated_at_ms": 1783311304757,
-                        "updated_by": 3790925372131
+                        "checksum": "fccc276c0d7fbae2e9508285cdde0f8475169634e89e466dac2e59f176c9be2f",
+                        "updated_by": 3790925372131,
+                        "updated_at_ms": 1783311304757
                       },
                       {
-                        "checksum": "450eabf178b41e46ea2f43d395a80bf8b956ddb9c9cea34f44ffc69a53e7a36b",
-                        "content_type": "text/markdown",
                         "file_id": "kfl_BMsQZCZSqhW4TFskYNb4H5",
                         "pack_id": "kpk_kE49k3FhecfJBwutbshEEc",
                         "rel_path": "DUTY.md",
+                        "content_type": "text/markdown",
                         "size_bytes": 1301,
-                        "updated_at_ms": 1784800003394,
-                        "updated_by": 2476444212131
+                        "checksum": "450eabf178b41e46ea2f43d395a80bf8b956ddb9c9cea34f44ffc69a53e7a36b",
+                        "updated_by": 2476444212131,
+                        "updated_at_ms": 1784800003394
                       }
                     ],
-                    "total": 17
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/ResponseEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/KnowledgeFileListResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                    "total": 2,
+                    "version": 134
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -56917,6 +58876,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -56924,80 +58886,80 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/KnowledgeFileListRequest"
+              },
+              "example": {
+                "pack_id": "kpk_kE49k3FhecfJBwutbshEEc"
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/knowledge/file/put": {
+      "post": {
+        "operationId": "knowledge-file-write-put",
+        "summary": "Upload knowledge file",
+        "description": "Create or overwrite a knowledge file with base64-encoded content.",
+        "tags": [
+          "AI SRE/Knowledge"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "List knowledge files",
-        "tags": [
-          "AI SRE/Knowledge"
-        ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Omitting `pack_id` targets the caller's account-scope knowledge (created lazily if absent).\n- Reading team-scope knowledge requires membership of that team.\n- `p`/`limit` are accepted but the current implementation always returns the full file list.\n",
-          "href": "/en/api-reference/ai-sre/knowledge/knowledge-file-read-list",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Knowledge Manage** (`ai-sre`) |\n\n## Usage\n\n- The file body is sent as base64 text in `content_b64` — this is not a multipart upload. Writing an existing `rel_path` overwrites it.\n- Limits: each file at most 1 MiB (`DUTY.md` at most 32 KiB), at most 100 files and 5 MiB in total per knowledge. Content must be UTF-8 text without NUL bytes. Violations, as well as invalid `rel_path` values, return `InvalidParameter`.\n- Pass `expected_version` (from a previous read or write) to write only if nobody changed the knowledge since; on mismatch the call returns HTTP 200 with `status` = `conflict` and writes nothing.\n- Every successful write increases the knowledge `version` by 1; writing `DUTY.md` also updates `duty_version`.\n- Editing account knowledge requires the account owner or an admin; editing team knowledge requires membership of that team.\n- Every call is recorded in the account audit log.\n",
+          "href": "/en/api-reference/ai-sre/knowledge/knowledge-file-write-put",
           "metadata": {
-            "sidebarTitle": "List knowledge files"
+            "sidebarTitle": "Upload knowledge file"
           }
-        }
-      }
-    },
-    "/safari/knowledge/file/put": {
-      "post": {
-        "description": "Create or overwrite a knowledge file with base64-encoded content.",
-        "operationId": "knowledge-file-write-put",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "content_b64": "IyBPcGVuQVBJIGV4YW1wbGUKVGVtcCBmaWxlIGZvciBBUEkgZG9jcyBleGFtcGxlLgo=",
-                "content_type": "text/markdown",
-                "rel_path": "tmp/openapi-example.md"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/KnowledgeFilePutRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "file": {
-                      "checksum": "a0775f9b3f392cd0560b21ad2f579ae4a5d6b1282b9eb145688ba2de717a816d",
-                      "content_type": "text/markdown",
-                      "file_id": "kfl_gctXKRG45aFQGgxSFr59WY",
-                      "pack_id": "kpk_kE49k3FhecfJBwutbshEEc",
-                      "rel_path": "tmp/openapi-example.md",
-                      "size_bytes": 50,
-                      "updated_at_ms": 1786458764961,
-                      "updated_by": 2476444212131
-                    }
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/ResponseEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/KnowledgeFilePutResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "status": "ok",
+                    "file": {
+                      "file_id": "kfl_gctXKRG45aFQGgxSFr59WY",
+                      "pack_id": "kpk_kE49k3FhecfJBwutbshEEc",
+                      "rel_path": "tmp/openapi-example.md",
+                      "content_type": "text/markdown",
+                      "size_bytes": 50,
+                      "checksum": "a0775f9b3f392cd0560b21ad2f579ae4a5d6b1282b9eb145688ba2de717a816d",
+                      "updated_by": 2476444212131,
+                      "updated_at_ms": 1786458764961
+                    },
+                    "version": 135
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -57015,102 +58977,107 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/KnowledgeFilePutRequest"
+              },
+              "example": {
+                "rel_path": "tmp/openapi-example.md",
+                "content_b64": "IyBPcGVuQVBJIGV4YW1wbGUKVGVtcCBmaWxlIGZvciBBUEkgZG9jcyBleGFtcGxlLgo=",
+                "content_type": "text/markdown",
+                "expected_version": 134
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/knowledge/get": {
+      "post": {
+        "operationId": "knowledge-pack-read-get",
+        "summary": "Get account knowledge",
+        "description": "Return the metadata and file list of the account-scope knowledge.",
+        "tags": [
+          "AI SRE/Knowledge"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "Upload knowledge file",
-        "tags": [
-          "AI SRE/Knowledge"
-        ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Knowledge Manage** (`ai-sre`) |\n\n## Usage\n\n- The file body is sent as base64 text in the JSON field `content_b64` — this is not a multipart upload.\n- Writing an existing `rel_path` overwrites it; `content_type` is inferred from the extension when omitted (`.md` → `text/markdown`).\n- Content must decode to valid UTF-8 text; binary payloads are rejected with `InvalidParameter`.\n- Editing the account-scope knowledge requires account owner/admin; editing team knowledge requires team membership.\n- Every call is recorded in the account audit log.\n",
-          "href": "/en/api-reference/ai-sre/knowledge/knowledge-file-write-put",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Always targets the caller's account knowledge; there is no `pack_id` parameter. Use `POST /safari/knowledge/pack/list` to find team knowledge and `POST /safari/knowledge/file/list` to list its files.\n- If the account has no knowledge yet, an empty one is created on this call, so a valid account never gets not-found here.\n- Any member of the account can read it; `pack.can_edit` tells whether the caller may change it.\n",
+          "href": "/en/api-reference/ai-sre/knowledge/knowledge-pack-read-get",
           "metadata": {
-            "sidebarTitle": "Upload knowledge file"
+            "sidebarTitle": "Get account knowledge"
           }
-        }
-      }
-    },
-    "/safari/knowledge/get": {
-      "post": {
-        "description": "Return the metadata and file list of the account-scope knowledge.",
-        "operationId": "knowledge-pack-read-get",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {},
-              "schema": {
-                "$ref": "#/components/schemas/KnowledgeGetRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ResponseEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/KnowledgeGetResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
+                    "pack": {
+                      "pack_id": "kpk_kE49k3FhecfJBwutbshEEc",
+                      "account_id": 2451002751131,
+                      "scope": "account",
+                      "scope_id": 2451002751131,
+                      "file_count": 2,
+                      "total_bytes": 2737,
+                      "version": 134,
+                      "duty_version": 130,
+                      "created_by": 2476444212131,
+                      "created_at_ms": 1778768680053,
+                      "updated_at_ms": 1786456567177,
+                      "can_edit": true
+                    },
                     "files": [
                       {
-                        "checksum": "fccc276c0d7fbae2e9508285cdde0f8475169634e89e466dac2e59f176c9be2f",
-                        "content_type": "text/markdown",
                         "file_id": "kfl_QvT4g3c8zAHxTthuT6hGne",
                         "pack_id": "kpk_kE49k3FhecfJBwutbshEEc",
                         "rel_path": "aliyun.md",
+                        "content_type": "text/markdown",
                         "size_bytes": 1436,
-                        "updated_at_ms": 1783311304757,
-                        "updated_by": 3790925372131
+                        "checksum": "fccc276c0d7fbae2e9508285cdde0f8475169634e89e466dac2e59f176c9be2f",
+                        "updated_by": 3790925372131,
+                        "updated_at_ms": 1783311304757
                       },
                       {
-                        "checksum": "450eabf178b41e46ea2f43d395a80bf8b956ddb9c9cea34f44ffc69a53e7a36b",
-                        "content_type": "text/markdown",
                         "file_id": "kfl_BMsQZCZSqhW4TFskYNb4H5",
                         "pack_id": "kpk_kE49k3FhecfJBwutbshEEc",
                         "rel_path": "DUTY.md",
+                        "content_type": "text/markdown",
                         "size_bytes": 1301,
-                        "updated_at_ms": 1784800003394,
-                        "updated_by": 2476444212131
+                        "checksum": "450eabf178b41e46ea2f43d395a80bf8b956ddb9c9cea34f44ffc69a53e7a36b",
+                        "updated_by": 2476444212131,
+                        "updated_at_ms": 1784800003394
                       }
-                    ],
-                    "pack": {
-                      "account_id": 2451002751131,
-                      "can_edit": true,
-                      "created_at_ms": 1778768680053,
-                      "created_by": 2476444212131,
-                      "duty_version": 130,
-                      "file_count": 17,
-                      "pack_id": "kpk_kE49k3FhecfJBwutbshEEc",
-                      "scope": "account",
-                      "scope_id": 2451002751131,
-                      "total_bytes": 41010,
-                      "updated_at_ms": 1786456567177,
-                      "version": 134
-                    }
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/ResponseEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/KnowledgeGetResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                    ]
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -57118,6 +59085,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -57125,69 +59095,67 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/KnowledgeGetRequest"
+              },
+              "example": {}
+            }
+          }
+        }
+      }
+    },
+    "/safari/knowledge/pack/delete": {
+      "post": {
+        "operationId": "knowledge-pack-write-delete",
+        "summary": "Delete knowledge",
+        "description": "Delete knowledge and all of its files.",
+        "tags": [
+          "AI SRE/Knowledge"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "Get account knowledge",
-        "tags": [
-          "AI SRE/Knowledge"
-        ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Always targets the caller's account-scope knowledge — there is no `pack_id` parameter; use `POST /safari/knowledge/pack/list` to discover team knowledge.\n- The account knowledge is created lazily on first access, so a valid account never gets not-found here.\n",
-          "href": "/en/api-reference/ai-sre/knowledge/knowledge-pack-read-get",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Knowledge Manage** (`ai-sre`) |\n\n## Usage\n\n- Removes the knowledge and every file it contains; there is no API to restore it.\n- Requires `can_edit` on the knowledge: the account owner or an admin for account knowledge, membership of the team for team knowledge.\n- Deleting the account knowledge is allowed; the next `POST /safari/knowledge/get` (or file call without `pack_id`) creates a new empty one.\n- Every call is recorded in the account audit log.\n",
+          "href": "/en/api-reference/ai-sre/knowledge/knowledge-pack-write-delete",
           "metadata": {
-            "sidebarTitle": "Get account knowledge"
+            "sidebarTitle": "Delete knowledge"
           }
-        }
-      }
-    },
-    "/safari/knowledge/pack/delete": {
-      "post": {
-        "description": "Delete knowledge and all of its files.",
-        "operationId": "knowledge-pack-write-delete",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "pack_id": "kpk_YqHXPTEUHQFGepUfRS7vsh"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/KnowledgePackDeleteRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "ok": true
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/ResponseEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/KnowledgePackDeleteResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "ok": true
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -57205,81 +59173,81 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/KnowledgePackDeleteRequest"
+              },
+              "example": {
+                "pack_id": "kpk_YqHXPTEUHQFGepUfRS7vsh"
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/knowledge/pack/ensure": {
+      "post": {
+        "operationId": "knowledge-pack-write-ensure",
+        "summary": "Ensure knowledge",
+        "description": "Idempotently create the knowledge at the given scope, or return the existing one.",
+        "tags": [
+          "AI SRE/Knowledge"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "Delete knowledge",
-        "tags": [
-          "AI SRE/Knowledge"
-        ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Knowledge Manage** (`ai-sre`) |\n\n## Usage\n\n- Deleting knowledge removes every file it contains; the operation cannot be undone.\n- Deleting the account-scope knowledge is allowed; it is re-created empty on next access.\n- Every call is recorded in the account audit log.\n",
-          "href": "/en/api-reference/ai-sre/knowledge/knowledge-pack-write-delete",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Knowledge Manage** (`ai-sre`) |\n\n## Usage\n\n- Idempotent: if knowledge already exists at (`scope`, `scope_id`), it is returned; otherwise it is created empty.\n- For `account` scope, `scope_id` is ignored and a default `DUTY.md` is written whenever the knowledge has none (including after it was deleted). The returned `file_count`/`version` are read before that write and may not include it yet.\n- `account` scope requires the account owner or an admin; `team` scope requires membership of that team — owners and admins are not exempt.\n- Every call is recorded in the account audit log.\n",
+          "href": "/en/api-reference/ai-sre/knowledge/knowledge-pack-write-ensure",
           "metadata": {
-            "sidebarTitle": "Delete knowledge"
+            "sidebarTitle": "Ensure knowledge"
           }
-        }
-      }
-    },
-    "/safari/knowledge/pack/ensure": {
-      "post": {
-        "description": "Idempotently create the knowledge at the given scope, or return the existing one.",
-        "operationId": "knowledge-pack-write-ensure",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "scope": "team",
-                "scope_id": 2477033058131
-              },
-              "schema": {
-                "$ref": "#/components/schemas/KnowledgePackEnsureRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "account_id": 2451002751131,
-                    "can_edit": true,
-                    "created_at_ms": 1778768680053,
-                    "created_by": 2476444212131,
-                    "duty_version": 130,
-                    "file_count": 17,
-                    "pack_id": "kpk_kE49k3FhecfJBwutbshEEc",
-                    "scope": "account",
-                    "scope_id": 2451002751131,
-                    "total_bytes": 41010,
-                    "updated_at_ms": 1786458765182,
-                    "version": 138
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/ResponseEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/KnowledgePackItem"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "pack_id": "kpk_5qRL34nKtoWM4nQVT2kHzy",
+                    "account_id": 2451002751131,
+                    "scope": "team",
+                    "scope_id": 2477033058131,
+                    "team_name": "SRE Team",
+                    "file_count": 4,
+                    "total_bytes": 11159,
+                    "version": 15,
+                    "duty_version": 15,
+                    "created_by": 2476444212131,
+                    "created_at_ms": 1782201586089,
+                    "updated_at_ms": 1785462092702,
+                    "can_edit": true
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -57297,103 +59265,101 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/KnowledgePackEnsureRequest"
+              },
+              "example": {
+                "scope": "team",
+                "scope_id": 2477033058131
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/knowledge/pack/list": {
+      "post": {
+        "operationId": "knowledge-pack-read-list",
+        "summary": "List knowledge",
+        "description": "List the knowledge visible to the caller across account and team scopes.",
+        "tags": [
+          "AI SRE/Knowledge"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "Ensure knowledge",
-        "tags": [
-          "AI SRE/Knowledge"
-        ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Knowledge Manage** (`ai-sre`) |\n\n## Usage\n\n- Idempotent: if knowledge already exists at (`scope`, `scope_id`), it is returned unchanged.\n- For `account` scope, `scope_id` is ignored (the account ID is used) and a default `DUTY.md` is seeded on first creation.\n- Creating the account-scope knowledge requires account owner/admin; creating into a team requires membership of that team.\n- Every call is recorded in the account audit log.\n",
-          "href": "/en/api-reference/ai-sre/knowledge/knowledge-pack-write-ensure",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Returns the account knowledge plus the knowledge of teams the caller belongs to. This applies to every caller — owners and admins do not see knowledge of teams they have not joined.\n- The account knowledge appears only after it has been created (by `POST /safari/knowledge/get`, a file call without `pack_id`, or `POST /safari/knowledge/pack/ensure`); this endpoint does not create it.\n- `query` filters first, then `p`/`limit` page the filtered result; `total` is the count after filtering. Omit both `p` and `limit` to get everything.\n",
+          "href": "/en/api-reference/ai-sre/knowledge/knowledge-pack-read-list",
           "metadata": {
-            "sidebarTitle": "Ensure knowledge"
+            "sidebarTitle": "List knowledge"
           }
-        }
-      }
-    },
-    "/safari/knowledge/pack/list": {
-      "post": {
-        "description": "List the knowledge visible to the caller across account and team scopes.",
-        "operationId": "knowledge-pack-read-list",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "include_account": true,
-                "limit": 20,
-                "p": 1,
-                "scope": "all"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/KnowledgePackListRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ResponseEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/KnowledgePackListResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "packs": [
                       {
-                        "account_id": 2451002751131,
-                        "can_edit": true,
-                        "created_at_ms": 1778768680053,
-                        "created_by": 2476444212131,
-                        "duty_version": 130,
-                        "file_count": 17,
                         "pack_id": "kpk_kE49k3FhecfJBwutbshEEc",
+                        "account_id": 2451002751131,
                         "scope": "account",
                         "scope_id": 2451002751131,
-                        "total_bytes": 41010,
+                        "file_count": 2,
+                        "total_bytes": 2737,
+                        "version": 134,
+                        "duty_version": 130,
+                        "created_by": 2476444212131,
+                        "created_at_ms": 1778768680053,
                         "updated_at_ms": 1786456567177,
-                        "version": 134
+                        "can_edit": true
                       },
                       {
-                        "account_id": 2451002751131,
-                        "can_edit": true,
-                        "created_at_ms": 1782201586089,
-                        "created_by": 2476444212131,
-                        "duty_version": 15,
-                        "file_count": 4,
                         "pack_id": "kpk_5qRL34nKtoWM4nQVT2kHzy",
+                        "account_id": 2451002751131,
                         "scope": "team",
                         "scope_id": 2477033058131,
-                        "team_name": "研发团队",
+                        "team_name": "SRE Team",
+                        "file_count": 4,
                         "total_bytes": 11159,
+                        "version": 15,
+                        "duty_version": 15,
+                        "created_by": 2476444212131,
+                        "created_at_ms": 1782201586089,
                         "updated_at_ms": 1785462092702,
-                        "version": 15
+                        "can_edit": true
                       }
                     ],
-                    "total": 3
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/ResponseEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/KnowledgePackListResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                    "total": 2
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -57401,6 +59367,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -57408,83 +59377,84 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/KnowledgePackListRequest"
+              },
+              "example": {
+                "p": 1,
+                "limit": 20,
+                "scope": "all",
+                "include_account": true
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/knowledge/pack/update": {
+      "post": {
+        "operationId": "knowledge-pack-write-update",
+        "summary": "Update knowledge",
+        "description": "Move knowledge to a different account or team scope.",
+        "tags": [
+          "AI SRE/Knowledge"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "List knowledge",
-        "tags": [
-          "AI SRE/Knowledge"
-        ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Visibility matches the console: admins see the account knowledge plus every team's knowledge; non-admins see the account knowledge plus their own teams' knowledge, and requested `team_ids` are silently intersected with their teams.\n- `scope` selects `all` (default), `account`-only, or `team`-only, overriding `include_account`.\n- `query` applies a case-insensitive substring filter over knowledge ID, scope, and team name; `p`/`limit` paginate the filtered result.\n",
-          "href": "/en/api-reference/ai-sre/knowledge/knowledge-pack-read-list",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Knowledge Manage** (`ai-sre`) |\n\n## Usage\n\n- `scope` is the only mutable field; omitting it, or passing the knowledge's current scope, changes nothing and returns the current knowledge.\n- The caller must be able to edit the knowledge where it is now (`can_edit`) and must be allowed at the destination: a team the caller belongs to, or `account` for the owner and admins.\n- The move fails with `ReferenceExist` when the destination already has knowledge; knowledge is never merged. Files and `version` move with it unchanged.\n- Every call is recorded in the account audit log.\n",
+          "href": "/en/api-reference/ai-sre/knowledge/knowledge-pack-write-update",
           "metadata": {
-            "sidebarTitle": "List knowledge"
+            "sidebarTitle": "Update knowledge"
           }
-        }
-      }
-    },
-    "/safari/knowledge/pack/update": {
-      "post": {
-        "description": "Move knowledge to a different account or team scope.",
-        "operationId": "knowledge-pack-write-update",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "pack_id": "kpk_5qRL34nKtoWM4nQVT2kHzy",
-                "scope": "team",
-                "scope_id": 2477033058131
-              },
-              "schema": {
-                "$ref": "#/components/schemas/KnowledgePackUpdateRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "account_id": 2451002751131,
-                    "can_edit": true,
-                    "created_at_ms": 1782201586089,
-                    "created_by": 2476444212131,
-                    "duty_version": 15,
-                    "file_count": 4,
-                    "pack_id": "kpk_5qRL34nKtoWM4nQVT2kHzy",
-                    "scope": "team",
-                    "scope_id": 2477033058131,
-                    "team_name": "研发团队",
-                    "total_bytes": 11159,
-                    "updated_at_ms": 1785462092702,
-                    "version": 15
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/ResponseEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/KnowledgePackItem"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "pack_id": "kpk_5qRL34nKtoWM4nQVT2kHzy",
+                    "account_id": 2451002751131,
+                    "scope": "team",
+                    "scope_id": 2477033058131,
+                    "team_name": "SRE Team",
+                    "file_count": 4,
+                    "total_bytes": 11159,
+                    "version": 15,
+                    "duty_version": 15,
+                    "created_by": 2476444212131,
+                    "created_at_ms": 1782201586089,
+                    "updated_at_ms": 1785462092702,
+                    "can_edit": true
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -57502,88 +59472,89 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/KnowledgePackUpdateRequest"
+              },
+              "example": {
+                "pack_id": "kpk_5qRL34nKtoWM4nQVT2kHzy",
+                "scope": "team",
+                "scope_id": 2477033058131
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/mcp/server/create": {
+      "post": {
+        "operationId": "mcp-write-server-create",
+        "summary": "Create MCP server",
+        "description": "Register a new MCP server (connector) on the account.",
+        "tags": [
+          "AI SRE/MCP servers"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "Update knowledge",
-        "tags": [
-          "AI SRE/Knowledge"
-        ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Knowledge Manage** (`ai-sre`) |\n\n## Usage\n\n- `scope` is the only mutable field; omitting it is a no-op that returns the current knowledge.\n- For `team` scope, `scope_id` is required; for `account` scope it is set to the account ID automatically.\n- The move fails with `ReferenceExist` when the destination scope already has knowledge — knowledge is never merged.\n- Every call is recorded in the account audit log.\n",
-          "href": "/en/api-reference/ai-sre/knowledge/knowledge-pack-write-update",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **MCP Manage** (`ai-sre`) |\n\n## Usage\n\n- `command`/`args`/`env` apply to `stdio`; `url`/`headers` apply to `sse`/`streamable-http`.\n- `server_name` must start with a letter and contain only letters, digits, `-`, or `_`, and must be unique within its scope (account-wide or one team); violations return `InvalidParameter`.\n- Without `source_template_name`, creating into a team (`team_id > 0`) requires the caller to belong to that team, and only the account owner or an admin may create at account scope (`team_id=0`).\n- Setting `source_template_name` installs a marketplace template: the template must exist (`ResourceNotFound` otherwise), `team_id` is ignored and the server is created at account scope, and the connection fields must equal the template's own except for its declared parameter values. Templates with per-user auth whose parameters let the installer choose the destination host can be installed only by the account owner or an admin.\n- Each `environments` entry must be `cloud` or the ID of a BYOC runner that is account-scoped or belongs to one of the caller's teams; duplicates are dropped and an empty string is rejected. Omitted or empty means all environments.\n- `per_user_secret` auth mode requires `secret_schema` to be valid JSON with a non-empty `header_name`.\n- `env` and `headers` values are masked when the key name contains `KEY`, `SECRET`, `TOKEN`, `PASSWORD`, `PASSWD`, `CREDENTIAL`, or `AUTHORIZATION` (case-insensitive), or has a `PWD` / `PASS` segment, or the value is encrypted at rest; such values are also encrypted at rest.\n- The response is the stored server. Its tool list is then fetched in the background through an already-online execution environment; the call does not wait for it.\n- Every call is recorded in the account audit log.\n",
+          "href": "/en/api-reference/ai-sre/mcp-servers/mcp-write-server-create",
           "metadata": {
-            "sidebarTitle": "Update knowledge"
+            "sidebarTitle": "Create MCP server"
           }
-        }
-      }
-    },
-    "/safari/mcp/server/create": {
-      "post": {
-        "description": "Register a new MCP server (connector) on the account.",
-        "operationId": "mcp-write-server-create",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "description": "Query Prometheus metrics and alerts.",
-                "server_name": "prometheus",
-                "status": "enabled",
-                "transport": "streamable-http",
-                "url": "https://mcp.example.com/prometheus"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/MCPServerCreateRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "account_id": 10023,
-                    "auth_mode": "shared",
-                    "call_timeout": 60,
-                    "can_edit": true,
-                    "connect_timeout": 10,
-                    "created_at": 1716960000000,
-                    "created_by": 80011,
-                    "description": "Query Prometheus metrics and alerts.",
-                    "environments": [],
-                    "server_id": "mcp_4kP9wQ2nLceRtY7uVb3xA1",
-                    "server_name": "prometheus",
-                    "status": "enabled",
-                    "team_id": 0,
-                    "transport": "streamable-http",
-                    "updated_at": 1717046400000,
-                    "url": "https://mcp.example.com/prometheus"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/ResponseEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/MCPServerItem"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "server_id": "mcp_4kP9wQ2nLceRtY7uVb3xA1",
+                    "account_id": 10023,
+                    "team_id": 0,
+                    "can_edit": true,
+                    "environments": [],
+                    "server_name": "prometheus",
+                    "description": "Query Prometheus metrics and alerts.",
+                    "transport": "streamable-http",
+                    "url": "https://mcp.example.com/prometheus",
+                    "headers": {
+                      "Authorization": "Bear****f2c1"
+                    },
+                    "status": "enabled",
+                    "connect_timeout": 0,
+                    "call_timeout": 0,
+                    "auth_mode": "shared",
+                    "created_by": 80011,
+                    "created_at": 1716960000000,
+                    "updated_at": 1716960000000
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -57601,68 +59572,74 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/MCPServerCreateRequest"
+              },
+              "example": {
+                "server_name": "prometheus",
+                "description": "Query Prometheus metrics and alerts.",
+                "transport": "streamable-http",
+                "url": "https://mcp.example.com/prometheus",
+                "headers": {
+                  "Authorization": "Bearer example-token-f2c1"
+                },
+                "status": "enabled"
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/mcp/server/delete": {
+      "post": {
+        "operationId": "mcp-write-server-delete",
+        "summary": "Delete MCP server",
+        "description": "Delete an MCP server by ID.",
+        "tags": [
+          "AI SRE/MCP servers"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "Create MCP server",
-        "tags": [
-          "AI SRE/MCP servers"
-        ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **MCP Manage** (`ai-sre`) |\n\n## Usage\n\n- `command`/`args`/`env` apply to `stdio`; `url`/`headers` apply to `sse`/`streamable-http`.\n- Server name must start with a letter and contain only letters, digits, `-`, or `_`, and is unique within its scope (account-wide or one team), case-insensitive; violations return InvalidParameter.\n- `environments` restricts where the server can run: a list of `cloud` and/or BYOC runner environment IDs; omitted or empty means all environments.\n- `per_user_secret` auth mode requires `secret_schema` to be valid JSON with a non-empty `header_name`.\n- Every call is recorded in the account audit log.\n",
-          "href": "/en/api-reference/ai-sre/mcp-servers/mcp-write-server-create",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **MCP Manage** (`ai-sre`) |\n\n## Usage\n\n- Permanently removes the server and drops its cached tool list; it stops being offered to AI SRE sessions and its name can be reused.\n- Requires edit rights on the server's current team: an account-scoped server (`team_id=0`) can be changed only by the account owner or an admin, a team server only by members of that team (owners and admins included only if they belong to it).\n- Returns `ResourceNotFound` if the server does not exist.\n- Every call is recorded in the account audit log.\n",
+          "href": "/en/api-reference/ai-sre/mcp-servers/mcp-write-server-delete",
           "metadata": {
-            "sidebarTitle": "Create MCP server"
+            "sidebarTitle": "Delete MCP server"
           }
-        }
-      }
-    },
-    "/safari/mcp/server/delete": {
-      "post": {
-        "description": "Delete an MCP server by ID.",
-        "operationId": "mcp-write-server-delete",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "server_id": "mcp_4kP9wQ2nLceRtY7uVb3xA1"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/MCPServerDeleteRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": null,
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/ResponseEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "description": "Always null on success.",
-                          "type": "null"
+                          "type": "null",
+                          "description": "Not returned on success; the body carries only `request_id`."
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
-              }
-            },
-            "description": "Success"
+              }
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -57680,68 +59657,67 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/MCPServerDeleteRequest"
+              },
+              "example": {
+                "server_id": "mcp_4kP9wQ2nLceRtY7uVb3xA1"
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/mcp/server/disable": {
+      "post": {
+        "operationId": "mcp-write-server-disable",
+        "summary": "Disable MCP server",
+        "description": "Disable an enabled MCP server.",
+        "tags": [
+          "AI SRE/MCP servers"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "Delete MCP server",
-        "tags": [
-          "AI SRE/MCP servers"
-        ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **MCP Manage** (`ai-sre`) |\n\n## Usage\n\n- Every call is recorded in the account audit log.\n",
-          "href": "/en/api-reference/ai-sre/mcp-servers/mcp-write-server-delete",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **MCP Manage** (`ai-sre`) |\n\n## Usage\n\n- Returns `InvalidParameter` if the server is already disabled.\n- Requires edit rights on the server's current team: an account-scoped server (`team_id=0`) can be changed only by the account owner or an admin, a team server only by members of that team (owners and admins included only if they belong to it).\n- A disabled server's tools are no longer offered to AI SRE sessions; its configuration is kept.\n- Every call is recorded in the account audit log.\n",
+          "href": "/en/api-reference/ai-sre/mcp-servers/mcp-write-server-disable",
           "metadata": {
-            "sidebarTitle": "Delete MCP server"
+            "sidebarTitle": "Disable MCP server"
           }
-        }
-      }
-    },
-    "/safari/mcp/server/disable": {
-      "post": {
-        "description": "Disable an enabled MCP server.",
-        "operationId": "mcp-write-server-disable",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "server_id": "mcp_4kP9wQ2nLceRtY7uVb3xA1"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/MCPServerStatusRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": null,
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/ResponseEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "description": "Always null on success.",
-                          "type": "null"
+                          "type": "null",
+                          "description": "Not returned on success; the body carries only `request_id`."
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -57759,68 +59735,67 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/MCPServerStatusRequest"
+              },
+              "example": {
+                "server_id": "mcp_4kP9wQ2nLceRtY7uVb3xA1"
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/mcp/server/enable": {
+      "post": {
+        "operationId": "mcp-write-server-enable",
+        "summary": "Enable MCP server",
+        "description": "Enable a disabled MCP server.",
+        "tags": [
+          "AI SRE/MCP servers"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "Disable MCP server",
-        "tags": [
-          "AI SRE/MCP servers"
-        ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **MCP Manage** (`ai-sre`) |\n\n## Usage\n\n- Disabling an already-disabled server returns InvalidParameter instead of a silent no-op.\n- Requires edit permission on the server's current team: account-scope servers are owner/admin only; team-scope servers require the caller to belong to that team (or be owner/admin).\n- Every call is recorded in the account audit log.\n",
-          "href": "/en/api-reference/ai-sre/mcp-servers/mcp-write-server-disable",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **MCP Manage** (`ai-sre`) |\n\n## Usage\n\n- Returns `InvalidParameter` if the server is already enabled.\n- Requires edit rights on the server's current team: an account-scoped server (`team_id=0`) can be changed only by the account owner or an admin, a team server only by members of that team (owners and admins included only if they belong to it).\n- Once enabled, the server's tools are offered to AI SRE sessions again; the cached tool list is dropped and fetched again on next use.\n- Every call is recorded in the account audit log.\n",
+          "href": "/en/api-reference/ai-sre/mcp-servers/mcp-write-server-enable",
           "metadata": {
-            "sidebarTitle": "Disable MCP server"
+            "sidebarTitle": "Enable MCP server"
           }
-        }
-      }
-    },
-    "/safari/mcp/server/enable": {
-      "post": {
-        "description": "Enable a disabled MCP server.",
-        "operationId": "mcp-write-server-enable",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "server_id": "mcp_4kP9wQ2nLceRtY7uVb3xA1"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/MCPServerStatusRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": null,
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/ResponseEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "description": "Always null on success.",
-                          "type": "null"
+                          "type": "null",
+                          "description": "Not returned on success; the body carries only `request_id`."
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -57838,84 +59813,87 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/MCPServerStatusRequest"
+              },
+              "example": {
+                "server_id": "mcp_4kP9wQ2nLceRtY7uVb3xA1"
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/mcp/server/get": {
+      "post": {
+        "operationId": "mcp-read-server-get",
+        "summary": "Get MCP server detail",
+        "description": "Get one MCP server as a pure database read — no live probe is performed.",
+        "tags": [
+          "AI SRE/MCP servers"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "Enable MCP server",
-        "tags": [
-          "AI SRE/MCP servers"
-        ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **MCP Manage** (`ai-sre`) |\n\n## Usage\n\n- Enabling an already-enabled server returns InvalidParameter instead of a silent no-op.\n- Requires edit permission on the server's current team: account-scope servers are owner/admin only; team-scope servers require the caller to belong to that team (or be owner/admin).\n- Every call is recorded in the account audit log.\n",
-          "href": "/en/api-reference/ai-sre/mcp-servers/mcp-write-server-enable",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **60 requests/minute**; **3 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- A pure database read — it never probes the live server; the stored configuration and the cached `ai_description` are returned as-is.\n- `env` and `headers` values are masked when the key name contains `KEY`, `SECRET`, `TOKEN`, `PASSWORD`, `PASSWD`, `CREDENTIAL`, or `AUTHORIZATION` (case-insensitive), or has a `PWD` / `PASS` segment, or the value is encrypted at rest.\n- `test_error` and `tested_at` report the last connection test run from the console; they are omitted if the server has never been tested.\n- Returns `ResourceNotFound` if the server does not exist.\n",
+          "href": "/en/api-reference/ai-sre/mcp-servers/mcp-read-server-get",
           "metadata": {
-            "sidebarTitle": "Enable MCP server"
+            "sidebarTitle": "Get MCP server detail"
           }
-        }
-      }
-    },
-    "/safari/mcp/server/get": {
-      "post": {
-        "description": "Get one MCP server as a pure database read — no live probe is performed.",
-        "operationId": "mcp-read-server-get",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "server_id": "mcp_4kP9wQ2nLceRtY7uVb3xA1"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/MCPServerGetRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "account_id": 10023,
-                    "auth_mode": "shared",
-                    "call_timeout": 60,
-                    "can_edit": true,
-                    "connect_timeout": 10,
-                    "created_at": 1716960000000,
-                    "created_by": 80011,
-                    "description": "Query Prometheus metrics and alerts.",
-                    "environments": [],
-                    "server_id": "mcp_4kP9wQ2nLceRtY7uVb3xA1",
-                    "server_name": "prometheus",
-                    "status": "enabled",
-                    "team_id": 0,
-                    "transport": "streamable-http",
-                    "updated_at": 1717046400000,
-                    "url": "https://mcp.example.com/prometheus"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/ResponseEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/MCPServerItem"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "server_id": "mcp_4kP9wQ2nLceRtY7uVb3xA1",
+                    "account_id": 10023,
+                    "team_id": 0,
+                    "can_edit": true,
+                    "environments": [],
+                    "server_name": "prometheus",
+                    "description": "Query Prometheus metrics and alerts.",
+                    "transport": "streamable-http",
+                    "url": "https://mcp.example.com/prometheus",
+                    "headers": {
+                      "Authorization": "Bear****f2c1"
+                    },
+                    "status": "enabled",
+                    "connect_timeout": 0,
+                    "call_timeout": 0,
+                    "auth_mode": "shared",
+                    "created_by": 80011,
+                    "created_at": 1716960000000,
+                    "updated_at": 1717046400000
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -57923,6 +59901,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -57930,91 +59911,92 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/MCPServerGetRequest"
+              },
+              "example": {
+                "server_id": "mcp_4kP9wQ2nLceRtY7uVb3xA1"
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/mcp/server/list": {
+      "post": {
+        "operationId": "mcp-read-server-list",
+        "summary": "List MCP servers",
+        "description": "List MCP servers visible to the caller across account and team scopes, with pagination.",
+        "tags": [
+          "AI SRE/MCP servers"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "Get MCP server detail",
-        "tags": [
-          "AI SRE/MCP servers"
-        ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- A pure database read — it never probes the live server; the stored configuration (with secrets masked) and the cached `ai_description` are returned as-is.\n",
-          "href": "/en/api-reference/ai-sre/mcp-servers/mcp-read-server-get",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Pagination uses `p`/`limit`: `p` below 1 is treated as 1 and `limit` below 1 as 20. Results are ordered by name, then server ID, ascending.\n- Visibility follows real team membership for every caller, owner and admins included: account-scoped rows plus rows of teams the caller belongs to; `team_ids` entries outside that set are ignored.\n- `scope=account` returns only account-scoped rows; `scope=team` returns only team rows; `all` (default) returns team rows plus account-scoped rows unless `include_account=false`.\n- `query` performs a case-insensitive substring search across name, description, AI-generated description, server ID, transport, URL, command, and source template name.\n- The response never includes a live tool list; `can_edit` on each row tells whether the caller may change that server.\n",
+          "href": "/en/api-reference/ai-sre/mcp-servers/mcp-read-server-list",
           "metadata": {
-            "sidebarTitle": "Get MCP server detail"
+            "sidebarTitle": "List MCP servers"
           }
-        }
-      }
-    },
-    "/safari/mcp/server/list": {
-      "post": {
-        "description": "List MCP servers visible to the caller across account and team scopes, with pagination.",
-        "operationId": "mcp-read-server-list",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "include_account": true,
-                "limit": 20,
-                "p": 1
-              },
-              "schema": {
-                "$ref": "#/components/schemas/MCPServerListRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "servers": [
-                      {
-                        "account_id": 10023,
-                        "auth_mode": "shared",
-                        "call_timeout": 60,
-                        "can_edit": true,
-                        "connect_timeout": 10,
-                        "created_at": 1716960000000,
-                        "created_by": 80011,
-                        "description": "Query Prometheus metrics and alerts.",
-                        "environments": [],
-                        "server_id": "mcp_4kP9wQ2nLceRtY7uVb3xA1",
-                        "server_name": "prometheus",
-                        "status": "enabled",
-                        "team_id": 0,
-                        "transport": "streamable-http",
-                        "updated_at": 1717046400000,
-                        "url": "https://mcp.example.com/prometheus"
-                      }
-                    ],
-                    "total": 1
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/ResponseEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/MCPServerListResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "total": 1,
+                    "servers": [
+                      {
+                        "server_id": "mcp_4kP9wQ2nLceRtY7uVb3xA1",
+                        "account_id": 10023,
+                        "team_id": 0,
+                        "can_edit": true,
+                        "environments": [],
+                        "server_name": "prometheus",
+                        "description": "Query Prometheus metrics and alerts.",
+                        "transport": "streamable-http",
+                        "url": "https://mcp.example.com/prometheus",
+                        "headers": {
+                          "Authorization": "Bear****f2c1"
+                        },
+                        "status": "enabled",
+                        "connect_timeout": 0,
+                        "call_timeout": 0,
+                        "auth_mode": "shared",
+                        "created_by": 80011,
+                        "created_at": 1716960000000,
+                        "updated_at": 1717046400000
+                      }
+                    ]
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -58022,6 +60004,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -58029,85 +60014,89 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/MCPServerListRequest"
+              },
+              "example": {
+                "p": 1,
+                "limit": 20,
+                "include_account": true
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/mcp/server/update": {
+      "post": {
+        "operationId": "mcp-write-server-update",
+        "summary": "Update MCP server",
+        "description": "Update an MCP server's configuration. Omit a field to leave it unchanged.",
+        "tags": [
+          "AI SRE/MCP servers"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "List MCP servers",
-        "tags": [
-          "AI SRE/MCP servers"
-        ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- The response never includes a live tool list; tools are probed asynchronously on create/update and cached for runtime use.\n- `query` performs a case-insensitive substring search across name, description, AI-generated description, server ID, transport, URL, command, and source template name.\n",
-          "href": "/en/api-reference/ai-sre/mcp-servers/mcp-read-server-list",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **MCP Manage** (`ai-sre`) |\n\n## Usage\n\n- Requires edit rights on the server's current team: an account-scoped server (`team_id=0`) can be changed only by the account owner or an admin, a team server only by members of that team (owners and admins included only if they belong to it).\n- `server_name`, `description`, `transport`, `command`, `url`, and `auth_mode` change only when non-empty, and `connect_timeout` / `call_timeout` only when non-zero, so these cannot be cleared through this endpoint.\n- `args`, `env`, and `headers` replace the whole value when sent: a key left out of `env`/`headers` is removed. For a protected `env`/`headers` key, sending the masked value or an empty string keeps the stored secret.\n- When `auth_mode` is sent, `secret_schema` is overwritten with the value sent alongside it (empty if omitted). `oauth_metadata` is cleared when `auth_mode` or `url` actually changes, unless a non-empty `oauth_metadata` is sent.\n- Moving to another team (`team_id > 0`) requires membership in the destination team and is refused for servers installed from the marketplace; moving to account scope (`team_id=0`) requires the account owner or an admin. If `environments` is not sent with a team change, the current runner entries must still be selectable by the caller or the update is rejected.\n- `environments`: omit (or `null`) to leave unchanged; send a list to replace it — an empty list clears the restriction back to all environments.\n- The response is the updated server. If a connection field changed, the cached tool list is dropped and fetched again in the background.\n- Every call is recorded in the account audit log.\n",
+          "href": "/en/api-reference/ai-sre/mcp-servers/mcp-write-server-update",
           "metadata": {
-            "sidebarTitle": "List MCP servers"
+            "sidebarTitle": "Update MCP server"
           }
-        }
-      }
-    },
-    "/safari/mcp/server/update": {
-      "post": {
-        "description": "Update an MCP server's configuration. Omit a field to leave it unchanged.",
-        "operationId": "mcp-write-server-update",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "description": "Query Prometheus metrics, alerts, and rules.",
-                "server_id": "mcp_4kP9wQ2nLceRtY7uVb3xA1"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/MCPServerUpdateRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "account_id": 10023,
-                    "auth_mode": "shared",
-                    "call_timeout": 60,
-                    "can_edit": true,
-                    "connect_timeout": 10,
-                    "created_at": 1716960000000,
-                    "created_by": 80011,
-                    "description": "Query Prometheus metrics, alerts, and rules.",
-                    "environments": [],
-                    "server_id": "mcp_4kP9wQ2nLceRtY7uVb3xA1",
-                    "server_name": "prometheus",
-                    "status": "enabled",
-                    "team_id": 0,
-                    "transport": "streamable-http",
-                    "updated_at": 1717046400000,
-                    "url": "https://mcp.example.com/prometheus"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/ResponseEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/MCPServerItem"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "server_id": "mcp_4kP9wQ2nLceRtY7uVb3xA1",
+                    "account_id": 10023,
+                    "team_id": 0,
+                    "can_edit": true,
+                    "environments": [],
+                    "server_name": "prometheus",
+                    "description": "Query Prometheus metrics, alerts, and rules.",
+                    "transport": "streamable-http",
+                    "url": "https://mcp.example.com/prometheus",
+                    "headers": {
+                      "Authorization": "Bear****f2c1"
+                    },
+                    "status": "enabled",
+                    "connect_timeout": 0,
+                    "call_timeout": 0,
+                    "auth_mode": "shared",
+                    "created_by": 80011,
+                    "created_at": 1716960000000,
+                    "updated_at": 1717046400000
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -58125,68 +60114,68 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/MCPServerUpdateRequest"
+              },
+              "example": {
+                "server_id": "mcp_4kP9wQ2nLceRtY7uVb3xA1",
+                "description": "Query Prometheus metrics, alerts, and rules."
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/session/delete": {
+      "post": {
+        "operationId": "session-write-delete",
+        "summary": "Delete session",
+        "description": "Soft-delete a session together with its subagent sessions and the files it presented.",
+        "tags": [
+          "AI SRE/Sessions"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "Update MCP server",
-        "tags": [
-          "AI SRE/MCP servers"
-        ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **MCP Manage** (`ai-sre`) |\n\n## Usage\n\n- Masked secret values in `env`/`headers` are preserved — sending the masked value back does not overwrite the stored secret.\n- `environments` is a tri-state partial-update field: omit (null) to leave it unchanged; send a list to set it — an empty list clears the restriction back to all environments.\n- Changing `team_id` requires reassignment permission on the destination team; if `environments` is left unchanged, the current environments must still be selectable by the caller under the new team or the update is rejected.\n- Every call is recorded in the account audit log.\n",
-          "href": "/en/api-reference/ai-sre/mcp-servers/mcp-write-server-update",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Requires manage rights on the session: a personal session (`team_id` = 0) can be deleted only by its creator; a team session by its creator or a member of the owning team. Account owners and admins get no exemption; anyone else receives `AccessDenied`.\n- An unknown or already-deleted `session_id` returns `ResourceNotFound`.\n- Background processes the session still runs (background shell commands, monitors) are stopped first on a best-effort basis; a failed stop does not block the delete.\n- Child subagent sessions and the files the session presented are deleted in the same transaction; the stored file contents are removed afterwards on a best-effort basis.\n",
+          "href": "/en/api-reference/ai-sre/sessions/session-write-delete",
           "metadata": {
-            "sidebarTitle": "Update MCP server"
+            "sidebarTitle": "Delete session"
           }
-        }
-      }
-    },
-    "/safari/session/delete": {
-      "post": {
-        "description": "Delete a session by ID.",
-        "operationId": "session-write-delete",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "session_id": "sess_f8oDvqiG64uur6sBNsTc4u"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/SessionDeleteRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": null,
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/ResponseEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "description": "Always null on success.",
-                          "type": "null"
+                          "type": "null",
+                          "description": "Not returned on success; the body carries only `request_id`."
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -58204,53 +60193,52 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/SessionDeleteRequest"
+              },
+              "example": {
+                "session_id": "sess_f8oDvqiG64uur6sBNsTc4u"
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/session/export": {
+      "post": {
+        "operationId": "session-read-export",
+        "summary": "Export session transcript",
+        "description": "Stream a session's full event transcript as newline-delimited JSON.",
+        "tags": [
+          "AI SRE/Sessions"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "Delete session",
-        "tags": [
-          "AI SRE/Sessions"
-        ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Personal sessions can be deleted only by their creator; team sessions can be deleted by the creator, an account admin, or a member of the owning team.\n- This is a soft delete: it also cascades to delete child subagent sessions and any presented files; the underlying S3/MinIO blobs are removed best-effort after the transaction commits, so an orphaned blob is possible on partial failure.\n",
-          "href": "/en/api-reference/ai-sre/sessions/session-write-delete",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/day**; **200 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- A personal session can be exported only by its creator; a team session by any member of the same account. Share links do not grant export. Missing or deleted sessions return `ResourceNotFound`.\n- The response is `application/x-ndjson` — parse it line by line and write it to a file instead of buffering the whole body.\n- The first line is always a `session_meta` object. Following lines carry a `type` of `user_message`, `system_reminder`, `agent_text`, `tool_call`, `subagent_dispatch`, `llm_call`, `final_answer`, or `session_fork`.\n- With `include_subagents=true`, each `subagent_dispatch` line is followed by the child session's own stream, starting with its own `session_meta`.\n- The request times out after 60 seconds; a very large session may not finish exporting within that window.\n- If export fails after streaming has started, the body ends with a `{\"type\":\"error\",\"content\":\"...\"}` line instead of an error envelope — check the last line to detect truncation.\n",
+          "href": "/en/api-reference/ai-sre/sessions/session-read-export",
           "metadata": {
-            "sidebarTitle": "Delete session"
+            "sidebarTitle": "Export session transcript"
           }
-        }
-      }
-    },
-    "/safari/session/export": {
-      "post": {
-        "description": "Stream a session's full event transcript as newline-delimited JSON.",
-        "operationId": "session-read-export",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "include_subagents": false,
-                "session_id": "sess_f8oDvqiG64uur6sBNsTc4u"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/SessionExportRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "Streaming NDJSON (application/x-ndjson). One JSON object per line, terminated by a newline. The first line is always a `session_meta` envelope; subsequent lines are session events.",
             "content": {
               "application/x-ndjson": {
                 "schema": {
-                  "description": "Newline-delimited JSON stream. Parse line-by-line; do not buffer the whole body.",
-                  "type": "string"
+                  "type": "string",
+                  "description": "Newline-delimited JSON stream. Parse line-by-line; do not buffer the whole body."
                 }
               }
-            },
-            "description": "Streaming NDJSON (application/x-ndjson). One JSON object per line, terminated by a newline. The first line is always a `session_meta` envelope; subsequent lines are session events."
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -58268,138 +60256,139 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/SessionExportRequest"
+              },
+              "example": {
+                "session_id": "sess_f8oDvqiG64uur6sBNsTc4u",
+                "include_subagents": false
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/session/get": {
+      "post": {
+        "operationId": "session-read-info",
+        "summary": "Get session detail",
+        "description": "Fetch one session plus a backward-paged window of its most recent events.",
+        "tags": [
+          "AI SRE/Sessions"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "Export session transcript",
-        "tags": [
-          "AI SRE/Sessions"
-        ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/day**; **200 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Personal sessions are exportable only by their creator; team sessions can be exported by same-account callers with the `session_id`.\n- The response is `application/x-ndjson` — parse line-by-line and write to a file; do not buffer the whole body in memory.\n- The first line is always a `session_meta` envelope; `include_subagents=true` inlines each child session's stream after its dispatch line.\n- Requests are capped at a 60-second execution timeout; very large sessions may not finish exporting within that window.\n- If the stream fails partway through, the response ends with a JSON error line instead of a proper error envelope (headers are already sent) — check for this trailing line to detect truncation.\n",
-          "href": "/en/api-reference/ai-sre/sessions/session-read-export",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- A personal session is readable only by its creator, or by anyone holding a valid `share_token` (view only). A team session is readable by any member of the same account. A missing, deleted, or unreadable session returns `ResourceNotFound`.\n- `events` holds the newest page in ascending order. To read older history, pass the returned `search_after_ctx` back; a malformed cursor returns `InvalidParameter`.\n- Page size is `limit`, else `num_recent_events`, else 100 (max 1000). Internal control events are left out, so a page can hold fewer events than requested.\n- The `current_turn_*` fields are filled only while `is_running` is true. `has_unread` is always `false` and `pinned_at` always `0` here; use `POST /safari/session/list` for those.\n- `pending_messages` lists messages queued behind the running turn; it is an empty array when nothing is queued.\n",
+          "href": "/en/api-reference/ai-sre/sessions/session-read-info",
           "metadata": {
-            "sidebarTitle": "Export session transcript"
+            "sidebarTitle": "Get session detail"
           }
-        }
-      }
-    },
-    "/safari/session/get": {
-      "post": {
-        "description": "Fetch one session plus a backward-paged window of its most recent events.",
-        "operationId": "session-read-info",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "num_recent_events": 50,
-                "session_id": "sess_f8oDvqiG64uur6sBNsTc4u"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/SessionGetRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ResponseEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/SessionGetResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
+                    "session": {
+                      "session_id": "sess_f8oDvqiG64uur6sBNsTc4u",
+                      "session_name": "Investigate cloud-assistant first heartbeat",
+                      "app_name": "ai-sre",
+                      "entry_kind": "web",
+                      "person_id": "3790925372131",
+                      "team_id": 0,
+                      "is_mine": true,
+                      "can_view": true,
+                      "can_continue": true,
+                      "can_manage": true,
+                      "can_fork": true,
+                      "access_source": "owner",
+                      "share_enabled": true,
+                      "share_version": 3,
+                      "shared_at": 1780367971000,
+                      "shared_by": 3790925372131,
+                      "status": "enabled",
+                      "incognito": false,
+                      "created_at": 1780367971228,
+                      "updated_at": 1780367993457,
+                      "token_usage": {
+                        "input_tokens": 14948,
+                        "cached_tokens": 11520,
+                        "output_tokens": 888,
+                        "reasoning_tokens": 351
+                      },
+                      "current_context_tokens": 14948,
+                      "context_window": 131072,
+                      "archived_at": 0,
+                      "pinned_at": 0,
+                      "last_event_at": 1780367992649,
+                      "is_running": false,
+                      "standing_tasks": 0,
+                      "has_unread": false,
+                      "current_turn_started_at": 1780367971241,
+                      "current_turn_active_ms": 21408,
+                      "current_turn_wait_ms": 0,
+                      "current_turn_tokens": 0
+                    },
                     "events": [
                       {
-                        "author": "user",
-                        "created_at": 1780367971241,
                         "event_id": "evt_3aZQ9p",
-                        "partial": false,
                         "session_id": "sess_f8oDvqiG64uur6sBNsTc4u",
+                        "author": "user",
+                        "partial": false,
+                        "turn_complete": false,
                         "status": "normal",
-                        "turn_complete": false
+                        "created_at": 1780367971241
                       },
                       {
+                        "event_id": "evt_7bWk2r",
+                        "session_id": "sess_f8oDvqiG64uur6sBNsTc4u",
                         "author": "ai-sre",
                         "content": {
+                          "role": "model",
                           "parts": [
                             {
                               "text": "..."
                             }
-                          ],
-                          "role": "model"
+                          ]
                         },
-                        "created_at": 1780367992649,
-                        "event_id": "evt_7bWk2r",
                         "partial": false,
-                        "session_id": "sess_f8oDvqiG64uur6sBNsTc4u",
+                        "turn_complete": true,
                         "status": "normal",
-                        "turn_complete": true
+                        "created_at": 1780367992649
                       }
                     ],
                     "has_more_older": false,
-                    "session": {
-                      "access_source": "manager",
-                      "app_name": "ai-sre",
-                      "archived_at": 0,
-                      "can_continue": true,
-                      "can_fork": true,
-                      "can_manage": true,
-                      "can_view": true,
-                      "context_window": 0,
-                      "created_at": 1780367971228,
-                      "current_context_tokens": 14948,
-                      "current_turn_active_ms": 0,
-                      "current_turn_started_at": 0,
-                      "current_turn_tokens": 0,
-                      "current_turn_wait_ms": 0,
-                      "entry_kind": "web",
-                      "has_unread": true,
-                      "incognito": false,
-                      "is_mine": false,
-                      "is_running": false,
-                      "last_event_at": 1780367992649,
-                      "person_id": "3790925372131",
-                      "pinned_at": 0,
-                      "session_id": "sess_f8oDvqiG64uur6sBNsTc4u",
-                      "session_name": "Investigate cloud-assistant first heartbeat",
-                      "share_enabled": true,
-                      "share_version": 3,
-                      "shared_at": 1780367971000,
-                      "shared_by": 3790925372131,
-                      "status": "enabled",
-                      "team_id": 0,
-                      "token_usage": {
-                        "cached_tokens": 11520,
-                        "input_tokens": 14948,
-                        "output_tokens": 888,
-                        "reasoning_tokens": 351
-                      },
-                      "updated_at": 1780367993457
-                    },
-                    "suggest_init": false
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/ResponseEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/SessionGetResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                    "pending_messages": []
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -58417,114 +60406,113 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/SessionGetRequest"
+              },
+              "example": {
+                "session_id": "sess_f8oDvqiG64uur6sBNsTc4u",
+                "num_recent_events": 50
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/session/list": {
+      "post": {
+        "operationId": "session-read-list",
+        "summary": "List sessions",
+        "description": "List agent sessions visible to the caller, filtered by app, entry surface, archive status, and team.",
+        "tags": [
+          "AI SRE/Sessions"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "Get session detail",
-        "tags": [
-          "AI SRE/Sessions"
-        ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Personal sessions are readable only by their creator; team sessions can be read by same-account callers with the `session_id`.\n- Page older history with `search_after_ctx` from the previous response.\n- `limit` (or legacy `num_recent_events`) caps the event page; default 100, max 1000.\n- A malformed `search_after_ctx` returns 400 immediately, before any DB work.\n- `current_turn_*` fields are populated only while the session `is_running`; `suggest_init` is the same account-wide onboarding flag as `session/list`.\n",
-          "href": "/en/api-reference/ai-sre/sessions/session-read-info",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Pagination uses `p`/`limit` (default 20, max 100). The caller's pinned sessions that match the filters are prepended on page 1 in addition to `limit` rows, never appear on later pages, and are not counted in `total`.\n- `scope=all` returns sessions the caller created plus sessions bound to teams the caller belongs to. Membership is real team membership for every role; account owners and admins do not see other teams' sessions here.\n- `team_ids`, `person_ids`, and `entry_kinds` only narrow the visible set. Incognito sessions are never listed; subagent sessions appear only with `include_subagent_sessions=true`.\n- For `app_name=ai-sre` the calling member must hold an AI SRE license seat; otherwise the request fails with a no-license error.\n- `creator_name`, `has_unread`, and `pinned_at` are computed per caller. The `current_turn_*` fields and `context_window` are always `0`, and `state`, `bound_environment`, `context_resolved`, `automation`, and `has_open_tasks` are not returned; use `POST /safari/session/get` for them.\n",
+          "href": "/en/api-reference/ai-sre/sessions/session-read-list",
           "metadata": {
-            "sidebarTitle": "Get session detail"
+            "sidebarTitle": "List sessions"
           }
-        }
-      }
-    },
-    "/safari/session/list": {
-      "post": {
-        "description": "List agent sessions visible to the caller, filtered by app, surface, archive status, and team.",
-        "operationId": "session-read-list",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "app_name": "ai-sre",
-                "limit": 2,
-                "orderby": "updated_at",
-                "scope": "all"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/SessionListRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ResponseEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/SessionListResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
+                    "total": 988,
                     "sessions": [
                       {
-                        "access_source": "manager",
+                        "session_id": "sess_f8oDvqiG64uur6sBNsTc4u",
+                        "session_name": "Investigate cloud-assistant first heartbeat",
                         "app_name": "ai-sre",
-                        "archived_at": 0,
-                        "can_continue": true,
-                        "can_fork": true,
-                        "can_manage": true,
-                        "can_view": true,
-                        "context_window": 0,
-                        "created_at": 1780367971228,
-                        "current_context_tokens": 14948,
-                        "current_turn_active_ms": 0,
-                        "current_turn_started_at": 0,
-                        "current_turn_tokens": 0,
-                        "current_turn_wait_ms": 0,
                         "entry_kind": "web",
-                        "has_unread": true,
-                        "incognito": false,
-                        "is_mine": false,
-                        "is_running": false,
-                        "last_event_at": 1780367992649,
                         "person_id": "3790925372131",
-                        "pinned_at": 0,
-                        "session_id": "sess_f8oDvqiG64uur6sBNsTc4u",
-                        "session_name": "Investigate cloud-assistant first heartbeat",
+                        "creator_name": "Alice Chen",
+                        "team_id": 0,
+                        "is_mine": true,
+                        "can_view": true,
+                        "can_continue": true,
+                        "can_manage": true,
+                        "can_fork": true,
+                        "access_source": "owner",
                         "share_enabled": true,
                         "share_version": 3,
                         "shared_at": 1780367971000,
                         "shared_by": 3790925372131,
                         "status": "enabled",
-                        "team_id": 0,
+                        "incognito": false,
+                        "created_at": 1780367971228,
+                        "updated_at": 1780367993457,
                         "token_usage": {
-                          "cached_tokens": 11520,
                           "input_tokens": 14948,
+                          "cached_tokens": 11520,
                           "output_tokens": 888,
                           "reasoning_tokens": 351
                         },
-                        "updated_at": 1780367993457
+                        "current_context_tokens": 14948,
+                        "context_window": 0,
+                        "archived_at": 0,
+                        "pinned_at": 0,
+                        "last_event_at": 1780367992649,
+                        "is_running": false,
+                        "standing_tasks": 0,
+                        "has_unread": true,
+                        "current_turn_started_at": 0,
+                        "current_turn_active_ms": 0,
+                        "current_turn_wait_ms": 0,
+                        "current_turn_tokens": 0
                       }
-                    ],
-                    "suggest_init": false,
-                    "total": 988
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/ResponseEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/SessionListResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                    ]
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -58542,68 +60530,70 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/SessionListRequest"
+              },
+              "example": {
+                "app_name": "ai-sre",
+                "limit": 2,
+                "orderby": "updated_at",
+                "scope": "all"
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/skill/delete": {
+      "post": {
+        "operationId": "skill-write-delete",
+        "summary": "Delete skill",
+        "description": "Soft-delete a skill so agents stop loading it and its name can be reused.",
+        "tags": [
+          "AI SRE/Skills"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "List sessions",
-        "tags": [
-          "AI SRE/Sessions"
-        ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Pagination uses `p`/`limit` (max 100); `scope` defaults to `all`.\n- `all` returns your personal sessions plus team sessions you can access; account admins see all team sessions, but not other users' personal sessions.\n- `team_ids` narrows the visible set and never expands access.\n- `is_running` reflects the live run-set; `has_unread` is computed per calling user; the `current_turn_*` fields are always zero here — only `session/get` computes them while a session is running.\n- `suggest_init` is an account-wide onboarding flag (true only when the account has no knowledge in any scope) — it doesn't depend on the list filters.\n",
-          "href": "/en/api-reference/ai-sre/sessions/session-read-list",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Skill Manage** (`ai-sre`) |\n\n## Usage\n\n- Requires edit rights on the skill: account-scope skills (`team_id` = 0) are editable by account owners and admins; team skills only by members of that team (no owner or admin exemption). Otherwise the call returns `AccessDenied`.\n- Soft delete: the skill is renamed and hidden from every endpoint, freeing its name in its scope for reuse; the stored archive is not removed.\n- An unknown or already-deleted `skill_id` returns `ResourceNotFound`.\n- Every call is recorded in the account audit log.\n",
+          "href": "/en/api-reference/ai-sre/skills/skill-write-delete",
           "metadata": {
-            "sidebarTitle": "List sessions"
+            "sidebarTitle": "Delete skill"
           }
-        }
-      }
-    },
-    "/safari/skill/delete": {
-      "post": {
-        "description": "Delete a skill by ID.",
-        "operationId": "skill-write-delete",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "skill_id": "skill_8s7Hn2kLpQ3xYbVc4Wd2m"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/SkillDeleteRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": null,
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/ResponseEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "description": "Always null on success.",
-                          "type": "null"
+                          "type": "null",
+                          "description": "Not returned on success; the body carries only `request_id`."
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -58621,68 +60611,67 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/SkillDeleteRequest"
+              },
+              "example": {
+                "skill_id": "skill_8s7Hn2kLpQ3xYbVc4Wd2m"
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/skill/disable": {
+      "post": {
+        "operationId": "skill-write-disable",
+        "summary": "Disable skill",
+        "description": "Disable an enabled skill so the agent stops loading it.",
+        "tags": [
+          "AI SRE/Skills"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "Delete skill",
-        "tags": [
-          "AI SRE/Skills"
-        ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Skill Manage** (`ai-sre`) |\n\n## Usage\n\n- Soft delete only: sets `status` to `deleted` and renames the row to free its name for reuse; the skill's zip archive is not removed from object storage.\n- Deleting an already-deleted or nonexistent `skill_id` returns `ResourceNotFound`, since the lookup excludes deleted rows before the delete itself runs.\n- Every call is recorded in the account audit log.\n",
-          "href": "/en/api-reference/ai-sre/skills/skill-write-delete",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Skill Manage** (`ai-sre`) |\n\n## Usage\n\n- Requires edit rights on the skill: account-scope skills (`team_id` = 0) are editable by account owners and admins; team skills only by members of that team (no owner or admin exemption). Otherwise the call returns `AccessDenied`.\n- Only an `enabled` skill can be disabled; disabling an already-disabled skill returns `InvalidParameter`.\n- Every call is recorded in the account audit log.\n",
+          "href": "/en/api-reference/ai-sre/skills/skill-write-disable",
           "metadata": {
-            "sidebarTitle": "Delete skill"
+            "sidebarTitle": "Disable skill"
           }
-        }
-      }
-    },
-    "/safari/skill/disable": {
-      "post": {
-        "description": "Disable an enabled skill so the agent stops loading it.",
-        "operationId": "skill-write-disable",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "skill_id": "skill_8s7Hn2kLpQ3xYbVc4Wd2m"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/SkillStatusRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": null,
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/ResponseEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "description": "Always null on success.",
-                          "type": "null"
+                          "type": "null",
+                          "description": "Not returned on success; the body carries only `request_id`."
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -58700,68 +60689,67 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/SkillStatusRequest"
+              },
+              "example": {
+                "skill_id": "skill_8s7Hn2kLpQ3xYbVc4Wd2m"
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/skill/enable": {
+      "post": {
+        "operationId": "skill-read-enable",
+        "summary": "Enable skill",
+        "description": "Enable a disabled skill so the agent can load it.",
+        "tags": [
+          "AI SRE/Skills"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "Disable skill",
-        "tags": [
-          "AI SRE/Skills"
-        ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Skill Manage** (`ai-sre`) |\n\n## Usage\n\n- Only an `enabled` skill can be disabled; an already-disabled skill returns `InvalidParameter`.\n- Every call is recorded in the account audit log.\n",
-          "href": "/en/api-reference/ai-sre/skills/skill-write-disable",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Skill Manage** (`ai-sre`) |\n\n## Usage\n\n- Requires edit rights on the skill: account-scope skills (`team_id` = 0) are editable by account owners and admins; team skills only by members of that team (no owner or admin exemption). Otherwise the call returns `AccessDenied`.\n- Only a `disabled` skill can be enabled; enabling an already-enabled skill returns `InvalidParameter`.\n- Every call is recorded in the account audit log.\n",
+          "href": "/en/api-reference/ai-sre/skills/skill-read-enable",
           "metadata": {
-            "sidebarTitle": "Disable skill"
+            "sidebarTitle": "Enable skill"
           }
-        }
-      }
-    },
-    "/safari/skill/enable": {
-      "post": {
-        "description": "Enable a disabled skill so the agent can load it.",
-        "operationId": "skill-read-enable",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "skill_id": "skill_8s7Hn2kLpQ3xYbVc4Wd2m"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/SkillStatusRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": null,
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/ResponseEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "description": "Always null on success.",
-                          "type": "null"
+                          "type": "null",
+                          "description": "Not returned on success; the body carries only `request_id`."
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -58779,92 +60767,92 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/SkillStatusRequest"
+              },
+              "example": {
+                "skill_id": "skill_8s7Hn2kLpQ3xYbVc4Wd2m"
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/skill/get": {
+      "post": {
+        "operationId": "skill-read-get",
+        "summary": "Get skill detail",
+        "description": "Get one skill including its full SKILL.md content.",
+        "tags": [
+          "AI SRE/Skills"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "Enable skill",
-        "tags": [
-          "AI SRE/Skills"
-        ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Skill Manage** (`ai-sre`) |\n\n## Usage\n\n- Only a `disabled` skill can be enabled; an already-enabled skill returns `InvalidParameter`.\n- Every call is recorded in the account audit log.\n",
-          "href": "/en/api-reference/ai-sre/skills/skill-read-enable",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Any account member can read any skill in the account by ID, including skills of teams they do not belong to; `can_edit` tells whether the caller may change it.\n- An unknown or deleted `skill_id` returns `ResourceNotFound`.\n- `update_available` is not computed here and is always `false`; use `POST /safari/skill/list` to see marketplace update availability.\n",
+          "href": "/en/api-reference/ai-sre/skills/skill-read-get",
           "metadata": {
-            "sidebarTitle": "Enable skill"
+            "sidebarTitle": "Get skill detail"
           }
-        }
-      }
-    },
-    "/safari/skill/get": {
-      "post": {
-        "description": "Get one skill including its full SKILL.md content.",
-        "operationId": "skill-read-get",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "skill_id": "skill_8s7Hn2kLpQ3xYbVc4Wd2m"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/SkillGetRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ResponseEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/SkillItem"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
-                    "account_id": 10023,
-                    "author": "sre-team",
-                    "can_edit": true,
-                    "content": "---\nname: k8s-triage\ndescription: ...\n---\n# Triage steps",
-                    "created_at": 1716960000000,
-                    "created_by": 80011,
-                    "description": "Diagnose unhealthy Kubernetes workloads from cluster events and pod logs.",
-                    "description_en": "Diagnose unhealthy Kubernetes workloads from cluster events and pod logs.",
-                    "is_modified": false,
                     "skill_id": "skill_8s7Hn2kLpQ3xYbVc4Wd2m",
+                    "account_id": 10023,
+                    "team_id": 0,
                     "skill_name": "k8s-triage",
-                    "status": "enabled",
+                    "description": "Diagnose unhealthy Kubernetes workloads from cluster events and pod logs.",
+                    "version": "1.2.0",
                     "tags": [
                       "kubernetes",
                       "triage"
                     ],
-                    "team_id": 0,
+                    "author": "sre-team",
                     "tools": [
                       "bash",
                       "mcp:prometheus/query"
                     ],
-                    "update_available": false,
+                    "status": "enabled",
+                    "created_by": 80011,
+                    "created_at": 1716960000000,
                     "updated_at": 1717046400000,
-                    "version": "1.2.0"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/ResponseEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/SkillItem"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                    "can_edit": true,
+                    "update_available": false,
+                    "is_modified": false,
+                    "description_en": "Diagnose unhealthy Kubernetes workloads from cluster events and pod logs.",
+                    "content": "---\nname: k8s-triage\ndescription: ...\n---\n# Triage steps"
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -58872,6 +60860,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -58879,97 +60870,95 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/SkillGetRequest"
+              },
+              "example": {
+                "skill_id": "skill_8s7Hn2kLpQ3xYbVc4Wd2m"
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/skill/list": {
+      "post": {
+        "operationId": "skill-read-list",
+        "summary": "List skills",
+        "description": "List AI SRE skills visible to the caller across account and team scopes, with pagination.",
+        "tags": [
+          "AI SRE/Skills"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "Get skill detail",
-        "tags": [
-          "AI SRE/Skills"
-        ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Returns `ResourceNotFound` if the skill does not exist or has already been deleted.\n- `can_edit` reflects team membership, but read access itself is open to any caller regardless of team.\n",
-          "href": "/en/api-reference/ai-sre/skills/skill-read-get",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Returns account-scope skills plus skills of teams the caller belongs to, sorted by `skill_name` ascending. Team membership is real membership for every role; `team_ids` outside the caller's teams are silently dropped.\n- `scope` overrides `include_account`: `account` returns only account-scope skills, `team` only the caller's team skills.\n- `content` is omitted in list rows; call `POST /safari/skill/get` for the body.\n- `update_available` compares each marketplace-installed skill with the current catalog; if the catalog cannot be loaded, it is `false` for every row instead of failing the request.\n",
+          "href": "/en/api-reference/ai-sre/skills/skill-read-list",
           "metadata": {
-            "sidebarTitle": "Get skill detail"
+            "sidebarTitle": "List skills"
           }
-        }
-      }
-    },
-    "/safari/skill/list": {
-      "post": {
-        "description": "List AI SRE skills visible to the caller across account and team scopes, with pagination.",
-        "operationId": "skill-read-list",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "include_account": true,
-                "limit": 20,
-                "p": 1
-              },
-              "schema": {
-                "$ref": "#/components/schemas/SkillListRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ResponseEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/SkillListResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
+                    "total": 1,
                     "skills": [
                       {
-                        "account_id": 10023,
-                        "author": "sre-team",
-                        "can_edit": true,
-                        "created_at": 1716960000000,
-                        "created_by": 80011,
-                        "description": "Diagnose unhealthy Kubernetes workloads from cluster events and pod logs.",
-                        "is_modified": false,
                         "skill_id": "skill_8s7Hn2kLpQ3xYbVc4Wd2m",
+                        "account_id": 10023,
+                        "team_id": 0,
                         "skill_name": "k8s-triage",
-                        "status": "enabled",
+                        "description": "Diagnose unhealthy Kubernetes workloads from cluster events and pod logs.",
+                        "version": "1.2.0",
                         "tags": [
                           "kubernetes",
                           "triage"
                         ],
-                        "team_id": 0,
+                        "author": "sre-team",
                         "tools": [
                           "bash",
                           "mcp:prometheus/query"
                         ],
-                        "update_available": false,
+                        "status": "enabled",
+                        "created_by": 80011,
+                        "created_at": 1716960000000,
                         "updated_at": 1717046400000,
-                        "version": "1.2.0"
+                        "can_edit": true,
+                        "update_available": false,
+                        "is_modified": false
                       }
-                    ],
-                    "total": 1
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/ResponseEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/SkillListResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                    ]
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -58977,6 +60966,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -58984,91 +60976,92 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/SkillListRequest"
+              },
+              "example": {
+                "p": 1,
+                "limit": 20,
+                "include_account": true
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/skill/update": {
+      "post": {
+        "operationId": "skill-write-update",
+        "summary": "Update skill",
+        "description": "Update a skill's descriptions or reassign its team scope.",
+        "tags": [
+          "AI SRE/Skills"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "List skills",
-        "tags": [
-          "AI SRE/Skills"
-        ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- The `content` field is omitted in list rows; fetch a single skill to read its body.\n- `scope` selects `all` (default), `account`-only, or `team`-only, overriding `include_account`; non-admins requesting specific `team_ids` are silently filtered down to the teams they belong to.\n- `update_available` compares against the marketplace catalog once per call; if the catalog fails to load, the badge is simply suppressed rather than the request failing.\n",
-          "href": "/en/api-reference/ai-sre/skills/skill-read-list",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Skill Manage** (`ai-sre`) |\n\n## Usage\n\n- Requires edit rights on the skill: account-scope skills (`team_id` = 0) are editable by account owners and admins; team skills only by members of that team (no owner or admin exemption). Otherwise the call returns `AccessDenied`.\n- Only `description`, `description_en`, and `team_id` can be changed; change the skill body by uploading a new archive.\n- `description` changes only when non-empty, so it cannot be cleared. `description_en` changes whenever sent; an empty string clears it.\n- Moving to a team (`team_id` > 0) requires membership in the target team; moving to account scope (`team_id` = 0) requires an account owner or admin. Marketplace-installed skills can only move to account scope. A name clash in the target scope returns `InvalidParameter`.\n- Every call is recorded in the account audit log.\n",
+          "href": "/en/api-reference/ai-sre/skills/skill-write-update",
           "metadata": {
-            "sidebarTitle": "List skills"
+            "sidebarTitle": "Update skill"
           }
-        }
-      }
-    },
-    "/safari/skill/update": {
-      "post": {
-        "description": "Update a skill's descriptions or reassign its team scope.",
-        "operationId": "skill-write-update",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "description": "Updated triage runbook.",
-                "skill_id": "skill_8s7Hn2kLpQ3xYbVc4Wd2m"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/SkillUpdateRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ResponseEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/SkillItem"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
-                    "account_id": 10023,
-                    "author": "sre-team",
-                    "can_edit": true,
-                    "created_at": 1716960000000,
-                    "created_by": 80011,
-                    "description": "Updated triage runbook.",
-                    "is_modified": false,
                     "skill_id": "skill_8s7Hn2kLpQ3xYbVc4Wd2m",
+                    "account_id": 10023,
+                    "team_id": 0,
                     "skill_name": "k8s-triage",
-                    "status": "enabled",
+                    "description": "Updated triage runbook.",
+                    "version": "1.2.0",
                     "tags": [
                       "kubernetes",
                       "triage"
                     ],
-                    "team_id": 0,
+                    "author": "sre-team",
                     "tools": [
                       "bash",
                       "mcp:prometheus/query"
                     ],
-                    "update_available": false,
+                    "status": "enabled",
+                    "created_by": 80011,
+                    "created_at": 1716960000000,
                     "updated_at": 1717046400000,
-                    "version": "1.2.0"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/ResponseEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/SkillItem"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                    "can_edit": true,
+                    "update_available": false,
+                    "is_modified": false
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -59086,91 +61079,183 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/SkillUpdateRequest"
+              },
+              "example": {
+                "skill_id": "skill_8s7Hn2kLpQ3xYbVc4Wd2m",
+                "description": "Updated triage runbook."
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/skill/upload": {
+      "post": {
+        "operationId": "skill-write-upload",
+        "summary": "Upload skill",
+        "description": "Upload a skill archive (.skill/.zip/.tar.gz/.tgz) to create or replace a skill.",
+        "tags": [
+          "AI SRE/Skills"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "Update skill",
-        "tags": [
-          "AI SRE/Skills"
-        ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Skill Manage** (`ai-sre`) |\n\n## Usage\n\n- Only `description`, `description_en`, and `team_id` are editable; the skill body is changed by re-uploading.\n- `description` only updates when non-empty — there is no way to clear it via this field; `description_en` is nilable, so send an empty string to explicitly clear it.\n- Reassigning `team_id` to a different team runs a second authorization check beyond edit access, verifying the caller may target the destination team.\n- Every call is recorded in the account audit log.\n",
-          "href": "/en/api-reference/ai-sre/skills/skill-write-update",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **30 requests/minute**; **3 requests/second** per account |\n| Permissions | **Skill Manage** (`ai-sre`) |\n\n## Usage\n\n- Send `multipart/form-data` with a `file` part. Accepted archives: `.skill`, `.zip`, `.tar.gz`, `.tgz`, up to 100 MB; the archive must contain `SKILL.md` with valid frontmatter, and every declared tool must exist.\n- Without `replace`, a new skill is created in `team_id`; a skill with the same name in that scope returns `InvalidParameter`.\n- `replace=true` without `skill_id` overwrites the same-named skill in `team_id` (creating it if absent). `replace=true` with `skill_id` overwrites that skill; the archive's skill name must match it, otherwise `InvalidParameter`.\n- Creating into `team_id` requires membership in that team (`team_id` = 0 requires an account owner or admin). Overwriting requires edit rights on the existing skill.\n- An overwrite keeps `skill_id` and scope, sets `status` back to `enabled`, and sets `is_modified` to `true`. The response always has `can_edit: true`.\n- Every call is recorded in the account audit log.\n",
+          "href": "/en/api-reference/ai-sre/skills/skill-write-upload",
           "metadata": {
-            "sidebarTitle": "Update skill"
+            "sidebarTitle": "Upload skill"
           }
-        }
-      }
-    },
-    "/safari/skill/upload": {
-      "post": {
-        "description": "Upload a skill archive (.skill/.zip/.tar.gz/.tgz) to create or replace a skill.",
-        "operationId": "skill-write-upload",
-        "requestBody": {
-          "content": {
-            "multipart/form-data": {
-              "example": {
-                "replace": false,
-                "team_id": 0
-              },
-              "schema": {
-                "$ref": "#/components/schemas/SkillUploadRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ResponseEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/SkillItem"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
-                    "account_id": 10023,
-                    "author": "sre-team",
-                    "can_edit": true,
-                    "created_at": 1716960000000,
-                    "created_by": 80011,
-                    "description": "Diagnose unhealthy Kubernetes workloads from cluster events and pod logs.",
-                    "is_modified": false,
                     "skill_id": "skill_8s7Hn2kLpQ3xYbVc4Wd2m",
+                    "account_id": 10023,
+                    "team_id": 0,
                     "skill_name": "k8s-triage",
-                    "status": "enabled",
+                    "description": "Diagnose unhealthy Kubernetes workloads from cluster events and pod logs.",
+                    "version": "1.2.0",
                     "tags": [
                       "kubernetes",
                       "triage"
                     ],
-                    "team_id": 0,
+                    "author": "sre-team",
                     "tools": [
                       "bash",
                       "mcp:prometheus/query"
                     ],
-                    "update_available": false,
+                    "status": "enabled",
+                    "created_by": 80011,
+                    "created_at": 1716960000000,
                     "updated_at": 1717046400000,
-                    "version": "1.2.0"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
+                    "can_edit": true,
+                    "update_available": false,
+                    "is_modified": false
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "429": {
+            "$ref": "#/components/responses/TooManyRequests"
+          },
+          "500": {
+            "$ref": "#/components/responses/ServerError"
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "multipart/form-data": {
+              "schema": {
+                "$ref": "#/components/schemas/SkillUploadRequest"
+              },
+              "example": {
+                "team_id": 0,
+                "replace": false
+              }
+            }
+          }
+        }
+      }
+    },
+    "/schedule/by-person": {
+      "post": {
+        "operationId": "scheduleByPerson",
+        "summary": "Get member on-call status",
+        "description": "Get a member's current and next on-call shifts and every enabled schedule they participate in.",
+        "tags": [
+          "On-call/Schedules"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- `current` is the shift in progress with its real start time; when the member is on call in several schedules at once, the one ending last is returned. `next` is the earliest upcoming shift. Each is `null` when nothing is found within 45 days of now.\n- `schedules` lists the enabled schedules where the member is in at least one layer that has not ended. Disabled schedules are not listed and do not count toward `current`/`next`.\n- Any member of the account can be queried; `person_id` comes from the member list.",
+          "href": "/en/api-reference/on-call/schedules/schedule-by-person",
+          "metadata": {
+            "sidebarTitle": "Get member on-call status"
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
                 "schema": {
                   "allOf": [
                     {
-                      "$ref": "#/components/schemas/ResponseEnvelope"
+                      "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/SkillItem"
+                          "$ref": "#/components/schemas/ScheduleByPersonResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "current": {
+                      "schedule_id": 2539108069860,
+                      "schedule_name": "Open Source Q&A",
+                      "start_at": 1773446400,
+                      "end_at": 1773532799
+                    },
+                    "next": {
+                      "schedule_id": 2539108069860,
+                      "schedule_name": "Open Source Q&A",
+                      "start_at": 1773532800
+                    },
+                    "schedules": [
+                      {
+                        "schedule_id": 2539108069860,
+                        "schedule_name": "Open Source Q&A"
+                      }
+                    ]
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -59188,86 +61273,64 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "security": [
-          {
-            "AppKeyAuth": []
-          }
-        ],
-        "summary": "Upload skill",
-        "tags": [
-          "AI SRE/Skills"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **30 requests/minute**; **3 requests/second** per account |\n| Permissions | **Skill Manage** (`ai-sre`) |\n\n## Usage\n\n- Send as `multipart/form-data` with a `file` part; accepted archive types are `.skill`, `.zip`, `.tar.gz`, `.tgz`, capped at 100MB (oversized files are rejected before the body is read).\n- `skill_id` + `replace=true` targets and overwrites that specific skill, skipping the team-authorship check since the caller already owns the row.\n- `replace=true` without `skill_id` upserts by matching skill name; omitting `replace` always creates a new skill — both paths require the caller to be allowed to author into the target `team_id`.\n- The response always stamps `can_edit: true`.\n- Every call is recorded in the account audit log.\n",
-          "href": "/en/api-reference/ai-sre/skills/skill-write-upload",
-          "metadata": {
-            "sidebarTitle": "Upload skill"
-          }
-        }
-      }
-    },
-    "/schedule/by-person": {
-      "post": {
-        "description": "Get a member's current and next on-call shifts and every enabled schedule they participate in.",
-        "operationId": "scheduleByPerson",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {
-                "person_id": 2476444212131
-              },
               "schema": {
                 "$ref": "#/components/schemas/ScheduleByPersonRequest"
+              },
+              "example": {
+                "person_id": 2476444212131
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/schedule/create": {
+      "post": {
+        "operationId": "scheduleCreate",
+        "summary": "Create schedule",
+        "description": "Create an on-call schedule with its rotation layers and shift notification settings.",
+        "tags": [
+          "On-call/Schedules"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Schedules Manage** (`on-call`) |\n\n## Usage\n\n- `schedule_name` (or the legacy `name`) is required, at most 40 characters, and must be unique in the account. `description` is at most 500 characters.\n- `time_zone` anchors every wall-clock rule of the schedule (handoff time, restriction windows, weekdays, fixed-time notifications) and cannot be changed later. When omitted, the schedule is evaluated in `Asia/Shanghai` and `time_zone` reads back as an empty string.\n- Layer times can be sent either as numbers (`layer_start`, `handoff_time`, `restrict_periods`, …) or as wall-clock strings (`starts_at`, `ends_at`, `handoff`, `restricts_wall`); wall-clock fields win and are converted in the schedule's time zone.\n- Creating more schedules than the account's plan allows is rejected with `NoLicense`.\n- Use `/schedule/preview` to check the resulting shifts before saving.\n- Every call is recorded in the account audit log.",
+          "href": "/en/api-reference/on-call/schedules/schedule-create",
+          "metadata": {
+            "sidebarTitle": "Create schedule"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "current": {
-                      "end_at": 1773532799,
-                      "schedule_id": 2539108069860,
-                      "schedule_name": "Open Source Q&A",
-                      "start_at": 1773446400
-                    },
-                    "next": {
-                      "end_at": 1773619199,
-                      "schedule_id": 2539108069860,
-                      "schedule_name": "Open Source Q&A",
-                      "start_at": 1773532800
-                    },
-                    "schedules": [
-                      {
-                        "schedule_id": 2539108069860,
-                        "schedule_name": "Open Source Q&A"
-                      }
-                    ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/ScheduleByPersonResponse"
+                          "$ref": "#/components/schemas/ScheduleIDResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "schedule_id": 6294534917601
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -59275,6 +61338,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -59282,135 +61348,134 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Get member on-call status",
-        "tags": [
-          "On-call/Schedules"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Schedules Read** (`on-call`) or **Schedules Manage** (`on-call`) |\n\n## Usage\n\n- `current` carries the shift in progress with its true start time; `next` is the upcoming shift, absent when nothing is scheduled within the lookup window.\n- Disabled schedules are not listed.",
-          "href": "/en/api-reference/on-call/schedules/schedule-by-person",
-          "metadata": {
-            "sidebarTitle": "Get member on-call status"
-          }
-        }
-      }
-    },
-    "/schedule/create": {
-      "post": {
-        "description": "Create a new on-call schedule (escalation rule schedule).",
-        "operationId": "scheduleCreate",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ScheduleUpsertRequest"
+              },
               "example": {
+                "schedule_name": "Production On-Call",
                 "description": "Primary on-call rotation for the production team",
+                "team_id": 4291079133131,
+                "time_zone": "Asia/Shanghai",
                 "layers": [
                   {
-                    "day_mask": {
-                      "repeat": [
-                        1,
-                        2,
-                        3,
-                        4,
-                        5
-                      ]
-                    },
-                    "enable_time": 1712000000,
-                    "expire_time": 0,
-                    "fair_rotation": false,
+                    "layer_name": "Layer 1",
+                    "name": "Layer 1",
+                    "mode": 0,
+                    "weight": 0,
+                    "hidden": 0,
                     "groups": [
                       {
-                        "end": 0,
                         "group_name": "A",
+                        "name": "A",
                         "members": [
                           {
+                            "role_id": 0,
                             "person_ids": [
                               2451002751131
-                            ],
-                            "role_id": 0
+                            ]
                           }
                         ],
-                        "name": "A",
-                        "start": 0
+                        "start": 0,
+                        "end": 0
                       },
                       {
-                        "end": 0,
                         "group_name": "B",
+                        "name": "B",
                         "members": [
                           {
+                            "role_id": 0,
                             "person_ids": [
                               2476123212131
-                            ],
-                            "role_id": 0
+                            ]
                           }
                         ],
-                        "name": "B",
-                        "start": 0
+                        "start": 0,
+                        "end": 0
                       }
                     ],
+                    "rotation_unit": "day",
+                    "rotation_value": 1,
+                    "rotation_duration": 86400,
                     "handoff_time": 0,
-                    "hidden": 0,
-                    "layer_name": "Layer 1",
-                    "mask_continuous_enabled": false,
-                    "mode": 0,
-                    "name": "Layer 1",
-                    "restrict_end": 0,
+                    "enable_time": 1712000000,
+                    "expire_time": 0,
                     "restrict_mode": 0,
-                    "restrict_periods": [],
                     "restrict_start": 0,
-                    "rotation_duration": 86400,
-                    "rotation_unit": "day",
-                    "rotation_value": 1,
-                    "weight": 0
+                    "restrict_end": 0,
+                    "restrict_periods": [],
+                    "day_mask": {
+                      "repeat": [
+                        1,
+                        2,
+                        3,
+                        4,
+                        5
+                      ]
+                    },
+                    "fair_rotation": false,
+                    "mask_continuous_enabled": false
                   }
                 ],
                 "notify": {
                   "advance_in_time": 300,
+                  "fixed_time": null,
                   "by": {
                     "follow_preference": true,
                     "personal_channels": null
                   },
-                  "fixed_time": null,
                   "webhooks": null
-                },
-                "schedule_name": "Production On-Call",
-                "team_id": 4291079133131
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ScheduleUpsertRequest"
+                }
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/schedule/delete": {
+      "post": {
+        "operationId": "scheduleDelete",
+        "summary": "Delete schedules",
+        "description": "Delete one or more on-call schedules by ID, together with their layers.",
+        "tags": [
+          "On-call/Schedules"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Schedules Manage** (`on-call`) |\n\n## Usage\n\n- A schedule still referenced by an escalation rule cannot be deleted: the call fails with HTTP 400 `ReferenceExist`, nothing is deleted, and `data.refs` lists the referencing rules (`kind`, `name`, `href`).\n- IDs that do not exist are ignored. The deletion of all listed schedules happens in one transaction.\n- Every call is recorded in the account audit log.",
+          "href": "/en/api-reference/on-call/schedules/schedule-delete",
+          "metadata": {
+            "sidebarTitle": "Delete schedules"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "schedule_id": 6294534917601
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/ScheduleIDResponse"
+                          "$ref": "#/components/schemas/ScheduleEmptyObject"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -59418,6 +61483,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -59425,387 +61493,316 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Create schedule",
-        "tags": [
-          "On-call/Schedules"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Schedules Manage** (`on-call`) |",
-          "href": "/en/api-reference/on-call/schedules/schedule-create",
-          "metadata": {
-            "sidebarTitle": "Create schedule"
-          }
-        }
-      }
-    },
-    "/schedule/delete": {
-      "post": {
-        "description": "Delete one or more on-call schedules by ID.",
-        "operationId": "scheduleDelete",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ScheduleIDsBodyRequest"
+              },
               "example": {
                 "schedule_ids": [
-                  2001
+                  5789640530410
                 ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ScheduleIDsBodyRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/schedule/info": {
+      "post": {
+        "operationId": "scheduleInfo",
+        "summary": "Get schedule info",
+        "description": "Return one on-call schedule with its layers and the shifts computed for a time window of up to 45 days.",
+        "tags": [
+          "On-call/Schedules"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Schedules Read** (`on-call`) or **Schedules Manage** (`on-call`) |\n\n## Usage\n\n- `start` and `end` are 10-digit Unix timestamps in seconds; `end` must be after `start` and at most 45 days later.\n- `schedule_layers` (and its alias `layer_schedules`) holds each visible layer's shifts in the window; `final_schedule` merges all layers, and a shift whose `group` is `null` is a gap with nobody on call.\n- The first computed shift may start before `start`: a shift already in progress at `start` is returned with its real start time.\n- `cur_oncall` is the shift in progress now and `next_oncall` the next shift with someone on duty; each is `null` when there is none within 45 days of now, independent of the requested window.\n- An unknown `schedule_id` returns `400`.",
+          "href": "/en/api-reference/on-call/schedules/schedule-info",
+          "metadata": {
+            "sidebarTitle": "Get schedule info"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/ScheduleEmptyObject"
+                          "$ref": "#/components/schemas/ScheduleItem"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
-                }
-              }
-            },
-            "description": "Success"
-          },
-          "400": {
-            "$ref": "#/components/responses/BadRequest"
-          },
-          "401": {
-            "$ref": "#/components/responses/Unauthorized"
-          },
-          "429": {
-            "$ref": "#/components/responses/TooManyRequests"
-          },
-          "500": {
-            "$ref": "#/components/responses/ServerError"
-          }
-        },
-        "summary": "Delete schedules",
-        "tags": [
-          "On-call/Schedules"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Schedules Manage** (`on-call`) |",
-          "href": "/en/api-reference/on-call/schedules/schedule-delete",
-          "metadata": {
-            "sidebarTitle": "Delete schedules"
-          }
-        }
-      }
-    },
-    "/schedule/info": {
-      "post": {
-        "description": "Return details of an on-call schedule including the computed schedule layers for the requested time window (max 45 days).",
-        "operationId": "scheduleInfo",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "end": 1712086400,
-                "schedule_id": 2001,
-                "start": 1712000000
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ScheduleInfoRequest"
-              }
-            }
-          },
-          "required": true
-        },
-        "responses": {
-          "200": {
-            "content": {
-              "application/json": {
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
+                    "id": 5789640530410,
+                    "name": "test-000001",
                     "account_id": 2451002751131,
+                    "group_id": 4291079133131,
+                    "time_zone": "Asia/Shanghai",
+                    "disabled": 0,
                     "create_at": 1766110836,
                     "create_by": 2476123212131,
-                    "cur_oncall": {
-                      "end": 1776009600,
-                      "group": {
-                        "end": 1776009600,
-                        "group_name": "A",
-                        "members": [
+                    "update_at": 1775205795,
+                    "update_by": 2476123212131,
+                    "layers": [
+                      {
+                        "account_id": 2451002751131,
+                        "name": "Layer 1",
+                        "schedule_id": 5789640530410,
+                        "hidden": 0,
+                        "mode": 0,
+                        "weight": 0,
+                        "groups": [
                           {
-                            "person_ids": [
-                              2451002751131
-                            ],
-                            "role_id": 0
-                          }
-                        ],
-                        "name": "A",
-                        "start": 1775972040
-                      },
-                      "index": 0,
-                      "start": 1775972040,
-                      "update_at": 0,
-                      "weight": 0
-                    },
-                    "description": "abc",
-                    "disabled": 0,
-                    "final_schedule": {
-                      "layer_name": "",
-                      "mode": 0,
-                      "name": "",
-                      "schedules": [
-                        {
-                          "end": 1776096000,
-                          "group": {
-                            "end": 1776096000,
                             "group_name": "A",
+                            "name": "A",
                             "members": [
                               {
+                                "role_id": 0,
                                 "person_ids": [
                                   3122470302131
-                                ],
-                                "role_id": 0
+                                ]
                               }
                             ],
-                            "name": "A",
-                            "start": 1776009600
+                            "start": 0,
+                            "end": 0
                           },
-                          "index": 0,
-                          "start": 1776009600
-                        }
-                      ]
-                    },
-                    "group_id": 4291079133131,
-                    "id": 5789640530410,
-                    "layer_schedules": [
+                          {
+                            "group_name": "B",
+                            "name": "B",
+                            "members": [
+                              {
+                                "role_id": 0,
+                                "person_ids": [
+                                  2659460982131
+                                ]
+                              }
+                            ],
+                            "start": 0,
+                            "end": 0
+                          }
+                        ],
+                        "rotation_duration": 86400,
+                        "handoff_time": 0,
+                        "enable_time": 1767542400,
+                        "expire_time": 0,
+                        "restrict_mode": 0,
+                        "restrict_start": 0,
+                        "restrict_end": 0,
+                        "restrict_periods": [],
+                        "day_mask": {
+                          "repeat": [
+                            1,
+                            2,
+                            3,
+                            4,
+                            5
+                          ]
+                        },
+                        "create_at": 1775205795,
+                        "create_by": 2476123212131,
+                        "update_at": 1775205795,
+                        "update_by": 2476123212131,
+                        "layer_name": "Layer 1",
+                        "fair_rotation": false,
+                        "layer_start": 1767542400,
+                        "layer_end": null,
+                        "rotation_unit": "day",
+                        "rotation_value": 1,
+                        "mask_continuous_enabled": false
+                      }
+                    ],
+                    "schedule_layers": [
                       {
                         "layer_name": "Layer 1",
-                        "mode": 0,
                         "name": "Layer 1",
+                        "mode": 0,
                         "schedules": [
                           {
+                            "start": 1776009600,
                             "end": 1776096000,
                             "group": {
-                              "end": 1776096000,
                               "group_name": "A",
+                              "name": "A",
                               "members": [
                                 {
+                                  "role_id": 0,
                                   "person_ids": [
                                     3122470302131
-                                  ],
-                                  "role_id": 0
+                                  ]
                                 }
                               ],
-                              "name": "A",
-                              "start": 1776009600
+                              "start": 1776009600,
+                              "end": 1776096000
+                            },
+                            "index": 0
+                          },
+                          {
+                            "start": 1776096000,
+                            "end": 1776182400,
+                            "group": {
+                              "group_name": "B",
+                              "name": "B",
+                              "members": [
+                                {
+                                  "role_id": 0,
+                                  "person_ids": [
+                                    2659460982131
+                                  ]
+                                }
+                              ],
+                              "start": 1776096000,
+                              "end": 1776182400
                             },
-                            "index": 0,
-                            "start": 1776009600
+                            "index": 0
                           }
                         ]
                       }
                     ],
-                    "layers": [
-                      {
-                        "account_id": 2451002751131,
-                        "create_at": 1775205795,
-                        "create_by": 2476123212131,
-                        "day_mask": {
-                          "repeat": [
-                            1,
-                            2,
-                            3,
-                            4,
-                            5
-                          ]
-                        },
-                        "enable_time": 1767542400,
-                        "expire_time": 0,
-                        "fair_rotation": false,
-                        "groups": [
-                          {
-                            "end": 0,
+                    "final_schedule": {
+                      "layer_name": "",
+                      "name": "",
+                      "mode": 0,
+                      "schedules": [
+                        {
+                          "start": 1776009600,
+                          "end": 1776096000,
+                          "group": {
                             "group_name": "A",
+                            "name": "A",
                             "members": [
                               {
+                                "role_id": 0,
                                 "person_ids": [
                                   3122470302131
-                                ],
-                                "role_id": 0
+                                ]
                               }
                             ],
-                            "name": "A",
-                            "start": 0
+                            "start": 1776009600,
+                            "end": 1776096000
                           },
-                          {
-                            "end": 0,
-                            "group_name": "B",
-                            "members": [
-                              {
-                                "person_ids": [
-                                  2659460982131
-                                ],
-                                "role_id": 0
-                              }
-                            ],
-                            "name": "B",
-                            "start": 0
-                          }
-                        ],
-                        "handoff_time": 0,
-                        "hidden": 0,
-                        "layer_end": null,
-                        "layer_name": "Layer 1",
-                        "layer_start": 1767542400,
-                        "mask_continuous_enabled": false,
-                        "mode": 0,
-                        "name": "Layer 1",
-                        "restrict_end": 0,
-                        "restrict_mode": 0,
-                        "restrict_periods": [],
-                        "restrict_start": 0,
-                        "rotation_duration": 86400,
-                        "rotation_unit": "day",
-                        "rotation_value": 1,
-                        "schedule_id": 5789640530410,
-                        "update_at": 1775205795,
-                        "update_by": 2476123212131,
-                        "weight": 0
-                      }
-                    ],
-                    "name": "test-000001",
-                    "next_oncall": {
-                      "end": 1776096000,
-                      "group": {
-                        "end": 1776096000,
-                        "group_name": "A",
-                        "members": [
-                          {
-                            "person_ids": [
-                              3122470302131
-                            ],
-                            "role_id": 0
-                          }
-                        ],
-                        "name": "A",
-                        "start": 1776009600
-                      },
-                      "index": 0,
-                      "start": 1776009600,
-                      "update_at": 0,
-                      "weight": 0
+                          "index": 0
+                        }
+                      ]
                     },
                     "notify": {
                       "advance_in_time": 300,
+                      "fixed_time": null,
                       "by": {
                         "follow_preference": false,
                         "personal_channels": [
                           "email"
                         ]
                       },
-                      "fixed_time": null,
                       "webhooks": [
                         {
+                          "type": "feishu_app",
                           "settings": {
+                            "token": "",
                             "alias": "",
+                            "data_source_id": 5427276014131,
                             "chat_ids": [
                               "oc_60a6dc4c6e4e5cbc4934ef08aa7ff76d"
-                            ],
-                            "data_source_id": 5427276014131,
-                            "sign_secret": "",
-                            "token": "",
-                            "verify_token": ""
-                          },
-                          "type": "feishu_app"
+                            ],
+                            "verify_token": "",
+                            "sign_secret": ""
+                          }
                         }
                       ]
                     },
                     "schedule_id": 5789640530410,
-                    "schedule_layers": [
+                    "schedule_name": "test-000001",
+                    "team_id": 4291079133131,
+                    "description": "abc",
+                    "layer_schedules": [
                       {
                         "layer_name": "Layer 1",
-                        "mode": 0,
                         "name": "Layer 1",
+                        "mode": 0,
                         "schedules": [
                           {
+                            "start": 1776009600,
                             "end": 1776096000,
                             "group": {
-                              "end": 1776096000,
                               "group_name": "A",
-                              "members": [
-                                {
-                                  "person_ids": [
-                                    3122470302131
-                                  ],
-                                  "role_id": 0
-                                }
-                              ],
                               "name": "A",
-                              "start": 1776009600
-                            },
-                            "index": 0,
-                            "start": 1776009600
-                          },
-                          {
-                            "end": 1776182400,
-                            "group": {
-                              "end": 1776182400,
-                              "group_name": "B",
                               "members": [
                                 {
+                                  "role_id": 0,
                                   "person_ids": [
-                                    2659460982131
-                                  ],
-                                  "role_id": 0
+                                    3122470302131
+                                  ]
                                 }
                               ],
-                              "name": "B",
-                              "start": 1776096000
+                              "start": 1776009600,
+                              "end": 1776096000
                             },
-                            "index": 0,
-                            "start": 1776096000
+                            "index": 0
                           }
                         ]
                       }
                     ],
-                    "schedule_name": "test-000001",
                     "status": 0,
-                    "team_id": 4291079133131,
-                    "update_at": 1775205795,
-                    "update_by": 2476123212131
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    "cur_oncall": {
+                      "start": 1775972040,
+                      "end": 1776009600,
+                      "group": {
+                        "group_name": "A",
+                        "name": "A",
+                        "members": [
+                          {
+                            "role_id": 0,
+                            "person_ids": [
+                              2451002751131
+                            ]
+                          }
+                        ],
+                        "start": 1775972040,
+                        "end": 1776009600
+                      },
+                      "update_at": 0,
+                      "weight": 0,
+                      "index": 0
                     },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/ScheduleItem"
-                        }
+                    "next_oncall": {
+                      "start": 1776009600,
+                      "end": 1776096000,
+                      "group": {
+                        "group_name": "A",
+                        "name": "A",
+                        "members": [
+                          {
+                            "role_id": 0,
+                            "person_ids": [
+                              3122470302131
+                            ]
+                          }
+                        ],
+                        "start": 1776009600,
+                        "end": 1776096000
                       },
-                      "type": "object"
+                      "update_at": 0,
+                      "weight": 0,
+                      "index": 0
                     }
-                  ]
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -59813,6 +61810,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -59820,121 +61820,120 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Get schedule info",
-        "tags": [
-          "On-call/Schedules"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Schedules Read** (`on-call`) or **Schedules Manage** (`on-call`) |",
-          "href": "/en/api-reference/on-call/schedules/schedule-info",
-          "metadata": {
-            "sidebarTitle": "Get schedule info"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ScheduleInfoRequest"
+              },
+              "example": {
+                "schedule_id": 5789640530410,
+                "start": 1776009600,
+                "end": 1776268800
+              }
+            }
           }
         }
       }
     },
     "/schedule/infos": {
       "post": {
-        "description": "Return details of multiple on-call schedules by their IDs.",
         "operationId": "scheduleInfos",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "schedule_ids": [
-                  2001,
-                  2002,
-                  2003
-                ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ScheduleIDsRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "Batch get schedules",
+        "description": "Return the basic configuration of several on-call schedules by ID, without layers or computed shifts.",
+        "tags": [
+          "On-call/Schedules"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Schedules Read** (`on-call`) or **Schedules Manage** (`on-call`) |\n\n## Usage\n\n- Returns stored configuration only: `layers`, `schedule_layers`, `layer_schedules`, `cur_oncall` and `next_oncall` are always `null`, and `final_schedule` is empty. Use `/schedule/info` for layers and shifts.\n- IDs that do not exist are skipped without error; disabled schedules are included.",
+          "href": "/en/api-reference/on-call/schedules/schedule-infos",
+          "metadata": {
+            "sidebarTitle": "Batch get schedules"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/ScheduleSelfResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "items": [
                       {
+                        "id": 5789640530410,
+                        "name": "test-000001",
                         "account_id": 2451002751131,
+                        "group_id": 4291079133131,
+                        "time_zone": "Asia/Shanghai",
+                        "disabled": 0,
                         "create_at": 1766110836,
                         "create_by": 2476123212131,
-                        "cur_oncall": null,
-                        "description": "abc",
-                        "disabled": 0,
+                        "update_at": 1775205795,
+                        "update_by": 2476123212131,
+                        "layers": null,
+                        "schedule_layers": null,
                         "final_schedule": {
                           "layer_name": "",
-                          "mode": 0,
                           "name": "",
+                          "mode": 0,
                           "schedules": null
                         },
-                        "group_id": 4291079133131,
-                        "id": 5789640530410,
-                        "layer_schedules": null,
-                        "layers": null,
-                        "name": "test-000001",
-                        "next_oncall": null,
                         "notify": {
                           "advance_in_time": 300,
+                          "fixed_time": null,
                           "by": {
                             "follow_preference": false,
                             "personal_channels": [
                               "email"
                             ]
                           },
-                          "fixed_time": null,
                           "webhooks": [
                             {
+                              "type": "feishu_app",
                               "settings": {
+                                "token": "",
                                 "alias": "",
+                                "data_source_id": 5427276014131,
                                 "chat_ids": [
                                   "oc_60a6dc4c6e4e5cbc4934ef08aa7ff76d"
                                 ],
-                                "data_source_id": 5427276014131,
-                                "sign_secret": "",
-                                "token": "",
-                                "verify_token": ""
-                              },
-                              "type": "feishu_app"
+                                "verify_token": "",
+                                "sign_secret": ""
+                              }
                             }
                           ]
                         },
                         "schedule_id": 5789640530410,
-                        "schedule_layers": null,
                         "schedule_name": "test-000001",
-                        "status": 0,
                         "team_id": 4291079133131,
-                        "update_at": 1775205795,
-                        "update_by": 2476123212131
+                        "description": "abc",
+                        "layer_schedules": null,
+                        "status": 0,
+                        "cur_oncall": null,
+                        "next_oncall": null
                       }
                     ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/ScheduleSelfResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -59942,6 +61941,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -59949,157 +61951,159 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Batch get schedules",
-        "tags": [
-          "On-call/Schedules"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Schedules Read** (`on-call`) or **Schedules Manage** (`on-call`) |",
-          "href": "/en/api-reference/on-call/schedules/schedule-infos",
-          "metadata": {
-            "sidebarTitle": "Batch get schedules"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ScheduleIDsRequest"
+              },
+              "example": {
+                "schedule_ids": [
+                  5789640530410,
+                  5432326025106
+                ]
+              }
+            }
           }
         }
       }
     },
     "/schedule/list": {
       "post": {
-        "description": "Return a paginated list of on-call schedules. When both start and end are provided (max 45 days apart), computed layer schedules are included.",
         "operationId": "scheduleList",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "is_my_team": true,
-                "limit": 20,
-                "p": 1,
-                "query": "production"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ScheduleListRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "List schedules",
+        "description": "List on-call schedules with filters and pagination; pass `start` and `end` to also compute shifts.",
+        "tags": [
+          "On-call/Schedules"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Sorted by creation time, newest first. `query` matches the schedule name or description as a substring.\n- `is_my_team: true` keeps schedules owned by the caller's teams. `is_my_manage: true` keeps schedules owned by the caller's teams or created by the caller. The two cannot both be true. `team_ids` is intersected with either filter.\n- Without `start`/`end`, items carry stored configuration only (`layers`, `schedule_layers`, `cur_oncall`, `next_oncall` are `null`). With both set, `layers`, `schedule_layers`, `final_schedule`, `cur_oncall` and `next_oncall` are computed; `layer_schedules` stays `null` here.\n- `start` and `end` are 10-digit Unix timestamps in seconds; `end` must be after `start` and at most 45 days later. Sending `end` without `start` is rejected.",
+          "href": "/en/api-reference/on-call/schedules/schedule-list",
+          "metadata": {
+            "sidebarTitle": "List schedules"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/ScheduleListResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "items": [
                       {
+                        "id": 5789640530410,
+                        "name": "test-000001",
                         "account_id": 2451002751131,
+                        "group_id": 4291079133131,
+                        "time_zone": "Asia/Shanghai",
+                        "disabled": 0,
                         "create_at": 1766110836,
                         "create_by": 2476123212131,
-                        "cur_oncall": null,
-                        "description": "abc",
-                        "disabled": 0,
+                        "update_at": 1775205795,
+                        "update_by": 2476123212131,
+                        "layers": null,
+                        "schedule_layers": null,
                         "final_schedule": {
                           "layer_name": "",
-                          "mode": 0,
                           "name": "",
+                          "mode": 0,
                           "schedules": null
                         },
-                        "group_id": 4291079133131,
-                        "id": 5789640530410,
-                        "layer_schedules": null,
-                        "layers": null,
-                        "name": "test-000001",
-                        "next_oncall": null,
                         "notify": {
                           "advance_in_time": 300,
+                          "fixed_time": null,
                           "by": {
                             "follow_preference": false,
                             "personal_channels": [
                               "email"
                             ]
                           },
-                          "fixed_time": null,
                           "webhooks": [
                             {
+                              "type": "feishu_app",
                               "settings": {
+                                "token": "",
                                 "alias": "",
+                                "data_source_id": 5427276014131,
                                 "chat_ids": [
                                   "oc_60a6dc4c6e4e5cbc4934ef08aa7ff76d"
                                 ],
-                                "data_source_id": 5427276014131,
-                                "sign_secret": "",
-                                "token": "",
-                                "verify_token": ""
-                              },
-                              "type": "feishu_app"
+                                "verify_token": "",
+                                "sign_secret": ""
+                              }
                             }
                           ]
                         },
                         "schedule_id": 5789640530410,
-                        "schedule_layers": null,
                         "schedule_name": "test-000001",
-                        "status": 0,
                         "team_id": 4291079133131,
-                        "update_at": 1775205795,
-                        "update_by": 2476123212131
+                        "description": "abc",
+                        "layer_schedules": null,
+                        "status": 0,
+                        "cur_oncall": null,
+                        "next_oncall": null
                       },
                       {
+                        "id": 5432326025106,
+                        "name": "test-2509300001",
                         "account_id": 2451002751131,
+                        "group_id": 2477033058131,
+                        "time_zone": "",
+                        "disabled": 0,
                         "create_at": 1759132037,
                         "create_by": 2476123212131,
-                        "cur_oncall": null,
-                        "description": "",
-                        "disabled": 0,
+                        "update_at": 1775207501,
+                        "update_by": 2476123212131,
+                        "layers": null,
+                        "schedule_layers": null,
                         "final_schedule": {
                           "layer_name": "",
-                          "mode": 0,
                           "name": "",
+                          "mode": 0,
                           "schedules": null
                         },
-                        "group_id": 2477033058131,
-                        "id": 5432326025106,
-                        "layer_schedules": null,
-                        "layers": null,
-                        "name": "test-2509300001",
-                        "next_oncall": null,
                         "notify": {
                           "advance_in_time": 300,
+                          "fixed_time": null,
                           "by": {
                             "follow_preference": true,
                             "personal_channels": null
                           },
-                          "fixed_time": null,
                           "webhooks": null
                         },
                         "schedule_id": 5432326025106,
-                        "schedule_layers": null,
                         "schedule_name": "test-2509300001",
-                        "status": 0,
                         "team_id": 2477033058131,
-                        "update_at": 1775207501,
-                        "update_by": 2476123212131
+                        "description": "",
+                        "layer_schedules": null,
+                        "status": 0,
+                        "cur_oncall": null,
+                        "next_oncall": null
                       }
                     ],
                     "total": 41
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/ScheduleListResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -60107,6 +62111,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -60114,272 +62121,228 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "List schedules",
-        "tags": [
-          "On-call/Schedules"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |",
-          "href": "/en/api-reference/on-call/schedules/schedule-list",
-          "metadata": {
-            "sidebarTitle": "List schedules"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ScheduleListRequest"
+              },
+              "example": {
+                "p": 1,
+                "limit": 20,
+                "query": "production",
+                "is_my_team": true
+              }
+            }
           }
         }
       }
     },
     "/schedule/preview": {
       "post": {
-        "description": "Preview the coverage generated by a schedule configuration without persisting it. The request accepts the same body as create/update plus a required start/end window (max 45 days).",
         "operationId": "schedulePreview",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "end": 1712086400,
-                "layers": [
-                  {
-                    "day_mask": {
-                      "repeat": [
-                        1,
-                        2,
-                        3,
-                        4,
-                        5
-                      ]
-                    },
-                    "enable_time": 1712000000,
-                    "expire_time": 0,
-                    "fair_rotation": false,
-                    "groups": [
-                      {
-                        "end": 0,
-                        "group_name": "A",
-                        "members": [
-                          {
-                            "person_ids": [
-                              2451002751131
-                            ],
-                            "role_id": 0
-                          }
-                        ],
-                        "name": "A",
-                        "start": 0
-                      }
-                    ],
-                    "handoff_time": 0,
-                    "hidden": 0,
-                    "layer_name": "Layer 1",
-                    "mask_continuous_enabled": false,
-                    "mode": 0,
-                    "name": "Layer 1",
-                    "restrict_end": 0,
-                    "restrict_mode": 0,
-                    "restrict_periods": [],
-                    "restrict_start": 0,
-                    "rotation_duration": 86400,
-                    "rotation_unit": "day",
-                    "rotation_value": 1,
-                    "weight": 0
-                  }
-                ],
-                "schedule_name": "Preview Schedule",
-                "start": 1712000000
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ScheduleUpsertRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "Preview schedule",
+        "description": "Preview the coverage generated by a schedule configuration without persisting it. The request accepts the same body as create/update plus a required start/end window (max 45 days).",
+        "tags": [
+          "On-call/Schedules"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **100 requests/minute**; **5 requests/second** per account |\n| Permissions | **Schedules Read** (`on-call`) or **Schedules Manage** (`on-call`) |\n\n## Usage\n\n- Nothing is saved. The body takes the same fields as `/schedule/create`, plus the required `start`/`end` window. `start` and `end` are 10-digit Unix timestamps in seconds; `end` must be after `start` and at most 45 days later.\n- Pass `time_zone` to preview in the time zone the schedule will be created with; without it, wall-clock values are evaluated in `Asia/Shanghai`.\n- Fields that only exist on saved schedules (`id`, `name`, `group_id`, `disabled`, `status`) are echoed from the request and are usually `null`.\n- `cur_oncall` is the shift in progress now and `next_oncall` the next shift with someone on duty; each is `null` when there is none within 45 days of now, independent of the requested window.",
+          "href": "/en/api-reference/on-call/schedules/schedule-preview",
+          "metadata": {
+            "sidebarTitle": "Preview schedule"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/ScheduleItem"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
+                    "id": null,
+                    "name": null,
                     "account_id": 0,
+                    "group_id": null,
+                    "time_zone": "",
+                    "disabled": null,
                     "create_at": 0,
                     "create_by": 0,
-                    "cur_oncall": null,
-                    "description": null,
-                    "disabled": null,
-                    "end": 1776240000,
-                    "final_schedule": {
-                      "layer_name": "",
-                      "mode": 0,
-                      "name": "",
-                      "schedules": [
-                        {
-                          "end": 1776096000,
-                          "group": {
-                            "end": 1776096000,
-                            "group_name": "A",
-                            "members": [
-                              {
-                                "person_ids": [
-                                  2451002751131
-                                ],
-                                "role_id": 0
-                              }
-                            ],
-                            "name": "A",
-                            "start": 1776009600
-                          },
-                          "index": 0,
-                          "start": 1776009600
-                        }
-                      ]
-                    },
-                    "group_id": null,
-                    "id": null,
-                    "layer_schedules": null,
+                    "update_at": 0,
+                    "update_by": 0,
                     "layers": [
                       {
                         "account_id": 0,
-                        "create_at": 0,
-                        "create_by": 0,
-                        "day_mask": {
-                          "repeat": [
-                            1,
-                            2,
-                            3,
-                            4,
-                            5
-                          ]
-                        },
-                        "enable_time": 1775980800,
-                        "expire_time": 0,
-                        "fair_rotation": false,
+                        "name": "Layer 1",
+                        "schedule_id": 0,
+                        "hidden": 0,
+                        "mode": 0,
+                        "weight": 0,
                         "groups": [
                           {
-                            "end": 0,
                             "group_name": "A",
+                            "name": "A",
                             "members": [
                               {
+                                "role_id": 0,
                                 "person_ids": [
                                   2451002751131
-                                ],
-                                "role_id": 0
+                                ]
                               }
                             ],
-                            "name": "A",
-                            "start": 0
+                            "start": 0,
+                            "end": 0
                           },
                           {
-                            "end": 0,
                             "group_name": "B",
+                            "name": "B",
                             "members": [
                               {
+                                "role_id": 0,
                                 "person_ids": [
                                   2476123212131
-                                ],
-                                "role_id": 0
-                              }
-                            ],
-                            "name": "B",
-                            "start": 0
-                          }
-                        ],
-                        "handoff_time": 0,
-                        "hidden": 0,
-                        "layer_end": null,
-                        "layer_name": "Layer 1",
-                        "layer_start": 1775980800,
-                        "mask_continuous_enabled": false,
-                        "mode": 0,
-                        "name": "Layer 1",
-                        "restrict_end": 0,
+                                ]
+                              }
+                            ],
+                            "start": 0,
+                            "end": 0
+                          }
+                        ],
+                        "rotation_duration": 86400,
+                        "handoff_time": 0,
+                        "enable_time": 1775980800,
+                        "expire_time": 0,
                         "restrict_mode": 0,
-                        "restrict_periods": [],
                         "restrict_start": 0,
-                        "rotation_duration": 86400,
-                        "rotation_unit": "day",
-                        "rotation_value": 1,
-                        "schedule_id": 0,
+                        "restrict_end": 0,
+                        "restrict_periods": [],
+                        "day_mask": {
+                          "repeat": [
+                            1,
+                            2,
+                            3,
+                            4,
+                            5
+                          ]
+                        },
+                        "create_at": 0,
+                        "create_by": 0,
                         "update_at": 0,
                         "update_by": 0,
-                        "weight": 0
+                        "layer_name": "Layer 1",
+                        "fair_rotation": false,
+                        "layer_start": 1775980800,
+                        "layer_end": null,
+                        "rotation_unit": "day",
+                        "rotation_value": 1,
+                        "mask_continuous_enabled": false
                       }
                     ],
-                    "name": null,
-                    "next_oncall": null,
-                    "notify": null,
-                    "schedule_id": 0,
                     "schedule_layers": [
                       {
                         "layer_name": "Layer 1",
-                        "mode": 0,
                         "name": "Layer 1",
+                        "mode": 0,
                         "schedules": [
                           {
+                            "start": 1776009600,
                             "end": 1776096000,
                             "group": {
-                              "end": 1776096000,
                               "group_name": "A",
+                              "name": "A",
                               "members": [
                                 {
+                                  "role_id": 0,
                                   "person_ids": [
                                     2451002751131
-                                  ],
-                                  "role_id": 0
+                                  ]
                                 }
                               ],
-                              "name": "A",
-                              "start": 1776009600
+                              "start": 1776009600,
+                              "end": 1776096000
                             },
-                            "index": 0,
-                            "start": 1776009600
+                            "index": 0
                           },
                           {
+                            "start": 1776096000,
                             "end": 1776182400,
                             "group": {
-                              "end": 1776182400,
                               "group_name": "B",
+                              "name": "B",
                               "members": [
                                 {
+                                  "role_id": 0,
                                   "person_ids": [
                                     2476123212131
-                                  ],
-                                  "role_id": 0
+                                  ]
                                 }
                               ],
-                              "name": "B",
-                              "start": 1776096000
+                              "start": 1776096000,
+                              "end": 1776182400
                             },
-                            "index": 0,
-                            "start": 1776096000
+                            "index": 0
                           }
                         ]
                       }
                     ],
-                    "schedule_name": null,
+                    "final_schedule": {
+                      "layer_name": "",
+                      "name": "",
+                      "mode": 0,
+                      "schedules": [
+                        {
+                          "start": 1776009600,
+                          "end": 1776096000,
+                          "group": {
+                            "group_name": "A",
+                            "name": "A",
+                            "members": [
+                              {
+                                "role_id": 0,
+                                "person_ids": [
+                                  2451002751131
+                                ]
+                              }
+                            ],
+                            "start": 1776009600,
+                            "end": 1776096000
+                          },
+                          "index": 0
+                        }
+                      ]
+                    },
                     "start": 1775980800,
-                    "status": null,
+                    "end": 1776240000,
+                    "notify": null,
+                    "schedule_id": 0,
+                    "schedule_name": null,
                     "team_id": null,
-                    "update_at": 0,
-                    "update_by": 0
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/ScheduleItem"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                    "description": null,
+                    "layer_schedules": null,
+                    "status": null,
+                    "cur_oncall": null,
+                    "next_oncall": null
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -60387,6 +62350,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -60394,165 +62360,213 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Preview schedule",
-        "tags": [
-          "On-call/Schedules"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **60 requests/minute**; **10 requests/second** per account |\n| Permissions | **Schedules Read** (`on-call`) or **Schedules Manage** (`on-call`) |",
-          "href": "/en/api-reference/on-call/schedules/schedule-preview",
-          "metadata": {
-            "sidebarTitle": "Preview schedule"
-          }
-        }
-      }
-    },
-    "/schedule/self": {
-      "post": {
-        "description": "Return on-call schedules where the current user is assigned.",
-        "operationId": "scheduleSelf",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ScheduleUpsertRequest"
+              },
               "example": {
+                "schedule_name": "Preview Schedule",
+                "start": 1712000000,
                 "end": 1712086400,
-                "start": 1712000000
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ScheduleSelfRequest"
+                "layers": [
+                  {
+                    "layer_name": "Layer 1",
+                    "name": "Layer 1",
+                    "mode": 0,
+                    "weight": 0,
+                    "hidden": 0,
+                    "groups": [
+                      {
+                        "group_name": "A",
+                        "name": "A",
+                        "members": [
+                          {
+                            "role_id": 0,
+                            "person_ids": [
+                              2451002751131
+                            ]
+                          }
+                        ],
+                        "start": 0,
+                        "end": 0
+                      }
+                    ],
+                    "rotation_unit": "day",
+                    "rotation_value": 1,
+                    "rotation_duration": 86400,
+                    "handoff_time": 0,
+                    "enable_time": 1712000000,
+                    "expire_time": 0,
+                    "restrict_mode": 0,
+                    "restrict_start": 0,
+                    "restrict_end": 0,
+                    "restrict_periods": [],
+                    "day_mask": {
+                      "repeat": [
+                        1,
+                        2,
+                        3,
+                        4,
+                        5
+                      ]
+                    },
+                    "fair_rotation": false,
+                    "mask_continuous_enabled": false
+                  }
+                ]
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/schedule/self": {
+      "post": {
+        "operationId": "scheduleSelf",
+        "summary": "List my schedules",
+        "description": "List the enabled on-call schedules the calling member belongs to, with the member's own shifts in the window.",
+        "tags": [
+          "On-call/Schedules"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Schedules Read** (`on-call`) or **Schedules Manage** (`on-call`) |\n\n## Usage\n\n- Lists every enabled schedule in which the calling member appears in any layer, whether or not they are on call in the window. Disabled schedules are skipped.\n- `final_schedule` keeps only the caller's shifts: periods where the caller is off duty have `group` set to `null`. `layers` and `schedule_layers` describe the whole schedule.\n- `cur_oncall` and `next_oncall` are always `null` here; use `/schedule/by-person` for the caller's current and next shift.\n- `start` and `end` are 10-digit Unix timestamps in seconds; `end` must be after `start` and at most 45 days later.",
+          "href": "/en/api-reference/on-call/schedules/schedule-self",
+          "metadata": {
+            "sidebarTitle": "List my schedules"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/ScheduleSelfResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "items": [
                       {
+                        "id": 2539108069860,
+                        "name": "Open Source Q&A",
                         "account_id": 2451002751131,
+                        "group_id": 2477033058131,
+                        "time_zone": "",
+                        "disabled": 0,
                         "create_at": 1702623874,
                         "create_by": 2451002751131,
-                        "cur_oncall": null,
-                        "description": "",
-                        "disabled": 0,
-                        "final_schedule": {
-                          "layer_name": "",
-                          "mode": 0,
-                          "name": "",
-                          "schedules": null
-                        },
-                        "group_id": 2477033058131,
-                        "id": 2539108069860,
-                        "layer_schedules": null,
+                        "update_at": 1710468081,
+                        "update_by": 2476444212131,
                         "layers": [
                           {
                             "account_id": 2451002751131,
-                            "create_at": 1702623874,
-                            "create_by": 2451002751131,
-                            "day_mask": {
-                              "repeat": [
-                                1,
-                                2,
-                                3,
-                                4,
-                                5
-                              ]
-                            },
-                            "enable_time": 1702623874,
-                            "expire_time": 0,
-                            "fair_rotation": false,
+                            "name": "Rule 1",
+                            "schedule_id": 2539108069860,
+                            "hidden": 0,
+                            "mode": 0,
+                            "weight": 0,
                             "groups": [
                               {
-                                "end": 0,
                                 "group_name": "A",
+                                "name": "A",
                                 "members": [
                                   {
+                                    "role_id": 0,
                                     "person_ids": [
                                       2476444212131
-                                    ],
-                                    "role_id": 0
+                                    ]
                                   }
                                 ],
-                                "name": "A",
-                                "start": 0
+                                "start": 0,
+                                "end": 0
                               },
                               {
-                                "end": 0,
                                 "group_name": "B",
+                                "name": "B",
                                 "members": [
                                   {
+                                    "role_id": 0,
                                     "person_ids": [
                                       2469167612131
-                                    ],
-                                    "role_id": 0
+                                    ]
                                   }
                                 ],
-                                "name": "B",
-                                "start": 0
+                                "start": 0,
+                                "end": 0
                               }
                             ],
+                            "rotation_duration": 86400,
                             "handoff_time": 0,
-                            "hidden": 0,
-                            "layer_end": null,
-                            "layer_name": "Rule 1",
-                            "layer_start": 1702623874,
-                            "mask_continuous_enabled": false,
-                            "mode": 0,
-                            "name": "Rule 1",
-                            "restrict_end": 0,
+                            "enable_time": 1702623874,
+                            "expire_time": 0,
                             "restrict_mode": 0,
-                            "restrict_periods": [],
                             "restrict_start": 0,
-                            "rotation_duration": 86400,
-                            "rotation_unit": "day",
-                            "rotation_value": 1,
-                            "schedule_id": 2539108069860,
+                            "restrict_end": 0,
+                            "restrict_periods": [],
+                            "day_mask": {
+                              "repeat": [
+                                1,
+                                2,
+                                3,
+                                4,
+                                5
+                              ]
+                            },
+                            "create_at": 1702623874,
+                            "create_by": 2451002751131,
                             "update_at": 1710468081,
                             "update_by": 2476444212131,
-                            "weight": 0
+                            "layer_name": "Rule 1",
+                            "fair_rotation": false,
+                            "layer_start": 1702623874,
+                            "layer_end": null,
+                            "rotation_unit": "day",
+                            "rotation_value": 1,
+                            "mask_continuous_enabled": false
                           }
                         ],
-                        "name": "Open Source Q&A",
-                        "next_oncall": null,
+                        "schedule_layers": null,
+                        "final_schedule": {
+                          "layer_name": "",
+                          "name": "",
+                          "mode": 0,
+                          "schedules": null
+                        },
                         "notify": {
-                          "by": null,
                           "fixed_time": null,
+                          "by": null,
                           "webhooks": null
                         },
                         "schedule_id": 2539108069860,
-                        "schedule_layers": null,
                         "schedule_name": "Open Source Q&A",
-                        "status": 0,
                         "team_id": 2477033058131,
-                        "update_at": 1710468081,
-                        "update_by": 2476444212131
+                        "description": "",
+                        "layer_schedules": null,
+                        "status": 0,
+                        "cur_oncall": null,
+                        "next_oncall": null
                       }
                     ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/ScheduleSelfResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -60560,6 +62574,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -60567,65 +62584,63 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "List my schedules",
-        "tags": [
-          "On-call/Schedules"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Schedules Read** (`on-call`) or **Schedules Manage** (`on-call`) |",
-          "href": "/en/api-reference/on-call/schedules/schedule-self",
-          "metadata": {
-            "sidebarTitle": "List my schedules"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ScheduleSelfRequest"
+              },
+              "example": {
+                "start": 1712000000,
+                "end": 1712086400
+              }
+            }
           }
         }
       }
     },
     "/schedule/update": {
       "post": {
-        "description": "Update an existing on-call schedule. Provide schedule_id to identify the schedule.",
         "operationId": "scheduleUpdate",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "description": "Updated primary on-call rotation",
-                "schedule_id": 2001,
-                "schedule_name": "Production On-Call (Updated)",
-                "team_id": 4291079133131
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ScheduleUpsertRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "Update schedule",
+        "description": "Update an on-call schedule identified by `schedule_id`; the layer list is replaced as a whole.",
+        "tags": [
+          "On-call/Schedules"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Schedules Manage** (`on-call`) |\n\n## Usage\n\n- `layers` is always replaced as a whole: send every layer you want to keep. Omitting `layers` (or sending an empty array) removes all layers.\n- Omitted `schedule_name`, `description`, `team_id`, `notify` and `status` keep their current values. A sent `notify` replaces the whole notification configuration.\n- On update, the legacy `name` and `disabled` fields are ignored; rename with `schedule_name` and enable/disable with `status` (`0` enabled, `1` disabled).\n- `time_zone` cannot be changed: omit it or send the current value; any other value is rejected. Wall-clock layer fields are converted in the stored time zone.\n- Every call is recorded in the account audit log.",
+          "href": "/en/api-reference/on-call/schedules/schedule-update",
+          "metadata": {
+            "sidebarTitle": "Update schedule"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/ScheduleEmptyObject"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -60633,6 +62648,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -60640,15 +62658,69 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Update schedule",
-        "tags": [
-          "On-call/Schedules"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Schedules Manage** (`on-call`) |",
-          "href": "/en/api-reference/on-call/schedules/schedule-update",
-          "metadata": {
-            "sidebarTitle": "Update schedule"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ScheduleUpsertRequest"
+              },
+              "example": {
+                "schedule_id": 5789640530410,
+                "schedule_name": "Production On-Call",
+                "description": "Primary on-call rotation for the production team",
+                "team_id": 4291079133131,
+                "status": 0,
+                "layers": [
+                  {
+                    "layer_name": "Layer 1",
+                    "mode": 0,
+                    "groups": [
+                      {
+                        "group_name": "A",
+                        "members": [
+                          {
+                            "role_id": 0,
+                            "person_ids": [
+                              2451002751131
+                            ]
+                          }
+                        ]
+                      },
+                      {
+                        "group_name": "B",
+                        "members": [
+                          {
+                            "role_id": 0,
+                            "person_ids": [
+                              2476123212131
+                            ]
+                          }
+                        ]
+                      }
+                    ],
+                    "rotation_unit": "day",
+                    "rotation_value": 1,
+                    "starts_at": {
+                      "date": "2026-04-13",
+                      "time": "09:00"
+                    },
+                    "restrict_mode": 0,
+                    "day_mask": {
+                      "repeat": [
+                        1,
+                        2,
+                        3,
+                        4,
+                        5
+                      ]
+                    },
+                    "fair_rotation": false,
+                    "mask_continuous_enabled": false
+                  }
+                ]
+              }
+            }
           }
         }
       }
@@ -60688,16 +62760,21 @@
                         "created_at": 1712700000,
                         "git_commit_sha": "abc1234def5678",
                         "git_repository_url": "https://github.com/example/my-web-app",
-                        "key": "browser/my-web-app/1.0.0/main.js.map",
-                        "metadata": {},
+                        "key": "3f9a1c2e7b8d4e6f9a0b1c2d3e4f5a6b",
+                        "metadata": {
+                          "minified_url": "https://cdn.example.com/static/js/main.js"
+                        },
+                        "minified_path": "/js_sourcemap/my-web-app/1.0.0/static/js/main.js",
+                        "minified_url": "https://cdn.example.com/static/js/main.js",
                         "service": "my-web-app",
                         "size": 204800,
+                        "sourcemap_path": "/js_sourcemap/my-web-app/1.0.0/static/js/main.js.map",
                         "type": "browser",
                         "updated_at": 1712700000,
                         "version": "1.0.0"
                       }
                     ],
-                    "total": 3
+                    "total": 1
                   },
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 },
@@ -60726,6 +62803,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -60738,7 +62818,7 @@
           "RUM/Sourcemaps"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- `start_time` and `end_time` are required — both use Unix epoch **milliseconds**. Maximum window is 365 days.\n- The `type` field selects the platform: `browser` (JavaScript), `android`, or `ios`. Defaults to `browser` when omitted.\n- Default page size is 20; maximum is 100. Default sort is `created_at` descending.\n- For Android, `build_id` matches the Gradle plugin build identifier. For iOS, `uuid` matches the dSYM bundle UUID.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- `start_time` and `end_time` are required — both use Unix epoch **milliseconds** and filter by upload time. Maximum window is 365 days.\n- `type` selects the platform store: `browser`, `android`, `ios`, `miniprogram`, `react-native`, `harmony`, `flutter` or `electron`. Defaults to `browser` when omitted; any other value (including `web`) returns an empty result.\n- `kind: native` switches `android` and `harmony` to their native `.so` symbol stores.\n- Default page size is 20; maximum is 100. Default sort is `created_at` descending.\n- `build_id`, `uuid` and `query` are substring matches. `uuid` and iOS `query` values are upper-cased and stripped of hyphens before matching.\n- When nothing matches, both `items` and `total` are omitted and `data` is an empty object.",
           "href": "/en/api-reference/rum/sourcemaps/sourcemap-read-list",
           "metadata": {
             "sidebarTitle": "List sourcemaps"
@@ -60748,7 +62828,7 @@
     },
     "/sourcemap/stack/enrich": {
       "post": {
-        "description": "Symbolicate or deobfuscate a browser, Android, iOS, Mini Program, or HarmonyOS stack trace.",
+        "description": "Symbolicate or deobfuscate a stack trace with the sourcemaps or symbol files uploaded for a service version.",
         "operationId": "sourcemap-read-stack-enrich",
         "requestBody": {
           "content": {
@@ -60826,6 +62906,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -60838,7 +62921,7 @@
           "RUM/Sourcemaps"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- `type` defaults to `browser` when omitted for backward compatibility.\n- Set `near` from 1 to 20 to include source-code snippets around converted frames.\n- For Android NDK native crashes, provide `arch` and `source_type: ndk` so the backend routes to native symbolication.\n- For iOS crash stacks, pass `binary_images` so addresses can be relocated against the uploaded dSYM files.\n- `no_cache` is intended for debugging and bypasses cached enrich results.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- `type` defaults to `browser` when omitted.\n- `service` and `version` must match the values used at upload time; frames with no matching symbols come back with `converted: false`.\n- Set `near` from 1 to 20 to include source-code snippets around converted frames.\n- `source_type` (the error's `error.source_type`) can reroute the request: with `type: android`, a value containing `ndk` — or an empty value plus `arch` — uses NDK native symbols; with `type: flutter` or `react-native`, `ios` uses dSYM and `android`/`ndk` uses Android symbols; with `type: electron`, `macos`/`windows`/`linux` uses Breakpad symbols for minidump frames.\n- For iOS crash stacks, pass `binary_images` so addresses can be relocated against the uploaded dSYM files.\n- Results are cached per stack; `no_cache: true` bypasses the cache and is intended for debugging.",
           "href": "/en/api-reference/rum/sourcemaps/sourcemap-read-stack-enrich",
           "metadata": {
             "sidebarTitle": "Enrich a stack trace"
@@ -60848,97 +62931,83 @@
     },
     "/status-page/change/active/list": {
       "get": {
-        "description": "List in-progress (non-terminal) events of a given type for a status page.",
         "operationId": "statusPageChangeActiveList",
-        "parameters": [
-          {
-            "description": "Status page ID.",
-            "in": "query",
-            "name": "page_id",
-            "required": true,
-            "schema": {
-              "format": "int64",
-              "type": "integer"
-            }
-          },
-          {
-            "description": "Event type filter. Required. Returns only in-progress (non-terminal) events — `investigating`/`identified`/`monitoring` for `incident`, `scheduled`/`ongoing` for `maintenance`.",
-            "in": "query",
-            "name": "type",
-            "required": true,
-            "schema": {
-              "enum": [
-                "incident",
-                "maintenance"
-              ],
-              "type": "string"
-            }
-          }
+        "summary": "List active status page events",
+        "description": "List in-progress (non-terminal) events of a given type for a status page.",
+        "tags": [
+          "On-call/Status pages"
         ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Returns all non-terminal events of the given type in one response, newest first: `investigating`/`identified`/`monitoring` incidents, or `scheduled`/`ongoing` maintenances.",
+          "href": "/en/api-reference/on-call/status-pages/status-page-change-active-list",
+          "metadata": {
+            "sidebarTitle": "List active status page events"
+          }
+        },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/StatusPageChangeListResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "items": [
                       {
+                        "change_id": 5821693893131,
+                        "page_id": 5750613685214,
+                        "type": "incident",
+                        "title": "Web Console Degraded Performance",
+                        "description": "We are currently investigating an issue affecting some services.",
+                        "status": "investigating",
                         "affected_components": [
                           {
-                            "available_since_seconds": 1765349358,
                             "component_id": "01KC3GAZ6ZJE40H55GM31RPWZE",
+                            "section_id": "01KC3FKKX5TSVG6Z3X1QNGF6V2",
                             "name": "Web Console",
+                            "available_since_seconds": 1765349358,
                             "order_id": 1,
-                            "section_id": "01KC3FKKX5TSVG6Z3X1QNGF6V2",
                             "status": "degraded"
                           }
                         ],
-                        "change_id": 5821693893131,
-                        "description": "We are currently investigating an issue affecting some services.",
-                        "notify_subscribers": true,
-                        "page_id": 5750613685214,
                         "start_at_seconds": 1766736878,
-                        "status": "investigating",
-                        "title": "Web Console Degraded Performance",
-                        "type": "incident",
                         "updates": [
                           {
+                            "update_id": "01KDCVJQ88SZPHWPTDV2Z2AZW8",
                             "at_seconds": 1766736876,
+                            "status": "investigating",
+                            "description": "We are currently investigating an issue affecting some services.",
                             "component_changes": [
                               {
                                 "component_id": "01KC3GAZ6ZJE40H55GM31RPWZE",
                                 "component_name": "Web Console",
                                 "status": "degraded"
                               }
-                            ],
-                            "description": "We are currently investigating an issue affecting some services.",
-                            "status": "investigating",
-                            "update_id": "01KDCVJQ88SZPHWPTDV2Z2AZW8"
+                            ]
                           }
-                        ]
+                        ],
+                        "notify_subscribers": true
                       }
                     ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/StatusPageChangeListResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -60946,6 +63015,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -60953,83 +63025,77 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "List active status page events",
-        "tags": [
-          "On-call/Status pages"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |",
-          "href": "/en/api-reference/on-call/status-pages/status-page-change-active-list",
-          "metadata": {
-            "sidebarTitle": "List active status page events"
+        "parameters": [
+          {
+            "name": "page_id",
+            "in": "query",
+            "required": true,
+            "schema": {
+              "type": "integer",
+              "format": "int64"
+            },
+            "description": "Status page ID."
+          },
+          {
+            "name": "type",
+            "in": "query",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "enum": [
+                "incident",
+                "maintenance"
+              ]
+            },
+            "description": "Event type filter. Required. Returns only in-progress (non-terminal) events — `investigating`/`identified`/`monitoring` for `incident`, `scheduled`/`ongoing` for `maintenance`."
           }
-        }
+        ]
       }
     },
     "/status-page/change/create": {
       "post": {
-        "description": "Create a new incident or maintenance event on a status page.",
         "operationId": "statusPageChangeCreate",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "description": "We are investigating degraded performance affecting the web console.",
-                "notify_subscribers": true,
-                "page_id": 5750613685214,
-                "start_at_seconds": 1712000000,
-                "status": "investigating",
-                "title": "Web Console Degraded Performance",
-                "type": "incident",
-                "updates": [
-                  {
-                    "component_changes": [
-                      {
-                        "component_id": "01KC3GAZ6ZJE40H55GM31RPWZE",
-                        "status": "degraded"
-                      }
-                    ],
-                    "description": "We are currently investigating an issue affecting some users.",
-                    "status": "investigating"
-                  }
-                ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/CreateStatusPageChangeRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "Create status page event",
+        "description": "Create a new incident or maintenance event on a status page.",
+        "tags": [
+          "On-call/Status pages"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Status Pages Events Manage** (`on-call`) |\n\n## Usage\n\n- `status` and every component status in `updates` must be valid for `type`, and every `component_id` must exist on the page.\n- `updates` must be in non-decreasing `at_seconds` order. If `status` is `resolved` or `completed`, every affected component must end as `operational`.\n- With `notify_subscribers: true`, subscribers are notified once, about the last entry in `updates`.\n- For a maintenance with `auto_update_by_schedule: true`, the server moves it from `scheduled` to `ongoing` at `start_at_seconds` and from `ongoing` to `completed` at `close_at_seconds`, setting affected components back to `operational`.\n- Pass `draft_id` to publish a draft stored by `POST /status-page/draft/create`; the draft must target the same page and `type` and can be published only once.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "href": "/en/api-reference/on-call/status-pages/status-page-change-create",
+          "metadata": {
+            "sidebarTitle": "Create status page event"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "change_id": 6294539747131,
-                    "change_name": "API Test Incident"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/StatusPageChangeCreateResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "change_id": 6294539747131,
+                    "change_name": "API Test Incident"
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -61037,6 +63103,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -61044,63 +63113,80 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Create status page event",
-        "tags": [
-          "On-call/Status pages"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Status Pages Events Manage** (`on-call`) |",
-          "href": "/en/api-reference/on-call/status-pages/status-page-change-create",
-          "metadata": {
-            "sidebarTitle": "Create status page event"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CreateStatusPageChangeRequest"
+              },
+              "example": {
+                "page_id": 5750613685214,
+                "type": "incident",
+                "title": "Web Console Degraded Performance",
+                "description": "We are investigating degraded performance affecting the web console.",
+                "status": "investigating",
+                "start_at_seconds": 1712000000,
+                "notify_subscribers": true,
+                "updates": [
+                  {
+                    "status": "investigating",
+                    "description": "We are currently investigating an issue affecting some users.",
+                    "component_changes": [
+                      {
+                        "component_id": "01KC3GAZ6ZJE40H55GM31RPWZE",
+                        "status": "degraded"
+                      }
+                    ]
+                  }
+                ]
+              }
+            }
           }
         }
       }
     },
     "/status-page/change/delete": {
       "post": {
-        "description": "Delete a status page event.",
         "operationId": "statusPageChangeDelete",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "change_id": 5821693893131,
-                "page_id": 5750613685214
-              },
-              "schema": {
-                "$ref": "#/components/schemas/DeleteStatusPageChangeRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "Delete status page event",
+        "description": "Delete an incident or maintenance event from a status page.",
+        "tags": [
+          "On-call/Status pages"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Status Pages Events Manage** (`on-call`) |\n\n## Usage\n\n- Deleting an event that does not exist returns success.\n- Subscriptions to this event are removed, and the scheduled transitions of an auto-updating maintenance are cancelled.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "href": "/en/api-reference/on-call/status-pages/status-page-change-delete",
+          "metadata": {
+            "sidebarTitle": "Delete status page event"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -61108,6 +63194,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -61115,119 +63204,111 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Delete status page event",
-        "tags": [
-          "On-call/Status pages"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Status Pages Events Manage** (`on-call`) |",
-          "href": "/en/api-reference/on-call/status-pages/status-page-change-delete",
-          "metadata": {
-            "sidebarTitle": "Delete status page event"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/DeleteStatusPageChangeRequest"
+              },
+              "example": {
+                "page_id": 5750613685214,
+                "change_id": 5821693893131
+              }
+            }
           }
         }
       }
     },
     "/status-page/change/info": {
       "get": {
-        "description": "Retrieve details of a specific status page event (incident or maintenance).",
         "operationId": "statusPageChangeInfo",
-        "parameters": [
-          {
-            "description": "Status page ID.",
-            "in": "query",
-            "name": "page_id",
-            "required": true,
-            "schema": {
-              "format": "int64",
-              "type": "integer"
-            }
-          },
-          {
-            "description": "Event (change) ID.",
-            "in": "query",
-            "name": "change_id",
-            "required": true,
-            "schema": {
-              "format": "int64",
-              "type": "integer"
-            }
-          }
+        "summary": "Get status page event detail",
+        "description": "Retrieve details of a specific status page event (incident or maintenance).",
+        "tags": [
+          "On-call/Status pages"
         ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Returns every affected component, including hidden ones; component names, sections, and order reflect the page's current configuration.\n- Returns `ResourceNotFound` when the page or the event does not exist.",
+          "href": "/en/api-reference/on-call/status-pages/status-page-change-info",
+          "metadata": {
+            "sidebarTitle": "Get status page event detail"
+          }
+        },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/StatusPageChangeItem"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
+                    "change_id": 5821693893131,
+                    "page_id": 5750613685214,
+                    "type": "incident",
+                    "title": "Web Console Degraded Performance",
+                    "description": "The issue has been resolved, and all services are operating normally.\n\nThank you for your patience.",
+                    "status": "resolved",
                     "affected_components": [
                       {
-                        "available_since_seconds": 1765349358,
                         "component_id": "01KC3GAZ6ZJE40H55GM31RPWZE",
+                        "section_id": "01KC3FKKX5TSVG6Z3X1QNGF6V2",
                         "name": "Web Console",
+                        "available_since_seconds": 1765349358,
                         "order_id": 1,
-                        "section_id": "01KC3FKKX5TSVG6Z3X1QNGF6V2",
                         "status": "operational"
                       }
                     ],
-                    "change_id": 5821693893131,
-                    "close_at_seconds": 1775529742,
-                    "description": "The issue has been resolved, and all services are operating normally.\n\nThank you for your patience.",
-                    "notify_subscribers": true,
-                    "page_id": 5750613685214,
                     "start_at_seconds": 1766736878,
-                    "status": "resolved",
-                    "title": "Web Console Degraded Performance",
-                    "type": "incident",
+                    "close_at_seconds": 1775529742,
                     "updates": [
                       {
+                        "update_id": "01KDCVJQ88SZPHWPTDV2Z2AZW8",
                         "at_seconds": 1766736876,
+                        "status": "investigating",
+                        "description": "We are currently investigating an issue affecting some services.",
                         "component_changes": [
                           {
                             "component_id": "01KC3GAZ6ZJE40H55GM31RPWZE",
                             "component_name": "Web Console",
                             "status": "degraded"
                           }
-                        ],
-                        "description": "We are currently investigating an issue affecting some services.",
-                        "status": "investigating",
-                        "update_id": "01KDCVJQ88SZPHWPTDV2Z2AZW8"
+                        ]
                       },
                       {
+                        "update_id": "01KNJX3KW873ZZSRZC14SGFYS3",
                         "at_seconds": 1775529742,
+                        "status": "resolved",
+                        "description": "The issue has been resolved, and all services are operating normally.",
                         "component_changes": [
                           {
                             "component_id": "01KC3GAZ6ZJE40H55GM31RPWZE",
                             "component_name": "Web Console",
                             "status": "operational"
                           }
-                        ],
-                        "description": "The issue has been resolved, and all services are operating normally.",
-                        "status": "resolved",
-                        "update_id": "01KNJX3KW873ZZSRZC14SGFYS3"
+                        ]
                       }
-                    ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/StatusPageChangeItem"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                    ],
+                    "notify_subscribers": true
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -61235,6 +63316,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -61242,246 +63326,248 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Get status page event detail",
-        "tags": [
-          "On-call/Status pages"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |",
-          "href": "/en/api-reference/on-call/status-pages/status-page-change-info",
-          "metadata": {
-            "sidebarTitle": "Get status page event detail"
-          }
-        }
-      }
-    },
-    "/status-page/change/list": {
-      "get": {
-        "description": "List status page events for console management. Unlike the public display endpoints, the response includes hidden components.",
-        "operationId": "statusPageChangeList",
         "parameters": [
           {
-            "description": "Status page ID.",
-            "in": "query",
             "name": "page_id",
-            "required": true,
-            "schema": {
-              "format": "int64",
-              "type": "integer"
-            }
-          },
-          {
-            "description": "Lower bound of the event activity window: only events still open at, or closed at or after, this Unix timestamp (seconds) are returned.",
-            "in": "query",
-            "name": "start_at_seconds",
-            "required": false,
-            "schema": {
-              "format": "int64",
-              "type": "integer"
-            }
-          },
-          {
-            "description": "Upper bound of the event activity window: only events started at or before this Unix timestamp (seconds) are returned.",
-            "in": "query",
-            "name": "end_at_seconds",
-            "required": false,
-            "schema": {
-              "format": "int64",
-              "type": "integer"
-            }
-          },
-          {
-            "description": "Event type filter. Required.",
             "in": "query",
-            "name": "type",
             "required": true,
             "schema": {
-              "enum": [
-                "incident",
-                "maintenance"
-              ],
-              "type": "string"
-            }
+              "type": "integer",
+              "format": "int64"
+            },
+            "description": "Status page ID."
           },
           {
-            "description": "Event status filter. Required. Must be a status valid for the given `type` (`investigating`/`identified`/`monitoring`/`resolved` for `incident`; `scheduled`/`ongoing`/`completed` for `maintenance`).",
+            "name": "change_id",
             "in": "query",
-            "name": "status",
             "required": true,
             "schema": {
-              "enum": [
-                "investigating",
-                "identified",
-                "monitoring",
-                "resolved",
-                "scheduled",
-                "ongoing",
-                "completed"
-              ],
-              "type": "string"
-            }
+              "type": "integer",
+              "format": "int64"
+            },
+            "description": "Event (change) ID."
           }
+        ]
+      }
+    },
+    "/status-page/change/list": {
+      "get": {
+        "operationId": "statusPageChangeList",
+        "summary": "List status page events",
+        "description": "List the incidents or maintenances of a status page by status and time window, including hidden components.",
+        "tags": [
+          "On-call/Status pages"
         ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Returns every matching event in one response (no pagination), sorted by `start_at_seconds`, newest first.\n- Without `start_at_seconds` and `end_at_seconds`, the time window is unbounded.",
+          "href": "/en/api-reference/on-call/status-pages/status-page-change-list",
+          "metadata": {
+            "sidebarTitle": "List status page events"
+          }
+        },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/StatusPageChangeListResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "items": [
                       {
+                        "change_id": 5821693893131,
+                        "page_id": 5750613685214,
+                        "type": "incident",
+                        "title": "Web Console Degraded Performance",
+                        "description": "The issue has been resolved, and all services are operating normally.",
+                        "status": "resolved",
                         "affected_components": [
                           {
-                            "available_since_seconds": 1765349358,
                             "component_id": "01KC3GAZ6ZJE40H55GM31RPWZE",
+                            "section_id": "01KC3FKKX5TSVG6Z3X1QNGF6V2",
                             "name": "Web Console",
+                            "available_since_seconds": 1765349358,
                             "order_id": 1,
-                            "section_id": "01KC3FKKX5TSVG6Z3X1QNGF6V2",
                             "status": "operational"
                           }
                         ],
-                        "change_id": 5821693893131,
-                        "close_at_seconds": 1775529742,
-                        "description": "The issue has been resolved, and all services are operating normally.",
-                        "notify_subscribers": true,
-                        "page_id": 5750613685214,
                         "start_at_seconds": 1766736878,
-                        "status": "resolved",
-                        "title": "Web Console Degraded Performance",
-                        "type": "incident",
+                        "close_at_seconds": 1775529742,
                         "updates": [
                           {
+                            "update_id": "01KDCVJQ88SZPHWPTDV2Z2AZW8",
                             "at_seconds": 1766736876,
+                            "status": "investigating",
+                            "description": "We are currently investigating an issue affecting some services.",
                             "component_changes": [
                               {
                                 "component_id": "01KC3GAZ6ZJE40H55GM31RPWZE",
                                 "component_name": "Web Console",
                                 "status": "degraded"
                               }
-                            ],
-                            "description": "We are currently investigating an issue affecting some services.",
-                            "status": "investigating",
-                            "update_id": "01KDCVJQ88SZPHWPTDV2Z2AZW8"
+                            ]
                           },
                           {
+                            "update_id": "01KNJX3KW873ZZSRZC14SGFYS3",
                             "at_seconds": 1775529742,
+                            "status": "resolved",
+                            "description": "The issue has been resolved, and all services are operating normally.",
                             "component_changes": [
                               {
                                 "component_id": "01KC3GAZ6ZJE40H55GM31RPWZE",
                                 "component_name": "Web Console",
                                 "status": "operational"
                               }
-                            ],
-                            "description": "The issue has been resolved, and all services are operating normally.",
-                            "status": "resolved",
-                            "update_id": "01KNJX3KW873ZZSRZC14SGFYS3"
+                            ]
                           }
-                        ]
+                        ],
+                        "notify_subscribers": true
                       }
                     ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/StatusPageChangeListResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                  }
                 }
               }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "429": {
+            "$ref": "#/components/responses/TooManyRequests"
+          },
+          "500": {
+            "$ref": "#/components/responses/ServerError"
+          }
+        },
+        "parameters": [
+          {
+            "name": "page_id",
+            "in": "query",
+            "required": true,
+            "schema": {
+              "type": "integer",
+              "format": "int64"
+            },
+            "description": "Status page ID."
+          },
+          {
+            "name": "start_at_seconds",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "integer",
+              "format": "int64"
             },
-            "description": "Success"
-          },
-          "400": {
-            "$ref": "#/components/responses/BadRequest"
+            "description": "Lower bound of the event activity window: only events still open at, or closed at or after, this Unix timestamp (seconds) are returned."
           },
-          "401": {
-            "$ref": "#/components/responses/Unauthorized"
+          {
+            "name": "end_at_seconds",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "integer",
+              "format": "int64"
+            },
+            "description": "Upper bound of the event activity window: only events started at or before this Unix timestamp (seconds) are returned."
           },
-          "429": {
-            "$ref": "#/components/responses/TooManyRequests"
+          {
+            "name": "type",
+            "in": "query",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "enum": [
+                "incident",
+                "maintenance"
+              ]
+            },
+            "description": "Event type filter. Required."
           },
-          "500": {
-            "$ref": "#/components/responses/ServerError"
+          {
+            "name": "status",
+            "in": "query",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "enum": [
+                "investigating",
+                "identified",
+                "monitoring",
+                "resolved",
+                "scheduled",
+                "ongoing",
+                "completed"
+              ]
+            },
+            "description": "Event status filter. Required. Must be a status valid for the given `type` (`investigating`/`identified`/`monitoring`/`resolved` for `incident`; `scheduled`/`ongoing`/`completed` for `maintenance`)."
           }
-        },
-        "summary": "List status page events",
+        ]
+      }
+    },
+    "/status-page/change/timeline/create": {
+      "post": {
+        "operationId": "statusPageChangeTimelineCreate",
+        "summary": "Create event timeline entry",
+        "description": "Add a timeline update to a status page event.",
         "tags": [
           "On-call/Status pages"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |",
-          "href": "/en/api-reference/on-call/status-pages/status-page-change-list",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Status Pages Events Manage** (`on-call`) |\n\n## Usage\n\n- `at_seconds` must not be earlier than the event's latest timeline entry.\n- Component changes whose status equals the component's current status are dropped from the stored entry.\n- Moving to `resolved` or `completed` requires every affected component to be `operational`; posting a non-terminal status on a closed event reopens it.\n- The event description is set to this entry's description. If the event has `notify_subscribers` enabled, subscribers are notified about this entry.\n- Manually moving an auto-updating maintenance to `ongoing` or `completed` cancels the matching scheduled transition.\n- Pass `draft_id` to publish a stored draft whose `change_id` is this event; a draft can be published only once.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "href": "/en/api-reference/on-call/status-pages/status-page-change-timeline-create",
           "metadata": {
-            "sidebarTitle": "List status page events"
+            "sidebarTitle": "Create event timeline entry"
           }
-        }
-      }
-    },
-    "/status-page/change/timeline/create": {
-      "post": {
-        "description": "Add a timeline update to a status page event.",
-        "operationId": "statusPageChangeTimelineCreate",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "at_seconds": 1712003600,
-                "change_id": 5821693893131,
-                "component_changes": [
-                  {
-                    "component_id": "01KC3GAZ6ZJE40H55GM31RPWZE",
-                    "status": "partial_outage"
-                  }
-                ],
-                "description": "We have identified the root cause and are working on a fix.",
-                "page_id": 5750613685214,
-                "status": "identified"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/CreateStatusPageChangeTimelineRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "update_id": "01KP0311872NVYFRRQ82FWXAP4"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/StatusPageChangeTimelineCreateResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "update_id": "01KP0311872NVYFRRQ82FWXAP4"
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -61489,6 +63575,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -61496,64 +63585,72 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Create event timeline entry",
-        "tags": [
-          "On-call/Status pages"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Status Pages Events Manage** (`on-call`) |",
-          "href": "/en/api-reference/on-call/status-pages/status-page-change-timeline-create",
-          "metadata": {
-            "sidebarTitle": "Create event timeline entry"
-          }
-        }
-      }
-    },
-    "/status-page/change/timeline/delete": {
-      "post": {
-        "description": "Delete a timeline entry from a status page event.",
-        "operationId": "statusPageChangeTimelineDelete",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CreateStatusPageChangeTimelineRequest"
+              },
               "example": {
-                "change_id": 5821693893131,
                 "page_id": 5750613685214,
-                "update_id": "01KP0311872NVYFRRQ82FWXAP4"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/DeleteStatusPageChangeTimelineRequest"
+                "change_id": 5821693893131,
+                "status": "identified",
+                "description": "We have identified the root cause and are working on a fix.",
+                "at_seconds": 1712003600,
+                "component_changes": [
+                  {
+                    "component_id": "01KC3GAZ6ZJE40H55GM31RPWZE",
+                    "status": "partial_outage"
+                  }
+                ]
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/status-page/change/timeline/delete": {
+      "post": {
+        "operationId": "statusPageChangeTimelineDelete",
+        "summary": "Delete event timeline entry",
+        "description": "Delete a timeline entry from a status page event.",
+        "tags": [
+          "On-call/Status pages"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Status Pages Events Manage** (`on-call`) |\n\n## Usage\n\n- The latest timeline entry cannot be deleted; trying returns `InvalidParameter`.\n- After deletion, the event's status, description, close time, and affected components are recomputed from the remaining entries.\n- Returns success when the event does not exist, and `ResourceNotFound` when the event exists but `update_id` does not.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "href": "/en/api-reference/on-call/status-pages/status-page-change-timeline-delete",
+          "metadata": {
+            "sidebarTitle": "Delete event timeline entry"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -61561,6 +63658,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -61568,66 +63668,64 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Delete event timeline entry",
-        "tags": [
-          "On-call/Status pages"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Status Pages Events Manage** (`on-call`) |",
-          "href": "/en/api-reference/on-call/status-pages/status-page-change-timeline-delete",
-          "metadata": {
-            "sidebarTitle": "Delete event timeline entry"
-          }
-        }
-      }
-    },
-    "/status-page/change/timeline/update": {
-      "post": {
-        "description": "Update a timeline entry for a status page event.",
-        "operationId": "statusPageChangeTimelineUpdate",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/DeleteStatusPageChangeTimelineRequest"
+              },
               "example": {
-                "at_seconds": 1712003600,
-                "change_id": 5821693893131,
-                "description": "Corrected description: root cause identified in database layer.",
                 "page_id": 5750613685214,
+                "change_id": 5821693893131,
                 "update_id": "01KP0311872NVYFRRQ82FWXAP4"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/UpdateStatusPageChangeTimelineRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/status-page/change/timeline/update": {
+      "post": {
+        "operationId": "statusPageChangeTimelineUpdate",
+        "summary": "Update event timeline entry",
+        "description": "Edit the time or description of a status page event timeline entry.",
+        "tags": [
+          "On-call/Status pages"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Status Pages Events Manage** (`on-call`) |\n\n## Usage\n\n- Only `at_seconds` and `description` can be edited; an entry's status and component changes are fixed.\n- Pass at least one of `at_seconds` (greater than 0) or a non-empty `description`; otherwise the call returns `InvalidParameter`.\n- `at_seconds` must stay between the previous and next entries; editing the first entry also moves the event start time.\n- Editing the latest entry's description also updates the event description. No subscriber notification is sent.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "href": "/en/api-reference/on-call/status-pages/status-page-change-timeline-update",
+          "metadata": {
+            "sidebarTitle": "Update event timeline entry"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -61635,6 +63733,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -61642,64 +63743,66 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Update event timeline entry",
-        "tags": [
-          "On-call/Status pages"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Status Pages Events Manage** (`on-call`) |",
-          "href": "/en/api-reference/on-call/status-pages/status-page-change-timeline-update",
-          "metadata": {
-            "sidebarTitle": "Update event timeline entry"
-          }
-        }
-      }
-    },
-    "/status-page/change/update": {
-      "post": {
-        "description": "Update an existing status page event.",
-        "operationId": "statusPageChangeUpdate",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/UpdateStatusPageChangeTimelineRequest"
+              },
               "example": {
-                "change_id": 5821693893131,
                 "page_id": 5750613685214,
-                "title": "Web Console Degraded Performance (Updated)"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/UpdateStatusPageChangeRequest"
+                "change_id": 5821693893131,
+                "update_id": "01KP0311872NVYFRRQ82FWXAP4",
+                "description": "Corrected description: root cause identified in database layer.",
+                "at_seconds": 1712003600
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/status-page/change/update": {
+      "post": {
+        "operationId": "statusPageChangeUpdate",
+        "summary": "Update status page event",
+        "description": "Update the title, responders, or linked events of a status page event.",
+        "tags": [
+          "On-call/Status pages"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Status Pages Events Manage** (`on-call`) |\n\n## Usage\n\n- Status, description, and component impact cannot be changed here; post a timeline entry with `POST /status-page/change/timeline/create` instead.\n- An omitted or empty `responders` or `linked_changes` keeps the current list, so these lists cannot be cleared through this endpoint.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "href": "/en/api-reference/on-call/status-pages/status-page-change-update",
+          "metadata": {
+            "sidebarTitle": "Update status page event"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -61707,6 +63810,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -61714,65 +63820,64 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Update status page event",
-        "tags": [
-          "On-call/Status pages"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Status Pages Events Manage** (`on-call`) |",
-          "href": "/en/api-reference/on-call/status-pages/status-page-change-update",
-          "metadata": {
-            "sidebarTitle": "Update status page event"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/UpdateStatusPageChangeRequest"
+              },
+              "example": {
+                "page_id": 5750613685214,
+                "change_id": 5821693893131,
+                "title": "Web Console Degraded Performance (Updated)"
+              }
+            }
           }
         }
       }
     },
     "/status-page/component/delete": {
       "post": {
-        "description": "Delete a service component from a status page.",
         "operationId": "statusPageComponentDelete",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "component_ids": [
-                  "01KP032KMN9YFBMPWANJMFZFG1"
-                ],
-                "page_id": 5750613685214
-              },
-              "schema": {
-                "$ref": "#/components/schemas/DeleteStatusPageComponentRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "Delete status page component",
+        "description": "Delete one or more service components from a status page.",
+        "tags": [
+          "On-call/Status pages"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Status Pages Manage** (`on-call`) |\n\n## Usage\n\n- If any ID in `component_ids` does not exist on the page, nothing is deleted and the call still returns success.\n- Subscriptions to the deleted components are removed.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "href": "/en/api-reference/on-call/status-pages/status-page-component-delete",
+          "metadata": {
+            "sidebarTitle": "Delete status page component"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -61780,6 +63885,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -61787,74 +63895,69 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Delete status page component",
-        "tags": [
-          "On-call/Status pages"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Status Pages Manage** (`on-call`) |",
-          "href": "/en/api-reference/on-call/status-pages/status-page-component-delete",
-          "metadata": {
-            "sidebarTitle": "Delete status page component"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/DeleteStatusPageComponentRequest"
+              },
+              "example": {
+                "page_id": 5750613685214,
+                "component_ids": [
+                  "01KP032KMN9YFBMPWANJMFZFG1"
+                ]
+              }
+            }
           }
         }
       }
     },
     "/status-page/component/upsert": {
       "post": {
-        "description": "Create or update a service component on a status page.",
         "operationId": "statusPageComponentUpsert",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "components": [
-                  {
-                    "description": "Main web interface",
-                    "name": "Web Console",
-                    "order_id": 1,
-                    "section_id": "01KC3FKKX5TSVG6Z3X1QNGF6V2"
-                  }
-                ],
-                "page_id": 5750613685214
-              },
-              "schema": {
-                "$ref": "#/components/schemas/UpsertStatusPageComponentRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "Upsert status page component",
+        "description": "Create or update one or more service components on a status page.",
+        "tags": [
+          "On-call/Status pages"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Status Pages Manage** (`on-call`) |\n\n## Usage\n\n- An item without `component_id` creates a component; an item with `component_id` updates that component.\n- An update overwrites `name`, `description`, `section_id`, `order_id`, `hide_uptime`, and `hide_all` with the values sent, so omitted fields are reset (omitting `section_id` moves the component to the top level); `available_since_seconds` is ignored on update.\n- Component names must be unique within the page and `section_id` must be an existing section; any invalid item rejects the whole request.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "href": "/en/api-reference/on-call/status-pages/status-page-component-upsert",
+          "metadata": {
+            "sidebarTitle": "Upsert status page component"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "component_ids": [
-                      "01KP032KMN9YFBMPWANJMFZFG1"
-                    ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/UpsertStatusPageComponentResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "component_ids": [
+                      "01KP032KMN9YFBMPWANJMFZFG1"
+                    ]
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -61862,6 +63965,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -61869,70 +63975,74 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Upsert status page component",
-        "tags": [
-          "On-call/Status pages"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Status Pages Manage** (`on-call`) |",
-          "href": "/en/api-reference/on-call/status-pages/status-page-component-upsert",
-          "metadata": {
-            "sidebarTitle": "Upsert status page component"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/UpsertStatusPageComponentRequest"
+              },
+              "example": {
+                "page_id": 5750613685214,
+                "components": [
+                  {
+                    "name": "Web Console",
+                    "description": "Main web interface",
+                    "section_id": "01KC3FKKX5TSVG6Z3X1QNGF6V2",
+                    "order_id": 1
+                  }
+                ]
+              }
+            }
           }
         }
       }
     },
     "/status-page/create": {
       "post": {
-        "description": "Create a new status page.",
         "operationId": "statusPageCreate",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "contact_info": "mailto:support@example.com",
-                "name": "My Status Page",
-                "page_header": "Welcome to our status page",
-                "type": "public",
-                "url_name": "my-status-page"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/CreateStatusPageRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "Create status page",
+        "description": "Create a public or internal status page for the account.",
+        "tags": [
+          "On-call/Status pages"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Status Pages Manage** (`on-call`) |\n\n## Usage\n\n- Page quota by On-call plan: public pages, 1 on Free and Standard and 5 on Professional; internal pages, Professional only, up to 20. Exceeding the quota returns `InvalidParameter`.\n- `url_name` is normalized to a lowercase slug and must be unique among the account's pages of the same type; `page_url_name` in the response is the final value.\n- Public pages support only email subscription and are the only type that can use `custom_domain`; internal pages support only IM subscription.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "href": "/en/api-reference/on-call/status-pages/status-page-create",
+          "metadata": {
+            "sidebarTitle": "Create status page"
+          }
         },
         "responses": {
           "200": {
-            "content": {
-              "application/json": {
-                "example": {
-                  "data": {
-                    "page_id": 6294565612043,
-                    "page_name": "My Status Page",
-                    "page_url_name": "my-status-page"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
+            "description": "Success",
+            "content": {
+              "application/json": {
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/CreateStatusPageResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "page_id": 6294565612043,
+                    "page_name": "My Status Page",
+                    "page_url_name": "my-status-page"
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -61940,6 +64050,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -61947,62 +64060,72 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Create status page",
-        "tags": [
-          "On-call/Status pages"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Status Pages Manage** (`on-call`) |",
-          "href": "/en/api-reference/on-call/status-pages/status-page-create",
-          "metadata": {
-            "sidebarTitle": "Create status page"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CreateStatusPageRequest"
+              },
+              "example": {
+                "name": "My Status Page",
+                "url_name": "my-status-page",
+                "type": "public",
+                "date_view": "list",
+                "display_uptime_mode": "chart_and_percentage",
+                "page_header": "Welcome to our status page",
+                "contact_info": "mailto:support@example.com",
+                "subscription": {
+                  "email": true,
+                  "im": false
+                }
+              }
+            }
           }
         }
       }
     },
     "/status-page/delete": {
       "post": {
-        "description": "Delete a status page.",
         "operationId": "statusPageDelete",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "page_id": 5750613685214
-              },
-              "schema": {
-                "$ref": "#/components/schemas/DeleteStatusPageRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "Delete status page",
+        "description": "Delete a status page together with its events and subscriptions.",
+        "tags": [
+          "On-call/Status pages"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Status Pages Manage** (`on-call`) |\n\n## Usage\n\n- Deleting a page that does not exist returns success.\n- The page's events and subscriptions are deleted in the background after the call returns.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "href": "/en/api-reference/on-call/status-pages/status-page-delete",
+          "metadata": {
+            "sidebarTitle": "Delete status page"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -62010,6 +64133,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -62017,78 +64143,65 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Delete status page",
-        "tags": [
-          "On-call/Status pages"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Status Pages Manage** (`on-call`) |",
-          "href": "/en/api-reference/on-call/status-pages/status-page-delete",
-          "metadata": {
-            "sidebarTitle": "Delete status page"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/DeleteStatusPageRequest"
+              },
+              "example": {
+                "page_id": 5750613685214
+              }
+            }
           }
         }
       }
     },
     "/status-page/draft/create": {
       "post": {
-        "description": "Store a status page event draft so a human can review and publish it from the console.",
         "operationId": "statusPageDraftCreate",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "draft": {
-                  "affected_components": [
-                    {
-                      "component_id": "01KC3GAZ6ZJE40H55GM31RPWZE",
-                      "status": "degraded"
-                    }
-                  ],
-                  "message": "We are investigating degraded performance affecting the web console.",
-                  "name": "Web Console Degraded Performance",
-                  "page_id": 5750613685214,
-                  "type": "incident",
-                  "v": 1
-                },
-                "source": "ai_sre:sess_01KC3H2A9ZQ8W7E6R5T4Y3U2I1"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/CreateStatusPageDraftRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "Create status page draft",
+        "description": "Store a status page event draft so a human can review and publish it from the console.",
+        "tags": [
+          "On-call/Status pages"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Status Pages Events Manage** (`on-call`) |\n\n## Usage\n\n- The `draft` payload is stored verbatim (up to 64 KB); the console publish form reads it back to prefill the event.\n- `draft.page_id` must be a page of the caller's account, every component in `draft.affected_components` must exist on it, and a `draft.change_id` greater than 0 must be an event of the same `type`.\n- Publish the draft by passing `draft_id` to `POST /status-page/change/create` (new event) or `POST /status-page/change/timeline/create` (update to `draft.change_id`); a draft can be published only once.\n- A draft is deleted 30 days after creation, whether or not it was published.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "href": "/en/api-reference/on-call/status-pages/status-page-draft-create",
+          "metadata": {
+            "sidebarTitle": "Create status page draft"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "created_at": 1788000000,
-                    "draft_id": "draft_3xK9mQ2vN7pR4wT8yH1sJ5"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/StatusPageDraftCreateResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "draft_id": "draft_3xK9mQ2vN7pR4wT8yH1sJ5",
+                    "created_at": 1788000000
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -62096,6 +64209,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -62103,75 +64219,107 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Create status page draft",
-        "tags": [
-          "On-call/Status pages"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- The `draft` payload is stored verbatim (up to 64 KB); the console publish form reads it back to prefill the event.\n- A draft lives for 30 days and is consumed exactly once when the event is published.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
-          "href": "/en/api-reference/on-call/status-pages/status-page-draft-create",
-          "metadata": {
-            "sidebarTitle": "Create status page draft"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CreateStatusPageDraftRequest"
+              },
+              "example": {
+                "draft": {
+                  "v": 1,
+                  "page_id": 5750613685214,
+                  "type": "incident",
+                  "name": "Web Console Degraded Performance",
+                  "message": "We are investigating degraded performance affecting the web console.",
+                  "affected_components": [
+                    {
+                      "component_id": "01KC3GAZ6ZJE40H55GM31RPWZE",
+                      "status": "degraded"
+                    }
+                  ]
+                },
+                "source": "ai_sre:sess_01KC3H2A9ZQ8W7E6R5T4Y3U2I1"
+              }
+            }
           }
         }
       }
     },
     "/status-page/info": {
       "get": {
-        "description": "Retrieve detailed configuration for a specific status page.",
         "operationId": "statusPageInfo",
-        "parameters": [
-          {
-            "description": "Status page ID.",
-            "in": "query",
-            "name": "page_id",
-            "required": true,
-            "schema": {
-              "format": "int64",
-              "type": "integer"
-            }
-          }
+        "summary": "Get status page detail",
+        "description": "Retrieve detailed configuration for a specific status page.",
+        "tags": [
+          "On-call/Status pages"
         ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |",
+          "href": "/en/api-reference/on-call/status-pages/status-page-info",
+          "metadata": {
+            "sidebarTitle": "Get status page detail"
+          }
+        },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/StatusPageInfoResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
-                    "components": [
-                      {
-                        "available_since_seconds": 1765349358,
-                        "component_id": "01KC3GAZ6ZJE40H55GM31RPWZE",
-                        "name": "Web Console",
-                        "order_id": 1,
-                        "section_id": "01KC3FKKX5TSVG6Z3X1QNGF6V2"
-                      }
-                    ],
-                    "contact_info": "mailto:support@example.com",
+                    "page_id": 5750613685214,
+                    "name": "Flashduty Status Page",
+                    "url_name": "flashduty-statuspage",
+                    "type": "public",
                     "custom_domain": "status.example.com",
+                    "logo": "https://cdn.example.com/logo.png",
+                    "favicon": "https://cdn.example.com/favicon.png",
+                    "page_header": "Welcome to our status page",
+                    "page_footer": "2025 Example Corp",
+                    "date_view": "list",
+                    "display_uptime_mode": "chart_and_percentage",
                     "custom_links": [
                       {
                         "key": "Documentation",
                         "value": "https://docs.example.com"
                       }
                     ],
-                    "date_view": "list",
-                    "display_uptime_mode": "chart_and_percentage",
-                    "favicon": "https://cdn.example.com/favicon.png",
-                    "logo": "https://cdn.example.com/logo.png",
-                    "managed_domain_feature_enabled": true,
-                    "name": "Flashduty Status Page",
-                    "page_footer": "2025 Example Corp",
-                    "page_header": "Welcome to our status page",
-                    "page_id": 5750613685214,
+                    "contact_info": "mailto:support@example.com",
+                    "components": [
+                      {
+                        "component_id": "01KC3GAZ6ZJE40H55GM31RPWZE",
+                        "section_id": "01KC3FKKX5TSVG6Z3X1QNGF6V2",
+                        "name": "Web Console",
+                        "available_since_seconds": 1765349358,
+                        "order_id": 1
+                      }
+                    ],
                     "sections": [
                       {
-                        "description": "Our core services",
-                        "hide_all": false,
-                        "hide_uptime": false,
+                        "section_id": "01KC3FKKX5TSVG6Z3X1QNGF6V2",
                         "name": "Core Services",
+                        "description": "Our core services",
                         "order_id": 1,
-                        "section_id": "01KC3FKKX5TSVG6Z3X1QNGF6V2"
+                        "hide_uptime": false,
+                        "hide_all": false
                       }
                     ],
                     "subscription": {
@@ -62179,29 +64327,11 @@
                       "im": false
                     },
                     "template_preference": "message",
-                    "type": "public",
-                    "url_name": "flashduty-statuspage"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/StatusPageInfoResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                    "managed_domain_feature_enabled": true
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -62209,6 +64339,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -62216,95 +64349,169 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Get status page detail",
-        "tags": [
-          "On-call/Status pages"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |",
-          "href": "/en/api-reference/on-call/status-pages/status-page-info",
-          "metadata": {
-            "sidebarTitle": "Get status page detail"
+        "parameters": [
+          {
+            "name": "page_id",
+            "in": "query",
+            "required": true,
+            "schema": {
+              "type": "integer",
+              "format": "int64"
+            },
+            "description": "Status page ID."
           }
-        }
+        ]
       }
     },
     "/status-page/list": {
       "get": {
-        "description": "List all status pages owned by the account, including their components and sections.",
         "operationId": "status-page-read-page-list",
+        "summary": "List status pages",
+        "description": "List all status pages owned by the account, including their components and sections.",
+        "tags": [
+          "On-call/Status pages"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Returns public and internal pages in one response (no pagination), most recently created first.",
+          "href": "/en/api-reference/on-call/status-pages/status-page-read-page-list",
+          "metadata": {
+            "sidebarTitle": "List status pages"
+          }
+        },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/ListStatusPageResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "items": [
                       {
-                        "components": [
+                        "page_id": 5750613685214,
+                        "name": "Example Status",
+                        "url_name": "example-status",
+                        "type": "public",
+                        "custom_domain": "status.example.com",
+                        "logo_url": "https://www.example.com",
+                        "page_header": "Example System Status",
+                        "date_view": "calendar",
+                        "display_uptime_mode": "chart_and_percentage",
+                        "custom_links": [
                           {
-                            "available_since_seconds": 1716962400,
-                            "component_id": "cmp_001",
-                            "description": "Core API service",
-                            "hide_all": false,
-                            "hide_uptime": false,
-                            "name": "API",
-                            "order_id": 1,
-                            "section_id": "sec_001"
+                            "key": "Home",
+                            "value": "https://www.example.com"
                           }
                         ],
-                        "contact_info": "mailto:support@acme.com",
-                        "custom_domain": "status.acme.com",
-                        "custom_links": [
+                        "contact_info": "mailto:support@example.com",
+                        "components": [
                           {
-                            "name": "Home",
-                            "url": "https://acme.com"
+                            "component_id": "01KC3GAZ6ZJE40H55GM31RPWZE",
+                            "section_id": "01KC3FKKX5TSVG6Z3X1QNGF6V2",
+                            "name": "API",
+                            "description": "Core API service",
+                            "available_since_seconds": 1716962400,
+                            "order_id": 1
                           }
                         ],
-                        "date_view": "calendar",
-                        "display_uptime_mode": "chart_and_percentage",
-                        "logo_url": "https://acme.com",
-                        "name": "Acme Status",
-                        "page_header": "Acme System Status",
-                        "page_id": 7001,
                         "sections": [
                           {
-                            "hide_all": false,
-                            "hide_uptime": false,
+                            "section_id": "01KC3FKKX5TSVG6Z3X1QNGF6V2",
                             "name": "Core Services",
+                            "description": "",
                             "order_id": 1,
-                            "section_id": "sec_001"
+                            "hide_uptime": false,
+                            "hide_all": false
                           }
                         ],
                         "subscription": {
                           "email": true,
                           "im": false
                         },
-                        "type": "public",
-                        "url_name": "acme"
+                        "template_preference": "message"
                       }
                     ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "429": {
+            "$ref": "#/components/responses/TooManyRequests"
+          },
+          "500": {
+            "$ref": "#/components/responses/ServerError"
+          }
+        }
+      }
+    },
+    "/status-page/migrate-email-subscribers": {
+      "post": {
+        "operationId": "statusPageMigrateEmailSubscribers",
+        "summary": "Migrate email subscribers",
+        "description": "Start a migration job that imports email subscribers from an Atlassian Statuspage into an existing Flashduty status page.",
+        "tags": [
+          "On-call/Status pages"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **30 requests/minute**; **2 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Requires the On-call Professional plan; other accounts get `AccessDenied`.\n- Runs asynchronously and returns `job_id`; poll `GET /status-page/migration/status`. Only one migration job per account can run at a time.\n- Run it after `POST /status-page/migrate-structure` for the same source page: component subscriptions are mapped to the components that migration created, and a subscriber whose components cannot be mapped is subscribed to all components.\n- Non-email, quarantined, and address-less subscribers are skipped and counted in `progress.subscribers_skipped`; recipients already subscribed on the target page are left unchanged.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "href": "/en/api-reference/on-call/status-pages/status-page-migrate-email-subscribers",
+          "metadata": {
+            "sidebarTitle": "Migrate email subscribers"
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/ListStatusPageResponse"
+                          "$ref": "#/components/schemas/StatusPageMigrationStartResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "job_id": "01KP0311872NVYFRRQ82FW0002"
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -62312,6 +64519,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -62319,66 +64529,66 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "List status pages",
-        "tags": [
-          "On-call/Status pages"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n",
-          "href": "/en/api-reference/on-call/status-pages/status-page-read-page-list",
-          "metadata": {
-            "sidebarTitle": "List status pages"
-          }
-        }
-      }
-    },
-    "/status-page/migrate-email-subscribers": {
-      "post": {
-        "description": "Start a migration job that imports email subscribers from an Atlassian Statuspage into an existing Flashduty status page.",
-        "operationId": "statusPageMigrateEmailSubscribers",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/MigrateStatusPageEmailSubscribersRequest"
+              },
               "example": {
                 "api_key": "sk-stsp-xxxxxxxxxxxxxxxxxxxx",
                 "source_page_id": "abcdefghij",
                 "target_page_id": 5750613685214
-              },
-              "schema": {
-                "$ref": "#/components/schemas/MigrateStatusPageEmailSubscribersRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/status-page/migrate-structure": {
+      "post": {
+        "operationId": "statusPageMigrateStructure",
+        "summary": "Migrate status page structure",
+        "description": "Start a migration job that imports the structure and historical events of an Atlassian Statuspage into a new Flashduty status page.",
+        "tags": [
+          "On-call/Status pages"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **30 requests/minute**; **2 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Requires the On-call Professional plan; other accounts get `AccessDenied`.\n- Runs asynchronously: the call checks the API key and source page, returns `job_id`, and the import continues in the background; poll `GET /status-page/migration/status`.\n- Only one migration job per account can run at a time; starting another returns `InvalidParameter`.\n- Creates a public status page with email subscription enabled; running it again for the same source page reuses the page created earlier.\n- Imports sections (from component groups), components, past incidents and maintenances, and incident templates; template failures are recorded in `progress.warnings` and do not fail the job.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "href": "/en/api-reference/on-call/status-pages/status-page-migrate-structure",
+          "metadata": {
+            "sidebarTitle": "Migrate status page structure"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "job_id": "01KP0311872NVYFRRQ82FW0002"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/StatusPageMigrationStartResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "job_id": "01KP0311872NVYFRRQ82FW0001"
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -62386,72 +64596,73 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
           "500": {
             "$ref": "#/components/responses/ServerError"
           }
-        },
-        "summary": "Migrate email subscribers",
-        "tags": [
-          "On-call/Status pages"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Status Pages Manage** (`on-call`) |",
-          "href": "/en/api-reference/on-call/status-pages/status-page-migrate-email-subscribers",
-          "metadata": {
-            "sidebarTitle": "Migrate email subscribers"
-          }
-        }
-      }
-    },
-    "/status-page/migrate-structure": {
-      "post": {
-        "description": "Start a migration job that imports the structure and historical events of an Atlassian Statuspage into a new Flashduty status page.",
-        "operationId": "statusPageMigrateStructure",
+        },
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/MigrateStatusPageStructureRequest"
+              },
               "example": {
                 "api_key": "sk-stsp-xxxxxxxxxxxxxxxxxxxx",
                 "source_page_id": "abcdefghij"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/MigrateStatusPageStructureRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/status-page/migration/cancel": {
+      "post": {
+        "operationId": "statusPageMigrationCancel",
+        "summary": "Cancel status page migration",
+        "description": "Cancel a running Atlassian Statuspage migration job.",
+        "tags": [
+          "On-call/Status pages"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Only a job whose `status` is `running` can be cancelled; otherwise the call returns `InvalidParameter`.\n- The job is marked `cancelled` at once and the account can start a new migration; data already imported is kept.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "href": "/en/api-reference/on-call/status-pages/status-page-migration-cancel",
+          "metadata": {
+            "sidebarTitle": "Cancel status page migration"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "job_id": "01KP0311872NVYFRRQ82FW0001"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/StatusPageMigrationStartResponse"
+                          "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -62459,6 +64670,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -62466,62 +64680,82 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Migrate status page structure",
-        "tags": [
-          "On-call/Status pages"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Status Pages Manage** (`on-call`) |",
-          "href": "/en/api-reference/on-call/status-pages/status-page-migrate-structure",
-          "metadata": {
-            "sidebarTitle": "Migrate status page structure"
-          }
-        }
-      }
-    },
-    "/status-page/migration/cancel": {
-      "post": {
-        "description": "Cancel an in-progress status page migration job. Only jobs currently in the `running` state can be cancelled.",
-        "operationId": "statusPageMigrationCancel",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {
-                "job_id": "01KP0311872NVYFRRQ82FW0001"
-              },
               "schema": {
                 "$ref": "#/components/schemas/CancelStatusPageMigrationRequest"
+              },
+              "example": {
+                "job_id": "01KP0311872NVYFRRQ82FW0001"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/status-page/migration/status": {
+      "get": {
+        "operationId": "statusPageMigrationStatus",
+        "summary": "Get migration status",
+        "description": "Get the current status and progress of a status page migration job.",
+        "tags": [
+          "On-call/Status pages"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Poll until `status` is no longer `running`; `progress.completed_steps` out of `progress.total_steps` shows how far the job is.\n- Job state is kept for 24 hours after its last update; after that the call returns `ResourceNotFound`.\n- A `job_id` that belongs to another account returns `AccessDenied`.",
+          "href": "/en/api-reference/on-call/status-pages/status-page-migration-status",
+          "metadata": {
+            "sidebarTitle": "Get migration status"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/EmptyResponse"
+                          "$ref": "#/components/schemas/StatusPageMigrationJob"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "job_id": "01KP0311872NVYFRRQ82FW0001",
+                    "account_id": 2451002751131,
+                    "source_page_id": "abcdefghij",
+                    "target_page_id": 5750613685214,
+                    "phase": "history",
+                    "status": "completed",
+                    "progress": {
+                      "total_steps": 5,
+                      "completed_steps": 5,
+                      "components_imported": 8,
+                      "sections_imported": 3,
+                      "incidents_imported": 12,
+                      "maintenances_imported": 2,
+                      "subscribers_imported": 0,
+                      "templates_imported": 0,
+                      "subscribers_skipped": 0
+                    },
+                    "created_at": 1766736878,
+                    "updated_at": 1766740000
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -62529,6 +64763,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -62536,80 +64773,60 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Cancel status page migration",
-        "tags": [
-          "On-call/Status pages"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Status Pages Manage** (`on-call`) |",
-          "href": "/en/api-reference/on-call/status-pages/status-page-migration-cancel",
-          "metadata": {
-            "sidebarTitle": "Cancel status page migration"
-          }
-        }
-      }
-    },
-    "/status-page/migration/status": {
-      "get": {
-        "description": "Get the current status and progress of a status page migration job.",
-        "operationId": "statusPageMigrationStatus",
         "parameters": [
           {
-            "description": "Migration job ID returned by `migrate-structure` or `migrate-email-subscribers`.",
-            "in": "query",
             "name": "job_id",
+            "in": "query",
             "required": true,
             "schema": {
               "type": "string"
-            }
+            },
+            "description": "Migration job ID returned by `migrate-structure` or `migrate-email-subscribers`."
           }
+        ]
+      }
+    },
+    "/status-page/section/delete": {
+      "post": {
+        "operationId": "statusPageSectionDelete",
+        "summary": "Delete status page section",
+        "description": "Delete one or more sections from a status page; their components move to the top level.",
+        "tags": [
+          "On-call/Status pages"
         ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Status Pages Manage** (`on-call`) |\n\n## Usage\n\n- If any ID in `section_ids` does not exist on the page, nothing is deleted and the call still returns success.\n- Components in a deleted section are kept and moved to the top level.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "href": "/en/api-reference/on-call/status-pages/status-page-section-delete",
+          "metadata": {
+            "sidebarTitle": "Delete status page section"
+          }
+        },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "account_id": 2451002751131,
-                    "created_at": 1766736878,
-                    "job_id": "01KP0311872NVYFRRQ82FW0001",
-                    "phase": "history",
-                    "progress": {
-                      "completed_steps": 5,
-                      "components_imported": 8,
-                      "incidents_imported": 12,
-                      "maintenances_imported": 2,
-                      "sections_imported": 3,
-                      "subscribers_imported": 0,
-                      "subscribers_skipped": 0,
-                      "templates_imported": 0,
-                      "total_steps": 5
-                    },
-                    "source_page_id": "abcdefghij",
-                    "status": "completed",
-                    "target_page_id": 5750613685214,
-                    "updated_at": 1766740000
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/StatusPageMigrationJob"
+                          "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -62617,6 +64834,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -62624,65 +64844,69 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Get migration status",
-        "tags": [
-          "On-call/Status pages"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |",
-          "href": "/en/api-reference/on-call/status-pages/status-page-migration-status",
-          "metadata": {
-            "sidebarTitle": "Get migration status"
-          }
-        }
-      }
-    },
-    "/status-page/section/delete": {
-      "post": {
-        "description": "Delete a section from a status page.",
-        "operationId": "statusPageSectionDelete",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/DeleteStatusPageSectionRequest"
+              },
               "example": {
                 "page_id": 5750613685214,
                 "section_ids": [
                   "01KP032J1FV2H8DDGN0QSJ1CAR"
                 ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/DeleteStatusPageSectionRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/status-page/section/upsert": {
+      "post": {
+        "operationId": "statusPageSectionUpsert",
+        "summary": "Upsert status page section",
+        "description": "Create or update one or more sections that group components on a status page.",
+        "tags": [
+          "On-call/Status pages"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Status Pages Manage** (`on-call`) |\n\n## Usage\n\n- An item without `section_id` creates a section; an item with `section_id` updates that section.\n- An update overwrites `name`, `description`, `order_id`, `hide_uptime`, and `hide_all` with the values sent, so omitted fields are reset.\n- Section names must be unique within the page; any invalid item rejects the whole request.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "href": "/en/api-reference/on-call/status-pages/status-page-section-upsert",
+          "metadata": {
+            "sidebarTitle": "Upsert status page section"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/EmptyResponse"
+                          "$ref": "#/components/schemas/UpsertStatusPageSectionResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "section_ids": [
+                      "01KP032J1FV2H8DDGN0QSJ1CAR"
+                    ]
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -62690,6 +64914,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -62697,73 +64924,54 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Delete status page section",
-        "tags": [
-          "On-call/Status pages"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Status Pages Manage** (`on-call`) |",
-          "href": "/en/api-reference/on-call/status-pages/status-page-section-delete",
-          "metadata": {
-            "sidebarTitle": "Delete status page section"
-          }
-        }
-      }
-    },
-    "/status-page/section/upsert": {
-      "post": {
-        "description": "Create or update a section on a status page.",
-        "operationId": "statusPageSectionUpsert",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/UpsertStatusPageSectionRequest"
+              },
               "example": {
                 "page_id": 5750613685214,
                 "sections": [
                   {
-                    "description": "Our core services",
                     "name": "Core Services",
+                    "description": "Our core services",
                     "order_id": 1
                   }
                 ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/UpsertStatusPageSectionRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/status-page/subscriber/export": {
+      "post": {
+        "operationId": "statusPageSubscriberExport",
+        "summary": "Export subscribers",
+        "description": "Export the subscribers of a status page as a CSV file.",
+        "tags": [
+          "On-call/Status pages"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **100 requests/day**; **20 requests/minute**; **10 requests/second** per account |\n| Permissions | **Status Pages Manage** (`on-call`) |\n\n## Usage\n\n- Requires the On-call Standard plan or higher; other accounts get `AccessDenied`.\n- The response is a `text/csv` attachment, not a JSON envelope, with the columns Method, Recipient, Components, Subscribe All (`Yes`/`No`), and Locale.\n- Components lists component names joined by `, `; a component inside a section is written as `Section › Component`.\n- Public pages export email subscribers and internal pages export IM subscribers; filtering by `component_ids` also includes subscribers of all components.",
+          "href": "/en/api-reference/on-call/status-pages/status-page-subscriber-export",
+          "metadata": {
+            "sidebarTitle": "Export subscribers"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success. CSV attachment, not a JSON envelope.",
             "content": {
-              "application/json": {
-                "example": {
-                  "data": {
-                    "section_ids": [
-                      "01KP032J1FV2H8DDGN0QSJ1CAR"
-                    ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
+              "text/csv": {
                 "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/UpsertStatusPageSectionResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
-                }
+                  "$ref": "#/components/schemas/StatusPageSubscriberExportResponse"
+                },
+                "example": "Method,Recipient,Components,Subscribe All,Locale\nemail,alice@example.com,,Yes,zh-CN\nemail,bob@example.com,\"Core Services › API\",No,en-US"
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -62771,6 +64979,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -62778,47 +64989,62 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Upsert status page section",
-        "tags": [
-          "On-call/Status pages"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Status Pages Manage** (`on-call`) |",
-          "href": "/en/api-reference/on-call/status-pages/status-page-section-upsert",
-          "metadata": {
-            "sidebarTitle": "Upsert status page section"
-          }
-        }
-      }
-    },
-    "/status-page/subscriber/export": {
-      "post": {
-        "description": "Export subscribers list for a status page as a CSV attachment. The response is a `text/csv` file with columns: Method, Recipient, Components, Subscribe All, Locale.",
-        "operationId": "statusPageSubscriberExport",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {
-                "page_id": 5750613685214
-              },
               "schema": {
                 "$ref": "#/components/schemas/ExportStatusPageSubscribersRequest"
+              },
+              "example": {
+                "page_id": 5750613685214
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/status-page/subscriber/import": {
+      "post": {
+        "operationId": "statusPageSubscriberImport",
+        "summary": "Import subscribers",
+        "description": "Bulk import subscribers into a status page without sending confirmation emails.",
+        "tags": [
+          "On-call/Status pages"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **60 requests/minute**; **3 requests/second** per account |\n| Permissions | **Status Pages Manage** (`on-call`) |\n\n## Usage\n\n- Requires the On-call Professional plan, and the account must also be allowlisted for subscriber import; otherwise the call returns `AccessDenied`.\n- `method` must match the page: `email` for a public page with email subscription enabled, `im` for an internal page with IM subscription enabled.\n- Each imported recipient's existing subscriptions on this page are replaced by the imported ones.\n- Every `component_ids` and `change_ids` entry must exist on the page; one invalid ID rejects the whole request.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "href": "/en/api-reference/on-call/status-pages/status-page-subscriber-import",
+          "metadata": {
+            "sidebarTitle": "Import subscribers"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
-              "text/csv": {
-                "example": "Method,Recipient,Components,Subscribe All,Locale\nemail,alice@example.com,,Yes,zh-CN\nemail,bob@example.com,\"Core Services › API\",No,en-US",
+              "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/StatusPageSubscriberExportResponse"
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/EmptyResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success. CSV attachment, not a JSON envelope."
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -62826,6 +65052,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -62833,78 +65062,97 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Export subscribers",
-        "tags": [
-          "On-call/Status pages"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **100 requests/day**; **20 requests/minute**; **10 requests/second** per account |\n| Permissions | **Status Pages Manage** (`on-call`) |",
-          "href": "/en/api-reference/on-call/status-pages/status-page-subscriber-export",
-          "metadata": {
-            "sidebarTitle": "Export subscribers"
-          }
-        }
-      }
-    },
-    "/status-page/subscriber/import": {
-      "post": {
-        "description": "Bulk import subscribers for a status page. The account must be allowlisted for subscriber import; otherwise the call is rejected with an access-denied error.",
-        "operationId": "statusPageSubscriberImport",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ImportStatusPageSubscribersRequest"
+              },
               "example": {
-                "method": "email",
                 "page_id": 5750613685214,
+                "method": "email",
                 "subscribers": [
                   {
+                    "recipient": "alice@example.com",
                     "all": true,
-                    "locale": "en-US",
-                    "recipient": "alice@example.com"
+                    "locale": "en-US"
                   },
                   {
-                    "all": false,
+                    "recipient": "bob@example.com",
                     "component_ids": [
                       "01KC3GAZ6ZJE40H55GM31RPWZE"
                     ],
-                    "locale": "zh-CN",
-                    "recipient": "bob@example.com"
+                    "all": false,
+                    "locale": "zh-CN"
                   }
                 ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ImportStatusPageSubscribersRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/status-page/subscriber/list": {
+      "get": {
+        "operationId": "statusPageSubscriberList",
+        "summary": "List status page subscribers",
+        "description": "List subscribers who have signed up for status page notifications.",
+        "tags": [
+          "On-call/Status pages"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Public pages list email subscribers and internal pages list IM subscribers.\n- Filtering by `component_ids` also returns subscribers who subscribed to all components.\n- Each item merges all subscriptions of one recipient; subscriptions to individual events are not shown.",
+          "href": "/en/api-reference/on-call/status-pages/status-page-subscriber-list",
+          "metadata": {
+            "sidebarTitle": "List status page subscribers"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/EmptyResponse"
+                          "$ref": "#/components/schemas/StatusPageSubscriberListResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "total": 2,
+                    "has_next_page": false,
+                    "items": [
+                      {
+                        "recipient": "alice@example.com",
+                        "method": "email",
+                        "components": [],
+                        "all": true,
+                        "locale": "zh-CN"
+                      },
+                      {
+                        "recipient": "bob@example.com",
+                        "method": "email",
+                        "components": [],
+                        "all": true,
+                        "locale": "en-US"
+                      }
+                    ]
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -62912,121 +65160,105 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
           "500": {
-            "$ref": "#/components/responses/ServerError"
-          }
-        },
-        "summary": "Import subscribers",
-        "tags": [
-          "On-call/Status pages"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **20 requests/minute**; **2 requests/second** per account |\n| Permissions | **Status Pages Manage** (`on-call`) |",
-          "href": "/en/api-reference/on-call/status-pages/status-page-subscriber-import",
-          "metadata": {
-            "sidebarTitle": "Import subscribers"
-          }
-        }
-      }
-    },
-    "/status-page/subscriber/list": {
-      "get": {
-        "description": "List subscribers who have signed up for status page notifications.",
-        "operationId": "statusPageSubscriberList",
+            "$ref": "#/components/responses/ServerError"
+          }
+        },
         "parameters": [
           {
-            "description": "Status page ID.",
-            "in": "query",
             "name": "page_id",
+            "in": "query",
             "required": true,
             "schema": {
-              "format": "int64",
-              "type": "integer"
-            }
+              "type": "integer",
+              "format": "int64"
+            },
+            "description": "Status page ID."
           },
           {
-            "description": "Comma-separated component IDs to filter subscribers by.",
-            "in": "query",
             "name": "component_ids",
+            "in": "query",
             "required": false,
             "schema": {
               "type": "string"
-            }
+            },
+            "description": "Comma-separated component IDs to filter subscribers by."
           },
           {
-            "description": "Page number (1-based).",
-            "in": "query",
             "name": "p",
+            "in": "query",
             "required": false,
             "schema": {
-              "default": 1,
+              "type": "integer",
               "format": "int64",
               "minimum": 1,
-              "type": "integer"
-            }
+              "default": 1
+            },
+            "description": "Page number (1-based)."
           },
           {
-            "description": "Page size (1-100).",
-            "in": "query",
             "name": "limit",
+            "in": "query",
             "required": false,
             "schema": {
-              "default": 10,
+              "type": "integer",
               "format": "int64",
-              "maximum": 100,
               "minimum": 1,
-              "type": "integer"
-            }
+              "maximum": 100,
+              "default": 10
+            },
+            "description": "Page size (1-100)."
           }
+        ]
+      }
+    },
+    "/status-page/template/delete": {
+      "post": {
+        "operationId": "statusPageTemplateDelete",
+        "summary": "Delete status page template",
+        "description": "Delete a predefined event template or a message template from a status page.",
+        "tags": [
+          "On-call/Status pages"
         ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Status Pages Manage** (`on-call`) |\n\n## Usage\n\n- Deleting a template that does not exist returns success.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "href": "/en/api-reference/on-call/status-pages/status-page-template-delete",
+          "metadata": {
+            "sidebarTitle": "Delete status page template"
+          }
+        },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "has_next_page": false,
-                    "items": [
-                      {
-                        "all": true,
-                        "components": [],
-                        "locale": "zh-CN",
-                        "method": "email",
-                        "recipient": "alice@example.com"
-                      },
-                      {
-                        "all": true,
-                        "components": [],
-                        "locale": "en-US",
-                        "method": "email",
-                        "recipient": "bob@example.com"
-                      }
-                    ],
-                    "total": 2
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/StatusPageSubscriberListResponse"
+                          "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -63034,6 +65266,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -63041,64 +65276,74 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "List status page subscribers",
-        "tags": [
-          "On-call/Status pages"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |",
-          "href": "/en/api-reference/on-call/status-pages/status-page-subscriber-list",
-          "metadata": {
-            "sidebarTitle": "List status page subscribers"
-          }
-        }
-      }
-    },
-    "/status-page/template/delete": {
-      "post": {
-        "description": "Delete an event template from a status page.",
-        "operationId": "statusPageTemplateDelete",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {
-                "page_id": 5720156736380,
-                "template_id": "01KP0339G5XDEPM4R86T2B23EP",
-                "type": "pre_defined"
-              },
               "schema": {
                 "$ref": "#/components/schemas/DeleteStatusPageTemplateRequest"
+              },
+              "example": {
+                "page_id": 5720156736380,
+                "type": "pre_defined",
+                "template_id": "01KP0339G5XDEPM4R86T2B23EP"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/status-page/template/list": {
+      "get": {
+        "operationId": "statusPageTemplateList",
+        "summary": "List status page templates",
+        "description": "List the predefined event templates or message templates of a status page.",
+        "tags": [
+          "On-call/Status pages"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |",
+          "href": "/en/api-reference/on-call/status-pages/status-page-template-list",
+          "metadata": {
+            "sidebarTitle": "List status page templates"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/EmptyResponse"
+                          "$ref": "#/components/schemas/ListStatusPageTemplatesResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "items": [
+                      {
+                        "template_id": "01KC8KP6PHVPSCAB0BTKZBN2HR",
+                        "title": "Service Disruption",
+                        "type": "incident",
+                        "status": "identified",
+                        "description": "We have identified the root cause."
+                      }
+                    ]
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -63106,6 +65351,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -63113,84 +65361,76 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Delete status page template",
-        "tags": [
-          "On-call/Status pages"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Status Pages Manage** (`on-call`) |",
-          "href": "/en/api-reference/on-call/status-pages/status-page-template-delete",
-          "metadata": {
-            "sidebarTitle": "Delete status page template"
-          }
-        }
-      }
-    },
-    "/status-page/template/list": {
-      "get": {
-        "description": "List all event templates for a status page.",
-        "operationId": "statusPageTemplateList",
         "parameters": [
           {
-            "description": "Status page ID.",
-            "in": "query",
             "name": "page_id",
+            "in": "query",
             "required": true,
             "schema": {
-              "format": "int64",
-              "type": "integer"
-            }
+              "type": "integer",
+              "format": "int64"
+            },
+            "description": "Status page ID."
           },
           {
-            "description": "Template category. `pre_defined` returns predefined event templates; `message` returns message notification templates.",
-            "in": "query",
             "name": "type",
+            "in": "query",
             "required": true,
             "schema": {
+              "type": "string",
               "enum": [
                 "pre_defined",
                 "message"
-              ],
-              "type": "string"
-            }
+              ]
+            },
+            "description": "Template category. `pre_defined` returns predefined event templates; `message` returns message notification templates."
           }
+        ]
+      }
+    },
+    "/status-page/template/upsert": {
+      "post": {
+        "operationId": "statusPageTemplateUpsert",
+        "summary": "Upsert status page template",
+        "description": "Create or update a predefined event template or a message template of a status page.",
+        "tags": [
+          "On-call/Status pages"
         ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Status Pages Manage** (`on-call`) |\n\n## Usage\n\n- Omit `template.template_id` to create a template; supply it to update one. An unknown `template_id` returns `InternalError`.\n- On update, empty fields keep their stored values. A predefined template's `type` cannot be changed; a message template's `type` can.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "href": "/en/api-reference/on-call/status-pages/status-page-template-upsert",
+          "metadata": {
+            "sidebarTitle": "Upsert status page template"
+          }
+        },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "items": [
-                      {
-                        "description": "We have identified the root cause.",
-                        "status": "identified",
-                        "template_id": "01KC8KP6PHVPSCAB0BTKZBN2HR",
-                        "title": "Service Disruption",
-                        "type": "incident"
-                      }
-                    ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/ListStatusPageTemplatesResponse"
+                          "$ref": "#/components/schemas/UpsertStatusPageTemplateResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "template_id": "01KP0339G5XDEPM4R86T2B23EP"
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -63198,6 +65438,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -63205,144 +65448,69 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "List status page templates",
-        "tags": [
-          "On-call/Status pages"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |",
-          "href": "/en/api-reference/on-call/status-pages/status-page-template-list",
-          "metadata": {
-            "sidebarTitle": "List status page templates"
-          }
-        }
-      }
-    },
-    "/status-page/template/upsert": {
-      "post": {
-        "description": "Create or update an event template for a status page.",
-        "operationId": "statusPageTemplateUpsert",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/UpsertStatusPageTemplateRequest"
+              },
               "example": {
                 "page_id": 5720156736380,
+                "type": "pre_defined",
                 "template": {
-                  "description": "We are investigating a service disruption affecting some users.",
-                  "status": "investigating",
                   "title": "Service Disruption",
+                  "status": "investigating",
+                  "description": "We are investigating a service disruption affecting some users.",
                   "type": "incident"
-                },
-                "type": "pre_defined"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/UpsertStatusPageTemplateRequest"
-              }
-            }
-          },
-          "required": true
-        },
-        "responses": {
-          "200": {
-            "content": {
-              "application/json": {
-                "example": {
-                  "data": {
-                    "template_id": "01KP0339G5XDEPM4R86T2B23EP"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/UpsertStatusPageTemplateResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
                 }
               }
-            },
-            "description": "Success"
-          },
-          "400": {
-            "$ref": "#/components/responses/BadRequest"
-          },
-          "401": {
-            "$ref": "#/components/responses/Unauthorized"
-          },
-          "429": {
-            "$ref": "#/components/responses/TooManyRequests"
-          },
-          "500": {
-            "$ref": "#/components/responses/ServerError"
-          }
-        },
-        "summary": "Upsert status page template",
-        "tags": [
-          "On-call/Status pages"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Status Pages Manage** (`on-call`) |",
-          "href": "/en/api-reference/on-call/status-pages/status-page-template-upsert",
-          "metadata": {
-            "sidebarTitle": "Upsert status page template"
+            }
           }
         }
       }
     },
     "/status-page/update": {
       "post": {
-        "description": "Update an existing status page configuration.",
         "operationId": "statusPageUpdate",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "contact_info": "mailto:support@example.com",
-                "name": "Flashduty Status Page (Updated)",
-                "page_header": "Updated status page header",
-                "page_id": 5750613685214
-              },
-              "schema": {
-                "$ref": "#/components/schemas/UpdateStatusPageRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "Update status page",
+        "description": "Update the configuration of an existing status page; omitted fields keep their values.",
+        "tags": [
+          "On-call/Status pages"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Status Pages Manage** (`on-call`) |\n\n## Usage\n\n- A field that is omitted or `null` keeps its value; an empty string clears a string field.\n- `custom_links` cannot be cleared: an omitted or empty array keeps the current links.\n- A new `url_name` is normalized to a slug and must be unique among the account's pages of the same type; `custom_domain` is rejected for internal pages.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "href": "/en/api-reference/on-call/status-pages/status-page-update",
+          "metadata": {
+            "sidebarTitle": "Update status page"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -63350,6 +65518,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -63357,62 +65528,65 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Update status page",
-        "tags": [
-          "On-call/Status pages"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Status Pages Manage** (`on-call`) |",
-          "href": "/en/api-reference/on-call/status-pages/status-page-update",
-          "metadata": {
-            "sidebarTitle": "Update status page"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/UpdateStatusPageRequest"
+              },
+              "example": {
+                "page_id": 5750613685214,
+                "name": "Flashduty Status Page (Updated)",
+                "page_header": "Updated status page header",
+                "contact_info": "mailto:support@example.com"
+              }
+            }
           }
         }
       }
     },
     "/team/delete": {
       "post": {
-        "description": "Permanently delete a team by ID, name, or external reference ID.",
         "operationId": "team-write-delete",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "team_id": 1001
-              },
-              "schema": {
-                "$ref": "#/components/schemas/TeamDeleteRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "Delete a team",
+        "description": "Delete a team by ID, name, or external reference ID and remove all of its members.",
+        "tags": [
+          "Platform/Teams"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Teams Manage** (`organization`) |\n\n## Usage\n\n- Provide one of `team_id`, `team_name`, or `ref_id`; when several are sent, `team_id` wins, then `team_name`, then `ref_id`.\n- Besides the permission above, the caller must be a member of the team, its creator, the account owner, or hold the Admin role; otherwise the call returns `403 AccessDenied`.\n- Fails with `400 ReferenceExist` while the team is still referenced by escalation rules, schedules, channels, notification templates, mapping schemas, service calendars, or the default teams of the SSO configuration; `data.refs` lists each reference (`kind`, `name`, `href`).\n- Deletion is soft: all members are removed from the team, the team disappears from lists and name/`ref_id` lookups, its name can be reused, and `POST /team/info` by `team_id` still returns it with `status` `deleted`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "href": "/en/api-reference/platform/teams/team-write-delete",
+          "metadata": {
+            "sidebarTitle": "Delete a team"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/PlatformEmptyObject"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -63430,79 +65604,79 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Delete a team",
-        "tags": [
-          "Platform/Teams"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Teams Manage** (`organization`) |\n\n## Usage\n\n- At least one of `team_id`, `team_name`, or `ref_id` must be provided.\n- Fails with `400 ReferenceExist` if the team is still referenced by schedules, escalation rules, or other resources.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
-          "href": "/en/api-reference/platform/teams/team-write-delete",
-          "metadata": {
-            "sidebarTitle": "Delete a team"
-          }
-        }
-      }
-    },
-    "/team/info": {
-      "post": {
-        "description": "Return a single team by ID, name, or external reference ID.",
-        "operationId": "team-read-info",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/TeamDeleteRequest"
+              },
               "example": {
                 "team_id": 1001
-              },
-              "schema": {
-                "$ref": "#/components/schemas/TeamInfoRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/team/info": {
+      "post": {
+        "operationId": "team-read-info",
+        "summary": "Get team detail",
+        "description": "Return a single team by ID, name, or external reference ID.",
+        "tags": [
+          "Platform/Teams"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Provide one of `team_id`, `team_name`, or `ref_id`; when several are sent, `ref_id` wins over `team_name`, which wins over `team_id`.\n- Lookups by `team_name` or `ref_id` only match non-deleted teams; a lookup by `team_id` also returns a deleted team, with `status` `deleted`.\n- When no team matches, the call returns `400 InvalidParameter`.",
+          "href": "/en/api-reference/platform/teams/team-read-info",
+          "metadata": {
+            "sidebarTitle": "Get team detail"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "account_id": 10023,
-                    "created_at": 1710000000,
-                    "creator_id": 80011,
-                    "creator_name": "alice",
-                    "description": "Backend reliability engineering team",
-                    "person_ids": [
-                      80011,
-                      80012
-                    ],
-                    "ref_id": "",
-                    "status": "enabled",
-                    "team_id": 1001,
-                    "team_name": "Backend SRE",
-                    "updated_at": 1712000000,
-                    "updated_by": 80011,
-                    "updated_by_name": "alice"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/TeamItem"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "account_id": 10023,
+                    "team_id": 1001,
+                    "team_name": "Backend SRE",
+                    "description": "Backend reliability engineering team",
+                    "status": "enabled",
+                    "updated_by_name": "alice",
+                    "updated_by": 80011,
+                    "creator_id": 80011,
+                    "creator_name": "",
+                    "created_at": 1710000000,
+                    "updated_at": 1712000000,
+                    "person_ids": [
+                      80011,
+                      80012
+                    ],
+                    "ref_id": ""
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -63510,6 +65684,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -63517,83 +65694,80 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Get team detail",
-        "tags": [
-          "Platform/Teams"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- At least one of `team_id`, `team_name`, or `ref_id` must be provided.",
-          "href": "/en/api-reference/platform/teams/team-read-info",
-          "metadata": {
-            "sidebarTitle": "Get team detail"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/TeamInfoRequest"
+              },
+              "example": {
+                "team_id": 1001
+              }
+            }
           }
         }
       }
     },
     "/team/infos": {
       "post": {
-        "description": "Return basic info for multiple teams by their IDs in a single request.",
         "operationId": "team-read-infos",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "team_ids": [
-                  1001,
-                  1002
-                ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/TeamInfosRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "Batch get teams",
+        "description": "Return basic info for multiple teams by their IDs in a single request.",
+        "tags": [
+          "Platform/Teams"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Duplicate IDs are deduplicated; IDs that match no team in the account are ignored.\n- Deleted teams are still returned (with an empty `person_ids`), so team IDs stored in older records still resolve to a name.\n- When no ID matches, `items` is `null`.",
+          "href": "/en/api-reference/platform/teams/team-read-infos",
+          "metadata": {
+            "sidebarTitle": "Batch get teams"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/TeamInfosResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "items": [
                       {
+                        "team_id": 1001,
+                        "team_name": "Backend SRE",
                         "person_ids": [
                           80011,
                           80012
-                        ],
-                        "team_id": 1001,
-                        "team_name": "Backend SRE"
+                        ]
                       },
                       {
+                        "team_id": 1002,
+                        "team_name": "Frontend",
                         "person_ids": [
                           80013
-                        ],
-                        "team_id": 1002,
-                        "team_name": "Frontend"
+                        ]
                       }
                     ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/TeamInfosResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -63601,6 +65775,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -63608,88 +65785,89 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Batch get teams",
-        "tags": [
-          "Platform/Teams"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Duplicate IDs are deduplicated; IDs that match no team are ignored.",
-          "href": "/en/api-reference/platform/teams/team-read-infos",
-          "metadata": {
-            "sidebarTitle": "Batch get teams"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/TeamInfosRequest"
+              },
+              "example": {
+                "team_ids": [
+                  1001,
+                  1002
+                ]
+              }
+            }
           }
         }
       }
     },
     "/team/list": {
       "post": {
-        "description": "Return a paginated list of teams in the current account.",
         "operationId": "team-read-list",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "asc": false,
-                "limit": 20,
-                "orderby": "created_at",
-                "p": 1
-              },
-              "schema": {
-                "$ref": "#/components/schemas/TeamListRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "List teams",
+        "description": "Return a paginated list of teams in the current account.",
+        "tags": [
+          "Platform/Teams"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Filter by `person_id` to return only the teams that person belongs to; `query` matches a substring of the team name or description.\n- Deleted teams are never listed.",
+          "href": "/en/api-reference/platform/teams/team-read-list",
+          "metadata": {
+            "sidebarTitle": "List teams"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "items": [
-                      {
-                        "account_id": 10023,
-                        "created_at": 1710000000,
-                        "creator_id": 80011,
-                        "creator_name": "alice",
-                        "description": "",
-                        "person_ids": [
-                          80011
-                        ],
-                        "ref_id": "",
-                        "status": "enabled",
-                        "team_id": 1001,
-                        "team_name": "Backend SRE",
-                        "updated_at": 1712000000,
-                        "updated_by": 0,
-                        "updated_by_name": ""
-                      }
-                    ],
-                    "limit": 20,
-                    "p": 1,
-                    "total": 5
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/TeamListResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "p": 1,
+                    "limit": 20,
+                    "total": 1,
+                    "items": [
+                      {
+                        "account_id": 10023,
+                        "team_id": 1001,
+                        "team_name": "Backend SRE",
+                        "description": "Backend reliability engineering team",
+                        "status": "enabled",
+                        "updated_by_name": "alice",
+                        "updated_by": 80011,
+                        "creator_id": 80011,
+                        "creator_name": "",
+                        "created_at": 1710000000,
+                        "updated_at": 1712000000,
+                        "person_ids": [
+                          80011,
+                          80012
+                        ],
+                        "ref_id": ""
+                      }
+                    ]
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -63697,6 +65875,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -63704,70 +65885,68 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "List teams",
-        "tags": [
-          "Platform/Teams"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Filter by `person_id` to return teams that a specific person belongs to.\n- Defaults: p=1, limit=20.",
-          "href": "/en/api-reference/platform/teams/team-read-list",
-          "metadata": {
-            "sidebarTitle": "List teams"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/TeamListRequest"
+              },
+              "example": {
+                "p": 1,
+                "limit": 20,
+                "orderby": "created_at",
+                "asc": false
+              }
+            }
           }
         }
       }
     },
     "/team/upsert": {
       "post": {
-        "description": "Create a new team or update an existing one. Pass `team_id` to update.",
         "operationId": "team-write-upsert",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "description": "Backend reliability engineering team",
-                "person_ids": [
-                  80011,
-                  80012
-                ],
-                "team_name": "Backend SRE"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/TeamUpsertRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "Create or update a team",
+        "description": "Create a new team or update an existing one. Pass `team_id` to update.",
+        "tags": [
+          "Platform/Teams"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Teams Manage** (`organization`) |\n\n## Usage\n\n- Omit `team_id` (or set it to 0) to create a team; pass an existing `team_id` to update it. A `team_id` that matches no team returns `400`.\n- `team_name` must be unique among the account's teams. A name used by another team returns `400`, except when `team_id` is 0 and `reset_if_name_exist` is true — then that team is updated.\n- Membership is always replaced: the team's members become exactly the union of `person_ids`, `emails`, and `phones`. Omitting all three on an update removes every member.\n- Entries that do not resolve to a member of the account (or the account owner) are silently dropped; nobody is invited.\n- On update, `description` and `ref_id` are overwritten as well — omitting them clears the stored values.\n- Updating also requires the caller to be a team member, the team creator, the account owner, or hold the Admin role.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "href": "/en/api-reference/platform/teams/team-write-upsert",
+          "metadata": {
+            "sidebarTitle": "Create or update a team"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "team_id": 1001,
-                    "team_name": "Backend SRE"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/TeamUpsertResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "team_id": 1001,
+                    "team_name": "Backend SRE"
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -63785,69 +65964,70 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Create or update a team",
-        "tags": [
-          "Platform/Teams"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Teams Manage** (`organization`) |\n\n## Usage\n\n- Omit `team_id` (or set to 0) to create a new team; pass an existing ID to update.\n- `team_name` must be 1–39 characters and unique within the account.\n- Pass `person_ids` to set team membership; this replaces the entire member list.\n- Pass `emails` or `phones` to add existing members by contact; contacts that match no member are ignored — nobody is invited.\n- `ref_id` is an external identifier for integration with third-party HR systems.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
-          "href": "/en/api-reference/platform/teams/team-write-upsert",
-          "metadata": {
-            "sidebarTitle": "Create or update a team"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/TeamUpsertRequest"
+              },
+              "example": {
+                "team_name": "Backend SRE",
+                "description": "Backend reliability engineering team",
+                "person_ids": [
+                  80011,
+                  80012
+                ]
+              }
+            }
           }
         }
       }
     },
     "/template/create": {
       "post": {
-        "description": "Create a new notification template.",
         "operationId": "template-write-create",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "description": "Default template for production incidents.",
-                "email": "Incident {{ .IncidentName }} on {{ .Severity }}",
-                "sms": "[Flashduty] {{ .IncidentName }} — {{ .Severity }}",
-                "team_id": 0,
-                "template_name": "Prod incident default"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/TemplateCreateRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "Create a template",
+        "description": "Create a notification template with per-channel message sources.",
+        "tags": [
+          "On-call/Notification templates"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Templates Manage** (`on-call`) |\n\n## Usage\n\n- Requires the Pro plan or higher; otherwise `NoLicense`.\n- `template_name` must be unique among the account's non-deleted templates and must not equal the built-in preset template's name in any supported language; otherwise `InvalidParameter`.\n- Every non-empty channel source is test-rendered against a mock incident; a template error in any channel fails the whole request with `InvalidParameter`. With `wecom_markdown_v2_enabled` = `true`, the rendered `wecom` content must be at most 4,096 bytes.\n- Channels left empty use the built-in preset content when notifications are sent.\n- A non-zero `team_id` must be an existing team; otherwise `InvalidParameter`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "href": "/en/api-reference/on-call/notification-templates/template-write-create",
+          "metadata": {
+            "sidebarTitle": "Create a template"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "template_id": "6605a1b2c3d4e5f6a7b8c9d0",
-                    "template_name": "Prod incident default"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/TemplateCreateResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "template_id": "6605a1b2c3d4e5f6a7b8c9d0",
+                    "template_name": "Prod incident default"
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -63855,6 +66035,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -63862,62 +66045,66 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Create a template",
-        "tags": [
-          "On-call/Notification templates"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Templates Manage** (`on-call`) |\n\n## Usage\n\n- `template_name` must be unique within the account; duplicates return `InvalidParameter`.\n- The server validates every non-empty channel template by rendering it against a mock incident — a syntactic error in any channel fails the whole request with `InvalidParameter`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
-          "href": "/en/api-reference/on-call/notification-templates/template-write-create",
-          "metadata": {
-            "sidebarTitle": "Create a template"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/TemplateCreateRequest"
+              },
+              "example": {
+                "team_id": 0,
+                "template_name": "Prod incident default",
+                "description": "Default template for production incidents.",
+                "email": "Incident {{.Title}} is {{.IncidentSeverity}}",
+                "sms": "[Flashduty] {{.Title}} - {{.IncidentSeverity}}"
+              }
+            }
           }
         }
       }
     },
     "/template/delete": {
       "post": {
-        "description": "Soft-delete a template by ID.",
         "operationId": "template-write-delete",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "template_id": "6605a1b2c3d4e5f6a7b8c9d0"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/TemplateIDRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "Delete a template",
+        "description": "Soft-delete a notification template by ID.",
+        "tags": [
+          "On-call/Notification templates"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Templates Manage** (`on-call`) |\n\n## Usage\n\n- If an escalation rule still uses the template, the call returns HTTP 400 `ReferenceExist` with `data.refs` (`kind` = `escalate_rule`, the rule `name`, a console `href`).\n- The template's `status` becomes `deleted`: it disappears from `/template/list` and its name can be reused, but `/template/info` still returns it.\n- An unknown or already-deleted `template_id` returns `InvalidParameter`.\n- Only an account admin, the template creator, or a member of the template's owning team may call this; others get `AccessDenied`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "href": "/en/api-reference/on-call/notification-templates/template-write-delete",
+          "metadata": {
+            "sidebarTitle": "Delete a template"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyObject"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -63935,87 +66122,95 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Delete a template",
-        "tags": [
-          "On-call/Notification templates"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Templates Manage** (`on-call`) |\n\n## Usage\n\n- Fails with `400 ReferenceExist` if the template is still referenced by any channel, escalation rule, or notification subscription.\n- Deletion is soft — `deleted_at` is set. The record remains for audit, but the template stops appearing in listings.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
-          "href": "/en/api-reference/on-call/notification-templates/template-write-delete",
-          "metadata": {
-            "sidebarTitle": "Delete a template"
-          }
-        }
-      }
-    },
-    "/template/info": {
-      "post": {
-        "description": "Return a single notification template by ID.",
-        "operationId": "template-read-info",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {
-                "template_id": "6605a1b2c3d4e5f6a7b8c9d0"
-              },
               "schema": {
                 "$ref": "#/components/schemas/TemplateIDRequest"
+              },
+              "example": {
+                "template_id": "6605a1b2c3d4e5f6a7b8c9d0"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/template/info": {
+      "post": {
+        "operationId": "template-read-info",
+        "summary": "Get template detail",
+        "description": "Return a single notification template by ID.",
+        "tags": [
+          "On-call/Notification templates"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Templates Read** (`on-call`) or **Templates Manage** (`on-call`) |\n\n## Usage\n\n- Pass `6321aad26c12104586a88916` as `template_id` to get the built-in preset template: its channel contents are in the account language, its name and description in the caller's language.\n- An unknown `template_id` returns `InvalidParameter`. A soft-deleted template is still returned, with `status` = `deleted`.",
+          "href": "/en/api-reference/on-call/notification-templates/template-read-info",
+          "metadata": {
+            "sidebarTitle": "Get template detail"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "account_id": 10023,
-                    "created_at": 1712700000,
-                    "creator_id": 80011,
-                    "description": "Default template for production incidents.",
-                    "dingtalk": "",
-                    "dingtalk_app": "",
-                    "email": "Incident {{ .IncidentName }} on {{ .Severity }}",
-                    "feishu": "",
-                    "feishu_app": "",
-                    "slack": "",
-                    "slack_app": "",
-                    "sms": "[Flashduty] {{ .IncidentName }} — {{ .Severity }}",
-                    "status": "enabled",
-                    "team_id": 0,
-                    "teams_app": "",
-                    "telegram": "",
-                    "template_id": "6605a1b2c3d4e5f6a7b8c9d0",
-                    "template_name": "Prod incident default",
-                    "updated_at": 1712702400,
-                    "updated_by": 80011,
-                    "voice": "",
-                    "wecom": "",
-                    "wecom_app": "",
-                    "zoom": ""
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/TemplateItem"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "account_id": 10023,
+                    "team_id": 0,
+                    "template_id": "6605a1b2c3d4e5f6a7b8c9d0",
+                    "template_name": "Prod incident default",
+                    "description": "Default template for production incidents.",
+                    "email": "Incident {{.Title}} is {{.IncidentSeverity}}",
+                    "sms": "[Flashduty] {{.Title}} - {{.IncidentSeverity}}",
+                    "voice": "",
+                    "dingtalk": "",
+                    "wecom": "",
+                    "feishu": "",
+                    "feishu_app": "",
+                    "dingtalk_app": "",
+                    "wecom_app": "",
+                    "slack_app": "",
+                    "teams_app": "",
+                    "telegram": "",
+                    "slack": "",
+                    "zoom": "",
+                    "wecom_markdown_v2_enabled": false,
+                    "feishu_app_card_v2_table_enabled": false,
+                    "feishu_app_card_v2_preserve_blank_lines": false,
+                    "feishu_app_war_room_enabled": false,
+                    "dingtalk_app_war_room_enabled": false,
+                    "slack_app_war_room_enabled": false,
+                    "incident_card_closed_action_apps": [],
+                    "incident_card_hidden_fields": {},
+                    "status": "enabled",
+                    "creator_id": 80011,
+                    "updated_by": 80011,
+                    "created_at": 1712700000,
+                    "updated_at": 1712702400
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -64023,6 +66218,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -64030,97 +66228,101 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Get template detail",
-        "tags": [
-          "On-call/Notification templates"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Templates Read** (`on-call`) |\n\n## Usage\n\n- Pass `000000000000000000000001` as `template_id` to retrieve the built-in preset template for the caller's account locale.",
-          "href": "/en/api-reference/on-call/notification-templates/template-read-info",
-          "metadata": {
-            "sidebarTitle": "Get template detail"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/TemplateIDRequest"
+              },
+              "example": {
+                "template_id": "6605a1b2c3d4e5f6a7b8c9d0"
+              }
+            }
           }
         }
       }
     },
     "/template/list": {
       "post": {
-        "description": "Return a paginated list of notification templates.",
         "operationId": "template-read-list",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "asc": false,
-                "is_my_team": false,
-                "limit": 20,
-                "orderby": "updated_at",
-                "p": 1
-              },
-              "schema": {
-                "$ref": "#/components/schemas/TemplateListRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "List templates",
+        "description": "Return a paginated list of notification templates.",
+        "tags": [
+          "On-call/Notification templates"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Read** (`on-call`) or **Channels Manage** (`on-call`) or **Templates Read** (`on-call`) or **Templates Manage** (`on-call`) |\n\n## Usage\n\n- The first page always starts with the built-in preset template (`template_id` `6321aad26c12104586a88916`), whatever the filters; it is also counted in `total`.\n- Results are sorted by `orderby` (default `created_at`), newest first unless `asc` is `true`. Soft-deleted templates are excluded.\n- `is_my_team: true` limits results to templates of the caller's teams; with `team_ids` also sent, only the teams in both lists are kept. If that intersection is empty, no team filter is applied and templates of all teams are returned. If the caller belongs to no team, the response is empty (`total` = 0, no preset).\n- `query` is a case-insensitive regular expression on `template_name`; an invalid expression is matched as literal text.",
+          "href": "/en/api-reference/on-call/notification-templates/template-read-list",
+          "metadata": {
+            "sidebarTitle": "List templates"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/TemplateListResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
+                    "total": 47,
                     "has_next_page": true,
                     "items": [
                       {
                         "account_id": 10023,
-                        "created_at": 1712700000,
-                        "creator_id": 80011,
+                        "team_id": 0,
+                        "template_id": "6605a1b2c3d4e5f6a7b8c9d0",
+                        "template_name": "Prod incident default",
                         "description": "Default template for production incidents.",
+                        "email": "Incident {{.Title}} is {{.IncidentSeverity}}",
+                        "sms": "[Flashduty] {{.Title}} - {{.IncidentSeverity}}",
+                        "voice": "",
                         "dingtalk": "",
-                        "dingtalk_app": "",
-                        "email": "Incident {{ .IncidentName }} on {{ .Severity }}",
+                        "wecom": "",
                         "feishu": "",
                         "feishu_app": "",
-                        "slack": "",
+                        "dingtalk_app": "",
+                        "wecom_app": "",
                         "slack_app": "",
-                        "sms": "[Flashduty] {{ .IncidentName }} — {{ .Severity }}",
-                        "status": "enabled",
-                        "team_id": 0,
                         "teams_app": "",
                         "telegram": "",
-                        "template_id": "6605a1b2c3d4e5f6a7b8c9d0",
-                        "template_name": "Prod incident default",
-                        "updated_at": 1712702400,
+                        "slack": "",
+                        "zoom": "",
+                        "wecom_markdown_v2_enabled": false,
+                        "feishu_app_card_v2_table_enabled": false,
+                        "feishu_app_card_v2_preserve_blank_lines": false,
+                        "feishu_app_war_room_enabled": false,
+                        "dingtalk_app_war_room_enabled": false,
+                        "slack_app_war_room_enabled": false,
+                        "incident_card_closed_action_apps": [],
+                        "incident_card_hidden_fields": {},
+                        "status": "enabled",
+                        "creator_id": 80011,
                         "updated_by": 80011,
-                        "voice": "",
-                        "wecom": "",
-                        "wecom_app": "",
-                        "zoom": ""
+                        "created_at": 1712700000,
+                        "updated_at": 1712702400
                       }
-                    ],
-                    "total": 47
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/TemplateListResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                    ]
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -64128,6 +66330,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -64135,79 +66340,106 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "List templates",
-        "tags": [
-          "On-call/Notification templates"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Templates Read** (`on-call`) or **Templates Manage** (`on-call`) |\n\n## Usage\n\n- Pagination defaults to page 1 with 20 rows. The response's `has_next_page` tells you whether another page exists without needing a separate count request.\n- When `is_my_team` is `true`, `team_ids` is ignored.",
-          "href": "/en/api-reference/on-call/notification-templates/template-read-list",
-          "metadata": {
-            "sidebarTitle": "List templates"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/TemplateListRequest"
+              },
+              "example": {
+                "p": 1,
+                "limit": 20,
+                "orderby": "updated_at",
+                "asc": false,
+                "is_my_team": false
+              }
+            }
           }
         }
       }
     },
     "/template/preview": {
       "post": {
-        "description": "Render a notification template against incident data or mock data and return the output.",
         "operationId": "template-read-preview",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "content": "Incident {{.Title}} is {{.Status}}",
-                "incident_card_hidden_fields": {
-                  "feishu_app": [
-                    "responders"
-                  ]
-                },
-                "incident_id": "664a1b2c3d4e5f6a7b8c9d0e",
-                "type": "feishu_app"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/PreviewTemplateRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "Preview template",
+        "description": "Render a template source against an incident or mock data and return what the channel would send.",
+        "tags": [
+          "On-call/Notification templates"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **100 requests/minute**; **5 requests/second** per account |\n| Permissions | **Templates Read** (`on-call`) or **Templates Manage** (`on-call`) |\n\n## Usage\n\n- Renders against `incident_id` when given (it must exist in the account, otherwise `InvalidParameter`), or against a mock incident. Empty `content` previews the channel's built-in preset.\n- A template error is not an HTTP error: the response has `success: false` and `message` explains why.\n- `card` describes the message frame around the rendered template (email subject, IM app card elements and buttons) for `email`, `feishu_app`, `dingtalk_app`, `wecom_app`, `slack_app` and `teams_app`; it is omitted for other types. Buttons that need an integration (AI analysis, war room) are not shown.\n- `incident_card_hidden_fields` applies to IM app cards; unsupported app types or field names return `InvalidParameter`.\n- Nothing is sent or saved.",
+          "href": "/en/api-reference/on-call/notification-templates/template-read-preview",
+          "metadata": {
+            "sidebarTitle": "Preview template"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "content": "Incident Database latency spike is Critical",
-                    "fixed_fields": [
-                      {
-                        "field": "channel",
-                        "value": "Payment Alerts"
-                      }
-                    ],
-                    "message": "",
-                    "success": true
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/PreviewTemplateResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "success": true,
+                    "content": "**Database latency spike** is Critical",
+                    "message": "",
+                    "card": {
+                      "title": "Database latency spike",
+                      "elements": [
+                        {
+                          "type": "template"
+                        },
+                        {
+                          "type": "divider"
+                        },
+                        {
+                          "type": "actions",
+                          "actions": [
+                            {
+                              "text": "Acknowledge",
+                              "style": "primary"
+                            },
+                            {
+                              "text": "Resolve",
+                              "style": "danger"
+                            },
+                            {
+                              "text": "Snooze",
+                              "style": "select"
+                            }
+                          ]
+                        }
+                      ]
+                    },
+                    "blocks": [
+                      {
+                        "type": "markdown",
+                        "content": "**Database latency spike** is Critical"
+                      }
+                    ],
+                    "size_bytes": 38,
+                    "size_limit_bytes": 30720
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -64215,6 +66447,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -64222,66 +66457,69 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Preview template",
-        "tags": [
-          "On-call/Notification templates"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **60 requests/minute**; **10 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- `incident_card_hidden_fields` applies only to supported IM-card previews; unsupported app types or field names return `InvalidParameter`.\n- `fixed_fields` is returned only when the selected IM preview has a non-empty fixed incident-card value.",
-          "href": "/en/api-reference/on-call/notification-templates/template-read-preview",
-          "metadata": {
-            "sidebarTitle": "Preview template"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PreviewTemplateRequest"
+              },
+              "example": {
+                "content": "**{{.Title}}** is {{.IncidentSeverity}}",
+                "type": "feishu_app",
+                "incident_id": "664a1b2c3d4e5f6a7b8c9d0e",
+                "incident_card_hidden_fields": {
+                  "feishu_app": [
+                    "responders"
+                  ]
+                }
+              }
+            }
           }
         }
       }
     },
     "/template/update": {
       "post": {
-        "description": "Update an existing template. Only the fields present in the request are written: a channel you omit keeps its current content, and an explicit empty string clears it.",
         "operationId": "template-write-update",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "description": "Updated description.",
-                "email": "Incident {{ .IncidentName }} on {{ .Severity }}",
-                "sms": "[Flashduty] {{ .IncidentName }} — {{ .Severity }}",
-                "template_id": "6605a1b2c3d4e5f6a7b8c9d0",
-                "template_name": "Prod incident default"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/TemplateUpdateRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "Update a template",
+        "description": "Update a notification template; only the fields present in the request are written.",
+        "tags": [
+          "On-call/Notification templates"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Templates Manage** (`on-call`) |\n\n## Usage\n\n- `template_name` is required on every call and always written. Other fields left out keep their current values; a channel sent as an empty string is cleared, and notifications on that channel then use the built-in preset content.\n- Every non-empty channel source in the request is test-rendered against a mock incident; a template error fails the whole request with `InvalidParameter`. While `wecom_markdown_v2_enabled` is `true`, the rendered `wecom` content must be at most 4,096 bytes.\n- `incident_card_hidden_fields` and `incident_card_closed_action_apps`, when sent, replace the stored value as a whole.\n- An unknown `template_id` returns `InvalidParameter`; a new `template_name` must not be used by another template.\n- Only an account admin, the template creator, or a member of the template's owning team may call this; others get `AccessDenied`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "href": "/en/api-reference/on-call/notification-templates/template-write-update",
+          "metadata": {
+            "sidebarTitle": "Update a template"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyObject"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -64299,82 +66537,85 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Update a template",
-        "tags": [
-          "On-call/Notification templates"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Templates Manage** (`on-call`) |\n\n## Usage\n\n- Only the fields present in the request are written. A channel you omit keeps its current content; send it as an empty string to clear it.\n- The caller needs data-permission on the template's team; otherwise the response is `AccessDenied`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
-          "href": "/en/api-reference/on-call/notification-templates/template-write-update",
-          "metadata": {
-            "sidebarTitle": "Update a template"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/TemplateUpdateRequest"
+              },
+              "example": {
+                "template_id": "6605a1b2c3d4e5f6a7b8c9d0",
+                "template_name": "Prod incident default",
+                "description": "Updated description.",
+                "email": "Incident {{.Title}} is {{.IncidentSeverity}}",
+                "sms": "[Flashduty] {{.Title}} - {{.IncidentSeverity}}"
+              }
+            }
           }
         }
       }
     },
     "/webhook/history/detail": {
       "post": {
-        "description": "Retrieve the detailed payload and response for a specific webhook delivery attempt.",
         "operationId": "webhookHistoryDetail",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "event_id": "20260412Xatt9hrXsgmFkBR78WF655",
-                "integration_id": 6113996590131
-              },
-              "schema": {
-                "$ref": "#/components/schemas/GetWebhookHistoryDetailRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "Get webhook delivery detail",
+        "description": "Retrieve the detailed payload and response for a specific webhook delivery attempt.",
+        "tags": [
+          "On-call/Integrations"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Take `event_id` and `integration_id` from a record of `POST /webhook/history/list`; `event_id` starts with the delivery date (`YYYYMMDD`), which the lookup relies on.\n- When no record matches, `data` is an empty object.\n- Returns `InvalidParameter` when delivery history recording is turned off for the deployment.",
+          "href": "/en/api-reference/on-call/integrations/webhook-history-detail",
+          "metadata": {
+            "sidebarTitle": "Get webhook delivery detail"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "attempt": 1,
-                    "channel_id": 2551105804131,
-                    "channel_name": "Production Alerts",
-                    "duration": 132,
-                    "endpoint": "https://example.com/webhook",
-                    "event_id": "20260412Xatt9hrXsgmFkBR78WF655",
-                    "event_time": "2026-04-12 13:31:11.357472",
-                    "event_type": "a_update",
-                    "integration_id": 5321026051131,
-                    "ref_id": "69da3f0ef77b1b51f40e83cc",
-                    "ref_title": "High CPU Usage on host-01",
-                    "request_body": "{\"event_type\":\"a_update\",\"event_id\":\"d789d65951c0532ea9b6a1d99b707054\"}",
-                    "request_headers": "{\"Content-Type\":\"application/json\"}",
-                    "response_body": "{\"ok\":true}",
-                    "response_headers": "{\"Content-Type\":\"application/json\"}",
-                    "status": "success",
-                    "status_code": 200,
-                    "webhook_type": "alert"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/WebhookHistoryDetail"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "integration_id": 5321026051131,
+                    "event_id": "20260412Xatt9hrXsgmFkBR78WF655",
+                    "webhook_type": "alert",
+                    "event_type": "a_update",
+                    "channel_id": 2551105804131,
+                    "ref_id": "69da3f0ef77b1b51f40e83cc",
+                    "request_headers": "{\"Content-Type\":\"application/json\"}",
+                    "request_body": "{\"event_type\":\"a_update\",\"event_id\":\"d789d65951c0532ea9b6a1d99b707054\"}",
+                    "endpoint": "https://example.com/webhook",
+                    "attempt": 1,
+                    "duration": 132,
+                    "status": "success",
+                    "status_code": 200,
+                    "response_headers": "{\"Content-Type\":\"application/json\"}",
+                    "response_body": "{\"ok\":true}",
+                    "event_time": "2026-04-12 13:31:11.357472",
+                    "ref_title": "High CPU Usage on host-01",
+                    "channel_name": "Production Alerts"
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -64382,6 +66623,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -64389,85 +66633,82 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "Get webhook delivery detail",
-        "tags": [
-          "On-call/Integrations"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Integrations Read** (`on-call`) |",
-          "href": "/en/api-reference/on-call/integrations/webhook-history-detail",
-          "metadata": {
-            "sidebarTitle": "Get webhook delivery detail"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/GetWebhookHistoryDetailRequest"
+              },
+              "example": {
+                "event_id": "20260412Xatt9hrXsgmFkBR78WF655",
+                "integration_id": 6113996590131
+              }
+            }
           }
         }
       }
     },
     "/webhook/history/list": {
       "post": {
-        "description": "List the delivery history for outbound webhook notifications.",
         "operationId": "webhookHistoryList",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "end_time": 1775203200000,
-                "integration_id": 6113996590131,
-                "limit": 20,
-                "start_time": 1775116800000,
-                "status": "success"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ListWebhookHistoryRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "List webhook delivery history",
+        "description": "List the delivery history for outbound webhook notifications.",
+        "tags": [
+          "On-call/Integrations"
+        ],
+        "x-mint": {
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- `start_time` and `end_time` are Unix milliseconds.\n- Each record is one delivery of one event to one endpoint; `attempt` counts the HTTP tries, which are retried only on connection errors.\n- Stored request and response headers and bodies are truncated.\n- Pass `search_after_ctx` from the previous response for the next page; it is an empty string on the last page.\n- Returns `InvalidParameter` when delivery history recording is turned off for the deployment.",
+          "href": "/en/api-reference/on-call/integrations/webhook-history-list",
+          "metadata": {
+            "sidebarTitle": "List webhook delivery history"
+          }
         },
         "responses": {
           "200": {
+            "description": "Success",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/ListWebhookHistoryResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "items": [
                       {
-                        "attempt": 1,
-                        "channel_id": 2551105804131,
-                        "duration": 132,
-                        "endpoint": "https://example.com/webhook",
+                        "integration_id": 5321026051131,
                         "event_id": "20260412Xatt9hrXsgmFkBR78WF655",
-                        "event_time": "2026-04-12 13:31:11.357472",
+                        "webhook_type": "alert",
                         "event_type": "a_update",
-                        "integration_id": 5321026051131,
+                        "channel_id": 2551105804131,
                         "ref_id": "69da3f0ef77b1b51f40e83cc",
+                        "endpoint": "https://example.com/webhook",
+                        "attempt": 1,
+                        "duration": 132,
                         "status": "success",
                         "status_code": 200,
-                        "webhook_type": "alert"
+                        "event_time": "2026-04-12 13:31:11.357472"
                       }
                     ],
                     "search_after_ctx": "eyJldmVudF90aW1lIjoiMjAyNi0wNC0xMlQxMzoxNToyNi4zODI1NDcrMDg6MDAiLCJldmVudF9pZCI6IjIwMjYwNDEybUdzeFAzZHJwRmZzNFpDUWQycFNEcCJ9",
                     "total": 346
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/ListWebhookHistoryResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                  }
                 }
               }
-            },
-            "description": "Success"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -64475,6 +66716,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -64482,15 +66726,21 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "List webhook delivery history",
-        "tags": [
-          "On-call/Integrations"
-        ],
-        "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Integrations Read** (`on-call`) |",
-          "href": "/en/api-reference/on-call/integrations/webhook-history-list",
-          "metadata": {
-            "sidebarTitle": "List webhook delivery history"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ListWebhookHistoryRequest"
+              },
+              "example": {
+                "limit": 20,
+                "start_time": 1775116800000,
+                "end_time": 1775203200000,
+                "integration_id": 6113996590131,
+                "status": "success"
+              }
+            }
           }
         }
       }
@@ -64499,12 +66749,12 @@
       "post": {
         "operationId": "memberNotify",
         "summary": "Notify members",
-        "description": "Send an email to account members on behalf of the caller, with content the caller supplies. Only callable with a credential minted for an AI SRE session; any other credential is rejected with `AccessDenied`. Delivery is asynchronous — `accepted` means the email was queued, not that it was delivered.",
+        "description": "Email account members a message written by the calling AI SRE session.",
         "tags": [
           "Platform/Members"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **200 requests/minute**; **10 requests/second** per account |\n| Permissions | None — callable only with an AI SRE session credential; any other credential is rejected with `AccessDenied` |\n\n## Usage\n\n- Recipients that are not active members of the caller's account, or that have no email address on file, are skipped rather than failing the whole request.\n- Whether email is included follows each recipient's own notification preferences for this kind of message; a recipient with no preference set defaults to receiving it.\n- Recipients receive exactly the sanitized `html` as the email body, with nothing added around it. The sender name shows the caller's name followed by \"(via AI SRE)\".\n- Before sending, the server inspects the submitted `html` and rejects the request with `400` / `InvalidParameter` when it contains constructs whose removal would change what recipients see (`<style>`, `<svg>`, `<iframe>`, `<object>`, `<embed>`, `<form>`, `<input>`, `<button>`, an `<img>` with a missing or non-`https` `src`, or an `<a>` whose href scheme is not `http`, `https`, or `mailto`); the error message names each construct and what to change, and nothing is queued — neither the hourly limit nor the per-turn duplicate check is consumed. Tags whose removal does not change rendering (`<script>`, `<meta>`, `<link>`, `<base>`, `on*` handlers) are still sanitized silently and never trigger a rejection.\n- At most 20 emails are delivered to the same recipient through this endpoint per hour; further deliveries to that recipient in the same window are skipped with `rate_limited`.\n- Retrying the same call within the same AI SRE session turn does not send a duplicate email to a recipient who already received one; the repeat is skipped with `duplicate`.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **200 requests/minute**; **10 requests/second** per account |\n| Permissions | None — but see the credential requirement under Usage |\n\n## Usage\n\n- Only callable with a credential minted for an AI SRE session; any other credential is rejected with `AccessDenied`.\n- Delivery is asynchronous — `accepted` means the email was queued, not that it was delivered.\n- Recipients that are not active members of the caller's account, or that have no email address on file, are skipped rather than failing the whole request.\n- Whether email is included follows each recipient's own notification preferences for this kind of message; a recipient with no preference set defaults to receiving it.\n- Recipients receive exactly the sanitized `html` as the email body, with nothing added around it. The sender name shows the caller's name followed by \"(via AI SRE)\".\n- Before sending, the server inspects the submitted `html` and rejects the request with `400` / `InvalidParameter` when it contains constructs whose removal would change what recipients see (`<style>`, `<svg>`, `<iframe>`, `<object>`, `<embed>`, `<form>`, `<input>`, `<button>`, an `<img>` with a missing or non-`https` `src`, or an `<a>` whose href scheme is not `http`, `https`, or `mailto`); the error message names each construct and what to change, and nothing is queued — neither the hourly limit nor the per-turn duplicate check is consumed. Tags whose removal does not change rendering (`<script>`, `<meta>`, `<link>`, `<base>`, `on*` handlers) are still sanitized silently and never trigger a rejection.\n- At most 20 emails are delivered to the same recipient through this endpoint per hour; further deliveries to that recipient in the same window are skipped with `rate_limited`.\n- Retrying the same call within the same AI SRE session turn does not send a duplicate email to a recipient who already received one; the repeat is skipped with `duplicate`.",
           "href": "/en/api-reference/platform/members/member-notify",
           "metadata": {
             "sidebarTitle": "Notify members"
@@ -64608,7 +66858,7 @@
           "Monitors/Dashboards"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Dashboards Manage** (`monit`) |\n\n## Usage\n\n- The caller supplies `dashboard_id`, so a retried request after a timeout fails with `DashboardIDConflict` instead of creating a second dashboard.\n- `definition` is bounded at 1 MiB and the request body at 2 MiB.\n- Audit-logged.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Dashboards Manage** (`monit`) |\n\n## Usage\n\n- The caller generates `dashboard_id` (a lowercase canonical UUIDv7). Retrying after a timeout with the same ID fails with `DashboardIDConflict` (HTTP 409) instead of creating a second dashboard.\n- `folder_id` must be one of the folders the `app_key` owner can access: folders they created or that belong to one of their teams, plus all subfolders of those; the account owner and admins can access every folder; otherwise the call fails with `FolderNotFound` (HTTP 404).\n- A new dashboard starts at `revision` 1; send it as `expected_revision` on the next update, move or delete.\n- An invalid `definition` returns `InvalidParameter` (HTTP 400) whose message lists each violation as `<JSON pointer>: <reason>`. A definition over 1 MiB or over a count limit such as sections per tab, panels, queries or variables, or a request body over 2 MiB, returns `EntityTooLarge` (HTTP 413); a `schema_version` other than `dashboard.v1` returns `UnsupportedSchemaVersion` (HTTP 422).\n- Audit-logged.",
           "href": "/en/api-reference/monitors/dashboards/monit-dashboard-write-create",
           "metadata": {
             "sidebarTitle": "Create dashboard"
@@ -64713,7 +66963,7 @@
                                       "legend_alias": "{{env}} requests",
                                       "query": {
                                         "mode": "range",
-                                        "expr": "sum(rate(http_requests_total{env=\"{{env}}\"}[5m]))",
+                                        "expr": "sum(rate(http_requests_total{env=\"${env}\"}[5m]))",
                                         "args": {},
                                         "min_step_seconds": 30
                                       }
@@ -64847,7 +67097,7 @@
                                   "legend_alias": "{{env}} requests",
                                   "query": {
                                     "mode": "range",
-                                    "expr": "sum(rate(http_requests_total{env=\"{{env}}\"}[5m]))",
+                                    "expr": "sum(rate(http_requests_total{env=\"${env}\"}[5m]))",
                                     "args": {},
                                     "min_step_seconds": 30
                                   }
@@ -64886,7 +67136,7 @@
           "Monitors/Dashboards"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | any valid `app_key`; the result is limited to folders its owner can read |\n\n## Usage\n\n- A dashboard in the trash returns `DashboardDeleted` rather than the definition.\n- This read is not permission-gated beyond folder readability: an `app_key` only sees dashboards in folders its owner can read.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Only dashboards in folders the `app_key` owner can access: folders they created or that belong to one of their teams, plus all subfolders of those; the account owner and admins can access every folder are visible; any other dashboard returns `DashboardNotFound` (HTTP 404).\n- A dashboard in the trash returns `DashboardDeleted` (HTTP 410) instead of its definition; find it with `POST /monit/dashboard/trash/list` and bring it back with `POST /monit/dashboard/restore`.\n- Send the returned `revision` as `expected_revision` on the next update, move or delete.",
           "href": "/en/api-reference/monitors/dashboards/monit-dashboard-read-get",
           "metadata": {
             "sidebarTitle": "Get dashboard detail"
@@ -64991,7 +67241,7 @@
                                       "legend_alias": "{{env}} requests",
                                       "query": {
                                         "mode": "range",
-                                        "expr": "sum(rate(http_requests_total{env=\"{{env}}\"}[5m]))",
+                                        "expr": "sum(rate(http_requests_total{env=\"${env}\"}[5m]))",
                                         "args": {},
                                         "min_step_seconds": 30
                                       }
@@ -65073,7 +67323,7 @@
           "Monitors/Dashboards"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Dashboards Manage** (`monit`) |\n\n## Usage\n\n- The whole definition is sent — this is not a partial update.\n- `expected_revision` must equal the stored revision or the call fails with `DashboardRevisionConflict`.\n- A byte-identical definition sets `changed` to false and does not create a revision.\n- The response `resource` is `null` only if the caller lost read access to the folder during the call.\n- Audit-logged.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Dashboards Manage** (`monit`) |\n\n## Usage\n\n- Send the whole definition; anything left out is removed, not kept from the stored version.\n- `expected_revision` must equal the stored revision, otherwise the call fails with `DashboardRevisionConflict` (HTTP 409); re-read the dashboard and retry.\n- On success `revision` goes up by 1 and a revision entry carrying `message` is recorded. When the normalized definition and `schema_version` equal the stored ones, `changed` is false, `revision` stays the same and no revision entry is recorded.\n- Titles and descriptions are trimmed and an omitted numeric `unit` is stored as `unitless`, so the returned `definition` can differ slightly from the request.\n- A dashboard in the trash returns `DashboardDeleted` (HTTP 410); a dashboard whose folder the caller cannot access returns `AccessDenied`. Validation and size errors are the same as for `POST /monit/dashboard/create`.\n- Audit-logged.",
           "href": "/en/api-reference/monitors/dashboards/monit-dashboard-write-update",
           "metadata": {
             "sidebarTitle": "Update dashboard"
@@ -65180,7 +67430,7 @@
                                         "legend_alias": "{{env}} requests",
                                         "query": {
                                           "mode": "range",
-                                          "expr": "sum(rate(http_requests_total{env=\"{{env}}\"}[5m]))",
+                                          "expr": "sum(rate(http_requests_total{env=\"${env}\"}[5m]))",
                                           "args": {},
                                           "min_step_seconds": 30
                                         }
@@ -65315,7 +67565,7 @@
                                   "legend_alias": "{{env}} requests",
                                   "query": {
                                     "mode": "range",
-                                    "expr": "sum(rate(http_requests_total{env=\"{{env}}\"}[5m]))",
+                                    "expr": "sum(rate(http_requests_total{env=\"${env}\"}[5m]))",
                                     "args": {},
                                     "min_step_seconds": 30
                                   }
@@ -65355,7 +67605,7 @@
           "Monitors/Dashboards"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Dashboards Manage** (`monit`) |\n\n## Usage\n\n- Both the source and the destination folder must be writable.\n- The definition is untouched, so `changed` is false only when the dashboard already sits in `folder_id`.\n- Audit-logged.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Dashboards Manage** (`monit`) |\n\n## Usage\n\n- The caller must be able to access both the current folder and the destination (folders they created or that belong to one of their teams, plus subfolders; the account owner and admins can access every folder). An inaccessible current folder returns `AccessDenied`; a missing or inaccessible destination returns `FolderNotFound` (HTTP 404).\n- The definition is not touched, but a real move still increments `revision` and records a revision entry. If the dashboard is already in `folder_id`, `changed` is false and nothing is written.\n- `expected_revision` must equal the stored revision, otherwise `DashboardRevisionConflict` (HTTP 409); a dashboard in the trash returns `DashboardDeleted` (HTTP 410).\n- Audit-logged.",
           "href": "/en/api-reference/monitors/dashboards/monit-dashboard-write-move",
           "metadata": {
             "sidebarTitle": "Move dashboard"
@@ -65462,7 +67712,7 @@
                                         "legend_alias": "{{env}} requests",
                                         "query": {
                                           "mode": "range",
-                                          "expr": "sum(rate(http_requests_total{env=\"{{env}}\"}[5m]))",
+                                          "expr": "sum(rate(http_requests_total{env=\"${env}\"}[5m]))",
                                           "args": {},
                                           "min_step_seconds": 30
                                         }
@@ -65539,12 +67789,12 @@
       "post": {
         "operationId": "monit-dashboard-write-delete",
         "summary": "Delete dashboard",
-        "description": "Move a dashboard to the trash.",
+        "description": "Move a dashboard to the trash, where it can be restored for 30 days.",
         "tags": [
           "Monitors/Dashboards"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Dashboards Manage** (`monit`) |\n\n## Usage\n\n- The delete is soft: the definition is retained for 30 days and can be brought back with `POST /monit/dashboard/restore`.\n- The returned `revision` is the one recorded for the deletion.\n- Audit-logged.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Dashboards Manage** (`monit`) |\n\n## Usage\n\n- The delete is soft: the dashboard moves to the trash and is permanently removed, with all its revisions, 30 days after deletion. Restore it before then with `POST /monit/dashboard/restore`.\n- Deleting increments `revision`; the returned `revision` is the value to send as `expected_revision` when restoring.\n- `expected_revision` must equal the stored revision, otherwise `DashboardRevisionConflict` (HTTP 409); deleting a dashboard that is already in the trash returns `DashboardDeleted` (HTTP 410).\n- Audit-logged.",
           "href": "/en/api-reference/monitors/dashboards/monit-dashboard-write-delete",
           "metadata": {
             "sidebarTitle": "Delete dashboard"
@@ -65621,7 +67871,7 @@
           "Monitors/Dashboards"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Dashboards Manage** (`monit`) |\n\n## Usage\n\n- Omit `folder_id` to restore into the original folder; if that folder is no longer writable the call fails with `RestoreFolderRequired` and you must name a destination.\n- Restoring a dashboard that is not in the trash fails with `DashboardNotFound`.\n- Audit-logged.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Dashboards Manage** (`monit`) |\n\n## Usage\n\n- Only dashboards in the trash can be restored; any other dashboard returns `DashboardNotFound` (HTTP 404).\n- `expected_revision` must equal the trashed dashboard's current revision (the `revision` returned by delete and shown in the trash listing), otherwise `DashboardRevisionConflict` (HTTP 409).\n- Omit `folder_id` to restore into the original folder. If that folder no longer exists, the account owner and admins get `RestoreFolderRequired` (HTTP 409) and must pass a destination; other members can only restore dashboards whose original folder they can still access and get `DashboardNotFound` otherwise.\n- A missing or inaccessible destination folder returns `FolderNotFound` (HTTP 404). Restoring increments `revision`.\n- Audit-logged.",
           "href": "/en/api-reference/monitors/dashboards/monit-dashboard-write-restore",
           "metadata": {
             "sidebarTitle": "Restore dashboard"
@@ -65726,7 +67976,7 @@
                                       "legend_alias": "{{env}} requests",
                                       "query": {
                                         "mode": "range",
-                                        "expr": "sum(rate(http_requests_total{env=\"{{env}}\"}[5m]))",
+                                        "expr": "sum(rate(http_requests_total{env=\"${env}\"}[5m]))",
                                         "args": {},
                                         "min_step_seconds": 30
                                       }
@@ -65802,12 +68052,12 @@
       "post": {
         "operationId": "monit-dashboard-read-list",
         "summary": "List dashboards",
-        "description": "List the dashboards in one folder.",
+        "description": "List the dashboards stored directly in one folder, with word search and paging.",
         "tags": [
           "Monitors/Dashboards"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | any valid `app_key`; the result is limited to folders its owner can read |\n\n## Usage\n\n- `folder_id` is required; the listing always includes descendant folders.\n- `query` is split on whitespace and matched against title and description.\n- Sort keys are limited to `title` and `updated_at` here, at most two, and default to `updated_at` descending.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Only dashboards stored directly in `folder_id` are returned; dashboards in its subfolders are not included. Use `POST /monit/dashboard/search` to look across folders.\n- `folder_id` must be one of the folders the `app_key` owner can access: folders they created or that belong to one of their teams, plus all subfolders of those; the account owner and admins can access every folder; otherwise the call fails with `FolderNotFound` (HTTP 404). Trashed dashboards are never listed.\n- `query` is split on whitespace; a dashboard matches when every word appears as a substring of its title or description.\n- Sort keys are `title` and `updated_at`, at most two and each used once; the default is `updated_at` descending, and ties are ordered by `dashboard_id`.",
           "href": "/en/api-reference/monitors/dashboards/monit-dashboard-read-list",
           "metadata": {
             "sidebarTitle": "List dashboards"
@@ -65912,7 +68162,7 @@
           "Monitors/Dashboards"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | any valid `app_key`; the result is limited to folders its owner can read |\n\n## Usage\n\n- `query` must contain at least one word; an empty query fails with `InvalidParameter`.\n- Scope is limited to the folders the `app_key` owner can read — this endpoint never widens access.\n- Sort keys are limited to `title` and `updated_at`.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- `query` must contain at least one word; an empty or whitespace-only query fails with `InvalidParameter`. A dashboard matches when every word appears as a substring of its title or description.\n- Results cover only folders the `app_key` owner can access: folders they created or that belong to one of their teams, plus all subfolders of those; the account owner and admins can access every folder. Trashed dashboards are never returned.\n- Sort keys are `title` and `updated_at`, at most two and each used once; the default is `updated_at` descending.",
           "href": "/en/api-reference/monitors/dashboards/monit-dashboard-read-search",
           "metadata": {
             "sidebarTitle": "Search dashboards"
@@ -66016,7 +68266,7 @@
           "Monitors/Dashboards"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Dashboards Manage** (`monit`) |\n\n## Usage\n\n- Sort keys are limited to `title` and `deleted_at` and default to `deleted_at` descending.\n- Unlike the read endpoints this one is gated by Dashboards Manage.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Dashboards Manage** (`monit`) |\n\n## Usage\n\n- Lists trashed dashboards in folders the `app_key` owner can access: folders they created or that belong to one of their teams, plus all subfolders of those; the account owner and admins can access every folder. Each entry is purged permanently 30 days after deletion.\n- Sort keys are `title` and `deleted_at`, at most two and each used once; the default is `deleted_at` descending.\n- Unlike the other dashboard read endpoints, this one requires the Dashboards Manage permission.",
           "href": "/en/api-reference/monitors/dashboards/monit-dashboard-trash-read-list",
           "metadata": {
             "sidebarTitle": "List trashed dashboards"
@@ -66116,7 +68366,7 @@
           "Monitors/Dashboards"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | any valid `app_key`; the result is limited to folders its owner can read |\n\n## Usage\n\n- At most 20 revisions are retained, including the current one; older ones are dropped as new revisions land.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Returns at most the 20 most recent revisions, newest first. Create, every update that changes the definition, move, delete and restore each record a revision; older ones are pruned.\n- `message` is present only on revisions written by `POST /monit/dashboard/update` with a message.\n- Only dashboards in folders the `app_key` owner can access: folders they created or that belong to one of their teams, plus all subfolders of those; the account owner and admins can access every folder are visible, others return `DashboardNotFound` (HTTP 404); a dashboard in the trash returns `DashboardDeleted` (HTTP 410).",
           "href": "/en/api-reference/monitors/dashboards/monit-dashboard-revision-read-list",
           "metadata": {
             "sidebarTitle": "List dashboard revisions"
@@ -66206,7 +68456,7 @@
           "Monitors/Dashboards"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | any valid `app_key`; the result is limited to folders its owner can read |\n\n## Usage\n\n- Revision numbers are per dashboard and start at 1.\n- A revision that has aged out of the 20-entry window returns `DashboardNotFound`.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Revision numbers are per dashboard and start at 1 (the create). Revisions older than the latest 20 are pruned and return `DashboardNotFound` (HTTP 404).\n- Only dashboards in folders the `app_key` owner can access: folders they created or that belong to one of their teams, plus all subfolders of those; the account owner and admins can access every folder are visible; a dashboard in the trash returns `DashboardDeleted` (HTTP 410), so restore it before reading its history.",
           "href": "/en/api-reference/monitors/dashboards/monit-dashboard-revision-read-get",
           "metadata": {
             "sidebarTitle": "Get dashboard revision"
@@ -66307,7 +68557,7 @@
                                       "legend_alias": "{{env}} requests",
                                       "query": {
                                         "mode": "range",
-                                        "expr": "sum(rate(http_requests_total{env=\"{{env}}\"}[5m]))",
+                                        "expr": "sum(rate(http_requests_total{env=\"${env}\"}[5m]))",
                                         "args": {},
                                         "min_step_seconds": 30
                                       }
@@ -66386,7 +68636,7 @@
           "Monitors/Dashboards"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | any valid `app_key`; the result is limited to folders its owner can read |\n\n## Usage\n\n- Use this to render navigation or let an agent find a panel ID before running it — it avoids paying for the full definition.\n- With `target_id` set, only the branch containing that tab, section or panel is returned; an unknown ID fails with `TargetNotFound`.\n- Panel entries carry only the visualization `kind` and the datasource type, never the panel's queries.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Use it to render navigation or to find a panel ID before calling `POST /monit/dashboard/panel/run`, without downloading queries.\n- With `target_id` set to a tab ID the whole tab is returned; a section ID returns that tab with only that section and no top panels; a panel ID returns only that panel inside its tab or section. An unknown ID fails with `TargetNotFound` (HTTP 404).\n- Panel entries carry only the visualization `kind` and the datasource type, never queries. Datasource variables always report `selection` as `single` without `all`.\n- Only dashboards in folders the `app_key` owner can access: folders they created or that belong to one of their teams, plus all subfolders of those; the account owner and admins can access every folder are visible; a dashboard in the trash returns `DashboardDeleted` (HTTP 410).",
           "href": "/en/api-reference/monitors/dashboards/monit-dashboard-read-outline",
           "metadata": {
             "sidebarTitle": "Get dashboard outline"
@@ -66529,7 +68779,7 @@
           "Monitors/Dashboards"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **16 requests/second** (no per-minute cap) per account |\n| Permissions | **Datasources Read** (`monit`) |\n\n## Usage\n\n- A variable that cannot be resolved does not fail the call: its entry carries an `error` and is left out of `selections`.\n- An explicitly empty `values` selection means unresolved — the resolver will not fall back to the stored default.\n- Selections are bounded at 20 variables; names must match `^[A-Za-z_][A-Za-z0-9_]{0,63}$`.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **16 requests/second** per account (no per-minute limit) |\n| Permissions | **Datasources Read** (`monit`) |\n\n## Usage\n\n- Resolves the variables of the current revision of a stored dashboard. `variables` holds the caller's current selections; a variable without an entry falls back to its stored default (`default` for `custom` and `query` variables; for `datasource` variables the `default_datasource_id` if it is still a candidate, otherwise the first candidate ordered by name).\n- A variable that cannot be resolved does not fail the call: its entry carries an `error` and is left out of `selections`. Typical causes are no selection and no default, a selection that is not among the candidates, an unresolved dependency, or an unreachable datasource.\n- An explicitly empty `values` selection means unresolved (`variable_invalid`); the resolver does not fall back to the stored default.\n- Variables are resolved in dependency order, so a variable that depends on a failed variable also reports an error. A name in `variables` that the dashboard does not define fails the call with HTTP 400.\n- Each variable returns at most 1000 candidates, and all candidates together must fit in 8 MiB, otherwise the call fails with `EntityTooLarge` (HTTP 413). `query` variables can only run against Prometheus, MySQL and Loki datasources.\n- The caller must be able to see the dashboard's folder; otherwise the call returns `DashboardNotFound` (HTTP 404). The call has a 35-second overall deadline; exceeding it returns `RuntimeTimeout` (HTTP 504).",
           "href": "/en/api-reference/monitors/dashboards/monit-dashboard-variable-read-resolve",
           "metadata": {
             "sidebarTitle": "Resolve dashboard variables"
@@ -66650,7 +68900,7 @@
           "Monitors/Dashboards"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **16 requests/second** (no per-minute cap) per account |\n| Permissions | **Datasources Read** (`monit`) |\n\n## Usage\n\n- `context` is `new` for a folder that has no dashboard yet, and `existing` for an already stored dashboard; mixing the two fields fails validation.\n- Nothing is persisted, so the response has no `dashboard_id` or `revision`.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **16 requests/second** per account (no per-minute limit) |\n| Permissions | **Datasources Read** (`monit`) |\n\n## Usage\n\n- Resolves a draft variable list that is not stored in a dashboard, so an editor can test variables before saving. Nothing is persisted, so the response has no `dashboard_id` or `revision`.\n- `context.kind` is `existing` with `dashboard_id` when the draft belongs to a stored dashboard, or `new` with `folder_id` when the dashboard does not exist yet; sending the other kind's field fails validation (HTTP 400). The caller needs access to that dashboard's folder or to that folder (otherwise 403/404).\n- The draft `variables` are validated like a stored definition (names, dependencies, option limits, at most 20 variables, 1 MiB); a violation fails the call with HTTP 400, or HTTP 413 when a size limit is exceeded.\n- Resolution behaves like variable resolve: a variable that fails carries an `error` and is absent from `selections`, and an empty `values` selection is unresolved.\n- The call has a 35-second overall deadline; exceeding it returns `RuntimeTimeout` (HTTP 504).",
           "href": "/en/api-reference/monitors/dashboards/monit-dashboard-variable-read-preview",
           "metadata": {
             "sidebarTitle": "Preview draft variables"
@@ -66799,7 +69049,7 @@
           "Monitors/Dashboards"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **16 requests/second** (no per-minute cap) per account |\n| Permissions | **Datasources Read** (`monit`) |\n\n## Usage\n\n- Use this to show which datasource a panel will hit, and with which expression, before spending a query.\n- `panel_ids` accepts 1–100 unique IDs; a panel missing from the dashboard yields a `state: \"error\"` entry instead of failing the whole call.\n- A panel whose queries only partly resolve reports `state: \"partial\"`.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **16 requests/second** per account (no per-minute limit) |\n| Permissions | **Datasources Read** (`monit`) |\n\n## Usage\n\n- Use this to show which datasource a panel will hit, and with which expression, before running it. Nothing is executed.\n- `panel_ids` accepts 1–100 unique IDs, answered in request order. A panel that is not in the dashboard yields `state: \"error\"` with reason `panel_missing` instead of failing the call; a text panel yields `state: \"error\"` with reason `invalid_request`.\n- `state` is `success` when every query of the panel resolved, `partial` when only some did, and `error` when none did. `queries` lists the queries that resolved; `error` reports only the first failure.\n- Built-in time variables (such as the step and the time range) are rendered from `time` and `max_data_points`, unless `preserve_builtin_variables` is `true`, which leaves them verbatim for a caller that renders them with its own window. User variables are always resolved.\n- Panel queries can only be bound to Prometheus, MySQL and Loki datasources. The call has a 35-second overall deadline; exceeding it returns `RuntimeTimeout` (HTTP 504).",
           "href": "/en/api-reference/monitors/dashboards/monit-dashboard-query-read-resolve",
           "metadata": {
             "sidebarTitle": "Resolve panel queries"
@@ -66925,7 +69175,7 @@
           "Monitors/Dashboards"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **16 requests/second** (no per-minute cap) per account |\n| Permissions | **Datasources Read** (`monit`) |\n\n## Usage\n\n- Omitting `revision` runs whatever is current; sending it makes the call reject a stale read instead of returning overwritten data.\n- `run_state` aggregates the per-query states — `partial` when some refs succeeded, `incompatible` when the datasource accepted the call but the query does not fit its type.\n- Each ref's `execution` payload is datasource-specific and passed through unmodified; `child_request_id` traces the underlying datasource call.\n- `max_data_points` defaults to 100 and is bounded at 2–5000. The whole response is capped at 8 MiB.\n- Queries inside one panel run with a concurrency of at most 6.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **32 requests/second** per account (no per-minute limit) |\n| Permissions | **Datasources Read** (`monit`) |\n\n## Usage\n\n- Executes every query of one panel of the current stored dashboard against its datasource. The call returns HTTP 200 even when every query failed; read `run_state` and each ref's `state` and `error`.\n- Omitting `revision` (or sending 0) runs the current revision. Sending it makes the call fail with `DashboardRevisionConflict` (HTTP 409) when the dashboard has changed, instead of returning data for a stale definition.\n- `run_state` summarizes the refs: `success` when all succeeded, `partial` when at least one succeeded and at least one did not, and otherwise `cancelled`, `incompatible` or `error`. A ref is `incompatible` when its query ran but the result does not fit the panel's visualization, for example a configured value field is missing or not numeric.\n- Each ref's `execution` is datasource-specific and passed through unmodified; `child_request_id` identifies the underlying datasource call. Text panels cannot be run (HTTP 400), and an unknown `panel_id` returns `TargetNotFound` (HTTP 404).\n- `max_data_points` defaults to 100 and is bounded at 2–5000. At most 6 queries of one panel run at the same time. A response larger than 8 MiB is rejected with `EntityTooLarge` (HTTP 413) instead of being truncated. The call has a 35-second overall deadline; exceeding it returns `RuntimeTimeout` (HTTP 504).",
           "href": "/en/api-reference/monitors/dashboards/monit-dashboard-panel-read-run",
           "metadata": {
             "sidebarTitle": "Run dashboard panel"
@@ -67086,7 +69336,7 @@
           "Monitors/Dashboards"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **16 requests/second** (no per-minute cap) per account |\n| Permissions | **Datasources Read** (`monit`) |\n\n## Usage\n\n- Use this to validate a panel while the user is still editing it — nothing is written and no revision is created.\n- The draft is still held to the same limits as a saved dashboard: grid overlap, query counts per visualization kind, and the 1 MiB definition ceiling.\n- The response mirrors a panel run minus `dashboard_id`.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **32 requests/second** per account (no per-minute limit) |\n| Permissions | **Datasources Read** (`monit`) |\n\n## Usage\n\n- Use this to check a panel while the user is still editing it: the draft panel and its variables are executed inline, and nothing is written and no revision is created.\n- `context` ties the draft to a stored dashboard (`existing` with `dashboard_id`) or to a folder that has no dashboard yet (`new` with `folder_id`). The caller needs access to that dashboard's folder or to that folder.\n- The draft `panel` and `variables` are validated like a stored definition (grid, query counts per visualization kind, variable references) and must stay within 1 MiB; a violation fails the call with HTTP 400, or HTTP 413 when a size limit is exceeded. Text panels cannot be previewed.\n- The response has the same shape as a panel run, without `dashboard_id` and `revision`. It returns HTTP 200 even when every query failed; read `run_state` and each ref's `state` and `error`.\n- `max_data_points` defaults to 100 and is bounded at 2–5000. At most 6 queries run at the same time. A response larger than 8 MiB is rejected with `EntityTooLarge` (HTTP 413). The call has a 35-second overall deadline; exceeding it returns `RuntimeTimeout` (HTTP 504).",
           "href": "/en/api-reference/monitors/dashboards/monit-dashboard-panel-read-preview",
           "metadata": {
             "sidebarTitle": "Preview draft panel"
@@ -67238,7 +69488,7 @@
                       "legend_alias": "{{env}} requests",
                       "query": {
                         "mode": "range",
-                        "expr": "sum(rate(http_requests_total{env=\"{{env}}\"}[5m]))",
+                        "expr": "sum(rate(http_requests_total{env=\"${env}\"}[5m]))",
                         "args": {},
                         "min_step_seconds": 30
                       }
@@ -67311,7 +69561,7 @@
           "Monitors/Rule folders"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Alerting Rules Read** or **Node Permissions Read** (`monit`) |\n\n## Usage\n\n- The response is a flat list of every readable folder, not a tree: rebuild the hierarchy from `parent_id` and `parent_path`, and search client-side.\n- Dashboards and alert rules both live in this folder tree, so the same IDs appear as `folder_id` on dashboard payloads.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Alerting Rules Read**, **Alerting Rules Manage**, **Node Permissions Read**, or **Node Permissions Manage** (`monit`) |\n\n## Usage\n\n- The response is a flat list of the visible folders, not a tree: rebuild the hierarchy from `parent_id` and `parent_path`, and search client-side. An account with no visible folder gets `[]`.\n- Account owners and admins see every folder. Other members see the folders they created, the folders that belong to one of their teams, everything below those folders, and the ancestor folders needed to reach them.\n- Dashboards and alert rules both live in this folder tree, so the same IDs appear as `folder_id` on dashboard payloads and alert rules.",
           "href": "/en/api-reference/monitors/rule-folders/monit-folder-read-list",
           "metadata": {
             "sidebarTitle": "List monitor folders"
@@ -67369,6 +69619,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -67387,7 +69640,7 @@
           "On-call/Integrations"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Integrations Read** (`on-call`) |\n\n## Usage\n\n- When `orderby` is omitted, types come back in console ranking order and `p`/`limit` still apply.\n- `supports_api_create` tells you which types `POST /integration/create` accepts.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Integrations Read** (`on-call`) |\n\n## Usage\n\n- When `orderby` is omitted, types come back in console ranking order and `p`/`limit` still apply.\n- `supports_api_create` tells you which types `POST /integration/create` accepts.\n- `category` values are not validated; an unknown value returns an empty list.",
           "href": "/en/api-reference/on-call/integrations/integration-api-read-type-list",
           "metadata": {
             "sidebarTitle": "List integration types"
@@ -67448,6 +69701,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -67481,7 +69737,7 @@
           "On-call/Integrations"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Integrations Read** (`on-call`) |\n\n## Usage\n\n- `orderby` defaults to `created_at`; `plugin_type` is sorted by the underlying plugin.\n- `plugin_type`, `status` and `category` accept comma-separated values; `ref_ids` values must start with `c_`, `a_` or `w_`; a `c_` filter is syntactically accepted but does not return channel-owned integrations.\n- With `is_my_team` set, results are limited to your teams and `team_ids` narrows that set further.\n- These APIs manage public (account-level) integrations only, not channel-owned dedicated integrations.\n- Items include `settings`, `integration_key`, `plugin_id`, `account_id`, and the legacy `data_source_id` alias. Saved secret values in `settings` are returned as `******`; `integration_key` is returned as is.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Integrations Read** (`on-call`) |\n\n## Usage\n\n- `orderby` defaults to `created_at`; `plugin_type` sorts by the underlying plugin. Rows are ordered by `ref_id` first, so `orderby` applies within each `ref_id` group.\n- `plugin_type`, `status` and `category` accept comma-separated values; `ref_ids` values must start with `c_`, `a_` or `w_`; a `c_` filter is syntactically accepted but does not return channel-owned integrations.\n- With `is_my_team` set, results are limited to your teams and `team_ids` narrows that set further; when you belong to no team, or `team_ids` shares no team with yours, the list is empty.\n- These APIs manage public (account-level) integrations only, not channel-owned dedicated integrations.\n- Items include `settings`, `integration_key`, `plugin_id`, `account_id`, and the legacy `data_source_id` alias. Saved secret values in `settings` are returned as `******`; `integration_key` is returned as is.",
           "href": "/en/api-reference/on-call/integrations/integration-api-read-list",
           "metadata": {
             "sidebarTitle": "List integrations"
@@ -67553,6 +69809,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -67586,7 +69845,7 @@
           "On-call/Integrations"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Integrations Read** (`on-call`) |\n\n## Usage\n\n- These APIs manage public (account-level) integrations only, not channel-owned dedicated integrations.\n- Saved secret values in `settings` are returned as `******`, and unset ones stay empty. The integration key is returned as is.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Integrations Read** (`on-call`) |\n\n## Usage\n\n- These APIs manage public (account-level) integrations only, not channel-owned dedicated integrations.\n- Saved secret values in `settings` are returned as `******`, and unset ones stay empty. The integration key is returned as is.\n- An unknown ID, or the ID of a channel-owned integration, returns `ResourceNotFound`.",
           "href": "/en/api-reference/on-call/integrations/integration-api-read-info",
           "metadata": {
             "sidebarTitle": "Get integration detail"
@@ -67648,6 +69907,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -67679,7 +69941,7 @@
           "On-call/Integrations"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Integrations Manage** (`on-call`) |\n\n## Usage\n\n- `plugin_type` must be one of the types listed by `POST /integration/type/list` with `supports_api_create: true`; anything else returns `InvalidParameter`.\n- These APIs manage public (account-level) integrations only, not channel-owned dedicated integrations.\n- An omitted `integration_key` is generated automatically; a supplied key must satisfy the length, account suffix, and uniqueness checks.\n- With `is_test: true`, inspect `test.success`; an HTTP 200 response alone does not establish that the plugin test succeeded.\n- Every call is recorded in the account audit log.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Integrations Manage** (`on-call`) |\n\n## Usage\n\n- `plugin_type` must be one of the types listed by `POST /integration/type/list` with `supports_api_create: true`; anything else returns `InvalidParameter`.\n- A type whose `status` is `disabled` returns `InvalidParameter`; a type not included in the account's plan returns `NoLicense`.\n- These APIs manage public (account-level) integrations only, not channel-owned dedicated integrations.\n- An omitted `integration_key` is generated automatically; a supplied key must satisfy the length, account suffix, and uniqueness checks.\n- With `is_test: true`, inspect `test.success`; an HTTP 200 response alone does not establish that the plugin test succeeded.\n- Every call is recorded in the account audit log.",
           "href": "/en/api-reference/on-call/integrations/integration-api-write-create",
           "metadata": {
             "sidebarTitle": "Create integration"
@@ -67725,6 +69987,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -67764,7 +70029,7 @@
           "On-call/Integrations"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Integrations Manage** (`on-call`) |\n\n## Usage\n\n- Only the fields you send are changed; omitted fields keep their current value.\n- Submitting `settings` replaces the configuration; known sensitive fields omitted or sent as `******` retain their value. Keeping a stored secret while changing where it is sent (such as `endpoint`, `url`, a database host or port, or an IM API base URL) is rejected, so send the secrets again with the new destination; `******` on a field with no stored value is rejected too. Send `headers: {}` to clear headers; use the integration type’s explicit empty value to clear a body.\n- Submit `settings` together with `is_test: true` to receive a plugin test result; secrets in the returned settings are masked the same way.\n- These APIs manage public (account-level) integrations only, not channel-owned dedicated integrations.\n- Write access also requires object permission: the account owner, an administrator, the creator, or a member of the assigned team; with no team, members with Integrations Manage may operate. Read-only integrations cannot be changed.\n- Every call is recorded in the account audit log.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Integrations Manage** (`on-call`) |\n\n## Usage\n\n- Only the fields you send are changed; omitted fields keep their current value.\n- Submitting `settings` replaces the configuration; known sensitive fields omitted or sent as `******` retain their value. Keeping a stored secret while changing where it is sent (such as `endpoint`, `url`, a database host or port, or an IM API base URL) is rejected, so send the secrets again with the new destination; `******` on a field with no stored value is rejected too. Send `headers: {}` to clear headers; use the integration type’s explicit empty value to clear a body.\n- Submit `settings` together with `is_test: true` to receive a plugin test result; secrets in the returned settings are masked the same way.\n- If another request changes the same integration's settings while this one is being processed, the call returns `RequestLocked`; retry it. A type no longer included in the account's plan returns `NoLicense`.\n- These APIs manage public (account-level) integrations only, not channel-owned dedicated integrations.\n- Write access also requires object permission: the account owner, an administrator, the creator, or a member of the assigned team; with no team, members with Integrations Manage may operate. Read-only integrations cannot be changed.\n- Every call is recorded in the account audit log.",
           "href": "/en/api-reference/on-call/integrations/integration-api-write-update",
           "metadata": {
             "sidebarTitle": "Update integration"
@@ -67830,6 +70095,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -67907,6 +70175,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -67938,7 +70209,7 @@
           "On-call/Integrations"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Integrations Manage** (`on-call`) |\n\n## Usage\n\n- Enabling an integration resumes its scheduled pull task and heartbeat, and requires the integration type to be available on the current plan.\n- Every call is recorded in the account audit log.\n- These APIs manage public (account-level) integrations only, not channel-owned dedicated integrations.\n- Write access also requires object permission: the account owner, an administrator, the creator, or a member of the assigned team; with no team, members with Integrations Manage may operate. Read-only integrations cannot be changed.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Integrations Manage** (`on-call`) |\n\n## Usage\n\n- Enabling an integration resumes its scheduled pull task and heartbeat, and requires the integration type to be available on the current plan.\n- Enabling an integration that is already enabled succeeds without change; the same holds for disabling a disabled one.\n- Every call is recorded in the account audit log.\n- These APIs manage public (account-level) integrations only, not channel-owned dedicated integrations.\n- Write access also requires object permission: the account owner, an administrator, the creator, or a member of the assigned team; with no team, members with Integrations Manage may operate. Read-only integrations cannot be changed.",
           "href": "/en/api-reference/on-call/integrations/integration-api-write-enable",
           "metadata": {
             "sidebarTitle": "Enable integration"
@@ -67977,6 +70248,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -68008,7 +70282,7 @@
           "On-call/Integrations"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Integrations Manage** (`on-call`) |\n\n## Usage\n\n- Disabling stops event ingestion and pauses the scheduled pull task; settings are kept so the integration can be enabled again.\n- Every call is recorded in the account audit log.\n- These APIs manage public (account-level) integrations only, not channel-owned dedicated integrations.\n- Write access also requires object permission: the account owner, an administrator, the creator, or a member of the assigned team; with no team, members with Integrations Manage may operate. Read-only integrations cannot be changed.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Integrations Manage** (`on-call`) |\n\n## Usage\n\n- Disabling stops event ingestion and pauses the scheduled pull task; settings are kept so the integration can be enabled again.\n- Enabling an integration that is already enabled succeeds without change; the same holds for disabling a disabled one.\n- Every call is recorded in the account audit log.\n- These APIs manage public (account-level) integrations only, not channel-owned dedicated integrations.\n- Write access also requires object permission: the account owner, an administrator, the creator, or a member of the assigned team; with no team, members with Integrations Manage may operate. Read-only integrations cannot be changed.",
           "href": "/en/api-reference/on-call/integrations/integration-api-write-disable",
           "metadata": {
             "sidebarTitle": "Disable integration"
@@ -68047,6 +70321,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -68119,6 +70396,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -68145,12 +70425,12 @@
       "post": {
         "operationId": "monit-folder-read-health",
         "summary": "Get monitor folder health",
-        "description": "Get health summaries for visible folders, including issues in their descendants.",
+        "description": "Get issue flags for the visible monitor folders, including issues in their descendants.",
         "tags": [
           "Monitors/Rule folders"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **30 requests/minute**; **2 requests/second** per account |\n| Permissions | **Alerting Rules Read**, **Alerting Rules Manage**, **Node Permissions Read**, or **Node Permissions Manage** (`monit`) |\n\n## Usage\n\n- Issues include active alerts and alert-rule runtime problems; issues propagate to visible ancestors.\n- This operation scans folder rules and runtime state. Avoid frequent polling.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **30 requests/minute**; **2 requests/second** per account |\n| Permissions | **Alerting Rules Read**, **Alerting Rules Manage**, **Node Permissions Read**, or **Node Permissions Manage** (`monit`) |\n\n## Usage\n\n- `items` has one entry per folder visible to the caller (the same set as `/monit/folder/list`), sorted by `id`.\n- `has_issue` is true when a rule in the folder or in any of its descendants has an active alert or a runtime problem. The issue then also shows on every visible ancestor folder. Only rules in folders the caller can read are counted.\n- This operation scans folder rules and runtime state. Avoid frequent polling.",
           "href": "/en/api-reference/monitors/rule-folders/monit-folder-read-health",
           "metadata": {
             "sidebarTitle": "Get monitor folder health"
@@ -68196,6 +70476,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -68209,12 +70492,12 @@
       "post": {
         "operationId": "monit-folder-write-create",
         "summary": "Create monitor folder",
-        "description": "Create a monitor folder at the root or under an accessible parent folder.",
+        "description": "Create a monitor folder at the root or under a parent folder the caller may modify.",
         "tags": [
           "Monitors/Rule folders"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Alerting Rules Manage** or **Node Permissions Manage** (`monit`) |\n\n## Usage\n\n- Use `parent_id: 0` or omit it to create a root folder. The parent must be accessible.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Alerting Rules Manage** or **Node Permissions Manage** (`monit`) |\n\n## Usage\n\n- Use `parent_id: 0` or omit it to create a root folder. To create under a parent, the caller must be allowed to modify it: an account owner or admin, the creator of the parent or of one of its ancestors, or a member of the team assigned to the parent or one of its ancestors. A parent that does not exist returns `InvalidParameter`; a parent you may not modify returns `AccessDenied`.\n- The response is the created folder.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/monitors/rule-folders/monit-folder-write-create",
           "metadata": {
             "sidebarTitle": "Create monitor folder"
@@ -68267,6 +70550,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -68296,12 +70582,12 @@
       "post": {
         "operationId": "monit-folder-write-update",
         "summary": "Update monitor folder",
-        "description": "Replace the name, note, and team assignment of an accessible monitor folder.",
+        "description": "Replace the name, note, and team assignment of a monitor folder the caller may modify.",
         "tags": [
           "Monitors/Rule folders"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Alerting Rules Manage** or **Node Permissions Manage** (`monit`) |\n\n## Usage\n\n- Send both `id` and `name`. This is a replacement of editable fields: omitting `note` clears it, and omitting `team_id` resets it to 0.\n- Use the move operation to change the parent folder.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Alerting Rules Manage** or **Node Permissions Manage** (`monit`) |\n\n## Usage\n\n- Send both `id` and `name`. This is a replacement of editable fields: omitting `note` clears it, and omitting `team_id` resets it to 0.\n- The caller must be allowed to modify the folder: an account owner or admin, the folder's creator or the creator of one of its ancestors, or a member of the team assigned to the folder or one of its ancestors. A missing folder returns `InvalidParameter`; a folder you may not modify returns `AccessDenied`.\n- Use the move operation to change the parent folder. The response is the updated folder.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/monitors/rule-folders/monit-folder-write-update",
           "metadata": {
             "sidebarTitle": "Update monitor folder"
@@ -68354,6 +70640,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -68388,7 +70677,7 @@
           "Monitors/Rule folders"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Alerting Rules Manage** or **Node Permissions Manage** (`monit`) |\n\n## Usage\n\n- You must have access to both the source and destination folders.\n- `dest_parent_id` is required; send 0 explicitly to move to the root. Moving under the folder itself or a descendant is rejected.\n- Descendant paths are updated in the same transaction.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Alerting Rules Manage** or **Node Permissions Manage** (`monit`) |\n\n## Usage\n\n- The caller must be allowed to modify the source folder and, unless `dest_parent_id` is 0, the destination folder.\n- `dest_parent_id` is required; send 0 explicitly to move to the root. It must differ from `id`, and moving under the folder itself or a descendant is rejected with `InvalidParameter`. Moving a folder to its current parent succeeds without changes.\n- Descendant paths are updated in the same transaction, and the folder and all its descendants record the caller as last updater.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/monitors/rule-folders/monit-folder-write-move",
           "metadata": {
             "sidebarTitle": "Move monitor folder"
@@ -68428,6 +70717,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -68455,12 +70747,12 @@
       "post": {
         "operationId": "monit-folder-write-delete",
         "summary": "Delete monitor folder",
-        "description": "Delete an accessible monitor folder after removing its children, rules, and dashboards.",
+        "description": "Delete an empty monitor folder that the caller may modify.",
         "tags": [
           "Monitors/Rule folders"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Alerting Rules Manage** or **Node Permissions Manage** (`monit`) |\n\n## Usage\n\n- Only empty folders can be deleted. Child folders, alert rules, and dashboards block deletion with HTTP 409 and error code `FolderNotEmpty`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Alerting Rules Manage** or **Node Permissions Manage** (`monit`) |\n\n## Usage\n\n- Only empty folders can be deleted; nothing inside is removed for you. Child folders, alert rules, and dashboards block deletion with HTTP 409 and error code `FolderNotEmpty`.\n- The caller must be allowed to modify the folder. A missing folder returns `InvalidParameter`; a folder you may not modify returns `AccessDenied`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/monitors/rule-folders/monit-folder-write-delete",
           "metadata": {
             "sidebarTitle": "Delete monitor folder"
@@ -68500,6 +70792,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
diff --git a/api-reference/openapi.zh.json b/api-reference/openapi.zh.json
index 91b7dd9b2..230e537da 100644
--- a/api-reference/openapi.zh.json
+++ b/api-reference/openapi.zh.json
@@ -23,25 +23,25 @@
         "description": "请求非法 — 通常是参数缺失或格式不正确。"
       },
       "Forbidden": {
+        "description": "app_key 有效，但其权限范围或创建者角色不允许该操作或该对象。",
         "content": {
           "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/ErrorResponse"
+            },
             "examples": {
               "noEditPermission": {
                 "value": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "error": {
                     "code": "AccessDenied",
                     "message": "Access Denied."
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
+                  }
                 }
               }
-            },
-            "schema": {
-              "$ref": "#/components/schemas/ErrorResponse"
             }
           }
-        },
-        "description": "app_key 有效但没有执行该操作的权限。"
+        }
       },
       "NotFound": {
         "content": {
@@ -107,25 +107,34 @@
         "description": "服务暂时不可用。反馈问题时请附带 request_id。"
       },
       "TooManyRequests": {
+        "description": "触发频率限制（账户级限制或该接口的平台级上限）。请等待响应头 `Flashcat-Request-Rate-Limit-Delay` 给出的秒数后重试。",
         "content": {
           "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/ErrorResponse"
+            },
             "examples": {
               "rateLimited": {
                 "value": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "error": {
                     "code": "RequestTooFrequently",
                     "message": "Request too frequently."
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
+                  }
                 }
               }
-            },
-            "schema": {
-              "$ref": "#/components/schemas/ErrorResponse"
             }
           }
         },
-        "description": "命中限流。可能是全局 API 限流、账户级限流或集成级限流。限流按账户聚合。"
+        "headers": {
+          "Flashcat-Request-Rate-Limit-Delay": {
+            "description": "距当前限流窗口重置的秒数。请求被网关全局保护限流拒绝时不返回该响应头。",
+            "schema": {
+              "type": "integer",
+              "minimum": 0
+            }
+          }
+        }
       },
       "Unauthorized": {
         "content": {
@@ -151,81 +160,87 @@
     },
     "schemas": {
       "A2AAgentCreateRequest": {
+        "type": "object",
         "description": "新建 A2A 智能体的注册参数。",
         "properties": {
           "agent_name": {
-            "description": "智能体显示名称。",
-            "maxLength": 128,
-            "type": "string"
-          },
-          "allow_insecure_oauth_http": {
-            "description": "允许该智能体使用非回环的 HTTP OAuth 发现/元数据端点，而非强制 HTTPS。默认为 false。",
-            "type": "boolean"
-          },
-          "allow_insecure_tls_skip_verify": {
-            "description": "连接到该智能体端点时跳过 TLS 证书验证（自签/私有证书）。默认为 false。",
-            "type": "boolean"
+            "type": "string",
+            "description": "智能体显示名称，会话中按此名称调用智能体。不能包含 `@`，不能是 `general` 或 `explore`，且在其作用域（账户级或单个团队）内唯一。",
+            "maxLength": 128
           },
-          "auth_config": {
-            "additionalProperties": {
-              "type": "string"
-            },
-            "description": "认证配置键值，例如 API key 或 bearer token。键名疑似凭据（包含 KEY、SECRET、TOKEN、PASSWORD 等）的值在响应中会被脱敏。",
-            "type": "object"
+          "instructions": {
+            "type": "string",
+            "description": "远程智能体的自然语言指令：Markdown 文档，可带 `summary` frontmatter，正文非空，最大 50 KiB（51200 字节）。必填 —— 已弃用的 `description` 字段仍保留以兼容旧客户端，若两者同时传入则必须与 `instructions` 完全一致。",
+            "maxLength": 51200
           },
-          "auth_mode": {
-            "description": "认证模式：`shared`（默认）所有用户共享一份凭证；`per_user_secret` 需要 `secret_schema.header_name`；`per_user_oauth` 为每个用户单独进行 OAuth。",
-            "type": "string"
+          "card_url": {
+            "type": "string",
+            "description": "远程智能体卡片的 URL。必须是 host 非空的绝对 `http` 或 `https` URL；不带路径时解析为 `/.well-known/agent-card.json`。若有在线执行环境，会拉取卡片并要求其声明 A2A 1.x 的 `JSONRPC` 或 `HTTP+JSON` 接口。"
           },
           "auth_type": {
-            "description": "访问远程智能体的认证类型：`none`（省略时默认）、`api_key` 或 `bearer`。",
+            "type": "string",
+            "description": "使用共享凭据访问远程智能体时的认证方式：\n- `none`：不发送凭据请求头。\n- `api_key`：把 `auth_config.api_key` 放进 `auth_config.header` 指定名称的请求头。\n- `bearer`：发送 `Authorization: Bearer <auth_config.token>`。\n\n省略时存为空字符串，效果同 `none`。",
             "enum": [
               "none",
               "api_key",
               "bearer"
-            ],
-            "type": "string"
+            ]
           },
-          "card_url": {
-            "description": "远程智能体卡片的 URL。必须是 host 非空的绝对 `http` 或 `https` URL；可达性由执行环境在运行时验证，创建时不检查。",
-            "type": "string"
+          "auth_config": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "string"
+            },
+            "description": "共享凭据键值：`auth_type=api_key` 时使用 `header` 和 `api_key`，`auth_type=bearer` 时使用 `token`。`api_key`、`token`、`client_secret` 的值加密存储，响应中脱敏。"
+          },
+          "streaming": {
+            "type": "boolean",
+            "description": "远程智能体是否支持流式响应。"
+          },
+          "team_id": {
+            "type": "integer",
+            "description": "团队范围：0 = 账户级；>0 = 团队。在账户级创建需要 owner/admin 角色；创建到某个团队需要真实属于该团队。",
+            "format": "int64"
           },
           "environments": {
-            "description": "该智能体可运行的执行环境：`cloud` 和/或 BYOC Runner 的环境 ID 列表。省略或为空表示所有环境。",
+            "type": "array",
             "items": {
               "type": "string"
             },
-            "type": "array"
-          },
-          "instructions": {
-            "description": "远程智能体的自然语言指令：Markdown 文档，可带 `summary` frontmatter，正文非空，最大 50 KiB（51200 字节）。必填 —— 已弃用的 `description` 字段仍保留以兼容旧客户端，若两者同时传入则必须与 `instructions` 完全一致。",
-            "maxLength": 51200,
-            "type": "string"
+            "description": "该智能体可运行的执行环境：`cloud` 和/或 BYOC Runner 的环境 ID 列表。省略或为空表示所有环境。"
           },
-          "oauth_metadata": {
-            "description": "JSON 编码的 OAuth 元数据；由 `per_user_oauth` 模式的 OAuth 发现流程填充。",
-            "type": "string"
+          "auth_mode": {
+            "type": "string",
+            "description": "凭据由谁提供：\n- `shared`（默认，空值等同）：使用保存在智能体上的一份凭据（`auth_type` + `auth_config`），所有调用者共用。\n- `per_user_secret`：每位用户各自保存密钥，放在 `secret_schema.header_name` 指定的请求头中发送。\n- `per_user_oauth`：每位用户各自完成 OAuth 授权，首次使用时完成发现与客户端注册。\n\n`per_user_secret` 要求 `secret_schema` 带非空的 `header_name`；其他取值返回 `InvalidParameter`。",
+            "enum": [
+              "shared",
+              "per_user_secret",
+              "per_user_oauth"
+            ],
+            "default": "shared"
           },
           "secret_schema": {
-            "description": "JSON 编码的密钥 schema，例如 `{\"header_name\":\"X-Api-Key\"}`；`auth_mode=per_user_secret` 时必填。",
-            "type": "string"
+            "type": "string",
+            "description": "JSON 编码的密钥 schema，例如 `{\"header_name\":\"X-Api-Key\"}`；`auth_mode=per_user_secret` 时必填。"
           },
-          "streaming": {
-            "description": "远程智能体是否支持流式响应。",
-            "type": "boolean"
+          "oauth_metadata": {
+            "type": "string",
+            "description": "JSON 编码的 OAuth 元数据；由 `per_user_oauth` 模式的 OAuth 发现流程填充。"
           },
-          "team_id": {
-            "description": "团队范围：0 = 账户级；>0 = 团队。在账户级创建需要 owner/admin 角色；创建到某个团队需要真实属于该团队。",
-            "format": "int64",
-            "type": "integer"
+          "allow_insecure_oauth_http": {
+            "type": "boolean",
+            "description": "允许该智能体使用非回环的 HTTP OAuth 发现/元数据端点，而非强制 HTTPS。默认为 false。"
+          },
+          "allow_insecure_tls_skip_verify": {
+            "type": "boolean",
+            "description": "连接到该智能体端点时跳过 TLS 证书验证（自签/私有证书）。默认为 false。"
           }
         },
         "required": [
           "agent_name",
           "instructions",
           "card_url"
-        ],
-        "type": "object"
+        ]
       },
       "A2AAgentCreateResponse": {
         "description": "注册 A2A 智能体的结果。",
@@ -254,133 +269,134 @@
         "type": "object"
       },
       "A2AAgentItem": {
+        "type": "object",
         "description": "一个已注册的 A2A（智能体间通信）远程智能体。",
         "properties": {
+          "agent_id": {
+            "type": "string",
+            "description": "唯一的 A2A 智能体 ID（前缀 `a2a_`）。"
+          },
           "account_id": {
+            "type": "integer",
             "description": "所属账户 ID。",
-            "format": "int64",
-            "type": "integer"
+            "format": "int64"
           },
-          "agent_card_name": {
-            "description": "从远程卡片解析得到的智能体名称；卡片尚未拉取时省略。",
-            "type": "string"
+          "team_id": {
+            "type": "integer",
+            "description": "团队范围：0 = 账户级；>0 = 所属团队。",
+            "format": "int64"
           },
-          "agent_card_skills": {
-            "description": "远程卡片宣告的技能；卡片尚未拉取时省略。",
+          "can_edit": {
+            "type": "boolean",
+            "description": "调用者能否更新、启用、停用或删除该智能体：账户级智能体仅账户 owner 或管理员为 `true`，团队智能体仅该团队成员为 `true`。"
+          },
+          "environments": {
+            "type": "array",
             "items": {
               "type": "string"
             },
-            "type": "array"
-          },
-          "agent_id": {
-            "description": "唯一的 A2A 智能体 ID（前缀 `a2a_`）。",
-            "type": "string"
+            "description": "该智能体可运行的执行环境（`cloud` 和/或 BYOC Runner 的环境 ID）。始终返回；`[]` 表示所有环境（该字段引入前的历史数据也是空数组）。"
           },
           "agent_name": {
-            "description": "智能体显示名称。",
-            "type": "string"
-          },
-          "allow_insecure_oauth_http": {
-            "description": "允许该智能体使用非回环的 HTTP OAuth 发现/元数据端点，而非强制 HTTPS。",
-            "type": "boolean"
-          },
-          "allow_insecure_tls_skip_verify": {
-            "description": "连接到该智能体端点时跳过 TLS 证书验证。",
-            "type": "boolean"
+            "type": "string",
+            "description": "智能体显示名称。"
           },
-          "auth_config": {
-            "additionalProperties": {
-              "type": "string"
-            },
-            "description": "认证配置键值。键名疑似凭据（包含 KEY、SECRET、TOKEN、PASSWORD 等）的值会被脱敏；为空时省略。",
-            "type": "object"
+          "instructions": {
+            "type": "string",
+            "description": "远程智能体的自然语言指令（旧名 `description`）。",
+            "maxLength": 51200
           },
-          "auth_mode": {
-            "description": "认证模式。可选值：`shared`（共享凭据：配置资源时保存一份静态凭据，账户内所有调用方共用；缺省及空字符串等同于此值）、`per_user_secret`（按人密钥：每位使用者按 `secret_schema` 各自保存密钥，运行时按人注入）、`per_user_oauth`（按人 OAuth：每位使用者各自完成 OAuth 授权，首次调用时按需完成发现与注册）。",
-            "enum": [
-              "shared",
-              "per_user_secret",
-              "per_user_oauth"
-            ],
-            "type": "string"
+          "card_url": {
+            "type": "string",
+            "description": "远程智能体卡片的 URL。"
           },
           "auth_type": {
-            "description": "访问远程智能体的认证类型：`none`、`api_key` 或 `bearer`。校验收紧前创建的历史数据可能返回空字符串，等价于 `none`。",
+            "type": "string",
+            "description": "使用共享凭据访问远程智能体时的认证方式：\n- `none`：不发送凭据请求头。\n- `api_key`：把 `auth_config.api_key` 放进 `auth_config.header` 指定名称的请求头。\n- `bearer`：发送 `Authorization: Bearer <auth_config.token>`。\n\n空字符串表示创建时未传 `auth_type`，效果同 `none`。",
             "enum": [
               "",
               "none",
               "api_key",
               "bearer"
-            ],
-            "type": "string"
-          },
-          "can_edit": {
-            "description": "调用者是否可以编辑该智能体。",
-            "type": "boolean"
+            ]
           },
-          "card_resolve_timeout": {
-            "description": "卡片解析超时时间（秒）。目前恒为 0 —— API 尚未提供设置方式。",
-            "type": "integer"
+          "auth_config": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "string"
+            },
+            "description": "共享凭据键值（`header`、`api_key`、`token` 等）。`api_key`、`token`、`client_secret` 以及其他加密存储的值会脱敏：超过 8 个字符时只显示首尾各 4 个字符、中间为 `****`，否则显示 `****`。为空时省略。"
           },
-          "card_url": {
-            "description": "远程智能体卡片的 URL。",
-            "type": "string"
+          "streaming": {
+            "type": "boolean",
+            "description": "远程智能体是否支持流式响应。"
           },
-          "created_at": {
-            "description": "创建时间。Unix 时间戳（毫秒）。",
-            "format": "int64",
-            "type": "integer"
+          "status": {
+            "type": "string",
+            "description": "智能体是否提供给 AI SRE 会话使用：\n- `enabled`：可被调用（创建后的状态）。\n- `disabled`：保留配置但不提供使用；可通过 `POST /safari/a2a-agent/enable` 重新启用。",
+            "enum": [
+              "enabled",
+              "disabled"
+            ]
           },
-          "created_by": {
-            "description": "创建该智能体的成员 ID。",
-            "format": "int64",
-            "type": "integer"
+          "agent_card_name": {
+            "type": "string",
+            "description": "旧记录中从远程卡片读取的智能体名称。服务端已不再写入该字段，新建智能体不返回。"
           },
-          "environments": {
-            "description": "该智能体可运行的执行环境（`cloud` 和/或 BYOC Runner 的环境 ID）。始终返回；`[]` 表示所有环境（该字段引入前的历史数据也是空数组）。",
+          "agent_card_skills": {
+            "type": "array",
             "items": {
               "type": "string"
             },
-            "type": "array"
+            "description": "旧记录中从远程卡片读取的技能名称。服务端已不再写入该字段，新建智能体不返回。"
           },
-          "instructions": {
-            "description": "远程智能体的自然语言指令（旧名 `description`）。",
-            "maxLength": 51200,
-            "type": "string"
+          "card_resolve_timeout": {
+            "type": "integer",
+            "description": "卡片解析超时时间（秒）。目前恒为 0 —— API 尚未提供设置方式。"
           },
-          "oauth_metadata": {
-            "description": "JSON 编码的 OAuth 元数据（per_user_oauth 模式）。",
-            "type": "string"
+          "task_timeout": {
+            "type": "integer",
+            "description": "单个任务执行超时时间（秒）。目前恒为 0 —— API 尚未提供设置方式。"
+          },
+          "auth_mode": {
+            "type": "string",
+            "description": "凭据由谁提供；为空时省略，效果同 `shared`：\n- `shared`：使用保存在智能体上的一份凭据（`auth_type` + `auth_config`），所有调用者共用。\n- `per_user_secret`：每位用户各自保存密钥，放在 `secret_schema.header_name` 指定的请求头中发送。\n- `per_user_oauth`：每位用户各自完成 OAuth 授权，首次使用时完成发现与客户端注册。",
+            "enum": [
+              "shared",
+              "per_user_secret",
+              "per_user_oauth"
+            ]
           },
           "secret_schema": {
-            "description": "JSON 编码的密钥 schema（per_user_secret 模式）。",
-            "type": "string"
+            "type": "string",
+            "description": "JSON 编码的密钥 schema（per_user_secret 模式）。"
           },
-          "status": {
-            "description": "智能体状态。",
-            "enum": [
-              "enabled",
-              "disabled"
-            ],
-            "type": "string"
+          "oauth_metadata": {
+            "type": "string",
+            "description": "JSON 编码的 OAuth 元数据（per_user_oauth 模式）。"
           },
-          "streaming": {
-            "description": "远程智能体是否支持流式响应。",
-            "type": "boolean"
+          "allow_insecure_oauth_http": {
+            "type": "boolean",
+            "description": "允许该智能体使用非回环的 HTTP OAuth 发现/元数据端点，而非强制 HTTPS。"
           },
-          "task_timeout": {
-            "description": "单个任务执行超时时间（秒）。目前恒为 0 —— API 尚未提供设置方式。",
-            "type": "integer"
+          "allow_insecure_tls_skip_verify": {
+            "type": "boolean",
+            "description": "连接到该智能体端点时跳过 TLS 证书验证。"
           },
-          "team_id": {
-            "description": "团队范围：0 = 账户级；>0 = 所属团队。",
+          "created_by": {
+            "type": "integer",
+            "description": "创建该智能体的成员 ID。",
+            "format": "int64"
+          },
+          "created_at": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "创建时间。Unix 时间戳（毫秒）。"
           },
           "updated_at": {
-            "description": "最后更新时间。Unix 时间戳（毫秒）。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "最后更新时间。Unix 时间戳（毫秒）。"
           }
         },
         "required": [
@@ -400,54 +416,53 @@
           "created_at",
           "updated_at",
           "environments"
-        ],
-        "type": "object"
+        ]
       },
       "A2AAgentListRequest": {
+        "type": "object",
         "description": "查询 A2A 智能体列表的分页、范围与搜索过滤参数。",
         "properties": {
-          "include_account": {
-            "description": "是否包含账户级（team_id=0）记录。默认为 true。",
-            "type": [
-              "boolean",
-              "null"
-            ]
-          },
-          "limit": {
-            "default": 20,
-            "description": "页面大小。",
-            "type": "integer"
-          },
           "offset": {
-            "default": 0,
+            "type": "integer",
             "description": "分页偏移量，即跳过的记录数，从 0 开始。",
-            "type": "integer"
+            "default": 0
           },
-          "query": {
-            "description": "在智能体名称、指令、卡片 URL、智能体 ID 以及解析得到的卡片名称中进行不区分大小写的子串搜索。",
-            "maxLength": 128,
-            "type": "string"
+          "limit": {
+            "type": "integer",
+            "description": "每页条数；小于等于 0 时按 20 处理。服务端不设上限。",
+            "default": 20
           },
           "scope": {
-            "default": "all",
-            "description": "可见范围：`all`（账户级加上调用者可见的团队）、`account`（仅账户级）或 `team`（调用者可见团队中的团队级记录）。",
+            "type": "string",
             "enum": [
               "all",
               "account",
               "team"
             ],
-            "type": "string"
+            "default": "all",
+            "description": "可见范围：`all`（账户级加上调用者可见的团队）、`account`（仅账户级）或 `team`（调用者可见团队中的团队级记录）。"
+          },
+          "query": {
+            "type": "string",
+            "description": "在智能体名称、指令、卡片 URL、智能体 ID 以及解析得到的卡片名称中进行不区分大小写的子串搜索。",
+            "maxLength": 128
           },
           "team_ids": {
-            "description": "限定在这些团队 ID 内；留空表示使用调用者可见的团队集合。",
+            "type": "array",
             "items": {
-              "format": "int64",
-              "type": "integer"
+              "type": "integer",
+              "format": "int64"
             },
-            "type": "array"
+            "description": "只返回这些团队的记录。调用者不属于的团队 ID 会被忽略；为空表示调用者所属的全部团队。"
+          },
+          "include_account": {
+            "type": [
+              "boolean",
+              "null"
+            ],
+            "description": "是否包含账户级（`team_id=0`）记录。默认 `true`；`scope` 为 `account` 时始终包含、为 `team` 时始终不包含，此时忽略该字段。"
           }
-        },
-        "type": "object"
+        }
       },
       "A2AAgentListResponse": {
         "description": "分页的 A2A 智能体列表。",
@@ -472,202 +487,217 @@
         "type": "object"
       },
       "A2AAgentUpdateRequest": {
+        "type": "object",
         "description": "对 A2A 智能体执行部分更新。字段为 null 或省略时保持不变。",
         "properties": {
           "agent_id": {
-            "description": "目标智能体 ID，取自 `POST /safari/a2a-agent/list` 返回的列表。",
-            "type": "string"
+            "type": "string",
+            "description": "目标智能体 ID，取自 `POST /safari/a2a-agent/list` 返回的列表。"
           },
           "agent_name": {
-            "description": "新的显示名称。省略则保持不变。",
-            "maxLength": 128,
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "新的显示名称，省略表示不变。规则同创建：不能含 `@`，不能是 `general` / `explore`，在作用域内唯一。",
+            "maxLength": 128
           },
-          "allow_insecure_oauth_http": {
-            "description": "切换该智能体的非回环 HTTP OAuth 发现开关。省略则保持不变。",
+          "instructions": {
             "type": [
-              "boolean",
+              "string",
               "null"
-            ]
+            ],
+            "description": "新的指令文档（约定同创建：可带 `summary` frontmatter，正文非空，最大 50 KiB）。省略则保持不变。已弃用的 `description` 字段仍可传入，若两者同时传入则必须一致。",
+            "maxLength": 51200
           },
-          "allow_insecure_tls_skip_verify": {
-            "description": "切换该智能体的 TLS 证书验证跳过开关。省略则保持不变。",
+          "card_url": {
             "type": [
-              "boolean",
+              "string",
               "null"
-            ]
-          },
-          "auth_config": {
-            "additionalProperties": {
-              "type": "string"
-            },
-            "description": "整体替换认证配置；省略则保持不变。未包含在 map 中的键会被删除。敏感键回传掩码值时保留已存储的密钥，传空字符串则清除该密钥。",
-            "type": "object"
+            ],
+            "description": "新的卡片 URL，省略表示不变。校验与兼容性检查同创建；实际变更时，若未传新的 `oauth_metadata`，会将其清空。"
           },
-          "auth_mode": {
-            "description": "新的认证模式：shared、per_user_secret 或 per_user_oauth。变更时会一并重写 secret_schema。",
+          "auth_type": {
             "type": [
               "string",
               "null"
-            ]
-          },
-          "auth_type": {
-            "description": "新的认证类型：`none`、`api_key` 或 `bearer`。省略则保持不变。",
+            ],
+            "description": "新的认证方式，省略表示不变。\n- `none`：不发送凭据请求头。\n- `api_key`：把 `auth_config.api_key` 放进 `auth_config.header` 指定名称的请求头。\n- `bearer`：发送 `Authorization: Bearer <auth_config.token>`。",
             "enum": [
               "none",
               "api_key",
               "bearer"
-            ],
+            ]
+          },
+          "auth_config": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "string"
+            },
+            "description": "整体替换认证配置；省略则保持不变。未包含在 map 中的键会被删除。敏感键回传掩码值时保留已存储的密钥，传空字符串则清除该密钥。"
+          },
+          "streaming": {
             "type": [
-              "string",
+              "boolean",
               "null"
-            ]
+            ],
+            "description": "切换流式支持。省略则保持不变。"
           },
-          "card_url": {
-            "description": "新的卡片 URL。省略则保持不变。",
+          "team_id": {
             "type": [
-              "string",
+              "integer",
               "null"
-            ]
+            ],
+            "description": "重新分配团队范围，省略表示不变。改到团队需是该团队成员；改为账户级（`0`）仅限账户 owner 或管理员。若变更团队但同一请求未传 `environments`，现有 Runner 条目必须对调用者仍可选，否则更新被拒绝。",
+            "format": "int64"
           },
           "environments": {
-            "description": "该智能体可运行的执行环境：`cloud` 和/或 BYOC Runner 的环境 ID 列表。省略（null）表示保持不变；传入列表即整体设置——空列表表示清除限制、恢复为所有环境。",
-            "items": {
-              "type": "string"
-            },
             "type": [
               "array",
               "null"
-            ]
+            ],
+            "items": {
+              "type": "string"
+            },
+            "description": "该智能体可运行的执行环境：`cloud` 和/或 BYOC Runner 的环境 ID 列表。省略（null）表示保持不变；传入列表即整体设置——空列表表示清除限制、恢复为所有环境。"
           },
-          "instructions": {
-            "description": "新的指令文档（约定同创建：可带 `summary` frontmatter，正文非空，最大 50 KiB）。省略则保持不变。已弃用的 `description` 字段仍可传入，若两者同时传入则必须一致。",
-            "maxLength": 51200,
+          "auth_mode": {
             "type": [
               "string",
               "null"
+            ],
+            "description": "新的认证模式，省略表示不变。取值（凭据由谁提供）：\n- `shared`（默认，空值等同）：使用保存在智能体上的一份凭据（`auth_type` + `auth_config`），所有调用者共用。\n- `per_user_secret`：每位用户各自保存密钥，放在 `secret_schema.header_name` 指定的请求头中发送。\n- `per_user_oauth`：每位用户各自完成 OAuth 授权，首次使用时完成发现与客户端注册。\n\n传入时，`secret_schema` 会被同一请求中的值覆盖。",
+            "enum": [
+              "shared",
+              "per_user_secret",
+              "per_user_oauth"
             ]
           },
-          "oauth_metadata": {
-            "description": "新的 JSON OAuth 元数据。若 auth_mode 变更但未传入此字段，将被清空。",
+          "secret_schema": {
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "新的 JSON 密钥 schema，例如 `{\"header_name\":\"X-Api-Key\"}`。仅在同时传入 `auth_mode` 时生效，单独传入会被忽略。"
           },
-          "secret_schema": {
-            "description": "新的 JSON 密钥 schema。",
+          "oauth_metadata": {
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "新的 JSON OAuth 元数据。非空值按原样保存。省略或为空时保留原值；若 `auth_mode` 或 `card_url` 发生变化，则清空。"
           },
-          "streaming": {
-            "description": "切换流式支持。省略则保持不变。",
+          "allow_insecure_oauth_http": {
             "type": [
               "boolean",
               "null"
-            ]
+            ],
+            "description": "切换该智能体的非回环 HTTP OAuth 发现开关。省略则保持不变。"
           },
-          "team_id": {
-            "description": "重新分配团队范围。省略则保持不变。重新分配需要对目标团队的权限；若团队变更且未同时传入新的环境绑定，则现有 Runner 绑定必须对调用者仍可选，否则更新将被拒绝。",
-            "format": "int64",
+          "allow_insecure_tls_skip_verify": {
             "type": [
-              "integer",
+              "boolean",
               "null"
-            ]
+            ],
+            "description": "切换该智能体的 TLS 证书验证跳过开关。省略则保持不变。"
           }
         },
         "required": [
           "agent_id"
-        ],
-        "type": "object"
+        ]
       },
       "AccountInfo": {
+        "type": "object",
         "properties": {
           "account_id": {
+            "type": "integer",
             "description": "主体（账户）标识。",
-            "format": "uint64",
-            "type": "integer"
+            "format": "uint64"
           },
           "account_name": {
-            "description": "主体名称。",
-            "type": "string"
-          },
-          "avatar": {
-            "description": "主体头像 URL。",
-            "type": "string"
-          },
-          "country_code": {
-            "description": "联系手机的 ISO 3166-1 alpha-2 地区代码（如 \"CN\"、\"US\"、\"HK\"）。",
-            "type": "string"
-          },
-          "created_at": {
-            "description": "主体创建时间，Unix 时间戳（秒）。",
-            "format": "int64",
-            "type": "integer"
+            "type": "string",
+            "description": "在控制台中显示的账户（组织）名称。"
           },
           "domain": {
-            "description": "主体主域名（登录子域名）。",
-            "type": "string"
-          },
-          "email": {
-            "description": "主体联系邮箱。",
-            "type": "string"
+            "type": "string",
+            "description": "主体主域名（登录子域名）。"
           },
           "extra_domains": {
-            "description": "主体的附加域名。",
+            "type": "array",
             "items": {
               "type": "string"
             },
-            "type": "array"
+            "description": "主体的附加域名。"
           },
-          "locale": {
-            "description": "主体语言偏好（例如 zh-CN、en-US）。",
-            "type": "string"
+          "phone": {
+            "type": "string",
+            "description": "主体联系电话，已做隐私脱敏处理。"
           },
-          "mp_account_id": {
-            "description": "账户在云市场平台上的标识。与 `mp_plat` 一起省略。",
-            "type": "string"
+          "country_code": {
+            "type": "string",
+            "description": "联系手机的 ISO 3166-1 alpha-2 地区代码（如 \"CN\"、\"US\"、\"HK\"）。"
           },
-          "mp_plat": {
-            "description": "账户来源的云市场平台。账户非来自云市场时不返回。",
-            "type": "string"
+          "email": {
+            "type": "string",
+            "description": "主体联系邮箱。"
           },
-          "phone": {
-            "description": "主体联系电话，已做隐私脱敏处理。",
-            "type": "string"
+          "avatar": {
+            "type": "string",
+            "description": "主体头像 URL。"
+          },
+          "locale": {
+            "type": "string",
+            "description": "账户语言偏好（`zh-CN` 或 `en-US`）；未设置时为空字符串。"
+          },
+          "time_zone": {
+            "type": "string",
+            "description": "账户默认时区（IANA 名称，如 `Asia/Shanghai`），未设置个人时区的成员跟随该时区。未设置时为空字符串。"
+          },
+          "created_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "主体创建时间，Unix 时间戳（秒）。"
           },
           "restrictions": {
+            "type": "object",
             "description": "账户访问限制。未配置时不返回。",
             "properties": {
-              "allow_subdomain": {
-                "description": "是否同时接受允许邮箱域名的子域名。",
-                "type": "boolean"
-              },
-              "email_domains": {
-                "description": "允许的登录邮箱域名。",
+              "ips": {
+                "type": [
+                  "array",
+                  "null"
+                ],
                 "items": {
                   "type": "string"
                 },
-                "type": "array"
+                "description": "允许访问本账户控制台和 API 的来源 IP 或 CIDR 网段；不限制时为 `null` 或空。"
               },
-              "ips": {
-                "description": "允许的来源 IP/CIDR 白名单。",
+              "email_domains": {
+                "type": [
+                  "array",
+                  "null"
+                ],
                 "items": {
                   "type": "string"
                 },
-                "type": "array"
+                "description": "允许新成员使用的邮箱域名；邀请其他域名的地址会被拒绝。不限制时为 `null` 或空。"
+              },
+              "allow_subdomain": {
+                "type": "boolean",
+                "description": "是否同时接受允许邮箱域名的子域名。"
               }
-            },
-            "type": "object"
+            }
           },
-          "time_zone": {
-            "description": "主体默认时区（IANA 名称，例如 Asia/Shanghai）。",
-            "type": "string"
+          "mp_plat": {
+            "type": "string",
+            "description": "账户开通来源的云市场：`aws`——AWS Marketplace。账户并非来自云市场时省略。",
+            "enum": [
+              "aws"
+            ]
+          },
+          "mp_account_id": {
+            "type": "string",
+            "description": "账户在云市场平台上的标识。与 `mp_plat` 一起省略。"
           }
         },
         "required": [
@@ -682,8 +712,7 @@
           "locale",
           "time_zone",
           "created_at"
-        ],
-        "type": "object"
+        ]
       },
       "AckIncidentRequest": {
         "description": "认领故障的参数。",
@@ -720,79 +749,80 @@
         "type": "object"
       },
       "AddIncidentResponderRequest": {
+        "type": "object",
         "description": "向已有故障添加处理人员的参数。",
+        "required": [
+          "incident_id",
+          "person_ids"
+        ],
         "properties": {
           "incident_id": {
-            "description": "故障 ID（MongoDB ObjectID）。",
+            "type": "string",
             "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
+            "description": "故障 ID（MongoDB ObjectID）。"
+          },
+          "person_ids": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "int64"
+            },
+            "description": "要添加为处理人的成员 ID。已经是处理人或账户中不存在的 ID 会被跳过。"
           },
           "notify": {
-            "description": "通知配置，默认跟随每人的个人通知偏好。",
+            "type": "object",
+            "description": "新加入处理人的通知设置。默认 `{\"follow_preference\": true}`。",
             "properties": {
               "follow_preference": {
-                "description": "为 false 时使用 `personal_channels`；为 true 或省略时跟随处理人员的个人偏好。",
                 "type": [
                   "boolean",
                   "null"
-                ]
+                ],
+                "description": "`true`：按每个人的个人通知偏好发送。`false`：使用 `personal_channels`，此时该字段不能为空。不传时必须设置 `personal_channels`。"
               },
               "personal_channels": {
-                "description": "使用的通知渠道（如 `voice`、`sms`、`email`）。",
+                "type": "array",
                 "items": {
                   "type": "string"
                 },
-                "type": "array"
+                "description": "`follow_preference` 为 `false` 时使用的通知渠道：`sms`、`voice`、`email`、`push`（手机 App 推送），或写作 `feishu_app:<integration_id>`、`dingtalk_app:<integration_id>`、`wecom_app:<integration_id>`、`slack_app:<integration_id>`、`teams_app:<integration_id>` 的 IM 应用渠道。`follow_preference` 为 `true` 时忽略。"
               },
               "template_id": {
-                "description": "通知模板 ID（MongoDB ObjectID）。",
+                "type": "string",
                 "pattern": "^[0-9a-fA-F]{24}$",
-                "type": "string"
+                "description": "通知模板 ID，取自通知模板相关接口。必须是账户中存在的模板，否则返回 `InvalidParameter`。"
               }
-            },
-            "type": "object"
-          },
-          "person_ids": {
-            "description": "要添加的处理人员成员 ID 列表。",
-            "items": {
-              "format": "int64",
-              "type": "integer"
-            },
-            "type": "array"
+            }
           }
-        },
-        "required": [
-          "incident_id",
-          "person_ids"
-        ],
-        "type": "object"
+        }
       },
       "AddWarRoomMemberRequest": {
+        "type": "object",
         "properties": {
-          "chat_id": {
-            "description": "IM 平台中作战室的群聊 ID。",
-            "type": "string"
-          },
           "integration_id": {
+            "type": "integer",
             "description": "承载作战室的 IM 集成 ID，可通过 `POST /datasource/im/war-room-enabled/list` 获取。",
-            "format": "int64",
-            "type": "integer"
+            "format": "int64"
+          },
+          "chat_id": {
+            "type": "string",
+            "description": "作战室群在 IM 平台上的会话 ID，可从 `POST /incident/war-room/list` 返回的作战室信息中获取。"
           },
           "member_ids": {
-            "description": "要加入作战室的人员 ID 列表。",
+            "type": "array",
+            "minItems": 1,
             "items": {
-              "format": "int64",
-              "type": "integer"
+              "type": "integer",
+              "format": "int64"
             },
-            "type": "array"
+            "description": "要添加的人员 ID（成员 ID；账户所有者为账户 ID）。不能为空。"
           }
         },
         "required": [
           "integration_id",
           "chat_id",
           "member_ids"
-        ],
-        "type": "object"
+        ]
       },
       "AffectedStatusPageComponentItem": {
         "description": "事件当前影响的状态页组件，包含组件元数据及其状态。",
@@ -850,90 +880,90 @@
         "type": "object"
       },
       "AlertEventGlobalListRequest": {
+        "type": "object",
         "description": "全局原始事件列表的过滤和分页条件，时间范围必填。",
+        "required": [
+          "start_time",
+          "end_time"
+        ],
         "properties": {
-          "asc": {
-            "description": "为 true 时升序排序。",
-            "type": "boolean"
-          },
-          "channel_ids": {
-            "description": "按协作空间 ID 过滤，最多 100 个。",
-            "items": {
-              "format": "int64",
-              "type": "integer"
-            },
-            "maxItems": 100,
-            "type": "array"
+          "start_time": {
+            "type": "integer",
+            "format": "int64",
+            "description": "查询窗口起点，Unix 时间戳（秒）。必须大于 0。",
+            "exclusiveMinimum": 0
           },
           "end_time": {
-            "description": "查询窗口终点，Unix 时间戳（秒）。必须大于 `start_time`；跨度不超过 31 天。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
-          },
-          "integration_ids": {
-            "description": "按集成 ID 过滤。",
-            "items": {
-              "format": "int64",
-              "type": "integer"
-            },
-            "type": "array"
+            "description": "查询窗口终点，Unix 时间戳（秒）。必须大于 `start_time`；跨度不超过 31 天。"
           },
-          "integration_types": {
-            "description": "按集成类型（插件键）过滤。",
-            "items": {
-              "type": "string"
-            },
-            "type": "array"
-          },
-          "limit": {
-            "description": "每页条数，最大 100，默认 20。",
-            "format": "int64",
-            "maximum": 100,
-            "minimum": 0,
+          "p": {
             "type": [
               "integer",
               "null"
-            ]
-          },
-          "orderby": {
-            "description": "排序字段，目前仅支持 `event_time`。",
-            "enum": [
-              "event_time"
             ],
-            "type": "string"
-          },
-          "p": {
-            "description": "页码，从 1 开始。仅在未提供 `search_after_ctx` 时生效。",
             "format": "int64",
-            "minimum": 0,
+            "description": "页码，从 1 开始。仅在未提供 `search_after_ctx` 时生效。",
+            "minimum": 0
+          },
+          "limit": {
             "type": [
               "integer",
               "null"
-            ]
+            ],
+            "format": "int64",
+            "description": "每页条数，最大 100，默认 20。",
+            "minimum": 0,
+            "maximum": 100
           },
           "search_after_ctx": {
-            "description": "分页游标：首页留空，之后传入上一次响应返回的 `search_after_ctx`。",
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "分页游标：首页留空，之后传入上一次响应返回的 `search_after_ctx`。"
+          },
+          "integration_ids": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "int64"
+            },
+            "description": "按集成 ID 过滤。"
+          },
+          "integration_types": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "按集成类型（插件键）过滤。"
+          },
+          "channel_ids": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "int64"
+            },
+            "description": "按协作空间 ID 过滤，最多 100 个。",
+            "maxItems": 100
           },
           "severities": {
-            "description": "逗号分隔的严重级别过滤，如 `Critical,Warning`。可选值：`Critical`、`Warning`、`Info`、`Ok`。",
-            "type": "string"
+            "type": "string",
+            "description": "按 `event_severity` 过滤，多个值用逗号分隔，如 `Critical,Warning`。有效取值：`Critical`、`Warning`、`Info`。取值不做校验，未知值（或 `Ok`）匹配不到事件。"
           },
-          "start_time": {
-            "description": "查询窗口起点，Unix 时间戳（秒）。必须大于 0。",
-            "exclusiveMinimum": 0,
-            "format": "int64",
-            "type": "integer"
+          "orderby": {
+            "type": "string",
+            "description": "排序字段，目前仅支持 `event_time`。",
+            "enum": [
+              "event_time"
+            ]
+          },
+          "asc": {
+            "type": "boolean",
+            "description": "为 true 时升序排序。"
           }
-        },
-        "required": [
-          "start_time",
-          "end_time"
-        ],
-        "type": "object"
+        }
       },
       "AlertEventGlobalListResponse": {
         "properties": {
@@ -961,113 +991,113 @@
         "type": "object"
       },
       "AlertEventItem": {
+        "type": "object",
         "description": "单条原始告警事件。",
         "properties": {
-          "account_id": {
-            "description": "账户 ID。",
-            "format": "int64",
-            "type": "integer"
+          "event_id": {
+            "type": "string",
+            "pattern": "^[0-9a-fA-F]{24}$",
+            "description": "事件 ID（MongoDB ObjectID）。"
           },
           "alert_id": {
-            "description": "父告警 ID（MongoDB ObjectID）。",
+            "type": "string",
             "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
+            "description": "父告警 ID（MongoDB ObjectID）。"
           },
-          "alert_key": {
-            "description": "用于将事件合并到告警的去重键。",
-            "type": "string"
+          "account_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "该记录所属账户的 ID；同一 `app_key` 返回的记录该值都相同。"
           },
           "channel_id": {
-            "description": "事件路由到的协作空间 ID。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "事件路由到的协作空间 ID。"
           },
-          "created_at": {
-            "description": "记录创建时间，Unix 时间戳（秒）。",
+          "integration_id": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "产生该事件的集成 ID。"
+          },
+          "integration_type": {
+            "type": "string",
+            "description": "集成的插件类型，例如 `prometheus.alert`、`grafana.alert`、`zabbix.alert`、`monit.alert`、`email.alert`。取值集合是开放的，会随新集成增加；完整列表可通过 `POST /integration/type/list` 获取。"
           },
           "data_source_id": {
-            "description": "已废弃，请使用 `integration_id`。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "已废弃，请使用 `integration_id`。"
           },
-          "deleted_at": {
-            "description": "软删除时间，Unix 时间戳（秒）。未删除时不返回该字段。",
-            "format": "int64",
-            "type": "integer"
+          "title": {
+            "type": "string",
+            "description": "事件标题。"
+          },
+          "title_rule": {
+            "type": "string",
+            "description": "用于从标签派生 `title` 的标题模板。"
           },
           "description": {
-            "description": "事件描述。",
-            "type": "string"
+            "type": "string",
+            "description": "事件描述。"
           },
-          "event_id": {
-            "description": "事件 ID（MongoDB ObjectID）。",
-            "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
+          "alert_key": {
+            "type": "string",
+            "description": "用于将事件合并到告警的去重键。"
           },
           "event_severity": {
-            "description": "事件严重级别：`Critical`、`Warning` 或 `Info`。事件级别不会取 `Ok`，`Ok` 只出现在 `event_status` 字段。",
+            "type": "string",
             "enum": [
               "Critical",
               "Warning",
               "Info"
             ],
-            "type": "string"
+            "description": "事件严重级别：`Critical`、`Warning` 或 `Info`。事件级别不会取 `Ok`，`Ok` 只出现在 `event_status` 字段。"
           },
           "event_status": {
-            "description": "事件状态：`Critical`/`Warning`/`Info` 表示触发事件，`Ok` 表示恢复事件。",
+            "type": "string",
             "enum": [
               "Critical",
               "Warning",
               "Info",
               "Ok"
             ],
-            "type": "string"
+            "description": "事件状态：`Critical`/`Warning`/`Info` 表示触发事件，`Ok` 表示恢复事件。"
           },
           "event_time": {
-            "description": "事件时间戳，Unix 时间戳（秒）。",
-            "format": "int64",
-            "type": "integer"
-          },
-          "images": {
-            "description": "事件附加的图片。",
-            "items": {
-              "$ref": "#/components/schemas/AlertImage"
-            },
-            "type": "array"
-          },
-          "integration_id": {
-            "description": "产生该事件的集成 ID。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
-          },
-          "integration_type": {
-            "description": "产生该事件的集成类型/插件键。",
-            "type": "string"
+            "description": "事件时间戳，Unix 时间戳（秒）。"
           },
           "labels": {
+            "type": "object",
             "additionalProperties": {
               "type": "string"
             },
-            "description": "标签键值对。",
-            "type": "object"
+            "description": "标签键值对。"
           },
-          "title": {
-            "description": "事件标题。",
-            "type": "string"
+          "images": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/AlertImage"
+            },
+            "description": "事件附加的图片。"
           },
-          "title_rule": {
-            "description": "用于从标签派生 `title` 的标题模板。",
-            "type": "string"
+          "created_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "记录创建时间，Unix 时间戳（秒）。"
           },
           "updated_at": {
-            "description": "记录更新时间，Unix 时间戳（秒）。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "记录更新时间，Unix 时间戳（秒）。"
+          },
+          "deleted_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "软删除时间，Unix 时间戳（秒）。未删除时不返回该字段。"
           }
-        },
-        "type": "object"
+        }
       },
       "AlertEventListRequest": {
         "properties": {
@@ -1217,231 +1247,243 @@
         "type": "string"
       },
       "AlertImage": {
+        "type": "object",
         "description": "告警或事件的图片附件。",
+        "required": [
+          "src"
+        ],
         "properties": {
-          "alt": {
-            "description": "替代文本。",
-            "type": "string"
-          },
           "href": {
-            "description": "点击图片时的跳转链接（可选）。",
-            "type": "string"
+            "type": "string",
+            "description": "点击图片时的跳转链接（可选）。"
           },
           "src": {
-            "description": "图片源地址或内部引用（以 `img_` 或 `http` 开头）。",
-            "type": "string"
+            "type": "string",
+            "description": "图片源地址或内部引用（以 `img_` 或 `http` 开头）。"
+          },
+          "alt": {
+            "type": "string",
+            "description": "图片无法显示时展示的替代文字；未设置时为空。"
           }
-        },
-        "required": [
-          "src"
-        ],
-        "type": "object"
+        }
       },
       "AlertInfo": {
+        "type": "object",
         "description": "告警详情。",
+        "required": [
+          "alert_id",
+          "integration_id",
+          "data_source_id",
+          "channel_id",
+          "account_id",
+          "description",
+          "title",
+          "title_rule",
+          "alert_key",
+          "alert_severity",
+          "alert_status",
+          "start_time",
+          "last_time",
+          "end_time",
+          "labels",
+          "ever_muted",
+          "created_at",
+          "updated_at",
+          "integration_name",
+          "integration_type",
+          "integration_ref_id",
+          "channel_name",
+          "channel_status",
+          "responder_name",
+          "responder_email",
+          "event_cnt",
+          "images",
+          "data_source_name",
+          "data_source_ref_id"
+        ],
         "properties": {
+          "alert_id": {
+            "type": "string",
+            "pattern": "^[0-9a-fA-F]{24}$",
+            "description": "告警 ID（MongoDB ObjectID）。"
+          },
+          "integration_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "产生告警的集成 ID。"
+          },
+          "data_source_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "已废弃，请使用 `integration_id`。"
+          },
+          "channel_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "告警被路由到的协作空间 ID，名称见 `channel_name`。"
+          },
           "account_id": {
-            "description": "账号 ID。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "该记录所属账户的 ID；同一 `app_key` 返回的记录该值都相同。"
           },
-          "alert_id": {
-            "description": "告警 ID（MongoDB ObjectID）。",
-            "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
+          "description": {
+            "type": "string",
+            "description": "告警描述。"
+          },
+          "title": {
+            "type": "string",
+            "description": "告警标题。"
+          },
+          "title_rule": {
+            "type": "string",
+            "description": "标题生成规则。"
           },
           "alert_key": {
-            "description": "用于合并事件的去重键。",
-            "type": "string"
+            "type": "string",
+            "description": "用于合并事件的去重键。"
           },
           "alert_severity": {
-            "description": "当前严重程度。",
+            "type": "string",
             "enum": [
               "Critical",
               "Warning",
               "Info",
               "Ok"
             ],
-            "type": "string"
+            "description": "当前严重程度。"
           },
           "alert_status": {
-            "description": "当前状态。",
+            "type": "string",
             "enum": [
               "Critical",
               "Warning",
               "Info",
               "Ok"
             ],
-            "type": "string"
+            "description": "当前状态。"
           },
-          "channel_id": {
-            "description": "协作空间 ID。",
+          "start_time": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
-          },
-          "channel_name": {
-            "description": "协作空间名称。",
-            "type": "string"
-          },
-          "channel_status": {
-            "description": "协作空间状态。",
-            "type": "string"
+            "description": "告警首次触发的 Unix 时间戳（秒）。"
           },
-          "created_at": {
-            "description": "创建时间戳（秒）。",
+          "last_time": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "最近一次事件的 Unix 时间戳（秒）。"
           },
-          "data_source_id": {
-            "description": "已废弃，请使用 `integration_id`。",
+          "end_time": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "告警恢复的 Unix 时间戳（秒），仍活跃时为 0。"
           },
-          "data_source_name": {
-            "description": "已废弃，请使用 `integration_name`。",
-            "type": "string"
-          },
-          "data_source_ref_id": {
-            "description": "已废弃，请使用 `integration_ref_id`。",
-            "type": "string"
+          "labels": {
+            "type": [
+              "object",
+              "null"
+            ],
+            "additionalProperties": {
+              "type": "string"
+            },
+            "description": "告警标签。"
           },
-          "data_source_type": {
-            "description": "已废弃，请使用 `integration_type`。",
-            "type": "string"
+          "ever_muted": {
+            "type": "boolean",
+            "description": "该告警是否曾被静默。"
           },
           "deleted_at": {
-            "description": "软删除时间戳（秒），未删除时为 0。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
-          },
-          "description": {
-            "description": "告警描述。",
-            "type": "string"
-          },
-          "detail_url": {
-            "description": "这条告警的控制台页面（`{控制台}/alert/detail/{alert_id}`）。部署没有配置控制台地址时为空。",
-            "type": "string"
+            "description": "软删除时间戳（秒），未删除时为 0。"
           },
-          "end_time": {
-            "description": "告警恢复的 Unix 时间戳（秒），仍活跃时为 0。",
+          "created_at": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "创建时间戳（秒）。"
           },
-          "event_cnt": {
-            "description": "合并到该告警的原始事件总数。",
+          "updated_at": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "最后更新时间戳（秒）。"
           },
-          "events": {
-            "description": "原始告警事件预览，仅在调用方请求时返回；每条告警最多返回最新 20 条。",
-            "items": {
-              "$ref": "#/components/schemas/AlertEventItem"
-            },
-            "type": "array"
+          "integration_name": {
+            "type": "string",
+            "description": "集成显示名称。"
           },
-          "ever_muted": {
-            "description": "该告警是否曾被静默。",
-            "type": "boolean"
+          "integration_type": {
+            "type": "string",
+            "description": "集成的插件类型，例如 `prometheus.alert`、`grafana.alert`、`zabbix.alert`、`monit.alert`、`email.alert`。取值集合是开放的，会随新集成增加；完整列表可通过 `POST /integration/type/list` 获取。"
           },
-          "images": {
-            "description": "附加图片。",
-            "items": {
-              "$ref": "#/components/schemas/Image"
-            },
-            "type": "array"
+          "integration_ref_id": {
+            "type": "string",
+            "description": "集成引用 ID。"
           },
-          "incident": {
-            "$ref": "#/components/schemas/IncidentShort",
-            "description": "所属故障引用，若告警已被合并。"
+          "channel_name": {
+            "type": "string",
+            "description": "协作空间名称。"
           },
-          "integration_id": {
-            "description": "产生告警的集成 ID。",
-            "format": "int64",
-            "type": "integer"
+          "channel_status": {
+            "type": "string",
+            "description": "协作空间状态：`enabled` 启用、`disabled` 禁用、`deleted` 已删除。记录不属于任何协作空间或协作空间已不存在时为空字符串。",
+            "enum": [
+              "enabled",
+              "disabled",
+              "deleted",
+              ""
+            ]
           },
-          "integration_name": {
-            "description": "集成显示名称。",
-            "type": "string"
+          "responder_name": {
+            "type": "string",
+            "description": "API 响应中恒为空字符串，仅在渲染通知时填充。"
           },
-          "integration_ref_id": {
-            "description": "集成引用 ID。",
-            "type": "string"
+          "responder_email": {
+            "type": "string",
+            "description": "API 响应中恒为空字符串，仅在渲染通知时填充。"
           },
-          "integration_type": {
-            "description": "集成类型。",
-            "type": "string"
+          "incident": {
+            "$ref": "#/components/schemas/IncidentShort",
+            "description": "所属故障引用，若告警已被合并。"
           },
-          "labels": {
-            "additionalProperties": {
-              "type": "string"
+          "events": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/AlertEventItem"
             },
-            "description": "告警标签。",
-            "type": "object"
+            "description": "原始告警事件预览，仅在调用方请求时返回；每条告警最多返回最新 20 条。"
           },
-          "last_time": {
-            "description": "最近一次事件的 Unix 时间戳（秒）。",
+          "event_cnt": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "合并到该告警的原始事件总数。"
           },
-          "responder_email": {
-            "description": "主处理人员邮箱。",
-            "type": "string"
+          "images": {
+            "type": [
+              "array",
+              "null"
+            ],
+            "items": {
+              "$ref": "#/components/schemas/Image"
+            },
+            "description": "告警附带的图片；没有时为 `null`。"
           },
-          "responder_name": {
-            "description": "主处理人员名称。",
+          "detail_url": {
+            "description": "这条告警的控制台页面（`{控制台}/alert/detail/{alert_id}`）。部署没有配置控制台地址时为空。",
             "type": "string"
           },
-          "start_time": {
-            "description": "告警首次触发的 Unix 时间戳（秒）。",
-            "format": "int64",
-            "type": "integer"
-          },
-          "title": {
-            "description": "告警标题。",
-            "type": "string"
+          "data_source_name": {
+            "type": "string",
+            "description": "已废弃，请使用 `integration_name`。"
           },
-          "title_rule": {
-            "description": "标题生成规则。",
-            "type": "string"
+          "data_source_type": {
+            "type": "string",
+            "description": "已废弃；与 `integration_type` 取值相同。"
           },
-          "updated_at": {
-            "description": "最后更新时间戳（秒）。",
-            "format": "int64",
-            "type": "integer"
+          "data_source_ref_id": {
+            "type": "string",
+            "description": "已废弃，请使用 `integration_ref_id`。"
           }
-        },
-        "required": [
-          "alert_id",
-          "integration_id",
-          "data_source_id",
-          "channel_id",
-          "account_id",
-          "description",
-          "title",
-          "title_rule",
-          "alert_key",
-          "alert_severity",
-          "alert_status",
-          "start_time",
-          "last_time",
-          "end_time",
-          "labels",
-          "ever_muted",
-          "created_at",
-          "updated_at",
-          "integration_name",
-          "integration_type",
-          "integration_ref_id",
-          "channel_name",
-          "channel_status",
-          "responder_name",
-          "responder_email",
-          "event_cnt",
-          "images",
-          "data_source_name",
-          "data_source_ref_id"
-        ],
-        "type": "object"
+        }
       },
       "AlertInfoRequest": {
         "properties": {
@@ -1457,382 +1499,377 @@
         "type": "object"
       },
       "AlertItem": {
+        "type": "object",
         "description": "包含完整详情的单条告警。",
         "properties": {
+          "alert_id": {
+            "type": "string",
+            "description": "告警唯一 ID（ObjectID 十六进制字符串）。"
+          },
+          "integration_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "产生该告警的集成 ID。"
+          },
+          "data_source_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "已废弃：请使用 `integration_id`。",
+            "deprecated": true
+          },
+          "channel_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "告警所属协作空间 ID。"
+          },
           "account_id": {
-            "description": "账户 ID。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "告警所属账户的 ID。"
           },
-          "alert_id": {
-            "description": "告警唯一 ID（ObjectID 十六进制字符串）。",
-            "type": "string"
+          "title": {
+            "type": "string",
+            "description": "告警标题。"
           },
-          "alert_key": {
-            "description": "去重键。",
-            "type": "string"
+          "title_rule": {
+            "type": "string",
+            "description": "用于从事件标签派生 `title` 的标题模板（如 `$service::$cluster`）。"
+          },
+          "description": {
+            "type": "string",
+            "description": "告警描述。"
           },
           "alert_severity": {
-            "description": "当前严重级别，取该告警出现过的最高级别：`Critical`、`Warning` 或 `Info`。",
+            "type": "string",
             "enum": [
               "Critical",
               "Warning",
               "Info"
             ],
-            "type": "string"
+            "description": "当前严重级别，取该告警出现过的最高级别：`Critical`、`Warning` 或 `Info`。"
           },
           "alert_status": {
-            "description": "当前状态：未恢复时为 `Critical`/`Warning`/`Info`，恢复后为 `Ok`。",
+            "type": "string",
             "enum": [
               "Critical",
               "Warning",
               "Info",
               "Ok"
             ],
-            "type": "string"
-          },
-          "channel_id": {
-            "description": "告警所属协作空间 ID。",
-            "format": "int64",
-            "type": "integer"
+            "description": "当前状态：未恢复时为 `Critical`/`Warning`/`Info`，恢复后为 `Ok`。"
           },
-          "channel_name": {
-            "description": "协作空间显示名称。",
-            "type": "string"
+          "alert_key": {
+            "type": "string",
+            "description": "去重键。"
           },
-          "channel_status": {
-            "description": "协作空间状态：`enabled`（启用）或 `disabled`（禁用）。",
-            "enum": [
-              "enabled",
-              "disabled"
-            ],
-            "type": "string"
+          "start_time": {
+            "type": "integer",
+            "format": "int64",
+            "description": "首次触发时间，Unix 时间戳（秒）。"
           },
-          "created_at": {
-            "description": "创建时间，Unix 时间戳（秒）。",
+          "last_time": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "最后事件时间，Unix 时间戳（秒）。"
           },
-          "data_source_id": {
-            "deprecated": true,
-            "description": "已废弃：请使用 `integration_id`。",
+          "end_time": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "恢复时间，Unix 时间戳（秒）。活跃时为 0。"
           },
-          "data_source_name": {
-            "deprecated": true,
-            "description": "已废弃：请使用 `integration_name`。",
-            "type": "string"
+          "labels": {
+            "type": [
+              "object",
+              "null"
+            ],
+            "additionalProperties": {
+              "type": "string"
+            },
+            "description": "标签键值对；告警没有标签时为 `null`。"
           },
-          "data_source_ref_id": {
-            "deprecated": true,
-            "description": "已废弃：请使用 `integration_ref_id`。",
-            "type": "string"
+          "ever_muted": {
+            "type": "boolean",
+            "description": "是否曾被静默。"
           },
-          "data_source_type": {
-            "deprecated": true,
-            "description": "已废弃：请使用 `integration_type`。为空时不返回。",
-            "type": "string"
+          "created_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "创建时间，Unix 时间戳（秒）。"
           },
-          "deleted_at": {
-            "description": "软删除时间，Unix 时间戳（秒）。未删除时不返回该字段。",
+          "updated_at": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "最后更新时间，Unix 时间戳（秒）。"
           },
-          "description": {
-            "description": "告警描述。",
-            "type": "string"
+          "integration_name": {
+            "type": "string",
+            "description": "集成显示名称。"
           },
-          "detail_url": {
-            "description": "这条告警的控制台页面（`{控制台}/alert/detail/{alert_id}`）。部署没有配置控制台地址时为空。",
-            "type": "string"
+          "integration_type": {
+            "type": "string",
+            "description": "产生该告警的集成类型标识，如 `prometheus.alert`、`zabbix.alert`；取值同 `POST /integration/type/list` 返回的 `plugin_type`。"
           },
-          "end_time": {
-            "description": "恢复时间，Unix 时间戳（秒）。活跃时为 0。",
-            "format": "int64",
-            "type": "integer"
+          "integration_ref_id": {
+            "type": "string",
+            "description": "集成的归属标识：账户级集成为 `a_<account_id>`，协作空间专属集成为 `c_<channel_id>`。"
+          },
+          "channel_name": {
+            "type": "string",
+            "description": "协作空间显示名称。"
+          },
+          "channel_status": {
+            "type": "string",
+            "description": "协作空间状态：`enabled`（启用）或 `disabled`（禁用）。",
+            "enum": [
+              "enabled",
+              "disabled"
+            ]
+          },
+          "responder_name": {
+            "type": "string",
+            "description": "响应人名称。本接口恒为空字符串——响应人信息记录在关联故障上。"
+          },
+          "responder_email": {
+            "type": "string",
+            "description": "响应人邮箱。本接口恒为空字符串——响应人信息记录在关联故障上。"
           },
           "event_cnt": {
-            "description": "该告警收到的原始事件总数。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "该告警收到的原始事件总数。"
+          },
+          "incident": {
+            "$ref": "#/components/schemas/IncidentShort",
+            "description": "关联故障（如有）。"
           },
           "events": {
-            "description": "告警的原始事件列表。本接口不返回；仅 `POST /incident/alert/list` 填充该字段。",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/AlertEventItem"
             },
-            "type": "array"
-          },
-          "ever_muted": {
-            "description": "是否曾被静默。",
-            "type": "boolean"
+            "description": "告警的原始事件列表。本接口不返回；仅 `POST /incident/alert/list` 填充该字段。"
           },
           "images": {
-            "description": "告警附加的图片。",
+            "type": [
+              "array",
+              "null"
+            ],
             "items": {
               "$ref": "#/components/schemas/AlertImage"
             },
-            "type": "array"
-          },
-          "incident": {
-            "$ref": "#/components/schemas/IncidentShort",
-            "description": "关联故障（如有）。"
-          },
-          "integration_id": {
-            "description": "产生该告警的集成 ID。",
-            "format": "int64",
-            "type": "integer"
-          },
-          "integration_name": {
-            "description": "集成显示名称。",
-            "type": "string"
-          },
-          "integration_ref_id": {
-            "description": "集成外部参考 ID。",
-            "type": "string"
-          },
-          "integration_type": {
-            "description": "集成类型/插件键。",
-            "type": "string"
-          },
-          "labels": {
-            "additionalProperties": {
-              "type": "string"
-            },
-            "description": "标签键值对。",
-            "type": "object"
-          },
-          "last_time": {
-            "description": "最后事件时间，Unix 时间戳（秒）。",
-            "format": "int64",
-            "type": "integer"
+            "description": "告警附带的图片；没有图片时为 `null`。"
           },
-          "responder_email": {
-            "description": "响应人邮箱。本接口恒为空字符串——响应人信息记录在关联故障上。",
-            "type": "string"
-          },
-          "responder_name": {
-            "description": "响应人名称。本接口恒为空字符串——响应人信息记录在关联故障上。",
+          "detail_url": {
+            "description": "这条告警的控制台页面（`{控制台}/alert/detail/{alert_id}`）。部署没有配置控制台地址时为空。",
             "type": "string"
           },
-          "start_time": {
-            "description": "首次触发时间，Unix 时间戳（秒）。",
-            "format": "int64",
-            "type": "integer"
+          "data_source_name": {
+            "type": "string",
+            "description": "已废弃：请使用 `integration_name`。",
+            "deprecated": true
           },
-          "title": {
-            "description": "告警标题。",
-            "type": "string"
+          "data_source_type": {
+            "type": "string",
+            "description": "已弃用，请使用 `integration_type`（取值相同，如 `prometheus.alert`）。为空时不返回。",
+            "deprecated": true
           },
-          "title_rule": {
-            "description": "用于从事件标签派生 `title` 的标题模板（如 `$service::$cluster`）。",
-            "type": "string"
+          "data_source_ref_id": {
+            "type": "string",
+            "description": "已废弃：请使用 `integration_ref_id`。",
+            "deprecated": true
           },
-          "updated_at": {
-            "description": "最后更新时间，Unix 时间戳（秒）。",
+          "deleted_at": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "软删除时间，Unix 时间戳（秒）。未删除时不返回该字段。"
           }
-        },
-        "type": "object"
+        }
       },
       "AlertListByIDsRequest": {
+        "type": "object",
+        "required": [
+          "alert_ids"
+        ],
         "properties": {
           "alert_ids": {
-            "description": "要查询的告警 ID 列表（ObjectID 十六进制字符串）。",
+            "type": "array",
             "items": {
               "type": "string"
             },
-            "minItems": 1,
-            "type": "array"
+            "description": "要查询的告警 ID（ObjectID 十六进制字符串）。格式错误的 ID 会使请求失败；账户中不存在的 ID 不会出现在结果中。"
           }
-        },
-        "required": [
-          "alert_ids"
-        ],
-        "type": "object"
+        }
       },
       "AlertListRequest": {
+        "type": "object",
         "description": "告警列表查询的过滤和分页条件，时间范围必填。",
+        "required": [
+          "start_time",
+          "end_time"
+        ],
         "properties": {
-          "alert_ids": {
-            "description": "只查询指定告警 ID（ObjectID 十六进制字符串）。非法 ID 会被忽略；全部非法时结果为空。",
-            "items": {
-              "type": "string"
-            },
-            "type": "array"
-          },
-          "alert_keys": {
-            "description": "按告警去重键过滤。",
-            "items": {
-              "type": "string"
-            },
-            "type": "array"
-          },
-          "alert_severity": {
-            "description": "逗号分隔的严重程度过滤，如 `Critical,Warning`。可选值：`Critical`、`Warning`、`Info`、`Ok`。",
-            "type": "string"
-          },
-          "asc": {
-            "description": "为 `true` 时按 `start_time` 升序排序；默认降序。",
-            "type": "boolean"
-          },
-          "by_updated_at": {
-            "description": "为 true 时，时间范围过滤作用于 `updated_at` 而非 `start_time`。",
-            "type": "boolean"
-          },
-          "channel_ids": {
-            "description": "按协作空间 ID 过滤。",
-            "items": {
-              "format": "int64",
-              "type": "integer"
-            },
-            "type": "array"
+          "start_time": {
+            "type": "integer",
+            "format": "int64",
+            "description": "查询窗口起点，Unix 时间戳（秒），作用于告警的 `start_time`。早于账户数据保留期时会被调整为保留期起点。"
           },
           "end_time": {
-            "description": "查询窗口终点，Unix 时间戳（秒）。必须大于 `start_time`；跨度不超过 31 天，且需在账户数据保留期内。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "查询窗口终点，Unix 时间戳（秒）。必须大于 `start_time`，跨度不超过 31 天（启用 `by_updated_at` 时不超过 7 天）。早于数据保留期起点时返回 `InvalidParameter`。"
           },
-          "ever_muted": {
-            "description": "按告警是否曾被静默过滤。",
+          "p": {
             "type": [
-              "boolean",
+              "integer",
               "null"
-            ]
-          },
-          "integration_ids": {
-            "description": "按集成 ID 过滤。",
-            "items": {
-              "format": "int64",
-              "type": "integer"
-            },
-            "type": "array"
+            ],
+            "format": "int64",
+            "description": "页码，从 1 开始。仅在未提供 `search_after_ctx` 时生效；`p * limit` 不能超过 10,000 条。",
+            "minimum": 0
           },
-          "is_active": {
-            "description": "按生命周期过滤：`true` 只返回未恢复告警（状态 `Critical`/`Warning`/`Info`），`false` 只返回已恢复告警（状态 `Ok`）。不传或传 `null` 返回全部。",
+          "limit": {
             "type": [
-              "boolean",
+              "integer",
               "null"
-            ]
-          },
-          "limit": {
-            "description": "每页条数，最大 100，默认 20。",
+            ],
             "format": "int64",
-            "maximum": 100,
+            "description": "每页条数，最大 100，默认 20。",
             "minimum": 0,
+            "maximum": 100
+          },
+          "search_after_ctx": {
             "type": [
-              "integer",
+              "string",
               "null"
-            ]
+            ],
+            "description": "上一页响应返回的分页游标，用于获取下一页。"
           },
-          "p": {
-            "description": "页码，从 1 开始。仅在未提供 `search_after_ctx` 时生效；`p * limit` 不能超过 10,000 条。",
-            "format": "int64",
-            "minimum": 0,
+          "is_active": {
             "type": [
-              "integer",
+              "boolean",
               "null"
-            ]
+            ],
+            "description": "按生命周期过滤：`true` 只返回未恢复告警（状态 `Critical`/`Warning`/`Info`），`false` 只返回已恢复告警（状态 `Ok`）。不传或传 `null` 返回全部。"
           },
-          "search_after_ctx": {
-            "description": "上一页响应返回的分页游标，用于获取下一页。",
+          "ever_muted": {
             "type": [
-              "string",
+              "boolean",
               "null"
-            ]
+            ],
+            "description": "按告警是否曾被静默过滤。"
           },
-          "start_time": {
-            "description": "检索窗口开始时间，Unix 时间戳（秒）。",
-            "format": "int64",
-            "type": "integer"
+          "alert_severity": {
+            "type": "string",
+            "description": "按 `alert_severity` 过滤，多个值用逗号分隔，如 `Critical,Warning`。允许的取值：`Critical`、`Warning`、`Info`、`Ok`，其他值返回 `InvalidParameter`。`alert_severity` 不会是 `Ok`，因此 `Ok` 匹配不到告警。"
+          },
+          "channel_ids": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "int64"
+            },
+            "description": "按协作空间 ID 过滤。"
+          },
+          "integration_ids": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "int64"
+            },
+            "description": "按集成 ID 过滤。"
+          },
+          "alert_ids": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "只查询指定告警 ID（ObjectID 十六进制字符串）。非法 ID 会被忽略；全部非法时结果为空。"
+          },
+          "alert_keys": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "按告警去重键过滤。"
+          },
+          "asc": {
+            "type": "boolean",
+            "description": "为 `true` 时按 `start_time` 升序排序；默认降序。"
+          },
+          "by_updated_at": {
+            "type": "boolean",
+            "description": "为 `true` 时，在按 `start_time` 过滤之外，还要求告警的 `updated_at` 落在 [`start_time`, `end_time`] 内；此时跨度不超过 7 天。"
           }
-        },
-        "required": [
-          "start_time",
-          "end_time"
-        ],
-        "type": "object"
+        }
       },
       "AlertListResponse": {
+        "type": "object",
         "description": "分页的告警列表。",
         "properties": {
+          "total": {
+            "type": "integer",
+            "format": "int64",
+            "description": "匹配的告警数量，最多为 1,000。"
+          },
           "has_next_page": {
-            "description": "是否有更多页。",
-            "type": "boolean"
+            "type": "boolean",
+            "description": "存在下一页时为 `true`。游标模式（传了 `search_after_ctx`）下结果准确；页码模式下按 `p * limit` 与封顶后的 `total` 比较，超过 1,000 条后即使还有匹配的告警也会返回 `false`，此时请改用 `search_after_ctx` 继续。"
+          },
+          "search_after_ctx": {
+            "type": "string",
+            "description": "下一页游标——本页最后一条告警的 ObjectID；请作为 `search_after_ctx` 传回。本页为空时不返回；游标模式下没有下一页时也不返回。"
           },
           "items": {
-            "description": "当前页的告警列表。",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/AlertItem"
             },
-            "type": "array"
-          },
-          "search_after_ctx": {
-            "description": "下一页游标——本页最后一条告警的 ObjectID 十六进制字符串，请求下一页时作为 `search_after_ctx` 传入。仅在 `has_next_page` 为 true 时返回。",
-            "type": "string"
-          },
-          "total": {
-            "description": "匹配的告警总数，最多统计 1000 条。",
-            "format": "int64",
-            "type": "integer"
+            "description": "当前页的告警列表。"
           }
-        },
-        "type": "object"
+        }
       },
       "AlertMergeRequest": {
+        "type": "object",
+        "required": [
+          "alert_ids",
+          "incident_id"
+        ],
         "properties": {
           "alert_ids": {
-            "description": "要合并的告警 ID 列表（ObjectID 十六进制字符串），可从 `POST /alert/list` 获取。所有 ID 必须属于当前账户。",
+            "type": "array",
             "items": {
               "type": "string"
             },
-            "minItems": 1,
-            "type": "array"
-          },
-          "comment": {
-            "description": "可选评论，记录在合并动态中。最长 1024 字符。",
-            "maxLength": 1024,
-            "type": "string"
+            "description": "要合并的告警 ID 列表（ObjectID 十六进制字符串），可从 `POST /alert/list` 获取。所有 ID 必须属于当前账户。"
           },
           "incident_id": {
+            "type": "string",
             "description": "目标故障 ID（ObjectID 十六进制字符串），可从 `POST /incident/list` 获取。",
-            "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
+            "pattern": "^[0-9a-fA-F]{24}$"
           },
-          "owner_id": {
-            "description": "目标故障的新负责人成员 ID，可通过 `POST /member/list` 获取。",
-            "format": "int64",
-            "type": "integer"
+          "comment": {
+            "type": "string",
+            "description": "可选评论，记录在合并动态中。最长 1024 字符。",
+            "maxLength": 1024
           },
           "title": {
+            "type": "string",
             "description": "可选，目标故障的新标题。最长 512 字符。",
-            "maxLength": 512,
-            "type": "string"
+            "maxLength": 512
+          },
+          "owner_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "目标故障的新负责人成员 ID，可通过 `POST /member/list` 获取。"
           }
-        },
-        "required": [
-          "alert_ids",
-          "incident_id"
-        ],
-        "type": "object"
+        }
       },
       "AlertPipeline": {
+        "type": "object",
         "description": "单条告警处理规则。",
         "properties": {
-          "if": {
-            "description": "AND 条件列表——仅当所有条件都匹配时规则生效。为 `null` 或不传表示规则对所有事件生效。",
-            "items": {
-              "$ref": "#/components/schemas/FilterCondition"
-            },
-            "type": [
-              "array",
-              "null"
-            ]
-          },
           "kind": {
-            "description": "规则类型。规则按数组顺序依次执行，`if` 条件命中后按 `kind` 处理事件。\n| 值 | 含义 |\n|---|---|\n| `title_reset` | 按 `settings.title` 模板重写事件标题。 |\n| `description_reset` | 按 `settings.description` 模板重写事件描述。 |\n| `severity_reset` | 将事件严重程度与状态重置为 `settings.severity`（`Critical`/`Warning`/`Info`）。 |\n| `alert_drop` | 直接丢弃匹配的事件，不生成告警。 |\n| `alert_inhibit` | 当存在匹配 `settings.source_filters` 且按 `settings.equals` 关联的活跃源告警时，丢弃该事件（抑制）。 |",
+            "type": "string",
             "enum": [
               "title_reset",
               "description_reset",
@@ -1840,9 +1877,20 @@
               "alert_drop",
               "alert_inhibit"
             ],
-            "type": "string"
+            "description": "规则类型。规则按数组顺序依次执行，`if` 条件命中后按 `kind` 处理事件。\n| 值 | 含义 |\n|---|---|\n| `title_reset` | 按 `settings.title` 模板重写事件标题。 |\n| `description_reset` | 按 `settings.description` 模板重写事件描述。 |\n| `severity_reset` | 将事件严重程度与状态重置为 `settings.severity`（`Critical`/`Warning`/`Info`）。 |\n| `alert_drop` | 直接丢弃匹配的事件，不生成告警。 |\n| `alert_inhibit` | 当存在匹配 `settings.source_filters` 且按 `settings.equals` 关联的活跃源告警时，丢弃该事件（抑制）。 |"
+          },
+          "if": {
+            "type": [
+              "array",
+              "null"
+            ],
+            "items": {
+              "$ref": "#/components/schemas/FilterCondition"
+            },
+            "description": "AND 过滤条件列表——事件满足全部条件时规则才生效。可用的 key：`severity`（别名 `alert_severity`、`event_severity`）、`status`、`title`、`title_rule`、`description`、`alert_key`、`integration_id`（别名 `data_source_id`）以及 `labels.<名称>`；其他 key 返回 `InvalidParameter`。为 `null` 或不传时规则作用于所有事件。"
           },
           "settings": {
+            "type": "object",
             "description": "与 `kind` 对应的配置。取值结构因 `kind` 而异：\n- `title_reset`：`{ \"title\": \"<模板字符串>\" }`\n- `description_reset`：`{ \"description\": \"<模板字符串>\" }`\n- `severity_reset`：`{ \"severity\": \"Critical\"|\"Warning\"|\"Info\" }`\n- `alert_drop`：`{}` (空对象)\n- `alert_inhibit`：`{ \"equals\": [\"<标签键>\", ...], \"source_filters\": <OrFilterGroup> }`",
             "oneOf": [
               {
@@ -1860,14 +1908,12 @@
               {
                 "$ref": "#/components/schemas/ApAlertInhibit"
               }
-            ],
-            "type": "object"
+            ]
           }
         },
         "required": [
           "kind"
-        ],
-        "type": "object"
+        ]
       },
       "AlertPipelineInfoRequest": {
         "properties": {
@@ -1963,27 +2009,26 @@
         "type": "object"
       },
       "AlertPipelineUpsertRequest": {
+        "type": "object",
+        "required": [
+          "integration_id",
+          "rules"
+        ],
         "properties": {
           "integration_id": {
-            "description": "要配置的集成 ID。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "要配置的集成 ID，账户级集成和协作空间专属集成均可。"
           },
           "rules": {
-            "description": "要应用的规则，按数组顺序执行。1 到 50 条。",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/AlertPipeline"
             },
-            "maxItems": 50,
-            "minItems": 1,
-            "type": "array"
+            "description": "要应用的规则，按数组顺序执行。最多 50 条；传空数组会清空所有规则。",
+            "maxItems": 50
           }
-        },
-        "required": [
-          "integration_id",
-          "rules"
-        ],
-        "type": "object"
+        }
       },
       "AlertRule": {
         "description": "完整的告警规则配置。",
@@ -2174,131 +2219,179 @@
         "type": "object"
       },
       "AlertRuleAudit": {
+        "type": "object",
         "description": "审计记录，保存某一时刻的规则快照。",
+        "required": [
+          "id",
+          "account_id",
+          "alert_rule_id",
+          "action",
+          "creator_id",
+          "creator_name",
+          "created_at"
+        ],
         "properties": {
+          "id": {
+            "type": "integer",
+            "format": "uint64",
+            "description": "审计记录 ID。"
+          },
           "account_id": {
-            "description": "所属账户 ID。",
+            "type": "integer",
             "format": "uint64",
-            "type": "integer"
+            "description": "所属账户 ID。"
+          },
+          "alert_rule_id": {
+            "type": "integer",
+            "format": "uint64",
+            "description": "关联的告警规则 ID。"
           },
           "action": {
+            "type": "string",
             "description": "操作类型：`create` = 创建规则；`update` = 更新规则（涵盖整体更新、字段批量更新、导入和移动）。",
             "enum": [
               "create",
               "update"
-            ],
-            "type": "string"
-          },
-          "alert_rule_id": {
-            "description": "关联的告警规则 ID。",
-            "format": "uint64",
-            "type": "integer"
+            ]
           },
           "content": {
-            "description": "审计时刻规则完整配置的 JSON 字符串，仅在 `/monit/rule/audit/detail` 返回，列表接口中省略。",
-            "type": "string"
-          },
-          "created_at": {
-            "description": "审计记录生成时间，Unix 时间戳（秒）；取变更时规则的 `updated_at`。",
-            "format": "int64",
-            "type": "integer"
+            "type": "string",
+            "description": "变更完成后规则完整配置的 JSON 字符串，仅在 `/monit/rule/audit/detail` 返回，列表接口中省略。由 `/monit/rule/v2/create` 和 `/monit/rule/v2/update` 写入的记录采用 `AlertRuleV2` 结构；由 `/monit/rule/update/fields` 和 `/monit/rule/move` 写入的记录采用规则的存储结构，其检查器配置使用旧版恢复设置，而不是 `recovery_mode` / `end_mode`。"
           },
           "creator_id": {
-            "description": "触发本次变更的用户 ID（取变更时规则的 `updater_id`）。",
+            "type": "integer",
             "format": "uint64",
-            "type": "integer"
+            "description": "触发本次变更的用户 ID（取变更时规则的 `updater_id`）。"
           },
           "creator_name": {
-            "description": "触发本次变更的用户名（取变更时规则的 `updater_name`）。",
-            "type": "string"
+            "type": "string",
+            "description": "触发本次变更的用户名（取变更时规则的 `updater_name`）。"
           },
-          "id": {
-            "description": "审计记录 ID。",
-            "format": "uint64",
-            "type": "integer"
+          "created_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "审计记录生成时间，Unix 时间戳（秒）；取变更时规则的 `updated_at`。"
           }
-        },
+        }
+      },
+      "AlertRuleBasic": {
+        "type": "object",
+        "description": "列表视图用的告警规则基础信息。`include_descendants` 为 `true` 的列表中只填充 `id`、`folder_id`、`name`，其余字段为零值。",
         "required": [
           "id",
           "account_id",
-          "alert_rule_id",
-          "action",
+          "folder_id",
+          "name",
+          "ds_type",
+          "enabled",
+          "debug_log_enabled",
+          "cron_pattern",
+          "delay_seconds",
           "creator_id",
           "creator_name",
-          "created_at"
+          "updater_id",
+          "updater_name",
+          "created_at",
+          "updated_at",
+          "triggered",
+          "labels",
+          "timezone",
+          "active_alert_count"
         ],
-        "type": "object"
-      },
-      "AlertRuleBasic": {
-        "description": "列表视图用的告警规则基础信息。",
         "properties": {
+          "id": {
+            "type": "integer",
+            "format": "uint64",
+            "description": "唯一规则 ID。"
+          },
           "account_id": {
-            "description": "账户 ID。",
+            "type": "integer",
             "format": "uint64",
-            "type": "integer"
+            "description": "规则所属账户 ID；在 `include_descendants` 为 `true` 的列表中为 `0`。"
           },
-          "active_alert_count": {
-            "description": "该规则当前活跃（未恢复）的告警数量。`triggered` 等价于 `active_alert_count > 0`。",
-            "format": "int64",
-            "type": "integer"
+          "folder_id": {
+            "type": "integer",
+            "format": "uint64",
+            "description": "直接包含该规则的文件夹 ID；在 `include_descendants` 为 `true` 的列表中可能是所请求文件夹的子孙文件夹。"
           },
-          "created_at": {
-            "description": "创建时间，Unix 时间戳（秒）。",
-            "format": "int64",
-            "type": "integer"
+          "name": {
+            "type": "string",
+            "description": "规则名称，在所属文件夹内唯一（最长 128 个字符）。"
           },
-          "creator_id": {
-            "description": "创建人用户 ID。",
-            "format": "uint64",
-            "type": "integer"
+          "labels": {
+            "type": [
+              "object",
+              "null"
+            ],
+            "additionalProperties": {
+              "type": "string"
+            },
+            "description": "规则附加到其告警事件上的自定义标签；在 `include_descendants` 为 `true` 的列表中为 `null`。"
           },
-          "creator_name": {
-            "description": "创建人用户名。",
-            "type": "string"
+          "ds_type": {
+            "type": "string",
+            "description": "规则查询的数据源类型。支持告警的类型：`prometheus`、`elasticsearch`、`loki`、`clickhouse`、`mysql`、`oracle`、`postgres`、`sls`、`tencent_cls`、`victorialogs`。只有启用的规则会按此列表校验，因此禁用的规则可能是其他值；在 `include_descendants` 为 `true` 的列表中为空。"
           },
-          "cron_pattern": {
-            "description": "调度表达式：6 字段 cron（含秒），如 `0 * * * * *`；或 `@every 30s` 形式的间隔描述。不允许以 `CRON_TZ=` 或 `TZ=` 开头，时区请填写到 `timezone` 字段。",
-            "type": "string"
+          "enabled": {
+            "type": "boolean",
+            "description": "规则是否启用。"
           },
           "debug_log_enabled": {
-            "description": "是否启用调试日志。",
-            "type": "boolean"
+            "type": "boolean",
+            "description": "是否开启调试日志；为 `true` 时 edge 会为该规则输出详细的评估日志。"
           },
-          "delay_seconds": {
-            "description": "评估延迟（秒）。",
-            "type": "integer"
+          "cron_pattern": {
+            "type": "string",
+            "description": "调度表达式：6 字段 cron（含秒），如 `0 * * * * *`；或 `@every 30s` 形式的间隔描述。不允许以 `CRON_TZ=` 或 `TZ=` 开头，时区请填写到 `timezone` 字段。"
           },
-          "ds_type": {
-            "description": "数据源类型，如 `prometheus`。",
-            "type": "string"
+          "timezone": {
+            "type": "string",
+            "description": "告警规则执行时区，决定 cron 调度与生效时间窗口的解释方式。仅接受 IANA 时区名（如 `Asia/Shanghai`、`UTC`、`Europe/London`）；不接受 `Local`、`UTC+8`、`CST` 等简写或偏移量。留空时按 `Asia/Shanghai` 处理。",
+            "default": "Asia/Shanghai"
           },
-          "enabled": {
-            "description": "规则是否启用。",
-            "type": "boolean"
+          "delay_seconds": {
+            "type": "integer",
+            "description": "评估时查询窗口向前偏移的秒数，用于补偿数据摄入延迟。"
           },
-          "folder_id": {
-            "description": "文件夹 ID。",
+          "creator_id": {
+            "type": "integer",
             "format": "uint64",
-            "type": "integer"
+            "description": "创建人用户 ID。"
           },
-          "id": {
-            "description": "唯一规则 ID。",
-            "format": "uint64",
-            "type": "integer"
+          "creator_name": {
+            "type": "string",
+            "description": "创建人用户名。"
           },
-          "labels": {
-            "additionalProperties": {
-              "type": "string"
-            },
-            "description": "自定义标签。",
-            "type": "object"
+          "updater_id": {
+            "type": "integer",
+            "format": "uint64",
+            "description": "最近修改人用户 ID。"
           },
-          "name": {
-            "description": "规则名称。",
-            "type": "string"
+          "updater_name": {
+            "type": "string",
+            "description": "最近修改人用户名。"
+          },
+          "created_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "创建时间，Unix 时间戳（秒）。"
+          },
+          "updated_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "最近修改时间，Unix 时间戳（秒）。"
+          },
+          "triggered": {
+            "type": "boolean",
+            "description": "是否有当前活跃告警。"
+          },
+          "active_alert_count": {
+            "type": "integer",
+            "format": "int64",
+            "description": "该规则当前活跃（未恢复）的告警数量。`triggered` 等价于 `active_alert_count > 0`。"
           },
           "runtime_state": {
-            "description": "运行时评估状态，由 edge 心跳与 edge 上报的规则运行状态推导。状态不可用时不返回。\n\n| 值 | 含义 |\n|---|---|\n| `disabled` | 规则已禁用。 |\n| `offline` | 负责该规则的 edge 实例或集群离线。 |\n| `abnormal` | edge 上报评估异常。 |\n| `stale` | edge 上报的运行状态已过期。 |\n| `no_datasource` | 当前没有数据源匹配规则的 `ds_list` / `ds_ids`。 |\n| `config_pending` | 最新的规则配置尚未下发到 edge。 |\n| `waiting` | 已启用，但 edge 尚未上报运行状态。 |\n| `normal` | 正常评估中。 |",
+            "type": "string",
             "enum": [
               "disabled",
               "offline",
@@ -2309,54 +2402,9 @@
               "waiting",
               "normal"
             ],
-            "type": "string"
-          },
-          "timezone": {
-            "default": "Asia/Shanghai",
-            "description": "告警规则执行时区，决定 cron 调度与生效时间窗口的解释方式。仅接受 IANA 时区名（如 `Asia/Shanghai`、`UTC`、`Europe/London`）；不接受 `Local`、`UTC+8`、`CST` 等简写或偏移量。留空时按 `Asia/Shanghai` 处理。",
-            "type": "string"
-          },
-          "triggered": {
-            "description": "是否有当前活跃告警。",
-            "type": "boolean"
-          },
-          "updated_at": {
-            "description": "最近修改时间，Unix 时间戳（秒）。",
-            "format": "int64",
-            "type": "integer"
-          },
-          "updater_id": {
-            "description": "最近修改人用户 ID。",
-            "format": "uint64",
-            "type": "integer"
-          },
-          "updater_name": {
-            "description": "最近修改人用户名。",
-            "type": "string"
+            "description": "运行时评估状态，由 edge 心跳与 edge 上报的规则运行状态推导。状态不可用时不返回。\n\n| 值 | 含义 |\n|---|---|\n| `disabled` | 规则已禁用。 |\n| `offline` | 负责该规则的 edge 实例或集群离线。 |\n| `abnormal` | edge 上报评估异常。 |\n| `stale` | edge 上报的运行状态已过期。 |\n| `no_datasource` | 当前没有数据源匹配规则的 `ds_list` / `ds_ids`。 |\n| `config_pending` | 最新的规则配置尚未下发到 edge。 |\n| `waiting` | 已启用，但 edge 尚未上报运行状态。 |\n| `normal` | 正常评估中。 |"
           }
-        },
-        "required": [
-          "id",
-          "account_id",
-          "folder_id",
-          "name",
-          "ds_type",
-          "enabled",
-          "debug_log_enabled",
-          "cron_pattern",
-          "delay_seconds",
-          "creator_id",
-          "creator_name",
-          "updater_id",
-          "updater_name",
-          "created_at",
-          "updated_at",
-          "triggered",
-          "labels",
-          "timezone",
-          "active_alert_count"
-        ],
-        "type": "object"
+        }
       },
       "AlertRuleCounter": {
         "description": "账户规则总数的一次历史快照。",
@@ -2516,96 +2564,97 @@
         "type": "object"
       },
       "ApAlertDrop": {
-        "description": "`alert_drop` 规则的配置：无需额外配置，匹配的告警将被静默丢弃。",
-        "properties": {},
-        "type": "object"
+        "type": "object",
+        "description": "`alert_drop` 的配置：无字段，传 `{}` 即可。命中的事件会被丢弃，不会创建或更新告警。",
+        "properties": {}
       },
       "ApAlertInhibit": {
-        "description": "`alert_inhibit` 规则的配置：当来源告警与当前告警共享相同标签值时，抑制匹配过滤条件的来源告警。",
+        "type": "object",
+        "description": "`alert_inhibit` 的配置：当同一集成中存在一条活跃告警（`alert_key` 不同、在事件前 10 分钟内开始），且它满足 `source_filters`、在每个 `equals` key 上与当前事件取值相同时，当前事件被丢弃。",
+        "required": [
+          "equals",
+          "source_filters"
+        ],
         "properties": {
           "equals": {
-            "description": "需要在来源告警与当前告警之间值相等的标签键列表。",
+            "type": "array",
             "items": {
               "type": "string"
             },
-            "type": "array"
+            "description": "源告警与当前事件取值必须相同的 key：`title`、`severity` 或 `labels.<名称>`。列表为空、包含其他 key，或事件缺少该标签时，规则不会抑制任何事件。"
           },
           "source_filters": {
-            "description": "用于匹配待抑制来源告警的 AND 过滤条件列表，需全部条件匹配。",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/FilterCondition"
             },
-            "type": "array"
+            "description": "源告警须满足的 AND 条件。可用的 key：`severity`、`title` 和 `labels.<名称>`；其他 key 返回 `InvalidParameter`。"
           }
-        },
-        "required": [
-          "equals",
-          "source_filters"
-        ],
-        "type": "object"
+        }
       },
       "ApDescriptionReset": {
-        "description": "`description_reset` 规则的配置：使用模板字符串覆盖告警描述。",
-        "properties": {
-          "description": {
-            "description": "新描述模板。",
-            "type": "string"
-          }
-        },
+        "type": "object",
+        "description": "`description_reset` 的配置：用渲染后的模板替换事件描述。",
         "required": [
           "description"
         ],
-        "type": "object"
+        "properties": {
+          "description": {
+            "type": "string",
+            "description": "描述模板。仅以 `[TPL]` 开头的值生效：其后内容按 Go 模板基于事件渲染并替换描述；不带该前缀时描述保持不变。"
+          }
+        }
       },
       "ApSeverityReset": {
-        "description": "`severity_reset` 规则的配置：将告警严重程度强制设置为固定值。",
+        "type": "object",
+        "description": "`severity_reset` 的配置：把事件的严重程度和状态都设为固定值。",
+        "required": [
+          "severity"
+        ],
         "properties": {
           "severity": {
-            "description": "目标严重程度级别。",
+            "type": "string",
             "enum": [
               "Critical",
               "Warning",
               "Info"
             ],
-            "type": "string"
+            "description": "要设置的严重程度：`Critical`、`Warning` 或 `Info`。事件状态会被设为相同的值。"
           }
-        },
-        "required": [
-          "severity"
-        ],
-        "type": "object"
+        }
       },
       "ApTitleReset": {
-        "description": "`title_reset` 规则的配置：使用模板字符串覆盖告警标题。",
-        "properties": {
-          "title": {
-            "description": "新标题模板，支持引用告警字段的 Golang 模板语法。",
-            "type": "string"
-          }
-        },
+        "type": "object",
+        "description": "`title_reset` 的配置：按标题规则重写事件标题。",
         "required": [
           "title"
         ],
-        "type": "object"
+        "properties": {
+          "title": {
+            "type": "string",
+            "description": "标题规则。以 `[TPL]` 开头时按 Go 模板基于事件渲染，如 `[TPL]{{.Labels.service}}`；否则视为以 `::` 分隔的片段列表，`$名称` 片段替换为同名标签的值，其他片段原样保留。"
+          }
+        }
       },
       "ArtifactFileStateItem": {
-        "description": "单个文件的发布状态。仅当文件存在已发布的产物时才会返回。",
+        "type": "object",
+        "description": "单个文件的产物发布状态。按文件所属会话和工作区路径匹配，因此已被重新发布的文件的旧版本也会返回当前产物。",
         "properties": {
-          "artifact_id": {
-            "description": "产物 ID（`art_` 前缀）。同时也是公开分享链接的标识。",
-            "type": "string"
-          },
           "file_id": {
-            "description": "回显请求中的文件 ID。",
-            "type": "string"
+            "type": "string",
+            "description": "该条结果对应的请求文件 ID。"
           },
-          "gallery_path": {
-            "description": "产物页面的控制台相对路径：`/ai-sre/artifacts/<artifact_id>`。",
-            "type": "string"
+          "artifact_id": {
+            "type": "string",
+            "description": "产物 ID（`art_` 前缀）。同时也是公开分享链接的标识。"
           },
           "title": {
-            "description": "已发布产物的展示标题。",
-            "type": "string"
+            "type": "string",
+            "description": "已发布产物的展示标题。"
+          },
+          "gallery_path": {
+            "type": "string",
+            "description": "产物页面的控制台相对路径：`/ai-sre/artifacts/<artifact_id>`。"
           }
         },
         "required": [
@@ -2613,42 +2662,41 @@
           "artifact_id",
           "title",
           "gallery_path"
-        ],
-        "type": "object"
+        ]
       },
       "ArtifactFileStateRequest": {
+        "type": "object",
         "description": "批量查询文件的产物发布状态。",
         "properties": {
           "file_ids": {
-            "description": "要查询的文件 ID（`pf_` 前缀）。单次最多 50 个；重复和空字符串会被忽略。",
+            "type": "array",
             "items": {
               "type": "string"
             },
             "maxItems": 50,
             "minItems": 1,
-            "type": "array"
+            "description": "要查询的文件 ID（`pf_` 前缀）。单次最多 50 个，按去重和去除空字符串之前的数量计算；超出时返回 `InvalidParameter`。"
           }
         },
         "required": [
           "file_ids"
-        ],
-        "type": "object"
+        ]
       },
       "ArtifactFileStateResponse": {
+        "type": "object",
         "description": "按文件返回的发布状态。",
         "properties": {
           "items": {
-            "description": "每个存在已发布产物的请求文件对应一条记录；未发布的文件不会出现在列表中。",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/ArtifactFileStateItem"
             },
-            "type": "array"
+            "description": "每个其会话文件路径当前有已发布产物的请求文件对应一条；没有已发布产物的文件和不存在的 ID 不会出现。都不匹配时为空数组。"
           }
         },
         "required": [
           "items"
-        ],
-        "type": "object"
+        ]
       },
       "ArtifactIdRequest": {
         "description": "指定一个产物库中的产物。",
@@ -2664,74 +2712,76 @@
         "type": "object"
       },
       "ArtifactListRequest": {
+        "type": "object",
         "description": "产物库列表的过滤与分页参数。",
         "properties": {
-          "asc": {
-            "description": "为 true 时升序，为 false 时降序。仅在设置了 `orderby` 时生效。",
-            "type": "boolean"
-          },
-          "limit": {
-            "default": 20,
-            "description": "每页条数。默认 20，最大 100。",
-            "maximum": 100,
-            "type": "integer"
-          },
-          "orderby": {
-            "description": "排序字段：`created_at` 或 `updated_at`。留空按 `updated_at` 倒序。",
-            "enum": [
-              "created_at",
-              "updated_at"
-            ],
-            "type": "string"
-          },
-          "page": {
-            "default": 1,
-            "description": "页码，从 1 开始。",
-            "minimum": 1,
-            "type": "integer"
-          },
-          "query": {
-            "description": "按产物标题做大小写不敏感的子串匹配。",
-            "type": "string"
-          },
           "scope": {
-            "default": "all",
-            "description": "可见范围。`all`（默认）= 调用者自己的个人产物 + 其所在团队的产物；`personal` = 仅调用者自己创建的；`team` = 仅调用者所属团队的团队产物。",
+            "type": "string",
             "enum": [
               "all",
               "personal",
               "team"
             ],
-            "type": "string"
+            "default": "all",
+            "description": "可见范围。`all`（默认）= 调用者自己的个人产物 + 其所在团队的产物；`personal` = 仅调用者自己创建的；`team` = 仅调用者所属团队的团队产物。"
           },
           "team_ids": {
-            "description": "只看指定团队的产物，与调用者可见范围取交集 —— 不属于调用者的团队不会有任何返回。",
+            "type": "array",
             "items": {
-              "format": "int64",
-              "type": "integer"
+              "type": "integer",
+              "format": "int64"
             },
-            "type": "array"
+            "description": "只看这些团队拥有的产物，与 `scope` 条件取交集。小于等于 0 的 ID 会被忽略；调用者不属于的团队不会有返回，且设置该字段后不会返回个人产物。"
+          },
+          "query": {
+            "type": "string",
+            "description": "按产物标题做大小写不敏感的子串匹配。"
+          },
+          "page": {
+            "type": "integer",
+            "default": 1,
+            "description": "页码，从 1 开始。小于 1 时按 1 处理。"
+          },
+          "limit": {
+            "type": "integer",
+            "default": 20,
+            "description": "每页条数。小于 1 时按 20 处理；大于 100 时按 100 处理（不会报错）。"
+          },
+          "orderby": {
+            "type": "string",
+            "enum": [
+              "created_at",
+              "updated_at"
+            ],
+            "description": "排序字段：`created_at`（发布时间）或 `updated_at`（最近变更时间）。留空时按 `updated_at` 倒序。无论哪种排序，调用者置顶的产物都排在最前，相同值再按 `artifact_id` 排序。"
+          },
+          "asc": {
+            "type": "boolean",
+            "description": "为 true 时升序，为 false 时降序。仅在设置了 `orderby` 时生效。"
           }
-        },
-        "type": "object"
+        }
       },
       "ArtifactListResponse": {
+        "type": "object",
         "description": "一页产物列表。",
         "properties": {
           "items": {
-            "description": "当前页的产物列表。",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/PublishedArtifactItem"
             },
-            "type": "array"
+            "description": "本页产物；调用者置顶的产物排在最前。无匹配时为空数组。"
           },
           "total": {
-            "description": "符合过滤条件的产物总数（跨所有页）。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "符合过滤条件的产物总数（跨所有页）。"
           }
         },
-        "type": "object"
+        "required": [
+          "items",
+          "total"
+        ]
       },
       "ArtifactPublishFromFileRequest": {
         "description": "把会话中生成的文件发布到产物库。",
@@ -2775,29 +2825,30 @@
         "type": "object"
       },
       "ArtifactShareState": {
+        "type": "object",
         "description": "产物的公开分享状态。",
         "properties": {
           "artifact_id": {
-            "description": "产物 ID（`art_` 前缀）。同时也是公开分享链接的标识。",
-            "type": "string"
-          },
-          "public_url": {
-            "description": "完全由 CDN 承载的匿名公开链接。任何拿到链接的人无需登录即可查看内容。",
-            "type": "string"
+            "type": "string",
+            "description": "产物 ID（`art_` 前缀）。同时也是公开分享链接的标识。"
           },
           "share_enabled": {
-            "description": "本响应中固定为 `true`。",
-            "type": "boolean"
+            "type": "boolean",
+            "description": "本响应中固定为 `true`。"
           },
-          "shared_at": {
-            "description": "最近一次开启分享或更新快照的 Unix 毫秒时间戳。",
-            "format": "int64",
-            "type": "integer"
+          "public_url": {
+            "type": "string",
+            "description": "匿名公开链接，形如 `<控制台域名>/share/artifact/<artifact_id>`。任何拿到链接的人无需登录即可查看内容。每次开启分享得到的都是同一个链接。"
           },
           "shared_by": {
-            "description": "开启分享的成员 ID。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "开启分享的成员 ID。同步快照时保持原值。"
+          },
+          "shared_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "最近一次开启分享或更新快照的 Unix 毫秒时间戳。"
           }
         },
         "required": [
@@ -2806,8 +2857,7 @@
           "public_url",
           "shared_by",
           "shared_at"
-        ],
-        "type": "object"
+        ]
       },
       "ArtifactSignRequest": {
         "description": "为文件申请签名下载/预览链接。",
@@ -2827,247 +2877,259 @@
         "type": "object"
       },
       "ArtifactUpdateRequest": {
+        "type": "object",
         "description": "产物的部分字段更新。仅更新传入的字段。",
         "properties": {
           "artifact_id": {
-            "description": "产物 ID（`art_` 前缀）。同时也是公开分享链接的标识。",
-            "type": "string"
+            "type": "string",
+            "description": "产物 ID（`art_` 前缀）。同时也是公开分享链接的标识。"
           },
-          "team_id": {
-            "description": "转移目标空间。`0` 表示转为个人产物（仅创建者可管理）；大于 0 表示转移到调用者所属的团队。不传则不变。",
-            "format": "int64",
+          "title": {
             "type": [
-              "integer",
+              "string",
               "null"
-            ]
+            ],
+            "description": "新标题。会去除首尾空白，为空时返回 `InvalidParameter`。不传或传 `null` 则保持不变。"
           },
-          "title": {
-            "description": "新标题。会去除首尾空白，传入时不能为空。不传则不变。",
+          "team_id": {
             "type": [
-              "string",
+              "integer",
               "null"
-            ]
+            ],
+            "format": "int64",
+            "description": "转移目标。`0` 表示转为个人产物，仅创建者本人可执行；大于 0 表示转移到该团队，调用者必须是该团队成员；负数返回 `InvalidParameter`。不传或传 `null` 则保持当前空间。创建者（`person_id`）不会改变。"
           }
         },
         "required": [
           "artifact_id"
-        ],
-        "type": "object"
+        ]
       },
       "AssignIncidentRequest": {
+        "type": "object",
         "description": "分派故障的参数。`incident_id` 与 `incident_ids` 二选一。",
+        "required": [
+          "assigned_to"
+        ],
         "properties": {
-          "assigned_to": {
-            "$ref": "#/components/schemas/AssignedTo",
-            "description": "分派目标，`person_ids` 与 `escalate_rule_id` 至少设置一项。"
-          },
           "incident_id": {
-            "description": "单个故障 ID。当 `incident_ids` 也传入时将被忽略。",
+            "type": "string",
             "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
+            "description": "单个故障 ID。当 `incident_ids` 也传入时将被忽略。"
           },
           "incident_ids": {
-            "description": "批量分派的故障 ID 列表，可通过 `POST /incident/list` 获取。",
+            "type": "array",
             "items": {
-              "pattern": "^[0-9a-fA-F]{24}$",
-              "type": "string"
+              "type": "string",
+              "pattern": "^[0-9a-fA-F]{24}$"
             },
-            "maxItems": 100,
             "minItems": 1,
-            "type": "array"
+            "maxItems": 100,
+            "description": "批量分派的故障 ID 列表，可通过 `POST /incident/list` 获取。"
+          },
+          "assigned_to": {
+            "$ref": "#/components/schemas/AssignedTo",
+            "description": "分派对象。设置 `person_ids`、`escalate_rule_id` 或 `emails`；都未设置时服务端会重新匹配协作空间的分派策略。"
           }
-        },
-        "required": [
-          "assigned_to"
-        ],
-        "type": "object"
+        }
       },
       "AssignedTo": {
-        "description": "故障分派目标。`person_ids` 与 `escalate_rule_id` 至少设置一项。",
+        "type": "object",
+        "description": "分派对象。请求中设置 `person_ids`、`escalate_rule_id` 或 `emails`；都未设置时服务端会重新匹配协作空间的分派策略。响应中该对象始终存在；从未分派过的故障 `type`、`id` 为空，`assigned_at` 为 `0`。",
         "properties": {
-          "assigned_at": {
-            "description": "指派发生的 Unix 时间戳（秒）。",
-            "format": "int64",
-            "type": "integer"
-          },
-          "emails": {
-            "description": "邮箱接收人列表，用于 ServiceNow 等外部系统。",
+          "person_ids": {
+            "type": "array",
             "items": {
-              "format": "email",
-              "type": "string"
+              "type": "integer",
+              "format": "int64"
             },
-            "maxItems": 100,
             "minItems": 1,
-            "type": "array"
+            "maxItems": 100,
+            "description": "直接指派的成员 ID 列表。"
           },
           "escalate_rule_id": {
-            "description": "按分派策略指派时使用的策略 ID（MongoDB ObjectID）。",
+            "type": "string",
             "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
+            "description": "按分派策略指派时使用的策略 ID（MongoDB ObjectID）。"
           },
-          "escalate_rule_name": {
-            "description": "分派策略名称，由服务端填充。",
-            "type": "string"
+          "layer_idx": {
+            "type": "integer",
+            "description": "`escalate_rule_id` 中的分派层级，从 0 开始（`0` 为第一级）。处理人取自该层级。"
           },
-          "id": {
-            "description": "服务端生成的指派 ID。",
-            "type": "string"
+          "type": {
+            "type": "string",
+            "description": "分派方式：`assign` 首次分派；`reassign` 对已分派故障的重新分派；`escalate` 由升级流程触发；`reopen` 故障重开后的重新分派；故障从未分派时响应中为空字符串。请求中可不传，由服务端推断。",
+            "enum": [
+              "assign",
+              "reassign",
+              "escalate",
+              "reopen",
+              ""
+            ]
           },
-          "layer_idx": {
-            "description": "当前环节索引。",
-            "type": "integer"
+          "emails": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "format": "email"
+            },
+            "minItems": 1,
+            "maxItems": 100,
+            "description": "成员邮箱；每个邮箱会解析为成员 ID 并合并到 `person_ids`。找不到对应成员的邮箱会被忽略。"
           },
           "notify": {
+            "type": "object",
             "description": "为本次指派覆盖通知渠道。",
             "properties": {
               "follow_preference": {
-                "description": "为 false 时使用 `personal_channels`；为 true 或省略时跟随处理人员的个人偏好。",
                 "type": [
                   "boolean",
                   "null"
-                ]
+                ],
+                "description": "`true`：按每个人的个人通知偏好发送。`false`：使用 `personal_channels`，此时该字段不能为空。不传时必须设置 `personal_channels`。"
               },
               "personal_channels": {
-                "description": "使用的通知渠道（如 `voice`、`sms`、`email`）。",
+                "type": "array",
                 "items": {
                   "type": "string"
                 },
-                "type": "array"
+                "description": "`follow_preference` 为 `false` 时使用的通知渠道：`sms`、`voice`、`email`、`push`（手机 App 推送），或写作 `feishu_app:<integration_id>`、`dingtalk_app:<integration_id>`、`wecom_app:<integration_id>`、`slack_app:<integration_id>`、`teams_app:<integration_id>` 的 IM 应用渠道。`follow_preference` 为 `true` 时忽略。"
               },
               "template_id": {
-                "description": "通知模板 ID（MongoDB ObjectID）。",
+                "type": "string",
                 "pattern": "^[0-9a-fA-F]{24}$",
-                "type": "string"
+                "description": "通知模板 ID（MongoDB ObjectID）。"
               }
-            },
-            "type": "object"
+            }
           },
-          "person_ids": {
-            "description": "直接指派的成员 ID 列表。",
+          "escalate_rule_name": {
+            "type": "string",
+            "description": "分派策略名称，由服务端在响应中填写；请求中传入会被忽略。"
+          },
+          "assigned_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "分派发生的 Unix 时间戳（秒），由服务端设置。"
+          },
+          "id": {
+            "type": "string",
+            "description": "服务端为每次分派生成的 ID。"
+          },
+          "effective_person_ids": {
+            "type": "array",
             "items": {
-              "format": "int64",
-              "type": "integer"
+              "type": "integer",
+              "format": "int64"
             },
-            "maxItems": 100,
-            "minItems": 1,
-            "type": "array"
-          },
-          "type": {
-            "description": "指派类型：`assign` 直接指派、`reassign` 重新指派、`escalate` 分派策略驱动、`reopen` 重新打开时自动指派。",
-            "enum": [
-              "assign",
-              "reassign",
-              "escalate",
-              "reopen"
-            ],
-            "type": "string"
+            "description": "实际接收分派的成员 ID：`person_ids` 加上所选分派层级的成员，去重并排序。由服务端设置；为空时省略。"
           }
-        },
-        "type": "object"
+        }
       },
       "AuditLog": {
+        "type": "object",
         "description": "单条审计日志。",
+        "required": [
+          "created_at",
+          "account_id",
+          "member_id",
+          "member_name",
+          "request_id",
+          "ip",
+          "operation",
+          "operation_name",
+          "body",
+          "params",
+          "is_dangerous",
+          "is_write",
+          "principal_kind",
+          "credential_type",
+          "credential_id"
+        ],
         "properties": {
-          "account_id": {
-            "description": "账户 ID。",
-            "format": "uint64",
-            "type": "integer"
-          },
-          "body": {
-            "description": "JSON 编码的请求体。包含敏感字段时整体改为 base64url 编码存储；超过 10 KB 时以截断占位说明替代。",
-            "type": "string"
-          },
           "created_at": {
-            "description": "操作时间，Unix 毫秒时间戳。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "操作时间，Unix 毫秒时间戳。"
           },
-          "credential_id": {
-            "description": "凭据 ID（App Key 的 ID）；`credential_type` 非 `app_key` 时为 0。",
+          "account_id": {
+            "type": "integer",
             "format": "uint64",
-            "type": "integer"
-          },
-          "credential_type": {
-            "description": "调用使用的凭据类型。控制台长期有效的 App Key 为 `app_key`，AI SRE 签发的短期 Key 为 `ephemeral_app_key`，成员会话为空字符串。",
-            "type": "string"
-          },
-          "ip": {
-            "description": "调用者的客户端 IP 地址。",
-            "type": "string"
-          },
-          "is_dangerous": {
-            "description": "是否被标记为高危操作。",
-            "type": "boolean"
-          },
-          "is_write": {
-            "description": "是否为写操作；false 表示只读操作。",
-            "type": "boolean"
+            "description": "该条记录所属账户的 ID。"
           },
           "member_id": {
-            "description": "执行操作的成员 ID。由账户主体（owner）亲自执行时为 0。",
+            "type": "integer",
             "format": "uint64",
-            "type": "integer"
+            "description": "执行操作的成员 ID。由账户主体（owner）亲自执行时为 0。"
           },
           "member_name": {
-            "description": "成员显示名称。`member_id` 为 0 时为空字符串。",
-            "type": "string"
+            "type": "string",
+            "description": "成员显示名称。`member_id` 为 0 时为空字符串。"
+          },
+          "request_id": {
+            "type": "string",
+            "description": "用于关联的唯一请求 ID。"
+          },
+          "ip": {
+            "type": "string",
+            "description": "调用者的客户端 IP 地址。"
           },
           "operation": {
-            "description": "稳定的机器可读操作名称，如 `template:write:create`。",
-            "type": "string"
+            "type": "string",
+            "description": "稳定的机器可读操作名称，如 `template:write:create`。"
           },
           "operation_name": {
-            "description": "操作的可读中文名称（如 `创建模板`）。",
-            "type": "string"
+            "type": "string",
+            "description": "操作的可读中文名称（如 `创建模板`）。"
+          },
+          "body": {
+            "type": "string",
+            "description": "JSON 编码的请求体。包含敏感字段时整体改为 base64url 编码存储；超过 10 KB 时以截断占位说明替代。"
           },
           "params": {
-            "description": "URL 路径参数的键值对数组，无参数时为空数组。",
+            "type": [
+              "array",
+              "string"
+            ],
             "items": {
+              "type": "object",
               "properties": {
                 "Key": {
-                  "description": "URL 路径参数名（路由中 `:xxx` 占位符的名称）。",
-                  "type": "string"
+                  "type": "string",
+                  "description": "URL 路径参数名（路由中 `:xxx` 占位符的名称）。"
                 },
                 "Value": {
-                  "description": "该路径参数在本次请求中的实际取值。",
-                  "type": "string"
+                  "type": "string",
+                  "description": "该路径参数在本次请求中的实际取值。"
                 }
-              },
-              "type": "object"
+              }
             },
-            "type": "array"
+            "description": "URL 路径参数，为 `Key`/`Value` 键值对数组（没有时为空数组）。部分部署形态会以 JSON 编码的字符串形式返回同一数组。"
+          },
+          "is_dangerous": {
+            "type": "boolean",
+            "description": "是否被标记为高危操作。"
+          },
+          "is_write": {
+            "type": "boolean",
+            "description": "是否为写操作；false 表示只读操作。"
           },
           "principal_kind": {
-            "description": "调用方类型。`member` —— 成员会话；`service` —— App Key 凭据。",
+            "type": "string",
             "enum": [
               "member",
               "service"
             ],
-            "type": "string"
+            "description": "调用方类型。`member`——成员或账户主体的会话；`service`——App Key，或签发给 AI SRE 的短期密钥。"
           },
-          "request_id": {
-            "description": "用于关联的唯一请求 ID。",
-            "type": "string"
+          "credential_type": {
+            "type": "string",
+            "description": "调用使用的凭据类型。控制台长期有效的 App Key 为 `app_key`，AI SRE 签发的短期 Key 为 `ephemeral_app_key`，成员会话为空字符串。"
+          },
+          "credential_id": {
+            "type": "integer",
+            "format": "uint64",
+            "description": "凭据 ID（App Key 的 ID）；`credential_type` 非 `app_key` 时为 0。"
           }
-        },
-        "required": [
-          "created_at",
-          "account_id",
-          "member_id",
-          "member_name",
-          "request_id",
-          "ip",
-          "operation",
-          "operation_name",
-          "body",
-          "params",
-          "is_dangerous",
-          "is_write",
-          "principal_kind",
-          "credential_type",
-          "credential_id"
-        ],
-        "type": "object"
+        }
       },
       "AuditOperationListRequest": {
         "additionalProperties": false,
@@ -3111,82 +3173,82 @@
         "type": "object"
       },
       "AuditRecordIDRequest": {
+        "type": "object",
+        "required": [
+          "id"
+        ],
         "properties": {
           "id": {
-            "description": "审计记录 ID——来自 `POST /monit/rule/audits` 返回行的 `id`，不是规则 ID。传规则 ID 会返回 HTTP 400。",
+            "type": "integer",
             "format": "uint64",
-            "type": "integer"
+            "description": "审计记录 ID——来自 `POST /monit/rule/audits` 返回行的 `id`，不是规则 ID。传入规则 ID 时会被当作审计记录 ID 查询，通常返回 `InvalidParameter`（`alert rule audit not found`）或一条不相关的记录。"
           }
-        },
-        "required": [
-          "id"
-        ],
-        "type": "object"
+        }
       },
       "AuditSearchRequest": {
+        "type": "object",
         "description": "审计日志检索的过滤条件，时间范围必填。",
+        "required": [
+          "start_time",
+          "end_time"
+        ],
         "properties": {
+          "start_time": {
+            "type": "integer",
+            "format": "int64",
+            "description": "检索窗口起点，Unix 秒级时间戳（不含该秒本身）。",
+            "example": 1712620800,
+            "minimum": 1
+          },
           "end_time": {
+            "type": "integer",
+            "format": "int64",
             "description": "检索窗口终点，Unix 秒级时间戳（含该秒）。必须大于 `start_time`，最大跨度 90 天。",
             "example": 1712707200,
-            "format": "int64",
-            "minimum": 1,
-            "type": "integer"
-          },
-          "is_dangerous": {
-            "description": "为 true 时只返回高危操作。",
-            "type": [
-              "boolean",
-              "null"
-            ]
-          },
-          "is_write": {
-            "description": "为 true 时只返回写操作；为 false 时只返回读操作。",
-            "type": [
-              "boolean",
-              "null"
-            ]
+            "minimum": 1
           },
           "limit": {
-            "description": "分页大小，0–99。省略或传 0 表示不分页——返回时间窗内全部匹配记录。",
-            "example": 20,
-            "maximum": 99,
+            "type": "integer",
+            "description": "每页条数，0–99。不传或为 0 时由服务端决定每页条数（可能返回全部匹配条目）。",
             "minimum": 0,
-            "type": "integer"
+            "maximum": 99,
+            "example": 20
+          },
+          "request_id": {
+            "type": "string",
+            "description": "按唯一请求 ID 过滤到单条记录。"
+          },
+          "search_after_ctx": {
+            "type": "string",
+            "description": "上次响应返回的不透明分页游标。首页留空。"
           },
           "operations": {
-            "description": "按操作名称过滤。合法值可通过 `POST /audit/operation/list` 获取。",
+            "type": "array",
             "items": {
               "type": "string"
             },
-            "type": "array"
+            "description": "按操作名称过滤。合法值可通过 `POST /audit/operation/list` 获取。"
           },
           "person_id": {
-            "description": "按操作人过滤，取成员 ID（可通过 `POST /member/list` 获取）；传账户 ID 则匹配账户主体自身的操作。",
+            "type": "integer",
             "format": "uint64",
-            "type": "integer"
-          },
-          "request_id": {
-            "description": "按唯一请求 ID 过滤到单条记录。",
-            "type": "string"
+            "description": "按操作人过滤，取成员 ID（可通过 `POST /member/list` 获取）；传账户 ID 则匹配账户主体自身的操作。"
           },
-          "search_after_ctx": {
-            "description": "上次响应返回的不透明分页游标。首页留空。",
-            "type": "string"
+          "is_dangerous": {
+            "type": [
+              "boolean",
+              "null"
+            ],
+            "description": "为 true 时只返回高危操作。"
           },
-          "start_time": {
-            "description": "检索窗口起点，Unix 秒级时间戳（不含该秒本身）。",
-            "example": 1712620800,
-            "format": "int64",
-            "minimum": 1,
-            "type": "integer"
+          "is_write": {
+            "type": [
+              "boolean",
+              "null"
+            ],
+            "description": "为 true 时只返回写操作；为 false 时只返回读操作。"
           }
-        },
-        "required": [
-          "start_time",
-          "end_time"
-        ],
-        "type": "object"
+        }
       },
       "AuditSearchResponse": {
         "description": "游标分页的审计日志检索结果。",
@@ -3216,94 +3278,134 @@
         "type": "object"
       },
       "AutomationRuleCreateRequest": {
+        "type": "object",
         "description": "创建自动化规则。",
         "properties": {
-          "cron_expr": {
-            "description": "运行周期。支持 4 段 `hour day month weekday`，会补 `minute=0`；也支持 5 段 `minute hour day month weekday`。分钟必须是固定整数，秒级 6 段不支持。同时设置日期和星期几的 cron 会被拒绝。创建 API 当前要求该字段，即使只启用 HTTP POST trigger，也要提供一个有效 cron 并把 `schedule_trigger_enabled` 设为 false。",
-            "example": "15 9 * * *",
-            "type": "string"
+          "name": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 255,
+            "description": "规则显示名称，1–255 个字符；首尾空格会被去除。"
+          },
+          "team_id": {
+            "type": "integer",
+            "format": "int64",
+            "minimum": 0,
+            "description": "规则作用域。`0` 或省略：调用者的个人规则。`>0`：团队规则，调用者必须是该团队成员。作用域创建后不可修改。"
+          },
+          "run_in": {
+            "type": "string",
+            "enum": [
+              "web",
+              "current-chat"
+            ],
+            "description": "规则运行的位置。`web`（默认）：在 Web 控制台会话中运行。`current-chat`：在创建规则时所在的 IM 群聊中运行；仅在与 AI SRE Agent 的实时 IM 会话中可用，API 调用传入会返回 `400`。"
           },
           "enabled": {
-            "description": "规则创建后是否启用。API 省略时为 false；Chat/CLI 入口会默认发送 true，除非用户要求禁用。",
-            "type": "boolean"
+            "type": "boolean",
+            "description": "创建后是否启用规则的自动触发器（定时、HTTP POST、On-call 故障、作战室）。默认 `false`。手动运行不受此影响。"
           },
-          "environment_id": {
-            "description": "BYOC Runner ID。仅 `environment_kind=byoc` 时使用。",
-            "type": "string"
+          "cron_expr": {
+            "type": "string",
+            "description": "按 `timezone` 本地时间计算的调度表达式。支持 4 段（`hour day month weekday`，分钟默认为 0）或 5 段（`minute hour day month weekday`）。分钟必须是一个固定整数；不支持秒级 6 段；同时指定日期和星期几会被拒绝。即使规则只使用其他触发器也必填：请传一个合法表达式并将 `schedule_trigger_enabled` 设为 `false`。",
+            "example": "15 9 * * *"
+          },
+          "timezone": {
+            "type": "string",
+            "description": "计算 `cron_expr` 所用的 IANA 时区名，例如 `Asia/Shanghai`。`Local`、`CST`、`UTC+8`、`GMT+8` 等含糊名称会被拒绝。省略时依次使用调用者的成员时区、账户时区，最后为 `Asia/Shanghai`。"
+          },
+          "schedule_trigger_enabled": {
+            "type": [
+              "boolean",
+              "null"
+            ],
+            "description": "是否启用定时触发器。省略时为 `true`；只希望由其他触发器触发的规则请传 `false`。"
+          },
+          "prompt": {
+            "type": "string",
+            "minLength": 1,
+            "description": "每次运行发给 AI SRE Agent 的任务指令。去除首尾空格后不能为空。"
           },
           "environment_kind": {
+            "type": "string",
             "description": "运行环境类型。省略或空字符串表示自动选择。可选值：`cloud`（平台托管的云端沙箱）、`byoc`（账户内自托管的 BYOC 运行器，需配合 `environment_id`）；自动选择时优先使用在线的 BYOC 运行器，否则使用云端沙箱。",
             "enum": [
               "",
               "cloud",
               "byoc"
-            ],
-            "type": "string"
+            ]
+          },
+          "environment_id": {
+            "type": "string",
+            "description": "BYOC 运行器 ID。`environment_kind=byoc` 时必填，其他类型下传入会被拒绝。个人规则只能使用账户级运行器；团队规则可使用账户级运行器或本团队的运行器。"
           },
           "http_post_trigger_enabled": {
-            "description": "是否创建并启用 HTTP POST trigger。启用时响应里会返回一次性 token。",
-            "type": "boolean"
+            "type": "boolean",
+            "description": "是否创建并启用 HTTP POST 触发器。为 `true` 时，响应会返回 `http_post_trigger_url` 和一次性的 `http_post_token`。"
           },
-          "name": {
-            "description": "规则名称。",
-            "maxLength": 255,
-            "minLength": 1,
-            "type": "string"
+          "oncall_incident_trigger_enabled": {
+            "type": "boolean",
+            "description": "是否启用 On-call 故障触发器。创建该触发器时（本字段为 `true`，或传了协作空间 ID 或严重程度），`oncall_incident_channel_ids` 和 `oncall_incident_severities` 都必须非空。"
           },
           "oncall_incident_channel_ids": {
-            "description": "监听的 On-call 集成 ID 列表；创建或启用该触发器时至少需要一个有效 ID。",
+            "type": "array",
             "items": {
+              "type": "integer",
               "format": "int64",
-              "minimum": 1,
-              "type": "integer"
+              "minimum": 1
             },
-            "type": "array"
+            "description": "要监听的协作空间 ID；这些协作空间中的故障可以发起运行。每个 ID 必须为正数。"
           },
           "oncall_incident_severities": {
-            "description": "监听的故障严重程度，支持 Critical、Warning 和 Info；创建或启用该触发器时至少需要一个值。",
+            "type": "array",
             "items": {
+              "type": "string",
               "enum": [
                 "Critical",
                 "Warning",
                 "Info"
-              ],
-              "type": "string"
+              ]
             },
-            "type": "array"
+            "description": "要监听的故障严重程度：`Critical`（最严重）、`Warning` 或 `Info`（最轻）——即 On-call 故障的严重程度。"
           },
-          "oncall_incident_trigger_enabled": {
-            "description": "是否启用 On-call 故障触发器。",
-            "type": "boolean"
-          },
-          "prompt": {
-            "description": "每次运行发给 AI SRE Agent 的任务提示词。",
-            "minLength": 1,
-            "type": "string"
-          },
-          "schedule_trigger_enabled": {
-            "description": "是否启用 schedule trigger。省略时为 true；HTTP-POST-only 规则应传 false。",
+          "oncall_incident_merge_similar": {
             "type": [
               "boolean",
               "null"
-            ]
+            ],
+            "description": "是否将相似故障合并分析。为 `true`（默认）时，与本规则正在分析的故障（运行中或 10 分钟内刚结束的运行）高度相似的新故障会加入该运行的会话，而不新开运行；其自身的运行记录为 `skipped`，并带有 `joined_session_id`。为 `false` 时，每个命中的故障都单独发起运行。"
           },
-          "team_id": {
-            "description": "作用域团队 ID。0 或省略表示个人规则；>0 表示账户下某团队。之后可通过 update 改派（团队规则转个人仅规则 owner 可操作；转入团队要求调用者属于该团队）。",
-            "format": "int64",
-            "minimum": 0,
-            "type": "integer"
+          "war_room_trigger_enabled": {
+            "type": "boolean",
+            "description": "是否启用作战室触发器。当 `war_room_channel_ids` 中某个协作空间的故障（严重程度在 `war_room_severities` 中）创建作战室（IM 群聊）时触发，Agent 会直接在该群聊中运行。创建该触发器时（本字段为 `true`，或传了 `war_room_channel_ids`），两个列表都必须非空。"
           },
-          "timezone": {
-            "description": "`cron_expr` 计算所用的 IANA 时区，例如 `Asia/Shanghai`。必须是服务端可加载的合法时区名，非法值会被拒绝。省略时依次回退到调用者的成员时区、账户时区，最后是服务端默认时区（Asia/Shanghai）。",
-            "type": "string"
+          "war_room_channel_ids": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "int64",
+              "minimum": 1
+            },
+            "description": "创建作战室时会发起运行的协作空间 ID。每个 ID 必须为正数。"
+          },
+          "war_room_severities": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "enum": [
+                "Critical",
+                "Warning",
+                "Info"
+              ]
+            },
+            "description": "故障创建作战室时会发起运行的严重程度：`Critical`（最严重）、`Warning` 或 `Info`（最轻）——即 On-call 故障的严重程度。"
           }
         },
         "required": [
           "name",
           "cron_expr",
           "prompt"
-        ],
-        "type": "object"
+        ]
       },
       "AutomationRuleIDRequest": {
         "properties": {
@@ -3318,139 +3420,278 @@
         "type": "object"
       },
       "AutomationRuleItem": {
+        "type": "object",
         "description": "自动化规则。",
         "properties": {
+          "rule_id": {
+            "type": "string",
+            "description": "规则 ID（前缀 `arule_`）。获取、更新、删除、运行和查询运行记录时作为 `rule_id` 传入。"
+          },
           "account_id": {
-            "description": "账户 ID。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "规则所属账户的 ID。"
           },
-          "can_edit": {
-            "description": "当调用者可管理该规则时为 true：个人规则仅限创建者；团队规则限账户管理员或规则所属团队成员。",
-            "type": "boolean"
+          "team_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "作用域团队 ID；`0` 表示个人规则。创建后不可修改。"
           },
-          "created_at": {
-            "description": "创建时间，Unix 毫秒。",
+          "owner_id": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "创建规则的成员 person ID。对个人规则而言，也是唯一可管理它的人。"
           },
-          "cron_expr": {
-            "description": "规范化后的 5 段 cron 表达式。",
-            "type": "string"
+          "name": {
+            "type": "string",
+            "description": "规则显示名称。"
           },
           "enabled": {
-            "description": "规则是否启用。",
-            "type": "boolean"
+            "type": "boolean",
+            "description": "规则的自动触发器是否启用。停用的规则仍可手动运行。个人规则的创建者离开账户后，规则会被自动停用。"
           },
-          "environment_id": {
-            "description": "BYOC Runner ID。",
-            "type": "string"
+          "run_scope": {
+            "type": "string",
+            "enum": [
+              "person",
+              "team"
+            ],
+            "description": "运行会话作用域。可选值：`person`（个人规则，team_id=0，以创建者个人身份运行；创建者离开账户后规则会被停用）、`team`（团队规则，team_id>0，归属团队并在团队成员间共享，不随创建者离开而失效）。该值由规则的 team_id 派生。"
+          },
+          "cron_expr": {
+            "type": "string",
+            "description": "规范化后的 5 段 cron 表达式（`minute hour day month weekday`），按 `timezone` 计算。"
+          },
+          "timezone": {
+            "type": "string",
+            "description": "`cron_expr` 计算所用的 IANA 时区。该字段上线后创建的规则始终会有值；上线前创建的旧数据可能为空，此时调度仍按 UTC 解析。"
+          },
+          "prompt": {
+            "type": "string",
+            "description": "每次运行发给 AI SRE Agent 的任务指令。"
           },
           "environment_kind": {
+            "type": "string",
             "description": "运行环境类型。省略或空字符串表示自动选择。可选值：`cloud`（平台托管的云端沙箱）、`byoc`（账户内自托管的 BYOC 运行器）；空字符串表示自动选择（优先在线的 BYOC 运行器，否则云端沙箱）。",
             "enum": [
               "",
               "cloud",
               "byoc"
-            ],
-            "type": "string"
+            ]
           },
-          "http_post_token": {
-            "description": "HTTP POST trigger token。只在创建或轮换 token 的响应中返回；请立即保存。",
-            "type": "string"
+          "environment_id": {
+            "type": "string",
+            "description": "`environment_kind=byoc` 时为 BYOC 运行器 ID；其他情况下为空字符串。"
           },
-          "http_post_trigger_enabled": {
-            "description": "HTTP POST trigger 是否启用。",
-            "type": "boolean"
+          "schedule_trigger_id": {
+            "type": "string",
+            "description": "定时触发器 ID；规则没有定时触发器时省略。"
+          },
+          "schedule_trigger_enabled": {
+            "type": "boolean",
+            "description": "定时触发器是否启用。"
           },
           "http_post_trigger_id": {
-            "description": "HTTP POST 触发器 ID；规则没有 HTTP POST 触发器时省略。",
-            "type": "string"
+            "type": "string",
+            "description": "HTTP POST 触发器 ID；规则没有 HTTP POST 触发器时省略。"
           },
           "http_post_trigger_url": {
-            "description": "HTTP POST 触发器路径；规则没有 HTTP POST 触发器时省略。",
-            "type": "string"
+            "type": "string",
+            "description": "触发 HTTP POST 触发器的路径 `/safari/automation/triggers/{trigger_id}/fire`，相对于 API 基础地址。发送 `POST` 并带 `Authorization: Bearer <http_post_token>`。规则没有 HTTP POST 触发器时省略。"
           },
-          "name": {
-            "description": "规则名称。",
-            "type": "string"
+          "http_post_trigger_enabled": {
+            "type": "boolean",
+            "description": "HTTP POST 触发器是否启用。"
+          },
+          "oncall_incident_trigger_id": {
+            "type": "string",
+            "description": "On-call 故障触发器 ID；规则没有 On-call 故障触发器时省略。"
+          },
+          "oncall_incident_trigger_enabled": {
+            "type": "boolean",
+            "description": "On-call 故障触发器是否启用。"
           },
           "oncall_incident_channel_ids": {
-            "description": "要监听的 On-call 渠道 ID。创建或启用该触发器至少需要一个有效 ID；未配置 On-call 故障触发器时省略。",
+            "type": "array",
             "items": {
+              "type": "integer",
               "format": "int64",
-              "minimum": 1,
-              "type": "integer"
+              "minimum": 1
             },
-            "type": "array"
+            "description": "On-call 故障触发器监听的协作空间 ID。规则没有该触发器时省略。"
           },
           "oncall_incident_severities": {
-            "description": "要监听的事故级别。支持的值为 Critical、Warning、Info；创建或启用该触发器至少需要一个值；未配置 On-call 故障触发器时省略。",
+            "type": "array",
             "items": {
+              "type": "string",
               "enum": [
                 "Critical",
                 "Warning",
                 "Info"
-              ],
-              "type": "string"
+              ]
             },
-            "type": "array"
+            "description": "On-call 故障触发器监听的严重程度：`Critical`（最严重）、`Warning` 或 `Info`（最轻）——即 On-call 故障的严重程度。规则没有该触发器时省略。"
           },
-          "oncall_incident_trigger_enabled": {
-            "description": "是否启用 On-call 故障触发器。",
-            "type": "boolean"
+          "oncall_incident_merge_similar": {
+            "type": "boolean",
+            "description": "是否将相似故障合并分析（含义见创建接口）。规则没有 On-call 故障触发器时为 `true`。"
           },
-          "oncall_incident_trigger_id": {
-            "description": "On-call 故障触发器 ID；规则没有 On-call 故障触发器时省略。",
-            "type": "string"
+          "war_room_trigger_id": {
+            "type": "string",
+            "description": "作战室触发器 ID。规则没有作战室触发器时省略。"
           },
-          "owner_id": {
-            "description": "创建者 person ID。",
-            "format": "int64",
-            "type": "integer"
+          "war_room_trigger_enabled": {
+            "type": "boolean",
+            "description": "作战室触发器是否启用。"
           },
-          "prompt": {
-            "description": "任务提示词。",
-            "type": "string"
+          "war_room_channel_ids": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "int64",
+              "minimum": 1
+            },
+            "description": "创建作战室时会发起运行的协作空间 ID。规则没有作战室触发器时省略。"
           },
-          "rule_id": {
-            "description": "规则 ID。",
-            "type": "string"
+          "war_room_severities": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "enum": [
+                "Critical",
+                "Warning",
+                "Info"
+              ]
+            },
+            "description": "创建作战室时会发起运行的严重程度：`Critical`（最严重）、`Warning` 或 `Info`（最轻）——即 On-call 故障的严重程度。规则没有作战室触发器时省略。"
           },
-          "run_scope": {
-            "description": "运行会话作用域。可选值：`person`（个人规则，team_id=0，以创建者个人身份运行；创建者离开账户后规则会被停用）、`team`（团队规则，team_id>0，归属团队并在团队成员间共享，不随创建者离开而失效）。该值由规则的 team_id 派生。",
+          "execution_place": {
+            "type": "string",
             "enum": [
-              "person",
-              "team"
+              "web_console",
+              "im"
             ],
-            "type": "string"
+            "description": "定时、HTTP POST、On-call 故障和手动触发的运行在哪里执行：`web_console`（Web 控制台会话）或 `im`（创建规则时所在的 IM 群聊）。作战室触发的运行始终在作战室群聊中执行。创建后不可修改。"
           },
-          "schedule_next_fire_at_ms": {
-            "description": "下一次计划触发时间，Unix 毫秒；0 表示暂无可用的下一次计划触发。",
-            "format": "int64",
-            "type": "integer"
+          "execution_location": {
+            "type": "object",
+            "description": "规则运行位置的只读描述。",
+            "properties": {
+              "place": {
+                "type": "string",
+                "enum": [
+                  "web_console",
+                  "im"
+                ],
+                "description": "与规则的 `execution_place` 相同：`web_console` 在 Web 控制台会话中运行，`im` 在绑定的 IM 群聊中运行。"
+              },
+              "run_scope": {
+                "type": "string",
+                "enum": [
+                  "person",
+                  "team"
+                ],
+                "description": "`person`：以创建者身份运行；`team`：归属 `team_id` 对应的团队运行。"
+              },
+              "team_id": {
+                "type": "integer",
+                "format": "int64",
+                "description": "运行所属团队；个人规则为 `0`。"
+              },
+              "platform": {
+                "type": "string",
+                "enum": [
+                  "feishu",
+                  "dingtalk",
+                  "wecom",
+                  "slack",
+                  "teams"
+                ],
+                "description": "绑定群聊所在的 IM 平台：`feishu`（飞书）、`dingtalk`（钉钉）、`wecom`（企业微信）、`slack`（Slack）、`teams`（Microsoft Teams）。仅 `place=im` 时返回。"
+              },
+              "conversation_mode": {
+                "type": "string",
+                "enum": [
+                  "direct",
+                  "group_chat",
+                  "group_thread",
+                  "war_room_chat"
+                ],
+                "description": "绑定会话的类型：`direct`（与机器人单聊）、`group_chat`（群聊）、`group_thread`（群聊中的话题）、`war_room_chat`（故障作战室）。仅 `place=im` 时返回。"
+              },
+              "chat_name": {
+                "type": "string",
+                "description": "绑定群聊的名称。仅 `place=im` 且名称已知时返回。"
+              },
+              "description": {
+                "type": "string",
+                "description": "可读的运行位置标签：Web 控制台规则为 `Web console`，否则为群聊名称，或平台加会话类型。"
+              }
+            },
+            "required": [
+              "place",
+              "run_scope",
+              "team_id",
+              "description"
+            ]
           },
-          "schedule_trigger_enabled": {
-            "description": "Schedule trigger 是否启用。",
-            "type": "boolean"
+          "last_run": {
+            "type": "object",
+            "description": "规则最近一次运行。仅列出自动化规则接口返回，且仅当规则至少运行过一次时返回。",
+            "properties": {
+              "run_id": {
+                "type": "string",
+                "description": "运行 ID，与列出自动化运行记录中的一致。"
+              },
+              "status": {
+                "type": "string",
+                "enum": [
+                  "queued",
+                  "running",
+                  "retrying",
+                  "succeeded",
+                  "partial",
+                  "failed",
+                  "skipped",
+                  "abandoned",
+                  "blocked"
+                ],
+                "description": "运行状态，含义与列出自动化运行记录中的 `status` 相同：`queued`、`running`、`retrying`（进行中）；`succeeded`、`partial`、`failed`、`skipped`（未执行或已合并到其他运行）、`abandoned`（未完成被终止）、`blocked`（因等待连接器授权而结束）。"
+              },
+              "started_at": {
+                "type": "integer",
+                "format": "int64",
+                "description": "开始时间，Unix 毫秒。"
+              }
+            },
+            "required": [
+              "run_id",
+              "status",
+              "started_at"
+            ]
           },
-          "schedule_trigger_id": {
-            "description": "定时触发器 ID；规则没有定时触发器时省略。",
-            "type": "string"
+          "http_post_token": {
+            "type": "string",
+            "description": "HTTP POST 触发器 token。只在签发它的响应中返回：带 `http_post_trigger_enabled=true` 的创建、新建该触发器的更新，或带 `rotate_http_post_trigger_token=true` 的更新。请立即保存，之后无法再次读取。"
           },
-          "team_id": {
-            "description": "作用域团队 ID；0 表示个人规则。",
-            "format": "int64",
-            "type": "integer"
+          "can_edit": {
+            "type": "boolean",
+            "description": "调用者可管理（获取、更新、删除、运行）该规则时为 `true`：个人规则的创建者，或团队规则所属团队的成员。账户所有者和管理员没有例外。"
           },
-          "timezone": {
-            "description": "`cron_expr` 计算所用的 IANA 时区。该字段上线后创建的规则始终会有值；上线前创建的旧数据可能为空，此时调度仍按 UTC 解析。",
-            "type": "string"
+          "created_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "创建时间，Unix 毫秒。"
           },
           "updated_at": {
-            "description": "更新时间，Unix 毫秒。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "更新时间，Unix 毫秒。"
+          },
+          "schedule_next_fire_at_ms": {
+            "type": "integer",
+            "format": "int64",
+            "description": "下一次计划触发时间，Unix 毫秒；0 表示暂无可用的下一次计划触发。"
           }
         },
         "required": [
@@ -3472,292 +3713,310 @@
           "created_at",
           "updated_at",
           "schedule_next_fire_at_ms",
-          "oncall_incident_trigger_enabled"
-        ],
-        "type": "object"
+          "oncall_incident_trigger_enabled",
+          "oncall_incident_merge_similar",
+          "war_room_trigger_enabled",
+          "execution_place"
+        ]
       },
       "AutomationRuleListRequest": {
-        "description": "列出当前调用者可见的自动化规则。`all` 包含调用者自己的个人规则和可访问团队的团队规则；账户管理员在列表中不可见他人的个人规则。",
+        "type": "object",
+        "description": "列出调用者可见的自动化规则：自己的个人规则，加上所属团队的团队规则。账户所有者和管理员同样受此限制。",
         "properties": {
-          "enabled": {
-            "description": "按启用状态过滤：`true` 仅返回已启用，`false` 仅返回已停用；省略或传 null 不过滤。",
-            "type": [
-              "boolean",
-              "null"
-            ]
-          },
-          "include_person": {
-            "description": "兼容字段；scope 为空且为 false 时等同于 team。",
-            "type": [
-              "boolean",
-              "null"
-            ]
-          },
-          "keyword": {
-            "description": "按名称关键字过滤。",
-            "maxLength": 64,
-            "type": "string"
+          "p": {
+            "type": "integer",
+            "default": 1,
+            "description": "页码，从 1 开始。"
           },
           "limit": {
+            "type": "integer",
             "default": 20,
             "description": "每页数量。小于 1 时回退为 20，大于 200 时按 200 处理。",
-            "maximum": 200,
-            "type": "integer"
-          },
-          "p": {
-            "default": 1,
-            "description": "页码，从 1 开始。",
-            "type": "integer"
+            "maximum": 200
           },
           "scope": {
-            "description": "作用域过滤：`all`（自己的个人规则 + 可访问团队规则）、`personal` 或 `team`；默认 `all`。",
+            "type": "string",
             "enum": [
               "all",
               "personal",
               "team"
             ],
-            "type": "string"
+            "description": "作用域过滤：`all`（默认）自己的个人规则加所属团队的规则；`personal` 仅自己的个人规则；`team` 仅所属团队的规则。"
           },
           "team_ids": {
-            "description": "过滤到这些团队 ID；该字段只会收窄结果，不会扩大访问范围。",
+            "type": "array",
             "items": {
-              "format": "int64",
-              "type": "integer"
+              "type": "integer",
+              "format": "int64"
             },
-            "type": "array"
+            "description": "过滤到这些团队 ID；该字段只会收窄结果，不会扩大访问范围。"
+          },
+          "include_person": {
+            "type": [
+              "boolean",
+              "null"
+            ],
+            "description": "旧版开关。仅在 `scope` 为空时生效：`false` 等同于 `scope=team`；其他情况忽略。"
+          },
+          "enabled": {
+            "type": [
+              "boolean",
+              "null"
+            ],
+            "description": "按启用状态过滤：`true` 仅返回已启用，`false` 仅返回已停用；省略或传 null 不过滤。"
+          },
+          "keyword": {
+            "type": "string",
+            "maxLength": 64,
+            "description": "返回名称包含该文本的规则。最多 64 个字符。"
           }
-        },
-        "type": "object"
+        }
       },
       "AutomationRuleListResponse": {
+        "type": "object",
         "properties": {
+          "total": {
+            "type": "integer",
+            "format": "int64",
+            "description": "符合过滤条件的规则总数（所有页）。"
+          },
           "rules": {
-            "description": "当前页的自动化规则数组，与 `total` 配合分页。",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/AutomationRuleItem"
             },
-            "type": "array"
-          },
-          "total": {
-            "description": "总数。",
-            "format": "int64",
-            "type": "integer"
+            "description": "当前页的自动化规则数组，与 `total` 配合分页。"
           }
         },
         "required": [
           "total",
           "rules"
-        ],
-        "type": "object"
+        ]
       },
       "AutomationRuleUpdateRequest": {
+        "type": "object",
         "description": "更新自动化规则。字段省略或传 null 表示不修改。",
         "properties": {
-          "cron_expr": {
-            "description": "运行周期。支持 4 段 `hour day month weekday`，会补 `minute=0`；也支持 5 段 `minute hour day month weekday`。分钟必须是固定整数，秒级 6 段不支持。",
-            "example": "15 9 * * *",
+          "rule_id": {
+            "type": "string",
+            "description": "目标规则 ID，取自 `POST /safari/automation/rule/list` 返回的列表。"
+          },
+          "name": {
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "maxLength": 255,
+            "description": "新的显示名称，最多 255 个字符。去除空格后为空会被拒绝。"
+          },
+          "team_id": {
+            "type": [
+              "integer",
+              "null"
+            ],
+            "format": "int64",
+            "minimum": 0,
+            "description": "规则作用域不可修改。请省略本字段或传当前值；传其他值会返回 `400`。"
           },
           "enabled": {
-            "description": "是否启用规则。",
             "type": [
               "boolean",
               "null"
-            ]
+            ],
+            "description": "是否启用规则的自动触发器。省略则保持不变。"
           },
-          "environment_id": {
-            "description": "BYOC Runner ID。",
+          "cron_expr": {
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "新的调度表达式，格式与创建时相同：4 段（`hour day month weekday`）或 5 段（`minute hour day month weekday`），分钟为固定整数，不支持秒，不能同时指定日期和星期几。省略则保持当前表达式。",
+            "example": "15 9 * * *"
+          },
+          "timezone": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "`cron_expr` 使用的新 IANA 时区。传空字符串会存为 `UTC`。省略或传 `null` 保持当前时区。"
+          },
+          "schedule_trigger_enabled": {
+            "type": [
+              "boolean",
+              "null"
+            ],
+            "description": "是否启用定时触发器。省略则保持不变。"
+          },
+          "prompt": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "新的 Agent 任务指令。省略则保持不变。"
           },
           "environment_kind": {
-            "description": "运行环境类型。省略或空字符串表示自动选择。",
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "新的运行环境：`\"\"` 自动选择（优先使用在线的 BYOC 运行器，否则使用云端沙箱）、`cloud` 平台托管的云端沙箱、`byoc` 使用 `environment_id` 指定的运行器。只传本字段不传 `environment_id` 时会清空已存的 `environment_id`。",
             "enum": [
               "",
               "cloud",
               "byoc"
-            ],
+            ]
+          },
+          "environment_id": {
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "BYOC 运行器 ID；最终 `environment_kind` 为 `byoc` 时必填，其他情况下会被拒绝。"
           },
           "http_post_trigger_enabled": {
-            "description": "是否启用 HTTP POST trigger。不存在时设为 true 会创建。",
             "type": [
               "boolean",
               "null"
-            ]
+            ],
+            "description": "启用或停用 HTTP POST 触发器。规则没有该触发器时传 `true` 会创建一个，并在本次响应中返回其 token。"
           },
-          "name": {
-            "description": "新规则名称。",
-            "maxLength": 255,
+          "oncall_incident_trigger_enabled": {
             "type": [
-              "string",
+              "boolean",
               "null"
-            ]
+            ],
+            "description": "启用或停用 On-call 故障触发器。规则还没有该触发器时，创建它还需同时提供 `oncall_incident_channel_ids` 和 `oncall_incident_severities`。"
           },
           "oncall_incident_channel_ids": {
-            "description": "监听的 On-call 集成 ID 列表；创建或启用该触发器时至少需要一个有效 ID。",
+            "type": "array",
             "items": {
+              "type": "integer",
               "format": "int64",
-              "minimum": 1,
-              "type": "integer"
+              "minimum": 1
             },
-            "type": "array"
+            "description": "非空时替换监听的协作空间 ID；空数组或省略则保留已存的 ID。"
           },
           "oncall_incident_severities": {
-            "description": "监听的故障严重程度，支持 Critical、Warning 和 Info；创建或启用该触发器时至少需要一个值。",
+            "type": "array",
             "items": {
+              "type": "string",
               "enum": [
                 "Critical",
                 "Warning",
                 "Info"
-              ],
-              "type": "string"
+              ]
             },
-            "type": "array"
+            "description": "非空时替换监听的严重程度（`Critical`（最严重）、`Warning` 或 `Info`（最轻）——即 On-call 故障的严重程度）；空数组或省略则保留已存的值。"
           },
-          "oncall_incident_trigger_enabled": {
-            "description": "是否启用 On-call 故障触发器。",
+          "oncall_incident_merge_similar": {
             "type": [
               "boolean",
               "null"
-            ]
-          },
-          "prompt": {
-            "description": "新的任务提示词。",
-            "type": [
-              "string",
-              "null"
-            ]
-          },
-          "rotate_http_post_trigger_token": {
-            "description": "是否轮换 HTTP POST trigger token。新 token 只会在本次响应中返回。",
-            "type": "boolean"
-          },
-          "rule_id": {
-            "description": "目标规则 ID，取自 `POST /safari/automation/rule/list` 返回的列表。",
-            "type": "string"
+            ],
+            "description": "是否将相似故障合并分析（含义见创建接口）。省略则保持不变。"
           },
-          "schedule_trigger_enabled": {
-            "description": "是否启用 schedule trigger。",
+          "war_room_trigger_enabled": {
             "type": [
               "boolean",
               "null"
-            ]
+            ],
+            "description": "启用或停用作战室触发器。规则还没有该触发器时，创建它还需同时提供 `war_room_channel_ids` 和 `war_room_severities`。省略则保持不变。"
           },
-          "team_id": {
-            "description": "改派规则作用域：0 表示转为个人规则（团队规则仅规则 owner 可转）；>0 表示转入调用者所属的团队。省略则保持不变。",
-            "format": "int64",
-            "minimum": 0,
-            "type": [
-              "integer",
-              "null"
-            ]
+          "war_room_channel_ids": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "int64",
+              "minimum": 1
+            },
+            "description": "非空时替换会触发运行的作战室协作空间 ID；空数组或省略则保留已存的 ID。"
           },
-          "timezone": {
-            "description": "更新 `cron_expr` 所用的 IANA 时区。省略或传 null 表示保持当前时区不变。",
-            "type": [
-              "string",
-              "null"
-            ]
-          }
-        },
+          "war_room_severities": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "enum": [
+                "Critical",
+                "Warning",
+                "Info"
+              ]
+            },
+            "description": "非空时替换作战室触发的严重程度（`Critical`（最严重）、`Warning` 或 `Info`（最轻）——即 On-call 故障的严重程度）；空数组或省略则保留已存的值。"
+          },
+          "rotate_http_post_trigger_token": {
+            "type": "boolean",
+            "description": "为 `true` 时签发新的 HTTP POST 触发器 token，旧 token 失效。该触发器必须存在且处于启用状态。新 token 只在本次响应中返回。"
+          }
+        },
         "required": [
           "rule_id"
-        ],
-        "type": "object"
+        ]
       },
       "AutomationRunItem": {
+        "type": "object",
         "properties": {
-          "account_id": {
-            "description": "账户 ID。",
-            "format": "int64",
-            "type": "integer"
-          },
-          "attempts": {
-            "description": "尝试次数。",
-            "type": "integer"
-          },
-          "completed_at": {
-            "description": "完成时间，Unix 毫秒。0 表示尚未完成。",
-            "format": "int64",
-            "type": "integer"
+          "run_id": {
+            "type": "string",
+            "description": "运行 ID（前缀 `trun_`）。"
           },
-          "created_at": {
-            "description": "创建时间，Unix 毫秒。",
-            "format": "int64",
-            "type": "integer"
+          "session_id": {
+            "type": "string",
+            "description": "本次运行所在的 AI SRE 会话 ID。运行尚未启动会话、加入了其他运行（见 `joined_session_id`），或在 IM 群聊中执行时省略。"
           },
-          "duration_ms": {
-            "description": "运行耗时，毫秒。",
-            "format": "int64",
-            "type": "integer"
+          "session_name": {
+            "type": "string",
+            "description": "运行会话的显示名称，批量查询填充；为空或查询失败时省略。"
           },
-          "error_code": {
-            "description": "错误码；运行未失败时为空字符串。",
-            "type": "string"
+          "joined_session_id": {
+            "type": "string",
+            "description": "对于合并到相似故障分析中的 On-call 故障运行（`status=skipped`）：其加入的会话 ID。其他情况省略。"
           },
-          "error_message": {
-            "description": "错误信息；运行未失败时为空字符串。",
-            "type": "string"
+          "joined_session_name": {
+            "type": "string",
+            "description": "`joined_session_id` 对应会话的显示名称。为空或名称查询失败时省略。"
           },
           "kind": {
+            "type": "string",
             "description": "运行类型；按规则查询时恒为 `automation_rule`。",
             "enum": [
               "automation_rule"
-            ],
-            "type": "string"
-          },
-          "occurrence_key": {
-            "description": "幂等键。",
-            "type": "string"
-          },
-          "result_json": {
-            "additionalProperties": true,
-            "description": "运行结果原始 JSON（运行启动后携带 `session_id`）；为空时为 null。",
-            "type": [
-              "object",
-              "null"
             ]
           },
-          "rule_id": {
-            "description": "规则 ID。",
-            "type": "string"
-          },
-          "run_id": {
-            "description": "运行 ID。",
-            "type": "string"
+          "account_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "运行所属账户的 ID。"
           },
-          "session_id": {
-            "description": "本次运行创建的会话 ID，从 `result_json` 中提取；运行尚未启动会话时省略。",
-            "type": "string"
+          "rule_id": {
+            "type": "string",
+            "description": "本次运行所属规则的 ID。"
           },
-          "session_name": {
-            "description": "运行会话的显示名称，批量查询填充；为空或查询失败时省略。",
-            "type": "string"
+          "trigger_kind": {
+            "type": "string",
+            "enum": [
+              "schedule",
+              "debug",
+              "manual",
+              "http_post",
+              "oncall_incident",
+              "war_room_created"
+            ],
+            "description": "触发来源。可选值：\n| 值 | 含义 |\n| --- | --- |\n| `schedule` | 定时触发器按计划触发 |\n| `debug` | 调试运行（保留值；当前规则运行不会产生） |\n| `manual` | 通过运行自动化规则接口手动发起 |\n| `http_post` | 通过规则的 HTTP POST 触发器触发 |\n| `oncall_incident` | 由命中条件的 On-call 故障触发 |\n| `war_room_created` | 命中条件的故障创建作战室时触发，在该群聊中运行 |"
           },
-          "started_at": {
-            "description": "开始时间，Unix 毫秒。",
-            "format": "int64",
-            "type": "integer"
+          "execution_place": {
+            "type": "string",
+            "enum": [
+              "web_console",
+              "im"
+            ],
+            "description": "本次运行的执行位置：`web_console`（Web 控制台会话，`session_id` 指向该会话）或 `im`（IM 群聊，不返回会话信息）。`war_room_created` 运行始终为 `im`。"
           },
-          "stats_json": {
-            "additionalProperties": true,
-            "description": "运行统计原始 JSON；为空时为 null。",
-            "type": [
-              "object",
-              "null"
-            ]
+          "occurrence_key": {
+            "type": "string",
+            "description": "本次触发的幂等键：手动运行为 `manual:<run_id>`，定时运行为 `<trigger_id>:<计划触发时间 Unix 毫秒>`，On-call 故障运行为 `oncall_incident:<trigger_id>:<incident_id>`。"
           },
           "status": {
-            "description": "运行状态。可选值（前三个为进行中，其余为终态）：\n| 值 | 含义 |\n| --- | --- |\n| `queued` | 已入队，等待工作器执行 |\n| `running` | 正在执行 |\n| `retrying` | 本次尝试失败，已安排重试 |\n| `succeeded` | 成功完成 |\n| `partial` | 部分成功（当前仅记忆整理类运行会产生；规则运行不会落到该状态） |\n| `failed` | 失败终态，不再重试 |\n| `skipped` | 未执行（如超过宽限期、触发器或规则失效），以运行记录形式留存原因 |\n| `abandoned` | 进行中超过陈旧阈值被后台清扫判为未完成（如工作器异常退出） |\n| `blocked` | 终态：有实际产出，但因连接器等待人工完成授权而结束（区别于 `failed`） |",
+            "type": "string",
             "enum": [
               "queued",
               "running",
@@ -3769,23 +4028,60 @@
               "abandoned",
               "blocked"
             ],
-            "type": "string"
+            "description": "运行状态。可选值（前三个为进行中，其余为终态）：\n| 值 | 含义 |\n| --- | --- |\n| `queued` | 已入队，等待工作器执行 |\n| `running` | 正在执行 |\n| `retrying` | 本次尝试失败，已安排重试 |\n| `succeeded` | 成功完成 |\n| `partial` | 部分成功（当前仅记忆整理类运行会产生；规则运行不会落到该状态） |\n| `failed` | 失败终态，不再重试 |\n| `skipped` | 未执行（如超过宽限期、触发器或规则失效），以运行记录形式留存原因；合并到相似故障分析中的 On-call 故障运行也记为该状态（见 `joined_session_id`） |\n| `abandoned` | 进行中超过陈旧阈值被后台清扫判为未完成（如工作器异常退出） |\n| `blocked` | 终态：有实际产出，但因连接器等待人工完成授权而结束（区别于 `failed`） |"
           },
-          "trigger_kind": {
-            "description": "触发来源。可选值：\n| 值 | 含义 |\n| --- | --- |\n| `schedule` | 定时触发器按调度计划触发 |\n| `debug` | 调试运行（保留值；当前版本的规则运行不产生该来源） |\n| `manual` | 用户手动触发一次运行 |\n| `http_post` | 通过规则的 HTTP POST webhook 触发 |\n| `oncall_incident` | 由值班故障（on-call incident）事件触发 |",
-            "enum": [
-              "schedule",
-              "debug",
-              "manual",
-              "http_post",
-              "oncall_incident"
+          "attempts": {
+            "type": "integer",
+            "description": "本次运行已进行的执行尝试次数。"
+          },
+          "started_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "开始时间，Unix 毫秒。"
+          },
+          "completed_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "完成时间，Unix 毫秒。0 表示尚未完成。"
+          },
+          "duration_ms": {
+            "type": "integer",
+            "format": "int64",
+            "description": "运行耗时，毫秒。"
+          },
+          "error_code": {
+            "type": "string",
+            "description": "错误码；运行未失败时为空字符串。"
+          },
+          "error_message": {
+            "type": "string",
+            "description": "错误信息；运行未失败时为空字符串。"
+          },
+          "stats_json": {
+            "type": [
+              "object",
+              "null"
             ],
-            "type": "string"
+            "additionalProperties": true,
+            "description": "运行统计原始 JSON；为空时为 null。"
+          },
+          "result_json": {
+            "type": [
+              "object",
+              "null"
+            ],
+            "additionalProperties": true,
+            "description": "运行结果原始 JSON（启动会话后携带 `session_id`）。为空或运行在 IM 群聊中执行时为 `null`。"
+          },
+          "created_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "创建时间，Unix 毫秒。"
           },
           "updated_at": {
-            "description": "更新时间，Unix 毫秒。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "更新时间，Unix 毫秒。"
           }
         },
         "required": [
@@ -3794,6 +4090,7 @@
           "account_id",
           "rule_id",
           "trigger_kind",
+          "execution_place",
           "occurrence_key",
           "status",
           "attempts",
@@ -3806,39 +4103,27 @@
           "error_message",
           "stats_json",
           "result_json"
-        ],
-        "type": "object"
+        ]
       },
       "AutomationRunListRequest": {
+        "type": "object",
         "properties": {
-          "limit": {
-            "default": 20,
-            "description": "每页数量。",
-            "type": "integer"
+          "rule_id": {
+            "type": "string",
+            "description": "目标规则 ID，取自 `POST /safari/automation/rule/list` 返回的列表。"
           },
           "p": {
+            "type": "integer",
             "default": 1,
-            "description": "页码，从 1 开始。",
-            "type": "integer"
-          },
-          "rule_id": {
-            "description": "目标规则 ID，取自 `POST /safari/automation/rule/list` 返回的列表。",
-            "type": "string"
-          },
-          "started_after_ms": {
-            "description": "开始时间下界，Unix 毫秒。早于 180 天运行记录保留下限的值会被截断到下限（省略时默认即为该下限）。",
-            "format": "int64",
-            "minimum": 0,
-            "type": "integer"
+            "description": "页码，从 1 开始。"
           },
-          "started_before_ms": {
-            "description": "开始时间上界，Unix 毫秒。必须不早于生效后的 `started_after_ms`；早于保留下限时返回空结果。",
-            "format": "int64",
-            "minimum": 0,
-            "type": "integer"
+          "limit": {
+            "type": "integer",
+            "default": 20,
+            "description": "每页数量。小于 1 时回退为 20。"
           },
           "status": {
-            "description": "运行状态过滤：`queued` 排队中、`running` 运行中、`retrying` 重试中、`succeeded` 成功、`partial` 部分成功、`failed` 失败、`skipped` 已跳过（如规则或触发器失效）、`abandoned` 已放弃（超过时效未完成被系统终结）、`blocked` 已阻塞（终态：有产出但某个连接器正等待人工完成授权）；省略则不过滤。",
+            "type": "string",
             "enum": [
               "queued",
               "running",
@@ -3850,145 +4135,214 @@
               "abandoned",
               "blocked"
             ],
-            "type": "string"
+            "description": "运行状态过滤：`queued` 排队中、`running` 运行中、`retrying` 重试中、`succeeded` 成功、`partial` 部分成功、`failed` 失败、`skipped` 已跳过（如规则或触发器失效）、`abandoned` 已放弃（超过时效未完成被系统终结）、`blocked` 已阻塞（终态：有产出但某个连接器正等待人工完成授权）；省略则不过滤。"
           },
           "trigger_kind": {
-            "description": "触发来源过滤：`schedule` 定时调度、`debug` 调试运行、`manual` 手动触发、`http_post` HTTP POST 触发、`oncall_incident` On-call 故障触发；省略则不过滤。",
+            "type": "string",
             "enum": [
               "schedule",
               "debug",
               "manual",
               "http_post",
-              "oncall_incident"
+              "oncall_incident",
+              "war_room_created"
             ],
-            "type": "string"
+            "description": "触发来源过滤：`schedule` 定时触发、`debug` 调试运行、`manual` 手动运行、`http_post` HTTP POST 触发、`oncall_incident` On-call 故障触发、`war_room_created` 作战室触发；省略则不过滤。"
+          },
+          "started_after_ms": {
+            "type": "integer",
+            "format": "int64",
+            "description": "开始时间下界，Unix 毫秒。早于 180 天运行记录保留下限的值会被截断到下限（省略时默认即为该下限）。",
+            "minimum": 0
+          },
+          "started_before_ms": {
+            "type": "integer",
+            "format": "int64",
+            "description": "开始时间上界，Unix 毫秒。必须不早于生效后的 `started_after_ms`；早于保留下限时返回空结果。",
+            "minimum": 0
           }
         },
         "required": [
           "rule_id"
-        ],
-        "type": "object"
+        ]
       },
       "AutomationRunListResponse": {
+        "type": "object",
         "properties": {
+          "total": {
+            "type": "integer",
+            "format": "int64",
+            "description": "符合过滤条件的运行总数（所有页）。"
+          },
           "runs": {
-            "description": "指定规则（`rule_id`）的运行记录数组，按请求中的状态/触发类型/时间范围过滤并分页。",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/AutomationRunItem"
             },
-            "type": "array"
-          },
-          "total": {
-            "description": "总数。",
-            "format": "int64",
-            "type": "integer"
+            "description": "指定规则（`rule_id`）的运行记录数组，按请求中的状态/触发类型/时间范围过滤并分页。"
           }
         },
         "required": [
           "total",
           "runs"
-        ],
-        "type": "object"
+        ]
       },
       "AutomationRunView": {
+        "type": "object",
         "description": "手动触发所创建运行的引用。",
         "properties": {
           "run_id": {
-            "description": "运行 ID，运行创建后始终会有值。",
-            "type": "string"
+            "type": "string",
+            "description": "运行 ID，运行创建后始终会有值。"
           },
           "session_id": {
-            "description": "本次运行对应的 AI SRE 会话 ID。由于调用只会在会话启动后才返回，因此在 200 响应中始终会有值。",
-            "type": "string"
+            "type": "string",
+            "description": "本次运行启动的 AI SRE 会话 ID。规则在 IM 群聊中执行（`execution_place=im`）时省略。"
           }
         },
         "required": [
           "run_id"
-        ],
-        "type": "object"
+        ]
       },
       "AutomationTemplateItem": {
+        "type": "object",
         "properties": {
-          "description": {
-            "description": "模板说明。",
-            "type": "string"
+          "name": {
+            "type": "string",
+            "description": "本地化的模板名称；可用作规则的 `name`。"
           },
-          "enabled": {
-            "description": "从该模板创建规则时默认是否启用（预填值）。",
-            "type": "boolean"
+          "key": {
+            "type": "string",
+            "description": "与语言无关的稳定模板 ID（小写字母、数字、下划线）。仅控制台其他页面直接引用的模板才有；其他模板省略。"
+          },
+          "description": {
+            "type": "string",
+            "description": "本地化的模板说明，描述基于该模板创建的规则会做什么。"
           },
           "icon": {
-            "description": "图标标识。",
-            "type": "string"
+            "type": "string",
+            "description": "控制台为该模板展示的图标标识，例如 `siren`。"
           },
-          "name": {
-            "description": "模板名称。",
-            "type": "string"
+          "category": {
+            "type": "string",
+            "description": "控制台中模板所在分组的本地化名称（自由文本），例如 `Incident Response`。分组顺序按其第一个模板出现的顺序。"
+          },
+          "enabled": {
+            "type": "boolean",
+            "description": "创建请求中 `enabled` 的预填值。"
           },
           "prompt": {
-            "description": "模板提示词。",
-            "type": "string"
+            "type": "string",
+            "description": "创建请求中 `prompt` 的预填值。"
+          },
+          "schedule_trigger_enabled": {
+            "type": "boolean",
+            "description": "`schedule_trigger_enabled` 的预填值；当且仅当返回 `cron_expr` 时为 `true`。"
+          },
+          "cron_expr": {
+            "type": "string",
+            "description": "`cron_expr` 的预填值。模板不使用定时触发器时省略；创建请求仍需提供合法的 `cron_expr`。"
+          },
+          "http_post_trigger_enabled": {
+            "type": "boolean",
+            "description": "`http_post_trigger_enabled` 的预填值。"
+          },
+          "oncall_incident_trigger_enabled": {
+            "type": "boolean",
+            "description": "`oncall_incident_trigger_enabled` 的预填值；为 `true` 时，创建前需补充 `oncall_incident_channel_ids`。"
+          },
+          "oncall_incident_severities": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "enum": [
+                "Critical",
+                "Warning",
+                "Info"
+              ]
+            },
+            "description": "`oncall_incident_severities` 的预填值（`Critical`（最严重）、`Warning` 或 `Info`（最轻）——即 On-call 故障的严重程度）。模板不使用 On-call 故障触发器时省略。"
+          },
+          "war_room_trigger_enabled": {
+            "type": "boolean",
+            "description": "`war_room_trigger_enabled` 的预填值；为 `true` 时，创建前需补充 `war_room_channel_ids`。"
+          },
+          "war_room_severities": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "enum": [
+                "Critical",
+                "Warning",
+                "Info"
+              ]
+            },
+            "description": "`war_room_severities` 的预填值（`Critical`（最严重）、`Warning` 或 `Info`（最轻）——即 On-call 故障的严重程度）。模板不使用作战室触发器时省略。"
           }
         },
         "required": [
           "name",
           "description",
           "icon",
+          "category",
           "enabled",
-          "prompt"
-        ],
-        "type": "object"
+          "prompt",
+          "schedule_trigger_enabled",
+          "http_post_trigger_enabled",
+          "oncall_incident_trigger_enabled",
+          "war_room_trigger_enabled"
+        ]
       },
       "AutomationTemplateListRequest": {
+        "type": "object",
         "properties": {
           "locale": {
-            "description": "模板语言，例如 zh-CN 或 en-US。省略时按请求语言自动选择。",
+            "type": "string",
             "maxLength": 16,
-            "type": "string"
+            "description": "模板语言。含 `zh` 返回中文，含 `en` 返回英文，其他非空值返回中文。省略时由查询参数 `locale`/`lang` 或请求头 `Accept-Language` 决定，默认中文。"
           }
-        },
-        "type": "object"
+        }
       },
       "AutomationTemplateListResponse": {
+        "type": "object",
         "properties": {
           "templates": {
-            "description": "内置自动化模板数组，展示文案按请求 `locale`（缺省取请求头语种）本地化。",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/AutomationTemplateItem"
             },
-            "type": "array"
+            "description": "按解析出的语言返回的内置模板，按展示顺序排列。"
           }
         },
         "required": [
           "templates"
-        ],
-        "type": "object"
+        ]
       },
       "BindWorkItemPostMortemRequest": {
+        "type": "object",
         "description": "将故障下未绑定的后续行动批量绑定到复盘的参数。",
+        "required": [
+          "post_mortem_id",
+          "incident_id",
+          "idempotency_key"
+        ],
         "properties": {
-          "idempotency_key": {
-            "description": "客户端生成的幂等键（最长 128 字符；仅限字母、数字、`_`、`-`、`.`、`:`）。",
-            "maxLength": 128,
-            "pattern": "^[A-Za-z0-9_\\-.:]+$",
-            "type": "string"
+          "post_mortem_id": {
+            "type": "string",
+            "description": "要绑定后续行动的故障复盘 ID（32 位十六进制字符串）。"
           },
           "incident_id": {
-            "description": "故障 ID（MongoDB ObjectID），其已转化但未绑定的后续行动将被绑定。",
+            "type": "string",
             "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
+            "description": "故障 ID（MongoDB ObjectID），其已转换且未绑定的事项会被绑定。该故障须已关联到 `post_mortem_id`。"
           },
-          "post_mortem_id": {
-            "description": "要绑定后续行动的故障复盘 ID（32 位十六进制字符串）。",
-            "type": "string"
+          "idempotency_key": {
+            "type": "string",
+            "maxLength": 128,
+            "pattern": "^[A-Za-z0-9_\\-.:]+$",
+            "description": "客户端生成的幂等键（最长 128 字符；仅限字母、数字、`_`、`-`、`.`、`:`）。"
           }
-        },
-        "required": [
-          "post_mortem_id",
-          "incident_id",
-          "idempotency_key"
-        ],
-        "type": "object"
+        }
       },
       "CalEventIDRequest": {
         "description": "日历事件删除请求。传入 event_id，或同时传入 start_at 和 end_at。",
@@ -4016,69 +4370,69 @@
         "type": "object"
       },
       "CalEventItem": {
+        "type": "object",
         "description": "日历事件条目。",
+        "required": [
+          "cal_id",
+          "event_id",
+          "summary",
+          "description",
+          "start_at",
+          "end_at",
+          "is_off",
+          "created_at",
+          "updated_at"
+        ],
         "properties": {
           "account_id": {
-            "description": "账户 ID，仅私有事件返回。",
+            "type": "integer",
             "format": "uint64",
-            "type": "integer"
+            "description": "账户 ID，仅私有事件返回。"
+          },
+          "creator_id": {
+            "type": "integer",
+            "format": "uint64",
+            "description": "创建人 ID，仅私有事件返回。"
           },
           "cal_id": {
-            "description": "日历 ID，公共事件为 locale key（如 zh-cn.china.official）。",
-            "type": "string"
+            "type": "string",
+            "description": "日历 ID，公共事件为 locale key（如 zh-cn.china.official）。"
           },
-          "created_at": {
-            "description": "创建时间（Unix 秒）。",
-            "format": "int64",
-            "type": "integer"
+          "event_id": {
+            "type": "string",
+            "description": "事件 ID。日历自有事件为 `cale.<id>`，按非工作日生成的条目为 `non_work.YYYYMMDD`，继承自节假日日历的事件为 `<节假日 cal_id>.<id>`。"
           },
-          "creator_id": {
-            "description": "创建人 ID，仅私有事件返回。",
-            "format": "uint64",
-            "type": "integer"
+          "summary": {
+            "type": "string",
+            "description": "事件摘要。"
           },
           "description": {
-            "description": "事件描述。",
-            "type": "string"
+            "type": "string",
+            "description": "事件描述。"
           },
-          "end_at": {
-            "description": "事件结束日期（YYYY-MM-DD，不含）。",
-            "type": "string"
+          "start_at": {
+            "type": "string",
+            "description": "事件开始日期（YYYY-MM-DD）。"
           },
-          "event_id": {
-            "description": "事件 ID。",
-            "type": "string"
+          "end_at": {
+            "type": "string",
+            "description": "事件结束日期（YYYY-MM-DD，不含）。"
           },
           "is_off": {
-            "description": "是否为非工作日。",
-            "type": "boolean"
-          },
-          "start_at": {
-            "description": "事件开始日期（YYYY-MM-DD）。",
-            "type": "string"
+            "type": "boolean",
+            "description": "是否为非工作日。"
           },
-          "summary": {
-            "description": "事件摘要。",
-            "type": "string"
+          "created_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "创建时间（Unix 秒）；生成的 `non_work.*` 条目为 `0`。"
           },
           "updated_at": {
-            "description": "更新时间（Unix 秒）。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "最后更新时间（Unix 秒）；生成的 `non_work.*` 条目为 `0`。"
           }
-        },
-        "required": [
-          "cal_id",
-          "event_id",
-          "summary",
-          "description",
-          "start_at",
-          "end_at",
-          "is_off",
-          "created_at",
-          "updated_at"
-        ],
-        "type": "object"
+        }
       },
       "CalEventListRequest": {
         "description": "日历事件列表请求。day > 0 时必须同时指定 month；month 与 day 为 0 表示不过滤。",
@@ -4233,50 +4587,50 @@
         "type": "object"
       },
       "CalendarCreateRequest": {
+        "type": "object",
         "description": "创建日历请求，cal_name 必填。",
+        "required": [
+          "cal_name"
+        ],
         "properties": {
           "cal_name": {
-            "description": "日历显示名称。",
-            "maxLength": 39,
+            "type": "string",
+            "description": "日历名称，在账户内必须唯一。",
             "minLength": 1,
-            "type": "string"
+            "maxLength": 39
           },
           "description": {
+            "type": "string",
             "description": "日历描述。",
-            "maxLength": 499,
-            "type": "string"
+            "maxLength": 499
           },
-          "extra_cal_ids": {
-            "description": "需要继承事件的公共节假日日历 ID 列表（例如 zh-cn.china.official）。",
-            "items": {
-              "type": "string"
-            },
-            "type": "array"
+          "timezone": {
+            "type": "string",
+            "description": "IANA 时区，如 `America/New_York`。为空时默认 `Asia/Shanghai`；非法名称返回 `InvalidParameter`。",
+            "default": "Asia/Shanghai"
           },
           "team_id": {
-            "description": "所属团队 ID，0 表示不关联团队。",
+            "type": "integer",
             "format": "uint64",
-            "type": "integer"
-          },
-          "timezone": {
-            "default": "Asia/Shanghai",
-            "description": "IANA 时区，为空时默认 Asia/Shanghai。",
-            "type": "string"
+            "description": "所属团队 ID；为 `0` 或不传表示不归属团队。非零 ID 必须是账户中的团队。"
           },
           "workdays": {
-            "description": "工作日（0 = 周日，6 = 周六）。",
+            "type": "array",
             "items": {
-              "maximum": 6,
+              "type": "integer",
               "minimum": 0,
-              "type": "integer"
+              "maximum": 6
             },
-            "type": "array"
+            "description": "每周工作日，`0` 表示周日……`6` 表示周六。未列出的日子为非工作日。为空时不把任何一天视为非工作日。"
+          },
+          "extra_cal_ids": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "需要继承事件的公共节假日日历 ID 列表（例如 zh-cn.china.official）。"
           }
-        },
-        "required": [
-          "cal_name"
-        ],
-        "type": "object"
+        }
       },
       "CalendarCreateResponse": {
         "description": "创建日历响应。",
@@ -4315,103 +4669,103 @@
         "type": "object"
       },
       "CalendarItem": {
+        "type": "object",
         "description": "服务日历详情。",
+        "required": [
+          "account_id",
+          "team_id",
+          "cal_id",
+          "cal_name",
+          "description",
+          "timezone",
+          "kind",
+          "created_at",
+          "updated_at",
+          "creator_id",
+          "updated_by",
+          "status"
+        ],
         "properties": {
           "account_id": {
-            "description": "账户 ID。",
+            "type": "integer",
             "format": "uint64",
-            "type": "integer"
+            "description": "日历所属账户的 ID。"
+          },
+          "team_id": {
+            "type": "integer",
+            "format": "uint64",
+            "description": "所属团队 ID（0 表示未关联团队）。"
           },
           "cal_id": {
-            "description": "日历 ID。",
-            "type": "string"
+            "type": "string",
+            "description": "日历 ID。"
           },
           "cal_name": {
-            "description": "日历显示名称。",
-            "type": "string"
-          },
-          "created_at": {
-            "description": "创建时间（Unix 秒）。",
-            "format": "int64",
-            "type": "integer"
-          },
-          "creator_id": {
-            "description": "创建人 ID。",
-            "format": "uint64",
-            "type": "integer"
+            "type": "string",
+            "description": "日历显示名称。"
           },
           "description": {
-            "description": "日历描述。",
-            "type": "string"
+            "type": "string",
+            "description": "日历描述。"
           },
-          "extra_cal_ids": {
-            "description": "继承的公共节假日日历 ID 列表。为空时省略。",
-            "items": {
-              "type": "string"
-            },
-            "type": "array"
+          "timezone": {
+            "type": "string",
+            "description": "IANA 时区。"
           },
           "kind": {
+            "type": "string",
             "description": "日历类型。`region.official.holiday` 为地区法定假日公共日历（数据来自中心假日服务），`religion.holiday` 为宗教假日公共日历（预留值，当前无数据），`personal` 为账户自建的个人/团队日历。",
             "enum": [
               "region.official.holiday",
               "religion.holiday",
               "personal"
-            ],
-            "type": "string"
+            ]
           },
-          "status": {
-            "description": "日历状态。`enabled` 正常可用；`deleted` 已删除，列表接口不返回。",
-            "enum": [
-              "enabled",
-              "deleted"
-            ],
-            "type": "string"
+          "workdays": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "minimum": 0,
+              "maximum": 6
+            },
+            "description": "每周工作日，`0` 表示周日……`6` 表示周六。未列出的日子为非工作日。为空时不把任何一天视为非工作日。 为空时不返回。"
           },
-          "team_id": {
-            "description": "所属团队 ID（0 表示未关联团队）。",
-            "format": "uint64",
-            "type": "integer"
+          "extra_cal_ids": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "继承的公共节假日日历 ID 列表。为空时省略。"
           },
-          "timezone": {
-            "description": "IANA 时区。",
-            "type": "string"
+          "created_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "创建时间（Unix 秒）。"
           },
           "updated_at": {
-            "description": "更新时间（Unix 秒）。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "更新时间（Unix 秒）。"
+          },
+          "creator_id": {
+            "type": "integer",
+            "format": "uint64",
+            "description": "创建人 ID。"
           },
           "updated_by": {
-            "description": "最后更新人 ID。",
+            "type": "integer",
             "format": "uint64",
-            "type": "integer"
+            "description": "最后更新人 ID。"
           },
-          "workdays": {
-            "description": "工作日（0 = 周日，6 = 周六）。为空时省略。",
-            "items": {
-              "maximum": 6,
-              "minimum": 0,
-              "type": "integer"
-            },
-            "type": "array"
+          "status": {
+            "type": "string",
+            "description": "日历状态。`enabled` 正常可用；`deleted` 已删除，列表接口不返回。",
+            "enum": [
+              "enabled",
+              "deleted"
+            ]
           }
-        },
-        "required": [
-          "account_id",
-          "team_id",
-          "cal_id",
-          "cal_name",
-          "description",
-          "timezone",
-          "kind",
-          "created_at",
-          "updated_at",
-          "creator_id",
-          "updated_by",
-          "status"
-        ],
-        "type": "object"
+        }
       },
       "CalendarListRequest": {
         "description": "日历列表请求。kind 用于按类型过滤；no_locale 在查询公共节假日日历时关闭 locale 过滤。",
@@ -4454,65 +4808,65 @@
         "type": "object"
       },
       "CalendarUpdateRequest": {
+        "type": "object",
         "description": "更新日历请求。cal_id 必填，其他字段均为可选，仅在传入时更新。",
+        "required": [
+          "cal_id"
+        ],
         "properties": {
           "cal_id": {
-            "description": "日历 ID，可通过 `POST /calendar/list` 获取。",
-            "type": "string"
+            "type": "string",
+            "description": "日历 ID，可通过 `POST /calendar/list` 获取。"
           },
           "cal_name": {
-            "description": "新的日历名称。",
-            "maxLength": 39,
-            "minLength": 1,
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "新的日历名称，在账户内必须唯一。",
+            "minLength": 1,
+            "maxLength": 39
           },
           "description": {
-            "description": "新的描述。",
-            "maxLength": 499,
             "type": [
               "string",
               "null"
-            ]
-          },
-          "extra_cal_ids": {
-            "description": "需要继承事件的公共节假日日历 ID 列表。",
-            "items": {
-              "type": "string"
-            },
-            "type": "array"
+            ],
+            "description": "新的描述。",
+            "maxLength": 499
           },
-          "team_id": {
-            "description": "新的所属团队 ID，可通过 `POST /team/list` 获取。",
-            "format": "uint64",
+          "timezone": {
             "type": [
-              "integer",
+              "string",
               "null"
-            ]
+            ],
+            "description": "新的 IANA 时区，如 `Asia/Shanghai`；非法名称返回 `InvalidParameter`。"
           },
-          "timezone": {
-            "description": "新的 IANA 时区。",
+          "team_id": {
             "type": [
-              "string",
+              "integer",
               "null"
-            ]
+            ],
+            "format": "uint64",
+            "description": "新的所属团队 ID，可从 `POST /team/list` 获取。`0` 表示取消团队归属；非零 ID 必须是账户中的团队。"
           },
           "workdays": {
-            "description": "工作日（0 = 周日，6 = 周六）。",
+            "type": "array",
             "items": {
-              "maximum": 6,
+              "type": "integer",
               "minimum": 0,
-              "type": "integer"
+              "maximum": 6
             },
-            "type": "array"
+            "description": "每周工作日，`0` 表示周日……`6` 表示周六。未列出的日子为非工作日。为空时不把任何一天视为非工作日。 传入时整体替换原列表，不传则保持不变。"
+          },
+          "extra_cal_ids": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "要继承事件的公共节假日日历 ID（见 `kind` 为 `region.official.holiday` 的 `POST /calendar/list`）。传入时整体替换原列表，空数组即全部移除，不传则保持不变。"
           }
-        },
-        "required": [
-          "cal_id"
-        ],
-        "type": "object"
+        }
       },
       "CancelStatusPageMigrationRequest": {
         "description": "取消进行中迁移任务所需的参数。",
@@ -4528,17 +4882,41 @@
         "type": "object"
       },
       "ChangeEventItem": {
+        "type": "object",
         "properties": {
+          "event_id": {
+            "type": "string",
+            "description": "变更事件 ID，MongoDB ObjectID 十六进制字符串。"
+          },
           "account_id": {
+            "type": "integer",
             "description": "变更事件所属账户。",
-            "format": "int64",
-            "type": "integer"
+            "format": "int64"
+          },
+          "channel_id": {
+            "type": "integer",
+            "description": "变更事件所属协作通道。",
+            "format": "int64"
+          },
+          "integration_id": {
+            "type": "integer",
+            "description": "上报该变更事件的集成。",
+            "format": "int64"
+          },
+          "title": {
+            "type": "string",
+            "description": "变更事件标题。"
+          },
+          "description": {
+            "type": "string",
+            "description": "变更事件描述。"
           },
           "change_key": {
-            "description": "用于聚合同一变更下事件的稳定键。",
-            "type": "string"
+            "type": "string",
+            "description": "用于聚合同一变更下事件的稳定键。"
           },
           "change_status": {
+            "type": "string",
             "description": "变更事件的生命周期状态。由变更事件源按执行进度上报。\n| 值 | 含义 |\n|---|---|\n| `Planned` | 已计划，尚未开始。 |\n| `Ready` | 已就绪，待执行。 |\n| `Processing` | 正在执行。 |\n| `Canceled` | 已取消。 |\n| `Done` | 已完成。 |\n| `Failed` | 失败。 |",
             "enum": [
               "Planned",
@@ -4547,81 +4925,112 @@
               "Canceled",
               "Done",
               "Failed"
-            ],
-            "type": "string"
-          },
-          "channel_id": {
-            "description": "变更事件所属协作通道。",
-            "format": "int64",
-            "type": "integer"
-          },
-          "created_at": {
-            "description": "变更事件创建时的 Unix 时间戳（秒）。",
-            "format": "int64",
-            "type": "integer"
-          },
-          "deleted_at": {
-            "description": "变更事件的删除时间，Unix 时间戳（秒）。未删除时不返回该字段。",
-            "format": "int64",
-            "type": "integer"
-          },
-          "description": {
-            "description": "变更事件描述。",
-            "type": "string"
+            ]
           },
-          "event_id": {
-            "description": "变更事件 ID，MongoDB ObjectID 十六进制字符串。",
-            "type": "string"
+          "link": {
+            "type": "string",
+            "description": "指向源变更记录的外部链接。"
           },
           "event_time": {
-            "description": "变更事件发生时的 Unix 时间戳（秒）。",
-            "format": "int64",
-            "type": "integer"
-          },
-          "integration_id": {
-            "description": "上报该变更事件的集成。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "变更事件发生时的 Unix 时间戳（秒）。"
           },
           "labels": {
+            "type": [
+              "object",
+              "null"
+            ],
             "additionalProperties": {
               "type": "string"
             },
-            "description": "附加到变更事件上的键值标签。",
-            "type": "object"
-          },
-          "link": {
-            "description": "指向源变更记录的外部链接。",
-            "type": "string"
+            "description": "附加到变更事件上的键值标签。"
           },
-          "title": {
-            "description": "变更事件标题。",
-            "type": "string"
+          "created_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "变更事件创建时的 Unix 时间戳（秒）。"
           },
           "updated_at": {
-            "description": "变更事件最近更新时的 Unix 时间戳（秒）。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "变更事件最近更新时的 Unix 时间戳（秒）。"
+          },
+          "deleted_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "变更事件的删除时间，Unix 时间戳（秒）。未删除时不返回该字段。"
           }
         },
-        "type": "object"
+        "required": [
+          "event_id",
+          "account_id",
+          "channel_id",
+          "integration_id",
+          "title",
+          "description",
+          "change_key",
+          "change_status",
+          "link",
+          "event_time",
+          "labels",
+          "created_at",
+          "updated_at"
+        ]
       },
       "ChangeItem": {
+        "type": "object",
         "properties": {
+          "change_id": {
+            "type": "string",
+            "description": "变更 ID，MongoDB ObjectID 十六进制字符串。"
+          },
           "account_id": {
+            "type": "integer",
             "description": "变更所属账户。",
-            "format": "int64",
-            "type": "integer"
+            "format": "int64"
           },
-          "change_id": {
-            "description": "变更 ID，MongoDB ObjectID 十六进制字符串。",
-            "type": "string"
+          "channel_id": {
+            "type": "integer",
+            "description": "变更所属协作通道。",
+            "format": "int64"
+          },
+          "channel_name": {
+            "type": "string",
+            "description": "协作空间名称；变更未关联到现有协作空间时为空字符串。"
+          },
+          "channel_status": {
+            "type": "string",
+            "description": "协作空间状态：`enabled` 或 `disabled`；变更未关联到现有协作空间时为空字符串。",
+            "enum": [
+              "enabled",
+              "disabled",
+              ""
+            ]
+          },
+          "integration_id": {
+            "type": "integer",
+            "description": "上报该变更的集成。",
+            "format": "int64"
+          },
+          "integration_name": {
+            "type": "string",
+            "description": "上报集成的名称。"
+          },
+          "title": {
+            "type": "string",
+            "description": "变更标题。"
+          },
+          "description": {
+            "type": "string",
+            "description": "变更描述。"
           },
           "change_key": {
-            "description": "用于聚合同一变更下事件的稳定键。",
-            "type": "string"
+            "type": "string",
+            "description": "用于聚合同一变更下事件的稳定键。"
           },
           "change_status": {
+            "type": "string",
             "description": "变更的当前生命周期状态。\n| 取值 | 含义 |\n|---|---|\n| `Planned` | 已计划，未开始。 |\n| `Ready` | 就绪，待执行。 |\n| `Processing` | 执行中。 |\n| `Canceled` | 已取消。 |\n| `Done` | 已完成。 |\n| `Failed` | 失败。 |",
             "enum": [
               "Planned",
@@ -4630,100 +5039,85 @@
               "Canceled",
               "Done",
               "Failed"
-            ],
-            "type": "string"
+            ]
           },
-          "channel_id": {
-            "description": "变更所属协作通道。",
+          "start_time": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
-          },
-          "channel_name": {
-            "description": "协作通道名称。",
-            "type": "string"
-          },
-          "channel_status": {
-            "description": "协作空间状态：`enabled`（启用）或 `disabled`（禁用）。",
-            "enum": [
-              "enabled",
-              "disabled"
-            ],
-            "type": "string"
-          },
-          "description": {
-            "description": "变更描述。",
-            "type": "string"
+            "description": "变更开始时的 Unix 时间戳（秒）。"
           },
-          "end_time": {
-            "description": "变更结束时的 Unix 时间戳（秒）。",
+          "last_time": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "变更最近活动的 Unix 时间戳（秒）。"
           },
-          "events": {
-            "description": "底层变更事件，仅在 include_events 为 true 时返回。",
-            "items": {
-              "$ref": "#/components/schemas/ChangeEventItem"
-            },
-            "type": "array"
-          },
-          "integration_id": {
-            "description": "上报该变更的集成。",
+          "end_time": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
-          },
-          "integration_name": {
-            "description": "上报集成的名称。",
-            "type": "string"
+            "description": "变更结束时的 Unix 时间戳（秒）。"
           },
           "labels": {
+            "type": [
+              "object",
+              "null"
+            ],
             "additionalProperties": {
               "type": "string"
             },
-            "description": "附加到变更上的键值标签。",
-            "type": "object"
-          },
-          "last_time": {
-            "description": "变更最近活动的 Unix 时间戳（秒）。",
-            "format": "int64",
-            "type": "integer"
+            "description": "变更附带的键值标签；没有标签时为 `null`。"
           },
           "link": {
-            "description": "指向源变更记录的外部链接。",
-            "type": "string"
-          },
-          "start_time": {
-            "description": "变更开始时的 Unix 时间戳（秒）。",
-            "format": "int64",
-            "type": "integer"
+            "type": "string",
+            "description": "指向源变更记录的外部链接。"
           },
-          "title": {
-            "description": "变更标题。",
-            "type": "string"
+          "events": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/ChangeEventItem"
+            },
+            "description": "构成该变更的、由集成上报的原始变更事件。仅在 `include_events` 为 `true` 时返回。"
           }
         },
-        "type": "object"
+        "required": [
+          "change_id",
+          "account_id",
+          "channel_id",
+          "channel_name",
+          "channel_status",
+          "integration_id",
+          "integration_name",
+          "title",
+          "description",
+          "change_key",
+          "change_status",
+          "start_time",
+          "last_time",
+          "end_time",
+          "labels",
+          "link"
+        ]
       },
       "ChannelCreateResponse": {
+        "type": "object",
+        "required": [
+          "channel_id",
+          "channel_name"
+        ],
         "properties": {
           "channel_id": {
-            "description": "新建协作空间的 ID。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "新建协作空间的 ID。"
           },
           "channel_name": {
-            "description": "请求中回显的协作空间名称。",
-            "type": "string"
+            "type": "string",
+            "description": "请求中回显的协作空间名称。"
           },
           "external_report_token": {
-            "description": "外部上报 token，仅在启用外部上报时返回。",
-            "type": "string"
+            "type": "string",
+            "description": "外部上报令牌。仅当请求中 `is_external_report_enabled` 为 `true` 时返回；之后可通过 `POST /channel/info` 再次读取。"
           }
-        },
-        "required": [
-          "channel_id",
-          "channel_name"
-        ],
-        "type": "object"
+        }
       },
       "ChannelIDRequest": {
         "properties": {
@@ -4769,219 +5163,219 @@
         "type": "object"
       },
       "ChannelInfosResponse": {
+        "type": "object",
+        "required": [
+          "items"
+        ],
         "properties": {
           "items": {
-            "description": "请求的 `channel_ids` 中实际存在的协作空间简要信息；未找到的 ID 会被忽略。",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/ChannelShort"
             },
-            "type": "array"
+            "description": "请求中存在的协作空间（含已删除的），不存在的 ID 被忽略。按协作空间创建顺序排列，而非请求顺序。"
           }
-        },
-        "required": [
-          "items"
-        ],
-        "type": "object"
+        }
       },
       "ChannelItem": {
+        "type": "object",
         "description": "协作空间详情记录，所有字段可选，仅在有值时返回。",
         "properties": {
-          "account_id": {
-            "description": "所属账户 ID。",
-            "format": "int64",
-            "type": "integer"
-          },
-          "active_incident_highest_severity": {
-            "description": "协作空间内活跃（已触发或处理中）故障的最高严重程度：`Critical`、`Warning` 或 `Info`。无活跃故障时不返回。",
-            "enum": [
-              "Critical",
-              "Warning",
-              "Info"
-            ],
-            "type": "string"
-          },
-          "auto_resolve_mode": {
-            "description": "自动恢复计时重置方式。`trigger`（默认）计时只在故障触发时启动一次，之后并入的新告警不影响计时；`update` 每当有新告警并入故障时从最新告警时间重新计时。",
-            "enum": [
-              "trigger",
-              "update"
-            ],
-            "type": "string"
-          },
-          "auto_resolve_timeout": {
-            "description": "自动恢复超时，单位秒。0 表示不自动恢复。",
+          "channel_id": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "协作空间 ID，在其他协作空间及策略接口中作为 `channel_id` 传入。"
           },
-          "channel_id": {
-            "description": "协作空间 ID。",
+          "team_id": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "所属团队 ID。"
           },
-          "channel_name": {
-            "description": "协作空间名称。",
-            "type": "string"
+          "team_name": {
+            "type": "string",
+            "description": "所属团队名称（由团队目录解析）。仅 `POST /channel/list`（非 `is_brief`）返回；解析失败时不返回。"
           },
-          "created_at": {
-            "description": "创建时间（Unix 秒）。",
-            "format": "int64",
-            "type": "integer"
+          "managing_team_ids": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "int64"
+            },
+            "description": "可管理该协作空间的其他团队 ID 列表。"
           },
           "creator_id": {
-            "description": "创建者成员 ID。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "创建者成员 ID。"
           },
           "creator_name": {
-            "description": "创建者成员名称（由成员目录解析；无法解析时为空）。",
-            "type": "string"
+            "type": "string",
+            "description": "创建者成员名称。仅 `POST /channel/list`（非 `is_brief`）返回；解析失败时不返回。"
           },
-          "deleted_at": {
-            "description": "删除时间（Unix 秒），仅软删除的协作空间非零。",
+          "account_id": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "所属账户 ID。"
           },
-          "description": {
-            "description": "描述信息。",
-            "type": "string"
+          "channel_name": {
+            "type": "string",
+            "description": "协作空间名称，账户内唯一，1–59 个字符。"
           },
-          "disable_auto_close": {
-            "description": "为 true 时禁用故障自动关闭。",
-            "type": "boolean"
+          "description": {
+            "type": "string",
+            "description": "描述信息。"
           },
-          "disable_outlier_detection": {
-            "description": "为 true 时禁用新奇故障检测。",
-            "type": "boolean"
+          "status": {
+            "type": "string",
+            "enum": [
+              "enabled",
+              "disabled",
+              "deleted"
+            ],
+            "description": "协作空间状态：\n- `enabled`：正常处理新进入的告警事件。\n- `disabled`：新进入的告警事件被丢弃。\n- `deleted`：已删除；只会出现在 `POST /channel/info` 与 `POST /channel/infos` 中，`POST /channel/list` 不返回。"
           },
-          "event_group": {
-            "$ref": "#/components/schemas/EventGroup",
-            "description": "告警事件合并配置。"
+          "deleted_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "删除时间（Unix 秒），仅软删除的协作空间非零。"
           },
-          "external_report_token": {
-            "description": "授予外部上报人的 token。仅在协作空间启用外部上报时返回。",
-            "type": "string"
+          "created_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "创建时间（Unix 秒）。"
           },
-          "flapping": {
-            "$ref": "#/components/schemas/Flapping",
-            "description": "抖动检测配置。"
+          "updated_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "最近更新时间（Unix 秒）。"
           },
-          "group": {
-            "$ref": "#/components/schemas/Group",
-            "description": "告警聚合配置。"
+          "auto_resolve_timeout": {
+            "type": "integer",
+            "format": "int64",
+            "description": "自动恢复超时，单位秒。0 表示不自动恢复。"
           },
-          "is_external_report_enabled": {
-            "description": "是否允许外部上报人向该协作空间上报故障。",
-            "type": "boolean"
+          "auto_resolve_mode": {
+            "type": "string",
+            "enum": [
+              "trigger",
+              "update"
+            ],
+            "description": "自动恢复计时重置方式。`trigger`（默认）计时只在故障触发时启动一次，之后并入的新告警不影响计时；`update` 每当有新告警并入故障时从最新告警时间重新计时。"
           },
           "is_private": {
-            "description": "为 true 时仅管理团队可见。",
-            "type": "boolean"
+            "type": "boolean",
+            "description": "为 true 时仅管理团队可见。"
           },
-          "is_starred": {
-            "description": "当前用户是否已收藏该协作空间。仅在 `POST /channel/list` 响应中返回。",
-            "type": "boolean"
+          "disable_outlier_detection": {
+            "type": "boolean",
+            "description": "为 true 时禁用新奇故障检测。"
           },
-          "last_incident_at": {
-            "description": "最近一次故障时间（Unix 秒）。",
-            "format": "int64",
-            "type": "integer"
+          "disable_auto_close": {
+            "type": "boolean",
+            "description": "为 true 时禁用故障自动关闭。"
           },
-          "managing_team_ids": {
-            "description": "可管理该协作空间的其他团队 ID 列表。",
-            "items": {
-              "format": "int64",
-              "type": "integer"
-            },
-            "type": "array"
+          "group": {
+            "$ref": "#/components/schemas/Group",
+            "description": "告警聚合配置。从未设置时返回 `{\"method\": \"n\"}`（不聚合）。"
+          },
+          "flapping": {
+            "$ref": "#/components/schemas/Flapping",
+            "description": "抖动检测配置。从未设置时返回默认值：开启，60 分钟内 4 次变化，静音 120 分钟。"
           },
           "progress_to_incident_cnts": {
             "$ref": "#/components/schemas/IncProgressCnts",
-            "description": "近 30 天按进度统计的故障数量。"
+            "description": "近 30 天内开始且仍未关闭的故障数，按进度统计。`is_brief` 时不返回。"
           },
-          "status": {
-            "description": "协作空间状态。`enabled` 正常接收与处理事件；`disabled` 停用，新事件被直接丢弃；`deleted` 已删除，仅按 ID 查询详情时可能返回，列表接口不返回。",
+          "is_starred": {
+            "type": "boolean",
+            "description": "当前调用者是否收藏了该协作空间。仅 `POST /channel/list` 返回。"
+          },
+          "active_incident_highest_severity": {
+            "type": "string",
             "enum": [
-              "enabled",
-              "disabled",
-              "deleted"
+              "Critical",
+              "Warning",
+              "Info"
             ],
-            "type": "string"
+            "description": "协作空间内活跃（已触发或处理中）故障的最高严重程度：`Critical`、`Warning` 或 `Info`。无活跃故障时不返回。"
           },
-          "team_id": {
-            "description": "所属团队 ID。",
+          "last_incident_at": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "最近一次故障时间（Unix 秒）。"
           },
-          "team_name": {
-            "description": "所属团队名称（由团队目录解析；无法解析时为空）。",
-            "type": "string"
+          "is_external_report_enabled": {
+            "type": "boolean",
+            "description": "是否允许外部上报人向该协作空间上报故障。"
           },
-          "updated_at": {
-            "description": "最近更新时间（Unix 秒）。",
-            "format": "int64",
-            "type": "integer"
+          "external_report_token": {
+            "type": "string",
+            "description": "外部上报人向该协作空间提交故障所用的令牌。仅在开启外部上报时返回。"
+          },
+          "event_group": {
+            "$ref": "#/components/schemas/EventGroup",
+            "description": "告警事件合并配置。从未设置时为开启合并、窗口 1,440 分钟。"
           }
-        },
-        "type": "object"
+        }
       },
       "ChannelRuleIDRequest": {
+        "type": "object",
+        "required": [
+          "channel_id",
+          "rule_id"
+        ],
         "properties": {
           "channel_id": {
-            "description": "所属协作空间 ID，可通过 `POST /channel/list` 获取。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "所属协作空间 ID，可通过 `POST /channel/list` 获取。"
           },
           "rule_id": {
-            "description": "规则 ID（MongoDB ObjectID）。",
+            "type": "string",
             "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
+            "description": "策略 ID（24 位十六进制），即同类策略创建或列表接口返回的 `rule_id`。"
           }
-        },
-        "required": [
-          "channel_id",
-          "rule_id"
-        ],
-        "type": "object"
+        }
       },
       "ChannelScopedListRequest": {
+        "type": "object",
+        "required": [
+          "channel_id"
+        ],
         "properties": {
           "channel_id": {
-            "description": "要列出规则的协作空间 ID。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "要查询策略的协作空间 ID，可通过 `POST /channel/list` 获取。"
           }
-        },
-        "required": [
-          "channel_id"
-        ],
-        "type": "object"
+        }
       },
       "ChannelShort": {
+        "type": "object",
+        "required": [
+          "channel_id",
+          "channel_name"
+        ],
         "properties": {
           "channel_id": {
-            "description": "协作空间 ID。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "协作空间 ID，为请求的 `channel_ids` 之一。"
           },
           "channel_name": {
-            "description": "协作空间名称。",
-            "type": "string"
+            "type": "string",
+            "description": "协作空间名称，账户内唯一。"
           },
           "status": {
-            "description": "协作空间状态：`enabled` 正常处理事件；`disabled` 丢弃新事件；`deleted` 已删除。",
+            "type": "string",
             "enum": [
               "enabled",
               "disabled",
               "deleted"
             ],
-            "type": "string"
+            "description": "协作空间状态：\n- `enabled`：正常处理新进入的告警事件。\n- `disabled`：新进入的告警事件被丢弃。\n- `deleted`：已删除。"
           }
-        },
-        "required": [
-          "channel_id",
-          "channel_name"
-        ],
-        "type": "object"
+        }
       },
       "CommentIncidentRequest": {
         "description": "为故障添加评论的参数。",
@@ -5057,786 +5451,359 @@
         "type": "object"
       },
       "ContextResolvedItem": {
-        "description": "该会话三层知识解析结果的快照。",
+        "type": "object",
+        "description": "会话上下文解析到的知识版本。在 `POST /safari/session/get` 中只填充 `versions`（`resolved_at_ms` 为 0）；智能体尚未解析过知识时不返回该对象。",
         "properties": {
           "account_pack_id": {
-            "description": "解析出的账户级知识 ID。",
-            "type": "string"
+            "type": "string",
+            "description": "解析出的账户级知识 ID。"
+          },
+          "team_pack_id": {
+            "type": "string",
+            "description": "解析出的团队级知识 ID。"
           },
           "incident_id": {
-            "description": "作战室来源时绑定的故障 ID。",
-            "type": "string"
+            "type": "string",
+            "description": "作战室来源时绑定的故障 ID。"
           },
           "resolved_at_ms": {
-            "description": "知识解析时间，Unix 毫秒时间戳。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
-          },
-          "team_pack_id": {
-            "description": "解析出的团队级知识 ID。",
-            "type": "string"
+            "description": "知识解析时间，Unix 毫秒时间戳。"
           },
           "versions": {
+            "type": "object",
             "additionalProperties": {
               "type": "integer"
             },
-            "description": "各份知识的解析版本映射。",
-            "type": "object"
+            "description": "知识 ID 到智能体最近一次加载的版本号的映射。"
           }
         },
         "required": [
           "resolved_at_ms"
-        ],
-        "type": "object"
+        ]
       },
       "ConvertWorkItemRequest": {
+        "type": "object",
         "description": "将行动项原地转化为复盘后续行动的参数。",
+        "required": [
+          "work_item_id",
+          "version",
+          "idempotency_key"
+        ],
         "properties": {
-          "idempotency_key": {
-            "description": "客户端生成的幂等键（最长 128 字符；仅限字母、数字、`_`、`-`、`.`、`:`）。",
+          "work_item_id": {
+            "type": "string",
             "maxLength": 128,
-            "pattern": "^[A-Za-z0-9_\\-.:]+$",
-            "type": "string"
+            "description": "跟进事项 ID（不透明字符串，最长 128 字符）。"
+          },
+          "version": {
+            "type": "integer",
+            "format": "int64",
+            "description": "事项当前的 `version`（≥ 1），用于乐观锁。"
           },
           "target_status": {
-            "description": "可选，设置在转化后后续行动上的状态，取 `open`、`in_progress`、`done`、`cancelled` 之一。",
+            "type": [
+              "string",
+              "null"
+            ],
             "enum": [
               "open",
               "in_progress",
               "done",
-              "cancelled"
+              "cancelled",
+              null
             ],
             "maxLength": 64,
-            "type": [
-              "string",
-              "null"
-            ]
+            "description": "可选，转换后的后续行动要设置的状态；省略或传 `null` 保持当前状态。取值：`open`（未开始）、`in_progress`（处理中）、`done`（已完成）、`cancelled`（已取消）。"
           },
-          "version": {
-            "description": "事项当前版本号，用于乐观锁。必须与存储的版本一致。",
-            "format": "int64",
-            "type": "integer"
-          },
-          "work_item_id": {
-            "description": "跟进事项 ID（不透明字符串，最长 128 字符）。",
+          "idempotency_key": {
+            "type": "string",
             "maxLength": 128,
-            "type": "string"
+            "pattern": "^[A-Za-z0-9_\\-.:]+$",
+            "description": "客户端生成的幂等键（最长 128 字符；仅限字母、数字、`_`、`-`、`.`、`:`）。"
           }
-        },
-        "required": [
-          "work_item_id",
-          "version",
-          "idempotency_key"
-        ],
-        "type": "object"
+        }
       },
       "CreateChannelRequest": {
+        "type": "object",
         "description": "创建协作空间所需的参数。",
+        "required": [
+          "team_id",
+          "channel_name"
+        ],
         "properties": {
-          "auto_resolve_mode": {
-            "description": "自动恢复计时方式：`trigger` 从故障触发时开始计时，`update` 每次告警更新都重新计时。",
-            "enum": [
-              "trigger",
-              "update"
-            ],
-            "type": "string"
-          },
-          "auto_resolve_timeout": {
-            "description": "自动恢复超时,单位秒。0 表示不自动恢复,最长 30 天。",
+          "team_id": {
+            "type": "integer",
             "format": "int64",
-            "maximum": 2592000,
-            "minimum": 0,
-            "type": "integer"
+            "description": "所属团队 ID，可通过 `POST /team/list` 获取。必填且必须存在。"
+          },
+          "managing_team_ids": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "int64"
+            },
+            "maxItems": 3,
+            "description": "可管理该协作空间的其他团队 ID,最多 3 个。"
           },
           "channel_name": {
-            "description": "协作空间名称,1 到 59 个字符。",
-            "maxLength": 59,
+            "type": "string",
             "minLength": 1,
-            "type": "string"
+            "maxLength": 59,
+            "description": "协作空间名称，1–59 个字符，账户内唯一。"
           },
           "description": {
-            "description": "描述信息,最多 500 个字符。",
+            "type": "string",
             "maxLength": 500,
-            "type": "string"
-          },
-          "disable_auto_close": {
-            "description": "禁用故障自动关闭。",
-            "type": "boolean"
-          },
-          "disable_outlier_detection": {
-            "description": "禁用新奇故障检测。",
-            "type": "boolean"
+            "description": "描述信息,最多 500 个字符。"
           },
           "escalate_rule": {
-            "description": "协作空间的默认分派策略,不需要时可省略。",
-            "properties": {
-              "aggr_window": {
-                "description": "延迟窗口,单位秒,0 表示不延迟。",
-                "maximum": 3600,
-                "minimum": 0,
-                "type": "integer"
-              },
-              "target": {
-                "description": "通知目标。`person_ids`、`team_ids`、`schedule_to_role_ids`、`emails` 至少设置一项,且 `by` 与 `webhooks` 至少设置一项。",
-                "properties": {
-                  "by": {
-                    "description": "按告警等级配置的个人通知渠道。未提供 `webhooks` 时必填。",
-                    "properties": {
-                      "critical": {
-                        "description": "Critical 级别使用的通知渠道。个人通知渠道：`sms`、`voice`、`email`、`push`；IM 群聊渠道：`feishu_app:<chat_id>`、`dingtalk_app:<chat_id>`、`wecom_app:<chat_id>`、`slack_app:<chat_id>`、`teams_app:<chat_id>`。",
-                        "items": {
-                          "type": "string"
-                        },
-                        "type": "array"
-                      },
-                      "follow_preference": {
-                        "description": "为 true 时跟随处理人员的个人偏好,忽略下方列表。",
-                        "type": "boolean"
-                      },
-                      "info": {
-                        "description": "Info 级别使用的通知渠道。取值同 `critical`。",
-                        "items": {
-                          "type": "string"
-                        },
-                        "type": "array"
-                      },
-                      "warning": {
-                        "description": "Warning 级别使用的通知渠道。取值同 `critical`。",
-                        "items": {
-                          "type": "string"
-                        },
-                        "type": "array"
-                      }
-                    },
-                    "type": "object"
-                  },
-                  "emails": {
-                    "description": "邮箱地址列表(推送场景)。",
-                    "items": {
-                      "format": "email",
-                      "type": "string"
-                    },
-                    "type": "array"
-                  },
-                  "person_ids": {
-                    "description": "直接通知的成员 ID 列表，可通过 `POST /member/list` 获取。",
-                    "items": {
-                      "format": "int64",
-                      "type": "integer"
-                    },
-                    "type": "array"
-                  },
-                  "schedule_to_role_ids": {
-                    "additionalProperties": {
-                      "items": {
-                        "format": "int64",
-                        "type": "integer"
-                      },
-                      "type": "array"
-                    },
-                    "description": "值班表 ID 到角色 ID 列表的映射,用于按值班角色通知。",
-                    "type": "object"
-                  },
-                  "team_ids": {
-                    "description": "通知的团队 ID 列表，可通过 `POST /team/list` 获取。",
-                    "items": {
-                      "format": "int64",
-                      "type": "integer"
-                    },
-                    "type": "array"
-                  },
-                  "webhooks": {
-                    "description": "群聊/Webhook 通知目标。未提供 `by` 时必填。",
-                    "items": {
-                      "properties": {
-                        "settings": {
-                          "additionalProperties": true,
-                          "description": "类型相关的配置参数(群聊 ID、URL 等)。",
-                          "type": "object"
-                        },
-                        "type": {
-                          "description": "Webhook 类型，可选值：`feishu`、`feishu_app`、`dingtalk`、`dingtalk_app`、`wecom`、`slack`、`slack_app`、`teams_app`、`telegram`、`zoom`。",
-                          "type": "string"
-                        }
-                      },
-                      "required": [
-                        "type",
-                        "settings"
-                      ],
-                      "type": "object"
-                    },
-                    "type": "array"
-                  }
-                },
-                "type": "object"
-              },
-              "template_id": {
-                "description": "通知模板 ID(MongoDB ObjectID)。",
-                "pattern": "^[0-9a-fA-F]{24}$",
-                "type": "string"
-              }
-            },
+            "type": "object",
+            "description": "创建一条名为 `Default` 的已启用分派策略，只有一个环节，对 `target` 通知一次。不传则创建的协作空间没有分派策略。",
             "required": [
               "template_id",
               "target"
             ],
-            "type": "object"
-          },
-          "event_group": {
-            "$ref": "#/components/schemas/EventGroup",
-            "description": "告警事件合并配置。不传时使用默认配置（启用合并，窗口 1440 分钟）。"
-          },
-          "flapping": {
-            "description": "抖动检测配置。",
             "properties": {
-              "in_mins": {
-                "description": "观察窗口,单位分钟。",
-                "maximum": 1440,
-                "minimum": 1,
-                "type": "integer"
-              },
-              "is_disabled": {
-                "description": "禁用抖动检测。",
-                "type": "boolean"
+              "aggr_window": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 3600,
+                "description": "新分派故障首次通知前的延迟（秒），0–3600；`0` 表示立即通知。"
               },
-              "max_changes": {
-                "description": "`in_mins` 内允许的最大状态变更次数。",
-                "maximum": 100,
-                "minimum": 2,
-                "type": "integer"
+              "template_id": {
+                "type": "string",
+                "pattern": "^[0-9a-fA-F]{24}$",
+                "description": "通知模板 ID（24 位十六进制），可通过 `POST /template/list` 获取，必须存在。"
               },
-              "mute_mins": {
-                "description": "检测到抖动后的静音时长,单位分钟。",
-                "maximum": 1440,
-                "minimum": 0,
-                "type": "integer"
+              "target": {
+                "$ref": "#/components/schemas/EscalateTarget",
+                "description": "通知对象及通知渠道。"
               }
-            },
-            "type": "object"
+            }
           },
           "group": {
-            "description": "告警聚合配置。",
-            "properties": {
-              "all_equals_required": {
-                "description": "为 true 时要求所有键同时存在才能参与聚合。",
-                "type": "boolean"
-              },
-              "cases": {
-                "description": "按过滤条件的聚合策略覆盖。",
-                "items": {
-                  "description": "条件化聚合覆盖：命中 `if` 的已存告警按 `equals` 键聚合，而不使用顶层聚合键。",
-                  "properties": {
-                    "equals": {
-                      "description": "命中告警使用的聚合键。可选值：`title`、`description`、`severity` 或任意 `labels.<name>`。",
-                      "items": {
-                        "type": "string"
-                      },
-                      "maxItems": 5,
-                      "minItems": 1,
-                      "type": "array"
-                    },
-                    "if": {
-                      "description": "针对已存告警字段的匹配条件，条件之间为 AND 关系。",
-                      "items": {
-                        "$ref": "#/components/schemas/FilterCondition"
-                      },
-                      "type": "array"
-                    }
-                  },
-                  "required": [
-                    "if",
-                    "equals"
-                  ],
-                  "type": "object"
-                },
-                "maxItems": 100,
-                "type": "array"
-              },
-              "equals": {
-                "description": "用于聚合判定的 label 键分组。",
-                "items": {
-                  "items": {
-                    "type": "string"
-                  },
-                  "type": "array"
-                },
-                "maxItems": 5,
-                "type": "array"
-              },
-              "i_keys": {
-                "description": "用于智能聚合向量化的 label 键。",
-                "items": {
-                  "type": "string"
-                },
-                "maxItems": 10,
-                "type": "array"
-              },
-              "i_score_threshold": {
-                "description": "智能聚合相似度阈值。",
-                "format": "float",
-                "maximum": 1,
-                "minimum": 0.5,
-                "type": "number"
-              },
-              "method": {
-                "description": "聚合方式:`i` 智能、`p` 规则、`n` 不聚合。",
-                "enum": [
-                  "i",
-                  "p",
-                  "n"
-                ],
-                "type": "string"
-              },
-              "storm_threshold": {
-                "description": "告警风暴阈值。",
-                "maximum": 10000,
-                "minimum": 0,
-                "type": "integer"
-              },
-              "storm_thresholds": {
-                "description": "多级告警风暴阈值。",
-                "items": {
-                  "type": "integer"
-                },
-                "maxItems": 5,
-                "type": "array"
-              },
-              "time_window": {
-                "description": "聚合时间窗口，单位分钟。默认最大值为 1440 分钟（24 小时）；开启扩展功能的账号最大可设置 43200 分钟（30 天）。",
-                "minimum": 0,
-                "type": "integer"
-              },
-              "window_type": {
-                "description": "窗口类型,默认 `tumbling`。`tumbling` 为固定窗口，自故障创建时间起算，窗口到期后新告警会开启新故障；`sliding` 为滑动窗口，自故障最近一次告警时间起算，每有新告警并入即向后顺延。",
-                "enum": [
-                  "tumbling",
-                  "sliding"
-                ],
-                "type": "string"
-              }
-            },
-            "required": [
-              "method"
-            ],
-            "type": "object"
+            "$ref": "#/components/schemas/Group",
+            "description": "告警聚合配置。不传时不聚合（`method` 为 `n`）。"
           },
-          "is_external_report_enabled": {
-            "description": "允许外部上报人向该协作空间上报故障。",
-            "type": "boolean"
+          "flapping": {
+            "$ref": "#/components/schemas/Flapping",
+            "description": "抖动检测配置。不传时使用默认值。"
           },
-          "is_private": {
-            "description": "为 true 时仅管理团队可见。",
-            "type": "boolean"
+          "auto_resolve_timeout": {
+            "type": "integer",
+            "format": "int64",
+            "minimum": 0,
+            "maximum": 2592000,
+            "description": "自动恢复超时,单位秒。0 表示不自动恢复,最长 30 天。"
           },
-          "managing_team_ids": {
-            "description": "可管理该协作空间的其他团队 ID,最多 3 个。",
-            "items": {
-              "format": "int64",
-              "type": "integer"
-            },
-            "maxItems": 3,
-            "type": "array"
+          "auto_resolve_mode": {
+            "type": "string",
+            "enum": [
+              "trigger",
+              "update"
+            ],
+            "description": "自动恢复的计时方式。`trigger`（默认）在故障触发时开始计时，只计一次；`update` 每当有新告警并入故障时重新计时。"
           },
           "plugin_ids": {
-            "description": "订阅该协作空间的集成 ID 列表。",
+            "type": "array",
             "items": {
-              "format": "int64",
-              "type": "integer"
+              "type": "integer",
+              "format": "int64"
             },
-            "type": "array"
+            "description": "集成类型 ID（即 `POST /integration/list` 返回的集成上的 `plugin_id`）。每个 ID 会创建一个该类型的协作空间专属集成，名称为该类型名称。ID 不存在时返回 `InvalidParameter`。"
           },
-          "team_id": {
-            "description": "所属团队 ID，可通过 `POST /team/list` 获取。",
-            "format": "int64",
-            "type": "integer"
+          "is_private": {
+            "type": "boolean",
+            "description": "为 true 时仅管理团队可见。"
+          },
+          "disable_outlier_detection": {
+            "type": "boolean",
+            "description": "禁用新奇故障检测。"
+          },
+          "disable_auto_close": {
+            "type": "boolean",
+            "description": "禁用故障自动关闭。"
+          },
+          "is_external_report_enabled": {
+            "type": "boolean",
+            "description": "为 true 时允许外部上报人向该协作空间提交故障，响应中返回生成的 `external_report_token`。"
+          },
+          "event_group": {
+            "$ref": "#/components/schemas/EventGroup",
+            "description": "告警事件合并配置。不传时使用默认配置（启用合并，窗口 1440 分钟）。"
           }
-        },
-        "required": [
-          "team_id",
-          "channel_name"
-        ],
-        "type": "object"
+        }
       },
       "CreateDropRuleRequest": {
+        "type": "object",
         "description": "创建排除规则所需的参数。",
+        "required": [
+          "channel_id",
+          "rule_name"
+        ],
         "properties": {
           "channel_id": {
-            "description": "所属协作空间 ID，可通过 `POST /channel/list` 获取。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "所属协作空间 ID，可通过 `POST /channel/list` 获取。"
+          },
+          "rule_name": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 39,
+            "description": "规则名称,1 到 39 个字符。"
           },
           "description": {
-            "description": "规则描述,最多 500 个字符。",
+            "type": "string",
             "maxLength": 500,
-            "type": "string"
+            "description": "规则描述,最多 500 个字符。"
           },
           "filters": {
-            "description": "告警事件匹配条件（OR-of-AND 结构）；命中的事件被完全丢弃——不产生告警、故障或通知。不传或为空时，规则不匹配任何事件。",
-            "items": {
-              "items": {
-                "properties": {
-                  "key": {
-                    "description": "字段键(如 `alert_severity`、`labels.service`)。",
-                    "type": "string"
-                  },
-                  "oper": {
-                    "description": "过滤运算符。",
-                    "enum": [
-                      "IN",
-                      "NOTIN"
-                    ],
-                    "type": "string"
-                  },
-                  "vals": {
-                    "description": "匹配值列表。",
-                    "items": {
-                      "type": "string"
-                    },
-                    "type": "array"
-                  }
-                },
-                "required": [
-                  "key",
-                  "oper",
-                  "vals"
-                ],
-                "type": "object"
-              },
-              "type": "array"
-            },
-            "type": "array"
-          },
-          "rule_name": {
-            "description": "规则名称,1 到 39 个字符。",
-            "maxLength": 39,
-            "minLength": 1,
-            "type": "string"
+            "$ref": "#/components/schemas/FilterGroup",
+            "description": "告警事件匹配条件（AND 组之间为 OR）。命中的事件被直接丢弃，不产生告警、故障或通知。可用字段：`title`、`description`、`severity`（别名 `alert_severity`、`event_severity`）、`status`、`alert_key`、`title_rule`、`integration_id`（别名 `data_source_id`），或任意 `labels.<name>`。不传或为空时规则不匹配任何事件。"
           }
-        },
-        "required": [
-          "channel_id",
-          "rule_name"
-        ],
-        "type": "object"
+        }
       },
       "CreateEscalationRuleRequest": {
+        "type": "object",
         "description": "创建分派策略所需的参数。",
+        "required": [
+          "channel_id",
+          "template_id",
+          "rule_name",
+          "layers"
+        ],
         "properties": {
-          "aggr_window": {
-            "description": "延迟窗口,单位秒,0 表示不延迟。",
-            "maximum": 3600,
-            "minimum": 0,
-            "type": "integer"
-          },
           "channel_id": {
-            "description": "所属协作空间 ID，可通过 `POST /channel/list` 获取。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
-          },
-          "description": {
-            "description": "策略描述,最多 500 个字符。",
-            "maxLength": 500,
-            "type": "string"
-          },
-          "filters": {
-            "description": "故障级匹配条件（OR-of-AND 结构）：策略匹配的是告警聚合而成的故障，而不是告警本身。不传或为空时对空间内所有故障生效。",
-            "items": {
-              "items": {
-                "properties": {
-                  "key": {
-                    "description": "字段键(如 `alert_severity`、`labels.service`)。",
-                    "type": "string"
-                  },
-                  "oper": {
-                    "description": "过滤运算符。",
-                    "enum": [
-                      "IN",
-                      "NOTIN"
-                    ],
-                    "type": "string"
-                  },
-                  "vals": {
-                    "description": "匹配值列表。",
-                    "items": {
-                      "type": "string"
-                    },
-                    "type": "array"
-                  }
-                },
-                "required": [
-                  "key",
-                  "oper",
-                  "vals"
-                ],
-                "type": "object"
-              },
-              "type": "array"
-            },
-            "type": "array"
-          },
-          "layers": {
-            "description": "分派环节列表,至少包含一个环节。",
-            "items": {
-              "properties": {
-                "escalate_window": {
-                  "description": "升级到下一环节前的等待时长,单位分钟。",
-                  "maximum": 720,
-                  "minimum": 0,
-                  "type": "integer"
-                },
-                "force_escalate": {
-                  "description": "为 true 时,即便未认领也强制升级。",
-                  "type": "boolean"
-                },
-                "max_times": {
-                  "description": "当前环节内的最大重复通知次数。",
-                  "maximum": 6,
-                  "minimum": 0,
-                  "type": "integer"
-                },
-                "notify_step": {
-                  "description": "重复通知间隔,单位分钟。",
-                  "format": "float",
-                  "maximum": 120,
-                  "minimum": 0.5,
-                  "type": "number"
-                },
-                "target": {
-                  "description": "通知目标。`person_ids`、`team_ids`、`schedule_to_role_ids`、`emails` 至少设置一项,且 `by` 与 `webhooks` 至少设置一项。",
-                  "properties": {
-                    "by": {
-                      "description": "按告警等级配置的个人通知渠道。未提供 `webhooks` 时必填。",
-                      "properties": {
-                        "critical": {
-                          "description": "Critical 级别使用的通知渠道。个人通知渠道：`sms`、`voice`、`email`、`push`；IM 群聊渠道：`feishu_app:<chat_id>`、`dingtalk_app:<chat_id>`、`wecom_app:<chat_id>`、`slack_app:<chat_id>`、`teams_app:<chat_id>`。",
-                          "items": {
-                            "type": "string"
-                          },
-                          "type": "array"
-                        },
-                        "follow_preference": {
-                          "description": "为 true 时跟随处理人员的个人偏好,忽略下方列表。",
-                          "type": "boolean"
-                        },
-                        "info": {
-                          "description": "Info 级别使用的通知渠道。取值同 `critical`。",
-                          "items": {
-                            "type": "string"
-                          },
-                          "type": "array"
-                        },
-                        "warning": {
-                          "description": "Warning 级别使用的通知渠道。取值同 `critical`。",
-                          "items": {
-                            "type": "string"
-                          },
-                          "type": "array"
-                        }
-                      },
-                      "type": "object"
-                    },
-                    "emails": {
-                      "description": "邮箱地址列表(推送场景)。",
-                      "items": {
-                        "format": "email",
-                        "type": "string"
-                      },
-                      "type": "array"
-                    },
-                    "person_ids": {
-                      "description": "直接通知的成员 ID 列表，可通过 `POST /member/list` 获取。",
-                      "items": {
-                        "format": "int64",
-                        "type": "integer"
-                      },
-                      "type": "array"
-                    },
-                    "schedule_to_role_ids": {
-                      "additionalProperties": {
-                        "items": {
-                          "format": "int64",
-                          "type": "integer"
-                        },
-                        "type": "array"
-                      },
-                      "description": "值班表 ID 到角色 ID 列表的映射,用于按值班角色通知。",
-                      "type": "object"
-                    },
-                    "team_ids": {
-                      "description": "通知的团队 ID 列表，可通过 `POST /team/list` 获取。",
-                      "items": {
-                        "format": "int64",
-                        "type": "integer"
-                      },
-                      "type": "array"
-                    },
-                    "webhooks": {
-                      "description": "群聊/Webhook 通知目标。未提供 `by` 时必填。",
-                      "items": {
-                        "properties": {
-                          "settings": {
-                            "additionalProperties": true,
-                            "description": "类型相关的配置参数(群聊 ID、URL 等)。",
-                            "type": "object"
-                          },
-                          "type": {
-                            "description": "Webhook 类型，可选值：`feishu`、`feishu_app`、`dingtalk`、`dingtalk_app`、`wecom`、`slack`、`slack_app`、`teams_app`、`telegram`、`zoom`。",
-                            "type": "string"
-                          }
-                        },
-                        "required": [
-                          "type",
-                          "settings"
-                        ],
-                        "type": "object"
-                      },
-                      "type": "array"
-                    }
-                  },
-                  "type": "object"
-                }
-              },
-              "required": [
-                "target"
-              ],
-              "type": "object"
-            },
-            "type": "array"
+            "description": "所属协作空间 ID，可通过 `POST /channel/list` 获取。"
           },
           "priority": {
-            "description": "匹配优先级,数值越小越优先。",
-            "maximum": 200,
-            "minimum": 0,
             "type": [
               "integer",
               "null"
-            ]
+            ],
+            "minimum": 0,
+            "maximum": 200,
+            "description": "匹配顺序，取值 `0` 到 `200`，数值越小越先匹配。不传时排在现有策略之后（当前最大优先级 + 1）。"
           },
-          "rule_name": {
-            "description": "策略名称,1 到 39 个字符。",
-            "maxLength": 39,
-            "minLength": 1,
-            "type": "string"
+          "aggr_window": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 3600,
+            "description": "新分派故障首次通知前的延迟（秒），0–3600；`0` 表示立即通知。"
           },
           "template_id": {
-            "description": "通知模板 ID(MongoDB ObjectID)。",
+            "type": "string",
             "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
+            "description": "通知模板 ID（24 位十六进制），可通过 `POST /template/list` 获取，必须存在。"
+          },
+          "rule_name": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 39,
+            "description": "策略名称,1 到 39 个字符。"
+          },
+          "description": {
+            "type": "string",
+            "maxLength": 500,
+            "description": "策略描述,最多 500 个字符。"
+          },
+          "layers": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/EscalateLayer"
+            },
+            "description": "按顺序排列的通知环节，故障从第一个环节开始。"
           },
           "time_filters": {
-            "description": "可选的周期性生效时间窗口。",
+            "type": "array",
             "items": {
-              "description": "周期性时间窗口。`start`/`end` 使用 24 小时制 `HH:MM` 格式;`repeat` 使用星期索引(0=周日 … 6=周六)。",
-              "properties": {
-                "cal_id": {
-                  "description": "可选日历 ID,限制窗口仅在日历匹配的日期生效。",
-                  "type": "string"
-                },
-                "end": {
-                  "description": "窗口结束时间,`HH:MM`。",
-                  "type": "string"
-                },
-                "is_off": {
-                  "description": "为 true 时匹配日历中的休息日。",
-                  "type": "boolean"
-                },
-                "repeat": {
-                  "description": "生效的星期列表,留空表示每天。",
-                  "items": {
-                    "type": "integer"
-                  },
-                  "type": "array"
-                },
-                "start": {
-                  "description": "窗口起始时间,`HH:MM`。",
-                  "type": "string"
-                }
-              },
-              "type": "object"
+              "$ref": "#/components/schemas/TimeFilter"
             },
-            "type": "array"
+            "description": "策略可参与匹配的周期时间窗口；不传或为空表示任何时间。"
+          },
+          "filters": {
+            "$ref": "#/components/schemas/FilterGroup",
+            "description": "故障匹配条件（AND 组之间为 OR），匹配的是告警所属的故障而不是告警本身。可用字段：`title`、`description`、`severity`（别名 `incident_severity`、`alert_severity`）、`status`（别名 `incident_status`、`alert_status`）、`dedup_key`、`integration_id`（别名 `data_source_id`），或任意 `labels.<name>`。不传或为空时匹配协作空间内的所有故障。"
           }
-        },
-        "required": [
-          "channel_id",
-          "template_id",
-          "rule_name",
-          "layers"
-        ],
-        "type": "object"
+        }
       },
       "CreateFieldRequest": {
+        "type": "object",
+        "required": [
+          "field_name",
+          "display_name",
+          "field_type",
+          "value_type"
+        ],
         "properties": {
-          "default_value": {
-            "description": "可选默认值，类型须与 `field_type` 匹配：`checkbox` 为 `bool`；`single_select` 为 `options` 中之一；`multi_select` 为 `options` 的子集；`text` 为不超过 3000 字符的字符串。",
-            "oneOf": [
-              {
-                "type": "boolean"
-              },
-              {
-                "type": "string"
-              },
-              {
-                "items": {
-                  "type": "string"
-                },
-                "type": "array"
-              },
-              {
-                "type": "null"
-              }
-            ]
-          },
-          "description": {
-            "description": "可选描述。",
-            "maxLength": 499,
-            "type": "string"
+          "field_name": {
+            "type": "string",
+            "pattern": "^[a-zA-Z_][a-zA-Z0-9_]{0,39}$",
+            "maxLength": 39,
+            "description": "字段标识：1–39 个 `[a-zA-Z0-9_]` 字符，以字母或下划线开头，创建后不可修改。"
           },
           "display_name": {
-            "description": "展示名，账号内须唯一。",
+            "type": "string",
             "maxLength": 39,
-            "type": "string"
+            "description": "展示名，账号内须唯一。"
           },
-          "field_name": {
-            "description": "机器名。必须以字母或下划线开头，长度 1–40，由 `[a-zA-Z0-9_]` 组成；创建后不可更改。",
-            "maxLength": 39,
-            "pattern": "^[a-zA-Z_][a-zA-Z0-9_]{0,39}$",
-            "type": "string"
+          "description": {
+            "type": "string",
+            "maxLength": 499,
+            "description": "可选描述。"
           },
           "field_type": {
-            "description": "字段类型，创建后不可更改。\n| 值 | 含义 |\n|---|---|\n| `text` | 自由文本；`value_type` 须为 `string`，不支持 `options`。 |\n| `single_select` | 从 `options` 中单选；`value_type` 须为 `string`。 |\n| `multi_select` | 从 `options` 中多选；`value_type` 须为 `string`。 |\n| `checkbox` | 布尔复选框；`value_type` 须为 `bool`，不支持 `options`。 |",
+            "type": "string",
             "enum": [
               "checkbox",
               "multi_select",
               "single_select",
               "text"
             ],
-            "type": "string"
-          },
-          "options": {
-            "description": "`single_select`/`multi_select` 必填且非空，元素唯一、每个 1–200 字符；`checkbox`/`text` 必须省略或为空。",
-            "items": {
-              "type": "string"
-            },
-            "type": "array"
+            "description": "字段类型，创建后不可更改。\n| 值 | 含义 |\n|---|---|\n| `text` | 自由文本；`value_type` 须为 `string`，不支持 `options`。 |\n| `single_select` | 从 `options` 中单选；`value_type` 须为 `string`。 |\n| `multi_select` | 从 `options` 中多选；`value_type` 须为 `string`。 |\n| `checkbox` | 布尔复选框；`value_type` 须为 `bool`，不支持 `options`。 |"
           },
           "value_type": {
-            "description": "取值类型。`checkbox` 须为 `bool`；其他类型须为 `string`。创建后不可更改。`float` 为保留值，当前所有 `field_type` 均不接受。",
+            "type": "string",
             "enum": [
               "string",
               "bool",
               "float"
             ],
-            "type": "string"
+            "description": "取值类型。`checkbox` 须为 `bool`；其他类型须为 `string`。创建后不可更改。`float` 为保留值，当前所有 `field_type` 均不接受。"
+          },
+          "options": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "`single_select`/`multi_select` 必填且非空，元素唯一、每个 1–200 字符；`checkbox`/`text` 必须省略或为空。"
+          },
+          "default_value": {
+            "description": "可选默认值，类型须与 `field_type` 匹配：`checkbox` 为 `bool`；`single_select` 为 `options` 中之一；`multi_select` 为 `options` 的子集；`text` 为不超过 3000 字符的字符串。",
+            "oneOf": [
+              {
+                "type": "boolean"
+              },
+              {
+                "type": "string"
+              },
+              {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              {
+                "type": "null"
+              }
+            ]
           }
-        },
-        "required": [
-          "field_name",
-          "display_name",
-          "field_type",
-          "value_type"
-        ],
-        "type": "object"
+        }
       },
       "CreateFieldResponse": {
         "properties": {
@@ -5857,24 +5824,24 @@
         "type": "object"
       },
       "CreateIncidentCommentTypeRequest": {
+        "type": "object",
         "description": "创建评论类型的参数。每个账户最多 10 个评论类型。",
-        "properties": {
-          "color": {
-            "description": "标签颜色，#RRGGBB 格式十六进制值，统一转为大写。",
-            "pattern": "^#[0-9A-Fa-f]{6}$",
-            "type": "string"
-          },
-          "name": {
-            "description": "展示名称。存储前去除首尾空白；账户内唯一（不区分大小写）。最多 40 个字符。",
-            "maxLength": 40,
-            "type": "string"
-          }
-        },
         "required": [
           "name",
           "color"
         ],
-        "type": "object"
+        "properties": {
+          "name": {
+            "type": "string",
+            "maxLength": 40,
+            "description": "展示名称。存储前去除首尾空白；账户内唯一（不区分大小写）。最多 40 个字符。不得包含控制字符或文字方向控制字符。"
+          },
+          "color": {
+            "type": "string",
+            "pattern": "^#[0-9A-Fa-f]{6}$",
+            "description": "标签颜色，#RRGGBB 格式十六进制值，统一转为大写。"
+          }
+        }
       },
       "CreateIncidentCommentTypeResponse": {
         "description": "创建评论类型的结果。",
@@ -5895,422 +5862,267 @@
         "type": "object"
       },
       "CreateIncidentRequest": {
+        "type": "object",
         "description": "手动创建故障所需的参数。",
+        "required": [
+          "incident_severity"
+        ],
         "properties": {
+          "incident_severity": {
+            "type": "string",
+            "enum": [
+              "Info",
+              "Warning",
+              "Critical"
+            ],
+            "description": "故障严重程度：`Info` 提示、`Warning` 警告、`Critical` 严重。"
+          },
+          "title": {
+            "type": "string",
+            "maxLength": 512,
+            "description": "故障标题，最多 512 个字符。账户配置了创建表单时必填且不能为空。"
+          },
+          "description": {
+            "type": "string",
+            "maxLength": 1024,
+            "description": "故障描述,最多 1024 个字符。"
+          },
+          "channel_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "故障所属的协作空间，须在账户中存在。除非账户配置了创建表单，否则可不填；不填即为独立故障。"
+          },
           "assigned_to": {
-            "description": "故障指派目标。可整体省略：省略或为空时按协作空间的默认分派处理；账户的创建表单生效时必填。`person_ids`、`escalate_rule_id`、`emails` 可同时设置，处理人员取并集。",
+            "type": "object",
+            "description": "分派对象。省略或为空时由协作空间的分派策略决定（独立故障不会有处理人员）；账户配置了创建表单时必填。`person_ids`、`escalate_rule_id` 和 `emails` 可同时设置，处理人员取并集。分派在创建之后执行，分派失败不会撤销故障。",
             "properties": {
-              "emails": {
-                "description": "按邮箱指派的接收人列表（1–100 个）：解析为账户成员后并入 `person_ids`，未匹配到成员的邮箱将被忽略。",
+              "person_ids": {
+                "type": "array",
                 "items": {
-                  "format": "email",
-                  "type": "string"
+                  "type": "integer",
+                  "format": "int64"
                 },
-                "maxItems": 100,
                 "minItems": 1,
-                "type": "array"
+                "maxItems": 100,
+                "description": "直接指派的成员 ID 列表（1–100 个），可与 `escalate_rule_id` 同时使用。"
               },
               "escalate_rule_id": {
-                "description": "按分派策略指派时使用的策略 ID(MongoDB ObjectID)，指派该策略 `layer_idx` 环节的人员。",
+                "type": "string",
                 "pattern": "^[0-9a-fA-F]{24}$",
-                "type": "string"
+                "description": "按分派策略指派时使用的策略 ID(MongoDB ObjectID)，指派该策略 `layer_idx` 环节的人员。"
               },
               "layer_idx": {
-                "description": "分派策略的起始环节索引，从 0 开始（默认 0，即第一个环节）；超出环节数会报错。仅在设置 `escalate_rule_id` 时有效。",
-                "type": "integer"
+                "type": "integer",
+                "description": "要分派的分派策略环节，从 0 开始（默认 0，即第一个环节）。仅与 `escalate_rule_id` 一起生效；越界时请求不会失败，但故障不会有处理人员。"
+              },
+              "type": {
+                "type": "string",
+                "enum": [
+                  "assign",
+                  "reassign",
+                  "escalate",
+                  "reopen"
+                ],
+                "description": "分派类型。通常无需传：服务端会设为 `assign`，因为手动创建总是首次分派。若传入则按原值保存。\n- `assign`：故障的首次分派。\n- `reassign`：替换之前分派的重新分派。\n- `escalate`：升级到下一环节触发的分派。\n- `reopen`：故障重新打开后从第一个环节重新分派。"
+              },
+              "emails": {
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "format": "email"
+                },
+                "minItems": 1,
+                "maxItems": 100,
+                "description": "按邮箱指派的接收人列表（1–100 个）：解析为账户成员后并入 `person_ids`，未匹配到成员的邮箱将被忽略。"
               },
               "notify": {
+                "type": "object",
                 "description": "为本次指派覆盖的通知渠道。",
                 "properties": {
                   "follow_preference": {
-                    "description": "为 false 时使用 `personal_channels`；为 true 或省略时跟随处理人员的个人偏好。",
                     "type": [
                       "boolean",
                       "null"
-                    ]
+                    ],
+                    "description": "为 false 时使用 `personal_channels`；为 true 或省略时跟随处理人员的个人偏好。"
                   },
                   "personal_channels": {
-                    "description": "使用的通知渠道(如 `voice`、`sms`、`email`)。",
+                    "type": "array",
                     "items": {
                       "type": "string"
                     },
-                    "type": "array"
+                    "description": "`follow_preference` 为 false 时使用的通知渠道：`sms`、`voice`、`email`、`push`，或以 `feishu_app:`、`dingtalk_app:`、`wecom_app:`、`slack_app:`、`teams_app:` 为前缀的 IM 应用渠道。"
                   },
                   "template_id": {
-                    "description": "通知模板 ID(MongoDB ObjectID)。",
+                    "type": "string",
                     "pattern": "^[0-9a-fA-F]{24}$",
-                    "type": "string"
+                    "description": "通知模板 ID(MongoDB ObjectID)。"
                   }
-                },
-                "type": "object"
-              },
-              "person_ids": {
-                "description": "直接指派的成员 ID 列表（1–100 个），可与 `escalate_rule_id` 同时使用。",
-                "items": {
-                  "format": "int64",
-                  "type": "integer"
-                },
-                "maxItems": 100,
-                "minItems": 1,
-                "type": "array"
-              },
-              "type": {
-                "description": "指派类型，由服务端自动推导，调用方无需传值：手动创建为 `assign`，再次指派为 `reassign`，升级触发为 `escalate`。\n| 值 | 含义 |\n|---|---|\n| `assign` | 手动创建故障时的首次指派。 |\n| `reassign` | 对已有故障的再次指派。 |\n| `escalate` | 分派策略升级触发的指派。 |\n| `reopen` | 故障重新打开后从第一环节重新开始的分派。 |",
-                "enum": [
-                  "assign",
-                  "reassign",
-                  "escalate",
-                  "reopen"
-                ],
-                "type": "string"
+                }
               }
-            },
-            "type": "object"
-          },
-          "channel_id": {
-            "description": "归属的协作空间 ID,留空表示独立故障。",
-            "format": "int64",
-            "type": "integer"
-          },
-          "description": {
-            "description": "故障描述,最多 1024 个字符。",
-            "maxLength": 1024,
-            "type": "string"
+            }
           },
           "fields": {
             "$ref": "#/components/schemas/CustomFieldValues",
             "description": "以字段名为键的自定义字段值。创建表单生效时，只接受表单中可见的字段。"
-          },
-          "incident_severity": {
-            "description": "故障严重程度：`Info` 提示、`Warning` 警告、`Critical` 严重。",
-            "enum": [
-              "Info",
-              "Warning",
-              "Critical"
-            ],
-            "type": "string"
-          },
-          "title": {
-            "description": "故障标题,最多 512 个字符。",
-            "maxLength": 512,
-            "type": "string"
           }
-        },
-        "required": [
-          "incident_severity"
-        ],
-        "type": "object"
+        }
       },
       "CreateIncidentResponse": {
+        "type": "object",
         "description": "手动创建故障的返回结果。",
+        "required": [
+          "incident_id",
+          "title"
+        ],
         "properties": {
           "incident_id": {
-            "description": "新建故障的 ID（MongoDB ObjectID）。",
+            "type": "string",
             "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
+            "description": "新建故障的 ID（MongoDB ObjectID）。"
           },
           "title": {
-            "description": "回显请求中传入的故障标题。",
-            "type": "string"
+            "type": "string",
+            "description": "请求中传入的故障标题；请求未传标题时为空。"
           }
-        },
-        "required": [
-          "incident_id",
-          "title"
-        ],
-        "type": "object"
+        }
       },
       "CreateInhibitRuleRequest": {
+        "type": "object",
         "description": "创建抑制策略所需的参数。",
+        "required": [
+          "channel_id",
+          "rule_name",
+          "equals"
+        ],
         "properties": {
           "channel_id": {
-            "description": "所属协作空间 ID，可通过 `POST /channel/list` 获取。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "所属协作空间 ID，可通过 `POST /channel/list` 获取。"
+          },
+          "rule_name": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 39,
+            "description": "策略名称,1 到 39 个字符。"
           },
           "description": {
-            "description": "策略描述,最多 500 个字符。",
+            "type": "string",
             "maxLength": 500,
-            "type": "string"
+            "description": "策略描述,最多 500 个字符。"
           },
           "equals": {
-            "description": "源（抑制方）告警与目标（被抑制）告警之间必须取值相等的字段键，例如 `data_source_id` 或 `labels.cluster`。",
+            "type": "array",
             "items": {
               "type": "string"
             },
-            "type": "array"
-          },
-          "is_directly_discard": {
-            "description": "为 true 时，命中的告警事件被完全丢弃；为 false 时，告警仍会被记录，但标记为被本策略静默。",
-            "type": "boolean"
-          },
-          "rule_name": {
-            "description": "策略名称,1 到 39 个字符。",
-            "maxLength": 39,
-            "minLength": 1,
-            "type": "string"
+            "description": "源告警与新事件取值必须相同的字段。只有 `title`、`severity` 和 `labels.<name>` 有效；其他字段（例如 `data_source_id`）虽能保存，但会导致策略永远不生效。必须传入；空数组同样使策略不生效。"
           },
           "source_filters": {
-            "description": "源告警需要满足的条件，针对已存的活跃告警求值。支持的键：`status`、`incident_status`、`alert_status`、`severity`、`incident_severity`、`alert_severity`、`title`、`description` 或任意 `labels.<name>`。为空时策略不生效。",
-            "items": {
-              "items": {
-                "properties": {
-                  "key": {
-                    "description": "字段键(如 `alert_severity`、`labels.service`)。",
-                    "type": "string"
-                  },
-                  "oper": {
-                    "description": "过滤运算符。",
-                    "enum": [
-                      "IN",
-                      "NOTIN"
-                    ],
-                    "type": "string"
-                  },
-                  "vals": {
-                    "description": "匹配值列表。",
-                    "items": {
-                      "type": "string"
-                    },
-                    "type": "array"
-                  }
-                },
-                "required": [
-                  "key",
-                  "oper",
-                  "vals"
-                ],
-                "type": "object"
-              },
-              "type": "array"
-            },
-            "type": "array"
+            "$ref": "#/components/schemas/FilterGroup",
+            "description": "源告警（起抑制作用的告警）需满足的条件，匹配对象是协作空间内已存储的活跃告警。可用字段：`title`、`description`、`severity`（别名 `incident_severity`、`alert_severity`）、`status`（别名 `incident_status`、`alert_status`），或任意 `labels.<name>`。为空时策略不生效。"
           },
           "target_filters": {
-            "description": "目标（被抑制）告警事件需要满足的条件；为空表示所有事件都是抑制目标。",
-            "items": {
-              "items": {
-                "properties": {
-                  "key": {
-                    "description": "字段键(如 `alert_severity`、`labels.service`)。",
-                    "type": "string"
-                  },
-                  "oper": {
-                    "description": "过滤运算符。",
-                    "enum": [
-                      "IN",
-                      "NOTIN"
-                    ],
-                    "type": "string"
-                  },
-                  "vals": {
-                    "description": "匹配值列表。",
-                    "items": {
-                      "type": "string"
-                    },
-                    "type": "array"
-                  }
-                },
-                "required": [
-                  "key",
-                  "oper",
-                  "vals"
-                ],
-                "type": "object"
-              },
-              "type": "array"
-            },
-            "type": "array"
+            "$ref": "#/components/schemas/FilterGroup",
+            "description": "新进入的告警事件需满足的条件，满足才会被抑制；为空表示所有新事件都是抑制对象。可用字段：`title`、`description`、`severity`（别名 `alert_severity`、`event_severity`）、`status`、`alert_key`、`title_rule`、`integration_id`（别名 `data_source_id`），或任意 `labels.<name>`。"
+          },
+          "is_directly_discard": {
+            "type": "boolean",
+            "description": "为 true 时，命中的告警事件被完全丢弃；为 false 时，告警仍会被记录，但标记为被本策略静默。"
           }
-        },
-        "required": [
-          "channel_id",
-          "rule_name",
-          "equals"
-        ],
-        "type": "object"
+        }
       },
       "CreateSilenceRuleRequest": {
+        "type": "object",
         "description": "创建静默策略所需的参数。`time_filter` 与 `time_filters` 必须且只能设置其一,`filters` 不能为空。",
+        "required": [
+          "channel_id",
+          "rule_name"
+        ],
         "properties": {
           "channel_id": {
-            "description": "所属协作空间 ID，可通过 `POST /channel/list` 获取。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "所属协作空间 ID，可通过 `POST /channel/list` 获取。"
+          },
+          "rule_name": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 39,
+            "description": "策略名称,1 到 39 个字符。"
           },
           "description": {
-            "description": "策略描述,最多 500 个字符。",
+            "type": "string",
             "maxLength": 500,
-            "type": "string"
+            "description": "策略描述,最多 500 个字符。"
           },
-          "filters": {
-            "description": "告警事件匹配条件（OR-of-AND 结构）。必填且至少包含一个条件。",
+          "from_incident_id": {
+            "type": "string",
+            "description": "创建该策略所依据的故障 ID（24 位十六进制）。故障必须存在，且每个故障只能有一条启用的静默策略。",
+            "pattern": "^[0-9a-fA-F]{24}$"
+          },
+          "time_filters": {
+            "type": "array",
             "items": {
-              "items": {
-                "properties": {
-                  "key": {
-                    "description": "字段键(如 `alert_severity`、`labels.service`)。",
-                    "type": "string"
-                  },
-                  "oper": {
-                    "description": "过滤运算符。",
-                    "enum": [
-                      "IN",
-                      "NOTIN"
-                    ],
-                    "type": "string"
-                  },
-                  "vals": {
-                    "description": "匹配值列表。",
-                    "items": {
-                      "type": "string"
-                    },
-                    "type": "array"
-                  }
-                },
-                "required": [
-                  "key",
-                  "oper",
-                  "vals"
-                ],
-                "type": "object"
-              },
-              "type": "array"
+              "$ref": "#/components/schemas/TimeFilter"
             },
-            "type": "array"
+            "description": "周期静默窗口。`time_filters` 与 `time_filter` 必须且只能设置其一。"
           },
-          "from_incident_id": {
-            "description": "策略关联的故障 ID（ObjectID 十六进制）。可选；设置后每个故障最多存在一条启用中的静默策略。",
-            "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
+          "time_filter": {
+            "$ref": "#/components/schemas/OnceTimeFilter",
+            "description": "一次性静默窗口。`time_filter` 与 `time_filters` 必须且只能设置其一。"
           },
-          "is_auto_delete": {
-            "description": "为 true 时，静默规则在时间窗结束后会被自动删除；默认为 false。",
-            "type": "boolean"
+          "filters": {
+            "$ref": "#/components/schemas/FilterGroup",
+            "description": "告警事件匹配条件（AND 组之间为 OR），时间窗口内命中的事件被静默。必填，且至少包含一个条件。可用字段：`title`、`description`、`severity`（别名 `alert_severity`、`event_severity`）、`status`、`alert_key`、`title_rule`、`integration_id`（别名 `data_source_id`），或任意 `labels.<name>`。"
           },
           "is_directly_discard": {
-            "description": "为 true 时，命中的告警事件被完全丢弃；为 false 时，告警仍会被记录，但标记为被本策略静默。",
-            "type": "boolean"
-          },
-          "rule_name": {
-            "description": "策略名称,1 到 39 个字符。",
-            "maxLength": 39,
-            "minLength": 1,
-            "type": "string"
-          },
-          "time_filter": {
-            "description": "一次性时间窗口,使用 Unix 秒定义。",
-            "properties": {
-              "end_time": {
-                "description": "窗口结束时间，Unix 秒时间戳。必须大于 0。",
-                "exclusiveMinimum": 0,
-                "format": "int64",
-                "type": "integer"
-              },
-              "start_time": {
-                "description": "窗口起始时间，Unix 秒时间戳。必须大于 0 且小于 `end_time`。",
-                "exclusiveMinimum": 0,
-                "format": "int64",
-                "type": "integer"
-              }
-            },
-            "required": [
-              "start_time",
-              "end_time"
-            ],
-            "type": "object"
+            "type": "boolean",
+            "description": "为 true 时，命中的告警事件被完全丢弃；为 false 时，告警仍会被记录，但标记为被本策略静默。"
           },
-          "time_filters": {
-            "description": "生效的周期性时间窗口列表,与 `time_filter` 互斥。",
-            "items": {
-              "description": "周期性时间窗口。`start`/`end` 使用 24 小时制 `HH:MM` 格式;`repeat` 使用星期索引(0=周日 … 6=周六)。",
-              "properties": {
-                "cal_id": {
-                  "description": "可选日历 ID,限制窗口仅在日历匹配的日期生效。",
-                  "type": "string"
-                },
-                "end": {
-                  "description": "窗口结束时间,`HH:MM`。",
-                  "type": "string"
-                },
-                "is_off": {
-                  "description": "为 true 时匹配日历中的休息日。",
-                  "type": "boolean"
-                },
-                "repeat": {
-                  "description": "生效的星期列表,留空表示每天。",
-                  "items": {
-                    "type": "integer"
-                  },
-                  "type": "array"
-                },
-                "start": {
-                  "description": "窗口起始时间,`HH:MM`。",
-                  "type": "string"
-                }
-              },
-              "type": "object"
-            },
-            "type": "array"
+          "is_auto_delete": {
+            "type": "boolean",
+            "description": "为 true 时，使用一次性 `time_filter` 的策略在 `end_time`（或最近一次更新时间，取较晚者）约 24 小时后被永久移除。通过 `from_incident_id` 创建的策略同样按此方式清理。使用周期 `time_filters` 的策略不会被自动移除。默认 `false`。"
           }
-        },
-        "required": [
-          "channel_id",
-          "rule_name"
-        ],
-        "type": "object"
+        }
       },
       "CreateStatusPageChangeRequest": {
+        "type": "object",
         "description": "创建状态页故障或维护事件所需的参数。首条更新必须包含 `component_changes` 以声明受影响组件;回溯事件至少需要 2 条更新。",
+        "required": [
+          "page_id",
+          "type",
+          "title",
+          "description",
+          "status",
+          "updates"
+        ],
         "properties": {
-          "auto_update_by_schedule": {
-            "description": "仅维护事件:根据计划窗口自动推进状态。",
-            "type": "boolean"
-          },
-          "close_at_seconds": {
-            "description": "事件结束时间（Unix 秒），必须大于或等于第一条更新的 `at_seconds`。回溯事件用它表示结束时间；对于开启 `auto_update_by_schedule` 的维护事件，它用于调度自动切换为 `completed` 的任务，且距当前时间不能超过 30 天。",
-            "format": "int64",
-            "type": "integer"
-          },
-          "description": {
-            "description": "事件描述（支持 Markdown），必填，不能为空。",
-            "type": "string"
-          },
-          "is_retrospective": {
-            "description": "标记为回溯(历史)事件。",
-            "type": "boolean"
-          },
-          "linked_changes": {
-            "description": "关联的事件 ID 列表(相关故障、发布等)。",
-            "items": {
-              "type": "string"
-            },
-            "type": "array"
-          },
-          "notify_subscribers": {
-            "description": "是否通知订阅者本事件及其所有更新。",
-            "type": "boolean"
-          },
           "page_id": {
-            "description": "状态页 ID，可通过 `GET /status-page/list` 获取。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "状态页 ID，可通过 `GET /status-page/list` 获取。"
           },
-          "responders": {
-            "description": "事件负责成员的 ID 列表。",
-            "items": {
-              "format": "int64",
-              "type": "integer"
-            },
-            "type": "array"
+          "type": {
+            "type": "string",
+            "enum": [
+              "incident",
+              "maintenance"
+            ],
+            "description": "事件类型：`incident` 故障，`maintenance` 计划维护。"
           },
-          "start_at_seconds": {
-            "description": "事件开始时间（Unix 秒）。存储的开始时间始终以第一条更新的 `at_seconds` 为准（该字段缺省时取当前时间）；对于开启 `auto_update_by_schedule` 的维护事件，本字段用于调度自动切换为 `ongoing` 的任务。",
-            "format": "int64",
-            "type": "integer"
+          "title": {
+            "type": "string",
+            "maxLength": 255,
+            "description": "事件标题,最多 255 个字符。"
+          },
+          "description": {
+            "type": "string",
+            "description": "事件描述（支持 Markdown），必填，不能为空。"
           },
           "status": {
-            "description": "事件初始状态。故障事件支持 `investigating`/`identified`/`monitoring`/`resolved`;维护事件支持 `scheduled`/`ongoing`/`completed`。",
+            "type": "string",
             "enum": [
               "investigating",
               "identified",
@@ -6320,68 +6132,53 @@
               "ongoing",
               "completed"
             ],
-            "type": "string"
+            "description": "事件初始状态。故障事件支持 `investigating`/`identified`/`monitoring`/`resolved`;维护事件支持 `scheduled`/`ongoing`/`completed`。"
           },
-          "title": {
-            "description": "事件标题,最多 255 个字符。",
-            "maxLength": 255,
-            "type": "string"
+          "start_at_seconds": {
+            "type": "integer",
+            "format": "int64",
+            "description": "事件开始时间，Unix 时间戳（秒）。维护事件会将其保存为计划开始时间（开启 `auto_update_by_schedule` 时即切换为 `ongoing` 的时间）；省略或为 0 时，以及故障事件，开始时间一律取第一条更新的 `at_seconds`。"
+          },
+          "responders": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "int64"
+            },
+            "description": "事件负责成员的 ID 列表。"
+          },
+          "linked_changes": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "关联的事件 ID 列表(相关故障、发布等)。"
           },
-          "type": {
-            "description": "事件类型：`incident` 故障，`maintenance` 计划维护。",
-            "enum": [
-              "incident",
-              "maintenance"
-            ],
-            "type": "string"
+          "close_at_seconds": {
+            "type": "integer",
+            "format": "int64",
+            "description": "事件结束时间，Unix 时间戳（秒），必须大于或等于第一条更新的 `at_seconds`。维护事件为计划结束时间；开启 `auto_update_by_schedule` 时会在该时间切换为 `completed`，且必须在当前时间起 30 天内。复盘事件处于终态且未传此字段时，取最后一条更新的时间。"
           },
           "updates": {
-            "description": "时间线更新列表。至少传 1 条，且至少有一条必须包含 `component_changes`。即时事件一般只传一条；回溯事件需传入全部历史更新。",
+            "type": "array",
             "items": {
+              "type": "object",
               "description": "时间线更新条目。",
               "properties": {
+                "update_id": {
+                  "type": "string",
+                  "description": "更新 ID。创建时由服务端生成;回溯历史更新时可手动指定。"
+                },
                 "at_seconds": {
-                  "description": "更新时间戳（Unix 秒）。第一条更新缺省或为 0 时取当前时间。",
+                  "type": "integer",
                   "format": "int64",
-                  "type": "integer"
-                },
-                "component_changes": {
-                  "description": "本次更新应用的组件状态变更。",
-                  "items": {
-                    "properties": {
-                      "component_id": {
-                        "description": "组件 ID，可通过 `GET /status-page/info` 获取。",
-                        "type": "string"
-                      },
-                      "status": {
-                        "description": "组件新状态。故障事件支持 `operational`/`degraded`/`partial_outage`/`full_outage`;维护事件支持 `operational`/`under_maintenance`。",
-                        "enum": [
-                          "operational",
-                          "degraded",
-                          "partial_outage",
-                          "full_outage",
-                          "under_maintenance"
-                        ],
-                        "type": "string"
-                      }
-                    },
-                    "required": [
-                      "component_id",
-                      "status"
-                    ],
-                    "type": "object"
-                  },
-                  "type": "array"
+                  "description": "更新时间戳（Unix 秒）。第一条更新缺省或为 0 时取当前时间。"
                 },
-                "description": {
-                  "description": "更新说明(支持 Markdown)。",
+                "status": {
                   "type": [
                     "string",
                     "null"
-                  ]
-                },
-                "status": {
-                  "description": "更新后的事件状态。若整体状态未变化可省略。前四个值仅适用于 incident 类型，后三个仅适用于 maintenance 类型。\n| 值 | 含义 |\n|---|---|\n| `investigating` | 排查中（incident）。 |\n| `identified` | 已定位原因（incident）。 |\n| `monitoring` | 已修复，观察中（incident）。 |\n| `resolved` | 已解决（incident）。 |\n| `scheduled` | 已计划（maintenance）。 |\n| `ongoing` | 进行中（maintenance）。 |\n| `completed` | 已完成（maintenance）。 |",
+                  ],
                   "enum": [
                     "investigating",
                     "identified",
@@ -6391,55 +6188,123 @@
                     "ongoing",
                     "completed"
                   ],
+                  "description": "更新后的事件状态。若整体状态未变化可省略。前四个值仅适用于 incident 类型，后三个仅适用于 maintenance 类型。\n| 值 | 含义 |\n|---|---|\n| `investigating` | 排查中（incident）。 |\n| `identified` | 已定位原因（incident）。 |\n| `monitoring` | 已修复，观察中（incident）。 |\n| `resolved` | 已解决（incident）。 |\n| `scheduled` | 已计划（maintenance）。 |\n| `ongoing` | 进行中（maintenance）。 |\n| `completed` | 已完成（maintenance）。 |"
+                },
+                "description": {
                   "type": [
                     "string",
                     "null"
-                  ]
+                  ],
+                  "description": "更新说明(支持 Markdown)。"
                 },
-                "update_id": {
-                  "description": "更新 ID。创建时由服务端生成;回溯历史更新时可手动指定。",
-                  "type": "string"
+                "component_changes": {
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "required": [
+                      "component_id",
+                      "status"
+                    ],
+                    "properties": {
+                      "component_id": {
+                        "type": "string",
+                        "description": "组件 ID，可通过 `GET /status-page/info` 获取。"
+                      },
+                      "status": {
+                        "type": "string",
+                        "enum": [
+                          "operational",
+                          "degraded",
+                          "partial_outage",
+                          "full_outage",
+                          "under_maintenance"
+                        ],
+                        "description": "组件新状态。故障事件支持 `operational`/`degraded`/`partial_outage`/`full_outage`;维护事件支持 `operational`/`under_maintenance`。"
+                      }
+                    }
+                  },
+                  "description": "本次更新应用的组件状态变更。"
                 }
-              },
-              "type": "object"
+              }
             },
-            "minItems": 1,
-            "type": "array"
+            "description": "时间线更新，须按 `at_seconds` 非递减排列。至少需要一条更新，且至少一条包含 `component_changes`。即时事件通常传一条；复盘事件至少传两条。",
+            "minItems": 1
+          },
+          "notify_subscribers": {
+            "type": "boolean",
+            "description": "是否通知订阅者。创建时仅针对最后一条更新发送一次通知；之后发布的时间线更新在该值为 `true` 时也会通知。"
+          },
+          "auto_update_by_schedule": {
+            "type": "boolean",
+            "description": "仅维护事件:根据计划窗口自动推进状态。"
+          },
+          "is_retrospective": {
+            "type": "boolean",
+            "description": "将事件标记为复盘事件（事后补录的历史事件）。要求 `updates` 至少两条。"
+          },
+          "draft_id": {
+            "type": "string",
+            "description": "随本次创建一并发布的草稿 ID，由 `POST /status-page/draft/create` 返回。草稿须处于待发布状态、指向本 `page_id` 和 `type` 且不带 `change_id`；事件创建成功后草稿标记为已发布。不发布草稿时省略。"
           }
-        },
+        }
+      },
+      "CreateStatusPageChangeTimelineRequest": {
+        "type": "object",
+        "description": "向状态页事件时间线追加一条更新所需的参数。",
         "required": [
           "page_id",
-          "type",
-          "title",
-          "description",
+          "change_id",
           "status",
-          "updates"
+          "description"
         ],
-        "type": "object"
-      },
-      "CreateStatusPageChangeTimelineRequest": {
-        "description": "向状态页事件时间线追加一条更新所需的参数。",
         "properties": {
-          "at_seconds": {
-            "description": "更新时间戳（Unix 秒），缺省或为 0 时取当前时间。",
+          "page_id": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "状态页 ID，可通过 `GET /status-page/list` 获取。"
           },
           "change_id": {
-            "description": "目标事件 ID，可通过 `GET /status-page/change/list` 获取。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "目标事件 ID，可通过 `GET /status-page/change/list` 获取。"
+          },
+          "at_seconds": {
+            "type": "integer",
+            "format": "int64",
+            "description": "更新时间，Unix 时间戳（秒），不能早于事件最新一条时间线更新。省略或为 0 时取当前时间。"
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "investigating",
+              "identified",
+              "monitoring",
+              "resolved",
+              "scheduled",
+              "ongoing",
+              "completed"
+            ],
+            "description": "本次更新后的事件状态，必须与事件类型匹配。若不改变状态，请传入当前状态。切换为 `resolved` 或 `completed` 时，所有受影响组件必须已恢复为 `operational`。\n| 取值 | 含义 |\n|---|---|\n| `investigating` | 调查中（故障）。 |\n| `identified` | 已定位原因（故障）。 |\n| `monitoring` | 已修复，观察中（故障）。 |\n| `resolved` | 已解决（故障）。 |\n| `scheduled` | 已计划（维护）。 |\n| `ongoing` | 进行中（维护）。 |\n| `completed` | 已完成（维护）。 |"
+          },
+          "description": {
+            "type": "string",
+            "description": "更新说明（支持 Markdown），必填，不能为空。"
           },
           "component_changes": {
-            "description": "本次更新应用的组件状态变更。组件 ID 不能重复。",
+            "type": "array",
             "items": {
+              "type": "object",
+              "required": [
+                "component_id",
+                "status"
+              ],
               "properties": {
                 "component_id": {
-                  "description": "组件 ID，可通过 `GET /status-page/info` 获取。",
-                  "type": "string"
+                  "type": "string",
+                  "description": "组件 ID，可通过 `GET /status-page/info` 获取。"
                 },
                 "status": {
-                  "description": "组件新状态。故障事件支持 `operational`/`degraded`/`partial_outage`/`full_outage`;维护事件支持 `operational`/`under_maintenance`。",
+                  "type": "string",
                   "enum": [
                     "operational",
                     "degraded",
@@ -6447,137 +6312,216 @@
                     "full_outage",
                     "under_maintenance"
                   ],
-                  "type": "string"
+                  "description": "组件新状态。故障事件支持 `operational`/`degraded`/`partial_outage`/`full_outage`;维护事件支持 `operational`/`under_maintenance`。"
                 }
-              },
-              "required": [
-                "component_id",
-                "status"
-              ],
-              "type": "object"
+              }
             },
-            "type": "array"
-          },
-          "description": {
-            "description": "更新说明（支持 Markdown），必填，不能为空。",
-            "type": "string"
-          },
-          "page_id": {
-            "description": "状态页 ID，可通过 `GET /status-page/list` 获取。",
-            "format": "int64",
-            "type": "integer"
+            "description": "本次更新应用的组件状态变更。组件 ID 不能重复。"
           },
-          "status": {
-            "description": "更新后的事件状态，需与事件类型匹配。当状态切换为 `resolved` 或 `completed` 时，所有受影响组件必须恢复为 `operational`。\n| 值 | 含义 |\n|---|---|\n| `investigating` | 排查中（incident）。 |\n| `identified` | 已定位原因（incident）。 |\n| `monitoring` | 已修复，观察中（incident）。 |\n| `resolved` | 已解决（incident）。 |\n| `scheduled` | 已计划（maintenance）。 |\n| `ongoing` | 进行中（maintenance）。 |\n| `completed` | 已完成（maintenance）。 |",
-            "enum": [
-              "investigating",
-              "identified",
-              "monitoring",
-              "resolved",
-              "scheduled",
-              "ongoing",
-              "completed"
-            ],
-            "type": "string"
+          "draft_id": {
+            "type": "string",
+            "description": "待发布草稿的 ID（由 `POST /status-page/draft/create` 返回，且其 `change_id` 指向本事件）；更新写入后草稿标记为已发布。不发布草稿时省略。"
           }
-        },
-        "required": [
-          "page_id",
-          "change_id",
-          "status",
-          "description"
-        ],
-        "type": "object"
+        }
       },
       "CreateStatusPageDraftRequest": {
+        "type": "object",
         "description": "存储状态页草稿的参数。`draft` 载荷将被原样存储，仅下列被校验的字段会被解析。",
+        "required": [
+          "draft"
+        ],
         "properties": {
           "draft": {
-            "description": "草稿载荷，原样存储，序列化后最大 64 KB。被校验的字段：`page_id`、`type`（`incident` 或 `maintenance`）、`name`、`message`；可选 `change_id`（大于 0 时表示向已有事件追加进展）、`status`、`affected_components`，以及 `start_time`/`end_time`（Unix epoch 秒，仅新建维护窗口时使用）。",
-            "type": "object"
+            "type": "object",
+            "description": "草稿载荷，原样存储（序列化后最大 64 KB）。服务端校验以下字段，其他字段原样保留供控制台使用。",
+            "required": [
+              "page_id",
+              "type",
+              "name",
+              "message"
+            ],
+            "additionalProperties": true,
+            "properties": {
+              "v": {
+                "type": "integer",
+                "description": "由生成方指定的载荷格式版本；仅存储，不解析。"
+              },
+              "page_id": {
+                "type": "integer",
+                "format": "int64",
+                "description": "目标状态页 ID，必须属于调用方账户。"
+              },
+              "page_name": {
+                "type": "string",
+                "description": "供控制台展示的状态页名称，不做校验。"
+              },
+              "type": {
+                "type": "string",
+                "enum": [
+                  "incident",
+                  "maintenance"
+                ],
+                "description": "草稿要创建或更新的事件类型：`incident` 为非计划故障，`maintenance` 为计划维护。"
+              },
+              "name": {
+                "type": "string",
+                "maxLength": 255,
+                "description": "事件标题，1 到 255 个字符。"
+              },
+              "message": {
+                "type": "string",
+                "description": "事件或更新的描述（Markdown），不能为空。"
+              },
+              "change_id": {
+                "type": "integer",
+                "format": "int64",
+                "description": "要追加更新的事件，必须是 `page_id` 上同一 `type` 的事件。省略或传 0 表示起草新事件。"
+              },
+              "status": {
+                "type": "string",
+                "enum": [
+                  "investigating",
+                  "identified",
+                  "monitoring",
+                  "resolved",
+                  "scheduled",
+                  "ongoing",
+                  "completed"
+                ],
+                "description": "建议的事件状态；传入时必须与 `type` 匹配（故障为 `investigating`/`identified`/`monitoring`/`resolved`，维护为 `scheduled`/`ongoing`/`completed`）。"
+              },
+              "affected_components": {
+                "type": "array",
+                "description": "草稿涉及的组件。",
+                "items": {
+                  "type": "object",
+                  "required": [
+                    "component_id"
+                  ],
+                  "properties": {
+                    "component_id": {
+                      "type": "string",
+                      "description": "组件 ID，必须存在于该状态页。"
+                    },
+                    "name": {
+                      "type": "string",
+                      "description": "供展示的组件名称，不做校验。"
+                    },
+                    "status": {
+                      "type": "string",
+                      "enum": [
+                        "operational",
+                        "degraded",
+                        "partial_outage",
+                        "full_outage",
+                        "under_maintenance"
+                      ],
+                      "description": "建议的组件状态；传入时必须与 `type` 匹配（故障为 `operational`/`degraded`/`partial_outage`/`full_outage`，维护为 `operational`/`under_maintenance`）。"
+                    }
+                  }
+                }
+              },
+              "start_time": {
+                "type": "integer",
+                "format": "int64",
+                "description": "新维护事件的计划开始时间，Unix 时间戳（秒）。"
+              },
+              "end_time": {
+                "type": "integer",
+                "format": "int64",
+                "description": "新维护事件的计划结束时间，Unix 时间戳（秒）；与 `start_time` 同时传入时必须大于 `start_time`。"
+              }
+            }
           },
           "source": {
-            "description": "草稿来源的不透明标记，例如 `ai_sre:sess_xxx`。最长 64 个字符。",
+            "type": "string",
             "maxLength": 64,
-            "type": "string"
+            "description": "记录草稿来源的自由文本（例如 AI 会话标识），随草稿存储和展示，服务端不解析。最多 64 个字符。"
           }
-        },
-        "required": [
-          "draft"
-        ],
-        "type": "object"
+        }
       },
       "CreateStatusPageRequest": {
+        "type": "object",
         "properties": {
-          "contact_info": {
-            "description": "联系信息，例如 mailto 或网站 URL。",
-            "type": "string"
+          "name": {
+            "type": "string",
+            "description": "状态页展示名称。",
+            "maxLength": 255
+          },
+          "url_name": {
+            "type": "string",
+            "description": "URL 安全 slug；会规范化为小写，非字母数字字符替换为连字符，且在账户内同类型状态页中必须唯一。",
+            "maxLength": 255
+          },
+          "type": {
+            "type": "string",
+            "description": "状态页可见性类型：`public` 任何人可访问，`internal` 仅本账号登录成员可见。",
+            "enum": [
+              "public",
+              "internal"
+            ]
           },
           "custom_domain": {
-            "description": "公开状态页使用的自定义域名。",
-            "maxLength": 255,
-            "type": "string"
+            "type": "string",
+            "description": "自定义域名，仅公开页可设置，且不能被其他状态页占用。",
+            "maxLength": 255
           },
-          "custom_links": {
-            "description": "状态页展示的自定义导航链接。",
-            "items": {
-              "additionalProperties": {
-                "type": "string"
-              },
-              "type": "object"
-            },
-            "type": "array"
+          "page_title": {
+            "type": "string",
+            "description": "为兼容保留的字段，服务端不会存储，传入无效果。"
+          },
+          "page_header": {
+            "type": "string",
+            "description": "状态页页头内容。"
+          },
+          "page_footer": {
+            "type": "string",
+            "description": "状态页页脚内容。"
           },
           "date_view": {
+            "type": "string",
             "description": "事件日期展示方式：`calendar` 日历视图，`list` 列表视图。",
             "enum": [
               "calendar",
               "list"
-            ],
-            "type": "string"
+            ]
           },
           "display_uptime_mode": {
+            "type": "string",
             "description": "可用率展示方式：`chart_and_percentage` 图表加百分比，`chart` 仅图表，`none` 不展示。",
             "enum": [
               "chart_and_percentage",
               "chart",
               "none"
-            ],
-            "type": "string"
-          },
-          "name": {
-            "description": "状态页展示名称。",
-            "maxLength": 255,
-            "type": "string"
-          },
-          "page_footer": {
-            "description": "状态页页脚内容。",
-            "type": "string"
+            ]
           },
-          "page_header": {
-            "description": "状态页页头内容。",
-            "type": "string"
+          "custom_links": {
+            "type": "array",
+            "description": "状态页展示的自定义导航链接。",
+            "items": {
+              "type": "object",
+              "properties": {
+                "key": {
+                  "type": "string",
+                  "description": "页面上显示的链接文字。"
+                },
+                "value": {
+                  "type": "string",
+                  "description": "链接文字指向的地址，例如 `https://www.example.com`。"
+                }
+              },
+              "additionalProperties": {
+                "type": "string"
+              }
+            }
           },
-          "page_title": {
-            "description": "状态页浏览器标题。",
-            "type": "string"
+          "contact_info": {
+            "type": "string",
+            "description": "联系信息，例如 mailto 或网站 URL。"
           },
           "subscription": {
             "$ref": "#/components/schemas/StatusPageSubscriptionItem",
-            "description": "订阅渠道开关。"
-          },
-          "type": {
-            "description": "状态页可见性类型：`public` 任何人可访问，`internal` 仅本账号登录成员可见。",
-            "enum": [
-              "public",
-              "internal"
-            ],
-            "type": "string"
-          },
-          "url_name": {
-            "description": "URL 安全的状态页路径，在账户和状态页类型内唯一。",
-            "maxLength": 255,
-            "type": "string"
+            "description": "订阅渠道开关，默认均为 `false`。公开页只能开启 `email`，内部页只能开启 `im`。"
           }
         },
         "required": [
@@ -6586,8 +6530,7 @@
           "type",
           "date_view",
           "display_uptime_mode"
-        ],
-        "type": "object"
+        ]
       },
       "CreateStatusPageResponse": {
         "properties": {
@@ -6613,91 +6556,67 @@
         "type": "object"
       },
       "CreateWarRoomRequest": {
+        "type": "object",
         "description": "为故障开启 IM 作战室所需的参数。",
+        "required": [
+          "incident_id",
+          "integration_id"
+        ],
         "properties": {
-          "add_observers": {
-            "description": "为 true 时同时将历史处理人员加入作战室作为观察员。",
-            "type": "boolean"
-          },
           "incident_id": {
-            "description": "故障 ID(MongoDB ObjectID)。",
+            "type": "string",
             "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
+            "description": "故障 ID(MongoDB ObjectID)。"
           },
           "integration_id": {
-            "description": "IM 集成 ID。需开启作战室能力;当前支持飞书、钉钉、企业自建企业微信、Slack 与 Teams。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "已开启作战室功能的 IM 集成 ID，可通过 `POST /datasource/im/war-room-enabled/list` 获取。支持飞书、钉钉、企业微信（仅自建应用）和 Slack。"
           },
           "member_ids": {
-            "description": "额外加入作战室的成员 ID 列表。",
+            "type": "array",
             "items": {
-              "format": "int64",
-              "type": "integer"
+              "type": "integer",
+              "format": "int64"
             },
-            "type": "array"
+            "description": "要邀请进群的成员 ID；每个 ID 都必须是账户中的有效成员。"
+          },
+          "add_observers": {
+            "type": "boolean",
+            "description": "为 true 时，同时邀请曾被分派或添加为处理人、但当前已不是处理人的成员。"
           }
-        },
-        "required": [
-          "incident_id",
-          "integration_id"
-        ],
-        "type": "object"
+        }
       },
       "CreateWorkItemRequest": {
+        "type": "object",
         "description": "创建故障跟进事项的参数。",
+        "required": [
+          "item_type",
+          "title",
+          "incident_id",
+          "idempotency_key"
+        ],
         "properties": {
-          "assignee_ids": {
-            "description": "初始负责人的旧版别名，等价于全部为 `person` 的 `assignees`。与 `assignees` 互斥，同时出现会报错。负责人须为已能查看锚定对象的活跃成员；指派不会授予访问权限。",
-            "items": {
-              "format": "int64",
-              "type": "integer"
-            },
-            "type": "array"
-          },
-          "assignees": {
-            "description": "初始负责人列表。每项为 `{type, id?}`。`type` 取 `person` 或 `ai_sre`；`ai_sre` 不带 `id`。与 `assignee_ids` 互斥，同时出现会报错。`assignee_ids` 是旧版别名，等价于全部为 `person`。最多 20 项。`person` 须为已能查看锚定对象的活跃成员；指派不会授予访问权限。",
-            "items": {
-              "$ref": "#/components/schemas/WorkItemAssignee"
-            },
-            "maxItems": 20,
-            "type": "array"
-          },
-          "description": {
-            "description": "可选的详细描述（最长 65,535 字符）。",
-            "maxLength": 65535,
-            "type": "string"
-          },
-          "idempotency_key": {
-            "description": "客户端生成的幂等键（最长 128 字符；仅限字母、数字、`_`、`-`、`.`、`:`）。",
-            "maxLength": 128,
-            "pattern": "^[A-Za-z0-9_\\-.:]+$",
-            "type": "string"
-          },
-          "incident_id": {
-            "description": "事项锚定的故障 ID（MongoDB ObjectID）。",
-            "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
-          },
           "item_type": {
-            "description": "`action` 锚定活动故障，不得设置 `post_mortem_id`；`follow_up` 必须设置 `post_mortem_id`。",
+            "type": "string",
             "enum": [
               "action",
               "follow_up"
             ],
-            "type": "string"
+            "description": "事项类型。\n- `action`：未关闭故障上的待办，不得设置 `post_mortem_id`。\n- `follow_up`：已关闭故障上的复盘后续行动，`post_mortem_id` 可选。"
           },
-          "post_mortem_id": {
-            "description": "故障复盘 ID（32 位十六进制字符串）。`follow_up` 必填，`action` 禁止填写。该复盘必须关联到 `incident_id`。",
-            "type": "string"
+          "title": {
+            "type": "string",
+            "maxLength": 512,
+            "description": "事项标题，最多 512 个字符；首尾空白会被去除，且不能为空。"
           },
-          "priority": {
-            "description": "可选的客户端自定义优先级（最长 64 字符）。",
-            "maxLength": 64,
-            "type": "string"
+          "description": {
+            "type": "string",
+            "maxLength": 65535,
+            "description": "可选的详细描述（最长 65,535 字符）。"
           },
           "status": {
-            "description": "可选，客户端自定义的初始状态，取 `open`、`in_progress`、`done`、`cancelled` 之一；省略或为空时默认为 `open`。",
+            "type": "string",
             "enum": [
               "open",
               "in_progress",
@@ -6705,21 +6624,45 @@
               "cancelled"
             ],
             "maxLength": 64,
-            "type": "string"
+            "description": "可选，客户端自定义的初始状态，取 `open`、`in_progress`、`done`、`cancelled` 之一；省略或为空时默认为 `open`。"
           },
-          "title": {
-            "description": "事项标题（最长 512 字符）。",
-            "maxLength": 512,
-            "type": "string"
+          "priority": {
+            "type": "string",
+            "maxLength": 64,
+            "description": "可选的优先级，自由文本，最多 64 个字符。控制台使用 `high`、`medium`、`low`；其他字符串会原样保存。"
+          },
+          "incident_id": {
+            "type": "string",
+            "pattern": "^[0-9a-fA-F]{24}$",
+            "description": "事项锚定的故障 ID（MongoDB ObjectID）。"
+          },
+          "post_mortem_id": {
+            "type": "string",
+            "description": "复盘 ID（32 位十六进制字符串）。`action` 不得设置。`follow_up` 可选：设置时故障须已关联到该复盘；省略时若故障已有复盘则自动使用。"
+          },
+          "assignee_ids": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "int64"
+            },
+            "description": "初始负责人的旧版别名，等价于全部为 `person` 的 `assignees`。与 `assignees` 互斥，同时出现会报错。负责人须为已能查看锚定对象的活跃成员；指派不会授予访问权限。"
+          },
+          "assignees": {
+            "description": "初始负责人列表。每项为 `{type, id?}`。`type` 取 `person` 或 `ai_sre`；`ai_sre` 不带 `id`。与 `assignee_ids` 互斥，同时出现会报错。`assignee_ids` 是旧版别名，等价于全部为 `person`。最多 20 项。`person` 须为已能查看锚定对象的活跃成员；指派不会授予访问权限。",
+            "items": {
+              "$ref": "#/components/schemas/WorkItemAssignee"
+            },
+            "maxItems": 20,
+            "type": "array"
+          },
+          "idempotency_key": {
+            "type": "string",
+            "maxLength": 128,
+            "pattern": "^[A-Za-z0-9_\\-.:]+$",
+            "description": "客户端生成的幂等键（最长 128 字符；仅限字母、数字、`_`、`-`、`.`、`:`）。"
           }
-        },
-        "required": [
-          "item_type",
-          "title",
-          "incident_id",
-          "idempotency_key"
-        ],
-        "type": "object"
+        }
       },
       "CustomFieldValues": {
         "additionalProperties": true,
@@ -6805,64 +6748,64 @@
         "type": "object"
       },
       "DSElasticSearchConfig": {
+        "type": "object",
         "description": "Elasticsearch 数据源配置。",
         "properties": {
-          "api_key": {
-            "description": "Elastic Cloud API 密钥，仅用于 `cloud` 部署。",
-            "type": "string"
-          },
-          "certificate_fingerprint": {
-            "description": "Elasticsearch CA 证书的 SHA-256 指纹，用于校验服务端证书链（ES 8 默认安全配置的推荐方式）。",
-            "type": "string"
-          },
-          "cloud_id": {
-            "description": "Elastic Cloud 部署 ID，仅用于 `cloud` 部署。",
-            "type": "string"
-          },
           "deployment": {
-            "description": "部署类型。`cloud` 使用 Elastic Cloud；`self-managed` 使用自托管集群。",
+            "type": "string",
             "enum": [
               "cloud",
               "self-managed"
             ],
-            "type": "string"
+            "description": "部署类型，必填。`cloud` 使用 Elastic Cloud（无需 `address`）；`self-managed` 使用自建集群（`address` 必填）。"
           },
-          "headers": {
-            "description": "附加到每个请求的自定义 HTTP 头列表，元素格式为 `Key: Value`。",
-            "items": {
-              "type": "string"
-            },
-            "type": "array"
+          "timeout_mills": {
+            "type": "integer",
+            "format": "int64",
+            "description": "单次查询超时时间（毫秒）；`0` 或省略时使用默认值 10000（10 秒）。"
+          },
+          "cloud_id": {
+            "type": "string",
+            "description": "Elastic Cloud 部署 ID，仅用于 `cloud` 部署。"
+          },
+          "api_key": {
+            "type": "string",
+            "description": "Elastic Cloud API 密钥，仅用于 `cloud` 部署。"
+          },
+          "username": {
+            "type": "string",
+            "description": "`self-managed` 部署的用户名。"
           },
           "password": {
-            "description": "自建集群（`self-managed`）的认证密码；配置了 `service_token` 时该字段不生效。",
-            "type": "string"
+            "type": "string",
+            "description": "自建集群（`self-managed`）的认证密码；配置了 `service_token` 时该字段不生效。"
           },
           "service_token": {
-            "description": "服务令牌，若设置则覆盖用户名/密码认证。",
-            "type": "string"
-          },
-          "timeout_mills": {
-            "description": "单次查询超时时间（毫秒）；`0` 或省略时使用默认值 10000（10 秒）。",
-            "format": "int64",
-            "type": "integer"
+            "type": "string",
+            "description": "服务令牌，若设置则覆盖用户名/密码认证。"
           },
           "tls_ca": {
-            "description": "PEM 格式的 CA 证书内容，用于校验 Elasticsearch 服务端证书。",
-            "type": "string"
+            "type": "string",
+            "description": "PEM 格式的 CA 证书内容，用于校验 Elasticsearch 服务端证书。"
           },
-          "username": {
-            "description": "`self-managed` 部署的用户名。",
-            "type": "string"
+          "certificate_fingerprint": {
+            "type": "string",
+            "description": "Elasticsearch CA 证书的 SHA-256 指纹，用于校验服务端证书链（ES 8 默认安全配置的推荐方式）。"
+          },
+          "headers": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "附加到每个请求的自定义 HTTP 头列表，元素格式为 `Key: Value`。"
           }
-        },
-        "type": "object"
+        }
       },
       "DSKafkaConfig": {
         "description": "诊断数据源连接配置。",
         "properties": {
           "password": {
-            "description": "认证密码，支持 ${env:NAME}。更新时省略保留；显式空字符串清除。响应中省略字面密码。",
+            "description": "认证密码，支持 ${env:NAME}。使用 SASL 认证时须与 `username` 一起提供，`sasl_mechanism` 为 `none` 时必须为空。更新时省略表示保留已保存的密码，显式传空字符串表示清除。响应中不返回明文密码。",
             "type": "string",
             "x-flashduty-preserve-absence": true
           },
@@ -6894,7 +6837,7 @@
           },
           "tls_enabled": {
             "default": false,
-            "description": "是否启用 TLS，默认为 false。",
+            "description": "是否启用 TLS，默认 false。为 false 时保存时会清空所有 `tls_*` 字段。",
             "type": "boolean"
           },
           "tls_key": {
@@ -6919,7 +6862,7 @@
             "type": "boolean"
           },
           "username": {
-            "description": "认证用户名，支持 ${env:NAME} 引用。",
+            "description": "认证用户名，支持 ${env:NAME} 引用。`sasl_mechanism` 为 `plain`、`scram-sha-256` 或 `scram-sha-512` 时必填，为 `none` 时必须为空。",
             "type": "string"
           }
         },
@@ -7011,7 +6954,7 @@
           },
           "tls_enabled": {
             "default": false,
-            "description": "是否启用 TLS，默认为 false。",
+            "description": "是否启用 TLS，默认 false。为 false 时保存时会清空所有 `tls_*` 字段。",
             "type": "boolean"
           },
           "tls_max_version": {
@@ -7031,7 +6974,7 @@
             "type": "boolean"
           },
           "username": {
-            "description": "认证用户名，支持 ${env:NAME} 引用。",
+            "description": "认证用户名，支持 ${env:NAME} 引用。须与 `password` 一起提供。",
             "type": "string"
           }
         },
@@ -7146,61 +7089,75 @@
         "type": "object"
       },
       "DSPayload": {
+        "type": "object",
         "description": "与类型相关的数据源配置，仅包含与 `type_ident` 匹配的配置块。",
         "properties": {
+          "prometheus": {
+            "$ref": "#/components/schemas/DSPrometheusConfig",
+            "description": "`type_ident` 为 `prometheus` 时的配置。"
+          },
+          "loki": {
+            "$ref": "#/components/schemas/DSLokiConfig",
+            "description": "`type_ident` 为 `loki` 时的配置。"
+          },
+          "mysql": {
+            "$ref": "#/components/schemas/DSMySQLConfig",
+            "description": "`type_ident` 为 `mysql` 时的配置。"
+          },
+          "oracle": {
+            "$ref": "#/components/schemas/DSOracleConfig",
+            "description": "`type_ident` 为 `oracle` 时的配置。"
+          },
+          "postgres": {
+            "$ref": "#/components/schemas/DSPostgresConfig",
+            "description": "`type_ident` 为 `postgres` 时的配置。"
+          },
           "clickhouse": {
-            "$ref": "#/components/schemas/DSClickHouseConfig"
+            "$ref": "#/components/schemas/DSClickHouseConfig",
+            "description": "`type_ident` 为 `clickhouse` 时的配置。"
           },
           "elasticsearch": {
-            "$ref": "#/components/schemas/DSElasticSearchConfig"
+            "$ref": "#/components/schemas/DSElasticSearchConfig",
+            "description": "`type_ident` 为 `elasticsearch` 时的配置。"
+          },
+          "sls": {
+            "$ref": "#/components/schemas/DSSLSConfig",
+            "description": "`type_ident` 为 `sls` 时的配置。"
+          },
+          "victorialogs": {
+            "$ref": "#/components/schemas/DSVictoriaLogsConfig",
+            "description": "`type_ident` 为 `victorialogs` 时的配置。"
+          },
+          "tencent_cls": {
+            "$ref": "#/components/schemas/DSTencentCLSConfig",
+            "description": "腾讯云 CLS 凭证。`type_ident` 为 `tencent_cls` 时必填。"
           },
           "kafka": {
             "$ref": "#/components/schemas/DSKafkaConfig",
-            "x-flashduty-preserve-absence": true
-          },
-          "loki": {
-            "$ref": "#/components/schemas/DSLokiConfig"
+            "x-flashduty-preserve-absence": true,
+            "description": "`type_ident` 为 `kafka`（仅诊断）时的配置。"
           },
           "mongodb_mongod": {
             "$ref": "#/components/schemas/DSMongoDBConfig",
-            "x-flashduty-preserve-absence": true
+            "x-flashduty-preserve-absence": true,
+            "description": "`type_ident` 为 `mongodb_mongod`（仅诊断）时的配置，字段与 `mongodb_mongos` 相同。"
           },
           "mongodb_mongos": {
             "$ref": "#/components/schemas/DSMongoDBConfig",
-            "x-flashduty-preserve-absence": true
-          },
-          "mysql": {
-            "$ref": "#/components/schemas/DSMySQLConfig"
-          },
-          "oracle": {
-            "$ref": "#/components/schemas/DSOracleConfig"
-          },
-          "postgres": {
-            "$ref": "#/components/schemas/DSPostgresConfig"
-          },
-          "prometheus": {
-            "$ref": "#/components/schemas/DSPrometheusConfig"
+            "x-flashduty-preserve-absence": true,
+            "description": "`type_ident` 为 `mongodb_mongos`（仅诊断）时的配置，字段与 `mongodb_mongod` 相同。"
           },
           "redis_node": {
             "$ref": "#/components/schemas/DSRedisNodeConfig",
-            "x-flashduty-preserve-absence": true
+            "x-flashduty-preserve-absence": true,
+            "description": "`type_ident` 为 `redis_node`（仅诊断）时的配置。"
           },
           "redis_sentinel": {
             "$ref": "#/components/schemas/DSRedisSentinelConfig",
-            "x-flashduty-preserve-absence": true
-          },
-          "sls": {
-            "$ref": "#/components/schemas/DSSLSConfig"
-          },
-          "tencent_cls": {
-            "$ref": "#/components/schemas/DSTencentCLSConfig",
-            "description": "腾讯云 CLS 凭证。`type_ident` 为 `tencent_cls` 时必填。"
-          },
-          "victorialogs": {
-            "$ref": "#/components/schemas/DSVictoriaLogsConfig"
+            "x-flashduty-preserve-absence": true,
+            "description": "`type_ident` 为 `redis_sentinel`（仅诊断）时的配置。"
           }
-        },
-        "type": "object"
+        }
       },
       "DSPostgresConfig": {
         "description": "PostgreSQL 数据源配置。",
@@ -7257,64 +7214,64 @@
         "type": "object"
       },
       "DSPrometheusConfig": {
+        "type": "object",
         "description": "Prometheus 数据源配置，TLS 字段继承自 TLSClientConfig。",
         "properties": {
           "basic_auth_enabled": {
-            "description": "启用 HTTP Basic 认证。",
-            "type": "boolean"
-          },
-          "basic_auth_password": {
-            "description": "Basic 认证密码。",
-            "type": "string"
+            "type": "boolean",
+            "description": "启用 HTTP Basic 认证。"
           },
           "basic_auth_username": {
-            "description": "Basic 认证用户名。",
-            "type": "string"
+            "type": "string",
+            "description": "Basic Auth 用户名，`basic_auth_enabled` 为 `true` 时生效。"
+          },
+          "basic_auth_password": {
+            "type": "string",
+            "description": "Basic Auth 密码，`basic_auth_enabled` 为 `true` 时生效。创建、更新和详情响应会原样返回。"
           },
           "headers": {
-            "description": "自定义 HTTP 请求头，格式为 `Key: Value`。",
+            "type": "array",
             "items": {
               "type": "string"
             },
-            "type": "array"
+            "description": "自定义 HTTP 请求头，格式为 `Key: Value`。"
           },
           "params": {
-            "description": "自定义查询参数，格式为 `key=value`。",
+            "type": "array",
             "items": {
               "type": "string"
             },
-            "type": "array"
+            "description": "自定义查询参数，格式为 `key=value`。"
           },
           "tls_ca": {
-            "description": "PEM 格式的 CA 证书内容，用于校验服务端证书。",
-            "type": "string"
+            "type": "string",
+            "description": "PEM 格式的 CA 证书内容，用于校验服务端证书。"
           },
           "tls_cert": {
-            "description": "PEM 格式的客户端证书内容，用于双向 TLS；须与 `tls_key` 成对配置。",
-            "type": "string"
+            "type": "string",
+            "description": "PEM 格式的客户端证书内容，用于双向 TLS；须与 `tls_key` 成对配置。"
           },
           "tls_key": {
-            "description": "PEM 格式的客户端私钥内容；须与 `tls_cert` 成对配置。",
-            "type": "string"
-          },
-          "tls_max_version": {
-            "description": "最高 TLS 版本，可选 `1.0`、`1.1`、`1.2`、`1.3`；留空表示不限制。",
-            "type": "string"
+            "type": "string",
+            "description": "PEM 格式的客户端私钥内容；须与 `tls_cert` 成对配置。"
           },
-          "tls_min_version": {
-            "description": "最低 TLS 版本，可选 `1.0`、`1.1`、`1.2`、`1.3`；留空表示不限制，且不得高于 `tls_max_version`。",
-            "type": "string"
+          "tls_skip_verify": {
+            "type": "boolean",
+            "description": "是否跳过服务端证书校验（不安全，仅用于自签名场景）。"
           },
           "tls_server_name": {
-            "description": "TLS 握手使用的 SNI / 证书校验主机名；留空时取连接地址中的主机名。",
-            "type": "string"
+            "type": "string",
+            "description": "TLS 握手使用的 SNI / 证书校验主机名；留空时取连接地址中的主机名。"
           },
-          "tls_skip_verify": {
-            "description": "是否跳过服务端证书校验（不安全，仅用于自签名场景）。",
-            "type": "boolean"
+          "tls_min_version": {
+            "type": "string",
+            "description": "最低 TLS 版本，可选 `1.0`、`1.1`、`1.2`、`1.3`；留空表示不限制，且不得高于 `tls_max_version`。"
+          },
+          "tls_max_version": {
+            "type": "string",
+            "description": "最高 TLS 版本，可选 `1.0`、`1.1`、`1.2`、`1.3`；留空表示不限制。"
           }
-        },
-        "type": "object"
+        }
       },
       "DSRedisNodeConfig": {
         "description": "诊断数据源连接配置。",
@@ -7338,7 +7295,7 @@
             "type": "integer"
           },
           "username": {
-            "description": "认证用户名，支持 ${env:NAME} 引用。",
+            "description": "认证用户名，支持 ${env:NAME} 引用。设置后必须同时提供 `password`（更新时省略 `password` 表示保留已保存的密码）。",
             "type": "string"
           }
         },
@@ -7360,7 +7317,7 @@
             "type": "integer"
           },
           "username": {
-            "description": "认证用户名，支持 ${env:NAME} 引用。",
+            "description": "认证用户名，支持 ${env:NAME} 引用。设置后必须同时提供 `password`（更新时省略 `password` 表示保留已保存的密码）。",
             "type": "string"
           }
         },
@@ -7465,42 +7422,72 @@
         "type": "object"
       },
       "DataSourceItem": {
+        "type": "object",
         "description": "单个监控数据源。",
+        "required": [
+          "id",
+          "account_id",
+          "type_ident",
+          "name",
+          "enabled",
+          "note",
+          "address",
+          "edge_cluster_name",
+          "updated_at",
+          "payload",
+          "alerting_enabled",
+          "manage_team_id",
+          "readonly_team_ids",
+          "creator_id"
+        ],
         "properties": {
-          "account_id": {
-            "description": "账户 ID。",
+          "id": {
+            "type": "integer",
             "format": "uint64",
-            "type": "integer"
+            "description": "数据源唯一 ID。用作更新、删除、详情接口的 `id`，以及工具调用接口的 `datasource_id`。"
           },
-          "address": {
-            "description": "连接地址。Prometheus/Loki/VictoriaLogs 为 HTTP URL；MySQL/Oracle/Postgres/ClickHouse 为 `host:port`；SLS 为不含 http/https 前缀的 endpoint。 Redis/MongoDB 诊断类型使用单个 host:port（IPv6 加方括号），不接受 URI、userinfo 或查询参数。Kafka 使用 1–32 个不重复、逗号分隔的 host:port 引导地址；payload 不含 broker 列表。规范化后最多 4096 个字符。",
-            "maxLength": 4096,
-            "type": "string"
+          "account_id": {
+            "type": "integer",
+            "format": "uint64",
+            "description": "数据源所属账户的 ID，恒为调用方所在账户。"
           },
-          "alerting_enabled": {
-            "description": "是否允许告警评估。告警同时要求 enabled=true 且类型支持告警。仅诊断类型固定为 false；false 不阻断非告警查询或工具。",
-            "type": "boolean"
+          "type_ident": {
+            "type": "string",
+            "enum": [
+              "prometheus",
+              "loki",
+              "mysql",
+              "oracle",
+              "postgres",
+              "clickhouse",
+              "elasticsearch",
+              "sls",
+              "tencent_cls",
+              "victorialogs",
+              "redis_node",
+              "redis_sentinel",
+              "mongodb_mongod",
+              "mongodb_mongos",
+              "kafka"
+            ],
+            "description": "数据源类型。\n\n告警类（可用于告警规则评估）：\n- `prometheus`：兼容 Prometheus 的指标数据源。\n- `loki`：Grafana Loki 日志。\n- `mysql`：MySQL。\n- `oracle`：Oracle 数据库。\n- `postgres`：PostgreSQL。\n- `clickhouse`：ClickHouse。\n- `elasticsearch`：Elasticsearch。\n- `sls`：阿里云日志服务（SLS）。\n- `tencent_cls`：腾讯云日志服务（CLS）。\n- `victorialogs`：VictoriaLogs。\n\n仅诊断类（不能用于告警评估，`alerting_enabled` 恒为 `false`）：\n- `redis_node`：单个 Redis 节点。\n- `redis_sentinel`：Redis Sentinel。\n- `mongodb_mongod`：MongoDB mongod 实例。\n- `mongodb_mongos`：MongoDB mongos 路由。\n- `kafka`：Kafka 集群。\n\n存放类型专属配置的 `payload` 键与类型同名。"
           },
-          "edge_cluster_name": {
-            "description": "负责使用该数据源评估规则的 Monitors Edge 集群名称。",
-            "type": "string"
+          "name": {
+            "type": "string",
+            "description": "数据源名称，在账户内唯一（不区分类型）。"
           },
           "enabled": {
-            "description": "是否启用业务执行。停用时拒绝业务查询和工具调用；重新启用不改变 alerting_enabled。",
-            "type": "boolean"
-          },
-          "id": {
-            "description": "唯一数据源 ID。",
-            "format": "uint64",
-            "type": "integer"
-          },
-          "name": {
-            "description": "数据源显示名称。",
-            "type": "string"
+            "type": "boolean",
+            "description": "是否启用业务执行。停用时拒绝业务查询和工具调用；重新启用不改变 alerting_enabled。"
           },
           "note": {
-            "description": "可选描述。",
-            "type": "string"
+            "type": "string",
+            "description": "自由文本备注；未设置时为空字符串。"
+          },
+          "address": {
+            "type": "string",
+            "description": "已保存的连接地址（已规范化）。格式取决于 `type_ident`，各类型格式见创建请求中的 `address` 字段。最长 4096 个字符。",
+            "maxLength": 4096
           },
           "payload": {
             "anyOf": [
@@ -7513,99 +7500,183 @@
             ],
             "description": "类型相关配置块，必须包含与 `type_ident` 匹配的键。`/monit/datasource/list` 响应中恒为 `null`（列表查询不读取 payload 列）；创建/更新/详情响应中会返回。对于 `tencent_cls`，`secret_key` 会被掩码为空字符串，除非其值为 `${env:...}` 引用。 诊断类型的 password 和 Kafka tls_key 在响应中省略，${env:...} 引用除外；更新时省略保留已保存的秘密，显式空字符串清除。其他配置字段保持原有行为。"
           },
-          "type_ident": {
-            "description": "数据源类型标识。支持：`prometheus`, `loki`, `mysql`, `oracle`, `postgres`, `clickhouse`, `elasticsearch`, `sls`, `tencent_cls`, `victorialogs`, `redis_node`, `redis_sentinel`, `mongodb_mongod`, `mongodb_mongos`, `kafka`。",
-            "type": "string"
+          "edge_cluster_name": {
+            "type": "string",
+            "description": "负责使用该数据源评估规则的 Monitors Edge 集群名称。"
           },
           "updated_at": {
-            "description": "最后更新时间，Unix 时间戳（秒）。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "最后更新时间，Unix 时间戳（秒）。"
+          },
+          "alerting_enabled": {
+            "description": "是否允许告警评估。告警同时要求 enabled=true 且类型支持告警。仅诊断类型固定为 false；false 不阻断非告警查询或工具。",
+            "type": "boolean"
+          },
+          "manage_team_id": {
+            "type": [
+              "integer",
+              "null"
+            ],
+            "format": "uint64",
+            "description": "负责团队 ID。该团队成员可以编辑、删除、启停该数据源并查看其完整配置。`null` 表示未指定负责团队：任何拥有“数据源管理”权限的调用方都可管理。创建者、账户所有者和管理员始终可管理。"
+          },
+          "readonly_team_ids": {
+            "type": [
+              "array",
+              "null"
+            ],
+            "items": {
+              "type": "integer",
+              "format": "uint64"
+            },
+            "description": "允许查询和引用该数据源的团队 ID 列表（负责团队、创建者、账户所有者和管理员始终可查询）。`null` 或空数组表示账户内所有成员都可查询。"
+          },
+          "creator_id": {
+            "type": [
+              "integer",
+              "null"
+            ],
+            "format": "uint64",
+            "description": "创建该数据源的成员 ID；未记录时为 `null`。创建者始终可管理该数据源。"
+          },
+          "my_perm": {
+            "type": "string",
+            "enum": [
+              "manage",
+              "readonly"
+            ],
+            "description": "调用方对该数据源的权限级别，仅出现在列表响应中。\n- `manage`：可编辑、删除、启停、查看配置并查询。\n- `readonly`：只能查询和引用，不能修改或查看配置。"
           }
-        },
-        "required": [
-          "id",
-          "account_id",
-          "type_ident",
-          "name",
-          "enabled",
-          "note",
-          "address",
-          "edge_cluster_name",
-          "updated_at",
-          "payload",
-          "alerting_enabled"
-        ],
-        "type": "object"
+        }
       },
       "DataSourceListRequest": {
+        "type": "object",
         "description": "查询数据源列表的过滤参数。",
         "properties": {
           "type": {
-            "description": "数据源类型标识。省略时返回全部类型。支持：`prometheus`, `loki`, `mysql`, `oracle`, `postgres`, `clickhouse`, `elasticsearch`, `sls`, `tencent_cls`, `victorialogs`, `redis_node`, `redis_sentinel`, `mongodb_mongod`, `mongodb_mongos`, `kafka`。",
-            "type": "string"
+            "type": "string",
+            "description": "仅返回该类型的数据源；省略或留空返回所有类型。无法识别的值不匹配任何数据源，返回空数组。\n\n告警类（可用于告警规则评估）：\n- `prometheus`：兼容 Prometheus 的指标数据源。\n- `loki`：Grafana Loki 日志。\n- `mysql`：MySQL。\n- `oracle`：Oracle 数据库。\n- `postgres`：PostgreSQL。\n- `clickhouse`：ClickHouse。\n- `elasticsearch`：Elasticsearch。\n- `sls`：阿里云日志服务（SLS）。\n- `tencent_cls`：腾讯云日志服务（CLS）。\n- `victorialogs`：VictoriaLogs。\n\n仅诊断类（不能用于告警评估，`alerting_enabled` 恒为 `false`）：\n- `redis_node`：单个 Redis 节点。\n- `redis_sentinel`：Redis Sentinel。\n- `mongodb_mongod`：MongoDB mongod 实例。\n- `mongodb_mongos`：MongoDB mongos 路由。\n- `kafka`：Kafka 集群。",
+            "enum": [
+              "prometheus",
+              "loki",
+              "mysql",
+              "oracle",
+              "postgres",
+              "clickhouse",
+              "elasticsearch",
+              "sls",
+              "tencent_cls",
+              "victorialogs",
+              "redis_node",
+              "redis_sentinel",
+              "mongodb_mongod",
+              "mongodb_mongos",
+              "kafka"
+            ]
+          },
+          "name": {
+            "type": "string",
+            "description": "仅返回名称与该值完全相等的数据源（名称在账户内唯一，因此最多一条）。省略或留空表示不按名称过滤。"
           }
-        },
-        "type": "object"
+        }
       },
       "DataSourceListResponse": {
-        "description": "数据源列表。本接口不读取 payload 列，因此每项的 `payload` 均为 `null`。",
+        "type": "array",
+        "description": "账户下调用方有权查询的数据源，按名称排序；没有匹配项时为空数组。列表不读取 `payload`，因此每项的 `payload` 均为 `null`；每项另带 `my_perm`。",
         "items": {
           "$ref": "#/components/schemas/DataSourceItem"
-        },
-        "type": "array"
+        }
       },
       "DataSourceUpsertRequest": {
-        "description": "创建或更新数据源的请求体。`id` 仅在更新时必填。`address` 除 Elasticsearch `deployment=cloud` 外均为必填。",
+        "type": "object",
+        "description": "创建或更新数据源的请求体。`id` 仅更新时必填，创建时忽略。更新会用请求中的值整体替换 `type_ident`、`name`、`note`、`address`、`payload` 和 `edge_cluster_name`，因此必须全部重新发送；仅 `enabled`、`alerting_enabled`、`manage_team_id`、`readonly_team_ids` 在省略时保持原值。除 `deployment=cloud` 的 Elasticsearch 外，`address` 对所有类型必填。",
+        "required": [
+          "type_ident",
+          "name",
+          "edge_cluster_name",
+          "payload"
+        ],
         "properties": {
+          "id": {
+            "type": "integer",
+            "format": "uint64",
+            "description": "数据源 ID。更新时必填（ID 不存在或属于其他账户时返回 `ResourceNotFound`）；创建时忽略。"
+          },
+          "type_ident": {
+            "type": "string",
+            "enum": [
+              "prometheus",
+              "loki",
+              "mysql",
+              "oracle",
+              "postgres",
+              "clickhouse",
+              "elasticsearch",
+              "sls",
+              "tencent_cls",
+              "victorialogs",
+              "redis_node",
+              "redis_sentinel",
+              "mongodb_mongod",
+              "mongodb_mongos",
+              "kafka"
+            ],
+            "description": "数据源类型。\n\n告警类（可用于告警规则评估）：\n- `prometheus`：兼容 Prometheus 的指标数据源。\n- `loki`：Grafana Loki 日志。\n- `mysql`：MySQL。\n- `oracle`：Oracle 数据库。\n- `postgres`：PostgreSQL。\n- `clickhouse`：ClickHouse。\n- `elasticsearch`：Elasticsearch。\n- `sls`：阿里云日志服务（SLS）。\n- `tencent_cls`：腾讯云日志服务（CLS）。\n- `victorialogs`：VictoriaLogs。\n\n仅诊断类（不能用于告警评估，`alerting_enabled` 恒为 `false`）：\n- `redis_node`：单个 Redis 节点。\n- `redis_sentinel`：Redis Sentinel。\n- `mongodb_mongod`：MongoDB mongod 实例。\n- `mongodb_mongos`：MongoDB mongos 路由。\n- `kafka`：Kafka 集群。\n\n存放类型专属配置的 `payload` 键与类型同名。"
+          },
+          "name": {
+            "type": "string",
+            "description": "数据源名称；必填，在账户内唯一（不区分类型），即查询接口中的 `ds_name`。重名时返回 `InvalidParameter`。"
+          },
+          "note": {
+            "type": "string",
+            "description": "自由文本备注。更新时省略或传空字符串会清空已保存的备注。"
+          },
           "address": {
-            "description": "连接地址。除 `elasticsearch` 的 `deployment: cloud` 部署外均为必填。Prometheus/Loki/VictoriaLogs 为 HTTP URL；MySQL/Oracle/Postgres/ClickHouse 为 `host:port`；SLS 为不含 `http(s)://` 前缀的 endpoint；`tencent_cls` 必须为 `cls.tencentcloudapi.com` 或 `cls.internal.tencentcloudapi.com`（要求 Monitors edge >= v0.66.0）。 Redis/MongoDB 诊断类型使用单个 host:port（IPv6 加方括号），不接受 URI、userinfo 或查询参数。Kafka 使用 1–32 个不重复、逗号分隔的 host:port 引导地址；payload 不含 broker 列表。规范化后最多 4096 个字符。",
-            "maxLength": 4096,
-            "type": "string"
+            "type": "string",
+            "description": "连接地址；除 `deployment: cloud` 的 `elasticsearch` 外，所有类型都必填。规范化后最长 4096 个字符。各类型格式：\n- `prometheus`、`loki`、`victorialogs`：HTTP URL；不以 `http` 开头时自动补 `http://`。\n- `mysql`、`oracle`、`postgres`：`host:port`。\n- `clickhouse`：一个或多个以逗号分隔的 `host:port`，重复地址会被拒绝。\n- `self-managed` 的 `elasticsearch`：一个或多个以逗号分隔的 HTTP(S) URL（缺省协议为 `http://`），各 URL 的查询参数必须一致，重复地址会被拒绝；`cloud` 部署无需填写。\n- `sls`：不带 `http://` 或 `https://` 前缀的 endpoint。\n- `tencent_cls`：只能是 `cls.tencentcloudapi.com` 或 `cls.internal.tencentcloudapi.com`（要求 Monitors edge >= v0.66.0）。\n- `redis_node`、`redis_sentinel`、`mongodb_mongod`、`mongodb_mongos`：单个 `host:port`（IPv6 须加方括号），不能含 URI、用户信息或查询串。\n- `kafka`：1-32 个互不重复、以逗号分隔的 `host:port` 引导地址（payload 中没有 broker 列表）。",
+            "maxLength": 4096
           },
-          "alerting_enabled": {
-            "description": "是否允许数据源用于告警。创建时省略：支持告警的类型默认为 true，仅诊断类型默认为 false；更新时省略保留当前值。null 非法。redis_node、redis_sentinel、mongodb_mongod、mongodb_mongos 和 kafka 不允许 true。有启用规则引用时，关闭用途返回冲突。",
-            "type": "boolean",
-            "x-flashduty-preserve-absence": true
+          "payload": {
+            "$ref": "#/components/schemas/DSPayload",
+            "description": "类型专属配置块，必须包含与 `type_ident` 同名的键。更新会整体替换 payload，需要保留的配置（包括非诊断类型的凭据，可通过详情接口读取）都要重新发送。例外：诊断类型省略密码（以及 Kafka 的 `tls_key`）表示保留已保存的值，传空字符串表示清除；`tencent_cls` 省略或传空的 `secret_key` 表示保留已保存的密钥。修改 `type_ident` 时不会沿用已保存的密钥。"
           },
           "edge_cluster_name": {
-            "description": "负责使用该数据源评估规则的 Monitors Edge 集群名称。",
-            "type": "string"
+            "type": "string",
+            "description": "负责评估规则和执行查询的 Monitors edge 集群名称，必须是账户下已存在的 edge 集群，否则返回 `InvalidParameter`。更新时修改该值会关闭使用此数据源的规则上的未恢复告警。"
           },
           "enabled": {
+            "type": "boolean",
             "description": "是否启用业务执行。创建时省略默认为 true；更新时省略保留当前值。显式 false 停用执行；null 非法。不改变 alerting_enabled。",
+            "x-flashduty-preserve-absence": true
+          },
+          "alerting_enabled": {
+            "description": "是否允许数据源用于告警。创建时省略：支持告警的类型默认为 true，仅诊断类型默认为 false；更新时省略保留当前值。null 非法。redis_node、redis_sentinel、mongodb_mongod、mongodb_mongos 和 kafka 不允许 true。有启用规则引用时，关闭用途返回冲突。",
             "type": "boolean",
             "x-flashduty-preserve-absence": true
           },
-          "id": {
-            "description": "数据源 ID。更新时必填，创建时省略。",
+          "manage_team_id": {
+            "type": [
+              "integer",
+              "null"
+            ],
             "format": "uint64",
-            "type": "integer"
-          },
-          "name": {
-            "description": "数据源显示名称，查询与诊断接口中的 `ds_name` 引用的就是这个名称。",
-            "type": "string"
-          },
-          "note": {
-            "description": "可选描述。",
-            "type": "string"
-          },
-          "payload": {
-            "$ref": "#/components/schemas/DSPayload",
-            "description": "类型相关配置块，必须包含与 `type_ident` 匹配的键。 诊断类型的 password 和 Kafka tls_key 在响应中省略，${env:...} 引用除外；更新时省略保留已保存的秘密，显式空字符串清除。其他配置字段保持原有行为。"
+            "description": "负责团队 ID（含义见响应中的同名字段）。创建时省略表示不指定负责团队；更新时省略保持原值，传 `null` 或 `0` 表示清除。`readonly_team_ids` 非空时必须填写。",
+            "x-flashduty-preserve-absence": true
           },
-          "type_ident": {
-            "description": "数据源类型标识。支持：`prometheus`, `loki`, `mysql`, `oracle`, `postgres`, `clickhouse`, `elasticsearch`, `sls`, `tencent_cls`, `victorialogs`, `redis_node`, `redis_sentinel`, `mongodb_mongod`, `mongodb_mongos`, `kafka`。",
-            "type": "string"
+          "readonly_team_ids": {
+            "type": [
+              "array",
+              "null"
+            ],
+            "items": {
+              "type": "integer",
+              "format": "uint64"
+            },
+            "description": "允许查询和引用该数据源的团队 ID 列表（含义见响应中的同名字段）。创建时省略表示不限制；更新时省略保持原值，传 `null` 或空数组表示清除（所有人可查询）。重复值和 `0` 会被去掉。依赖 `manage_team_id`：列表非空而未指定负责团队时返回 `InvalidParameter`。",
+            "x-flashduty-preserve-absence": true
           }
-        },
-        "required": [
-          "type_ident",
-          "name",
-          "edge_cluster_name",
-          "payload"
-        ],
-        "type": "object"
+        }
       },
       "DatasourceQueryExecution": {
         "type": "object",
@@ -7967,7 +8038,7 @@
             "type": "integer"
           },
           "datasource_id": {
-            "description": "通过 /monit/datasource/list 获取的数据源 ID。",
+            "description": "要执行工具的数据源 ID，可从 `/monit/datasource/list` 获取。调用方需要拥有该数据源的查询权限。查询工具（`<type>.query`）的 ID 不能超过 9007199254740991。",
             "format": "uint64",
             "minimum": 1,
             "type": "integer"
@@ -8030,7 +8101,7 @@
       "DatasourceToolTruncation": {
         "properties": {
           "reason": {
-            "description": "结果截断原因；该对象存在即表示发生截断。",
+            "description": "结果被截断的原因，由执行端 Edge 给出，请当作不透明字符串处理。仅当结果被截断时才返回该对象。",
             "type": "string"
           }
         },
@@ -8080,17 +8151,17 @@
         "type": "object"
       },
       "DeletePostMortemTemplateRequest": {
+        "type": "object",
         "description": "删除故障复盘模板的参数。",
-        "properties": {
-          "template_id": {
-            "description": "模板 ID，可通过 `POST /incident/post-mortem/template/list` 获取。",
-            "type": "string"
-          }
-        },
         "required": [
           "template_id"
         ],
-        "type": "object"
+        "properties": {
+          "template_id": {
+            "type": "string",
+            "description": "要删除的自定义模板 ID，可从 `POST /incident/post-mortem/template/list` 获取。"
+          }
+        }
       },
       "DeleteStatusPageChangeRequest": {
         "description": "删除状态页事件所需的参数。",
@@ -8226,44 +8297,52 @@
         "type": "object"
       },
       "DeleteWarRoomRequest": {
+        "type": "object",
         "description": "删除故障战情室的参数。",
+        "required": [
+          "incident_id",
+          "integration_id"
+        ],
         "properties": {
           "incident_id": {
-            "description": "故障 ID（MongoDB ObjectID）。",
+            "type": "string",
             "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
+            "description": "故障 ID（MongoDB ObjectID）。"
           },
           "integration_id": {
-            "description": "IM 集成 ID，可通过 `POST /datasource/im/war-room-enabled/list` 获取。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "IM 集成 ID，可通过 `POST /datasource/im/war-room-enabled/list` 获取。"
+          },
+          "unlink_only": {
+            "type": "boolean",
+            "description": "为 true 时只解除故障与作战室的关联，不解散群组。仅限账户所有者和管理员，仅在 IM 集成已禁用或已删除时可用，且必须传 `chat_id`。"
+          },
+          "chat_id": {
+            "type": "string",
+            "description": "要解除关联的作战室群 ID，取自 `POST /incident/war-room/list`。`unlink_only` 为 `true` 时必填，且必须与当前作战室一致；其他情况忽略。"
           }
-        },
-        "required": [
-          "incident_id",
-          "integration_id"
-        ],
-        "type": "object"
+        }
       },
       "DeleteWorkItemRequest": {
+        "type": "object",
         "description": "软删除跟进事项的参数。",
-        "properties": {
-          "version": {
-            "description": "事项当前版本号，用于乐观锁。必须与存储的版本一致。",
-            "format": "int64",
-            "type": "integer"
-          },
-          "work_item_id": {
-            "description": "跟进事项 ID（不透明字符串，最长 128 字符）。",
-            "maxLength": 128,
-            "type": "string"
-          }
-        },
         "required": [
           "work_item_id",
           "version"
         ],
-        "type": "object"
+        "properties": {
+          "work_item_id": {
+            "type": "string",
+            "maxLength": 128,
+            "description": "跟进事项 ID（不透明字符串，最长 128 字符）。"
+          },
+          "version": {
+            "type": "integer",
+            "format": "int64",
+            "description": "事项当前的 `version`（≥ 1），用于乐观锁。"
+          }
+        }
       },
       "DimensionInsightItem": {
         "allOf": [
@@ -8384,16 +8463,16 @@
         ]
       },
       "DimensionInsightResponse": {
+        "type": "object",
         "properties": {
           "items": {
-            "description": "按接口维度（账户/团队/协作空间）聚合的洞察指标行；启用 `split_hours` 或 `aggregate_unit` 时会进一步按时段或时间桶拆分。",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/DimensionInsightItem"
             },
-            "type": "array"
+            "description": "指标行，按时间桶从新到旧排列。没有故障的时间桶或维度取值不产生行；空数组表示没有匹配的故障。"
           }
-        },
-        "type": "object"
+        }
       },
       "DisableIncidentMergeRequest": {
         "description": "禁用故障自动合并的参数。",
@@ -8434,25 +8513,29 @@
         "type": "object"
       },
       "DoIncidentCustomActionResponse": {
-        "description": "自定义操作的执行结果。",
+        "type": [
+          "object",
+          "null"
+        ],
+        "description": "操作的 HTTP 请求成功时为 `null`；失败时为包含 `message` 的对象。",
         "properties": {
           "message": {
-            "description": "HTTP 调用失败时的错误信息，成功时不返回。",
-            "type": "string"
+            "type": "string",
+            "description": "请求操作地址时返回的错误（例如 2 秒超时）。"
           }
-        },
-        "type": "object"
+        }
       },
       "DutyError": {
+        "type": "object",
         "description": "响应结构中的错误 payload，仅在非 2xx 响应时出现。",
         "properties": {
           "code": {
             "$ref": "#/components/schemas/ErrorCode"
           },
           "message": {
-            "description": "用户可读的错误描述，语言会跟随调用方的 Accept-Language。可能包含字段名、ID 等请求上下文。",
-            "example": "The specified parameter template_id is not valid.",
-            "type": "string"
+            "type": "string",
+            "description": "按响应语言（query 参数 `locale` / `lang` 或请求头 `Accept-Language`）返回的错误描述，可能包含出错的字段名，请不要解析它。",
+            "example": "The specified parameter template_id is not valid."
           },
           "reason": {
             "description": "可选的机器可读拒绝原因，包含数据源工具错误；结合 HTTP 状态及 code 判断。",
@@ -8463,8 +8546,7 @@
         "required": [
           "code",
           "message"
-        ],
-        "type": "object"
+        ]
       },
       "EmptyObject": {
         "additionalProperties": false,
@@ -8477,62 +8559,62 @@
         "type": "object"
       },
       "EmptyResponse": {
-        "description": "空响应体。成功时服务端返回 `data: null`。",
-        "properties": {},
-        "type": "object"
+        "type": "object",
+        "description": "无返回数据。不同接口的 `data` 可能是 `{}`，也可能不出现在响应中；请只根据 HTTP 200 且没有 `error` 判断成功。",
+        "properties": {}
       },
       "EnabledTime": {
+        "type": "object",
         "description": "规则激活时间窗口。",
         "properties": {
           "days": {
-            "description": "星期几，0 = 周日。",
+            "type": "array",
             "items": {
               "type": "integer"
             },
-            "type": "array"
-          },
-          "etime": {
-            "description": "结束时间，如 `18:00`。",
-            "type": "string"
+            "description": "时间窗口适用的星期，`0` = 周日至 `6` = 周六；不能为空，不能重复。"
           },
           "stime": {
-            "description": "起始时间，如 `09:00`。",
-            "type": "string"
+            "type": "string",
+            "description": "开始时间，24 小时制 `HH:MM` 格式，如 `09:00`。"
+          },
+          "etime": {
+            "type": "string",
+            "description": "结束时间，24 小时制 `HH:MM` 格式，如 `18:00`。"
           }
-        },
-        "type": "object"
+        }
       },
       "EnrichFilter": {
+        "type": "object",
+        "required": [
+          "key",
+          "oper",
+          "vals"
+        ],
         "description": "单个标签过滤条件。",
         "properties": {
           "key": {
-            "description": "要匹配的事件键（如 `labels.severity`、`title`），不能为空。",
-            "minLength": 1,
-            "type": "string"
+            "type": "string",
+            "description": "要匹配的事件键：`title`、`description`、`labels.<name>` 或其他告警 / 变更事件键。`labels.<name>` 中的标签名须合法。",
+            "minLength": 1
           },
           "oper": {
-            "description": "匹配操作符。`IN` 表示任一值匹配即通过；`NOTIN` 表示所有值均不匹配时通过。",
+            "type": "string",
             "enum": [
               "IN",
               "NOTIN"
             ],
-            "type": "string"
+            "description": "匹配操作符。\n- `IN`：键的值匹配 `vals` 中任意一个即命中；事件中不存在该键时不命中。\n- `NOTIN`：键的值不匹配 `vals` 中任何一个即命中；事件中不存在该键时总是命中。"
           },
           "vals": {
-            "description": "匹配值列表，至少包含 1 个。",
+            "type": "array",
             "items": {
               "type": "string"
             },
-            "minItems": 1,
-            "type": "array"
+            "description": "要匹配的值（至少一个）。每个值可以是：精确字符串；`/regex/` 形式的正则表达式；含 `*`、`?` 的通配符；`cidr:<CIDR>`（如 `cidr:203.0.113.0/24`）表示 IP 网段；`num:lt:<n>`、`num:le:<n>`、`num:gt:<n>`、`num:ge:<n>` 表示数值比较。",
+            "minItems": 1
           }
-        },
-        "required": [
-          "key",
-          "oper",
-          "vals"
-        ],
-        "type": "object"
+        }
       },
       "EnrichRule": {
         "description": "带可选条件的富化规则，包含特定类型配置。",
@@ -8605,52 +8687,53 @@
         "type": "object"
       },
       "EnrichmentItem": {
+        "type": "object",
         "description": "集成的富化规则集。",
         "properties": {
-          "created_at": {
-            "description": "创建时间，Unix 时间戳（秒）。",
-            "format": "int64",
-            "type": "integer"
-          },
-          "creator_id": {
-            "description": "创建者成员 ID。",
-            "format": "int64",
-            "type": "integer"
-          },
-          "deleted_at": {
-            "description": "删除时间，Unix 时间戳（秒）。规则集未删除时省略；读取接口不会返回已软删除的规则集，因此实际上始终省略。",
-            "format": "int64",
-            "type": "integer"
-          },
           "integration_id": {
-            "description": "集成 ID。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "该规则集所属集成的 ID；每个集成最多一个规则集。"
           },
           "rules": {
-            "description": "有序富化规则列表。",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/EnrichRule"
             },
-            "type": "array"
+            "description": "按执行顺序排列的规则；后面的规则能看到前面规则写入的标签。"
           },
           "status": {
-            "description": "规则集状态：`enabled`（生效）或 `deleted`（已软删除）。读取接口会过滤软删除的规则集，响应中始终为 `enabled`。",
+            "type": "string",
             "enum": [
               "enabled",
               "deleted"
             ],
-            "type": "string"
+            "description": "规则集状态：`enabled`（生效）或 `deleted`（已软删除）。读取接口会过滤软删除的规则集，响应中始终为 `enabled`。"
+          },
+          "updated_by": {
+            "type": "integer",
+            "format": "int64",
+            "description": "最后更新者成员 ID。"
+          },
+          "creator_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "创建者成员 ID。"
+          },
+          "created_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "创建时间，Unix 时间戳（秒）。"
           },
           "updated_at": {
-            "description": "最后更新时间，Unix 时间戳（秒）。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "最后更新时间，Unix 时间戳（秒）。"
           },
-          "updated_by": {
-            "description": "最后更新者成员 ID。",
+          "deleted_at": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "删除时间，Unix 时间戳（秒）。规则集未删除时省略；读取接口不会返回已软删除的规则集，因此实际上始终省略。"
           }
         },
         "required": [
@@ -8661,8 +8744,7 @@
           "creator_id",
           "created_at",
           "updated_at"
-        ],
-        "type": "object"
+        ]
       },
       "EnrichmentListRequest": {
         "properties": {
@@ -8697,67 +8779,74 @@
         "type": "object"
       },
       "EnrichmentUpsertRequest": {
+        "type": "object",
+        "required": [
+          "integration_id",
+          "rules"
+        ],
         "properties": {
           "integration_id": {
-            "description": "待配置富化规则的集成 ID。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "待配置富化规则的集成 ID。"
           },
           "rules": {
-            "description": "富化规则有序列表，将原子替换现有全部规则。",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/EnrichRule"
             },
-            "type": "array"
+            "description": "有序的规则列表，整体替换该集成的规则集；传 `[]` 可删除全部规则。规则按此顺序执行。"
           }
-        },
-        "required": [
-          "integration_id",
-          "rules"
-        ],
-        "type": "object"
+        }
       },
       "EnvironmentBinding": {
-        "description": "会话绑定的 runner 或云沙箱。首条消息前为 null。",
+        "type": "object",
+        "description": "会话绑定的 runner 或云沙箱。仅 `POST /safari/session/get` 返回；会话绑定前（首条消息之前）不返回。",
         "properties": {
-          "id": {
-            "description": "环境标识：`cloud` 绑定为云沙箱 ID，`byoc` 绑定为 runner/环境 ID。",
-            "type": "string"
-          },
           "kind": {
+            "type": "string",
             "description": "会话当前绑定的环境类型：`cloud`（托管沙箱）或 `byoc`（自建 runner）。",
             "enum": [
               "cloud",
               "byoc"
-            ],
-            "type": "string"
+            ]
+          },
+          "id": {
+            "type": "string",
+            "description": "环境标识：`cloud` 绑定为云沙箱 ID，`byoc` 绑定为 runner/环境 ID。"
           },
           "name": {
-            "description": "可读的环境名称；cloud 绑定使用默认允许列表时为空。",
-            "type": "string"
+            "type": "string",
+            "description": "可读的环境名称；cloud 绑定使用默认允许列表时为空。"
+          },
+          "team_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "绑定环境所属团队；账户级环境为 0。"
           },
           "status": {
-            "description": "绑定的实时健康状态，按类型分命名空间：BYOC 使用 online/pending/offline/deleted；cloud 使用 available/rebuilding/expired。",
+            "type": "string",
+            "description": "绑定的实时健康状态。未知时不返回。\n\n`byoc`：\n- `online`：runner 已连接且就绪\n- `degraded`：runner 已连接但执行器不健康；仍可发送消息\n- `pending`：runner 从未连接过\n- `offline`：runner 心跳丢失，无法处理消息\n- `deleted`：环境已不存在，需另选环境\n\n`cloud`：\n- `available`：沙箱可处理下一条消息（暂停或启动中的沙箱会自动恢复）\n- `rebuilding`：沙箱正在恢复或重建\n- `expired`：沙箱已永久失败，无法自行恢复\n- `deleted`：所选的云环境模板已被删除",
             "enum": [
               "online",
+              "degraded",
               "pending",
               "offline",
               "deleted",
               "available",
               "rebuilding",
               "expired"
-            ],
-            "type": "string"
+            ]
           }
         },
         "required": [
           "kind",
           "id"
-        ],
-        "type": "object"
+        ]
       },
       "ErrorCode": {
-        "description": "Flashduty 错误码枚举。每个失败响应的 `error.code` 都是下列稳定值之一，HTTP 状态码仅作参考。\n\n| 错误码 | HTTP | 含义 |\n|---|---|---|\n| `OK` | 200 | 保留值，正常错误响应不会返回。 |\n| `InvalidParameter` | 400 | 必填参数缺失或未通过校验。 |\n| `BadRequest` | 400 | 通用的 400 错误，通常是请求本身不合法。 |\n| `InvalidContentType` | 400 | 请求头 `Content-Type` 不是 `application/json`。 |\n| `ResourceNotFound` | 400 | 目标资源不存在。注意 HTTP 状态码是 400 而非 404（历史设计）。 |\n| `NoLicense` | 400 | 功能需要有效授权，但未找到可用的 license。 |\n| `ReferenceExist` | 400 | 该资源仍被其他实体引用，无法删除。 |\n| `Unauthorized` | 401 | `app_key` 缺失、无效或已过期。 |\n| `BalanceNotEnough` | 402 | 账户余额不足，无法执行需要计费的操作。 |\n| `AccessDenied` | 403 | 身份认证通过，但 RBAC 权限不足以执行该操作。 |\n| `RouteNotFound` | 404 | 请求的 URL 路径不是已知路由。 |\n| `MethodNotAllowed` | 405 | 当前路径不接受所使用的 HTTP 方法。 |\n| `UndonedOrderExist` | 409 | 账户存在未完成的订单，请稍后重试。 |\n| `RequestLocked` | 423 | 因连续失败被临时锁定。 |\n| `EntityTooLarge` | 413 | 请求体超过允许的最大长度。 |\n| `RequestTooFrequently` | 429 | 命中限流（全局、账户级或集成级）。 |\n| `RequestVerifyRequired` | 428 | 操作需要二次验证码，但未提供。 |\n| `DangerousOperation` | 428 | 危险操作，需要进行 MFA 验证。 |\n| `InternalError` | 500 | 服务端未预期错误。反馈问题请附上 `request_id`。 |\n| `ServiceUnavailable` | 503 | 后端依赖不可用，请稍后重试。 |",
+        "type": "string",
+        "description": "错误码。所有失败响应都会把 `error.code` 设为下列稳定字符串之一，请以它而不是 HTTP 状态码做判断。\n\n| 错误码 | HTTP | 含义 |\n|---|---|---|\n| `OK` | 200 | 保留值，失败的请求不会返回。 |\n| `InvalidParameter` | 400 | 参数缺失、类型错误或未通过校验，`message` 通常会指出字段名。 |\n| `BadRequest` | 400 | 请求违反业务规则或与对象当前状态冲突，`message` 会说明原因。 |\n| `InvalidContentType` | 400 | 请求体没有以 `application/json` 发送。 |\n| `ResourceNotFound` | 400 | 引用的对象在本账户中不存在或已删除。注意 HTTP 状态码是 400 而不是 404。 |\n| `NoLicense` | 400 | 账户套餐不包含该功能、套餐配额已用完、套餐已过期或额度不足。 |\n| `ReferenceExist` | 400 | 对象仍被其他对象引用，无法删除。 |\n| `Unauthorized` | 401 | APP Key 缺失、无效或已删除。 |\n| `BalanceNotEnough` | 402 | 仅用于控制台计费流程，Open API 接口不会返回。 |\n| `AccessDenied` | 403 | APP Key 的权限范围或创建者角色不允许该操作或该对象。 |\n| `RouteNotFound` | 404 | 没有与该 HTTP 方法和路径匹配的接口。 |\n| `MethodNotAllowed` | 405 | 路径存在，但不支持该 HTTP 方法。 |\n| `UndonedOrderExist` | 409 | 仅用于控制台计费流程，Open API 接口不会返回。 |\n| `EntityTooLarge` | 413 | 请求体超出大小限制。 |\n| `RequestLocked` | 423 | 仅用于控制台登录保护，Open API 接口不会返回。 |\n| `RequestVerifyRequired` | 428 | 仅用于控制台验证码流程，Open API 接口不会返回。 |\n| `DangerousOperation` | 428 | 仅用于控制台高风险操作的 MFA 校验，Open API 接口不会返回。 |\n| `RequestTooFrequently` | 429 | 触发频率限制；请等待响应头 `Flashcat-Request-Rate-Limit-Delay` 给出的秒数后再重试。 |\n| `InternalError` | 500 | 服务端意外错误；请退避后重试，反馈问题时附上 `request_id`。 |\n| `ServiceUnavailable` | 503 | 后端依赖过载或不可用，请退避后重试。 |",
         "enum": [
           "OK",
           "InvalidParameter",
@@ -8772,38 +8861,37 @@
           "RouteNotFound",
           "MethodNotAllowed",
           "UndonedOrderExist",
-          "RequestLocked",
           "EntityTooLarge",
-          "RequestTooFrequently",
+          "RequestLocked",
           "RequestVerifyRequired",
           "DangerousOperation",
+          "RequestTooFrequently",
           "InternalError",
           "ServiceUnavailable"
         ],
-        "example": "InvalidParameter",
-        "type": "string",
         "x-enumDescriptions": {
-          "AccessDenied": "身份认证通过，但 RBAC 权限不足以执行该操作。",
-          "BadRequest": "通用的 400 错误，通常是请求本身不合法。",
-          "BalanceNotEnough": "账户余额不足，无法执行需要计费的操作。",
-          "DangerousOperation": "危险操作，需要进行 MFA 验证。",
-          "EntityTooLarge": "请求体超过允许的最大长度。",
-          "InternalError": "服务端未预期错误。反馈问题请附上 `request_id`。",
-          "InvalidContentType": "请求头 `Content-Type` 不是 `application/json`。",
-          "InvalidParameter": "必填参数缺失或未通过校验。",
-          "MethodNotAllowed": "当前路径不接受所使用的 HTTP 方法。",
-          "NoLicense": "功能需要有效授权，但未找到可用的 license。",
-          "OK": "保留值，正常错误响应不会返回。",
-          "ReferenceExist": "该资源仍被其他实体引用，无法删除。",
-          "RequestLocked": "因连续失败被临时锁定。",
-          "RequestTooFrequently": "命中限流（全局、账户级或集成级）。",
-          "RequestVerifyRequired": "操作需要二次验证码，但未提供。",
-          "ResourceNotFound": "目标资源不存在。注意 HTTP 状态码是 400 而非 404（历史设计）。",
-          "RouteNotFound": "请求的 URL 路径不是已知路由。",
-          "ServiceUnavailable": "后端依赖不可用，请稍后重试。",
-          "Unauthorized": "`app_key` 缺失、无效或已过期。",
-          "UndonedOrderExist": "账户存在未完成的订单，请稍后重试。"
-        }
+          "OK": "保留值，失败的请求不会返回。",
+          "InvalidParameter": "参数缺失、类型错误或未通过校验，`message` 通常会指出字段名。",
+          "BadRequest": "请求违反业务规则或与对象当前状态冲突，`message` 会说明原因。",
+          "InvalidContentType": "请求体没有以 `application/json` 发送。",
+          "ResourceNotFound": "引用的对象在本账户中不存在或已删除。注意 HTTP 状态码是 400 而不是 404。",
+          "NoLicense": "账户套餐不包含该功能、套餐配额已用完、套餐已过期或额度不足。",
+          "ReferenceExist": "对象仍被其他对象引用，无法删除。",
+          "Unauthorized": "APP Key 缺失、无效或已删除。",
+          "BalanceNotEnough": "仅用于控制台计费流程，Open API 接口不会返回。",
+          "AccessDenied": "APP Key 的权限范围或创建者角色不允许该操作或该对象。",
+          "RouteNotFound": "没有与该 HTTP 方法和路径匹配的接口。",
+          "MethodNotAllowed": "路径存在，但不支持该 HTTP 方法。",
+          "UndonedOrderExist": "仅用于控制台计费流程，Open API 接口不会返回。",
+          "EntityTooLarge": "请求体超出大小限制。",
+          "RequestLocked": "仅用于控制台登录保护，Open API 接口不会返回。",
+          "RequestVerifyRequired": "仅用于控制台验证码流程，Open API 接口不会返回。",
+          "DangerousOperation": "仅用于控制台高风险操作的 MFA 校验，Open API 接口不会返回。",
+          "RequestTooFrequently": "触发频率限制；请等待响应头 `Flashcat-Request-Rate-Limit-Delay` 给出的秒数后再重试。",
+          "InternalError": "服务端意外错误；请退避后重试，反馈问题时附上 `request_id`。",
+          "ServiceUnavailable": "后端依赖过载或不可用，请退避后重试。"
+        },
+        "example": "InvalidParameter"
       },
       "ErrorResponse": {
         "description": "错误响应结构。`error` 必填，`data` 不存在。",
@@ -8824,433 +8912,470 @@
         "type": "object"
       },
       "ErsComposition": {
+        "type": "object",
+        "title": "composition",
+        "required": [
+          "result_label",
+          "template"
+        ],
         "properties": {
-          "override": {
-            "description": "为 `true` 时若标签已存在则覆盖，默认为 `false`。",
-            "type": "boolean"
-          },
           "result_label": {
+            "type": "string",
             "description": "组合值写入的目标标签键名，须匹配 `^[a-zA-Z_][a-zA-Z0-9_]*$`。",
-            "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$",
-            "type": "string"
+            "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$"
           },
           "template": {
-            "description": "Go `text/template` 模板串（1–500 字符），基于事件结构体渲染，如 `{{.Title}}`、`{{.Description}}`、`{{.Labels.key}}`。示例：`{{.Labels.region}}-{{.Labels.env}}`。",
+            "type": "string",
             "maxLength": 500,
-            "minLength": 1,
-            "type": "string"
+            "description": "Go `text/template` 模板串（1–500 字符），基于事件结构体渲染，如 `{{.Title}}`、`{{.Description}}`、`{{.Labels.key}}`。示例：`{{.Labels.region}}-{{.Labels.env}}`。",
+            "minLength": 1
+          },
+          "override": {
+            "type": "boolean",
+            "description": "为 `false`（默认）时，若事件已有 `result_label` 标签则跳过该规则；为 `true` 时覆盖已有值。"
           }
-        },
-        "required": [
-          "result_label",
-          "template"
-        ],
-        "title": "composition",
-        "type": "object"
+        }
       },
       "ErsDrop": {
+        "type": "object",
+        "title": "drop",
+        "required": [
+          "drop_labels"
+        ],
         "properties": {
           "drop_labels": {
-            "description": "待从告警中删除的标签键列表。",
+            "type": "array",
             "items": {
               "type": "string"
             },
-            "type": "array"
+            "description": "要从事件中删除的标签名（至少一个），不带 `labels.` 前缀。",
+            "minItems": 1
           }
-        },
-        "required": [
-          "drop_labels"
-        ],
-        "title": "drop",
-        "type": "object"
+        }
       },
       "ErsExtraction": {
+        "type": "object",
+        "title": "extraction",
+        "required": [
+          "source_field",
+          "result_label"
+        ],
         "properties": {
-          "g_json": {
-            "description": "GJson 路径表达式，用于从 JSON 编码的字段中提取值。与 `pattern` 互斥。",
-            "type": "string"
+          "source_field": {
+            "type": "string",
+            "description": "待提取的源字段。可为 `title`、`description` 或以 `labels.` 为前缀的标签键（如 `labels.env`）。"
           },
-          "override": {
-            "description": "为 `true` 时若标签已存在则覆盖，默认为 `false`。",
-            "type": "boolean"
+          "result_label": {
+            "type": "string",
+            "description": "提取值写入的目标标签键名，须匹配 `^[a-zA-Z_][a-zA-Z0-9_]*$`。",
+            "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$"
           },
           "pattern": {
-            "description": "应用于源值的 RE2 正则表达式，须至少包含一个捕获组；所有捕获组用空格连接后写入 `result_label`。与 `g_json` 互斥。",
-            "type": "string"
+            "type": "string",
+            "description": "作用于来源值的正则表达式（RE2），可以用 `/.../` 包裹。所有捕获组以空格拼接后写入 `result_label`。未匹配、没有捕获组或第一个捕获组为空时不写入。`pattern` 与 `g_json` 必须且只能设置一个。"
           },
-          "result_label": {
-            "description": "提取值写入的目标标签键名，须匹配 `^[a-zA-Z_][a-zA-Z0-9_]*$`。",
-            "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$",
-            "type": "string"
+          "g_json": {
+            "type": "string",
+            "description": "当来源值是 JSON 字符串时使用的 GJSON 路径（开头的 `$.` 会被忽略），如 `host.name`。来源值不是合法 JSON 时跳过该规则；路径不存在时写入空字符串。`pattern` 与 `g_json` 必须且只能设置一个。"
           },
-          "source_field": {
-            "description": "待提取的源字段。可为 `title`、`description` 或以 `labels.` 为前缀的标签键（如 `labels.env`）。",
-            "type": "string"
+          "override": {
+            "type": "boolean",
+            "description": "为 `false`（默认）时，若事件已有 `result_label` 标签则跳过该规则；为 `true` 时覆盖已有值。"
           }
-        },
-        "required": [
-          "source_field",
-          "result_label"
-        ],
-        "title": "extraction",
-        "type": "object"
+        }
       },
       "ErsMapping": {
+        "type": "object",
+        "title": "mapping",
+        "required": [
+          "result_labels"
+        ],
         "properties": {
-          "api_id": {
-            "description": "映射 API ID（MongoDB ObjectID 十六进制）。`mapping_type` 为 `api` 时必填。",
-            "type": "string"
+          "result_labels": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$"
+            },
+            "description": "要用查找结果填充的标签键（至少一个）。`schema` 方式下通常取映射规则的 `result_labels`；`api` 方式下会作为 `result_label_keys` 发送给 API。",
+            "minItems": 1
           },
           "mapping_type": {
-            "default": "schema",
-            "description": "映射来源类型。`schema` 使用映射规则表；`api` 调用外部 HTTP API。",
+            "type": "string",
             "enum": [
               "schema",
               "api"
             ],
-            "type": "string"
+            "default": "schema",
+            "description": "查找来源。\n- `schema`（默认）：用事件中该映射规则 `source_labels` 的值，在映射规则 `schema_id` 中查找数据行；缺少任一来源标签或未匹配到行时不生效。\n- `api`：携带事件调用映射 API `api_id`；只对告警事件生效。"
           },
-          "override": {
-            "description": "为 `true` 时若标签已存在则覆盖，默认为 `false`。",
-            "type": "boolean"
+          "schema_id": {
+            "type": "string",
+            "description": "映射规则 ID（MongoDB ObjectID 十六进制）。`mapping_type` 为 `schema` 时必填。"
           },
-          "result_labels": {
-            "description": "映射查找结果要填充的标签键名，每个须匹配 `^[a-zA-Z_][a-zA-Z0-9_]*$`。",
-            "items": {
-              "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$",
-              "type": "string"
-            },
-            "type": "array"
+          "api_id": {
+            "type": "string",
+            "description": "映射 API ID（MongoDB ObjectID 十六进制）。`mapping_type` 为 `api` 时必填。"
           },
-          "schema_id": {
-            "description": "映射规则 ID（MongoDB ObjectID 十六进制）。`mapping_type` 为 `schema` 时必填。",
-            "type": "string"
+          "override": {
+            "type": "boolean",
+            "description": "为 `false`（默认）时，若 `result_labels` 中的标签都已存在则跳过该规则，否则只填充缺失的标签；为 `true` 时用查找结果覆盖全部 `result_labels`。"
           }
-        },
-        "required": [
-          "result_labels"
-        ],
-        "title": "mapping",
-        "type": "object"
+        }
       },
       "EscalateLayer": {
+        "type": "object",
+        "required": [
+          "target"
+        ],
         "properties": {
-          "escalate_window": {
-            "description": "进入下一环节前的等待时间，单位分钟。",
-            "maximum": 720,
-            "minimum": 0,
-            "type": "integer"
-          },
-          "force_escalate": {
-            "description": "为 true 时无论是否认领都强制升级。",
-            "type": "boolean"
-          },
           "max_times": {
-            "description": "当前环节内的最大重复通知次数。",
-            "maximum": 6,
+            "type": "integer",
             "minimum": 0,
-            "type": "integer"
+            "maximum": 6,
+            "description": "本环节的通知总次数（含首次），0–6；`0` 和 `1` 都只通知一次。"
           },
           "notify_step": {
-            "description": "重复通知间隔，单位分钟。",
+            "type": "number",
             "format": "float",
-            "maximum": 120,
             "minimum": 0.5,
-            "type": "number"
+            "maximum": 120,
+            "description": "本环节重复通知的间隔（分钟），0.5–120，保留一位小数。仅当 `max_times` 大于 1 时生效。"
           },
           "target": {
             "$ref": "#/components/schemas/EscalateTarget"
+          },
+          "escalate_window": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 720,
+            "description": "本环节首次通知后等待多少分钟升级到下一环节，0–720。最后一个环节忽略此值。"
+          },
+          "force_escalate": {
+            "type": "boolean",
+            "description": "为 true 时，即使故障已被认领（`Processing`）也继续升级；为 false 时故障被认领后停止升级。已关闭或暂缓中的故障不会升级。"
           }
-        },
-        "required": [
-          "target"
-        ],
-        "type": "object"
+        }
       },
       "EscalateRuleItem": {
+        "type": "object",
+        "required": [
+          "account_id",
+          "channel_id",
+          "priority",
+          "aggr_window",
+          "rule_name",
+          "description",
+          "layers",
+          "time_filters",
+          "filters",
+          "status",
+          "template_id",
+          "rule_id",
+          "updated_by",
+          "created_at",
+          "updated_at"
+        ],
         "properties": {
           "account_id": {
-            "description": "所属账户 ID。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
-          },
-          "aggr_window": {
-            "description": "延迟窗口，单位秒。",
-            "type": "integer"
+            "description": "所属账户 ID。"
           },
           "channel_id": {
-            "description": "所属协作空间 ID。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "所属协作空间 ID。"
           },
-          "channel_name": {
-            "description": "协作空间名称，跨空间列表响应会填充该字段。",
-            "type": "string"
+          "priority": {
+            "type": "integer",
+            "description": "匹配顺序，取值 `0` 到 `200`：数值越小越先匹配，相同时按创建时间。第一条启用且时间窗口与过滤条件都命中新故障的策略负责该故障。"
           },
-          "created_at": {
-            "description": "创建时间，Unix 秒时间戳。",
-            "format": "int64",
-            "type": "integer"
+          "aggr_window": {
+            "type": "integer",
+            "description": "新分派故障首次通知前的延迟（秒），0–3600；`0` 表示立即通知。"
           },
-          "deleted_at": {
-            "description": "删除时间，Unix 秒时间戳。仅在策略被软删除时返回；已删除的策略不会出现在列表响应中。",
-            "format": "int64",
-            "type": "integer"
+          "rule_name": {
+            "type": "string",
+            "description": "策略名称，1–39 个字符。"
           },
           "description": {
-            "description": "策略描述。",
-            "type": "string"
-          },
-          "filters": {
-            "$ref": "#/components/schemas/FilterGroup",
-            "description": "故障级匹配条件（OR-of-AND 结构）：策略匹配的是告警聚合而成的故障，而不是告警本身。不传或为空时对空间内所有故障生效。"
+            "type": "string",
+            "description": "策略描述。"
           },
           "layers": {
-            "description": "分派环节列表。",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/EscalateLayer"
             },
-            "type": "array"
+            "description": "分派环节列表。"
           },
-          "priority": {
-            "description": "匹配优先级，数值越小越优先。",
-            "type": "integer"
-          },
-          "rule_id": {
-            "description": "分派策略 ID（MongoDB ObjectID）。",
-            "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
+          "time_filters": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/TimeFilter"
+            },
+            "description": "策略可参与匹配的周期时间窗口；为空表示任何时间。"
           },
-          "rule_name": {
-            "description": "策略名称。",
-            "type": "string"
+          "filters": {
+            "$ref": "#/components/schemas/FilterGroup",
+            "description": "故障匹配条件（AND 组之间为 OR），匹配的是告警所属的故障。为空表示匹配协作空间内的所有故障。"
           },
           "status": {
-            "description": "策略状态：`enabled` 生效中，`disabled` 已暂停，`deleted` 已软删除（仅详情接口可能返回；列表接口不会返回已删除策略）。",
+            "type": "string",
             "enum": [
               "enabled",
               "disabled",
               "deleted"
             ],
-            "type": "string"
+            "description": "策略状态：`enabled` 生效中，`disabled` 已暂停，`deleted` 已软删除（仅详情接口可能返回；列表接口不会返回已删除策略）。"
           },
           "template_id": {
-            "description": "通知模板 ID（MongoDB ObjectID）。",
+            "type": "string",
             "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
-          },
-          "time_filters": {
-            "description": "策略生效的周期性时间窗口。",
-            "items": {
-              "$ref": "#/components/schemas/TimeFilter"
-            },
-            "type": "array"
+            "description": "通知模板 ID（24 位十六进制）；参见 `POST /template/list`。"
           },
-          "updated_at": {
-            "description": "最近更新时间，Unix 秒时间戳。",
-            "format": "int64",
-            "type": "integer"
+          "rule_id": {
+            "type": "string",
+            "pattern": "^[0-9a-fA-F]{24}$",
+            "description": "分派策略 ID（MongoDB ObjectID）。"
           },
           "updated_by": {
-            "description": "最近更新该策略的成员 ID。",
-            "format": "int64",
-            "type": "integer"
-          }
-        },
-        "required": [
-          "account_id",
-          "channel_id",
-          "priority",
-          "aggr_window",
-          "rule_name",
-          "description",
-          "layers",
-          "time_filters",
-          "filters",
-          "status",
-          "template_id",
-          "rule_id",
-          "updated_by",
-          "created_at",
-          "updated_at"
-        ],
-        "type": "object"
-      },
-      "EscalateTarget": {
-        "description": "通知目标。`person_ids`、`team_ids`、`schedule_to_role_ids`、`emails` 至少设置一项，且 `by` 与 `webhooks` 至少设置一项。",
-        "properties": {
-          "by": {
-            "description": "按告警等级配置的个人通知渠道。未提供 `webhooks` 时必填。",
-            "properties": {
-              "critical": {
-                "description": "Critical 级别使用的通知渠道。个人通知渠道：`sms`、`voice`、`email`、`push`；IM 群聊渠道：`feishu_app:<chat_id>`、`dingtalk_app:<chat_id>`、`wecom_app:<chat_id>`、`slack_app:<chat_id>`、`teams_app:<chat_id>`。",
-                "items": {
-                  "type": "string"
-                },
-                "type": "array"
-              },
-              "follow_preference": {
-                "description": "为 true 时跟随处理人员的个人偏好，忽略下方列表。",
-                "type": "boolean"
-              },
-              "info": {
-                "description": "Info 级别使用的通知渠道。取值同 `critical`。",
-                "items": {
-                  "type": "string"
-                },
-                "type": "array"
-              },
-              "warning": {
-                "description": "Warning 级别使用的通知渠道。取值同 `critical`。",
-                "items": {
-                  "type": "string"
-                },
-                "type": "array"
-              }
-            },
-            "type": "object"
+            "type": "integer",
+            "format": "int64",
+            "description": "最近更新该策略的成员 ID。"
           },
-          "emails": {
-            "description": "邮箱地址列表（推送场景）。",
+          "deleted_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "删除时间，Unix 秒时间戳。仅在策略被软删除时返回；已删除的策略不会出现在列表响应中。"
+          },
+          "created_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "创建时间，Unix 秒时间戳。"
+          },
+          "updated_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "最近更新时间，Unix 秒时间戳。"
+          }
+        }
+      },
+      "EscalateTarget": {
+        "type": "object",
+        "description": "通知目标。`person_ids`、`team_ids`、`schedule_to_role_ids`、`emails` 至少设置一项，且 `by` 与 `webhooks` 至少设置一项。",
+        "properties": {
+          "person_ids": {
+            "type": "array",
             "items": {
-              "format": "email",
-              "type": "string"
+              "type": "integer",
+              "format": "int64"
             },
-            "type": "array"
+            "description": "直接通知的成员 ID，可通过 `POST /member/list` 获取。每个 ID 都必须存在。"
           },
-          "person_ids": {
-            "description": "直接通知的成员 ID 列表。",
+          "team_ids": {
+            "type": "array",
             "items": {
-              "format": "int64",
-              "type": "integer"
+              "type": "integer",
+              "format": "int64"
             },
-            "type": "array"
+            "description": "通知其成员的团队 ID，可通过 `POST /team/list` 获取。每个团队至少要有一名成员。"
           },
           "schedule_to_role_ids": {
+            "type": "object",
             "additionalProperties": {
+              "type": "array",
               "items": {
-                "format": "int64",
-                "type": "integer"
-              },
-              "type": "array"
+                "type": "integer",
+                "format": "int64"
+              }
             },
-            "description": "值班表 ID 到角色 ID 列表的映射，用于按值班角色通知。",
-            "type": "object"
+            "description": "通知当前值班人员：键为值班表 ID（来自 `POST /schedule/list`，以字符串形式书写），值为该值班表上的角色 ID 列表，且不能为空。"
           },
-          "team_ids": {
-            "description": "通知的团队 ID 列表。",
+          "emails": {
+            "type": "array",
             "items": {
-              "format": "int64",
-              "type": "integer"
+              "type": "string",
+              "format": "email"
             },
-            "type": "array"
+            "description": "账户成员的邮箱地址；环节触发时按邮箱解析为对应成员。"
           },
-          "webhooks": {
-            "description": "群聊/Webhook 通知目标。未提供 `by` 时必填。",
-            "items": {
-              "properties": {
-                "settings": {
-                  "additionalProperties": true,
-                  "description": "类型相关的配置参数（群聊 ID、URL 等）。",
-                  "type": "object"
+          "by": {
+            "type": [
+              "object",
+              "null"
+            ],
+            "description": "按故障严重程度为本目标中的人员配置的个人通知渠道。未设置 `webhooks` 时必填；未设置时返回 `null`。",
+            "properties": {
+              "follow_preference": {
+                "type": "boolean",
+                "description": "为 true 时，按每个人在个人通知偏好中为该严重程度配置的渠道通知，忽略 `critical`、`warning`、`info`。"
+              },
+              "critical": {
+                "type": "array",
+                "items": {
+                  "type": "string"
                 },
-                "type": {
-                  "description": "Webhook 类型，可选值：`feishu`、`feishu_app`、`dingtalk`、`dingtalk_app`、`wecom`、`slack`、`slack_app`、`teams_app`、`telegram`、`zoom`。",
+                "description": "故障严重程度为 `Critical` 时使用的通知渠道：`sms`、`voice`、`email`、`push`，或通过 IM 应用集成发送的单聊消息，写作 `<app>:<integration_id>`，其中 `<app>` 为 `feishu_app`、`dingtalk_app`、`wecom_app`、`slack_app` 或 `teams_app`，`<integration_id>` 为该 IM 集成的 ID。其他取值返回 `InvalidParameter`。"
+              },
+              "warning": {
+                "type": "array",
+                "items": {
                   "type": "string"
-                }
+                },
+                "description": "故障严重程度为 `Warning` 时使用的通知渠道，取值同 `critical`。"
               },
+              "info": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "description": "故障严重程度为 `Info` 时使用的通知渠道，取值同 `critical`。"
+              }
+            }
+          },
+          "webhooks": {
+            "type": [
+              "array",
+              "null"
+            ],
+            "description": "通过机器人或 IM 应用通知的群聊。未设置 `by` 时必填；未设置时返回 `null`。",
+            "items": {
+              "type": "object",
               "required": [
                 "type",
                 "settings"
               ],
-              "type": "object"
-            },
-            "type": "array"
+              "properties": {
+                "type": {
+                  "type": "string",
+                  "description": "投递方式：\n- `feishu`、`dingtalk`、`wecom`、`slack`、`telegram`、`zoom`：对应 IM 的群机器人（Webhook）。\n- `feishu_app`、`dingtalk_app`、`slack_app`、`teams_app`：通过对应 IM 应用集成触达的群聊。",
+                  "enum": [
+                    "feishu",
+                    "dingtalk",
+                    "wecom",
+                    "slack",
+                    "telegram",
+                    "zoom",
+                    "feishu_app",
+                    "dingtalk_app",
+                    "slack_app",
+                    "teams_app"
+                  ]
+                },
+                "settings": {
+                  "type": "object",
+                  "additionalProperties": true,
+                  "description": "与类型相关的配置，例如机器人的 Webhook token 或应用的群聊 ID；`feishu_app` 与 `dingtalk_app` 必须提供。各类型的具体结构可先在控制台配置一次，再通过 `POST /channel/escalate/rule/info` 读取。"
+                }
+              }
+            }
           }
-        },
-        "type": "object"
+        }
       },
       "EventGroup": {
+        "type": "object",
         "description": "告警事件合并配置。启用后，同一告警的重复事件会在时间窗口内并入已有告警，而不是新建告警。",
         "properties": {
           "is_enabled": {
-            "description": "为 true 时，重复事件并入已有告警；为 false 时，每个事件都单独生成告警。默认为 true。",
-            "type": "boolean"
+            "type": "boolean",
+            "description": "为 true 时，同一告警的重复事件并入已有告警；为 false 时每个事件单独生成告警。传入 `event_group` 时请显式设置此字段，不传即为 `false`。创建时完全不传 `event_group` 则默认开启合并。"
           },
           "time_window": {
-            "description": "合并窗口，单位分钟，范围 1-1440（24 小时）；开通扩展额度的账号最大可设 10080（7 天）。默认 1440。",
+            "type": "integer",
             "minimum": 1,
-            "type": "integer"
+            "description": "合并窗口（分钟），`is_enabled` 为 true 时必填。默认取值范围 1–1440；开通了扩展合并窗口的账户最大可设 10080（7 天）。关闭合并时忽略。"
           }
-        },
-        "type": "object"
+        }
       },
       "EventItem": {
+        "type": "object",
         "description": "单条已持久化的会话事件。content/actions/usage_metadata 携带原始 ADK 信封，请将其视为不透明的结构化负载。",
         "properties": {
-          "actions": {
-            "additionalProperties": true,
-            "description": "ADK actions 信封（状态增量、转移、升级）。",
-            "type": "object"
+          "event_id": {
+            "type": "string",
+            "description": "事件标识。"
+          },
+          "session_id": {
+            "type": "string",
+            "description": "所属会话 ID。"
+          },
+          "invocation_id": {
+            "type": "string",
+            "description": "写入该事件的调用（一轮智能体执行）ID。为空时不返回。"
+          },
+          "root_invocation_id": {
+            "type": "string",
+            "description": "该事件所属顶层用户轮次的调用 ID，用于把嵌套子智能体调用写入的事件关联回该轮次。为空时不返回。"
+          },
+          "delivery_mode": {
+            "type": "string",
+            "enum": [
+              "reply_only"
+            ],
+            "description": "产生该事件的 IM 请求所协商的投递方式。`reply_only`：IM 端只展示显式回复，不展示智能体的最终文本。普通投递时不返回。"
+          },
+          "is_error": {
+            "type": "boolean",
+            "description": "该事件为记录运行时失败、且错误信息可直接展示给用户的助手事件时为 true。为 false 时不返回。"
           },
           "author": {
-            "description": "事件作者（如 user 或智能体名称）。",
-            "type": "string"
+            "type": "string",
+            "description": "事件作者（如 user 或智能体名称）。"
+          },
+          "person_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "发送该用户消息的成员 ID。助手事件、工具事件以及未记录成员时（自动化运行、部分 IM 轮次）不返回。"
           },
           "branch": {
-            "description": "嵌套智能体的 ADK 分支路径。",
-            "type": "string"
+            "type": "string",
+            "description": "嵌套智能体的 ADK 分支路径。"
           },
           "content": {
+            "type": "object",
             "additionalProperties": true,
-            "description": "ADK content 信封 {role, parts:[...]}。",
-            "type": "object"
+            "description": "ADK content 信封 {role, parts:[...]}。"
           },
-          "created_at": {
-            "description": "事件写入时间，Unix 毫秒时间戳。",
-            "format": "int64",
-            "type": "integer"
-          },
-          "error_code": {
-            "description": "当该事件表示失败时的错误码。",
-            "type": "string"
+          "actions": {
+            "type": "object",
+            "additionalProperties": true,
+            "description": "ADK actions 信封（状态增量、转移、升级）。"
           },
-          "error_message": {
-            "description": "可读的错误信息（如有）。",
-            "type": "string"
+          "usage_metadata": {
+            "type": "object",
+            "additionalProperties": true,
+            "description": "单轮 token 用量元数据。"
           },
-          "event_id": {
-            "description": "事件标识。",
-            "type": "string"
+          "partial": {
+            "type": "boolean",
+            "description": "流式部分分片时为 true。"
           },
-          "invocation_id": {
-            "description": "标识一轮的 ADK 调用 ID。",
-            "type": "string"
+          "turn_complete": {
+            "type": "boolean",
+            "description": "一轮的终止事件上为 true。"
           },
-          "partial": {
-            "description": "流式部分分片时为 true。",
-            "type": "boolean"
+          "error_code": {
+            "type": "string",
+            "description": "当该事件表示失败时的错误码。"
           },
-          "session_id": {
-            "description": "所属会话 ID。",
-            "type": "string"
+          "error_message": {
+            "type": "string",
+            "description": "可读的错误信息（如有）。"
           },
           "status": {
+            "type": "string",
             "description": "事件状态。可选值：`normal`（正常事件，会进入提供给模型的上下文）、`compressed`（已被上下文压缩（compaction）折叠进摘要边界事件，不再加载给模型，仅作历史留存）。",
             "enum": [
               "normal",
               "compressed"
-            ],
-            "type": "string"
-          },
-          "turn_complete": {
-            "description": "一轮的终止事件上为 true。",
-            "type": "boolean"
+            ]
           },
-          "usage_metadata": {
-            "additionalProperties": true,
-            "description": "单轮 token 用量元数据。",
-            "type": "object"
+          "created_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "事件写入时间，Unix 毫秒时间戳。"
           }
         },
         "required": [
@@ -9259,8 +9384,7 @@
           "partial",
           "turn_complete",
           "created_at"
-        ],
-        "type": "object"
+        ]
       },
       "ExploreData": {
         "description": "探索查询结果载荷。",
@@ -9286,67 +9410,78 @@
         "type": "object"
       },
       "ExploreField": {
+        "type": "object",
         "description": "Frame 的一列。取值按列组织，可以包含 null。",
+        "required": [
+          "name",
+          "type",
+          "values"
+        ],
         "properties": {
-          "labels": {
-            "additionalProperties": {
-              "type": "string"
-            },
-            "description": "该列的标签集合。仅 `time_series` 的取值字段可以携带标签，`table` 字段不允许。",
-            "type": "object"
-          },
           "name": {
-            "description": "列名，最长 1 MiB 的 UTF-8 字符串。",
-            "type": "string"
+            "type": "string",
+            "description": "列名，最长 1 MiB 的 UTF-8 字符串。"
           },
           "type": {
-            "description": "列类型。`time_series` 内不接受 `string`；`float` 存放数值，`time` 取值为 UTC RFC3339Nano 字符串。",
+            "type": "string",
             "enum": [
               "string",
               "float",
               "time"
             ],
-            "type": "string"
+            "description": "列类型。`time_series` 内不接受 `string`；`float` 存放数值，`time` 取值为 UTC RFC3339Nano 字符串。"
+          },
+          "labels": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "string"
+            },
+            "description": "该列的标签集合。仅 `time_series` 的取值字段可以携带标签，`table` 字段不允许。"
           },
           "values": {
-            "description": "按行顺序排列的列取值。",
+            "type": "array",
             "items": {
-              "description": "单个单元格。`time` 为 UTC RFC3339Nano 字符串，`float` 可以是字符串 `NaN`、`+Inf`、`-Inf`，除 `time_series` 中的时间值外均可以为 null。"
+              "oneOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "number"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "单元格取值。`time` 单元格为 UTC RFC3339Nano 字符串；`float` 单元格可以是字符串 `NaN`、`+Inf`、`-Inf`；除 `time_series` frame 中的时间值外，任何单元格都可以为 null。"
             },
-            "type": "array"
+            "description": "按行顺序排列的列取值。"
           }
-        },
-        "required": [
-          "name",
-          "type",
-          "values"
-        ],
-        "type": "object"
+        }
       },
       "ExploreFrame": {
+        "type": "object",
         "description": "单个列式 Frame，Frame 内所有字段的取值数量一致。",
+        "required": [
+          "kind",
+          "fields"
+        ],
         "properties": {
-          "fields": {
-            "description": "Frame 的列。",
-            "items": {
-              "$ref": "#/components/schemas/ExploreField"
-            },
-            "type": "array"
-          },
           "kind": {
-            "description": "Frame 形态。`table` 为无标签表格，`time_series` 恰好包含一个时间字段和一个 float 字段。",
+            "type": "string",
             "enum": [
               "table",
               "time_series"
             ],
-            "type": "string"
+            "description": "Frame 形态。`table` 是不带标签的表格。`time_series` 恰好包含一个时间字段和一个 float 字段，时间值严格递增且不为 null。"
+          },
+          "fields": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/ExploreField"
+            },
+            "description": "Frame 的列。"
           }
-        },
-        "required": [
-          "kind",
-          "fields"
-        ],
-        "type": "object"
+        }
       },
       "ExploreLogEntry": {
         "description": "单条日志。",
@@ -9390,71 +9525,79 @@
         "type": "object"
       },
       "ExploreResult": {
+        "type": "object",
         "description": "结果主体。`frames`、`samples`、`entries` 三者中只有与 `kind` 匹配的一个会出现。",
+        "required": [
+          "kind"
+        ],
         "properties": {
-          "applied_limit": {
-            "description": "日志结果实际生效的条数上限，最大 1000。",
-            "type": "integer"
-          },
-          "entries": {
-            "description": "日志条目列表，`kind` 为 `logs` 时出现，长度不超过 `applied_limit`。",
-            "items": {
-              "$ref": "#/components/schemas/ExploreLogEntry"
-            },
-            "type": "array"
-          },
-          "frames": {
-            "description": "列式 Frame 列表，`kind` 为 `frames` 时出现，最多 1,000 个。",
-            "items": {
-              "$ref": "#/components/schemas/ExploreFrame"
-            },
-            "type": "array"
-          },
-          "has_more": {
-            "description": "日志结果是否因 `applied_limit` 被截断。",
-            "type": "boolean"
-          },
           "kind": {
-            "description": "结果形态。`frames` 返回列式表格或时序，`samples` 返回带标签的瞬时值，`logs` 返回日志条目。",
+            "type": "string",
             "enum": [
               "frames",
               "samples",
               "logs"
             ],
-            "type": "string"
+            "description": "结果形态。`frames` 返回列式表格或时序，`samples` 返回带标签的瞬时值，`logs` 返回日志条目。"
+          },
+          "frames": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/ExploreFrame"
+            },
+            "description": "列式 frame。`kind` 为 `frames` 时返回；最多 1,000 个 frame，表格行合计最多 1,000 行，值合计最多 100,000 个。"
           },
           "samples": {
-            "description": "瞬时采样列表，`kind` 为 `samples` 时出现，最多 1,000 条。",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/ExploreSample"
             },
-            "type": "array"
+            "description": "瞬时采样列表，`kind` 为 `samples` 时出现，最多 1,000 条。"
+          },
+          "entries": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/ExploreLogEntry"
+            },
+            "description": "日志条目列表，`kind` 为 `logs` 时出现，长度不超过 `applied_limit`。"
+          },
+          "applied_limit": {
+            "type": "integer",
+            "description": "logs 结果实际应用的条数上限：1 到 1000（`sls` 数据源为 1 到 100）。仅在 `kind` 为 `logs` 时返回。"
+          },
+          "has_more": {
+            "type": "boolean",
+            "description": "日志结果是否因 `applied_limit` 被截断。"
           }
-        },
-        "required": [
-          "kind"
-        ],
-        "type": "object"
+        }
       },
       "ExploreSample": {
+        "type": "object",
         "description": "单个瞬时采样。",
+        "required": [
+          "labels",
+          "value"
+        ],
         "properties": {
           "labels": {
+            "type": "object",
             "additionalProperties": {
               "type": "string"
             },
-            "description": "采样的标签集合。可以为空，但不能为 null。",
-            "type": "object"
+            "description": "采样的标签集合。可以为空，但不能为 null。"
           },
           "value": {
-            "description": "采样值：数字，或字符串 `NaN`、`+Inf`、`-Inf`。不能为 null。"
+            "oneOf": [
+              {
+                "type": "number"
+              },
+              {
+                "type": "string"
+              }
+            ],
+            "description": "采样值：数字，或字符串 `NaN`、`+Inf`、`-Inf` 之一。不会为 null。"
           }
-        },
-        "required": [
-          "labels",
-          "value"
-        ],
-        "type": "object"
+        }
       },
       "PrometheusLabelValuesResponse": {
         "description": "所查询数据源返回的原生 Prometheus HTTP API 响应。本接口不会把结果包装进 Flashduty 统一响应 envelope。",
@@ -9490,80 +9633,82 @@
         "type": "object"
       },
       "QueryExploreExecution": {
-        "description": "查询的时间语义。可接受的配套字段取决于 `kind`：`instant` 只需 `to_ms`（`from_ms` 可选），`range` 需要 `from_ms`、`to_ms` 和 `max_data_points`，`window` 需要 `from_ms` 和 `to_ms`。HTTP 接口不接受 `step_seconds`。",
+        "type": "object",
+        "description": "查询的时间语义。可接受的配套字段取决于 `kind`：`instant` 使用 `to_ms`（可选 `from_ms`），`range` 需要 `from_ms`、`to_ms` 和 `max_data_points`，`window` 只使用 `from_ms` 与 `to_ms`。同时给出两个时间时，`from_ms` 必须小于 `to_ms`。HTTP 接口不接受 `step_seconds`。",
+        "required": [
+          "kind"
+        ],
         "properties": {
-          "from_ms": {
-            "description": "范围起点的 Unix 毫秒时间戳。`range` 和 `window` 必填，`instant` 可选。",
-            "format": "int64",
-            "type": "integer"
-          },
           "kind": {
-            "description": "执行类型。`instant` 在单个时间点取值，`range` 在时间范围内取序列，`window` 返回时间窗口内的原始行。",
+            "type": "string",
             "enum": [
               "instant",
               "range",
               "window"
             ],
-            "type": "string"
+            "description": "执行类型。\n\n- `instant`：在单个时间点上求值。\n- `range`：在 `from_ms` 到 `to_ms` 范围内求时间序列，步长由 `max_data_points` 与 `min_step_seconds` 推导。\n- `window`：查询 `from_ms` 到 `to_ms` 之间的区间，不带步长。"
+          },
+          "from_ms": {
+            "type": "integer",
+            "format": "int64",
+            "description": "区间起点，Unix 时间戳，单位毫秒；非负且小于 `to_ms`。`range` 与 `window` 必填，`instant` 可选。",
+            "minimum": 0
+          },
+          "to_ms": {
+            "type": "integer",
+            "format": "int64",
+            "description": "区间终点（`instant` 时为求值时间），Unix 时间戳，单位毫秒；非负。所有执行类型都必填。",
+            "minimum": 0
           },
           "max_data_points": {
-            "description": "返回的数据点数量上限。`range` 必填，`instant` 与 `window` 不接受该字段。",
+            "type": "integer",
             "format": "int64",
-            "maximum": 5000,
             "minimum": 2,
-            "type": "integer"
+            "maximum": 5000,
+            "description": "返回的数据点数量上限。`range` 必填，`instant` 与 `window` 不接受该字段。"
           },
           "min_step_seconds": {
-            "description": "由 `max_data_points` 推导出的步长下限（秒）。可选，仅在 `range` 下接受。",
+            "type": "integer",
             "format": "int64",
             "minimum": 1,
-            "type": "integer"
-          },
-          "to_ms": {
-            "description": "范围终点的 Unix 毫秒时间戳。所有执行类型均必填。",
-            "format": "int64",
-            "type": "integer"
+            "description": "由 `max_data_points` 推导出的步长下限（秒）。可选，仅在 `range` 下接受。"
           }
-        },
-        "required": [
-          "kind"
-        ],
-        "type": "object"
+        }
       },
       "QueryExploreRequest": {
+        "type": "object",
         "description": "探索查询请求。四个顶层字段均为必填，未知字段会被拒绝。",
+        "required": [
+          "datasource_id",
+          "expr",
+          "args",
+          "execution"
+        ],
         "properties": {
+          "datasource_id": {
+            "type": "integer",
+            "format": "int64",
+            "minimum": 1,
+            "maximum": 9007199254740991,
+            "description": "来自 `/monit/datasource/list` 的数据源 ID。必须是正的 JavaScript 安全整数，对应已认证账户下已启用、且调用方有权查询的数据源。"
+          },
+          "expr": {
+            "type": "string",
+            "minLength": 1,
+            "description": "使用数据源原生语言的查询表达式（PromQL、LogsQL、SQL 等）。非空 UTF-8，最大 64 KiB；`mysql` 最大 16 KiB，`tencent_cls` 最大 12 KiB。"
+          },
           "args": {
+            "type": "object",
             "additionalProperties": {
               "type": "string"
             },
-            "description": "宏替换参数，按变量名索引，用于 Grafana 风格变量。键最长 256 字节，值最长 64 KiB，总预算 128 KiB。",
             "maxProperties": 128,
-            "type": "object"
-          },
-          "datasource_id": {
-            "description": "数据源 ID，来自 `/monit/datasource/list`。必须是正数且不超过 JavaScript 安全整数范围，且属于当前账户。",
-            "format": "int64",
-            "maximum": 9007199254740991,
-            "minimum": 1,
-            "type": "integer"
+            "description": "宏替换参数，按变量名索引，用于 Grafana 风格变量。键最长 256 字节，值最长 64 KiB，总预算 128 KiB。"
           },
           "execution": {
             "$ref": "#/components/schemas/QueryExploreExecution"
-          },
-          "expr": {
-            "description": "使用数据源原生语言的查询表达式（如 PromQL、LogsQL、SQL 等）。非空 UTF-8 字符串，最长 64 KiB；部分数据源类型限制更小。",
-            "minLength": 1,
-            "type": "string"
           }
-        },
-        "required": [
-          "datasource_id",
-          "expr",
-          "args",
-          "execution"
-        ],
-        "type": "object"
+        }
       },
       "ExportStatusPageSubscribersRequest": {
         "description": "导出状态页订阅者列表所需的参数。",
@@ -9587,43 +9732,43 @@
         "type": "object"
       },
       "ExportedStatusPageSubscriberItem": {
+        "type": "object",
         "description": "状态页订阅者，供订阅者列表和导出接口返回。",
+        "required": [
+          "recipient",
+          "method",
+          "components",
+          "all"
+        ],
         "properties": {
-          "all": {
-            "description": "是否订阅全部组件。",
-            "type": "boolean"
-          },
-          "components": {
-            "description": "该订阅者订阅的组件列表。",
-            "items": {
-              "$ref": "#/components/schemas/StatusPageComponentItem"
-            },
-            "type": "array"
-          },
-          "locale": {
-            "description": "通知的首选语言。为空时不返回。",
-            "type": "string"
+          "recipient": {
+            "type": "string",
+            "description": "订阅接收方：公开状态页为邮箱地址，内部状态页为用户 ID。"
           },
           "method": {
-            "description": "订阅通知方式。`email` 为邮件订阅（公开状态页）；`im` 为 IM 即时消息订阅（内部状态页）。取值由状态页类型决定。",
+            "type": "string",
             "enum": [
               "email",
               "im"
             ],
-            "type": "string"
+            "description": "订阅通知方式。`email` 为邮件订阅（公开状态页）；`im` 为 IM 即时消息订阅（内部状态页）。取值由状态页类型决定。"
           },
-          "recipient": {
-            "description": "订阅接收方：公开状态页为邮箱地址，内部状态页为用户 ID。",
-            "type": "string"
+          "components": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/StatusPageComponentItem"
+            },
+            "description": "订阅者关注的组件，每项只包含 `component_id` 和 `name`。`all` 为 `true` 时为空数组。"
+          },
+          "all": {
+            "type": "boolean",
+            "description": "是否订阅全部组件。"
+          },
+          "locale": {
+            "type": "string",
+            "description": "通知的首选语言。为空时不返回。"
           }
-        },
-        "required": [
-          "recipient",
-          "method",
-          "components",
-          "all"
-        ],
-        "type": "object"
+        }
       },
       "FacetCountItem": {
         "description": "一个分面值及其出现次数。",
@@ -9792,26 +9937,29 @@
         "type": "object"
       },
       "FeedDetailIncidentAck": {
+        "type": "object",
         "description": "`i_ack` 的 detail 载荷。",
         "properties": {
+          "progress": {
+            "type": "string",
+            "description": "本次认领把故障从 `Triggered` 变为 `Processing` 时为 `Processing`；故障原本已是 `Processing` 时省略。",
+            "enum": [
+              "Processing"
+            ]
+          },
           "comment": {
-            "description": "写入时间线评论的表单摘要。未提交认领表单摘要时省略。",
-            "type": "string"
+            "type": "string",
+            "description": "写入时间线评论的表单摘要。未提交认领表单摘要时省略。"
           },
           "images": {
-            "description": "认领表单提交的图片，仅写入时间线记录。未提交时省略。",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/Image"
             },
-            "type": "array"
-          },
-          "progress": {
-            "description": "认领时记录的处理进展。",
-            "type": "string"
+            "description": "认领表单提交的图片，仅写入时间线记录。未提交时省略。"
           }
         },
-        "title": "i_ack",
-        "type": "object"
+        "title": "i_ack"
       },
       "FeedDetailIncidentAddRspd": {
         "description": "`i_a_rspd` 的 detail 载荷。",
@@ -9859,27 +10007,28 @@
         "type": "object"
       },
       "FeedDetailIncidentComment": {
+        "type": "object",
         "description": "`i_comm` 的 detail 载荷。",
         "properties": {
           "comment": {
-            "description": "评论正文。",
-            "type": "string"
+            "type": "string",
+            "description": "评论正文。"
           },
-          "comment_type": {
-            "$ref": "#/components/schemas/IncidentCommentTypeDisplay"
+          "mute_reply": {
+            "type": "boolean",
+            "description": "是否静音该评论的回复。"
           },
           "comment_type_id": {
-            "description": "附加到评论的账户级评论类型 ObjectID。",
+            "type": "string",
             "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
+            "description": "附加到评论的账户级评论类型 ObjectID。"
           },
-          "mute_reply": {
-            "description": "是否静音该评论的回复。",
-            "type": "boolean"
+          "comment_type": {
+            "$ref": "#/components/schemas/IncidentCommentTypeDisplay",
+            "description": "所附评论类型的名称和颜色，读取时解析；未附评论类型或类型已不存在时省略。"
           }
         },
-        "title": "i_comm",
-        "type": "object"
+        "title": "i_comm"
       },
       "FeedDetailIncidentCustomAction": {
         "description": "`i_custom` 的 detail 载荷。",
@@ -9898,46 +10047,47 @@
         "type": "object"
       },
       "FeedDetailIncidentMerge": {
+        "type": "object",
         "description": "`i_merge` 的 detail 载荷。",
         "properties": {
           "comment": {
-            "description": "合并时的评论。",
-            "type": "string"
-          },
-          "owner_id": {
-            "description": "执行合并操作的成员 ID。",
-            "format": "int64",
-            "type": "integer"
-          },
-          "remove_source_incidents": {
-            "description": "合并后是否移除源故障。",
-            "type": "boolean"
+            "type": "string",
+            "description": "合并时的评论。"
           },
           "source_incidents": {
-            "description": "被合并的源故障列表。",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/IncidentShort"
             },
-            "type": "array"
-          },
-          "source_responders": {
-            "description": "从源故障继承的响应人成员 ID 列表。",
-            "items": {
-              "format": "int64",
-              "type": "integer"
-            },
-            "type": "array"
+            "description": "被合并进目标故障的源故障；出现在目标故障的记录中。"
           },
           "target_incident": {
-            "$ref": "#/components/schemas/IncidentShort"
+            "$ref": "#/components/schemas/IncidentShort",
+            "description": "本故障被合并进的目标故障；出现在源故障的记录中。"
+          },
+          "owner_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "故障合并不会修改负责人，因此不写入此字段；仅可能出现在旧记录中。"
           },
           "title": {
-            "description": "合并后的故障标题。",
-            "type": "string"
+            "type": "string",
+            "description": "合并时为目标故障设置的新标题；仅出现在目标故障的记录中，且仅在标题变化时出现。"
+          },
+          "remove_source_incidents": {
+            "type": "boolean",
+            "description": "合并后源故障被永久删除时为 `true`。"
+          },
+          "source_responders": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "int64"
+            },
+            "description": "源故障上的处理人成员 ID，仅供参考，不会加入目标故障的处理人。"
           }
         },
-        "title": "i_merge",
-        "type": "object"
+        "title": "i_merge"
       },
       "FeedDetailIncidentMuteByFlapping": {
         "description": "`i_m_flapping` 的 detail 载荷。",
@@ -9966,22 +10116,23 @@
         "type": "object"
       },
       "FeedDetailIncidentNew": {
+        "type": "object",
         "description": "`i_new` 的 detail 载荷。",
         "properties": {
-          "reporter_email": {
-            "description": "外部创建故障时的上报人邮箱。",
-            "type": "string"
-          },
           "severity": {
-            "$ref": "#/components/schemas/FeedSeverity"
+            "$ref": "#/components/schemas/FeedSeverity",
+            "description": "故障创建时的严重程度。"
           },
           "title": {
-            "description": "故障初始标题。",
-            "type": "string"
+            "type": "string",
+            "description": "故障初始标题。"
+          },
+          "reporter_email": {
+            "type": "string",
+            "description": "外部创建故障时的上报人邮箱。"
           }
         },
-        "title": "i_new",
-        "type": "object"
+        "title": "i_new"
       },
       "FeedDetailIncidentNotify": {
         "description": "`i_notify` 的 detail 载荷。",
@@ -10048,15 +10199,15 @@
         "type": "object"
       },
       "FeedDetailIncidentReopen": {
+        "type": "object",
         "description": "`i_reopen` 的 detail 载荷。",
         "properties": {
           "reason": {
-            "description": "重新打开故障的原因。",
-            "type": "string"
+            "type": "string",
+            "description": "调用 `POST /incident/reopen` 时传入的 `reason` 原文；未填写时省略。"
           }
         },
-        "title": "i_reopen",
-        "type": "object"
+        "title": "i_reopen"
       },
       "FeedDetailIncidentResetDescription": {
         "additionalProperties": false,
@@ -10104,32 +10255,34 @@
         "type": "object"
       },
       "FeedDetailIncidentResetSeverity": {
+        "type": "object",
         "description": "`i_r_severity` 的 detail 载荷。",
         "properties": {
           "from": {
-            "$ref": "#/components/schemas/FeedSeverity"
+            "$ref": "#/components/schemas/FeedSeverity",
+            "description": "修改前的严重程度。"
           },
           "to": {
-            "$ref": "#/components/schemas/FeedSeverity"
+            "$ref": "#/components/schemas/FeedSeverity",
+            "description": "修改后的严重程度。"
           }
         },
-        "title": "i_r_severity",
-        "type": "object"
+        "title": "i_r_severity"
       },
       "FeedDetailIncidentResetTitle": {
+        "type": "object",
         "description": "`i_r_title` 的 detail 载荷。",
         "properties": {
           "from": {
-            "description": "变更前的标题。",
-            "type": "string"
+            "type": "string",
+            "description": "修改前的标题。"
           },
           "to": {
-            "description": "变更后的标题。",
-            "type": "string"
+            "type": "string",
+            "description": "修改后的标题。"
           }
         },
-        "title": "i_r_title",
-        "type": "object"
+        "title": "i_r_title"
       },
       "FeedDetailIncidentResolve": {
         "description": "`i_rslv` 的 detail 载荷。",
@@ -10190,113 +10343,150 @@
         "type": "object"
       },
       "FeedDetailIncidentUnack": {
+        "type": "object",
         "description": "`i_unack` 的 detail 载荷。",
         "properties": {
           "progress": {
-            "description": "取消认领时记录的处理进展。",
-            "type": "string"
+            "type": "string",
+            "description": "撤销认领后故障回到 `Triggered`（已无处理人处于认领状态）时为 `Triggered`，否则省略。",
+            "enum": [
+              "Triggered"
+            ]
           }
         },
-        "title": "i_unack",
-        "type": "object"
+        "title": "i_unack"
       },
       "FeedDetailIncidentWake": {
+        "type": "object",
         "description": "`i_wake` 的 detail 载荷。",
         "properties": {
           "snoozedBefore": {
-            "description": "原本计划结束暂停的 Unix 时间戳。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "被取消的暂停原定结束的 Unix 时间戳（秒）。"
           }
         },
-        "title": "i_wake",
-        "type": "object"
+        "title": "i_wake"
       },
       "FeedDetailIncidentWarRoomCreate": {
+        "type": "object",
         "description": "`i_wr_create` 的 detail 载荷。",
         "properties": {
+          "integration_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "承载作战室群聊的集成 ID。"
+          },
           "chat_id": {
-            "description": "群聊 ID。",
-            "type": "string"
+            "type": "string",
+            "description": "群聊 ID。"
           },
           "chat_name": {
-            "description": "群聊显示名称。",
-            "type": "string"
+            "type": "string",
+            "description": "群聊显示名称。"
           },
-          "integration_id": {
-            "description": "承载作战室群聊的集成 ID。",
-            "format": "int64",
-            "type": "integer"
+          "plugin_type": {
+            "type": "string",
+            "description": "IM 集成的插件类型：`feishu_app`（飞书）、`dingtalk_app`（钉钉）、`wecom_app`（企业微信）、`slack_app`（Slack）。",
+            "enum": [
+              "feishu_app",
+              "dingtalk_app",
+              "wecom_app",
+              "slack_app"
+            ]
           },
           "integration_name": {
-            "description": "集成显示名称。",
-            "type": "string"
-          },
-          "plugin_type": {
-            "description": "聊天集成插件类型。",
-            "type": "string"
+            "type": "string",
+            "description": "集成显示名称。"
           },
           "share_link": {
-            "description": "作战室的可分享加入链接。",
-            "type": "string"
+            "type": "string",
+            "description": "作战室的可分享加入链接。"
           }
         },
-        "title": "i_wr_create",
-        "type": "object"
+        "title": "i_wr_create"
       },
       "FeedDetailIncidentWarRoomDelete": {
+        "type": "object",
         "description": "`i_wr_delete` 的 detail 载荷。",
         "properties": {
+          "integration_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "承载作战室群聊的集成 ID。"
+          },
+          "unlink_only": {
+            "type": "boolean",
+            "description": "仅解除关联（`unlink_only` 请求）、未解散群组时为 `true`，否则省略。"
+          },
           "chat_id": {
-            "description": "群聊 ID。",
-            "type": "string"
+            "type": "string",
+            "description": "群聊 ID。"
           },
           "chat_name": {
-            "description": "群聊显示名称。",
-            "type": "string"
+            "type": "string",
+            "description": "群聊显示名称。"
           },
-          "integration_id": {
-            "description": "承载作战室群聊的集成 ID。",
-            "format": "int64",
-            "type": "integer"
+          "plugin_type": {
+            "type": "string",
+            "description": "IM 集成的插件类型：`feishu_app`（飞书）、`dingtalk_app`（钉钉）、`wecom_app`（企业微信）、`slack_app`（Slack）。",
+            "enum": [
+              "feishu_app",
+              "dingtalk_app",
+              "wecom_app",
+              "slack_app"
+            ]
           },
           "integration_name": {
-            "description": "集成显示名称。",
-            "type": "string"
-          },
-          "plugin_type": {
-            "description": "聊天集成插件类型。",
-            "type": "string"
+            "type": "string",
+            "description": "集成显示名称。"
           }
         },
-        "title": "i_wr_delete",
-        "type": "object"
+        "title": "i_wr_delete"
       },
       "FeedDetailWorkItemAssigneesChanged": {
+        "type": "object",
         "description": "`i_wi_assignees` 的 detail 载荷。",
         "properties": {
-          "added_assignee_ids": {
-            "description": "新增为负责人的成员 ID。",
+          "work_item_id": {
+            "type": "string",
+            "description": "工作项 ID（`wi_` 加随机字符串），可用于 `/incident/work-item/*` 系列接口。"
+          },
+          "item_type": {
+            "type": "string",
+            "enum": [
+              "action",
+              "follow_up"
+            ],
+            "description": "跟进事项类型。`action`：挂在故障上的处置行动事项；`follow_up`：挂在故障复盘（Post-mortem）上的改进事项。"
+          },
+          "title": {
+            "type": "string",
+            "description": "跟进事项标题。"
+          },
+          "assignee_ids": {
+            "type": "array",
             "items": {
-              "format": "int64",
-              "type": "integer"
+              "type": "integer",
+              "format": "int64"
             },
-            "type": "array"
+            "description": "变更后的负责人成员 ID 列表。"
           },
-          "added_assignees": {
+          "added_assignee_ids": {
             "type": "array",
             "items": {
-              "$ref": "#/components/schemas/WorkItemAssignee"
+              "type": "integer",
+              "format": "int64"
             },
-            "description": "本次新增的负责人，按提交顺序。`added_assignee_ids` 是其中仅含 `person` 的子集。无新增时省略。"
+            "description": "新增为负责人的成员 ID。"
           },
-          "assignee_ids": {
-            "description": "变更后的负责人成员 ID 列表。",
+          "removed_assignee_ids": {
+            "type": "array",
             "items": {
-              "format": "int64",
-              "type": "integer"
+              "type": "integer",
+              "format": "int64"
             },
-            "type": "array"
+            "description": "从负责人中移除的成员 ID。"
           },
           "assignees": {
             "type": "array",
@@ -10305,21 +10495,12 @@
             },
             "description": "跟进事项的负责人。每项为 `{type, id?}`；`ai_sre` 不带 `id`。无负责人时省略。"
           },
-          "item_type": {
-            "description": "跟进事项类型。`action`：挂在故障上的处置行动事项；`follow_up`：挂在故障复盘（Post-mortem）上的改进事项。",
-            "enum": [
-              "action",
-              "follow_up"
-            ],
-            "type": "string"
-          },
-          "removed_assignee_ids": {
-            "description": "从负责人中移除的成员 ID。",
+          "added_assignees": {
+            "type": "array",
             "items": {
-              "format": "int64",
-              "type": "integer"
+              "$ref": "#/components/schemas/WorkItemAssignee"
             },
-            "type": "array"
+            "description": "本次新增的负责人，按提交顺序。`added_assignee_ids` 是其中仅含 `person` 的子集。无新增时省略。"
           },
           "removed_assignees": {
             "type": "array",
@@ -10327,130 +10508,151 @@
               "$ref": "#/components/schemas/WorkItemAssignee"
             },
             "description": "本次移除的负责人。`removed_assignee_ids` 是其中仅含 `person` 的子集。无移除时省略。"
-          },
-          "title": {
-            "description": "跟进事项标题。",
-            "type": "string"
-          },
-          "work_item_id": {
-            "description": "跟进事项 ID。",
-            "type": "string"
           }
         },
-        "title": "i_wi_assignees",
-        "type": "object"
+        "title": "i_wi_assignees"
       },
       "FeedDetailWorkItemBound": {
+        "type": "object",
         "description": "`i_wi_bound` 的 detail 载荷。",
         "properties": {
+          "work_item_id": {
+            "type": "string",
+            "description": "工作项 ID（`wi_` 加随机字符串），可用于 `/incident/work-item/*` 系列接口。"
+          },
           "item_type": {
-            "description": "跟进事项类型。`action`：挂在故障上的处置行动事项；`follow_up`：挂在故障复盘（Post-mortem）上的改进事项。",
+            "type": "string",
             "enum": [
               "action",
               "follow_up"
             ],
-            "type": "string"
-          },
-          "post_mortem_id": {
-            "description": "跟进事项绑定的故障复盘 ID。",
-            "type": "string"
+            "description": "跟进事项类型。`action`：挂在故障上的处置行动事项；`follow_up`：挂在故障复盘（Post-mortem）上的改进事项。"
           },
           "title": {
-            "description": "跟进事项标题。",
-            "type": "string"
+            "type": "string",
+            "description": "跟进事项标题。"
           },
-          "work_item_id": {
-            "description": "跟进事项 ID。",
-            "type": "string"
+          "post_mortem_id": {
+            "type": "string",
+            "description": "跟进事项绑定的故障复盘 ID。"
           }
         },
-        "title": "i_wi_bound",
-        "type": "object"
+        "title": "i_wi_bound"
       },
       "FeedDetailWorkItemCompleted": {
+        "type": "object",
         "description": "`i_wi_completed` 的 detail 载荷。",
         "properties": {
-          "from_status": {
-            "description": "完成前的状态标签。",
-            "type": "string"
+          "work_item_id": {
+            "type": "string",
+            "description": "工作项 ID（`wi_` 加随机字符串），可用于 `/incident/work-item/*` 系列接口。"
           },
           "item_type": {
-            "description": "跟进事项类型。`action`：挂在故障上的处置行动事项；`follow_up`：挂在故障复盘（Post-mortem）上的改进事项。",
+            "type": "string",
             "enum": [
               "action",
               "follow_up"
             ],
-            "type": "string"
-          },
-          "post_mortem_id": {
-            "description": "跟进事项绑定的故障复盘 ID。",
-            "type": "string"
+            "description": "跟进事项类型。`action`：挂在故障上的处置行动事项；`follow_up`：挂在故障复盘（Post-mortem）上的改进事项。"
           },
           "title": {
-            "description": "跟进事项标题。",
-            "type": "string"
+            "type": "string",
+            "description": "跟进事项标题。"
+          },
+          "from_status": {
+            "type": "string",
+            "description": "完成前的状态，通常为 `open` 或 `in_progress`；这些状态引入前创建的工作项可能是其他文本。"
           },
           "to_status": {
-            "description": "完成后的状态标签。",
-            "type": "string"
+            "type": "string",
+            "description": "完成后的状态，恒为 `done`。",
+            "enum": [
+              "done"
+            ]
           },
-          "work_item_id": {
-            "description": "跟进事项 ID。",
-            "type": "string"
+          "post_mortem_id": {
+            "type": "string",
+            "description": "跟进事项绑定的故障复盘 ID。"
           }
         },
-        "title": "i_wi_completed",
-        "type": "object"
+        "title": "i_wi_completed"
       },
       "FeedDetailWorkItemConverted": {
+        "type": "object",
         "description": "`i_wi_converted` 的 detail 载荷。",
         "properties": {
+          "work_item_id": {
+            "type": "string",
+            "description": "工作项 ID（`wi_` 加随机字符串），可用于 `/incident/work-item/*` 系列接口。"
+          },
+          "title": {
+            "type": "string",
+            "description": "跟进事项标题。"
+          },
           "from_type": {
-            "description": "转化前的事项类型。`action`：挂在故障上的处置行动事项；`follow_up`：挂在故障复盘（Post-mortem）上的改进事项。当前转换方向仅支持 `action` → `follow_up`，因此该事件中 `from_type` 恒为 `action`。",
+            "type": "string",
             "enum": [
               "action",
               "follow_up"
             ],
-            "type": "string"
-          },
-          "post_mortem_id": {
-            "description": "跟进事项绑定的故障复盘 ID。",
-            "type": "string"
-          },
-          "status": {
-            "description": "转化后的事项状态标签。",
-            "type": "string"
-          },
-          "title": {
-            "description": "跟进事项标题。",
-            "type": "string"
+            "description": "转化前的事项类型。`action`：挂在故障上的处置行动事项；`follow_up`：挂在故障复盘（Post-mortem）上的改进事项。当前转换方向仅支持 `action` → `follow_up`，因此该事件中 `from_type` 恒为 `action`。"
           },
           "to_type": {
-            "description": "转化后的事项类型。`action`：挂在故障上的处置行动事项；`follow_up`：挂在故障复盘（Post-mortem）上的改进事项。当前转换方向仅支持 `action` → `follow_up`，因此该事件中 `to_type` 恒为 `follow_up`，且转换成功后会立即尝试绑定故障对应的复盘。",
+            "type": "string",
             "enum": [
               "action",
               "follow_up"
             ],
-            "type": "string"
+            "description": "转化后的事项类型。`action`：挂在故障上的处置行动事项；`follow_up`：挂在故障复盘（Post-mortem）上的改进事项。当前转换方向仅支持 `action` → `follow_up`，因此该事件中 `to_type` 恒为 `follow_up`，且转换成功后会立即尝试绑定故障对应的复盘。"
           },
-          "work_item_id": {
-            "description": "跟进事项 ID。",
-            "type": "string"
+          "post_mortem_id": {
+            "type": "string",
+            "description": "跟进事项绑定的故障复盘 ID。"
+          },
+          "status": {
+            "type": "string",
+            "description": "转换后的工作项状态，通常为 `open` 或 `in_progress`（转换不改变状态）。"
           }
         },
-        "title": "i_wi_converted",
-        "type": "object"
+        "title": "i_wi_converted"
       },
       "FeedDetailWorkItemCreated": {
+        "type": "object",
         "description": "`i_wi_created` 的 detail 载荷。",
         "properties": {
+          "work_item_id": {
+            "type": "string",
+            "description": "工作项 ID（`wi_` 加随机字符串），可用于 `/incident/work-item/*` 系列接口。"
+          },
+          "item_type": {
+            "type": "string",
+            "enum": [
+              "action",
+              "follow_up"
+            ],
+            "description": "跟进事项类型。`action`：挂在故障上的处置行动事项，可直接转换为 `follow_up`；`follow_up`：挂在故障复盘（Post-mortem）上的改进事项，创建时要求故障已关联到该复盘。"
+          },
+          "title": {
+            "type": "string",
+            "description": "跟进事项标题。"
+          },
+          "status": {
+            "type": "string",
+            "description": "创建时的工作项状态：`open` 未开始；`in_progress` 进行中；`done` 已完成；`cancelled` 已取消。",
+            "enum": [
+              "open",
+              "in_progress",
+              "done",
+              "cancelled"
+            ]
+          },
           "assignee_ids": {
-            "description": "负责人成员 ID 列表。",
+            "type": "array",
             "items": {
-              "format": "int64",
-              "type": "integer"
+              "type": "integer",
+              "format": "int64"
             },
-            "type": "array"
+            "description": "负责人成员 ID 列表。"
           },
           "assignees": {
             "type": "array",
@@ -10459,152 +10661,120 @@
             },
             "description": "跟进事项的负责人。每项为 `{type, id?}`；`ai_sre` 不带 `id`。无负责人时省略。"
           },
-          "item_type": {
-            "description": "跟进事项类型。`action`：挂在故障上的处置行动事项，可直接转换为 `follow_up`；`follow_up`：挂在故障复盘（Post-mortem）上的改进事项，创建时要求故障已关联到该复盘。",
-            "enum": [
-              "action",
-              "follow_up"
-            ],
-            "type": "string"
-          },
           "post_mortem_id": {
-            "description": "跟进事项绑定的故障复盘 ID。",
-            "type": "string"
-          },
-          "status": {
-            "description": "跟进事项状态标签（如 `open`、`done`）。",
-            "type": "string"
-          },
-          "title": {
-            "description": "跟进事项标题。",
-            "type": "string"
-          },
-          "work_item_id": {
-            "description": "跟进事项 ID。",
-            "type": "string"
+            "type": "string",
+            "description": "跟进事项绑定的故障复盘 ID。"
           }
         },
-        "title": "i_wi_created",
-        "type": "object"
+        "title": "i_wi_created"
       },
       "FeedDetailWorkItemDeleted": {
+        "type": "object",
         "description": "`i_wi_deleted` 的 detail 载荷。",
         "properties": {
+          "work_item_id": {
+            "type": "string",
+            "description": "工作项 ID（`wi_` 加随机字符串），可用于 `/incident/work-item/*` 系列接口。"
+          },
           "item_type": {
-            "description": "跟进事项类型。`action`：挂在故障上的处置行动事项；`follow_up`：挂在故障复盘（Post-mortem）上的改进事项。",
+            "type": "string",
             "enum": [
               "action",
               "follow_up"
             ],
-            "type": "string"
-          },
-          "post_mortem_id": {
-            "description": "跟进事项绑定的故障复盘 ID。",
-            "type": "string"
+            "description": "跟进事项类型。`action`：挂在故障上的处置行动事项；`follow_up`：挂在故障复盘（Post-mortem）上的改进事项。"
           },
           "title": {
-            "description": "跟进事项标题。",
-            "type": "string"
+            "type": "string",
+            "description": "跟进事项标题。"
           },
-          "work_item_id": {
-            "description": "跟进事项 ID。",
-            "type": "string"
+          "post_mortem_id": {
+            "type": "string",
+            "description": "跟进事项绑定的故障复盘 ID。"
           }
         },
-        "title": "i_wi_deleted",
-        "type": "object"
+        "title": "i_wi_deleted"
       },
       "FeedDetailWorkItemUpdated": {
+        "type": "object",
         "description": "`i_wi_updated` 的 detail 载荷。仅发生变化的字段携带 `from_*`/`to_*` 值。",
         "properties": {
-          "from_description": {
-            "description": "更新前的描述。",
-            "type": "string"
-          },
-          "from_priority": {
-            "description": "更新前的优先级标签。",
-            "type": "string"
-          },
-          "from_status": {
-            "description": "更新前的状态标签。",
-            "type": "string"
-          },
-          "from_title": {
-            "description": "更新前的标题。",
-            "type": "string"
+          "work_item_id": {
+            "type": "string",
+            "description": "工作项 ID（`wi_` 加随机字符串），可用于 `/incident/work-item/*` 系列接口。"
           },
           "item_type": {
-            "description": "跟进事项类型。`action`：挂在故障上的处置行动事项；`follow_up`：挂在故障复盘（Post-mortem）上的改进事项。",
+            "type": "string",
             "enum": [
               "action",
               "follow_up"
             ],
-            "type": "string"
+            "description": "跟进事项类型。`action`：挂在故障上的处置行动事项；`follow_up`：挂在故障复盘（Post-mortem）上的改进事项。"
           },
           "title": {
-            "description": "跟进事项标题。",
-            "type": "string"
+            "type": "string",
+            "description": "跟进事项标题。"
           },
-          "to_description": {
-            "description": "更新后的描述。",
-            "type": "string"
+          "from_title": {
+            "type": "string",
+            "description": "更新前的标题。"
           },
-          "to_priority": {
-            "description": "更新后的优先级标签。",
-            "type": "string"
+          "from_status": {
+            "type": "string",
+            "description": "更新前的状态，仅在状态变化时出现。通常为 `open`、`in_progress`、`done`、`cancelled` 之一；这些状态引入前创建的工作项可能是其他文本。"
           },
           "to_status": {
-            "description": "更新后的状态标签。",
-            "type": "string"
+            "type": "string",
+            "description": "更新后的状态，仅在状态变化时出现。`open` 未开始；`in_progress` 进行中；`done` 已完成；`cancelled` 已取消。",
+            "enum": [
+              "open",
+              "in_progress",
+              "done",
+              "cancelled"
+            ]
           },
-          "work_item_id": {
-            "description": "跟进事项 ID。",
-            "type": "string"
+          "from_priority": {
+            "type": "string",
+            "description": "更新前的优先级。由客户端自定义的优先级文本（最多 64 个字符），仅在优先级变化时出现。"
+          },
+          "to_priority": {
+            "type": "string",
+            "description": "更新后的优先级。由客户端自定义的优先级文本（最多 64 个字符），仅在优先级变化时出现。"
+          },
+          "from_description": {
+            "type": "string",
+            "description": "更新前的描述。"
+          },
+          "to_description": {
+            "type": "string",
+            "description": "更新后的描述。"
           }
         },
-        "title": "i_wi_updated",
-        "type": "object"
+        "title": "i_wi_updated"
       },
       "FeedItem": {
+        "type": "object",
         "description": "单条告警动态记录。`detail` 字段依 `type` 判别；具体结构参见各 `FeedDetailAlert*` schema。",
+        "required": [
+          "ref_id",
+          "type",
+          "detail",
+          "account_id",
+          "creator_id",
+          "created_at",
+          "updated_at"
+        ],
         "properties": {
-          "account_id": {
-            "description": "账户 ID。",
-            "format": "int64",
-            "type": "integer"
-          },
-          "created_at": {
-            "description": "创建时间，Unix 毫秒时间戳。",
-            "format": "int64",
-            "type": "integer"
-          },
-          "creator_id": {
-            "description": "创建者成员 ID。系统生成的记录为 0。",
-            "format": "int64",
-            "type": "integer"
+          "ref_id": {
+            "type": "string",
+            "pattern": "^[0-9a-fA-F]{24}$",
+            "description": "本条记录引用的告警 ObjectID。"
           },
-          "deleted_at": {
-            "description": "软删除时间，Unix 时间戳（毫秒）。未删除时不返回该字段。",
-            "format": "int64",
-            "type": "integer"
+          "type": {
+            "$ref": "#/components/schemas/AlertFeedType"
           },
           "detail": {
             "description": "类型特定的详情数据，结构由 `type` 决定。对未存储详情的条目可能为 `null`。",
-            "discriminator": {
-              "mapping": {
-                "a_ack": "#/components/schemas/FeedDetailAlertAck",
-                "a_close": "#/components/schemas/FeedDetailAlertClose",
-                "a_comm": "#/components/schemas/FeedDetailAlertComment",
-                "a_m_flapping": "#/components/schemas/FeedDetailAlertMuteByFlapping",
-                "a_m_inhibit": "#/components/schemas/FeedDetailAlertMuteByInhibit",
-                "a_m_silence": "#/components/schemas/FeedDetailAlertMuteBySilence",
-                "a_merge": "#/components/schemas/FeedDetailAlertMerge",
-                "a_new": "#/components/schemas/FeedDetailAlertTrigger",
-                "a_unack": "#/components/schemas/FeedDetailAlertUnack",
-                "a_update": "#/components/schemas/FeedDetailAlertUpdate"
-              },
-              "propertyName": "type"
-            },
             "oneOf": [
               {
                 "$ref": "#/components/schemas/FeedDetailAlertTrigger"
@@ -10636,20 +10806,47 @@
               {
                 "$ref": "#/components/schemas/FeedDetailAlertClose"
               }
-            ]
+            ],
+            "discriminator": {
+              "propertyName": "type",
+              "mapping": {
+                "a_new": "#/components/schemas/FeedDetailAlertTrigger",
+                "a_update": "#/components/schemas/FeedDetailAlertUpdate",
+                "a_comm": "#/components/schemas/FeedDetailAlertComment",
+                "a_merge": "#/components/schemas/FeedDetailAlertMerge",
+                "a_m_silence": "#/components/schemas/FeedDetailAlertMuteBySilence",
+                "a_m_inhibit": "#/components/schemas/FeedDetailAlertMuteByInhibit",
+                "a_m_flapping": "#/components/schemas/FeedDetailAlertMuteByFlapping",
+                "a_ack": "#/components/schemas/FeedDetailAlertAck",
+                "a_unack": "#/components/schemas/FeedDetailAlertUnack",
+                "a_close": "#/components/schemas/FeedDetailAlertClose"
+              }
+            }
           },
-          "ref_id": {
-            "description": "本条记录引用的告警 ObjectID。",
-            "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
+          "account_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "告警所属账户的 ID。"
           },
-          "type": {
-            "$ref": "#/components/schemas/AlertFeedType"
+          "creator_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "创建者成员 ID。系统生成的记录为 0。"
+          },
+          "created_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "创建时间，Unix 毫秒时间戳。"
           },
           "updated_at": {
-            "description": "最后更新时间，Unix 毫秒时间戳。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "最后更新时间，Unix 毫秒时间戳。"
+          },
+          "deleted_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "软删除时间，Unix 时间戳（毫秒）。未删除时不返回该字段。"
           },
           "via": {
             "type": "string",
@@ -10659,17 +10856,7 @@
             "type": "string",
             "description": "写入该记录的 AI SRE 会话 ID；非智能体写入时不返回该字段。"
           }
-        },
-        "required": [
-          "ref_id",
-          "type",
-          "detail",
-          "account_id",
-          "creator_id",
-          "created_at",
-          "updated_at"
-        ],
-        "type": "object"
+        }
       },
       "FeedSeverity": {
         "description": "严重等级。",
@@ -10682,28 +10869,30 @@
         "type": "string"
       },
       "FieldDeleteReference": {
+        "type": "object",
         "description": "仍引用该字段的自定义表单。",
+        "required": [
+          "kind",
+          "name",
+          "href"
+        ],
         "properties": {
-          "href": {
-            "description": "引用该字段的自定义表单控制台 URL。",
-            "type": "string"
-          },
           "kind": {
-            "const": "custom_form",
+            "type": "string",
             "description": "被引用资源类型。在此响应中始终为 `custom_form`。",
-            "type": "string"
+            "enum": [
+              "custom_form"
+            ]
           },
           "name": {
-            "description": "引用该字段的自定义表单类型名称（如 `解决故障` 表示解决故障表单）。",
-            "type": "string"
+            "type": "string",
+            "description": "引用该字段的自定义表单类型名称（如 `解决故障` 表示解决故障表单）。"
+          },
+          "href": {
+            "type": "string",
+            "description": "引用该字段的自定义表单控制台 URL。"
           }
-        },
-        "required": [
-          "kind",
-          "name",
-          "href"
-        ],
-        "type": "object"
+        }
       },
       "FieldDeleteReferenceError": {
         "description": "自定义表单仍引用该字段时返回的错误响应。",
@@ -10929,70 +11118,70 @@
         "type": "object"
       },
       "FilterCondition": {
+        "type": "object",
+        "required": [
+          "key",
+          "oper",
+          "vals"
+        ],
         "properties": {
           "key": {
-            "description": "过滤字段名。内置告警字段使用字段名（如 `alert_severity`、`alert_key`、`check`、`resource`、`service`、`cluster`），自定义标签使用 `labels.<name>` 前缀（如 `labels.env`、`labels.region`）。",
-            "type": "string"
+            "type": "string",
+            "description": "要匹配的字段。可用的内置字段取决于策略类型，见承载条件的字段说明；任意 `labels.<name>`（如 `labels.env`）始终可用。未知字段返回 `InvalidParameter`。告警或故障缺少该字段时，`IN` 不匹配，`NOTIN` 匹配。"
           },
           "oper": {
-            "description": "过滤操作符。`IN`：值必须匹配 `vals` 中的某一项；`NOTIN`：值不能匹配 `vals` 中任何一项。支持 `/pattern/` 格式的正则表达式。",
+            "type": "string",
             "enum": [
               "IN",
               "NOTIN"
             ],
-            "type": "string"
+            "description": "匹配操作符，区分大小写。`IN`：字段值匹配 `vals` 中任意一项即命中；`NOTIN`：与 `vals` 中所有项都不匹配才命中。"
           },
           "vals": {
-            "description": "匹配值列表。每一项为普通字符串或 `/regex/` 正则模式。",
-            "items": {
-              "type": "string"
-            },
-            "type": "array"
-          }
-        },
-        "required": [
-          "key",
-          "oper",
-          "vals"
-        ],
-        "type": "object"
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "要比较的值，至少一项。每项的匹配方式：普通字符串精确匹配；含 `*` 或 `?` 时按通配符匹配整个值；用斜杠包裹时按正则表达式匹配，如 `/^db-/`（可匹配值的任意位置）；`cidr:<网段>` 匹配 IP 范围，如 `cidr:203.0.113.0/24`；`num:<op>:<数字>` 做数值比较，`op` 为 `lt`、`le`、`gt`、`ge`，如 `num:gt:90`。"
+          }
+        }
       },
       "FilterGroup": {
         "$ref": "#/components/schemas/OrFilterGroup"
       },
       "Flapping": {
+        "type": "object",
         "description": "抖动检测配置。",
         "properties": {
-          "in_mins": {
-            "description": "观察窗口，单位分钟。",
-            "maximum": 1440,
-            "minimum": 1,
-            "type": "integer"
-          },
           "is_disabled": {
-            "description": "禁用抖动检测。",
-            "type": "boolean"
+            "type": "boolean",
+            "description": "为 true 时关闭抖动检测。"
           },
           "max_changes": {
-            "description": "`in_mins` 内允许的最大状态变更次数。",
-            "maximum": 100,
+            "type": "integer",
             "minimum": 2,
-            "type": "integer"
+            "maximum": 100,
+            "description": "`in_mins` 内允许的最大状态变化次数，2–100。不传或为 `0` 时三个值都使用默认值：4 次、`in_mins` 60、`mute_mins` 120。"
           },
-          "mute_mins": {
-            "description": "检测到抖动后的静音时长，单位分钟。",
+          "in_mins": {
+            "type": "integer",
+            "minimum": 1,
             "maximum": 1440,
+            "description": "观察窗口，单位分钟。"
+          },
+          "mute_mins": {
+            "type": "integer",
             "minimum": 0,
-            "type": "integer"
+            "maximum": 1440,
+            "description": "检测到抖动后的静音时长，单位分钟。"
           }
-        },
-        "type": "object"
+        }
       },
       "GetRemoteConfigRequest": {
         "description": "获取远程配置请求",
         "properties": {
           "application_id": {
-            "description": "RUM 应用 ID。",
+            "description": "RUM 应用 ID，可通过 `POST /rum/application/list` 获取。",
             "type": "string"
           }
         },
@@ -11005,7 +11194,15 @@
         "description": "当前生效的远程配置及其版本。",
         "properties": {
           "config": {
-            "$ref": "#/components/schemas/RemoteConfig"
+            "anyOf": [
+              {
+                "$ref": "#/components/schemas/RemoteConfig"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "线上生效的配置（最新发布的版本）。应用从未配置过时为 `null`。"
           },
           "updated_at": {
             "description": "Unix 时间戳（毫秒）—— 当前版本发布时间。从未配置时为 0。",
@@ -11017,31 +11214,40 @@
             "type": "integer"
           }
         },
-        "type": "object"
+        "type": "object",
+        "required": [
+          "config",
+          "version",
+          "updated_at"
+        ]
       },
       "GetWarRoomDefaultObserversRequest": {
+        "type": "object",
         "properties": {
           "incident_id": {
-            "description": "故障 ID，MongoDB ObjectID 十六进制字符串。",
-            "type": "string"
+            "type": "string",
+            "pattern": "^[0-9a-fA-F]{24}$",
+            "description": "故障 ID（MongoDB ObjectID）。"
           }
         },
         "required": [
           "incident_id"
-        ],
-        "type": "object"
+        ]
       },
       "GetWarRoomDefaultObserversResponse": {
+        "type": "object",
         "properties": {
           "observers": {
-            "description": "建议作为作战室默认观察者的历史响应人。",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/WarRoomPersonItem"
             },
-            "type": "array"
+            "description": "建议的观察者，按时间线顺序排列。没有时为空数组。"
           }
         },
-        "type": "object"
+        "required": [
+          "observers"
+        ]
       },
       "GetWarRoomDetailRequest": {
         "description": "获取战情室实时详情的参数。",
@@ -11063,130 +11269,130 @@
         "type": "object"
       },
       "GetWebhookHistoryDetailRequest": {
+        "type": "object",
         "description": "获取单条 Webhook 推送详情的参数。",
+        "required": [
+          "event_id",
+          "integration_id"
+        ],
         "properties": {
           "event_id": {
-            "description": "由 `ListWebhookHistory` 返回的事件 ID。",
-            "type": "string"
+            "type": "string",
+            "description": "`POST /webhook/history/list` 返回记录中的 `event_id`。它以推送日期（`YYYYMMDD`）开头，缺少该前缀时请求失败。"
           },
           "integration_id": {
-            "description": "事件所属的集成 ID，可从 `POST /webhook/history/list` 的返回项中获取。",
+            "type": "integer",
             "format": "int64",
             "minimum": 1,
-            "type": "integer"
+            "description": "事件所属的集成 ID，可从 `POST /webhook/history/list` 的返回项中获取。"
           }
-        },
-        "required": [
-          "event_id",
-          "integration_id"
-        ],
-        "type": "object"
+        }
       },
       "Group": {
+        "type": "object",
         "description": "告警聚合配置。",
+        "required": [
+          "method"
+        ],
         "properties": {
-          "all_equals_required": {
-            "description": "为 true 时要求所有键同时存在才能参与聚合。",
-            "type": "boolean"
+          "method": {
+            "type": "string",
+            "enum": [
+              "i",
+              "p",
+              "n"
+            ],
+            "description": "聚合方式：\n- `n`：不聚合，每条新告警单独生成故障。\n- `p`：按 `equals` 与 `cases` 中的字段规则聚合，需要 Standard 及以上许可证。\n- `i`：按内容相似度智能聚合（见 `i_keys`、`i_score_threshold`），需要 Pro 许可证。"
+          },
+          "equals": {
+            "type": "array",
+            "items": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "maxItems": 5,
+            "description": "规则聚合（`p`）使用的字段组，最多 5 组。新告警与活跃故障在任意一组的所有字段上取值都相同时并入该故障。可用字段：`title`、`description`、`severity` 或 `labels.<name>`；每组不能为空。`p` 模式下 `equals` 与 `cases` 至少提供其一。"
           },
           "cases": {
+            "type": "array",
+            "maxItems": 100,
             "description": "按过滤条件的聚合策略覆盖。",
             "items": {
+              "type": "object",
               "description": "条件化聚合覆盖：命中 `if` 的已存告警按 `equals` 键聚合，而不使用顶层聚合键。",
+              "required": [
+                "if",
+                "equals"
+              ],
               "properties": {
-                "equals": {
-                  "description": "命中告警使用的聚合键。可选值：`title`、`description`、`severity` 或任意 `labels.<name>`。",
-                  "items": {
-                    "type": "string"
-                  },
-                  "maxItems": 5,
-                  "minItems": 1,
-                  "type": "array"
-                },
                 "if": {
+                  "type": "array",
                   "description": "针对已存告警字段的匹配条件，条件之间为 AND 关系。",
                   "items": {
                     "$ref": "#/components/schemas/FilterCondition"
+                  }
+                },
+                "equals": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
                   },
-                  "type": "array"
+                  "minItems": 1,
+                  "maxItems": 5,
+                  "description": "命中告警使用的聚合键。可选值：`title`、`description`、`severity` 或任意 `labels.<name>`。"
                 }
-              },
-              "required": [
-                "if",
-                "equals"
-              ],
-              "type": "object"
-            },
-            "maxItems": 100,
-            "type": "array"
-          },
-          "equals": {
-            "description": "用于聚合判定的 label 键分组。",
-            "items": {
-              "items": {
-                "type": "string"
-              },
-              "type": "array"
-            },
-            "maxItems": 5,
-            "type": "array"
+              }
+            }
           },
-          "i_keys": {
-            "description": "用于智能聚合向量化的 label 键。",
-            "items": {
-              "type": "string"
-            },
-            "maxItems": 10,
-            "type": "array"
+          "all_equals_required": {
+            "type": "boolean",
+            "description": "为 true 时，只有告警上存在该组全部字段才可匹配；为 false 时，缺失字段按空值比较，但该组至少要有一个字段存在。"
           },
-          "i_score_threshold": {
-            "description": "智能聚合相似度阈值。",
-            "format": "float",
-            "maximum": 1,
-            "minimum": 0.5,
-            "type": "number"
+          "time_window": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "聚合时间窗口，单位分钟。默认最大值为 1440 分钟（24 小时）；开启扩展功能的账号最大可设置 43200 分钟（30 天）。"
           },
-          "method": {
-            "description": "聚合方式：`i` 智能、`p` 规则、`n` 不聚合。",
+          "window_type": {
+            "type": "string",
             "enum": [
-              "i",
-              "p",
-              "n"
+              "tumbling",
+              "sliding"
             ],
-            "type": "string"
+            "description": "窗口类型，默认 `tumbling`。`tumbling` 为固定窗口，自故障创建时间起算，窗口到期后新告警会开启新故障；`sliding` 为滑动窗口，自故障最近一次告警时间起算，每有新告警并入即向后顺延。"
           },
           "storm_threshold": {
-            "description": "告警风暴阈值。",
-            "maximum": 10000,
+            "type": "integer",
             "minimum": 0,
-            "type": "integer"
+            "maximum": 10000,
+            "description": "旧版单级风暴阈值；仅当 `storm_thresholds` 为空且取值大于 1 时生效。`0` 表示关闭。"
           },
           "storm_thresholds": {
-            "description": "多级告警风暴阈值。",
+            "type": "array",
             "items": {
               "type": "integer"
             },
             "maxItems": 5,
-            "type": "array"
+            "description": "触发故障风暴事件的告警数：并入同一故障的告警数达到某个阈值时发送风暴通知。最多 5 个值，每个至少为 2，自动去重并排序。"
           },
-          "time_window": {
-            "description": "聚合时间窗口，单位分钟。默认最大值为 1440 分钟（24 小时）；开启扩展功能的账号最大可设置 43200 分钟（30 天）。",
-            "minimum": 0,
-            "type": "integer"
+          "i_keys": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "maxItems": 10,
+            "description": "智能聚合（`i`）使用的字段，最多 10 个：`title`、`description`、`severity` 或 `labels.<name>`。为空时使用 `title`、`description`、`labels.service`、`labels.resource`。"
           },
-          "window_type": {
-            "description": "窗口类型，默认 `tumbling`。`tumbling` 为固定窗口，自故障创建时间起算，窗口到期后新告警会开启新故障；`sliding` 为滑动窗口，自故障最近一次告警时间起算，每有新告警并入即向后顺延。",
-            "enum": [
-              "tumbling",
-              "sliding"
-            ],
-            "type": "string"
+          "i_score_threshold": {
+            "type": "number",
+            "format": "float",
+            "minimum": 0.5,
+            "maximum": 1,
+            "description": "智能聚合把告警并入已有故障所需的最低相似度，0.5–1。不传或为 `0` 时使用 0.9。"
           }
-        },
-        "required": [
-          "method"
-        ],
-        "type": "object"
+        }
       },
       "IDRequest": {
         "description": "包含单个数字 ID 的请求。",
@@ -11203,111 +11409,111 @@
         "type": "object"
       },
       "Image": {
+        "type": "object",
         "description": "图片或附件引用。",
+        "required": [
+          "src"
+        ],
         "properties": {
-          "alt": {
-            "description": "替代文本。",
-            "type": "string"
+          "src": {
+            "type": "string",
+            "description": "图片来源，可以是 `img_` 上传 token 或 `http(s)` URL。"
           },
           "href": {
-            "description": "可选的图片跳转链接。",
-            "type": "string"
+            "type": "string",
+            "description": "可选的图片跳转链接。"
           },
-          "src": {
-            "description": "图片来源，可以是 `img_` 上传 token 或 `http(s)` URL。",
-            "type": "string"
+          "alt": {
+            "type": "string",
+            "description": "图片无法显示时展示的替代文字；未设置时为空。"
           }
-        },
-        "required": [
-          "src"
-        ],
-        "type": "object"
+        }
       },
       "ImportStatusPageSubscriberItem": {
+        "type": "object",
         "description": "单个待导入的订阅者。",
+        "required": [
+          "recipient"
+        ],
         "properties": {
-          "all": {
-            "description": "为 true 时订阅所有组件。当 `component_ids` 与 `change_ids` 均为空时必须为 true。",
-            "type": "boolean"
+          "recipient": {
+            "type": "string",
+            "maxLength": 255,
+            "description": "邮箱地址（公开状态页）或用户 ID（内部状态页）。"
           },
-          "change_ids": {
-            "description": "订阅者需要接收通知的特定事件 ID 列表。",
+          "component_ids": {
+            "type": "array",
             "items": {
-              "format": "int64",
-              "type": "integer"
+              "type": "string"
             },
-            "type": "array"
+            "description": "订阅者需要接收通知的组件 ID 列表。"
           },
-          "component_ids": {
-            "description": "订阅者需要接收通知的组件 ID 列表。",
+          "change_ids": {
+            "type": "array",
             "items": {
-              "type": "string"
+              "type": "integer",
+              "format": "int64"
             },
-            "type": "array"
+            "description": "订阅者需要接收通知的特定事件 ID 列表。"
           },
-          "locale": {
-            "description": "通知的首选语言。留空时使用请求语言。",
-            "type": "string"
+          "all": {
+            "type": "boolean",
+            "description": "为 `true` 时订阅者接收全部组件和事件的通知，并忽略 `component_ids`/`change_ids`。两个列表都为空时必须为 `true`。"
           },
-          "recipient": {
-            "description": "邮箱地址（公开状态页）或用户 ID（内部状态页）。",
-            "maxLength": 255,
-            "type": "string"
+          "locale": {
+            "type": "string",
+            "description": "通知的首选语言。留空时使用请求语言。"
           }
-        },
-        "required": [
-          "recipient"
-        ],
-        "type": "object"
+        }
       },
       "ImportStatusPageSubscribersRequest": {
+        "type": "object",
         "description": "批量导入订阅者所需的参数。每个订阅者的 `recipient` 非空且不超过 255 字符；并且至少订阅一个组件/事件，或将 `all` 置为 true。",
+        "required": [
+          "page_id",
+          "method"
+        ],
         "properties": {
+          "page_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "目标状态页 ID，可通过 `GET /status-page/list` 获取。"
+          },
           "method": {
-            "description": "订阅通知方式。`email` 仅适用于公开状态页，`im` 仅适用于内部状态页。",
+            "type": "string",
             "enum": [
               "email",
               "im"
             ],
-            "type": "string"
-          },
-          "page_id": {
-            "description": "目标状态页 ID，可通过 `GET /status-page/list` 获取。",
-            "format": "int64",
-            "type": "integer"
+            "description": "订阅通知方式。`email` 仅适用于公开状态页，`im` 仅适用于内部状态页。"
           },
           "subscribers": {
-            "description": "要导入的订阅者列表。",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/ImportStatusPageSubscriberItem"
             },
-            "type": "array"
+            "description": "要导入的订阅者。每个接收人在该状态页上已有的订阅会被替换；省略或传空数组时不做任何操作。"
           }
-        },
-        "required": [
-          "page_id",
-          "method"
-        ],
-        "type": "object"
+        }
       },
       "IncProgressCnts": {
+        "type": "object",
+        "required": [
+          "Triggered",
+          "Processing"
+        ],
         "properties": {
-          "Processing": {
-            "description": "近 30 天处理中的故障数量。",
+          "Triggered": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "近 30 天内开始、仍处于 `Triggered`（未认领）的故障数。"
           },
-          "Triggered": {
-            "description": "近 30 天触发中的故障数量。",
+          "Processing": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "近 30 天内开始、处于 `Processing`（已认领、未关闭）的故障数。"
           }
-        },
-        "required": [
-          "Triggered",
-          "Processing"
-        ],
-        "type": "object"
+        }
       },
       "IncidentActionImage": {
         "description": "附加到认领或解决故障时间线记录的图片。",
@@ -11331,9 +11537,23 @@
         "type": "object"
       },
       "IncidentCardHiddenFields": {
+        "type": "object",
+        "description": "按 IM 应用类型隐藏的故障卡片字段。只接受受支持的 IM 应用类型和字段名。",
+        "propertyNames": {
+          "type": "string",
+          "enum": [
+            "feishu_app",
+            "dingtalk_app",
+            "slack_app",
+            "teams_app",
+            "wecom_app"
+          ]
+        },
         "additionalProperties": {
-          "description": "要为该 IM 应用隐藏的故障卡片字段名。",
+          "type": "array",
+          "description": "要在该应用故障卡片上隐藏的字段：`channel`（协作空间名称）、`snoozed_before`（暂停截止时间）、`severity`（严重程度）、`responders`（处理人）、`aggregate_alert_count`（合并的告警数）、`detail`（详情按钮）、`ai_analysis`（AI 分析按钮）。",
           "items": {
+            "type": "string",
             "enum": [
               "channel",
               "snoozed_before",
@@ -11342,23 +11562,9 @@
               "aggregate_alert_count",
               "detail",
               "ai_analysis"
-            ],
-            "type": "string"
-          },
-          "type": "array"
-        },
-        "description": "按 IM 应用类型隐藏的故障卡片字段。只接受受支持的 IM 应用类型和字段名。",
-        "propertyNames": {
-          "enum": [
-            "feishu_app",
-            "dingtalk_app",
-            "slack_app",
-            "teams_app",
-            "wecom_app"
-          ],
-          "type": "string"
-        },
-        "type": "object"
+            ]
+          }
+        }
       },
       "IncidentCommentTypeDisplay": {
         "description": "账户级评论类型的解析后展示信息，读取时根据当前类型定义填充。",
@@ -11449,69 +11655,28 @@
         "type": "object"
       },
       "IncidentFeedItem": {
+        "type": "object",
         "description": "单条故障时间线条目。`detail` 字段由 `type` 决定具体结构，详见各 `FeedDetail*` 结构。",
+        "required": [
+          "ref_id",
+          "type",
+          "detail",
+          "account_id",
+          "creator_id",
+          "created_at",
+          "updated_at"
+        ],
         "properties": {
-          "account_id": {
-            "description": "账号 ID。",
-            "format": "int64",
-            "type": "integer"
-          },
-          "created_at": {
-            "description": "创建时间戳（毫秒）。",
-            "format": "int64",
-            "type": "integer"
-          },
-          "creator_id": {
-            "description": "操作人成员 ID，`0` 表示系统生成。",
-            "format": "int64",
-            "type": "integer"
+          "ref_id": {
+            "type": "string",
+            "pattern": "^[0-9a-fA-F]{24}$",
+            "description": "条目所属故障的 ID，等于请求中的 `incident_id`。"
           },
-          "deleted_at": {
-            "description": "软删除时间戳（毫秒），未删除时为 0。",
-            "format": "int64",
-            "type": "integer"
+          "type": {
+            "$ref": "#/components/schemas/IncidentFeedType"
           },
           "detail": {
             "description": "由 `type` 决定的具体载荷；条目无结构化详情时为 `null`。",
-            "discriminator": {
-              "mapping": {
-                "a_merge": "#/components/schemas/FeedDetailAlertMerge",
-                "i_a_rspd": "#/components/schemas/FeedDetailIncidentAddRspd",
-                "i_ack": "#/components/schemas/FeedDetailIncidentAck",
-                "i_assign": "#/components/schemas/FeedDetailIncidentAssign",
-                "i_auto_refresh": "#/components/schemas/FeedDetailIncidentAutoRefreshCard",
-                "i_comm": "#/components/schemas/FeedDetailIncidentComment",
-                "i_custom": "#/components/schemas/FeedDetailIncidentCustomAction",
-                "i_m_flapping": "#/components/schemas/FeedDetailIncidentMuteByFlapping",
-                "i_m_reply": "#/components/schemas/FeedDetailIncidentMuteReply",
-                "i_merge": "#/components/schemas/FeedDetailIncidentMerge",
-                "i_new": "#/components/schemas/FeedDetailIncidentNew",
-                "i_notify": "#/components/schemas/FeedDetailIncidentNotify",
-                "i_r_desc": "#/components/schemas/FeedDetailIncidentResetDescription",
-                "i_r_field": "#/components/schemas/FeedDetailIncidentResetField",
-                "i_r_impact": "#/components/schemas/FeedDetailIncidentResetImpact",
-                "i_r_rc": "#/components/schemas/FeedDetailIncidentResetRootCause",
-                "i_r_rsltn": "#/components/schemas/FeedDetailIncidentResetResolution",
-                "i_r_severity": "#/components/schemas/FeedDetailIncidentResetSeverity",
-                "i_r_title": "#/components/schemas/FeedDetailIncidentResetTitle",
-                "i_reopen": "#/components/schemas/FeedDetailIncidentReopen",
-                "i_rslv": "#/components/schemas/FeedDetailIncidentResolve",
-                "i_snooze": "#/components/schemas/FeedDetailIncidentSnooze",
-                "i_storm": "#/components/schemas/FeedDetailIncidentStorm",
-                "i_unack": "#/components/schemas/FeedDetailIncidentUnack",
-                "i_wake": "#/components/schemas/FeedDetailIncidentWake",
-                "i_wi_assignees": "#/components/schemas/FeedDetailWorkItemAssigneesChanged",
-                "i_wi_bound": "#/components/schemas/FeedDetailWorkItemBound",
-                "i_wi_completed": "#/components/schemas/FeedDetailWorkItemCompleted",
-                "i_wi_converted": "#/components/schemas/FeedDetailWorkItemConverted",
-                "i_wi_created": "#/components/schemas/FeedDetailWorkItemCreated",
-                "i_wi_deleted": "#/components/schemas/FeedDetailWorkItemDeleted",
-                "i_wi_updated": "#/components/schemas/FeedDetailWorkItemUpdated",
-                "i_wr_create": "#/components/schemas/FeedDetailIncidentWarRoomCreate",
-                "i_wr_delete": "#/components/schemas/FeedDetailIncidentWarRoomDelete"
-              },
-              "propertyName": "type"
-            },
             "oneOf": [
               {
                 "$ref": "#/components/schemas/FeedDetailIncidentNew"
@@ -11614,36 +11779,118 @@
               },
               {
                 "$ref": "#/components/schemas/FeedDetailAlertMerge"
+              },
+              {
+                "type": "object",
+                "title": "i_wi_auto_converted",
+                "description": "`i_wi_auto_converted` 的详情。",
+                "properties": {
+                  "count": {
+                    "type": "integer",
+                    "description": "被转为后续行动的行动项数量。"
+                  },
+                  "work_item_ids": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    },
+                    "description": "被转换的工作项 ID。"
+                  },
+                  "titles": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    },
+                    "description": "被转换工作项的标题，顺序与 `work_item_ids` 一致。"
+                  },
+                  "post_mortem_id": {
+                    "type": "string",
+                    "description": "后续行动绑定的复盘报告 ID；故障没有复盘报告时为空。"
+                  }
+                }
               }
-            ]
+            ],
+            "discriminator": {
+              "propertyName": "type",
+              "mapping": {
+                "i_new": "#/components/schemas/FeedDetailIncidentNew",
+                "i_assign": "#/components/schemas/FeedDetailIncidentAssign",
+                "i_a_rspd": "#/components/schemas/FeedDetailIncidentAddRspd",
+                "i_notify": "#/components/schemas/FeedDetailIncidentNotify",
+                "i_storm": "#/components/schemas/FeedDetailIncidentStorm",
+                "i_snooze": "#/components/schemas/FeedDetailIncidentSnooze",
+                "i_wake": "#/components/schemas/FeedDetailIncidentWake",
+                "i_ack": "#/components/schemas/FeedDetailIncidentAck",
+                "i_unack": "#/components/schemas/FeedDetailIncidentUnack",
+                "i_comm": "#/components/schemas/FeedDetailIncidentComment",
+                "i_rslv": "#/components/schemas/FeedDetailIncidentResolve",
+                "i_reopen": "#/components/schemas/FeedDetailIncidentReopen",
+                "i_merge": "#/components/schemas/FeedDetailIncidentMerge",
+                "i_r_title": "#/components/schemas/FeedDetailIncidentResetTitle",
+                "i_r_desc": "#/components/schemas/FeedDetailIncidentResetDescription",
+                "i_r_impact": "#/components/schemas/FeedDetailIncidentResetImpact",
+                "i_r_rc": "#/components/schemas/FeedDetailIncidentResetRootCause",
+                "i_r_rsltn": "#/components/schemas/FeedDetailIncidentResetResolution",
+                "i_r_severity": "#/components/schemas/FeedDetailIncidentResetSeverity",
+                "i_r_field": "#/components/schemas/FeedDetailIncidentResetField",
+                "i_m_flapping": "#/components/schemas/FeedDetailIncidentMuteByFlapping",
+                "i_m_reply": "#/components/schemas/FeedDetailIncidentMuteReply",
+                "i_custom": "#/components/schemas/FeedDetailIncidentCustomAction",
+                "i_wr_create": "#/components/schemas/FeedDetailIncidentWarRoomCreate",
+                "i_wr_delete": "#/components/schemas/FeedDetailIncidentWarRoomDelete",
+                "i_auto_refresh": "#/components/schemas/FeedDetailIncidentAutoRefreshCard",
+                "i_wi_created": "#/components/schemas/FeedDetailWorkItemCreated",
+                "i_wi_updated": "#/components/schemas/FeedDetailWorkItemUpdated",
+                "i_wi_assignees": "#/components/schemas/FeedDetailWorkItemAssigneesChanged",
+                "i_wi_completed": "#/components/schemas/FeedDetailWorkItemCompleted",
+                "i_wi_converted": "#/components/schemas/FeedDetailWorkItemConverted",
+                "i_wi_bound": "#/components/schemas/FeedDetailWorkItemBound",
+                "i_wi_deleted": "#/components/schemas/FeedDetailWorkItemDeleted",
+                "a_merge": "#/components/schemas/FeedDetailAlertMerge"
+              }
+            }
           },
-          "ref_id": {
-            "description": "引用对象 ObjectID，根据 type 不同可能指向故障或告警。",
-            "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
+          "account_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "该记录所属账户的 ID；同一 `app_key` 返回的记录该值都相同。"
           },
-          "type": {
-            "$ref": "#/components/schemas/IncidentFeedType"
+          "creator_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "操作人成员 ID，`0` 表示系统生成。"
+          },
+          "deleted_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "软删除时间戳（毫秒），未删除时为 0。"
+          },
+          "created_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "创建时间戳（毫秒）。"
           },
           "updated_at": {
-            "description": "最后更新时间戳（毫秒）。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "最后更新时间戳（毫秒）。"
+          },
+          "via": {
+            "type": "string",
+            "enum": [
+              "ai_sre"
+            ],
+            "description": "由 AI SRE 代 `creator_id` 执行操作时为 `ai_sre`；直接操作时省略。"
+          },
+          "agent_session_id": {
+            "type": "string",
+            "description": "执行该操作的 AI SRE 会话 ID；仅在 `via` 为 `ai_sre` 且记录了会话时出现。"
           }
-        },
-        "required": [
-          "ref_id",
-          "type",
-          "detail",
-          "account_id",
-          "creator_id",
-          "created_at",
-          "updated_at"
-        ],
-        "type": "object"
+        }
       },
       "IncidentFeedType": {
-        "description": "故障时间线条目类型。每个值对应一个生命周期事件，其 `detail` 载荷结构由该字段决定。故障级事件前缀为 `i_`；向上冒泡到故障时间线的告警级事件前缀为 `a_`。\n\n| 类型 | 含义 |\n|---|---|\n| `i_new` | 故障创建：系统自动或人工创建了新故障。 |\n| `i_assign` | 分派响应人：故障被分派给指定人员处理。 |\n| `i_a_rspd` | 添加响应人：有新的响应人被加入处理。 |\n| `i_notify` | 通过某个渠道在指定环节发送通知。 |\n| `i_storm` | 故障触发告警风暴阈值。 |\n| `i_snooze` | 暂停通知指定时长。 |\n| `i_wake` | 取消暂停并恢复通知。 |\n| `i_ack` | 确认故障：响应人确认已开始处理故障。 |\n| `i_unack` | 取消认领。 |\n| `i_comm` | 添加评论：响应人记录了处理进展或关键信息。 |\n| `i_rslv` | 解决故障：故障被标记为已解决。 |\n| `i_reopen` | 重新打开：已解决的故障被重新打开，可能问题复发。 |\n| `i_merge` | 合并故障：多个相关故障被合并为一个。 |\n| `i_r_title` | 标题更新。 |\n| `i_r_desc` | 描述更新。 |\n| `i_r_impact` | 影响范围更新。 |\n| `i_r_rc` | 根因更新。 |\n| `i_r_rsltn` | 解决方案更新。 |\n| `i_r_severity` | 严重等级变更：故障的严重程度被调整。 |\n| `i_r_field` | 自定义字段值更新。 |\n| `i_m_flapping` | 因抖动检测被静默。 |\n| `i_m_reply` | 评论静音回复标记。 |\n| `i_custom` | 执行动作：触发了自动化操作或脚本。 |\n| `i_wr_create` | 创建作战室：建立了即时通讯群组用于协作处理。 |\n| `i_wr_delete` | 删除作战室群组。 |\n| `i_auto_refresh` | 卡片自动刷新事件。 |\n| `i_wi_created` | 跟进事项创建：创建了行动项或后续行动。 |\n| `i_wi_updated` | 跟进事项更新：标题、描述、状态或优先级发生变化。 |\n| `i_wi_assignees` | 跟进事项负责人变更：负责人被更新。 |\n| `i_wi_completed` | 跟进事项完成：负责人将跟进事项标记为完成。 |\n| `i_wi_converted` | 跟进事项转化：行动项被转化为后续行动。 |\n| `i_wi_bound` | 跟进事项绑定：已转化的后续行动被绑定到故障复盘。 |\n| `i_wi_deleted` | 跟进事项删除：行动项或后续行动被软删除。 |\n| `a_merge` | 告警合并：一条告警被合并进已有故障。 |",
+        "type": "string",
+        "description": "故障时间线条目类型。每个值对应一个生命周期事件，其 `detail` 载荷结构由该字段决定。故障级事件前缀为 `i_`；向上冒泡到故障时间线的告警级事件前缀为 `a_`。\n\n| 类型 | 含义 |\n|---|---|\n| `i_new` | 故障创建：系统自动或人工创建了新故障。 |\n| `i_assign` | 分派响应人：故障被分派给指定人员处理。 |\n| `i_a_rspd` | 添加响应人：有新的响应人被加入处理。 |\n| `i_notify` | 通过某个渠道在指定环节发送通知。 |\n| `i_storm` | 故障触发告警风暴阈值。 |\n| `i_snooze` | 暂停通知指定时长。 |\n| `i_wake` | 取消暂停并恢复通知。 |\n| `i_ack` | 确认故障：响应人确认已开始处理故障。 |\n| `i_unack` | 取消认领。 |\n| `i_comm` | 添加评论：响应人记录了处理进展或关键信息。 |\n| `i_rslv` | 解决故障：故障被标记为已解决。 |\n| `i_reopen` | 重新打开：已解决的故障被重新打开，可能问题复发。 |\n| `i_merge` | 合并故障：多个相关故障被合并为一个。 |\n| `i_r_title` | 标题更新。 |\n| `i_r_desc` | 描述更新。 |\n| `i_r_impact` | 影响范围更新。 |\n| `i_r_rc` | 根因更新。 |\n| `i_r_rsltn` | 解决方案更新。 |\n| `i_r_severity` | 严重等级变更：故障的严重程度被调整。 |\n| `i_r_field` | 自定义字段值更新。 |\n| `i_m_flapping` | 因抖动检测被静默。 |\n| `i_m_reply` | 评论静音回复标记。 |\n| `i_custom` | 执行动作：触发了自动化操作或脚本。 |\n| `i_wr_create` | 创建作战室：建立了即时通讯群组用于协作处理。 |\n| `i_wr_delete` | 删除作战室群组。 |\n| `i_auto_refresh` | 卡片自动刷新事件。 |\n| `i_wi_created` | 跟进事项创建：创建了行动项或后续行动。 |\n| `i_wi_updated` | 跟进事项更新：标题、描述、状态或优先级发生变化。 |\n| `i_wi_assignees` | 跟进事项负责人变更：负责人被更新。 |\n| `i_wi_completed` | 跟进事项完成：负责人将跟进事项标记为完成。 |\n| `i_wi_converted` | 跟进事项转化：行动项被转化为后续行动。 |\n| `i_wi_bound` | 跟进事项绑定：已转化的后续行动被绑定到故障复盘。 |\n| `i_wi_deleted` | 跟进事项删除：行动项或后续行动被软删除。 |\n| `i_wi_auto_converted` | 工作项自动转换：关闭故障时，未完成的行动项被转为后续行动。 |\n| `a_merge` | 告警合并：一条告警被合并进已有故障。 |",
         "enum": [
           "i_new",
           "i_assign",
@@ -11678,399 +11925,436 @@
           "i_wi_converted",
           "i_wi_bound",
           "i_wi_deleted",
+          "i_wi_auto_converted",
           "a_merge"
+        ]
+      },
+      "IncidentInfo": {
+        "type": "object",
+        "description": "故障详细信息。",
+        "required": [
+          "incident_id",
+          "account_id",
+          "channel_id",
+          "team_id",
+          "integration_id",
+          "integration_ids",
+          "integration_types",
+          "dedup_key",
+          "equals_md5",
+          "start_time",
+          "end_time",
+          "last_time",
+          "ack_time",
+          "close_time",
+          "creator_id",
+          "closer_id",
+          "owner_id",
+          "incident_status",
+          "incident_severity",
+          "progress",
+          "title",
+          "description",
+          "ai_summary",
+          "impact",
+          "root_cause",
+          "resolution",
+          "num",
+          "created_at",
+          "updated_at",
+          "snoozed_before",
+          "group_method",
+          "ever_muted",
+          "labels",
+          "fields",
+          "assigned_to",
+          "alert_cnt",
+          "active_alert_cnt",
+          "alert_event_cnt",
+          "responders",
+          "account_name",
+          "account_locale",
+          "account_time_zone",
+          "channel_name",
+          "channel_status",
+          "detail_url",
+          "silence_url",
+          "post_mortem_id",
+          "images",
+          "manual_overrides",
+          "has_unfinished_work_item"
         ],
-        "type": "string"
-      },
-      "IncidentInfo": {
-        "description": "故障详细信息。",
         "properties": {
-          "account_id": {
-            "description": "所属账号 ID。",
-            "format": "int64",
-            "type": "integer"
-          },
-          "account_locale": {
-            "description": "账号语言。",
-            "type": "string"
-          },
-          "account_name": {
-            "description": "账号名称。",
-            "type": "string"
-          },
-          "account_time_zone": {
-            "description": "账号时区。",
-            "type": "string"
+          "incident_id": {
+            "type": "string",
+            "pattern": "^[0-9a-fA-F]{24}$",
+            "description": "故障 ID（MongoDB ObjectID）。"
           },
-          "ack_time": {
-            "description": "首次认领的 Unix 时间戳（秒），未认领时为 0。",
+          "account_id": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "所属账号 ID。"
           },
-          "active_alert_cnt": {
-            "description": "当前处于 Critical/Warning/Info 状态的告警数量。",
+          "channel_id": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
-          },
-          "ai_summary": {
-            "description": "AI 生成的故障摘要。",
-            "type": "string"
+            "description": "协作空间 ID，独立故障为 0。"
           },
-          "alert_cnt": {
-            "description": "合并到此故障的告警总数。",
+          "team_id": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "故障所属协作空间的团队 ID；协作空间无团队时为 0。"
           },
-          "alert_event_cnt": {
-            "description": "所有合并告警的原始事件总数。",
+          "integration_id": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "故障关联的首个集成 ID。"
           },
-          "alerts": {
-            "description": "关联告警列表，仅在通知模板与自定义动作中填充。",
+          "integration_ids": {
+            "type": [
+              "array",
+              "null"
+            ],
             "items": {
-              "$ref": "#/components/schemas/AlertInfo"
+              "type": "integer",
+              "format": "int64"
             },
-            "type": "array"
+            "description": "为该故障贡献告警的全部集成 ID；没有集成的故障（如手动创建的故障）为 `null`。"
           },
-          "assigned_to": {
-            "$ref": "#/components/schemas/AssignedTo",
-            "description": "故障当前的指派对象。"
-          },
-          "channel_id": {
-            "description": "协作空间 ID，独立故障为 0。",
-            "format": "int64",
-            "type": "integer"
+          "integration_types": {
+            "type": [
+              "array",
+              "null"
+            ],
+            "items": {
+              "type": "string"
+            },
+            "description": "全部贡献集成的插件类型（含义见 `integration_type`）；没有时为 `null`。"
           },
-          "channel_name": {
-            "description": "协作空间名称。",
-            "type": "string"
+          "dedup_key": {
+            "type": "string",
+            "description": "合并告警时使用的去重键。"
           },
-          "channel_status": {
-            "description": "协作空间状态。",
-            "type": "string"
+          "equals_md5": {
+            "type": "string",
+            "description": "用于内容比对的 MD5 哈希。"
           },
-          "close_time": {
-            "description": "关闭时间的 Unix 时间戳（秒），仍开启时为 0。",
+          "start_time": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "故障开始的 Unix 时间戳（秒）。"
           },
-          "closer": {
-            "$ref": "#/components/schemas/PersonShort",
-            "description": "关闭人信息。"
+          "end_time": {
+            "type": "integer",
+            "format": "int64",
+            "description": "故障结束的 Unix 时间戳（秒），仍活跃时为 0。"
           },
-          "closer_id": {
-            "description": "关闭者成员 ID，自动关闭时为 0。",
+          "last_time": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "最近一次更新的 Unix 时间戳（秒）。"
           },
-          "created_at": {
-            "description": "创建时间戳（秒）。",
+          "ack_time": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "首次认领的 Unix 时间戳（秒），未认领时为 0。"
           },
-          "creator": {
-            "$ref": "#/components/schemas/PersonShort",
-            "description": "创建人信息。"
+          "close_time": {
+            "type": "integer",
+            "format": "int64",
+            "description": "关闭时间的 Unix 时间戳（秒），仍开启时为 0。"
           },
           "creator_id": {
-            "description": "创建者成员 ID，系统自动创建时为 0。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "创建者成员 ID，系统自动创建时为 0。"
           },
-          "data_source_id": {
-            "deprecated": true,
-            "description": "已废弃。请使用 `integration_id`。",
+          "closer_id": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "关闭者成员 ID，自动关闭时为 0。"
           },
-          "data_source_ids": {
-            "deprecated": true,
-            "description": "已废弃。请使用 `integration_ids`。",
-            "items": {
-              "format": "int64",
-              "type": "integer"
-            },
-            "type": "array"
+          "owner_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "主负责人成员 ID，无则为 0。"
           },
-          "data_source_type": {
-            "deprecated": true,
-            "description": "已废弃。请使用 `integration_type`。",
-            "type": "string"
+          "incident_status": {
+            "type": "string",
+            "enum": [
+              "Critical",
+              "Warning",
+              "Info",
+              "Ok"
+            ],
+            "description": "当前故障状态，由告警状态推导。"
           },
-          "data_source_types": {
-            "deprecated": true,
-            "description": "已废弃。请使用 `integration_types`。",
-            "items": {
-              "type": "string"
-            },
-            "type": "array"
+          "incident_severity": {
+            "type": "string",
+            "enum": [
+              "Critical",
+              "Warning",
+              "Info",
+              "Ok"
+            ],
+            "description": "配置的故障严重程度。"
           },
-          "dedup_key": {
-            "description": "合并告警时使用的去重键。",
-            "type": "string"
+          "progress": {
+            "type": "string",
+            "enum": [
+              "Triggered",
+              "Processing",
+              "Closed"
+            ],
+            "description": "故障进展状态。`Triggered` 已触发待认领；`Processing` 已认领处理中（取消认领会回到 `Triggered`）；`Closed` 已关闭。"
           },
-          "deleted_at": {
-            "description": "软删除时间戳（秒），未删除时为 0。",
-            "format": "int64",
-            "type": "integer"
+          "title": {
+            "type": "string",
+            "description": "故障标题。"
           },
           "description": {
-            "description": "故障描述。",
-            "type": "string"
+            "type": "string",
+            "description": "故障描述。"
           },
-          "detail_url": {
-            "description": "前端详情页地址。",
-            "type": "string"
+          "ai_summary": {
+            "type": "string",
+            "description": "AI 生成的故障摘要。"
           },
-          "end_time": {
-            "description": "故障结束的 Unix 时间戳（秒），仍活跃时为 0。",
-            "format": "int64",
-            "type": "integer"
+          "impact": {
+            "type": "string",
+            "description": "影响范围描述。"
           },
-          "equals_md5": {
-            "description": "用于内容比对的 MD5 哈希。",
-            "type": "string"
+          "root_cause": {
+            "type": "string",
+            "description": "根因分析。"
           },
-          "ever_muted": {
-            "description": "该故障是否曾被静默。",
-            "type": "boolean"
+          "resolution": {
+            "type": "string",
+            "description": "解决方案说明。"
           },
-          "fields": {
-            "additionalProperties": true,
-            "description": "自定义字段取值，按字段名索引。",
-            "type": "object"
+          "num": {
+            "type": "string",
+            "description": "短标识，可能重复。"
           },
           "frequency": {
+            "type": "string",
             "description": "频率分布桶，用于分析故障发生模式：`frequent`（频繁）或 `rare`（偶发）。",
             "enum": [
               "frequent",
               "rare"
-            ],
-            "type": "string"
+            ]
+          },
+          "deleted_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "软删除时间戳（秒），未删除时为 0。"
+          },
+          "created_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "创建时间戳（秒）。"
+          },
+          "updated_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "最后更新时间戳（秒）。"
+          },
+          "snoozed_before": {
+            "type": "integer",
+            "format": "int64",
+            "description": "通知暂停截止时间（Unix 秒），0 表示未暂停。"
           },
           "group_method": {
+            "type": "string",
             "description": "构建故障时使用的告警聚合方法：`i` 智能聚合、`p` 规则聚合、`n` 不聚合。",
             "enum": [
               "i",
               "p",
               "n"
-            ],
-            "type": "string"
-          },
-          "images": {
-            "description": "附加图片。",
-            "items": {
-              "$ref": "#/components/schemas/Image"
-            },
-            "type": "array"
+            ]
           },
-          "impact": {
-            "description": "影响范围描述。",
-            "type": "string"
+          "ever_muted": {
+            "type": "boolean",
+            "description": "该故障是否曾被静默。"
           },
-          "incident_id": {
-            "description": "故障 ID（MongoDB ObjectID）。",
-            "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
+          "has_unfinished_work_item": {
+            "type": "boolean",
+            "description": "故障仍有至少一个状态既不是 `done` 也不是 `cancelled` 的行动项或后续行动时为 `true`。"
           },
-          "incident_severity": {
-            "description": "配置的故障严重程度。",
-            "enum": [
-              "Critical",
-              "Warning",
-              "Info",
-              "Ok"
+          "labels": {
+            "type": [
+              "object",
+              "null"
             ],
-            "type": "string"
+            "additionalProperties": {
+              "type": "string"
+            },
+            "description": "从告警继承的标签。"
           },
-          "incident_status": {
-            "description": "当前故障状态，由告警状态推导。",
-            "enum": [
-              "Critical",
-              "Warning",
-              "Info",
-              "Ok"
-            ],
-            "type": "string"
+          "fields": {
+            "type": "object",
+            "additionalProperties": true,
+            "description": "自定义字段取值，按字段名索引。"
           },
-          "integration_id": {
-            "description": "故障关联的首个集成 ID。",
+          "assigned_to": {
+            "$ref": "#/components/schemas/AssignedTo",
+            "description": "当前分派对象。始终存在；从未分派过的故障 `type`、`id` 为空，`assigned_at` 为 `0`。"
+          },
+          "reporter_email": {
+            "type": "string",
+            "description": "手工创建故障时的上报者邮箱。"
+          },
+          "alert_cnt": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "合并到此故障的告警总数。"
           },
-          "integration_ids": {
-            "description": "所有为此故障贡献告警的集成 ID。",
-            "items": {
-              "format": "int64",
-              "type": "integer"
-            },
-            "type": "array"
+          "active_alert_cnt": {
+            "type": "integer",
+            "format": "int64",
+            "description": "当前处于 Critical/Warning/Info 状态的告警数量。"
           },
-          "integration_type": {
-            "description": "首个告警的集成类型，详情页用于标签映射。",
-            "type": "string"
+          "alert_event_cnt": {
+            "type": "integer",
+            "format": "int64",
+            "description": "所有合并告警的原始事件总数。"
           },
-          "integration_types": {
-            "description": "所有相关集成的类型。",
+          "alerts": {
+            "type": "array",
             "items": {
-              "type": "string"
+              "$ref": "#/components/schemas/AlertInfo"
             },
-            "type": "array"
+            "description": "故障相关接口不返回此字段，仅出现在通知模板和自定义操作的数据中。"
           },
-          "labels": {
-            "additionalProperties": {
-              "type": "string"
-            },
-            "description": "从告警继承的标签。",
-            "type": "object"
+          "closer": {
+            "$ref": "#/components/schemas/PersonShort",
+            "description": "关闭人信息。"
           },
-          "last_time": {
-            "description": "最近一次更新的 Unix 时间戳（秒）。",
-            "format": "int64",
-            "type": "integer"
+          "creator": {
+            "$ref": "#/components/schemas/PersonShort",
+            "description": "创建人信息。"
           },
-          "links": {
-            "description": "协作空间配置的链接集成。",
-            "items": {
-              "$ref": "#/components/schemas/LinkItem"
-            },
-            "type": "array"
+          "owner": {
+            "$ref": "#/components/schemas/PersonShort",
+            "description": "负责人信息，可能已废弃。",
+            "deprecated": true
           },
-          "manual_overrides": {
-            "description": "被手工覆盖过的字段名列表。",
+          "responders": {
+            "type": "array",
             "items": {
-              "type": "string"
+              "$ref": "#/components/schemas/Responder"
             },
-            "type": "array"
+            "description": "当前处理人员列表。"
           },
-          "num": {
-            "description": "短标识，可能重复。",
-            "type": "string"
+          "account_name": {
+            "type": "string",
+            "description": "API 响应中恒为空字符串，仅在渲染通知时填充。"
           },
-          "owner": {
-            "$ref": "#/components/schemas/PersonShort",
-            "deprecated": true,
-            "description": "负责人信息，可能已废弃。"
+          "account_locale": {
+            "type": "string",
+            "description": "API 响应中恒为空字符串，仅在渲染通知时填充。"
           },
-          "owner_id": {
-            "description": "主负责人成员 ID，无则为 0。",
-            "format": "int64",
-            "type": "integer"
+          "account_time_zone": {
+            "type": "string",
+            "description": "API 响应中恒为空字符串，仅在渲染通知时填充。"
           },
-          "post_mortem_id": {
-            "description": "关联的复盘报告 ID，一条故障只能关联一份复盘报告。",
-            "type": "string"
+          "channel_name": {
+            "type": "string",
+            "description": "协作空间名称。"
           },
-          "progress": {
-            "description": "故障进展状态。`Triggered` 已触发待认领；`Processing` 已认领处理中（取消认领会回到 `Triggered`）；`Closed` 已关闭。",
+          "channel_status": {
+            "type": "string",
+            "description": "协作空间状态：`enabled` 启用、`disabled` 禁用、`deleted` 已删除。记录不属于任何协作空间或协作空间已不存在时为空字符串。",
             "enum": [
-              "Triggered",
-              "Processing",
-              "Closed"
-            ],
-            "type": "string"
+              "enabled",
+              "disabled",
+              "deleted",
+              ""
+            ]
           },
-          "reporter_email": {
-            "description": "手工创建故障时的上报者邮箱。",
-            "type": "string"
+          "detail_url": {
+            "type": "string",
+            "description": "前端详情页地址。"
           },
-          "resolution": {
-            "description": "解决方案说明。",
-            "type": "string"
+          "silence_url": {
+            "type": "string",
+            "description": "快速静默页面地址。"
           },
-          "responders": {
-            "description": "当前处理人员列表。",
+          "links": {
+            "type": "array",
             "items": {
-              "$ref": "#/components/schemas/Responder"
+              "$ref": "#/components/schemas/LinkItem"
             },
-            "type": "array"
+            "description": "协作空间配置的链接集成。"
           },
-          "root_cause": {
-            "description": "根因分析。",
-            "type": "string"
+          "integration_type": {
+            "type": "string",
+            "description": "故障第一个集成的插件类型（全部类型见 `integration_types`）。取值集合开放，例如 `prometheus.alert`、`monit.alert`；完整列表可通过 `POST /integration/type/list` 获取。故障没有集成或接口不填充时省略。"
           },
-          "silence_url": {
-            "description": "快速静默页面地址。",
-            "type": "string"
+          "post_mortem_id": {
+            "type": "string",
+            "description": "关联的复盘报告 ID，一条故障只能关联一份复盘报告。"
           },
-          "snoozed_before": {
-            "description": "通知暂停截止时间（Unix 秒），0 表示未暂停。",
-            "format": "int64",
-            "type": "integer"
+          "images": {
+            "type": [
+              "array",
+              "null"
+            ],
+            "items": {
+              "$ref": "#/components/schemas/Image"
+            },
+            "description": "故障附带的图片；没有时为 `null`。以 `img_` 开头的令牌会以下载地址返回。"
           },
-          "start_time": {
-            "description": "故障开始的 Unix 时间戳（秒）。",
-            "format": "int64",
-            "type": "integer"
+          "manual_overrides": {
+            "type": [
+              "array",
+              "null"
+            ],
+            "items": {
+              "type": "string",
+              "enum": [
+                "title",
+                "description",
+                "incident_severity"
+              ]
+            },
+            "description": "被手动修改过、因此不再被合并告警覆盖的字段：`title`、`description`、`incident_severity`。没有时为 `null`。"
           },
-          "team_id": {
-            "description": "故障所属协作空间的团队 ID；协作空间无团队时为 0。",
+          "data_source_id": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "已废弃。请使用 `integration_id`。",
+            "deprecated": true
           },
-          "title": {
-            "description": "故障标题。",
-            "type": "string"
+          "data_source_ids": {
+            "type": [
+              "array",
+              "null"
+            ],
+            "items": {
+              "type": "integer",
+              "format": "int64"
+            },
+            "description": "已废弃。请使用 `integration_ids`。",
+            "deprecated": true
           },
-          "updated_at": {
-            "description": "最后更新时间戳（秒）。",
-            "format": "int64",
-            "type": "integer"
+          "data_source_type": {
+            "type": "string",
+            "description": "已废弃；与 `integration_type` 取值相同。",
+            "deprecated": true
+          },
+          "data_source_types": {
+            "type": [
+              "array",
+              "null"
+            ],
+            "items": {
+              "type": "string"
+            },
+            "description": "已废弃。请使用 `integration_types`。",
+            "deprecated": true
           }
-        },
-        "required": [
-          "incident_id",
-          "account_id",
-          "channel_id",
-          "team_id",
-          "integration_id",
-          "integration_ids",
-          "integration_types",
-          "dedup_key",
-          "equals_md5",
-          "start_time",
-          "end_time",
-          "last_time",
-          "ack_time",
-          "close_time",
-          "creator_id",
-          "closer_id",
-          "owner_id",
-          "incident_status",
-          "incident_severity",
-          "progress",
-          "title",
-          "description",
-          "ai_summary",
-          "impact",
-          "root_cause",
-          "resolution",
-          "num",
-          "created_at",
-          "updated_at",
-          "snoozed_before",
-          "group_method",
-          "ever_muted",
-          "labels",
-          "fields",
-          "assigned_to",
-          "alert_cnt",
-          "active_alert_cnt",
-          "alert_event_cnt",
-          "responders",
-          "account_name",
-          "account_locale",
-          "account_time_zone",
-          "channel_name",
-          "channel_status",
-          "detail_url",
-          "silence_url",
-          "post_mortem_id",
-          "images",
-          "manual_overrides"
-        ],
-        "type": "object"
+        }
       },
       "IncidentInfoRequest": {
         "description": "单个故障查询参数。incident_id 与 num 二者择一传入。",
@@ -12088,35 +12372,35 @@
         "type": "object"
       },
       "IncidentListResponse": {
+        "type": "object",
         "description": "故障分页列表。",
+        "required": [
+          "items",
+          "total",
+          "has_next_page"
+        ],
         "properties": {
-          "has_next_page": {
-            "description": "是否还有更多页。",
-            "type": "boolean"
-          },
           "items": {
-            "description": "当前页故障列表。",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/IncidentInfo"
             },
-            "type": "array"
+            "description": "当前页故障列表。"
+          },
+          "total": {
+            "type": "integer",
+            "format": "int64",
+            "description": "匹配的故障数量，最多为 1,000。对于 `POST /incident/list-by-ids`，为实际找到的故障数。"
+          },
+          "has_next_page": {
+            "type": "boolean",
+            "description": "是否还有下一页。按 `p`/`limit` 分页时根据封顶后的 `total` 计算，超过 1,000 条后即使还有数据也为 `false`；按 `search_after_ctx` 分页时如实反映。`POST /incident/list-by-ids` 恒为 `false`。"
           },
           "search_after_ctx": {
-            "description": "下一页翻页游标。",
-            "type": "string"
-          },
-          "total": {
-            "description": "命中总数。",
-            "format": "int64",
-            "type": "integer"
+            "type": "string",
+            "description": "指向本页最后一条记录的游标；在下一次请求中作为 `search_after_ctx` 传入，即可越过 1,000 条的分页上限继续读取。`p`/`limit` 模式下每个非空页都会返回，游标模式下仅在 `has_next_page` 为 `true` 时返回。`POST /incident/list-by-ids` 不返回。"
           }
-        },
-        "required": [
-          "items",
-          "total",
-          "has_next_page"
-        ],
-        "type": "object"
+        }
       },
       "IncidentRawItem": {
         "description": "分析看板故障列表返回的原始故障记录，附带每条故障的处理效能指标。",
@@ -12409,135 +12693,141 @@
         "type": "object"
       },
       "IncidentShort": {
+        "type": "object",
         "description": "嵌入告警中的故障简要信息。",
         "properties": {
           "incident_id": {
-            "description": "故障 ID（ObjectID 十六进制字符串）。",
-            "type": "string"
-          },
-          "progress": {
-            "description": "故障处理进度——`Triggered`、`Processing`、`Closed` 之一。",
-            "type": "string"
+            "type": "string",
+            "description": "故障 ID（ObjectID 十六进制字符串）。"
           },
           "title": {
-            "description": "故障标题。",
-            "type": "string"
+            "type": "string",
+            "description": "故障标题。"
+          },
+          "progress": {
+            "type": "string",
+            "description": "故障处理进度：`Triggered` 未认领；`Processing` 已认领处理中；`Closed` 已关闭。",
+            "enum": [
+              "Triggered",
+              "Processing",
+              "Closed"
+            ]
           }
-        },
-        "type": "object"
+        }
       },
       "InhibitRuleItem": {
+        "type": "object",
+        "required": [
+          "account_id",
+          "channel_id",
+          "rule_name",
+          "description",
+          "source_filters",
+          "target_filters",
+          "equals",
+          "is_directly_discard",
+          "status",
+          "rule_id",
+          "updated_by",
+          "created_at",
+          "updated_at"
+        ],
         "properties": {
           "account_id": {
-            "description": "规则所属账户 ID。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "规则所属账户 ID。"
           },
           "channel_id": {
-            "description": "规则所属协作空间 ID。",
-            "format": "int64",
-            "type": "integer"
-          },
-          "created_at": {
-            "description": "创建时间，Unix 时间戳（秒）。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "规则所属协作空间 ID。"
           },
-          "deleted_at": {
-            "description": "删除时间，Unix 秒时间戳。仅在策略被软删除时返回；已删除的策略不会出现在列表响应中。",
-            "format": "int64",
-            "type": "integer"
+          "rule_name": {
+            "type": "string",
+            "description": "抑制策略名称，1–39 个字符。"
           },
           "description": {
-            "description": "规则描述。",
-            "type": "string"
+            "type": "string",
+            "description": "规则描述。"
+          },
+          "source_filters": {
+            "$ref": "#/components/schemas/FilterGroup",
+            "description": "源告警需要满足的条件，针对已存的活跃告警求值。支持的键：`status`、`incident_status`、`alert_status`、`severity`、`incident_severity`、`alert_severity`、`title`、`description` 或任意 `labels.<name>`。为空时策略不生效。"
+          },
+          "target_filters": {
+            "$ref": "#/components/schemas/FilterGroup",
+            "description": "新进入的告警事件需满足的条件，满足才会被抑制；为空表示所有新事件都是抑制对象。可用字段：`title`、`description`、`severity`（别名 `alert_severity`、`event_severity`）、`status`、`alert_key`、`title_rule`、`integration_id`（别名 `data_source_id`），或任意 `labels.<name>`。"
           },
           "equals": {
-            "description": "源（抑制方）告警与目标（被抑制）告警之间必须取值相等的字段键，例如 `data_source_id` 或 `labels.cluster`。",
+            "type": "array",
             "items": {
               "type": "string"
             },
-            "type": "array"
+            "description": "源告警与新事件取值必须相同的字段。只有 `title`、`severity` 和 `labels.<name>` 有效；包含其他字段时策略永远不生效。"
           },
           "is_directly_discard": {
-            "description": "为 true 时，命中的告警事件被完全丢弃；为 false 时，告警仍会被记录，但标记为被本策略静默。",
-            "type": "boolean"
-          },
-          "rule_id": {
-            "description": "规则 ID（MongoDB ObjectID）。",
-            "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
-          },
-          "rule_name": {
-            "description": "规则名称。",
-            "type": "string"
-          },
-          "source_filters": {
-            "$ref": "#/components/schemas/FilterGroup",
-            "description": "源告警需要满足的条件，针对已存的活跃告警求值。支持的键：`status`、`incident_status`、`alert_status`、`severity`、`incident_severity`、`alert_severity`、`title`、`description` 或任意 `labels.<name>`。为空时策略不生效。"
+            "type": "boolean",
+            "description": "为 true 时，命中的告警事件被完全丢弃；为 false 时，告警仍会被记录，但标记为被本策略静默。"
           },
           "status": {
-            "description": "规则状态：`enabled` 启用，`disabled` 停用；已删除的规则不会出现在列表中。",
+            "type": "string",
             "enum": [
               "enabled",
               "disabled"
             ],
-            "type": "string"
+            "description": "规则状态：`enabled` 启用，`disabled` 停用；已删除的规则不会出现在列表中。"
           },
-          "target_filters": {
-            "$ref": "#/components/schemas/FilterGroup",
-            "description": "目标（被抑制）告警事件需要满足的条件；为空表示所有事件都是抑制目标。"
+          "rule_id": {
+            "type": "string",
+            "pattern": "^[0-9a-fA-F]{24}$",
+            "description": "规则 ID（MongoDB ObjectID）。"
+          },
+          "updated_by": {
+            "type": "integer",
+            "format": "int64",
+            "description": "最近一次更新该规则的用户 ID。"
+          },
+          "created_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "创建时间，Unix 时间戳（秒）。"
           },
           "updated_at": {
-            "description": "最近更新时间，Unix 时间戳（秒）。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "最近更新时间，Unix 时间戳（秒）。"
           },
-          "updated_by": {
-            "description": "最近一次更新该规则的用户 ID。",
+          "deleted_at": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "删除时间，Unix 秒时间戳。仅在策略被软删除时返回；已删除的策略不会出现在列表响应中。"
           }
-        },
-        "required": [
-          "account_id",
-          "channel_id",
-          "rule_name",
-          "description",
-          "source_filters",
-          "target_filters",
-          "equals",
-          "is_directly_discard",
-          "status",
-          "rule_id",
-          "updated_by",
-          "created_at",
-          "updated_at"
-        ],
-        "type": "object"
+        }
       },
       "InitPostMortemRequest": {
+        "type": "object",
         "description": "从故障初始化复盘报告的参数。",
+        "required": [
+          "incident_ids",
+          "template_id"
+        ],
         "properties": {
           "incident_ids": {
-            "description": "要关联到复盘报告的故障 ID，1-10 个。",
+            "type": "array",
+            "minItems": 1,
+            "maxItems": 10,
             "items": {
-              "type": "string"
+              "type": "string",
+              "pattern": "^[0-9a-fA-F]{24}$"
             },
-            "maxItems": 10,
-            "minItems": 1,
-            "type": "array"
+            "description": "要关联到报告的故障 ID（MongoDB ObjectID），1–10 个，须均在本账户中存在。同一组故障总是对应同一份报告。"
           },
           "template_id": {
-            "description": "用于初始化报告的模板 ID。",
-            "type": "string"
+            "type": "string",
+            "description": "模板 ID，可从 `POST /incident/post-mortem/template/list` 获取，例如内置的 `post_mortem_default_tmpl_en-us`、`post_mortem_default_tmpl_zh-cn`，或自定义模板 ID。"
           }
-        },
-        "required": [
-          "incident_ids",
-          "template_id"
-        ],
-        "type": "object"
+        }
       },
       "InsightAlertByLabelItem": {
         "properties": {
@@ -12580,150 +12870,150 @@
         "type": "object"
       },
       "InsightFilter": {
+        "type": "object",
         "description": "洞察与导出接口共享的过滤参数。`severities` 至多 3 项，team/channel/responder/incident 过滤条件每项至多 100 条，时间范围不能超过一年。",
+        "required": [
+          "start_time",
+          "end_time"
+        ],
         "properties": {
-          "asc": {
-            "description": "为 `true` 时升序，否则降序。仅 `/insight/incident/list` 使用。",
-            "type": "boolean"
+          "start_time": {
+            "type": "integer",
+            "format": "int64",
+            "description": "起始时间，Unix 秒。必须大于 0。",
+            "exclusiveMinimum": 0
           },
-          "channel_ids": {
-            "description": "按协作空间 ID 过滤，至多 100 项。",
+          "end_time": {
+            "type": "integer",
+            "format": "int64",
+            "description": "结束时间，Unix 秒，必须大于 `start_time`。"
+          },
+          "team_ids": {
+            "type": "array",
             "items": {
-              "format": "int64",
-              "type": "integer"
+              "type": "integer",
+              "format": "int64"
             },
-            "maxItems": 100,
-            "type": "array"
-          },
-          "description_html_to_text": {
-            "description": "导出时是否将描述列中的 HTML 标签转换为纯文本。",
-            "type": "boolean"
+            "description": "按团队 ID 过滤，至多 100 项。",
+            "maxItems": 100
           },
-          "end_time": {
-            "description": "结束时间，Unix 秒，必须大于 `start_time`。",
-            "format": "int64",
-            "type": "integer"
+          "channel_ids": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "int64"
+            },
+            "description": "按协作空间 ID 过滤，至多 100 项。",
+            "maxItems": 100
           },
-          "export_fields": {
-            "description": "导出 CSV 的列 key 列表，按给定顺序输出；未知或重复的 key 会被拒绝。各导出接口支持的 key 集合不同，见对应接口的描述。仅导出接口使用；最多 50 个。",
+          "responder_ids": {
+            "type": "array",
             "items": {
-              "type": "string"
+              "type": "integer",
+              "format": "int64"
             },
-            "maxItems": 50,
-            "type": "array"
+            "description": "按响应人成员 ID 过滤。用于 `/insight/responder`（返回哪些响应人）以及故障列表/导出（任一指定成员参与响应的故障）；账户、团队、协作空间维度和 Top-K 接口忽略该字段。最多 100 个。",
+            "maxItems": 100
           },
-          "fields": {
-            "additionalProperties": true,
-            "description": "自定义字段过滤（精确匹配）。",
-            "type": "object"
+          "severities": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "enum": [
+                "Critical",
+                "Warning",
+                "Info",
+                "Ok"
+              ]
+            },
+            "description": "按严重程度过滤：`Critical`、`Warning`、`Info` 或 `Ok`。最多 3 个。",
+            "maxItems": 3
           },
           "incident_ids": {
-            "description": "按故障 ID（MongoDB ObjectID）过滤，至多 100 项。",
+            "type": "array",
             "items": {
-              "pattern": "^[0-9a-fA-F]{24}$",
-              "type": "string"
+              "type": "string",
+              "pattern": "^[0-9a-fA-F]{24}$"
             },
-            "maxItems": 100,
-            "type": "array"
-          },
-          "include_ever_muted": {
-            "description": "是否包含曾被收敛的故障；默认不包含。",
-            "type": "boolean"
+            "description": "按故障 ID（24 位十六进制）过滤。仅用于故障列表和故障导出。最多 100 个。",
+            "maxItems": 100
           },
-          "is_my_team": {
-            "description": "是否仅返回调用者所属团队的数据。若调用者无任何团队，返回空集合。",
-            "type": "boolean"
+          "query": {
+            "type": "string",
+            "description": "对故障标题做子串匹配（SQL `LIKE %query%`）。"
           },
           "labels": {
+            "type": "object",
             "additionalProperties": {
               "type": "string"
             },
-            "description": "标签过滤（精确匹配）。",
-            "type": "object"
+            "description": "标签过滤（精确匹配）。"
+          },
+          "fields": {
+            "type": "object",
+            "additionalProperties": true,
+            "description": "自定义字段过滤（精确匹配）。"
           },
           "orderby": {
-            "description": "故障列表的排序字段，目前仅支持 `created_at`（故障创建时间）。仅 `/insight/incident/list` 使用。",
+            "type": "string",
             "enum": [
               "created_at"
             ],
-            "type": "string"
-          },
-          "query": {
-            "description": "对故障标题做子串匹配（SQL `LIKE %query%`）。",
-            "type": "string"
+            "description": "故障列表的排序字段；仅支持 `created_at`（故障创建时间，默认）。用于 `/insight/incident/list` 和 `/insight/incident/export`。"
           },
-          "responder_ids": {
-            "description": "按处理人员 ID 过滤，至多 100 项。",
-            "items": {
-              "format": "int64",
-              "type": "integer"
-            },
-            "maxItems": 100,
-            "type": "array"
+          "asc": {
+            "type": "boolean",
+            "description": "为 `true` 时升序，否则降序（默认）。用于故障列表和故障导出；`/insight/alert/topk-by-label` 有自己的 `asc`。"
           },
-          "seconds_to_ack_from": {
-            "description": "认领时长下界（秒，包含）。",
-            "format": "int64",
-            "minimum": 0,
-            "type": "integer"
+          "is_my_team": {
+            "type": "boolean",
+            "description": "只看调用者所在团队的数据（同时传 `team_ids` 时取交集）。调用者不属于任何团队时结果为空。"
           },
-          "seconds_to_ack_to": {
-            "description": "认领时长上界（秒，不包含）。两端同时设置时，必须大于 `seconds_to_ack_from`。",
-            "format": "int64",
-            "minimum": 0,
-            "type": "integer"
+          "time_zone": {
+            "type": "string",
+            "description": "用于切分 `aggregate_unit` 时间桶的 IANA 时区（如 `Asia/Shanghai`、`UTC`）；`EST` 之类的缩写以及 `Etc/GMT±N` 会被拒绝。默认 UTC。`/insight/incident/export` 用它渲染时间，未传时依次回退到账户时区、`Asia/Shanghai`。"
           },
           "seconds_to_close_from": {
-            "description": "解决时长下界（秒，包含）。",
+            "type": "integer",
             "format": "int64",
-            "minimum": 0,
-            "type": "integer"
+            "description": "解决时长下界（秒，包含）。",
+            "minimum": 0
           },
           "seconds_to_close_to": {
-            "description": "解决时长上界（秒，不包含）。两端同时设置时，必须大于 `seconds_to_close_from`。",
+            "type": "integer",
             "format": "int64",
-            "minimum": 0,
-            "type": "integer"
+            "description": "解决时长上界（秒，不包含）。两端同时设置时，必须大于 `seconds_to_close_from`。",
+            "minimum": 0
           },
-          "severities": {
-            "description": "按严重程度过滤，至多 3 项。",
-            "items": {
-              "enum": [
-                "Critical",
-                "Warning",
-                "Info",
-                "Ok"
-              ],
-              "type": "string"
-            },
-            "maxItems": 3,
-            "type": "array"
+          "seconds_to_ack_from": {
+            "type": "integer",
+            "format": "int64",
+            "description": "认领时长下界（秒，包含）。",
+            "minimum": 0
           },
-          "start_time": {
-            "description": "起始时间，Unix 秒。必须大于 0。",
-            "exclusiveMinimum": 0,
+          "seconds_to_ack_to": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "认领时长上界（秒，不包含）。两端同时设置时，必须大于 `seconds_to_ack_from`。",
+            "minimum": 0
           },
-          "team_ids": {
-            "description": "按团队 ID 过滤，至多 100 项。",
+          "export_fields": {
+            "type": "array",
             "items": {
-              "format": "int64",
-              "type": "integer"
+              "type": "string"
             },
-            "maxItems": 100,
-            "type": "array"
+            "description": "导出 CSV 的列 key 列表，按给定顺序输出；未知或重复的 key 会被拒绝。各导出接口支持的 key 集合不同，见对应接口的描述。仅导出接口使用；最多 50 个。",
+            "maxItems": 50
           },
-          "time_zone": {
-            "description": "用于划分 日/周/月 聚合桶的 IANA 时区名（如 `Asia/Shanghai`）。可选，默认 UTC；仅 `/insight/incident/export` 例外：缺省时依次回退到账户时区、`Asia/Shanghai`。",
-            "type": "string"
+          "description_html_to_text": {
+            "type": "boolean",
+            "description": "导出时是否将描述列中的 HTML 标签转换为纯文本。"
+          },
+          "include_ever_muted": {
+            "type": "boolean",
+            "description": "是否包含曾被收敛的故障；默认不包含。"
           }
-        },
-        "required": [
-          "start_time",
-          "end_time"
-        ],
-        "type": "object"
+        }
       },
       "InsightIncidentExportRequest": {
         "$ref": "#/components/schemas/InsightFilter"
@@ -12768,29 +13058,29 @@
         ]
       },
       "InsightIncidentListResponse": {
+        "type": "object",
         "properties": {
+          "total": {
+            "type": "integer",
+            "format": "int64",
+            "description": "匹配的故障数。请求带 `search_after_ctx` 时只统计游标之后的故障。"
+          },
           "has_next_page": {
-            "description": "是否还有下一页。",
-            "type": "boolean"
+            "type": "boolean",
+            "description": "是否还有下一页。"
+          },
+          "search_after_ctx": {
+            "type": "string",
+            "description": "下一页游标——本页最后一行的故障 ID。仅在 `has_next_page` 为 true 时返回。"
           },
           "items": {
-            "description": "故障明细列表。",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/IncidentRawItem"
             },
-            "type": "array"
-          },
-          "search_after_ctx": {
-            "description": "下一页游标——本页最后一行的故障 ID。仅在 `has_next_page` 为 true 时返回。",
-            "type": "string"
-          },
-          "total": {
-            "description": "匹配的故障总数。",
-            "format": "int64",
-            "type": "integer"
+            "description": "本页的故障；无匹配时为空数组。"
           }
-        },
-        "type": "object"
+        }
       },
       "InsightQueryRequest": {
         "allOf": [
@@ -12798,23 +13088,23 @@
             "$ref": "#/components/schemas/InsightFilter"
           },
           {
+            "type": "object",
             "description": "洞察维度聚合请求。在 InsightFilter 基础上增加聚合控制字段。",
             "properties": {
+              "split_hours": {
+                "type": "boolean",
+                "description": "为 `true` 时，每个时间桶再按 `work`、`sleep`、`off` 拆分，分别作为带 `hours` 的独立行返回。"
+              },
               "aggregate_unit": {
-                "description": "将指标按时间粒度聚合。设置后时间范围须不少于 24 小时；`day` 粒度时范围不得超过 31 天。`day` 按自然日、`week` 按自然周、`month` 按自然月切分聚合桶，边界按 `time_zone` 对齐。",
+                "type": "string",
                 "enum": [
                   "day",
                   "week",
                   "month"
                 ],
-                "type": "string"
-              },
-              "split_hours": {
-                "description": "为 `true` 时将指标拆分为 `work`/`sleep`/`off` 时段。",
-                "type": "boolean"
+                "description": "将时间范围切分为时间桶；不传则整个范围作为一个桶。要求时间范围至少 24 小时，`day` 最多 31 天。\n- `day`：按 `time_zone` 的自然日切分（第一个桶从 `start_time` 到下一个零点）。\n- `week`：从 `start_time` 起每 7 天一个桶（不对齐到周一）。\n- `month`：按 `time_zone` 的自然月切分（第一个桶从 `start_time` 到下个月 1 日）。"
               }
-            },
-            "type": "object"
+            }
           }
         ]
       },
@@ -12824,195 +13114,235 @@
             "$ref": "#/components/schemas/InsightQueryRequest"
           },
           {
+            "type": "object",
+            "required": [
+              "label"
+            ],
             "properties": {
-              "asc": {
-                "description": "为 `true` 时升序，否则降序。",
-                "type": "boolean"
-              },
-              "k": {
-                "default": 20,
-                "description": "返回的前 K 条记录数，1 到 100，默认 20。",
-                "maximum": 100,
-                "minimum": 1,
-                "type": "integer"
-              },
               "label": {
-                "description": "聚合维度。`check` 按告警事件的 `labels.check` 标签（监控检查项）取值聚合；`resource` 按 `labels.resource` 标签（监控资源标识）取值聚合。",
+                "type": "string",
                 "enum": [
                   "check",
                   "resource"
                 ],
-                "type": "string"
+                "description": "聚合维度。`check` 按告警事件的 `labels.check` 标签（监控检查项）取值聚合；`resource` 按 `labels.resource` 标签（监控资源标识）取值聚合。"
+              },
+              "k": {
+                "type": "integer",
+                "description": "返回的标签值个数，1–100（默认 20）。设置 `split_hours` 时按每个小时桶分别生效。",
+                "minimum": 1,
+                "maximum": 100,
+                "default": 20
               },
               "orderby": {
-                "description": "排序字段。`total_alert_cnt` 按告警数排序；`total_alert_event_cnt` 按原始告警事件数排序（默认）。",
+                "type": "string",
                 "enum": [
                   "total_alert_cnt",
                   "total_alert_event_cnt"
                 ],
-                "type": "string"
+                "description": "排序字段。`total_alert_cnt` 按告警数排序；`total_alert_event_cnt` 按原始告警事件数排序（默认）。"
+              },
+              "asc": {
+                "type": "boolean",
+                "description": "为 `true` 时升序，否则降序。"
               }
-            },
-            "required": [
-              "label"
-            ],
-            "type": "object"
+            }
           }
         ]
       },
       "InviteMemberItem": {
+        "type": "object",
         "description": "待邀请的成员。只需提供 `email`，或同时提供 `member_name` 与 `phone`。",
         "properties": {
-          "country_code": {
-            "description": "`phone` 的 ISO 3166-1 alpha-2 地区代码（如 \"CN\"）；写入前校验并统一转为大写，非法值返回 400。当 `phone` 不带 \"+\" 前缀时兼作解析提示（未传时默认 \"CN\"）。",
-            "type": "string"
-          },
-          "email": {
-            "description": "邮箱地址。未提供 `phone` 时必填。",
-            "type": "string"
-          },
-          "locale": {
-            "description": "语言。可选值：`zh-CN`（简体中文）、`en-US`（英文）；非法值返回 400。",
-            "enum": [
-              "zh-CN",
-              "en-US"
-            ],
-            "type": "string"
-          },
           "member_name": {
-            "description": "显示名称，2–39 个字符。未提供 `email` 时必填；省略时取邮箱前缀作为名称。",
-            "maxLength": 39,
+            "type": "string",
             "minLength": 2,
-            "type": "string"
+            "maxLength": 39,
+            "description": "显示名称，2–39 个字符。未提供 `email` 时必填；省略时取邮箱前缀作为名称。"
+          },
+          "email": {
+            "type": "string",
+            "description": "邮箱地址，以小写存储。未提供 `phone` 时必填。"
           },
           "phone": {
-            "description": "手机号。未提供 `email` 时必填。",
-            "type": "string"
+            "type": "string",
+            "description": "手机号。未提供 `email` 时必填。"
           },
-          "ref_id": {
-            "description": "外部引用 ID",
-            "type": "string"
+          "country_code": {
+            "type": "string",
+            "description": "`phone` 的 ISO 3166-1 alpha-2 地区代码（如 \"CN\"）；写入前校验并统一转为大写，非法值返回 400。当 `phone` 不带 \"+\" 前缀时兼作解析提示（未传时默认 \"CN\"）。"
           },
           "role_ids": {
-            "description": "授予的角色 ID 列表",
+            "type": "array",
             "items": {
-              "format": "uint64",
-              "type": "integer"
+              "type": "integer",
+              "format": "uint64"
             },
-            "type": "array"
+            "description": "要分配的角色 ID：内置的 `2`（Admin）、`6`（Responder）、`8`（Viewer），或 `POST /role/list` 中的自定义角色 ID。不传时默认为 Viewer（`8`）；不存在的 ID 返回 `400`。"
+          },
+          "locale": {
+            "type": "string",
+            "enum": [
+              "zh-CN",
+              "en-US"
+            ],
+            "description": "语言：`zh-CN`（简体中文）或 `en-US`（英文），其他值返回 400。不传时使用账户的语言设置。"
           },
           "time_zone": {
-            "description": "时区",
-            "type": "string"
+            "type": "string",
+            "description": "IANA 时区名称，如 `Asia/Shanghai`。不传则成员跟随账户时区；名称无效时返回 `400`。"
+          },
+          "ref_id": {
+            "type": "string",
+            "description": "外部引用 ID（如 HR 系统中的员工号），之后可在 `POST /member/delete`、`POST /member/info/reset` 中作为查找键。"
           }
-        },
-        "type": "object"
+        }
       },
       "KnowledgeFileDeleteRequest": {
+        "type": "object",
         "description": "要删除的知识文件。",
         "properties": {
-          "force": {
-            "description": "即使其他知识文件仍引用该文件也强制删除；此时引用方会以警告形式返回，而不再阻止删除。",
-            "type": "boolean"
-          },
           "pack_id": {
-            "description": "知识 ID；默认为调用者的账户范围知识。",
-            "type": "string"
+            "type": "string",
+            "description": "知识 ID；默认为调用者的账户范围知识。"
           },
           "rel_path": {
-            "description": "文件相对于知识根目录的路径。",
-            "type": "string"
+            "type": "string",
+            "description": "文件相对于知识根目录的路径，路径规则与 `POST /safari/knowledge/file/put` 相同。"
+          },
+          "force": {
+            "type": "boolean",
+            "description": "即使其他知识文件仍引用该文件也强制删除；此时引用方会以警告形式返回，而不再阻止删除。"
+          },
+          "expected_version": {
+            "type": "integer",
+            "minimum": 0,
+            "default": 0,
+            "description": "乐观并发校验。`0` 或不传：无条件删除。正数：仅当知识当前 `version` 等于该值时才删除；否则不删除，返回 HTTP 200，`status` 为 `conflict` 并带上当前 `version`。"
           }
         },
         "required": [
           "rel_path"
-        ],
-        "type": "object"
+        ]
       },
       "KnowledgeFileDeleteResponse": {
-        "description": "删除结果；无警告时为空对象。",
+        "type": "object",
+        "description": "删除结果。",
         "properties": {
+          "status": {
+            "type": "string",
+            "enum": [
+              "ok",
+              "conflict"
+            ],
+            "description": "删除结果。\n- `ok`：文件已删除，或本来就不存在。\n- `conflict`：`expected_version` 与知识当前版本不一致，未删除任何内容。"
+          },
           "warnings": {
-            "description": "删除后的非阻塞警告数组；`code=still_referenced_by` 表示被（强制）删除的文件仍被知识内其他文件 @ref 引用（`refs` 列出引用方）。无警告时该字段缺省（omitempty）。",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/KnowledgeWarning"
             },
-            "type": "array"
+            "description": "非阻塞警告；`still_referenced_by` 表示通过 `force` 删除了仍被其他文件引用的文件（`refs` 列出引用方）。没有警告时不返回。"
+          },
+          "version": {
+            "type": "integer",
+            "description": "删除后的知识 `version`（文件不存在时不变）。文件不存在且未传 `expected_version` 时为 `0`。`conflict` 时为知识当前版本。"
+          },
+          "message": {
+            "type": "string",
+            "description": "冲突说明。仅 `status` 为 `conflict` 时返回。"
           }
         },
-        "type": "object"
+        "required": [
+          "status",
+          "version"
+        ]
       },
       "KnowledgeFileGetRequest": {
+        "type": "object",
         "description": "要获取的文件。",
         "properties": {
           "pack_id": {
-            "description": "知识 ID；默认为调用者的账户范围知识。",
-            "type": "string"
+            "type": "string",
+            "description": "知识 ID；默认为调用者的账户范围知识。"
           },
           "rel_path": {
-            "description": "文件相对于知识根目录的路径。",
-            "type": "string"
+            "type": "string",
+            "description": "文件相对于知识根目录的路径。该路径下没有文件时调用仍然成功，`file` 为 `null`，`content_b64` 为空。"
           }
         },
         "required": [
           "rel_path"
-        ],
-        "type": "object"
+        ]
       },
       "KnowledgeFileGetResponse": {
-        "description": "文件元数据及其 Base64 编码的内容。",
+        "type": "object",
+        "description": "文件元数据、Base64 编码的文件内容以及当前知识版本号。",
         "properties": {
+          "file": {
+            "description": "文件元数据；`rel_path` 下没有文件时为 `null`。",
+            "oneOf": [
+              {
+                "$ref": "#/components/schemas/KnowledgeFileItem"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
           "content_b64": {
-            "description": "Base64 编码的文件内容；解码后为 UTF-8 文本。",
-            "type": "string"
+            "type": "string",
+            "description": "Base64 编码的文件内容。文件不存在（或内容为空）时为空字符串。"
           },
-          "file": {
-            "$ref": "#/components/schemas/KnowledgeFileItem"
+          "version": {
+            "type": "integer",
+            "description": "知识当前的 `version`。可作为 `expected_version` 传给 `POST /safari/knowledge/file/put` 或 `POST /safari/knowledge/file/delete`，若期间知识被他人修改则拒绝写入。"
           }
         },
         "required": [
           "file",
-          "content_b64"
-        ],
-        "type": "object"
+          "content_b64",
+          "version"
+        ]
       },
       "KnowledgeFileItem": {
+        "type": "object",
         "description": "单个知识文件的元数据；文件内容需通过 file/get 单独获取。",
         "properties": {
-          "checksum": {
-            "description": "文件内容的 SHA-256 十六进制摘要。",
-            "type": "string"
-          },
-          "content_type": {
-            "description": "MIME 类型；上传时未指定则按扩展名推断。",
-            "type": "string"
-          },
           "file_id": {
-            "description": "文件 ID（`kfl_` 前缀）。",
-            "type": "string"
+            "type": "string",
+            "description": "文件 ID（`kfl_` 前缀）。"
           },
           "pack_id": {
-            "description": "文件所属的知识 ID。",
-            "type": "string"
+            "type": "string",
+            "description": "文件所属的知识 ID。"
           },
           "rel_path": {
-            "description": "相对于知识根目录的路径，如 `runbooks/restart.md`。",
-            "type": "string"
+            "type": "string",
+            "description": "相对于知识根目录的路径，以 `/` 分隔，如 `runbooks/restart.md`。在同一份知识内唯一。"
+          },
+          "content_type": {
+            "type": "string",
+            "description": "文件的 MIME 类型，取值不固定：写入时未传 `content_type` 则按 `rel_path` 的扩展名推断——`.md` → `text/markdown`，`.yaml`/`.yml` → `text/yaml`，`.json` → `application/json`，`.sh` → `text/x-sh`，其他 → `text/plain`；显式传入的值原样保存。"
           },
           "size_bytes": {
+            "type": "integer",
             "description": "文件大小（字节）。",
-            "format": "int64",
-            "type": "integer"
+            "format": "int64"
           },
-          "updated_at_ms": {
-            "description": "最近修改时间的 Unix 毫秒时间戳。",
-            "format": "int64",
-            "type": "integer"
+          "checksum": {
+            "type": "string",
+            "description": "文件内容的 SHA-256 十六进制摘要。"
           },
           "updated_by": {
+            "type": "integer",
             "description": "最近修改者成员 ID。",
-            "format": "int64",
-            "type": "integer"
+            "format": "int64"
+          },
+          "updated_at_ms": {
+            "type": "integer",
+            "description": "最近修改时间的 Unix 毫秒时间戳。",
+            "format": "int64"
           }
         },
         "required": [
@@ -13024,8 +13354,7 @@
           "checksum",
           "updated_by",
           "updated_at_ms"
-        ],
-        "type": "object"
+        ]
       },
       "KnowledgeFileListRequest": {
         "description": "要列出文件的知识。",
@@ -13046,70 +13375,99 @@
         "type": "object"
       },
       "KnowledgeFileListResponse": {
-        "description": "知识内的文件。",
+        "type": "object",
+        "description": "知识中的全部文件及当前知识版本号。",
         "properties": {
           "files": {
-            "description": "指定知识内的文件数组；无文件时为空数组。",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/KnowledgeFileItem"
             },
-            "type": "array"
+            "description": "指定知识内的文件数组；无文件时为空数组。"
           },
           "total": {
-            "description": "知识内文件总数。",
-            "format": "int64",
-            "type": "integer"
+            "type": "integer",
+            "description": "`files` 中的文件数，即知识的全部文件数（该接口不分页）。",
+            "format": "int64"
+          },
+          "version": {
+            "type": "integer",
+            "description": "知识当前的 `version`，可作为文件写入的 `expected_version`。"
           }
         },
         "required": [
           "files",
-          "total"
-        ],
-        "type": "object"
+          "total",
+          "version"
+        ]
       },
       "KnowledgeFilePutRequest": {
+        "type": "object",
         "description": "要创建或覆盖的文件。文件体通过 `content_b64` 以 Base64 文本上传，不是 multipart 上传。",
         "properties": {
+          "pack_id": {
+            "type": "string",
+            "description": "知识 ID；默认为调用者的账户范围知识。"
+          },
+          "rel_path": {
+            "type": "string",
+            "description": "目标路径，相对于知识根目录；该路径已有文件时会被覆盖。必须以 `/` 分隔、不能以 `/` 开头、必须是规范化形式，且任一路径段不能为空、`.`、`..` 或以 `.` 开头（不允许隐藏文件）。"
+          },
           "content_b64": {
-            "description": "Base64 编码的文件内容；解码后必须是合法的 UTF-8 文本（拒绝二进制）。单文件上限 1 MiB。",
-            "type": "string"
+            "type": "string",
+            "description": "Base64（标准字母表）编码的文件内容。解码后必须是不含 NUL 字节的 UTF-8 文本，且不超过 1 MiB（`DUTY.md` 不超过 32 KiB）。不传或传空字符串则写入空文件。"
           },
           "content_type": {
-            "description": "MIME 类型；留空时按扩展名推断。",
-            "type": "string"
-          },
-          "pack_id": {
-            "description": "知识 ID；默认为调用者的账户范围知识。",
-            "type": "string"
+            "type": "string",
+            "description": "与文件一起保存的 MIME 类型。可选：不传时按 `rel_path` 扩展名推断（`.md` → `text/markdown`，`.yaml`/`.yml` → `text/yaml`，`.json` → `application/json`，`.sh` → `text/x-sh`，其他 → `text/plain`）。传入的值原样保存。"
           },
-          "rel_path": {
-            "description": "相对于知识根目录的目标路径；已存在的文件会被覆盖。",
-            "type": "string"
+          "expected_version": {
+            "type": "integer",
+            "minimum": 0,
+            "default": 0,
+            "description": "乐观并发校验。`0` 或不传：无条件写入。正数：仅当知识当前 `version` 等于该值时才写入；否则不写入，返回 HTTP 200，`status` 为 `conflict` 并带上当前 `version`。"
           }
         },
         "required": [
           "rel_path"
-        ],
-        "type": "object"
+        ]
       },
       "KnowledgeFilePutResponse": {
-        "description": "写入的文件及非阻塞提示。",
+        "type": "object",
+        "description": "写入结果。成功时包含写入的文件；版本冲突时只有 `status`、`version` 和 `message`。",
         "properties": {
+          "status": {
+            "type": "string",
+            "enum": [
+              "ok",
+              "conflict"
+            ],
+            "description": "写入结果。\n- `ok`：修改已提交。\n- `conflict`：`expected_version` 与知识当前版本不一致，未做任何修改；请重新读取文件后用返回的 `version` 重试。"
+          },
           "file": {
-            "$ref": "#/components/schemas/KnowledgeFileItem"
+            "$ref": "#/components/schemas/KnowledgeFileItem",
+            "description": "写入后保存的文件。`status` 为 `conflict` 时不返回。"
           },
           "warnings": {
-            "description": "写入成功后的非阻塞警告数组；`code=unresolved_reference` 表示文件内容中的 @ref 引用了知识内不存在的文件。无警告时该字段缺省（omitempty）。",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/KnowledgeWarning"
             },
-            "type": "array"
+            "description": "非阻塞警告；`unresolved_reference` 表示写入内容中的 @ref 指向知识中不存在的路径。没有警告时不返回。"
+          },
+          "version": {
+            "type": "integer",
+            "description": "`status` 为 `ok` 时是本次写入产生的知识 `version`；为 `conflict` 时是知识当前版本。可作为下一次写入的 `expected_version`。"
+          },
+          "message": {
+            "type": "string",
+            "description": "冲突说明（`this knowledge was updated by someone else`）。仅 `status` 为 `conflict` 时返回。"
           }
         },
         "required": [
-          "file"
-        ],
-        "type": "object"
+          "status",
+          "version"
+        ]
       },
       "KnowledgeGetRequest": {
         "description": "无请求字段——固定查询账户范围知识。",
@@ -13150,105 +13508,106 @@
         "type": "object"
       },
       "KnowledgePackDeleteResponse": {
+        "type": "object",
         "description": "删除结果。",
         "properties": {
           "ok": {
-            "description": "知识删除成功时为 true。",
-            "type": "boolean"
+            "type": "boolean",
+            "description": "成功时恒为 `true`；删除失败会直接返回错误。"
           }
         },
         "required": [
           "ok"
-        ],
-        "type": "object"
+        ]
       },
       "KnowledgePackEnsureRequest": {
+        "type": "object",
         "description": "要确保存在知识的范围。",
         "properties": {
           "scope": {
-            "description": "知识范围。可选值：`account`（账户级知识，scope_id 固定为调用方账户 ID，仅账户管理员可创建；首次创建会播种默认 DUTY.md）、`team`（团队级知识，必须提供 `scope_id` 团队 ID，调用者需属于该团队）。",
+            "type": "string",
+            "description": "要确保存在的知识范围。\n- `account`：账户知识。`scope_id` 会被替换为调用者的账户 ID；仅账户 Owner 和管理员可调用，即使知识已存在也一样。若该知识中没有 `DUTY.md`，会写入一份默认 `DUTY.md`。\n- `team`：`scope_id` 指定团队的知识。必须传 `scope_id`，且调用者须是该团队成员。",
             "enum": [
               "account",
               "team"
-            ],
-            "type": "string"
+            ]
           },
           "scope_id": {
-            "description": "团队 ID；团队范围必填，账户范围忽略。",
-            "format": "int64",
-            "type": "integer"
+            "type": "integer",
+            "description": "团队 ID。`team` 范围必填（非 0），否则返回 `InvalidParameter`；`account` 范围忽略。",
+            "format": "int64"
           }
         },
         "required": [
           "scope"
-        ],
-        "type": "object"
+        ]
       },
       "KnowledgePackItem": {
+        "type": "object",
         "description": "知识——一棵带版本号的文件树，AI SRE 会话启动时会注入到每个沙箱中。每个（账户, scope, scope_id）仅有一份知识。",
         "properties": {
+          "pack_id": {
+            "type": "string",
+            "description": "知识 ID（`kpk_` 前缀）。"
+          },
           "account_id": {
+            "type": "integer",
             "description": "知识所属账户 ID。",
-            "format": "int64",
-            "type": "integer"
-          },
-          "can_edit": {
-            "description": "调用者是否有权限编辑该知识。",
-            "type": "boolean"
-          },
-          "created_at_ms": {
-            "description": "创建时间的 Unix 毫秒时间戳。",
-            "format": "int64",
-            "type": "integer"
-          },
-          "created_by": {
-            "description": "创建者成员 ID。",
-            "format": "int64",
-            "type": "integer"
-          },
-          "duty_version": {
-            "description": "最后一次撰写或确认 DUTY.md 时的知识版本。当 `version` 大于该值时，说明 DUTY.md 已不能反映知识的全部文件。",
-            "type": "integer"
-          },
-          "file_count": {
-            "description": "知识内文件数量。",
-            "type": "integer"
-          },
-          "pack_id": {
-            "description": "知识 ID（`kpk_` 前缀）。",
-            "type": "string"
+            "format": "int64"
           },
           "scope": {
-            "description": "知识范围；`channel` 为历史遗留范围，新建知识为 `account` 或 `team`。",
+            "type": "string",
+            "description": "知识范围。\n- `account`：账户级知识，整个账户共享；`scope_id` 为账户 ID。\n- `team`：归属某个团队的知识；`scope_id` 为团队 ID。\n- `channel`：历史遗留范围。无法通过本 API 创建或移入，`POST /safari/knowledge/pack/list` 也不会返回；只有按 `pack_id` 直接访问此类知识时才会出现。",
             "enum": [
               "account",
               "team",
               "channel"
-            ],
-            "type": "string"
+            ]
           },
           "scope_id": {
+            "type": "integer",
             "description": "范围归属 ID：账户范围为账户 ID，团队范围为团队 ID。",
-            "format": "int64",
-            "type": "integer"
+            "format": "int64"
           },
           "team_name": {
-            "description": "所属团队的显示名称（仅团队范围）；为空时省略（账户范围，或团队名称解析失败）。",
-            "type": "string"
+            "type": "string",
+            "description": "所属团队的显示名称（仅团队范围）；为空时省略（账户范围，或团队名称解析失败）。"
+          },
+          "file_count": {
+            "type": "integer",
+            "description": "知识中当前的文件数量。"
           },
           "total_bytes": {
-            "description": "知识内所有文件的总字节数。",
-            "format": "int64",
-            "type": "integer"
+            "type": "integer",
+            "description": "所有文件的总大小（字节），每份知识上限 5 MiB。",
+            "format": "int64"
+          },
+          "version": {
+            "type": "integer",
+            "description": "知识版本号。从 0 开始，每次写入或删除文件加 1；移动知识范围不会改变版本号。"
+          },
+          "duty_version": {
+            "type": "integer",
+            "description": "最近一次写入 `DUTY.md` 时的 `version`。写入 `DUTY.md` 会把它设为新的 `version`；当 `version` 更大时，说明 `DUTY.md` 上次更新后又有文件被新增、修改或删除，`DUTY.md` 可能未覆盖全部文件。"
+          },
+          "created_by": {
+            "type": "integer",
+            "description": "触发创建该知识的成员 ID。账户知识会在第一个需要它的请求中自动创建，因此可能是账户内任意成员。",
+            "format": "int64"
+          },
+          "created_at_ms": {
+            "type": "integer",
+            "description": "创建时间的 Unix 毫秒时间戳。",
+            "format": "int64"
           },
           "updated_at_ms": {
+            "type": "integer",
             "description": "最近修改时间的 Unix 毫秒时间戳。",
-            "format": "int64",
-            "type": "integer"
+            "format": "int64"
           },
-          "version": {
-            "description": "知识版本号，文件每次变更时递增。",
-            "type": "integer"
+          "can_edit": {
+            "type": "boolean",
+            "description": "调用者能否修改该知识及其文件：`account` 范围仅账户 Owner 和管理员为 `true`；`team` 范围仅当调用者是该团队成员时为 `true`（Owner 和管理员也不例外）。"
           }
         },
         "required": [
@@ -13264,51 +13623,50 @@
           "created_at_ms",
           "updated_at_ms",
           "can_edit"
-        ],
-        "type": "object"
+        ]
       },
       "KnowledgePackListRequest": {
+        "type": "object",
         "description": "知识列表的过滤与分页参数。",
         "properties": {
-          "include_account": {
-            "description": "是否包含账户范围的知识；默认为 true。",
-            "type": [
-              "boolean",
-              "null"
-            ]
-          },
-          "limit": {
-            "description": "每页条数。",
-            "type": "integer"
-          },
           "p": {
-            "description": "页码，从 1 开始；`p` 与 `limit` 均未设置时返回全部结果。",
-            "type": "integer"
+            "type": "integer",
+            "description": "页码，从 1 开始。`p` 与 `limit` 都不传（或 ≤ 0）时不分页，返回全部匹配结果；只传 `limit` 时 `p` 默认为 1。"
           },
-          "query": {
-            "description": "对知识 ID、范围、范围 ID/账户 ID 和团队名称做大小写不敏感的子串过滤。",
-            "maxLength": 128,
-            "type": "string"
+          "limit": {
+            "type": "integer",
+            "description": "每页条数。传了 `p` 但未传 `limit` 时默认为 20；不限制上限。"
           },
           "scope": {
-            "description": "限定范围；`all`（默认）会覆盖 `include_account`。可选值：`all`（账户范围 + 可见团队范围）、`account`（仅账户级知识）、`team`（仅团队级知识，可配合 `team_ids` 过滤）。",
+            "type": "string",
+            "description": "返回哪些范围：\n- `all`（默认）：账户知识（`include_account` 为 `false` 时除外）加上可见的团队知识。\n- `account`：仅账户知识，忽略 `include_account` 和 `team_ids`。\n- `team`：仅团队知识，可用 `team_ids` 进一步筛选；忽略 `include_account`。",
             "enum": [
               "all",
               "account",
               "team"
-            ],
-            "type": "string"
+            ]
+          },
+          "query": {
+            "type": "string",
+            "description": "对知识 ID、范围、范围 ID、账户 ID 和团队名称做大小写不敏感的子串过滤；账户知识还可匹配 `账户`/`账号`，团队知识还可匹配 `团队`。首尾空格会被忽略。",
+            "maxLength": 128
           },
           "team_ids": {
-            "description": "限定团队 ID；非管理员会与其所属团队取交集。",
+            "type": "array",
+            "description": "将团队知识限定在这些团队 ID 内。调用者不属于的团队 ID 会被静默丢弃——对所有调用者都一样，包括 Owner 和管理员。",
             "items": {
-              "format": "int64",
-              "type": "integer"
-            },
-            "type": "array"
+              "type": "integer",
+              "format": "int64"
+            }
+          },
+          "include_account": {
+            "type": [
+              "boolean",
+              "null"
+            ],
+            "description": "`scope` 为 `all` 或未传时是否包含账户知识，默认 `true`。"
           }
-        },
-        "type": "object"
+        }
       },
       "KnowledgePackListResponse": {
         "description": "可见的知识及过滤后的总数。",
@@ -13333,64 +13691,64 @@
         "type": "object"
       },
       "KnowledgePackUpdateRequest": {
+        "type": "object",
         "description": "将知识移动到其他范围。",
         "properties": {
           "pack_id": {
-            "description": "要更新的知识 ID。",
-            "type": "string"
+            "type": "string",
+            "description": "要更新的知识 ID。"
           },
           "scope": {
-            "description": "目标范围；不传则为空操作，返回当前知识。",
-            "enum": [
-              "account",
-              "team"
-            ],
             "type": [
               "string",
               "null"
+            ],
+            "description": "目标范围。不传则不做修改，直接返回当前知识。\n- `account`：设为账户知识（仅账户 Owner 和管理员）。\n- `team`：移到 `scope_id` 指定的团队（调用者须是该团队成员）。\n其他取值返回 `InvalidParameter`。目标范围已有知识时返回 `ReferenceExist`。",
+            "enum": [
+              "account",
+              "team"
             ]
           },
           "scope_id": {
-            "description": "目标团队 ID；`scope` 为 `team` 时必填，为 `account` 时自动设置。",
-            "format": "int64",
             "type": [
               "integer",
               "null"
-            ]
+            ],
+            "description": "目标团队 ID。`scope` 为 `team` 时必填（非 0）；`scope` 为 `account` 时忽略（使用账户 ID）。",
+            "format": "int64"
           }
         },
         "required": [
           "pack_id"
-        ],
-        "type": "object"
+        ]
       },
       "KnowledgeWarning": {
+        "type": "object",
         "description": "文件上传/删除返回的非阻塞提示，例如指向已删除文件的引用。",
         "properties": {
           "code": {
+            "type": "string",
             "description": "提示码。可选值：`unresolved_reference`（写入的文件内容中 @ref 引用了知识内不存在的文件，`ref` 给出该引用）、`still_referenced_by`（被删除的文件仍被知识内其他文件 @ref 引用，`refs` 列出引用方）。",
             "enum": [
               "unresolved_reference",
               "still_referenced_by"
-            ],
-            "type": "string"
+            ]
           },
           "ref": {
-            "description": "与提示相关的单个引用。",
-            "type": "string"
+            "type": "string",
+            "description": "仅 `unresolved_reference` 时返回：知识中不存在的被引用路径。"
           },
           "refs": {
-            "description": "与提示相关的多个引用。",
+            "type": "array",
+            "description": "仅 `still_referenced_by` 时返回：仍引用被删文件的其他文件的 `rel_path` 列表。",
             "items": {
               "type": "string"
-            },
-            "type": "array"
+            }
           }
         },
         "required": [
           "code"
-        ],
-        "type": "object"
+        ]
       },
       "LicenseListResponse": {
         "description": "当前账户中持有固定或临时 On-call 许可的人员。",
@@ -13493,171 +13851,155 @@
         "type": "object"
       },
       "ListChangeRequest": {
+        "type": "object",
         "properties": {
-          "asc": {
-            "description": "为 true 时升序排序，默认降序。",
-            "type": "boolean"
+          "start_time": {
+            "type": "integer",
+            "format": "int64",
+            "description": "查询时间窗起点，Unix 时间戳（秒）。实际为必填：必须小于 `end_time`，时间跨度不超过 31 天。变更的 [start_time, last_time] 区间与时间窗有重叠即匹配。",
+            "minimum": 0
           },
-          "channel_ids": {
-            "description": "按协作空间 ID 过滤。",
-            "items": {
-              "description": "",
-              "format": "int64",
-              "type": "integer"
-            },
-            "type": "array"
+          "end_time": {
+            "type": "integer",
+            "format": "int64",
+            "description": "查询时间窗终点，Unix 时间戳（秒）。实际为必填，约束见 `start_time`。",
+            "minimum": 0
           },
-          "data_source_id": {
-            "deprecated": true,
-            "description": "已废弃：请使用 `integration_ids`。按单个集成 ID 过滤。",
+          "p": {
+            "type": "integer",
+            "description": "页码，从 1 开始，默认 1。",
             "format": "int64",
             "minimum": 1,
-            "type": "integer"
-          },
-          "data_source_ids": {
-            "deprecated": true,
-            "description": "已废弃：请使用 `integration_ids`。提供时至少 1 个。",
-            "items": {
-              "description": "集成 ID。",
-              "format": "int64",
-              "type": "integer"
-            },
-            "minItems": 1,
-            "type": "array"
+            "default": 1
           },
-          "end_time": {
-            "description": "查询窗口终点，Unix 时间戳（秒）。默认值与约束见 `start_time`。",
+          "limit": {
+            "type": "integer",
+            "description": "每页条数，1-100，默认 10。",
             "format": "int64",
-            "minimum": 0,
-            "type": "integer"
+            "minimum": 1,
+            "maximum": 100,
+            "default": 10
           },
-          "filters": {
-            "description": "结构化过滤条件，与查询按 AND 组合（如按标签过滤）。以 `incident` 开头的 key 会被忽略。",
+          "channel_ids": {
+            "type": "array",
             "items": {
-              "$ref": "#/components/schemas/FilterCondition"
+              "type": "integer",
+              "description": "协作空间 ID。",
+              "format": "int64"
             },
-            "type": "array"
-          },
-          "include_events": {
-            "description": "为 true 时返回每个变更的底层变更事件。",
-            "type": "boolean"
-          },
-          "integration_id": {
-            "deprecated": true,
-            "description": "已废弃：请使用 `integration_ids`。按单个集成 ID 过滤。",
-            "format": "int64",
-            "minimum": 1,
-            "type": "integer"
+            "description": "按协作空间 ID 过滤。"
           },
           "integration_ids": {
-            "description": "按上报集成 ID 过滤。提供时至少 1 个。",
+            "type": "array",
             "items": {
-              "description": "",
-              "format": "int64",
-              "type": "integer"
+              "type": "integer",
+              "description": "集成 ID。",
+              "format": "int64"
             },
-            "minItems": 1,
-            "type": "array"
-          },
-          "limit": {
-            "default": 10,
-            "description": "每页条数。",
-            "format": "int64",
-            "maximum": 100,
-            "minimum": 1,
-            "type": "integer"
+            "description": "按上报集成 ID 过滤。提供时至少 1 个。",
+            "minItems": 1
           },
           "orderby": {
+            "type": "string",
             "description": "排序字段：`start_time` 或 `last_time`，默认 `start_time`。",
             "enum": [
               "start_time",
               "last_time"
-            ],
-            "type": "string"
+            ]
           },
-          "p": {
-            "description": "页码，从 1 开始。",
-            "format": "int64",
-            "minimum": 1,
-            "type": "integer"
+          "asc": {
+            "type": "boolean",
+            "description": "为 true 时升序排序，默认降序。"
+          },
+          "include_events": {
+            "type": "boolean",
+            "description": "为 true 时返回每个变更的底层变更事件。"
           },
           "query": {
-            "description": "对变更标题、change_key、描述做大小写不敏感的子串或正则匹配。非法正则按字面量匹配。",
-            "type": "string"
+            "type": "string",
+            "description": "对变更标题、change_key、描述做大小写不敏感的子串或正则匹配。非法正则按字面量匹配。"
           },
-          "start_time": {
-            "description": "查询窗口起点，Unix 时间戳（秒）。可选——`start_time` 和 `end_time` 都不传或为 0 时，默认查询最近一小时。必须小于 `end_time`，跨度不超过 31 天。当变更的 [start_time, last_time] 区间与查询窗口重叠时命中。",
+          "filters": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/FilterCondition"
+            },
+            "description": "结构化过滤条件，与查询按 AND 组合（如按标签过滤）。以 `incident` 开头的 key 会被忽略。"
+          },
+          "data_source_ids": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "int64",
+              "description": "集成 ID。"
+            },
+            "description": "已废弃：请使用 `integration_ids`。提供时至少 1 个。",
+            "deprecated": true,
+            "minItems": 1
+          },
+          "data_source_id": {
+            "type": "integer",
             "format": "int64",
-            "minimum": 0,
-            "type": "integer"
+            "minimum": 1,
+            "deprecated": true,
+            "description": "已废弃：请使用 `integration_ids`。按单个集成 ID 过滤。"
+          },
+          "integration_id": {
+            "type": "integer",
+            "format": "int64",
+            "minimum": 1,
+            "deprecated": true,
+            "description": "已废弃：请使用 `integration_ids`。按单个集成 ID 过滤。"
           }
         },
-        "type": "object"
+        "required": [
+          "start_time",
+          "end_time"
+        ]
       },
       "ListChangeResponse": {
+        "type": "object",
         "properties": {
+          "total": {
+            "type": "integer",
+            "description": "匹配的变更总数。",
+            "format": "int64"
+          },
           "has_next_page": {
-            "description": "当前页之后是否还有更多页。",
-            "type": "boolean"
+            "type": "boolean",
+            "description": "当前页之后是否还有更多页。"
           },
           "items": {
-            "description": "当前页的变更列表。",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/ChangeItem"
             },
-            "type": "array"
-          },
-          "total": {
-            "description": "匹配的变更总数。",
-            "format": "int64",
-            "type": "integer"
+            "description": "当前页的变更列表。"
           }
         },
-        "type": "object"
+        "required": [
+          "total",
+          "has_next_page",
+          "items"
+        ]
       },
       "ListChannelsRequest": {
+        "type": "object",
         "properties": {
-          "asc": {
-            "description": "为 true 时升序排列；默认为 false（降序）。",
-            "type": "boolean"
-          },
-          "channel_ids": {
-            "description": "按指定协作空间 ID 过滤。",
-            "items": {
-              "format": "int64",
-              "type": "integer"
-            },
-            "type": "array"
-          },
-          "channel_name": {
-            "description": "协作空间名称精确匹配，优先级高于 `query` 的名称过滤。必须为合法 UTF-8，非法字节序列会返回 `InvalidParameter`。",
-            "type": "string"
-          },
-          "is_brief": {
-            "description": "为 true 时仅返回 `channel_id`、`channel_name`、`description` 和 `status` 字段，且不分页，一次返回全部匹配结果。",
-            "type": "boolean"
-          },
-          "is_my_managed": {
-            "description": "为 true 时仅返回当前用户可管理的协作空间。",
-            "type": "boolean"
-          },
-          "is_my_starred": {
-            "description": "为 true 时仅返回当前用户收藏的协作空间，与 `is_my_team` 互斥。",
-            "type": "boolean"
-          },
-          "is_my_team": {
-            "description": "为 true 时仅返回当前用户所在团队持有的协作空间，与 `is_my_starred` 互斥。",
-            "type": "boolean"
+          "p": {
+            "type": "integer",
+            "minimum": 1,
+            "description": "页码，从 1 开始。请始终传入：不传时返回第一页，但 `has_next_page` 不可靠。"
           },
           "limit": {
-            "default": 100,
-            "description": "每页大小，未传时默认为 100。",
-            "maximum": 100,
+            "type": "integer",
             "minimum": 1,
-            "type": "integer"
+            "maximum": 100,
+            "default": 100,
+            "description": "每页大小，未传时默认为 100。"
           },
           "orderby": {
-            "description": "排序字段。默认为 `created_at`。",
+            "type": "string",
             "enum": [
               "ranking",
               "created_at",
@@ -13665,53 +14007,79 @@
               "channel_name",
               "last_incident_at"
             ],
-            "type": "string"
+            "description": "排序字段，默认 `created_at`。`ranking` 按调用者在控制台保存的自定义顺序排序，未保存时按创建顺序；`channel_name` 不区分大小写排序。"
           },
-          "p": {
-            "description": "页码，从 1 开始。",
-            "minimum": 1,
-            "type": "integer"
+          "asc": {
+            "type": "boolean",
+            "description": "为 true 时升序排列；默认为 false（降序）。"
           },
-          "query": {
-            "description": "针对协作空间名称和描述的不区分大小写正则匹配；正则语法非法时按字面量匹配。必须为合法 UTF-8，非法字节序列会返回 `InvalidParameter`。",
-            "type": "string"
+          "is_my_managed": {
+            "type": "boolean",
+            "description": "为 true 时只返回所属团队为调用者所在团队、或由调用者创建的协作空间。优先于 `is_my_team` 与 `is_my_starred`。"
+          },
+          "is_my_starred": {
+            "type": "boolean",
+            "description": "为 true 时只返回调用者收藏的协作空间。不能与 `is_my_team` 同时为 true。"
+          },
+          "is_brief": {
+            "type": "boolean",
+            "description": "为 true 时每项只返回 `channel_id`、`channel_name`、`description`、`status`、`is_starred`，并一次返回全部结果。"
+          },
+          "is_my_team": {
+            "type": "boolean",
+            "description": "为 true 时只返回所属团队为调用者所在团队的协作空间。不能与 `is_my_starred` 同时为 true。"
           },
           "team_ids": {
-            "description": "按团队 ID 过滤。",
+            "type": "array",
             "items": {
-              "format": "int64",
-              "type": "integer"
+              "type": "integer",
+              "format": "int64"
             },
-            "type": "array"
+            "description": "只返回所属团队在列表中的协作空间。`is_my_managed` 或 `is_my_team` 为 true 时忽略。"
+          },
+          "query": {
+            "type": "string",
+            "description": "针对协作空间名称和描述的不区分大小写正则匹配；正则语法非法时按字面量匹配。必须为合法 UTF-8，非法字节序列会返回 `InvalidParameter`。"
+          },
+          "channel_ids": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "int64"
+            },
+            "description": "按指定协作空间 ID 过滤。"
+          },
+          "channel_name": {
+            "type": "string",
+            "description": "协作空间名称精确匹配，优先级高于 `query` 的名称过滤。必须为合法 UTF-8，非法字节序列会返回 `InvalidParameter`。"
           }
-        },
-        "type": "object"
+        }
       },
       "ListChannelsResponse": {
+        "type": "object",
+        "required": [
+          "items",
+          "total",
+          "has_next_page"
+        ],
         "properties": {
-          "has_next_page": {
-            "description": "是否还有下一页。",
-            "type": "boolean"
-          },
           "items": {
-            "description": "当前页的协作空间列表。",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/ChannelItem"
             },
-            "type": "array"
+            "description": "当前页的协作空间列表。"
           },
           "total": {
-            "description": "匹配到的协作空间总数。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "所有页中匹配的协作空间总数。"
+          },
+          "has_next_page": {
+            "type": "boolean",
+            "description": "是否还有下一页。仅在传入 `p` 时可靠。"
           }
-        },
-        "required": [
-          "items",
-          "total",
-          "has_next_page"
-        ],
-        "type": "object"
+        }
       },
       "ListDropRulesResponse": {
         "properties": {
@@ -13729,19 +14097,19 @@
         "type": "object"
       },
       "ListEscalationRulesResponse": {
+        "type": "object",
+        "required": [
+          "items"
+        ],
         "properties": {
           "items": {
-            "description": "该协作空间下的全部升级规则（不含已删除），按优先级升序。",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/EscalateRuleItem"
             },
-            "type": "array"
+            "description": "协作空间的分派策略（不含已删除），按匹配顺序排列：先按 `priority` 升序，再按创建时间。"
           }
-        },
-        "required": [
-          "items"
-        ],
-        "type": "object"
+        }
       },
       "ListIncidentAlertsRequest": {
         "description": "查询故障关联告警的过滤条件。",
@@ -13784,26 +14152,26 @@
         "type": "object"
       },
       "ListIncidentAlertsResponse": {
+        "type": "object",
         "description": "故障下的告警分页列表。",
+        "required": [
+          "items",
+          "total"
+        ],
         "properties": {
           "items": {
-            "description": "告警列表。",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/AlertInfo"
             },
-            "type": "array"
+            "description": "当前页的告警；没有匹配告警时为空数组。"
           },
           "total": {
-            "description": "命中总数。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "命中总数。"
           }
-        },
-        "required": [
-          "items",
-          "total"
-        ],
-        "type": "object"
+        }
       },
       "ListIncidentCommentTypesRequest": {
         "description": "无参数。该接口始终返回调用账户的全部评论类型。",
@@ -13811,56 +14179,60 @@
         "type": "object"
       },
       "ListIncidentCommentTypesResponse": {
+        "type": "object",
         "description": "账户评论类型的完整列表，按展示位置排序。",
         "properties": {
           "items": {
-            "description": "账户的全部评论类型，按展示位置排序。",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/IncidentCommentTypeItem"
             },
-            "type": "array"
+            "description": "账户的全部评论类型，按展示位置排序。"
           }
         },
-        "type": "object"
+        "required": [
+          "items"
+        ]
       },
       "ListIncidentFeedRequest": {
+        "type": "object",
         "description": "获取故障时间线的参数。",
+        "required": [
+          "incident_id"
+        ],
         "properties": {
-          "asc": {
-            "description": "true 为按时间升序。",
-            "type": "boolean"
-          },
           "incident_id": {
-            "description": "故障 ID（MongoDB ObjectID）。",
+            "type": "string",
             "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
+            "description": "故障 ID（MongoDB ObjectID）。"
           },
-          "limit": {
-            "default": 20,
-            "description": "分页大小，最大 100。",
+          "p": {
+            "type": "integer",
             "format": "int64",
-            "maximum": 100,
             "minimum": 1,
-            "type": "integer"
-          },
-          "p": {
             "description": "页码，从 1 开始。",
+            "default": 1
+          },
+          "limit": {
+            "type": "integer",
             "format": "int64",
             "minimum": 1,
-            "type": "integer"
+            "maximum": 100,
+            "default": 20,
+            "description": "分页大小，最大 100。"
+          },
+          "asc": {
+            "type": "boolean",
+            "description": "true 为按时间升序。"
           },
           "types": {
-            "description": "可选类型过滤，仅返回指定类型的时间线条目。",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/IncidentFeedType"
             },
-            "type": "array"
+            "description": "只返回这些类型的条目；不传时返回全部类型。"
           }
-        },
-        "required": [
-          "incident_id"
-        ],
-        "type": "object"
+        }
       },
       "ListIncidentFeedResponse": {
         "description": "故障时间线分页结果。",
@@ -13901,140 +14273,144 @@
         "type": "object"
       },
       "ListIncidentsRequest": {
+        "type": "object",
         "description": "查询故障列表的过滤条件。`start_time` 与 `end_time` 必填，时间窗口不超过 31 天。",
+        "required": [
+          "start_time",
+          "end_time"
+        ],
         "properties": {
-          "acker_ids": {
-            "description": "按认领人过滤，取值为成员 ID，可通过 `POST /member/list` 获取。",
-            "items": {
-              "format": "int64",
-              "type": "integer"
-            },
-            "type": "array"
+          "start_time": {
+            "type": "integer",
+            "format": "int64",
+            "description": "时间窗口起点（Unix 秒）。与 `end_time` 构成的窗口最长 31 天，按故障发生时间过滤。"
+          },
+          "end_time": {
+            "type": "integer",
+            "format": "int64",
+            "description": "时间窗口终点（Unix 秒），必须大于 `start_time` 且不超过 31 天。"
           },
           "asc": {
-            "description": "true 为升序。",
-            "type": "boolean"
+            "type": "boolean",
+            "description": "true 为升序。"
+          },
+          "is_snoozed": {
+            "type": "boolean",
+            "description": "true 时仅返回已暂停通知的故障。"
+          },
+          "is_my_team": {
+            "type": "boolean",
+            "description": "true 时仅返回用户所属团队管理的协作空间中的故障。"
+          },
+          "is_my_channel": {
+            "type": "boolean",
+            "description": "true 时仅返回用户个人管理的协作空间中的故障。"
+          },
+          "ever_muted": {
+            "type": "boolean",
+            "description": "true 时仅返回曾被静默的故障。"
+          },
+          "is_rare": {
+            "type": "boolean",
+            "description": "true 时仅返回新奇故障。"
+          },
+          "has_unfinished_work_item": {
+            "type": "boolean",
+            "description": "为 true 时只返回仍有状态既不是 `done` 也不是 `cancelled` 的行动项或后续行动的故障。`false` 不做过滤。"
+          },
+          "progress": {
+            "type": "string",
+            "description": "要匹配的处理进度，多个值用英文逗号分隔，例如 `Triggered,Processing`。取值：`Triggered` 未认领；`Processing` 已认领处理中；`Closed` 已关闭。不传时匹配全部进度。"
+          },
+          "query": {
+            "type": "string",
+            "description": "全文搜索关键词。"
+          },
+          "incident_severity": {
+            "type": "string",
+            "description": "要匹配的严重程度，多个值用英文逗号分隔，例如 `Critical,Warning`。取值：`Critical` 严重、`Warning` 警告、`Info` 提醒。"
           },
           "channel_ids": {
-            "description": "协作空间 ID 列表，0 表示独立故障。",
+            "type": "array",
             "items": {
-              "format": "int64",
-              "type": "integer"
+              "type": "integer",
+              "format": "int64"
             },
-            "type": "array"
+            "description": "协作空间 ID 列表，0 表示独立故障。"
           },
-          "closer_ids": {
-            "description": "关闭人员成员 ID，0 表示自动关闭。",
+          "team_ids": {
+            "type": "array",
             "items": {
-              "format": "int64",
-              "type": "integer"
+              "type": "integer",
+              "format": "int64"
             },
-            "type": "array"
+            "description": "团队 ID 列表，通过协作空间所属团队进行解析。"
           },
-          "creator_ids": {
-            "description": "创建人员成员 ID，0 表示自动创建。",
+          "responder_ids": {
+            "type": "array",
             "items": {
-              "format": "int64",
-              "type": "integer"
+              "type": "integer",
+              "format": "int64"
             },
-            "type": "array"
+            "description": "按处理人过滤，取值为成员 ID，可通过 `POST /member/list` 获取。"
           },
-          "end_time": {
-            "description": "时间窗口终点（Unix 秒），必须大于 `start_time` 且不超过 31 天。",
-            "format": "int64",
-            "type": "integer"
+          "acker_ids": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "int64"
+            },
+            "description": "按认领人过滤，取值为成员 ID，可通过 `POST /member/list` 获取。"
           },
-          "ever_muted": {
-            "description": "true 时仅返回曾被静默的故障。",
-            "type": "boolean"
+          "creator_ids": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "int64"
+            },
+            "description": "创建人员成员 ID，0 表示自动创建。"
+          },
+          "closer_ids": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "int64"
+            },
+            "description": "关闭人员成员 ID，0 表示自动关闭。"
           },
           "incident_ids": {
-            "description": "指定故障 ID 列表进行过滤。",
+            "type": "array",
             "items": {
               "type": "string"
             },
-            "type": "array"
-          },
-          "incident_severity": {
-            "description": "严重程度过滤，逗号分隔（`Critical,Warning,Info`）。",
-            "type": "string"
-          },
-          "is_my_channel": {
-            "description": "true 时仅返回用户个人管理的协作空间中的故障。",
-            "type": "boolean"
-          },
-          "is_my_team": {
-            "description": "true 时仅返回用户所属团队管理的协作空间中的故障。",
-            "type": "boolean"
-          },
-          "is_rare": {
-            "description": "true 时仅返回新奇故障。",
-            "type": "boolean"
-          },
-          "is_snoozed": {
-            "description": "true 时仅返回已暂停通知的故障。",
-            "type": "boolean"
-          },
-          "limit": {
-            "default": 20,
-            "description": "分页大小，最大 100。",
-            "format": "int64",
-            "maximum": 100,
-            "minimum": 0,
-            "type": "integer"
+            "description": "指定故障 ID 列表进行过滤。"
           },
           "nums": {
-            "description": "按故障短编号过滤，即控制台故障标题前展示的编号。",
+            "type": "array",
             "items": {
               "type": "string"
             },
-            "type": "array"
+            "description": "按故障短编号过滤，即控制台故障标题前展示的编号。"
           },
           "p": {
-            "description": "页码，从 1 开始。",
+            "type": "integer",
             "format": "int64",
             "minimum": 0,
-            "type": "integer"
-          },
-          "progress": {
-            "description": "进展状态过滤，逗号分隔（如 `Triggered,Processing`）。",
-            "type": "string"
-          },
-          "query": {
-            "description": "全文搜索关键词。",
-            "type": "string"
-          },
-          "responder_ids": {
-            "description": "按处理人过滤，取值为成员 ID，可通过 `POST /member/list` 获取。",
-            "items": {
-              "format": "int64",
-              "type": "integer"
-            },
-            "type": "array"
-          },
-          "search_after_ctx": {
-            "description": "上一次响应返回的翻页游标。",
-            "type": "string"
+            "description": "页码，从 1 开始。"
           },
-          "start_time": {
-            "description": "时间窗口起点（Unix 秒）。与 `end_time` 构成的窗口最长 31 天，按故障发生时间过滤。",
+          "limit": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "minimum": 0,
+            "maximum": 100,
+            "default": 20,
+            "description": "分页大小，最大 100。"
           },
-          "team_ids": {
-            "description": "团队 ID 列表，通过协作空间所属团队进行解析。",
-            "items": {
-              "format": "int64",
-              "type": "integer"
-            },
-            "type": "array"
+          "search_after_ctx": {
+            "type": "string",
+            "description": "上次响应返回的 `search_after_ctx` 游标；设置后忽略 `p`。"
           }
-        },
-        "required": [
-          "start_time",
-          "end_time"
-        ],
-        "type": "object"
+        }
       },
       "ListInhibitRulesResponse": {
         "properties": {
@@ -14093,142 +14469,139 @@
         "type": "object"
       },
       "ListPostMortemTemplatesRequest": {
+        "type": "object",
         "description": "故障复盘模板的分页与排序参数。",
         "properties": {
-          "asc": {
-            "description": "为 true 时按升序排序。",
-            "type": "boolean"
-          },
-          "limit": {
-            "default": 20,
-            "description": "每页数量，最多 100。",
-            "format": "int64",
-            "maximum": 100,
-            "minimum": 0,
-            "type": "integer"
-          },
           "order_by": {
-            "description": "排序字段。",
+            "type": "string",
             "enum": [
               "created_at_seconds"
             ],
-            "type": "string"
+            "description": "自定义模板的排序字段。仅支持 `created_at_seconds`，也是默认值。"
+          },
+          "asc": {
+            "type": "boolean",
+            "description": "为 true 时自定义模板升序排列；默认 false（最新在前）。"
           },
           "p": {
-            "description": "页码，从 1 开始。",
+            "type": "integer",
             "format": "int64",
             "minimum": 0,
-            "type": "integer"
+            "description": "页码，从 1 开始；0 或省略表示 1。"
+          },
+          "limit": {
+            "type": "integer",
+            "format": "int64",
+            "minimum": 0,
+            "maximum": 100,
+            "default": 20,
+            "description": "每页条数，1–100；0 或省略表示 20。"
           },
           "search_after_ctx": {
-            "description": "上一页响应返回的向后分页游标。",
-            "type": "string"
+            "type": "string",
+            "description": "本接口不支持游标分页，请勿设置，使用 `p` 分页。若传入则必须是整数字符串，且此时 `p` 被忽略（结果从第一页开始）。"
           }
-        },
-        "type": "object"
+        }
       },
       "ListPostMortemTemplatesResponse": {
+        "type": "object",
         "description": "分页后的故障复盘模板列表。",
+        "required": [
+          "items",
+          "total",
+          "has_next_page"
+        ],
         "properties": {
-          "has_next_page": {
-            "description": "为 true 表示还有下一页。",
-            "type": "boolean"
-          },
           "items": {
-            "description": "当前页的模板。",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/PostMortemTemplate"
             },
-            "type": "array"
-          },
-          "search_after_ctx": {
-            "description": "向后分页游标。",
-            "type": "string"
+            "description": "当前页的模板；第 1 页的第一项为内置模板。"
           },
           "total": {
-            "description": "匹配的模板总数。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "模板总数，包含内置模板。"
+          },
+          "has_next_page": {
+            "type": "boolean",
+            "description": "还有下一页时为 true。"
           }
-        },
-        "required": [
-          "items",
-          "total",
-          "has_next_page"
-        ],
-        "type": "object"
+        }
       },
       "ListPostMortemsRequest": {
+        "type": "object",
         "description": "查询复盘报告列表的过滤条件。",
         "properties": {
-          "asc": {
-            "description": "true 为升序。",
-            "type": "boolean"
+          "status": {
+            "type": "string",
+            "enum": [
+              "drafting",
+              "published"
+            ],
+            "description": "可选的复盘状态过滤：`drafting` 仅返回草稿，`published` 仅返回已发布。缺省时返回全部状态的复盘。"
           },
-          "channel_ids": {
-            "description": "限定查询的协作空间 ID。",
+          "team_ids": {
+            "type": "array",
             "items": {
-              "format": "int64",
-              "type": "integer"
+              "type": "integer",
+              "format": "int64"
             },
-            "type": "array"
+            "description": "限定查询的团队 ID。"
           },
-          "created_at_end_seconds": {
-            "description": "复盘创建时间上界（Unix 秒）。",
-            "format": "int64",
-            "minimum": 0,
-            "type": "integer"
+          "channel_ids": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "int64"
+            },
+            "description": "限定查询的协作空间 ID。"
           },
           "created_at_start_seconds": {
-            "description": "复盘创建时间下界（Unix 秒）。",
+            "type": "integer",
             "format": "int64",
             "minimum": 0,
-            "type": "integer"
+            "description": "复盘创建时间下界（Unix 秒）。"
           },
-          "limit": {
-            "default": 20,
-            "description": "分页大小，最大 100。",
+          "created_at_end_seconds": {
+            "type": "integer",
             "format": "int64",
-            "maximum": 100,
             "minimum": 0,
-            "type": "integer"
+            "description": "复盘创建时间上界（Unix 秒）。"
           },
           "order_by": {
-            "description": "排序字段。",
+            "type": "string",
             "enum": [
               "created_at_seconds",
               "updated_at_seconds"
             ],
-            "type": "string"
+            "description": "排序字段：`created_at_seconds` 按创建时间，`updated_at_seconds` 按最后更新时间。",
+            "default": "created_at_seconds"
+          },
+          "asc": {
+            "type": "boolean",
+            "description": "true 为升序。"
           },
           "p": {
-            "description": "页码，从 1 开始。",
+            "type": "integer",
             "format": "int64",
             "minimum": 0,
-            "type": "integer"
-          },
-          "search_after_ctx": {
-            "description": "上一次响应返回的翻页游标。",
-            "type": "string"
+            "description": "页码，从 1 开始。"
           },
-          "status": {
-            "description": "可选的复盘状态过滤：`drafting` 仅返回草稿，`published` 仅返回已发布。缺省时返回全部状态的复盘。",
-            "enum": [
-              "drafting",
-              "published"
-            ],
-            "type": "string"
+          "limit": {
+            "type": "integer",
+            "format": "int64",
+            "minimum": 0,
+            "maximum": 100,
+            "default": 20,
+            "description": "分页大小，最大 100。"
           },
-          "team_ids": {
-            "description": "限定查询的团队 ID。",
-            "items": {
-              "format": "int64",
-              "type": "integer"
-            },
-            "type": "array"
+          "search_after_ctx": {
+            "type": "string",
+            "description": "上一次响应返回的翻页游标。"
           }
-        },
-        "type": "object"
+        }
       },
       "ListPostMortemsResponse": {
         "description": "复盘报告分页列表。",
@@ -14265,7 +14638,7 @@
         "description": "远程配置历史查询请求。默认按最新在前排序。",
         "properties": {
           "application_id": {
-            "description": "RUM 应用 ID。",
+            "description": "RUM 应用 ID，可通过 `POST /rum/application/list` 获取。",
             "type": "string"
           },
           "asc": {
@@ -14274,13 +14647,12 @@
           },
           "limit": {
             "default": 20,
-            "description": "每页条数。默认 20，最大 100。",
-            "maximum": 100,
+            "description": "每页条数。`0` 或负数按 20 处理；大于 100 时按 100 处理。",
             "type": "integer"
           },
           "orderby": {
             "default": "updated_at",
-            "description": "排序字段。默认 `updated_at`。",
+            "description": "排序字段：\n\n- `updated_at`：发布时间（默认）。\n- `version`：版本号。\n\n其他取值会回退为 `updated_at`。",
             "enum": [
               "updated_at",
               "version"
@@ -14304,40 +14676,45 @@
         "description": "远程配置历史分页结果。",
         "properties": {
           "has_next_page": {
-            "description": "是否还有下一页。",
+            "description": "本页之后还有更多版本时为 `true`。",
             "type": "boolean"
           },
           "items": {
-            "description": "版本列表，默认最新在前。",
+            "description": "本页的版本，默认最新在前。应用从未配置过时为空数组。",
             "items": {
               "$ref": "#/components/schemas/RemoteConfigHistoryItem"
             },
             "type": "array"
           },
           "total": {
-            "description": "版本总数。",
+            "description": "保留的版本总数（最多 50 个）。",
             "type": "integer"
           }
         },
-        "type": "object"
+        "type": "object",
+        "required": [
+          "total",
+          "has_next_page",
+          "items"
+        ]
       },
       "ListRoutesRequest": {
+        "type": "object",
         "description": "批量查询多个集成路由规则所需的参数。",
+        "required": [
+          "integration_ids"
+        ],
         "properties": {
           "integration_ids": {
-            "description": "需要查询路由规则的集成 ID 列表。",
+            "type": "array",
             "items": {
-              "format": "int64",
-              "type": "integer"
+              "type": "integer",
+              "format": "int64"
             },
-            "minItems": 1,
-            "type": "array"
+            "description": "要查询路由规则的共享集成 ID，至少一个，可通过 `POST /integration/list` 获取。",
+            "minItems": 1
           }
-        },
-        "required": [
-          "integration_ids"
-        ],
-        "type": "object"
+        }
       },
       "ListRoutesResponse": {
         "description": "路由规则列表的响应包装。",
@@ -14460,111 +14837,129 @@
         "type": "object"
       },
       "ListWebhookHistoryRequest": {
+        "type": "object",
         "description": "出站 Webhook 推送历史的筛选参数。查询必须指定毫秒级的时间窗口；使用 `search_after_ctx` 进行游标分页。",
+        "required": [
+          "limit",
+          "start_time",
+          "end_time"
+        ],
         "properties": {
-          "asc": {
-            "description": "为 true 时按 `event_time` 升序排序，否则降序。",
-            "type": "boolean"
-          },
-          "end_time": {
-            "description": "时间窗口结束时间（Unix 毫秒），必须大于 `start_time`。",
-            "format": "int64",
-            "maximum": 9999999999999,
-            "minimum": 1000000000000,
-            "type": "integer"
-          },
-          "event_types": {
-            "description": "按事件类型过滤，取值为动态类型代码（如 `i_new` 故障创建、`a_new` 告警触发）。",
-            "items": {
-              "type": "string"
-            },
-            "type": "array"
-          },
-          "integration_id": {
-            "description": "按 Webhook 集成 ID 过滤。",
-            "format": "int64",
-            "minimum": 0,
-            "type": "integer"
+          "search_after_ctx": {
+            "type": "string",
+            "description": "上一次调用返回的不透明游标，用于获取下一页。"
           },
           "limit": {
-            "description": "每页数量。",
-            "maximum": 100,
+            "type": "integer",
             "minimum": 1,
-            "type": "integer"
+            "maximum": 100,
+            "description": "每页记录数，1–100。"
+          },
+          "asc": {
+            "type": "boolean",
+            "description": "为 true 时按 `event_time` 升序排序，否则降序。"
           },
           "orderby": {
-            "description": "排序字段，目前仅支持 `event_time`。",
+            "type": "string",
             "enum": [
               "event_time"
             ],
-            "type": "string"
+            "description": "排序字段，目前仅支持 `event_time`。"
           },
           "ref_id": {
-            "description": "按引用 ID 过滤（故障或告警 ID）。",
+            "type": "string",
             "maxLength": 128,
-            "type": "string"
-          },
-          "search_after_ctx": {
-            "description": "上一次调用返回的不透明游标，用于获取下一页。",
-            "type": "string"
+            "description": "按引用 ID 过滤（故障或告警 ID）。"
           },
-          "start_time": {
-            "description": "时间窗口起始时间（Unix 毫秒）。",
+          "integration_id": {
+            "type": "integer",
             "format": "int64",
-            "maximum": 9999999999999,
-            "minimum": 1000000000000,
-            "type": "integer"
+            "minimum": 0,
+            "description": "按 Webhook 集成 ID 过滤；为 `0` 或不传时返回全部集成。"
+          },
+          "event_types": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "按事件类型过滤，取值为动态类型代码（如 `i_new` 故障创建、`a_new` 告警触发）。"
           },
           "status": {
-            "description": "按投递状态过滤：`success` 成功，`failed` 失败。",
+            "type": "string",
             "enum": [
               "success",
               "failed"
             ],
-            "type": "string"
+            "description": "按投递状态过滤：`success` 成功，`failed` 失败。"
+          },
+          "start_time": {
+            "type": "integer",
+            "format": "int64",
+            "minimum": 1000000000000,
+            "maximum": 9999999999999,
+            "description": "时间窗口起始时间（Unix 毫秒）。"
+          },
+          "end_time": {
+            "type": "integer",
+            "format": "int64",
+            "minimum": 1000000000000,
+            "maximum": 9999999999999,
+            "description": "时间窗口结束时间（Unix 毫秒），必须大于 `start_time`。"
           }
-        },
-        "required": [
-          "limit",
-          "start_time",
-          "end_time"
-        ],
-        "type": "object"
+        }
       },
       "ListWebhookHistoryResponse": {
+        "type": "object",
         "description": "分页的 Webhook 推送历史。",
+        "required": [
+          "items",
+          "total",
+          "search_after_ctx"
+        ],
         "properties": {
           "items": {
-            "description": "当前页的 Webhook 推送记录。",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/WebhookHistoryItem"
             },
-            "type": "array"
-          },
-          "search_after_ctx": {
-            "description": "下一页游标，传入下次请求的 `search_after_ctx`。无更多数据时为空。",
-            "type": "string"
+            "description": "当前页的 Webhook 推送记录。"
           },
           "total": {
-            "description": "匹配记录总数。",
-            "format": "int64",
-            "type": "integer"
+            "type": "integer",
+            "description": "满足过滤条件的记录总数，不设上限。",
+            "format": "int64"
+          },
+          "search_after_ctx": {
+            "type": "string",
+            "description": "下一页游标，传入下次请求的 `search_after_ctx`。无更多数据时为空。"
           }
-        },
-        "required": [
-          "items",
-          "total",
-          "search_after_ctx"
-        ],
-        "type": "object"
+        }
       },
       "ListWorkItemRequest": {
+        "type": "object",
         "description": "查询跟进事项的过滤条件。`incident_id`、`post_mortem_id`、`assignee_id`，或 `assignee_type` 为 `ai_sre`，至少满足一个。",
         "properties": {
+          "incident_id": {
+            "type": "string",
+            "pattern": "^[0-9a-fA-F]{24}$",
+            "description": "故障 ID（MongoDB ObjectID）。同时返回锚定在该故障复盘上的后续行动。"
+          },
+          "post_mortem_id": {
+            "type": "string",
+            "description": "故障复盘 ID（32 位十六进制字符串）。返回绑定到该复盘的后续行动。"
+          },
+          "item_type": {
+            "type": "string",
+            "enum": [
+              "action",
+              "follow_up"
+            ],
+            "description": "按事项类型过滤：`action` 行动项，`follow_up` 复盘跟进项。"
+          },
           "assignee_id": {
-            "description": "按负责人成员 ID 过滤结果。仅按负责人查询时，须为本人或账户管理员。`assignee_type` 为 `ai_sre` 时忽略本字段。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "只返回指派给该成员 ID 的事项。仅按负责人查询时，调用方须为该成员本人，或账户所有者、管理员。`assignee_type` 为 `ai_sre` 时忽略。"
           },
           "assignee_type": {
             "description": "按负责人类型过滤：`person` 或 `ai_sre`。`ai_sre` 返回指派给 AI SRE 的事项（AI 用它查询自己的任务），不需要 `assignee_id`。`person` 与 `assignee_id` 一起使用时，只返回该成员负责的事项。省略本字段且 `assignee_id` 为正数时，按 `person` 过滤。",
@@ -14575,150 +14970,136 @@
             "type": "string"
           },
           "cursor": {
-            "description": "分页游标，取自上一次响应的 `next_cursor`。",
-            "type": "string"
-          },
-          "incident_id": {
-            "description": "故障 ID（MongoDB ObjectID）。同时返回锚定在该故障复盘上的后续行动。",
-            "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
-          },
-          "item_type": {
-            "description": "按事项类型过滤：`action` 行动项，`follow_up` 复盘跟进项。",
-            "enum": [
-              "action",
-              "follow_up"
-            ],
-            "type": "string"
+            "type": "string",
+            "description": "上一次响应中的 `next_cursor`，内容不透明。游标无效时返回 `InvalidParameter`。"
           },
           "limit": {
-            "default": 50,
-            "description": "每页条数，最多 200，默认 50。",
+            "type": "integer",
             "format": "int64",
-            "maximum": 200,
-            "minimum": 0,
-            "type": "integer"
-          },
-          "post_mortem_id": {
-            "description": "故障复盘 ID（32 位十六进制字符串）。返回绑定到该复盘的后续行动。",
-            "type": "string"
+            "default": 50,
+            "description": "每页条数。0、负数或省略表示 50；大于 200 时按 200 处理。"
           }
-        },
-        "type": "object"
+        }
       },
       "MCPServerCreateRequest": {
+        "type": "object",
         "description": "新建 MCP 服务器的配置。",
         "properties": {
-          "allow_insecure_oauth_http": {
-            "description": "允许该服务器的 OAuth 令牌交换使用明文 HTTP，仅用于测试，默认 false。",
-            "type": "boolean"
+          "server_name": {
+            "type": "string",
+            "description": "MCP 服务器名称：必须以字母开头，只能包含字母、数字、`-` 或 `_`（`@` 为保留字符）；在其作用域（账户级或单个团队）内唯一。",
+            "minLength": 1,
+            "maxLength": 255
+          },
+          "description": {
+            "type": "string",
+            "description": "服务器描述。",
+            "minLength": 1,
+            "maxLength": 1024
           },
-          "allow_insecure_tls_skip_verify": {
-            "description": "连接该服务器时跳过 TLS 证书校验，仅用于测试，默认 false。",
-            "type": "boolean"
+          "transport": {
+            "type": "string",
+            "description": "传输协议：`stdio` 通过 `command`/`args`/`env` 启动本地进程，`sse` / `streamable-http` 通过 `url`/`headers` 连接远程服务。",
+            "enum": [
+              "stdio",
+              "sse",
+              "streamable-http"
+            ]
+          },
+          "command": {
+            "type": "string",
+            "description": "可执行命令（stdio 传输）。"
           },
           "args": {
-            "description": "命令参数（stdio 传输）。",
+            "type": "array",
             "items": {
               "type": "string"
             },
-            "type": "array"
-          },
-          "auth_mode": {
-            "description": "认证模式：shared（默认）、per_user_secret 或 per_user_oauth。",
-            "type": "string"
-          },
-          "call_timeout": {
-            "description": "工具调用超时，单位秒。0 表示默认（60 秒）。",
-            "type": "integer"
-          },
-          "command": {
-            "description": "可执行命令（stdio 传输）。",
-            "type": "string"
-          },
-          "connect_timeout": {
-            "description": "连接超时，单位秒。0 表示默认（10 秒）。",
-            "type": "integer"
-          },
-          "description": {
-            "description": "服务器描述。",
-            "maxLength": 1024,
-            "minLength": 1,
-            "type": "string"
+            "description": "命令参数（stdio 传输）。"
           },
           "env": {
+            "type": "object",
             "additionalProperties": {
               "type": "string"
             },
-            "description": "环境变量（stdio 传输）。",
-            "type": "object"
+            "description": "环境变量（`stdio` 传输）。键名疑似凭据（包含 `KEY`、`SECRET`、`TOKEN`、`PASSWORD` 等）的值加密存储，响应中脱敏。"
           },
-          "environments": {
-            "description": "该服务器可运行的执行环境：`cloud` 和/或 BYOC Runner 的环境 ID 列表。省略或为空表示所有环境。",
-            "items": {
-              "type": "string"
-            },
-            "type": "array"
+          "url": {
+            "type": "string",
+            "description": "服务器 URL（sse / streamable-http 传输）。"
           },
           "headers": {
+            "type": "object",
             "additionalProperties": {
               "type": "string"
             },
-            "description": "HTTP 头（sse / streamable-http）。",
-            "type": "object"
+            "description": "HTTP 请求头（`sse` / `streamable-http` 传输）。键名疑似凭据（包含 `KEY`、`TOKEN`、`AUTHORIZATION` 等）的值加密存储，响应中脱敏。"
           },
-          "oauth_metadata": {
-            "description": "JSON OAuth 元数据；为 per_user_oauth 预留。",
-            "type": "string"
+          "connect_timeout": {
+            "type": "integer",
+            "description": "连接超时（秒）。省略或为 `0` 时存为 `0`，使用默认 10 秒。"
           },
-          "secret_schema": {
-            "description": "JSON 密钥 schema；auth_mode=per_user_secret 时必填。",
-            "type": "string"
+          "call_timeout": {
+            "type": "integer",
+            "description": "工具调用超时（秒）。省略或为 `0` 时存为 `0`，使用默认 60 秒。"
           },
-          "server_name": {
-            "description": "MCP 服务器名称：必须以字母开头，仅含字母、数字、`-`、`_`（`@` 为保留字符）；在其作用域（账户范围或单个团队）内唯一，大小写不敏感。",
-            "maxLength": 255,
-            "minLength": 1,
-            "type": "string"
+          "auth_mode": {
+            "type": "string",
+            "description": "凭据由谁提供：\n- `shared`（默认，空值等同）：使用保存在服务器上的一份凭据（`env` / `headers`），所有调用者共用。\n- `per_user_secret`：每位用户各自保存密钥，放在 `secret_schema.header_name` 指定的请求头中发送。\n- `per_user_oauth`：每位用户各自完成 OAuth 授权，首次使用时完成发现与客户端注册。\n\n`per_user_secret` 要求 `secret_schema` 带非空的 `header_name`；其他取值返回 `InvalidParameter`。",
+            "enum": [
+              "shared",
+              "per_user_secret",
+              "per_user_oauth"
+            ],
+            "default": "shared"
           },
-          "source_template_name": {
-            "description": "从连接器模板创建时的市场模板名称。",
-            "type": "string"
+          "secret_schema": {
+            "type": "string",
+            "description": "JSON 密钥 schema；auth_mode=per_user_secret 时必填。"
+          },
+          "oauth_metadata": {
+            "type": "string",
+            "description": "JSON OAuth 元数据；为 per_user_oauth 预留。"
           },
           "status": {
-            "default": "enabled",
+            "type": "string",
             "description": "初始状态：`enabled`（默认）创建即启用，`disabled` 创建后保持停用。",
             "enum": [
               "enabled",
               "disabled"
             ],
-            "type": "string"
+            "default": "enabled"
           },
           "team_id": {
-            "description": "团队范围：0 表示账户级；>0 表示团队。",
-            "format": "int64",
-            "type": "integer"
+            "type": "integer",
+            "description": "团队范围：`0` = 账户级（仅账户 owner 或管理员）；`>0` = 调用者所属的团队。传入 `source_template_name` 时忽略，市场安装一律为账户级。",
+            "format": "int64"
           },
-          "transport": {
-            "description": "传输协议：`stdio` 通过 `command`/`args`/`env` 启动本地进程，`sse` / `streamable-http` 通过 `url`/`headers` 连接远程服务。",
-            "enum": [
-              "stdio",
-              "sse",
-              "streamable-http"
-            ],
-            "type": "string"
+          "environments": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "该服务器可运行的执行环境：`cloud` 和/或 BYOC Runner 的环境 ID 列表。省略或为空表示所有环境。"
           },
-          "url": {
-            "description": "服务器 URL（sse / streamable-http 传输）。",
-            "type": "string"
+          "allow_insecure_oauth_http": {
+            "type": "boolean",
+            "description": "允许该服务器的 OAuth 令牌交换使用明文 HTTP，仅用于测试，默认 false。"
+          },
+          "allow_insecure_tls_skip_verify": {
+            "type": "boolean",
+            "description": "连接该服务器时跳过 TLS 证书校验，仅用于测试，默认 false。"
+          },
+          "source_template_name": {
+            "type": "string",
+            "description": "要安装的市场模板名称。传入时模板必须存在，服务器建在账户级，且连接字段必须与模板一致，只能填写模板声明的参数值。创建后不可修改。"
           }
         },
         "required": [
           "server_name",
           "description",
           "transport"
-        ],
-        "type": "object"
+        ]
       },
       "MCPServerDeleteRequest": {
         "description": "按 ID 删除 MCP 服务器。",
@@ -14747,146 +15128,156 @@
         "type": "object"
       },
       "MCPServerItem": {
+        "type": "object",
         "description": "账户下注册的 MCP 服务器（连接器）。",
         "properties": {
+          "server_id": {
+            "type": "string",
+            "description": "MCP 服务器唯一 ID（前缀 `mcp_`）。"
+          },
           "account_id": {
+            "type": "integer",
             "description": "所属账户 ID。",
-            "format": "int64",
-            "type": "integer"
-          },
-          "ai_description": {
-            "description": "LLM 生成的描述，存在时优先于 `description`；尚未生成时省略。",
-            "type": "string"
+            "format": "int64"
           },
-          "allow_insecure_oauth_http": {
-            "description": "允许该服务器的 OAuth token 交换走明文 HTTP；仅供测试使用。为 false 时省略。",
-            "type": "boolean"
+          "team_id": {
+            "type": "integer",
+            "description": "团队范围：0 表示账户级；>0 表示所属团队。",
+            "format": "int64"
           },
-          "allow_insecure_tls_skip_verify": {
-            "description": "连接该服务器时跳过 TLS 证书校验；仅供测试使用。为 false 时省略。",
-            "type": "boolean"
+          "can_edit": {
+            "type": "boolean",
+            "description": "调用者能否更新、启用、停用或删除该服务器：账户级服务器仅账户 owner 或管理员为 `true`，团队服务器仅该团队成员为 `true`。创建和更新接口的响应恒为 `true`。"
           },
-          "args": {
-            "description": "命令参数（stdio 传输）。",
+          "environments": {
+            "type": "array",
             "items": {
               "type": "string"
             },
-            "type": "array"
-          },
-          "auth_mode": {
-            "description": "认证模式。可选值：`shared`（共享凭据：配置资源时保存一份静态凭据，账户内所有调用方共用；缺省及空字符串等同于此值）、`per_user_secret`（按人密钥：每位使用者按 `secret_schema` 各自保存密钥，运行时按人注入）、`per_user_oauth`（按人 OAuth：每位使用者各自完成 OAuth 授权，首次调用时按需完成发现与注册）。",
-            "enum": [
-              "shared",
-              "per_user_secret",
-              "per_user_oauth"
-            ],
-            "type": "string"
-          },
-          "call_timeout": {
-            "description": "工具调用超时，单位秒（0 表示默认 60 秒）。",
-            "type": "integer"
+            "description": "该服务器可运行的执行环境（`cloud` 和/或 BYOC Runner 的环境 ID）。始终返回；`[]` 表示所有环境（该字段引入前的历史数据也是空数组）。"
           },
-          "can_edit": {
-            "description": "调用者是否可编辑该服务器。",
-            "type": "boolean"
+          "server_name": {
+            "type": "string",
+            "description": "MCP 服务器名称，在其作用域（账户级或单个团队）内唯一。"
           },
-          "command": {
-            "description": "可执行命令（仅 stdio 传输）。",
-            "type": "string"
+          "description": {
+            "type": "string",
+            "description": "服务器描述。"
           },
-          "connect_timeout": {
-            "description": "连接超时，单位秒（0 表示默认 10 秒）。",
-            "type": "integer"
+          "ai_description": {
+            "type": "string",
+            "description": "LLM 生成的描述，存在时优先于 `description`；尚未生成时省略。"
           },
-          "created_at": {
-            "description": "创建时间，Unix 毫秒时间戳。",
-            "format": "int64",
-            "type": "integer"
+          "transport": {
+            "type": "string",
+            "description": "传输协议。可选值：`stdio`（标准输入输出，本地子进程方式）、`sse`（独立 SSE，旧版 MCP 传输协议）、`streamable-http`（较新的 HTTP 流式传输协议）。",
+            "enum": [
+              "stdio",
+              "sse",
+              "streamable-http"
+            ]
           },
-          "created_by": {
-            "description": "创建该服务器的成员 ID。",
-            "format": "int64",
-            "type": "integer"
+          "command": {
+            "type": "string",
+            "description": "可执行命令（仅 stdio 传输）。"
           },
-          "description": {
-            "description": "服务器描述。",
-            "type": "string"
+          "args": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "命令参数（stdio 传输）。"
           },
           "env": {
+            "type": "object",
             "additionalProperties": {
               "type": "string"
             },
-            "description": "环境变量（stdio 传输）；密钥值已脱敏。",
-            "type": "object"
+            "description": "环境变量（`stdio` 传输）。键名疑似凭据或已加密存储的值会脱敏：超过 8 个字符时只显示首尾各 4 个字符、中间为 `****`，否则显示 `****`。为空时省略。"
           },
-          "environments": {
-            "description": "该服务器可运行的执行环境（`cloud` 和/或 BYOC Runner 的环境 ID）。始终返回；`[]` 表示所有环境（该字段引入前的历史数据也是空数组）。",
-            "items": {
-              "type": "string"
-            },
-            "type": "array"
+          "url": {
+            "type": "string",
+            "description": "服务器 URL（sse / streamable-http 传输）。"
           },
           "headers": {
+            "type": "object",
             "additionalProperties": {
               "type": "string"
             },
-            "description": "HTTP 头（sse / streamable-http）；密钥值已脱敏。",
-            "type": "object"
-          },
-          "oauth_metadata": {
-            "description": "JSON 编码的 OAuth 元数据（per_user_oauth 模式）。",
-            "type": "string"
+            "description": "HTTP 请求头（`sse` / `streamable-http` 传输），脱敏规则同 `env`。为空时省略。"
           },
           "proxy_url": {
-            "description": "访问服务器使用的出站代理 URL。",
-            "type": "string"
+            "type": "string",
+            "description": "访问服务器使用的出站代理 URL。公开 API 无法设置；为空时省略。"
           },
-          "secret_schema": {
-            "description": "JSON 编码的密钥 schema（per_user_secret 模式）。",
-            "type": "string"
+          "status": {
+            "type": "string",
+            "description": "服务器的工具是否提供给 AI SRE 会话使用：\n- `enabled`：可用（创建时默认）。\n- `disabled`：保留配置但不提供使用；可通过 `POST /safari/mcp/server/enable` 重新启用。",
+            "enum": [
+              "enabled",
+              "disabled"
+            ]
           },
-          "server_id": {
-            "description": "MCP 服务器唯一 ID（前缀 `mcp_`）。",
-            "type": "string"
+          "connect_timeout": {
+            "type": "integer",
+            "description": "存储的连接超时（秒）；`0` 表示使用默认 10 秒。"
           },
-          "server_name": {
-            "description": "MCP 服务器名称，在其作用域（账户范围或单个团队）内唯一，大小写不敏感。",
-            "type": "string"
+          "call_timeout": {
+            "type": "integer",
+            "description": "存储的工具调用超时（秒）；`0` 表示使用默认 60 秒。"
           },
-          "source_template_name": {
-            "description": "该连接器安装来源的市场模板名称；自建为空。",
-            "type": "string"
+          "allow_insecure_oauth_http": {
+            "type": "boolean",
+            "description": "允许该服务器的 OAuth token 交换走明文 HTTP；仅供测试使用。为 false 时省略。"
           },
-          "status": {
-            "description": "服务器状态。",
+          "allow_insecure_tls_skip_verify": {
+            "type": "boolean",
+            "description": "连接该服务器时跳过 TLS 证书校验；仅供测试使用。为 false 时省略。"
+          },
+          "auth_mode": {
+            "type": "string",
+            "description": "凭据由谁提供；为空时省略，效果同 `shared`：\n- `shared`：使用保存在服务器上的一份凭据（`env` / `headers`），所有调用者共用。\n- `per_user_secret`：每位用户各自保存密钥，放在 `secret_schema.header_name` 指定的请求头中发送。\n- `per_user_oauth`：每位用户各自完成 OAuth 授权，首次使用时完成发现与客户端注册。",
             "enum": [
-              "enabled",
-              "disabled"
-            ],
-            "type": "string"
+              "shared",
+              "per_user_secret",
+              "per_user_oauth"
+            ]
           },
-          "team_id": {
-            "description": "团队范围：0 表示账户级；>0 表示所属团队。",
+          "secret_schema": {
+            "type": "string",
+            "description": "JSON 编码的密钥 schema（per_user_secret 模式）。"
+          },
+          "oauth_metadata": {
+            "type": "string",
+            "description": "JSON 编码的 OAuth 元数据（per_user_oauth 模式）。"
+          },
+          "source_template_name": {
+            "type": "string",
+            "description": "该服务器安装来源的市场模板名称；手动创建的服务器不返回此字段。"
+          },
+          "test_error": {
+            "type": "string",
+            "description": "最近一次连接测试的错误信息；最近一次测试成功或从未测试时不返回。"
+          },
+          "tested_at": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "最近一次连接测试的时间，Unix 毫秒时间戳；从未测试时不返回。"
           },
-          "transport": {
-            "description": "传输协议。可选值：`stdio`（标准输入输出，本地子进程方式）、`sse`（独立 SSE，旧版 MCP 传输协议）、`streamable-http`（较新的 HTTP 流式传输协议）。",
-            "enum": [
-              "stdio",
-              "sse",
-              "streamable-http"
-            ],
-            "type": "string"
+          "created_by": {
+            "type": "integer",
+            "description": "创建该服务器的成员 ID。",
+            "format": "int64"
           },
-          "updated_at": {
-            "description": "最近更新时间，Unix 毫秒时间戳。",
+          "created_at": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "创建时间，Unix 毫秒时间戳。"
           },
-          "url": {
-            "description": "服务器 URL（sse / streamable-http 传输）。",
-            "type": "string"
+          "updated_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "最近更新时间，Unix 毫秒时间戳。"
           }
         },
         "required": [
@@ -14904,53 +15295,53 @@
           "created_at",
           "updated_at",
           "environments"
-        ],
-        "type": "object"
+        ]
       },
       "MCPServerListRequest": {
+        "type": "object",
         "description": "MCP 服务器列表的分页、范围与搜索过滤条件。",
         "properties": {
-          "include_account": {
-            "description": "是否包含账户级（team_id=0）记录，默认 true。",
-            "type": [
-              "boolean",
-              "null"
-            ]
-          },
-          "limit": {
-            "default": 20,
-            "description": "每页数量。",
-            "type": "integer"
-          },
           "p": {
-            "default": 1,
-            "description": "页码，从 1 开始。",
-            "type": "integer"
+            "type": "integer",
+            "description": "页码，从 1 开始；小于 1 时按 1 处理。",
+            "default": 1
           },
-          "query": {
-            "description": "对名称、描述、AI 生成描述、服务器 ID、传输协议、URL、命令、市场模板名称进行不区分大小写的子串搜索。",
-            "maxLength": 128,
-            "type": "string"
+          "limit": {
+            "type": "integer",
+            "description": "每页条数；小于 1 时按 20 处理。服务端不设上限。",
+            "default": 20
           },
           "scope": {
+            "type": "string",
             "description": "结果范围：account 仅返回账户级记录，team 仅返回调用者可见的团队级记录，省略则默认为 all（返回两者，仍受 team_ids/include_account 约束）。",
             "enum": [
               "all",
               "account",
               "team"
             ],
-            "type": "string"
+            "default": "all"
+          },
+          "query": {
+            "type": "string",
+            "maxLength": 128,
+            "description": "对名称、描述、AI 生成描述、服务器 ID、传输协议、URL、命令、市场模板名称进行不区分大小写的子串搜索。"
           },
           "team_ids": {
-            "description": "按团队 ID 过滤；为空则使用调用者可见范围。",
+            "type": "array",
             "items": {
-              "format": "int64",
-              "type": "integer"
+              "type": "integer",
+              "format": "int64"
             },
-            "type": "array"
+            "description": "只返回这些团队的记录。调用者不属于的团队 ID 会被忽略；为空表示调用者所属的全部团队。"
+          },
+          "include_account": {
+            "type": [
+              "boolean",
+              "null"
+            ],
+            "description": "是否包含账户级（`team_id=0`）记录。默认 `true`；`scope` 为 `account` 时始终包含、为 `team` 时始终不包含，此时忽略该字段。"
           }
-        },
-        "type": "object"
+        }
       },
       "MCPServerListResponse": {
         "description": "分页的 MCP 服务器列表。",
@@ -14988,119 +15379,124 @@
         "type": "object"
       },
       "MCPServerUpdateRequest": {
+        "type": "object",
         "description": "MCP 服务器的部分更新；省略字段表示不变。",
         "properties": {
-          "allow_insecure_oauth_http": {
-            "description": "是否允许 OAuth 令牌交换使用明文 HTTP。省略表示不变。",
-            "type": [
-              "boolean",
-              "null"
-            ]
+          "server_id": {
+            "type": "string",
+            "description": "目标 MCP 服务器 ID，取自 `POST /safari/mcp/server/list` 返回的列表。"
           },
-          "allow_insecure_tls_skip_verify": {
-            "description": "是否跳过 TLS 证书校验。省略表示不变。",
-            "type": [
-              "boolean",
-              "null"
+          "server_name": {
+            "type": "string",
+            "description": "新名称；省略或留空则不修改。",
+            "minLength": 1,
+            "maxLength": 255
+          },
+          "description": {
+            "type": "string",
+            "description": "新描述；省略或留空则不修改。",
+            "minLength": 1,
+            "maxLength": 1024
+          },
+          "transport": {
+            "type": "string",
+            "description": "传输协议；切换时应一并提供对应字段（`stdio` 用 `command`/`args`/`env`，`sse` / `streamable-http` 用 `url`/`headers`）；省略或留空则不修改。",
+            "enum": [
+              "stdio",
+              "sse",
+              "streamable-http"
             ]
           },
+          "command": {
+            "type": "string",
+            "description": "新的可执行命令（`stdio` 传输），省略或为空表示不变。"
+          },
           "args": {
-            "description": "命令参数（`stdio` 传输）；整体替换：传 `[]` 可清空，省略则不修改。",
+            "type": "array",
             "items": {
               "type": "string"
             },
-            "type": "array"
-          },
-          "auth_mode": {
-            "description": "认证模式：shared（默认）、per_user_secret 或 per_user_oauth。",
-            "type": "string"
-          },
-          "call_timeout": {
-            "description": "工具调用超时，单位秒。0 表示默认（60 秒）。",
-            "type": "integer"
-          },
-          "command": {
-            "description": "可执行命令（stdio 传输）。",
-            "type": "string"
-          },
-          "connect_timeout": {
-            "description": "连接超时，单位秒。0 表示默认（10 秒）。",
-            "type": "integer"
-          },
-          "description": {
-            "description": "新描述；省略或留空则不修改。",
-            "maxLength": 1024,
-            "minLength": 1,
-            "type": "string"
+            "description": "命令参数（`stdio` 传输）；整体替换：传 `[]` 可清空，省略则不修改。"
           },
           "env": {
+            "type": "object",
             "additionalProperties": {
               "type": "string"
             },
-            "description": "环境变量（`stdio` 传输）；整体替换，但敏感键回传掩码值或空字符串时保留服务端存储的原值；省略则不修改。",
-            "type": "object"
+            "description": "环境变量（`stdio` 传输）；整体替换，未传入的键会被删除。对受保护的键（规则见详情接口的脱敏说明），回传脱敏值或空字符串会保留已存储的值。省略表示不变。"
           },
-          "environments": {
-            "description": "该服务器可运行的执行环境：`cloud` 和/或 BYOC Runner 的环境 ID 列表。省略（null）表示保持不变；传入列表即整体设置——空列表表示清除限制、恢复为所有环境。",
-            "items": {
-              "type": "string"
-            },
-            "type": [
-              "array",
-              "null"
-            ]
+          "url": {
+            "type": "string",
+            "description": "新的服务器 URL（`sse` / `streamable-http` 传输），省略或为空表示不变。实际变更时，若未传新的 `oauth_metadata`，会将其清空。"
           },
           "headers": {
+            "type": "object",
             "additionalProperties": {
               "type": "string"
             },
-            "description": "HTTP 头（`sse` / `streamable-http` 传输）；整体替换，掩码/空值保留规则同 `env`；省略则不修改。",
-            "type": "object"
+            "description": "HTTP 头（`sse` / `streamable-http` 传输）；整体替换，掩码/空值保留规则同 `env`；省略则不修改。"
           },
-          "oauth_metadata": {
-            "description": "JSON OAuth 元数据；为 per_user_oauth 预留。",
-            "type": "string"
+          "connect_timeout": {
+            "type": "integer",
+            "description": "新的连接超时（秒），省略或为 `0` 表示不变（存储值为 `0` 时使用默认 10 秒）。"
           },
-          "secret_schema": {
-            "description": "JSON 密钥 schema；auth_mode=per_user_secret 时必填。",
-            "type": "string"
+          "call_timeout": {
+            "type": "integer",
+            "description": "新的工具调用超时（秒），省略或为 `0` 表示不变（存储值为 `0` 时使用默认 60 秒）。"
           },
-          "server_id": {
-            "description": "目标 MCP 服务器 ID，取自 `POST /safari/mcp/server/list` 返回的列表。",
-            "type": "string"
+          "auth_mode": {
+            "type": "string",
+            "description": "新的认证模式，省略或为空表示不变。凭据由谁提供：\n- `shared`（默认，空值等同）：使用保存在服务器上的一份凭据（`env` / `headers`），所有调用者共用。\n- `per_user_secret`：每位用户各自保存密钥，放在 `secret_schema.header_name` 指定的请求头中发送。\n- `per_user_oauth`：每位用户各自完成 OAuth 授权，首次使用时完成发现与客户端注册。\n\n`per_user_secret` 要求 `secret_schema` 带非空的 `header_name`；其他取值返回 `InvalidParameter`。",
+            "enum": [
+              "shared",
+              "per_user_secret",
+              "per_user_oauth"
+            ]
           },
-          "server_name": {
-            "description": "新名称；省略或留空则不修改。",
-            "maxLength": 255,
-            "minLength": 1,
-            "type": "string"
+          "secret_schema": {
+            "type": "string",
+            "description": "新的 JSON 密钥 schema，例如 `{\"header_name\":\"X-Api-Key\"}`。仅在同时传入非空 `auth_mode` 时生效，单独传入会被忽略。"
+          },
+          "oauth_metadata": {
+            "type": "string",
+            "description": "新的 JSON OAuth 元数据。非空值按原样保存。省略或为空时保留原值；若 `auth_mode` 或 `url` 发生变化，则清空。"
           },
           "team_id": {
-            "description": "重新分配团队范围：0 表示账户级；>0 表示团队。省略则不变。",
-            "format": "int64",
             "type": [
               "integer",
               "null"
-            ]
+            ],
+            "description": "重新分配团队范围：`0` = 账户级（仅账户 owner 或管理员）；`>0` = 调用者所属的团队。从市场安装的服务器只能改为 `0`。省略表示不变。",
+            "format": "int64"
           },
-          "transport": {
-            "description": "传输协议；切换时应一并提供对应字段（`stdio` 用 `command`/`args`/`env`，`sse` / `streamable-http` 用 `url`/`headers`）；省略或留空则不修改。",
-            "enum": [
-              "stdio",
-              "sse",
-              "streamable-http"
+          "environments": {
+            "type": [
+              "array",
+              "null"
             ],
-            "type": "string"
+            "items": {
+              "type": "string"
+            },
+            "description": "该服务器可运行的执行环境：`cloud` 和/或 BYOC Runner 的环境 ID 列表。省略（null）表示保持不变；传入列表即整体设置——空列表表示清除限制、恢复为所有环境。"
           },
-          "url": {
-            "description": "服务器 URL（sse / streamable-http 传输）。",
-            "type": "string"
+          "allow_insecure_oauth_http": {
+            "type": [
+              "boolean",
+              "null"
+            ],
+            "description": "是否允许 OAuth 令牌交换使用明文 HTTP。省略表示不变。"
+          },
+          "allow_insecure_tls_skip_verify": {
+            "type": [
+              "boolean",
+              "null"
+            ],
+            "description": "是否跳过 TLS 证书校验。省略表示不变。"
           }
         },
         "required": [
           "server_id"
-        ],
-        "type": "object"
+        ]
       },
       "ManualRunRuleResult": {
         "description": "手动运行一次自动化规则（跳过其计划触发时间）的结果。",
@@ -15131,73 +15527,75 @@
         "type": "object"
       },
       "MappingAPICreateRequest": {
+        "type": "object",
+        "required": [
+          "api_name",
+          "url"
+        ],
         "properties": {
           "api_name": {
-            "description": "唯一的 API 名称（最多 199 个字符）。",
+            "type": "string",
             "maxLength": 199,
-            "type": "string"
+            "description": "映射 API 名称，在未删除的映射 API 中唯一（最长 199 字符）。"
           },
           "description": {
-            "description": "可选描述，超过 500 字符会被静默截断。",
-            "type": "string"
+            "type": "string",
+            "description": "可选描述，超过 500 字符会被静默截断。"
+          },
+          "url": {
+            "type": "string",
+            "format": "uri",
+            "maxLength": 500,
+            "description": "以 `POST` 调用的地址。须为 `http` 或 `https` URL，最长 500 字符；SaaS 环境下主机名不得解析到内网 IP。"
+          },
+          "insecure_skip_verify": {
+            "type": "boolean",
+            "description": "是否跳过 TLS 证书验证，默认 `false`。"
           },
           "headers": {
+            "type": "object",
             "additionalProperties": {
               "type": "string"
             },
-            "description": "自定义 HTTP 请求头。SaaS 模式下安全敏感的请求头名（`authorization`、`cookie`、`x-forwarded-for` 等）会被拒绝；键须为 RFC 7230 token 字符（最长 1024），值最长 4096 字符。",
-            "type": "object"
+            "description": "自定义 HTTP 请求头。SaaS 模式下安全敏感的请求头名（`authorization`、`cookie`、`x-forwarded-for` 等）会被拒绝；键须为 RFC 7230 token 字符（最长 1024），值最长 4096 字符。"
           },
-          "insecure_skip_verify": {
-            "description": "是否跳过 TLS 证书验证，默认 `false`。",
-            "type": "boolean"
+          "timeout": {
+            "type": "integer",
+            "description": "整个请求的超时时间，单位秒（1–3）。不传或传 0 时为 2。",
+            "minimum": 1,
+            "maximum": 3,
+            "default": 2
           },
           "retry_count": {
-            "description": "失败重试次数（0–1），默认 0。",
-            "maximum": 1,
+            "type": "integer",
+            "description": "调用失败后的重试次数（0–1），默认 0。",
             "minimum": 0,
-            "type": "integer"
+            "maximum": 1,
+            "default": 0
           },
           "team_id": {
-            "description": "所属团队 ID，可通过 `POST /team/list` 获取。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
-          },
-          "timeout": {
-            "description": "请求超时秒数（1–3），默认 2。",
-            "maximum": 3,
-            "minimum": 1,
-            "type": "integer"
-          },
-          "url": {
-            "description": "HTTP/HTTPS 端点 URL（最多 500 个字符）。",
-            "format": "uri",
-            "maxLength": 500,
-            "type": "string"
+            "description": "所属团队 ID，可通过 `POST /team/list` 获取。不传或传 `0` 表示不属于任何团队；非 0 时须为已存在的团队。"
           }
-        },
-        "required": [
-          "api_name",
-          "url"
-        ],
-        "type": "object"
+        }
       },
       "MappingAPICreateResponse": {
+        "type": "object",
         "properties": {
           "api_id": {
-            "description": "创建的映射 API ID（MongoDB ObjectID 十六进制）。",
-            "type": "string"
+            "type": "string",
+            "description": "创建的映射 API ID（MongoDB ObjectID 十六进制）。"
           },
           "api_name": {
-            "description": "API 名称。",
-            "type": "string"
+            "type": "string",
+            "description": "新建映射 API 的名称，与请求一致。"
           }
         },
         "required": [
           "api_id",
           "api_name"
-        ],
-        "type": "object"
+        ]
       },
       "MappingAPIIDRequest": {
         "properties": {
@@ -15212,83 +15610,84 @@
         "type": "object"
       },
       "MappingAPIItem": {
+        "type": "object",
         "description": "映射 API 配置。",
         "properties": {
           "api_id": {
-            "description": "API ID（MongoDB ObjectID 十六进制）。",
-            "type": "string"
+            "type": "string",
+            "description": "API ID（MongoDB ObjectID 十六进制）。"
           },
           "api_name": {
-            "description": "API 名称。",
-            "type": "string"
-          },
-          "created_at": {
-            "description": "创建时间，Unix 时间戳（秒）。为 0（历史数据）时省略。",
-            "format": "int64",
-            "type": "integer"
-          },
-          "creator_id": {
-            "description": "创建者成员 ID。",
-            "format": "int64",
-            "type": "integer"
-          },
-          "deleted_at": {
-            "description": "删除时间，Unix 时间戳（秒）。未软删除时省略。",
-            "format": "int64",
-            "type": "integer"
+            "type": "string",
+            "description": "映射 API 名称，在未删除的映射 API 中唯一。"
           },
           "description": {
-            "description": "描述。",
-            "type": "string"
+            "type": "string",
+            "description": "描述文字（最多 500 字符），未填写时为空字符串。"
+          },
+          "url": {
+            "type": "string",
+            "description": "端点 URL。"
           },
           "headers": {
-            "additionalProperties": {
-              "type": "string"
-            },
-            "description": "自定义请求头，未配置时为 `null`。",
             "type": [
               "object",
               "null"
-            ]
+            ],
+            "additionalProperties": {
+              "type": "string"
+            },
+            "description": "每次调用都会携带的请求头，以明文返回。未配置时为 `null`。"
           },
-          "insecure_skip_verify": {
-            "description": "是否跳过 TLS 验证。",
-            "type": "boolean"
+          "timeout": {
+            "type": "integer",
+            "description": "整个请求的超时时间，单位秒（1–3）。"
           },
           "retry_count": {
-            "description": "重试次数。",
-            "type": "integer"
+            "type": "integer",
+            "description": "调用失败后的重试次数：`0` 或 `1`。"
+          },
+          "insecure_skip_verify": {
+            "type": "boolean",
+            "description": "是否跳过 TLS 验证。"
           },
           "status": {
-            "description": "API 状态：`enabled`（生效）或 `deleted`（已软删除）。list 接口不返回 `deleted`，info 接口可能返回。",
+            "type": "string",
             "enum": [
               "enabled",
               "deleted"
             ],
-            "type": "string"
+            "description": "API 状态：`enabled`（生效）或 `deleted`（已软删除）。list 接口不返回 `deleted`，info 接口可能返回。"
           },
           "team_id": {
-            "description": "所属团队 ID。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
-          },
-          "timeout": {
-            "description": "请求超时秒数。",
-            "type": "integer"
+            "description": "所属团队 ID。"
           },
-          "updated_at": {
-            "description": "最后更新时间，Unix 时间戳（秒）。为 0（历史数据）时省略。",
+          "creator_id": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "创建者成员 ID。"
           },
           "updated_by": {
-            "description": "最后更新者成员 ID。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "最后更新者成员 ID。"
           },
-          "url": {
-            "description": "端点 URL。",
-            "type": "string"
+          "created_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "创建时间，Unix 时间戳（秒）。为 0（历史数据）时省略。"
+          },
+          "updated_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "最后更新时间，Unix 时间戳（秒）。为 0（历史数据）时省略。"
+          },
+          "deleted_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "删除时间，Unix 时间戳（秒）。未软删除时省略。"
           }
         },
         "required": [
@@ -15304,340 +15703,348 @@
           "team_id",
           "updated_by",
           "creator_id"
-        ],
-        "type": "object"
+        ]
       },
       "MappingAPIListResponse": {
+        "type": "object",
         "properties": {
+          "total": {
+            "type": "integer",
+            "description": "返回的条目数；该列表不分页。"
+          },
           "items": {
-            "description": "映射 API 列表。",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/MappingAPIItem"
             },
-            "type": "array"
-          },
-          "total": {
-            "description": "映射 API 总数。",
-            "type": "integer"
+            "description": "映射 API 列表。"
           }
         },
         "required": [
           "total",
           "items"
-        ],
-        "type": "object"
+        ]
       },
       "MappingAPIUpdateRequest": {
+        "type": "object",
+        "required": [
+          "api_id"
+        ],
         "properties": {
           "api_id": {
-            "description": "映射 API ID（MongoDB ObjectID 十六进制）。",
-            "type": "string"
+            "type": "string",
+            "description": "映射 API ID（MongoDB ObjectID 十六进制）。"
           },
           "api_name": {
-            "description": "新 API 名称（最多 199 个字符）。",
-            "maxLength": 199,
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "maxLength": 199,
+            "description": "新名称，在未删除的映射 API 中唯一（最长 199 字符）。不传则保持不变。"
           },
           "description": {
-            "description": "新描述。",
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "新描述，超过 500 字符会被截断。不传则保持不变，传 `\"\"` 清空。"
           },
-          "headers": {
-            "additionalProperties": {
-              "type": "string"
-            },
-            "description": "自定义 HTTP 请求头。SaaS 模式下安全敏感的请求头名（`authorization`、`cookie`、`x-forwarded-for` 等）会被拒绝；键须为 RFC 7230 token 字符（最长 1024），值最长 4096 字符。",
-            "type": "object"
+          "url": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "format": "uri",
+            "maxLength": 500,
+            "description": "新的 `http`/`https` 地址（最长 500 字符）；SaaS 环境下主机名不得解析到内网 IP。不传则保持不变。"
           },
           "insecure_skip_verify": {
-            "description": "新 TLS 跳过验证设置。",
             "type": [
               "boolean",
               "null"
-            ]
+            ],
+            "description": "新的跳过 TLS 证书校验设置。不传则保持不变。"
           },
-          "retry_count": {
-            "description": "新重试次数。",
-            "maximum": 1,
-            "minimum": 0,
-            "type": [
-              "integer",
-              "null"
-            ]
+          "headers": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "string"
+            },
+            "description": "传入时整体替换请求头，传 `{}` 清空全部请求头；不传则保持不变。SaaS 环境下会拒绝敏感请求头（见 `/enrichment/mapping/api/create`）；键最长 1,024 字符，值最长 4,096 字符。"
           },
-          "team_id": {
-            "description": "新所属团队 ID，可通过 `POST /team/list` 获取。",
-            "format": "int64",
+          "timeout": {
             "type": [
               "integer",
               "null"
-            ]
-          },
-          "timeout": {
-            "description": "新超时秒数。",
-            "maximum": 3,
+            ],
+            "description": "新的整个请求超时时间，单位秒（1–3）。不传则保持不变。",
             "minimum": 1,
+            "maximum": 3
+          },
+          "retry_count": {
             "type": [
               "integer",
               "null"
-            ]
+            ],
+            "description": "新的重试次数（0–1）。不传则保持不变。",
+            "minimum": 0,
+            "maximum": 1
           },
-          "url": {
-            "description": "新端点 URL（最多 500 个字符）。",
-            "format": "uri",
-            "maxLength": 500,
+          "team_id": {
             "type": [
-              "string",
+              "integer",
               "null"
-            ]
+            ],
+            "format": "int64",
+            "description": "新的所属团队 ID，可通过 `POST /team/list` 获取；传 `0` 解除团队关联。不传则保持不变。"
           }
-        },
-        "required": [
-          "api_id"
-        ],
-        "type": "object"
+        }
       },
       "MappingDataDeleteRequest": {
+        "type": "object",
+        "required": [
+          "schema_id",
+          "keys"
+        ],
         "properties": {
+          "schema_id": {
+            "type": "string",
+            "description": "映射规则 ID（MongoDB ObjectID 十六进制）。"
+          },
           "keys": {
-            "description": "待删除的数据行键名列表。",
+            "type": "array",
             "items": {
               "type": "string"
             },
             "maxItems": 100,
-            "type": "array"
-          },
-          "schema_id": {
-            "description": "映射规则 ID（MongoDB ObjectID 十六进制）。",
-            "type": "string"
+            "description": "要删除的行 key（最多 100 个），取自 `/enrichment/mapping/data/list` 返回的 `key` 或 `/enrichment/mapping/data/upsert` 返回的 `keys`。匹配不到行的 key 会被忽略。"
           }
-        },
-        "required": [
-          "schema_id",
-          "keys"
-        ],
-        "type": "object"
+        }
       },
       "MappingDataItem": {
+        "type": "object",
         "description": "单条映射数据行。",
         "properties": {
-          "created_at": {
-            "description": "创建时间，Unix 时间戳（秒），为 0 时省略。",
-            "format": "int64",
-            "type": "integer"
+          "key": {
+            "type": "string",
+            "description": "数据行的组合键——来源标签值（按标签名排序、以 `:` 连接）的 MD5。为空时省略。"
           },
           "fields": {
+            "type": "object",
             "additionalProperties": {
               "type": "string"
             },
-            "description": "该行的全部标签键值对，为空时省略。",
-            "type": "object"
+            "description": "该行的全部标签键值对，为空时省略。"
           },
-          "key": {
-            "description": "数据行的组合键——来源标签值（按标签名排序、以 `:` 连接）的 MD5。为空时省略。",
-            "type": "string"
+          "created_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "该行最近一次写入的时间，Unix 秒；被替换的行会得到新值。为 0 时省略。"
           },
           "updated_at": {
-            "description": "最后更新时间，Unix 时间戳（秒），为 0 时省略。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "最后更新时间，Unix 时间戳（秒），为 0 时省略。"
           }
-        },
-        "type": "object"
+        }
       },
       "MappingDataListRequest": {
+        "type": "object",
+        "required": [
+          "schema_id"
+        ],
         "properties": {
-          "asc": {
-            "description": "为 `true` 时升序排列。",
-            "type": "boolean"
+          "schema_id": {
+            "type": "string",
+            "description": "映射规则 ID（MongoDB ObjectID 十六进制）。"
           },
-          "limit": {
-            "description": "每页数量（0–100）；省略、`null` 或 0 时默认为 20。",
-            "format": "int64",
-            "maximum": 100,
-            "minimum": 0,
-            "type": [
-              "integer",
-              "null"
-            ]
+          "query": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "string"
+            },
+            "description": "按来源标签值精确过滤。不属于来源标签的键会被静默忽略；一旦指定，必须包含全部来源标签。"
           },
           "orderby": {
-            "description": "排序字段，默认 `updated_at`。",
+            "type": "string",
             "enum": [
               "created_at",
               "updated_at"
             ],
-            "type": "string"
+            "description": "排序字段，默认 `updated_at`。"
+          },
+          "asc": {
+            "type": "boolean",
+            "description": "为 `true` 时正序；默认 `false`（最新的在前）。",
+            "default": false
           },
           "p": {
-            "description": "页码（从 1 开始），用于页码分页；省略、`null` 或 0 时默认为 1。设置 `search_after_ctx` 时忽略该参数。页码分页最多可取 10,000 行（`p * limit <= 10000`）。",
-            "format": "int64",
-            "minimum": 0,
             "type": [
               "integer",
               "null"
-            ]
-          },
-          "query": {
-            "additionalProperties": {
-              "type": "string"
-            },
-            "description": "按来源标签值精确过滤。不属于来源标签的键会被静默忽略；一旦指定，必须包含全部来源标签。",
-            "type": "object"
+            ],
+            "format": "int64",
+            "description": "页码（从 1 开始），用于页码分页；省略、`null` 或 0 时默认为 1。设置 `search_after_ctx` 时忽略该参数。页码分页最多可取 10,000 行（`p * limit <= 10000`）。",
+            "minimum": 0
           },
-          "schema_id": {
-            "description": "映射规则 ID（MongoDB ObjectID 十六进制）。",
-            "type": "string"
+          "limit": {
+            "type": [
+              "integer",
+              "null"
+            ],
+            "format": "int64",
+            "description": "每页数量（0–100）；省略、`null` 或 0 时默认为 20。",
+            "minimum": 0,
+            "maximum": 100
           },
           "search_after_ctx": {
-            "description": "游标分页使用的不透明游标——传入上一次响应中的 `search_after_ctx`。须为 MongoDB ObjectID 十六进制字符串；设置后忽略 `p`。",
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "游标分页使用的不透明游标——传入上一次响应中的 `search_after_ctx`。须为 MongoDB ObjectID 十六进制字符串；设置后忽略 `p`。"
           }
-        },
-        "required": [
-          "schema_id"
-        ],
-        "type": "object"
+        }
       },
       "MappingDataListResponse": {
+        "type": "object",
         "properties": {
-          "has_next_page": {
-            "description": "是否存在更多页。",
-            "type": "boolean"
-          },
           "items": {
-            "description": "数据行列表。",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/MappingDataItem"
             },
-            "type": "array"
-          },
-          "search_after_ctx": {
-            "description": "下一页游标（本页最后一行的 ObjectID 十六进制）。没有下一页时省略。",
-            "type": "string"
+            "description": "本页的数据行，按 `orderby`/`asc` 排序；无匹配时为空数组。"
           },
           "total": {
-            "description": "匹配的总行数。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "匹配 `query` 的行数，最多统计到 1,000；值为 1,000 表示至少 1,000 行。"
+          },
+          "has_next_page": {
+            "type": "boolean",
+            "description": "为 `true` 表示本页之后还有数据。"
+          },
+          "used_cnt": {
+            "type": "integer",
+            "format": "int64",
+            "description": "该映射规则中存储的总行数，不受 `query` 影响，可用于对照行数上限（默认 10,000 行）。"
+          },
+          "search_after_ctx": {
+            "type": "string",
+            "description": "下一页游标（本页最后一行的 ObjectID 十六进制）。没有下一页时省略。"
           }
         },
         "required": [
           "items",
           "total",
-          "has_next_page"
-        ],
-        "type": "object"
+          "has_next_page",
+          "used_cnt"
+        ]
       },
       "MappingDataUpsertRequest": {
+        "type": "object",
+        "required": [
+          "schema_id",
+          "docs"
+        ],
         "properties": {
+          "schema_id": {
+            "type": "string",
+            "description": "映射规则 ID（MongoDB ObjectID 十六进制）。"
+          },
           "docs": {
-            "description": "待插入或更新的数据行。每行须包含所有来源标签和结果标签；未知标签会被静默丢弃；单个值超过 2048 字符将被拒绝。",
+            "type": "array",
             "items": {
+              "type": "object",
               "additionalProperties": {
                 "type": "string"
-              },
-              "type": "object"
+              }
             },
             "maxItems": 1000,
-            "type": "array"
-          },
-          "schema_id": {
-            "description": "映射规则 ID（MongoDB ObjectID 十六进制）。",
-            "type": "string"
+            "description": "要写入或替换的数据行（最多 1,000 行）。每行是标签名到值的映射，须包含全部来源标签和结果标签；其他键会被丢弃；值超过 2,048 字节会被拒绝。来源标签值与已有行相同的行会替换该行。"
           }
-        },
-        "required": [
-          "schema_id",
-          "docs"
-        ],
-        "type": "object"
+        }
       },
       "MappingDataUpsertResponse": {
+        "type": "object",
         "properties": {
           "keys": {
-            "description": "已 Upsert 数据行的组合键列表。",
+            "type": "array",
             "items": {
               "type": "string"
             },
-            "type": "array"
+            "description": "已写入行的 key（每个不同的行一个，顺序不固定），可用于 `/enrichment/mapping/data/delete`。"
           }
         },
         "required": [
           "keys"
-        ],
-        "type": "object"
+        ]
       },
       "MappingSchemaCreateRequest": {
+        "type": "object",
+        "required": [
+          "schema_name",
+          "source_labels",
+          "result_labels"
+        ],
         "properties": {
+          "schema_name": {
+            "type": "string",
+            "maxLength": 39,
+            "description": "映射规则名称，在账户未删除的映射规则中唯一（最长 39 字符）。"
+          },
           "description": {
-            "description": "可选描述（最多 500 个字符）。",
+            "type": "string",
             "maxLength": 500,
-            "type": "string"
-          },
-          "result_labels": {
-            "description": "匹配后写入的输出标签名（1–10 个）。每个须匹配 `^[a-zA-Z_][a-zA-Z0-9_]*$`；列表内不得重复，且不得与 `source_labels` 重叠。",
-            "items": {
-              "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$",
-              "type": "string"
-            },
-            "maxItems": 10,
-            "type": "array",
-            "uniqueItems": true
+            "description": "可选描述（最多 500 个字符）。"
           },
-          "schema_name": {
-            "description": "唯一的映射规则名称（最多 39 个字符）。",
-            "maxLength": 39,
-            "type": "string"
+          "team_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "所属团队 ID，可通过 `POST /team/list` 获取。不传或传 `0` 表示不属于任何团队；非 0 时须为已存在的团队。"
           },
           "source_labels": {
-            "description": "查找键标签名（1–3 个）。每个须匹配 `^[a-zA-Z_][a-zA-Z0-9_]*$`；列表内不得重复，且不得与 `result_labels` 重叠。",
+            "type": "array",
             "items": {
-              "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$",
-              "type": "string"
+              "type": "string",
+              "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$"
             },
             "maxItems": 3,
-            "type": "array",
-            "uniqueItems": true
+            "description": "查找键标签名（1–3 个）。每个须匹配 `^[a-zA-Z_][a-zA-Z0-9_]*$`；列表内不得重复，且不得与 `result_labels` 重叠。",
+            "uniqueItems": true,
+            "minItems": 1
           },
-          "team_id": {
-            "description": "所属团队 ID，`0` 表示无团队。",
-            "format": "int64",
-            "type": "integer"
+          "result_labels": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$"
+            },
+            "maxItems": 10,
+            "description": "匹配后写入的输出标签名（1–10 个）。每个须匹配 `^[a-zA-Z_][a-zA-Z0-9_]*$`；列表内不得重复，且不得与 `source_labels` 重叠。",
+            "uniqueItems": true,
+            "minItems": 1
           }
-        },
-        "required": [
-          "schema_name",
-          "source_labels",
-          "result_labels"
-        ],
-        "type": "object"
+        }
       },
       "MappingSchemaCreateResponse": {
+        "type": "object",
         "properties": {
           "schema_id": {
-            "description": "创建的映射规则 ID（MongoDB ObjectID 十六进制）。",
-            "type": "string"
+            "type": "string",
+            "description": "创建的映射规则 ID（MongoDB ObjectID 十六进制）。"
           },
           "schema_name": {
-            "description": "映射规则名称。",
-            "type": "string"
+            "type": "string",
+            "description": "新建映射规则的名称，与请求一致。"
           }
         },
         "required": [
           "schema_id",
           "schema_name"
-        ],
-        "type": "object"
+        ]
       },
       "MappingSchemaIDRequest": {
         "properties": {
@@ -15652,71 +16059,72 @@
         "type": "object"
       },
       "MappingSchemaItem": {
+        "type": "object",
         "description": "映射规则定义。",
         "properties": {
-          "created_at": {
-            "description": "创建时间，Unix 时间戳（秒）。为 0（历史数据）时省略。",
-            "format": "int64",
-            "type": "integer"
-          },
-          "creator_id": {
-            "description": "创建者成员 ID。",
-            "format": "int64",
-            "type": "integer"
+          "schema_id": {
+            "type": "string",
+            "description": "映射规则 ID（MongoDB ObjectID 十六进制）。"
           },
-          "deleted_at": {
-            "description": "删除时间，Unix 时间戳（秒）。未软删除时省略。",
-            "format": "int64",
-            "type": "integer"
+          "schema_name": {
+            "type": "string",
+            "description": "映射规则名称，在账户未删除的映射规则中唯一。"
           },
           "description": {
-            "description": "描述。",
-            "type": "string"
+            "type": "string",
+            "description": "描述。"
           },
-          "result_labels": {
-            "description": "输出标签名。",
+          "source_labels": {
+            "type": "array",
             "items": {
               "type": "string"
             },
-            "type": "array"
-          },
-          "schema_id": {
-            "description": "映射规则 ID（MongoDB ObjectID 十六进制）。",
-            "type": "string"
-          },
-          "schema_name": {
-            "description": "映射规则名称。",
-            "type": "string"
+            "description": "其值组成数据行查找键的标签名（1–3 个），创建后不可修改。"
           },
-          "source_labels": {
-            "description": "查找键标签名。",
+          "result_labels": {
+            "type": "array",
             "items": {
               "type": "string"
             },
-            "type": "array"
+            "description": "匹配到行时写入事件的标签名（1–10 个），创建后不可修改。"
           },
           "status": {
-            "description": "映射规则状态：`enabled`（生效）或 `deleted`（已软删除）。list 接口不返回 `deleted`，info 接口可能返回。",
+            "type": "string",
             "enum": [
               "enabled",
               "deleted"
             ],
-            "type": "string"
+            "description": "映射规则状态：`enabled`（生效）或 `deleted`（已软删除）。list 接口不返回 `deleted`，info 接口可能返回。"
           },
           "team_id": {
-            "description": "所属团队 ID。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "所属团队 ID；不属于任何团队时为 `0`。"
           },
-          "updated_at": {
-            "description": "最后更新时间，Unix 时间戳（秒）。为 0（历史数据）时省略。",
+          "creator_id": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "创建者成员 ID。"
           },
           "updated_by": {
-            "description": "最后更新者成员 ID。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "最后更新者成员 ID。"
+          },
+          "created_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "创建时间，Unix 时间戳（秒）。为 0（历史数据）时省略。"
+          },
+          "updated_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "最后更新时间，Unix 时间戳（秒）。为 0（历史数据）时省略。"
+          },
+          "deleted_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "删除时间，Unix 时间戳（秒）。未软删除时省略。"
           }
         },
         "required": [
@@ -15729,127 +16137,126 @@
           "team_id",
           "updated_by",
           "creator_id"
-        ],
-        "type": "object"
+        ]
       },
       "MappingSchemaListResponse": {
+        "type": "object",
         "properties": {
+          "total": {
+            "type": "integer",
+            "description": "返回的条目数；该列表不分页。"
+          },
           "items": {
-            "description": "映射规则列表。",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/MappingSchemaItem"
             },
-            "type": "array"
-          },
-          "total": {
-            "description": "映射规则总数。",
-            "type": "integer"
+            "description": "映射规则列表。"
           }
         },
         "required": [
           "total",
           "items"
-        ],
-        "type": "object"
+        ]
       },
       "MappingSchemaUpdateRequest": {
+        "type": "object",
+        "required": [
+          "schema_id"
+        ],
         "properties": {
-          "description": {
-            "description": "新的描述（最多 500 个字符）。",
-            "maxLength": 500,
-            "type": [
-              "string",
-              "null"
-            ]
-          },
           "schema_id": {
-            "description": "映射规则 ID（MongoDB ObjectID 十六进制）。",
-            "type": "string"
+            "type": "string",
+            "description": "映射规则 ID（MongoDB ObjectID 十六进制）。"
           },
           "schema_name": {
-            "description": "新的映射规则名称（最多 39 个字符）。",
+            "type": [
+              "string",
+              "null"
+            ],
             "maxLength": 39,
+            "description": "新名称，在未删除的映射规则中唯一（最长 39 字符）。不传则保持不变。"
+          },
+          "description": {
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "maxLength": 500,
+            "description": "新描述（最长 500 字符）。不传则保持不变，传 `\"\"` 清空。"
           },
           "team_id": {
-            "description": "新的所属团队 ID，`0` 表示移除团队关联。",
-            "format": "int64",
             "type": [
               "integer",
               "null"
-            ]
+            ],
+            "format": "int64",
+            "description": "新的所属团队 ID，可通过 `POST /team/list` 获取；传 `0` 解除团队关联。不传则保持不变。"
           }
-        },
-        "required": [
-          "schema_id"
-        ],
-        "type": "object"
+        }
       },
       "MemberDeleteRequest": {
-        "anyOf": [
-          {
-            "required": [
-              "member_id"
-            ]
+        "type": "object",
+        "description": "删除成员请求（提供其中一个查找字段）",
+        "properties": {
+          "member_id": {
+            "type": "integer",
+            "format": "uint64",
+            "description": "成员 ID。同时提供多个查找字段时，按 `member_id` > `member_name` > `email` > `phone` > `ref_id` 的优先级取第一个非空值"
           },
-          {
-            "required": [
-              "member_name"
-            ]
+          "member_name": {
+            "type": "string",
+            "description": "成员名称。仅在未提供 `member_id` 时生效"
           },
-          {
-            "required": [
-              "email"
-            ]
+          "email": {
+            "type": "string",
+            "description": "邮箱地址。仅在 `member_id`、`member_name` 均未提供时生效"
           },
-          {
-            "required": [
-              "phone"
-            ]
+          "phone": {
+            "type": "string",
+            "description": "手机号。仅在 `member_id`、`member_name`、`email` 均未提供时生效"
           },
-          {
-            "required": [
-              "ref_id"
-            ]
-          }
-        ],
-        "description": "删除成员请求（提供其中一个查找字段）",
-        "properties": {
           "country_code": {
-            "description": "当 `phone` 不带 \"+\" 前缀时的解析地区提示 —— ISO 3166-1 alpha-2 地区代码（如 \"CN\"，未传时默认 \"CN\"）。此解析场景仍兼容 \"86\" 等数字电话区号。",
-            "type": "string"
+            "type": "string",
+            "description": "当 `phone` 不带 \"+\" 前缀时的解析地区提示 —— ISO 3166-1 alpha-2 地区代码（如 \"CN\"，未传时默认 \"CN\"）。此解析场景仍兼容 \"86\" 等数字电话区号。"
           },
-          "email": {
-            "description": "邮箱地址。仅在 `member_id`、`member_name` 均未提供时生效",
-            "type": "string"
+          "ref_id": {
+            "type": "string",
+            "description": "外部引用 ID。仅在其他查找字段均未提供时生效"
           },
           "is_force": {
-            "default": false,
-            "description": "是否强制删除。默认 false，会检查成员是否被分派策略、值班表等资源引用；设为 true 则跳过引用检查直接删除",
-            "type": "boolean"
+            "type": "boolean",
+            "description": "跳过引用检查。为 false（默认）时，若成员属于某个团队、被分派策略指定或在值班表中，调用返回 `ReferenceExist`。强制删除不会移除这些引用。",
+            "default": false
+          }
+        },
+        "anyOf": [
+          {
+            "required": [
+              "member_id"
+            ]
           },
-          "member_id": {
-            "description": "成员 ID。同时提供多个查找字段时，按 `member_id` > `member_name` > `email` > `phone` > `ref_id` 的优先级取第一个非空值",
-            "format": "uint64",
-            "type": "integer"
+          {
+            "required": [
+              "member_name"
+            ]
           },
-          "member_name": {
-            "description": "成员名称。仅在未提供 `member_id` 时生效",
-            "type": "string"
+          {
+            "required": [
+              "email"
+            ]
           },
-          "phone": {
-            "description": "手机号。仅在 `member_id`、`member_name`、`email` 均未提供时生效",
-            "type": "string"
+          {
+            "required": [
+              "phone"
+            ]
           },
-          "ref_id": {
-            "description": "外部引用 ID。仅在其他查找字段均未提供时生效",
-            "type": "string"
+          {
+            "required": [
+              "ref_id"
+            ]
           }
-        },
-        "type": "object"
+        ]
       },
       "MemberEmptyObject": {
         "description": "空响应",
@@ -15862,102 +16269,110 @@
         "type": "object"
       },
       "MemberInfoResponse": {
+        "type": "object",
         "description": "当前成员资料",
         "properties": {
-          "account_avatar": {
-            "description": "账户头像 URL",
-            "type": "string"
-          },
-          "account_email": {
-            "description": "账户邮箱",
-            "type": "string"
-          },
           "account_id": {
-            "description": "账户 ID",
+            "type": "integer",
             "format": "uint64",
-            "type": "integer"
-          },
-          "account_locale": {
-            "description": "账户级语言偏好（如 zh-CN、en-US）。账户未设置时不返回。",
-            "type": "string"
+            "description": "成员所属账户的 ID。"
           },
           "account_name": {
-            "description": "账户名称",
-            "type": "string"
+            "type": "string",
+            "description": "账户（组织）名称。"
+          },
+          "account_avatar": {
+            "type": "string",
+            "description": "账户头像 URL"
+          },
+          "account_email": {
+            "type": "string",
+            "description": "账户主体的联系邮箱。"
           },
           "account_role_ids": {
-            "description": "授予的角色 ID 列表",
+            "type": "array",
             "items": {
-              "format": "uint64",
-              "type": "integer"
+              "type": "integer",
+              "format": "uint64"
             },
-            "type": "array"
+            "description": "成员被分配的角色 ID，可通过 `POST /role/list` 解析。"
+          },
+          "account_locale": {
+            "type": "string",
+            "description": "账户级语言偏好（如 zh-CN、en-US）。账户未设置时不返回。"
           },
           "account_time_zone": {
-            "description": "账户级时区（如 Asia/Shanghai）。账户未设置时不返回。",
-            "type": "string"
+            "type": "string",
+            "description": "账户设置的 IANA 时区；账户未设置时为空字符串。始终返回。"
           },
-          "avatar": {
-            "description": "成员头像 URL",
-            "type": "string"
+          "resolved_time_zone": {
+            "type": "string",
+            "description": "实际生效的时区：成员的 `time_zone` 有效时取它，否则取账户时区，再否则为 `Asia/Shanghai`。始终返回。"
           },
-          "country_code": {
-            "description": "成员联系手机的 ISO 3166-1 alpha-2 地区代码（如 \"CN\"、\"US\"、\"HK\"）。",
-            "type": "string"
+          "domain": {
+            "type": "string",
+            "description": "账户域名，即登录控制台所用的子域名。"
           },
-          "created_at": {
-            "description": "成员创建时间，Unix 秒级时间戳。",
-            "format": "int64",
-            "type": "integer"
+          "member_id": {
+            "type": "integer",
+            "format": "uint64",
+            "description": "调用成员的 ID。"
           },
-          "domain": {
-            "description": "账户域名",
-            "type": "string"
+          "member_name": {
+            "type": "string",
+            "description": "成员显示名称"
+          },
+          "phone": {
+            "type": "string",
+            "description": "脱敏手机号"
+          },
+          "phone_verified": {
+            "type": "boolean",
+            "description": "手机号是否已验证"
           },
           "email": {
-            "description": "邮箱地址",
-            "type": "string"
+            "type": "string",
+            "description": "邮箱地址"
           },
           "email_verified": {
-            "description": "邮箱是否已验证",
-            "type": "boolean"
+            "type": "boolean",
+            "description": "邮箱是否已验证"
           },
-          "is_external": {
-            "description": "是否通过 SSO 创建",
-            "type": "boolean"
+          "country_code": {
+            "type": "string",
+            "description": "成员联系手机的 ISO 3166-1 alpha-2 地区代码（如 \"CN\"、\"US\"、\"HK\"）。"
+          },
+          "avatar": {
+            "type": "string",
+            "description": "成员头像 URL"
           },
           "locale": {
-            "description": "成员语言偏好。成员未设置时不返回。",
-            "type": "string"
+            "type": "string",
+            "description": "成员语言偏好。成员未设置时不返回。"
           },
-          "member_id": {
-            "description": "成员 ID",
-            "format": "uint64",
-            "type": "integer"
+          "time_zone": {
+            "type": "string",
+            "description": "成员自己设置的 IANA 时区；跟随账户时区时为空字符串。始终返回。"
           },
-          "member_name": {
-            "description": "成员显示名称",
-            "type": "string"
+          "is_external": {
+            "type": "boolean",
+            "description": "是否通过 SSO 创建"
           },
-          "mp_account_id": {
-            "description": "账户在云市场平台上的标识。与 `mp_plat` 一起省略。",
-            "type": "string"
+          "created_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "成员创建时间，Unix 秒级时间戳。"
           },
           "mp_plat": {
-            "description": "账户来源的云市场平台。账户非来自云市场时不返回。",
-            "type": "string"
-          },
-          "phone": {
-            "description": "脱敏手机号",
-            "type": "string"
-          },
-          "phone_verified": {
-            "description": "手机号是否已验证",
-            "type": "boolean"
+            "type": "string",
+            "description": "账户开通来源的云市场：`aws`——AWS Marketplace。账户并非来自云市场时省略。",
+            "enum": [
+              "aws"
+            ]
           },
-          "time_zone": {
-            "description": "成员的 IANA 时区。成员未设置时不返回。",
-            "type": "string"
+          "mp_account_id": {
+            "type": "string",
+            "description": "账户在云市场平台上的标识。与 `mp_plat` 一起省略。"
           }
         },
         "required": [
@@ -15976,9 +16391,11 @@
           "country_code",
           "avatar",
           "is_external",
-          "created_at"
-        ],
-        "type": "object"
+          "created_at",
+          "time_zone",
+          "account_time_zone",
+          "resolved_time_zone"
+        ]
       },
       "MemberInviteRequest": {
         "description": "邀请成员请求",
@@ -16002,187 +16419,190 @@
         "type": "object"
       },
       "MemberInviteResponse": {
+        "type": "object",
         "description": "邀请成员响应",
         "properties": {
           "items": {
-            "description": "新建的成员列表",
+            "type": [
+              "array",
+              "null"
+            ],
             "items": {
               "$ref": "#/components/schemas/NewMemberItem"
             },
-            "type": "array"
+            "description": "本次新建的成员；因已存在而跳过的条目不会列出。一个都没有创建时为 `null`。"
           }
-        },
-        "type": "object"
+        }
       },
       "MemberItem": {
+        "type": "object",
         "description": "成员条目",
+        "required": [
+          "account_id",
+          "member_id",
+          "member_name",
+          "country_code",
+          "phone",
+          "email",
+          "phone_verified",
+          "email_verified",
+          "avatar",
+          "status",
+          "account_role_ids",
+          "created_at",
+          "updated_at",
+          "ref_id",
+          "is_external"
+        ],
         "properties": {
           "account_id": {
-            "description": "账户 ID",
+            "type": "integer",
             "format": "uint64",
-            "type": "integer"
+            "description": "成员所属账户的 ID。"
           },
-          "account_role_ids": {
-            "description": "角色 ID 列表",
-            "items": {
-              "format": "uint64",
-              "type": "integer"
-            },
-            "type": "array"
+          "member_id": {
+            "type": "integer",
+            "format": "uint64",
+            "description": "成员 ID；在其他接口中同一值即人员 ID（如 `person_ids`）。"
           },
-          "avatar": {
-            "description": "头像 URL",
-            "type": "string"
+          "member_name": {
+            "type": "string",
+            "description": "显示名称，在账户内唯一。"
           },
           "country_code": {
-            "description": "成员联系手机的 ISO 3166-1 alpha-2 地区代码（如 \"CN\"、\"US\"、\"HK\"）。",
-            "type": "string"
+            "type": "string",
+            "description": "成员联系手机的 ISO 3166-1 alpha-2 地区代码（如 \"CN\"、\"US\"、\"HK\"）。"
           },
-          "created_at": {
-            "description": "创建时间（Unix 秒）",
-            "format": "int64",
-            "type": "integer"
+          "phone": {
+            "type": "string",
+            "description": "E.164 格式的手机号，中间几位已打码（如 `+86151****6519`）；未设置时为空字符串。"
           },
           "email": {
-            "description": "邮箱地址",
-            "type": "string"
-          },
-          "email_verified": {
-            "description": "邮箱已验证",
-            "type": "boolean"
-          },
-          "is_external": {
-            "description": "是否通过 SSO 创建",
-            "type": "boolean"
+            "type": "string",
+            "description": "邮箱地址（小写）；未设置时为空字符串。"
           },
           "locale": {
-            "description": "成员语言偏好（如 `zh-CN`）。为空时不返回——列表接口不填充该字段。",
-            "type": "string"
-          },
-          "member_id": {
-            "description": "成员 ID",
-            "format": "uint64",
-            "type": "integer"
-          },
-          "member_name": {
-            "description": "显示名称",
-            "type": "string"
+            "type": "string",
+            "description": "语言偏好。`POST /member/list` 不填充该字段，因此始终省略。"
           },
-          "phone": {
-            "description": "脱敏手机号",
-            "type": "string"
+          "time_zone": {
+            "type": "string",
+            "description": "成员自己设置的 IANA 时区（如 `Asia/Shanghai`）。未设置时省略，表示跟随账户时区；生效时区可通过 `POST /member/info` 获取。"
           },
           "phone_verified": {
-            "description": "手机已验证",
-            "type": "boolean"
+            "type": "boolean",
+            "description": "成员已验证手机号时为 `true`。"
           },
-          "ref_id": {
-            "description": "外部引用 ID",
-            "type": "string"
+          "email_verified": {
+            "type": "boolean",
+            "description": "成员已验证邮箱时为 `true`。"
+          },
+          "avatar": {
+            "type": "string",
+            "description": "头像图片 URL 或路径；未设置时为空字符串。"
           },
           "status": {
-            "description": "成员状态。`enabled` — 已激活成员；`pending` — 已邀请但尚未接受；`deleted` — 已从组织移除。",
+            "type": "string",
             "enum": [
               "enabled",
-              "pending",
-              "deleted"
+              "pending"
             ],
-            "type": "string"
+            "description": "成员状态。`enabled`——正常成员；`pending`——已邀请但尚未接受。已删除的成员不会列出。"
           },
-          "time_zone": {
-            "description": "成员的 IANA 时区（如 `Asia/Shanghai`）。为空时不返回——列表接口不填充该字段。",
-            "type": "string"
+          "account_role_ids": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "uint64"
+            },
+            "description": "成员被分配的角色 ID：内置的 `2`（Admin）、`6`（Responder）、`8`（Viewer），或 `POST /role/list` 中的自定义角色 ID。"
+          },
+          "is_external": {
+            "type": "boolean",
+            "description": "成员通过单点登录同步创建（而非邀请或注册）时为 `true`。"
+          },
+          "ref_id": {
+            "type": "string",
+            "description": "外部引用 ID（如 HR 系统中的员工号）；未设置时为空字符串。"
+          },
+          "created_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "创建时间（Unix 秒）"
           },
           "updated_at": {
-            "description": "更新时间（Unix 秒）",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "更新时间（Unix 秒）"
           }
-        },
-        "required": [
-          "account_id",
-          "member_id",
-          "member_name",
-          "country_code",
-          "phone",
-          "email",
-          "phone_verified",
-          "email_verified",
-          "avatar",
-          "status",
-          "account_role_ids",
-          "created_at",
-          "updated_at",
-          "ref_id",
-          "is_external"
-        ],
-        "type": "object"
+        }
       },
       "MemberListRequest": {
+        "type": "object",
         "description": "查询成员列表请求",
         "properties": {
-          "asc": {
-            "description": "是否升序，默认 false（降序）",
-            "type": "boolean"
-          },
-          "limit": {
-            "default": 100,
-            "description": "每页条数，省略或传 0 时服务端默认 100",
-            "maximum": 100,
-            "minimum": 1,
-            "type": "integer"
+          "role_id": {
+            "type": "integer",
+            "format": "uint64",
+            "description": "按角色 ID 过滤，角色 ID 可通过 `POST /role/list` 获取（内置角色：2=Admin、6=Responder、8=Viewer）"
           },
           "member_id": {
-            "description": "按成员 ID 过滤，仅返回该成员。",
+            "type": "integer",
             "format": "uint64",
-            "type": "integer"
+            "description": "按成员 ID 过滤，仅返回该成员。"
+          },
+          "p": {
+            "type": "integer",
+            "minimum": 1,
+            "description": "页码，从 1 开始。默认第一页。"
+          },
+          "limit": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 100,
+            "description": "每页条数，省略或传 0 时服务端默认 100",
+            "default": 100
           },
           "orderby": {
-            "description": "排序字段，默认 `updated_at`",
+            "type": "string",
             "enum": [
               "created_at",
               "updated_at"
             ],
-            "type": "string"
+            "description": "排序字段，默认 `updated_at`"
           },
-          "p": {
-            "description": "页码，从 1 开始",
-            "minimum": 1,
-            "type": "integer"
+          "asc": {
+            "type": "boolean",
+            "description": "是否升序，默认 false（降序）"
           },
           "query": {
-            "description": "按成员名称或邮箱做子串匹配；若可解析为手机号，则同时按手机号精确匹配",
-            "type": "string"
-          },
-          "role_id": {
-            "description": "按角色 ID 过滤，角色 ID 可通过 `POST /role/list` 获取（内置角色：2=Admin、6=Responder、8=Viewer）",
-            "format": "uint64",
-            "type": "integer"
+            "type": "string",
+            "description": "搜索关键字。对成员名称或邮箱做子串匹配；纯数字关键字还会精确匹配成员 ID；能解析为手机号的关键字（不带 `+` 时按中国号码解析）还会精确匹配手机号。"
           }
-        },
-        "type": "object"
+        }
       },
       "MemberListResponse": {
+        "type": "object",
         "description": "成员列表响应",
         "properties": {
-          "items": {
-            "description": "成员列表",
-            "items": {
-              "$ref": "#/components/schemas/MemberItem"
-            },
-            "type": "array"
+          "p": {
+            "type": "integer",
+            "description": "请求中的页码；未传 `p` 时为 `0`（返回的是第一页）。"
           },
           "limit": {
-            "description": "每页条数",
-            "type": "integer"
-          },
-          "p": {
-            "description": "当前页码",
-            "type": "integer"
+            "type": "integer",
+            "description": "实际使用的每页条数；未传 `limit` 时为 100。"
           },
           "total": {
-            "description": "总数",
-            "type": "integer"
+            "type": "integer",
+            "description": "符合筛选条件的成员总数（跨所有页）。"
+          },
+          "items": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/MemberItem"
+            },
+            "description": "当前页的成员；没有匹配时为空数组。"
           }
         },
         "required": [
@@ -16190,33 +16610,32 @@
           "limit",
           "total",
           "items"
-        ],
-        "type": "object"
+        ]
       },
       "MemberOncallInterval": {
+        "type": "object",
         "description": "成员的一个值班班次区间。",
         "properties": {
-          "end_at": {
-            "description": "Unix 时间戳（秒）—— 班次结束时间。值班进行中时缺省。",
-            "format": "int64",
-            "type": "integer"
-          },
           "schedule_id": {
+            "type": "integer",
             "description": "所属排班 ID。",
-            "format": "int64",
-            "type": "integer"
+            "format": "int64"
           },
           "schedule_name": {
-            "description": "所属排班名称。",
-            "type": "string"
+            "type": "string",
+            "description": "所属排班名称。"
           },
           "start_at": {
+            "type": "integer",
             "description": "Unix 时间戳（秒）—— 班次开始时间。",
-            "format": "int64",
-            "type": "integer"
+            "format": "int64"
+          },
+          "end_at": {
+            "type": "integer",
+            "description": "班次结束时间（Unix 秒）。`current` 中返回；`next` 中省略。",
+            "format": "int64"
           }
-        },
-        "type": "object"
+        }
       },
       "MemberResetInfoRequest": {
         "anyOf": [
@@ -16288,397 +16707,397 @@
         "type": "object"
       },
       "MemberResetInfoUpdates": {
+        "type": "object",
         "description": "要写入的成员资料字段。未传的字段保持不变。",
         "properties": {
-          "avatar": {
-            "description": "新的头像 URL。",
-            "maxLength": 499,
+          "member_name": {
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "minLength": 2,
+            "maxLength": 39,
+            "description": "新的显示名称，2–39 个字符，在账户内唯一。"
           },
-          "country_code": {
-            "description": "ISO 3166-1 alpha-2 地区代码（如 \"CN\"、\"US\"）。可独立更新（无需同时传 `phone`），并兼作解析 `phone` 的地区提示；非法值返回 400，显式传空字符串也会被拒绝。",
+          "password": {
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "按前端加密格式传入的新登录密码。"
           },
-          "email": {
-            "description": "新的邮箱地址。",
+          "phone": {
             "type": [
               "string",
               "null"
-            ]
-          },
-          "locale": {
-            "description": "新的语言偏好。可选值：`zh-CN`（简体中文）、`en-US`（英文）；非法值返回 400。",
-            "enum": [
-              "zh-CN",
-              "en-US"
             ],
+            "description": "新的手机号；非 E.164 格式时请同时传 `country_code`。不能已属于其他成员；新号码会被标记为未验证（见 `from`）。"
+          },
+          "country_code": {
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "ISO 3166-1 alpha-2 地区代码（如 \"CN\"、\"US\"）。可独立更新（无需同时传 `phone`），并兼作解析 `phone` 的地区提示；非法值返回 400，显式传空字符串也会被拒绝。"
           },
-          "member_name": {
-            "description": "新的显示名称。",
-            "maxLength": 39,
-            "minLength": 2,
+          "email": {
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "新的邮箱地址。不能已属于其他成员；新地址会被标记为未验证（见 `from`）。"
           },
-          "password": {
-            "description": "按前端加密格式传入的新登录密码。",
+          "avatar": {
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "maxLength": 499,
+            "description": "新的头像 URL。"
           },
-          "phone": {
-            "description": "新的手机号；如不是 E.164 格式，可同时传 country_code。",
+          "locale": {
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "enum": [
+              "zh-CN",
+              "en-US"
+            ],
+            "description": "新的语言偏好。可选值：`zh-CN`（简体中文）、`en-US`（英文）；非法值返回 400。"
           },
-          "ref_id": {
-            "description": "新的外部引用 ID。",
+          "time_zone": {
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "新的 IANA 时区名称，如 `Asia/Shanghai`；传空字符串会清除该设置，使成员跟随账户时区。名称无效时返回 `400`。"
           },
-          "time_zone": {
-            "description": "新的 IANA 时区名称，例如 Asia/Shanghai。",
+          "ref_id": {
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "新的外部引用 ID；传空字符串会清空。"
           }
-        },
-        "type": "object"
+        }
       },
       "MemberRoleGrantRequest": {
+        "type": "object",
         "description": "授予成员角色请求",
+        "required": [
+          "member_id",
+          "role_ids"
+        ],
         "properties": {
           "member_id": {
-            "description": "成员 ID",
+            "type": "integer",
             "format": "uint64",
-            "type": "integer"
+            "description": "要修改角色的成员 ID（取自 `POST /member/list`）。"
           },
           "role_ids": {
-            "description": "要授予的角色 ID 列表，将追加到成员现有角色集合（自动去重）。",
+            "type": "array",
             "items": {
-              "format": "uint64",
-              "type": "integer"
+              "type": "integer",
+              "format": "uint64"
             },
-            "type": "array"
+            "description": "要授予的角色 ID 列表，将追加到成员现有角色集合（自动去重）。"
           }
-        },
+        }
+      },
+      "MemberRoleRevokeRequest": {
+        "type": "object",
+        "description": "解除成员角色请求",
         "required": [
           "member_id",
           "role_ids"
         ],
-        "type": "object"
-      },
-      "MemberRoleRevokeRequest": {
-        "description": "解除成员角色请求",
         "properties": {
           "member_id": {
-            "description": "成员 ID",
+            "type": "integer",
             "format": "uint64",
-            "type": "integer"
+            "description": "要修改角色的成员 ID（取自 `POST /member/list`）。"
           },
           "role_ids": {
-            "description": "要从成员处撤销的角色 ID 列表。",
+            "type": "array",
             "items": {
-              "format": "uint64",
-              "type": "integer"
+              "type": "integer",
+              "format": "uint64"
             },
-            "type": "array"
+            "description": "要从成员处撤销的角色 ID 列表。"
           }
-        },
-        "required": [
-          "member_id",
-          "role_ids"
-        ],
-        "type": "object"
+        }
       },
       "MemberRoleUpdateRequest": {
+        "type": "object",
         "description": "更新成员角色请求",
+        "required": [
+          "member_id"
+        ],
         "properties": {
           "member_id": {
-            "description": "成员 ID",
+            "type": "integer",
             "format": "uint64",
-            "type": "integer"
+            "description": "要修改角色的成员 ID（取自 `POST /member/list`）。"
           },
           "role_ids": {
-            "description": "新的角色 ID 集合，整体替换成员现有角色（非追加）；可通过 `POST /role/list` 获取，留空时重置为内置 Viewer 角色（ID 8）",
+            "type": "array",
             "items": {
-              "format": "uint64",
-              "type": "integer"
+              "type": "integer",
+              "format": "uint64"
             },
-            "type": "array"
+            "description": "新的角色 ID 集合，整体替换成员现有角色（不是追加）。ID 可通过 `POST /role/list` 获取。"
           }
-        },
-        "required": [
-          "member_id"
-        ],
-        "type": "object"
+        }
       },
       "MemberScheduleItem": {
+        "type": "object",
         "description": "该成员参与的一个启用中的排班。",
         "properties": {
           "schedule_id": {
-            "description": "排班 ID。",
-            "format": "int64",
-            "type": "integer"
+            "type": "integer",
+            "description": "成员参与的值班表 ID，可传给 `/schedule/info`。",
+            "format": "int64"
           },
           "schedule_name": {
-            "description": "排班名称。",
-            "type": "string"
+            "type": "string",
+            "description": "该值班表的名称。"
           }
-        },
-        "type": "object"
+        }
       },
       "MergeIncidentsRequest": {
+        "type": "object",
         "description": "合并故障的参数。",
+        "required": [
+          "source_incident_ids",
+          "target_incident_id"
+        ],
         "properties": {
-          "comment": {
-            "description": "可选，合并时间线上的备注。",
-            "maxLength": 1024,
-            "type": "string"
-          },
-          "owner_id": {
-            "description": "仅为兼容保留，服务端当前忽略该字段；合并不会修改目标故障的负责人。",
-            "format": "int64",
-            "type": "integer"
-          },
-          "remove_source_incidents": {
-            "description": "为 true 时合并后软删除源故障，否则将源故障关闭。",
-            "type": "boolean"
-          },
           "source_incident_ids": {
-            "description": "待合并的源故障 ID 列表。若其中包含目标故障 ID，系统会自动去除。",
+            "type": "array",
             "items": {
-              "pattern": "^[0-9a-fA-F]{24}$",
-              "type": "string"
+              "type": "string",
+              "pattern": "^[0-9a-fA-F]{24}$"
             },
-            "maxItems": 100,
             "minItems": 1,
-            "type": "array"
+            "maxItems": 100,
+            "description": "待合并的源故障 ID 列表。若其中包含目标故障 ID，系统会自动去除。"
           },
           "target_incident_id": {
-            "description": "合并目标故障 ID，可通过 `POST /incident/list` 获取。",
+            "type": "string",
             "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
+            "description": "合并目标故障 ID，可通过 `POST /incident/list` 获取。"
           },
           "title": {
-            "description": "可选，为目标故障设置新标题。",
+            "type": "string",
             "maxLength": 512,
-            "type": "string"
+            "description": "可选，为目标故障设置新标题。"
+          },
+          "comment": {
+            "type": "string",
+            "maxLength": 1024,
+            "description": "可选，合并时间线上的备注。"
+          },
+          "owner_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "仅为兼容保留，服务端当前忽略该字段；合并不会修改目标故障的负责人。"
+          },
+          "remove_source_incidents": {
+            "type": "boolean",
+            "description": "为 true 时，源故障的告警转移到目标故障后永久删除源故障；为 false 时源故障被关闭并保留。"
           }
-        },
-        "required": [
-          "source_incident_ids",
-          "target_incident_id"
-        ],
-        "type": "object"
+        }
       },
       "MetricsBase": {
+        "type": "object",
         "description": "每条聚合洞察行都带有的共享维度字段。",
         "properties": {
-          "channel_id": {
-            "description": "协作空间 ID，仅在按协作空间聚合（`/insight/channel`）时返回。",
-            "format": "int64",
-            "type": "integer"
-          },
-          "channel_name": {
-            "description": "协作空间名称，按协作空间聚合时返回；名称查不到时省略。",
-            "type": "string"
-          },
           "hours": {
-            "description": "启用 `split_hours` 时的小时桶。`work` 为周一至周五 08:00–19:00，`sleep` 为每天 23:00–08:00，`off` 为其余时间，均按账户时区计算（`sleep` 优先于 `work`）。`split_hours` 为 false 时不返回。",
+            "type": "string",
             "enum": [
               "work",
               "sleep",
               "off"
             ],
-            "type": "string"
+            "description": "启用 `split_hours` 时的小时桶。`work` 为周一至周五 08:00–19:00，`sleep` 为每天 23:00–08:00，`off` 为其余时间，均按账户时区计算（`sleep` 优先于 `work`）。`split_hours` 为 false 时不返回。"
           },
-          "responder_id": {
-            "description": "处理人员（个人）ID，仅在按处理人员聚合（`/insight/responder`）时返回。",
+          "ts": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "时间桶的开始时间（Unix 秒）。未设置 `aggregate_unit` 时等于 `start_time`。"
           },
-          "responder_name": {
-            "description": "处理人员姓名，按处理人员聚合时返回；姓名查不到时省略。",
-            "type": "string"
+          "channel_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "协作空间 ID，仅在按协作空间聚合（`/insight/channel`）时返回。"
           },
           "team_id": {
-            "description": "团队 ID，仅在按团队聚合（`/insight/team`）时返回。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "团队 ID，仅 `/insight/team` 返回。汇总未归属团队故障的那一行不含该字段。"
+          },
+          "responder_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "处理人员（个人）ID，仅在按处理人员聚合（`/insight/responder`）时返回。"
           },
           "team_name": {
-            "description": "团队名称，按团队聚合时返回；名称查不到（如团队已删除）时省略。",
-            "type": "string"
+            "type": "string",
+            "description": "团队名称，按团队聚合时返回；名称查不到（如团队已删除）时省略。"
           },
-          "ts": {
-            "description": "聚合桶的起始时间，Unix 时间戳（秒）。未使用 `aggregate_unit` 时等于 `start_time`。",
-            "format": "int64",
-            "type": "integer"
+          "channel_name": {
+            "type": "string",
+            "description": "协作空间名称，按协作空间聚合时返回；名称查不到时省略。"
+          },
+          "responder_name": {
+            "type": "string",
+            "description": "处理人员姓名，按处理人员聚合时返回；姓名查不到时省略。"
           }
-        },
-        "type": "object"
+        }
       },
       "MigrateStatusPageEmailSubscribersRequest": {
+        "type": "object",
         "description": "启动 Atlassian Statuspage 邮件订阅者迁移任务所需的参数。",
+        "required": [
+          "api_key",
+          "source_page_id",
+          "target_page_id"
+        ],
         "properties": {
           "api_key": {
-            "description": "可访问源状态页的 Atlassian Statuspage API Key。",
-            "type": "string"
+            "type": "string",
+            "description": "可访问源状态页的 Atlassian Statuspage API Key。"
           },
           "source_page_id": {
-            "description": "Atlassian Statuspage 源状态页 ID。",
-            "type": "string"
+            "type": "string",
+            "description": "Atlassian Statuspage 源页面 ID，只能包含字母、数字、`_` 和 `-`。"
           },
           "target_page_id": {
-            "description": "接收导入订阅者的 Flashduty 目标状态页 ID。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "接收导入订阅者的 Flashduty 目标状态页 ID。"
           }
-        },
-        "required": [
-          "api_key",
-          "source_page_id",
-          "target_page_id"
-        ],
-        "type": "object"
+        }
       },
       "MigrateStatusPageStructureRequest": {
+        "type": "object",
         "description": "启动 Atlassian Statuspage 结构与历史迁移任务所需的参数。",
+        "required": [
+          "api_key",
+          "source_page_id"
+        ],
         "properties": {
           "api_key": {
-            "description": "可访问源状态页的 Atlassian Statuspage API Key。",
-            "type": "string"
+            "type": "string",
+            "description": "可访问源状态页的 Atlassian Statuspage API Key。"
           },
           "source_page_id": {
-            "description": "Atlassian Statuspage 源状态页 ID。",
-            "type": "string"
+            "type": "string",
+            "description": "Atlassian Statuspage 源页面 ID，只能包含字母、数字、`_` 和 `-`。"
           },
           "url_name": {
-            "description": "新状态页的目标 URL 名称，会被规范化为 URL 安全的别名（最长 255 字符）。省略或传 null 时根据源状态页名称生成；显式传空字符串会被拒绝。",
-            "maxLength": 255,
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "新状态页的目标 URL 名称，会被规范化为 URL 安全的别名（最长 255 字符）。省略或传 null 时根据源状态页名称生成；显式传空字符串会被拒绝。",
+            "maxLength": 255
           }
-        },
-        "required": [
-          "api_key",
-          "source_page_id"
-        ],
-        "type": "object"
+        }
       },
       "NameMessage": {
+        "type": "object",
         "description": "批量规则操作中，单条规则的处理结果。",
-        "properties": {
-          "message": {
-            "description": "成功时为空，失败时为错误信息。",
-            "type": "string"
-          },
-          "name": {
-            "description": "规则名称。",
-            "type": "string"
-          }
-        },
         "required": [
           "name",
           "message"
         ],
-        "type": "object"
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "该结果对应的规则名称；规则 ID 不存在时为 `id: <id>`。"
+          },
+          "message": {
+            "type": "string",
+            "description": "该规则的处理结果。成功时，`/monit/rule/update/fields` 返回空字符串，`/monit/rule/move` 返回本地化的成功文案（`Move successfully` / `移动成功`）；失败时为错误信息。"
+          }
+        }
       },
       "NewMemberItem": {
+        "type": "object",
         "description": "新建成员信息",
         "properties": {
           "member_id": {
-            "description": "成员 ID",
+            "type": "integer",
             "format": "uint64",
-            "type": "integer"
+            "description": "新建成员的 ID。"
           },
           "member_name": {
-            "description": "成员显示名称",
-            "type": "string"
+            "type": "string",
+            "description": "为成员保存的显示名称；未传 `member_name` 时取邮箱前缀。"
           }
-        },
-        "type": "object"
+        }
       },
       "NotifyChat": {
+        "type": "object",
         "description": "群聊通知投递记录。",
         "properties": {
+          "data_source_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "发送通知所用的集成数据源 ID。"
+          },
           "chat_id": {
-            "description": "群聊 ID。",
-            "type": "string"
+            "type": "string",
+            "description": "群聊 ID。"
           },
           "chat_name": {
-            "description": "群聊显示名称。",
-            "type": "string"
-          },
-          "data_source_id": {
-            "description": "发送通知所用的集成数据源 ID。",
-            "format": "int64",
-            "type": "integer"
+            "type": "string",
+            "description": "群聊显示名称。"
           },
           "failed_reason": {
-            "description": "投递失败原因。",
-            "type": "string"
+            "type": "string",
+            "description": "投递渠道上报的本地化失败原因；投递成功或未上报失败时省略。该文本不是固定的错误码集合。"
           }
-        },
-        "type": "object"
+        }
       },
       "NotifyPerson": {
+        "type": "object",
         "description": "个人通知投递记录。",
         "properties": {
-          "failed_reason": {
-            "description": "投递失败原因。",
-            "type": "string"
-          },
           "person_id": {
-            "description": "接收人成员 ID。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "接收人成员 ID。"
+          },
+          "failed_reason": {
+            "type": "string",
+            "description": "投递渠道上报的本地化失败原因；投递成功或未上报失败时省略。该文本不是固定的错误码集合。"
           },
           "sms_content": {
-            "description": "短信投递时发送的短信内容。",
-            "type": "string"
+            "type": "string",
+            "description": "短信投递时发送的短信内容。"
           }
-        },
-        "type": "object"
+        }
       },
       "NotifyRobot": {
+        "type": "object",
         "description": "机器人 webhook 通知投递记录。",
         "properties": {
+          "token": {
+            "type": "string",
+            "description": "机器人 token 或标识。"
+          },
           "alias": {
-            "description": "机器人别名。",
-            "type": "string"
+            "type": "string",
+            "description": "机器人别名。"
           },
           "failed_reason": {
-            "description": "投递失败原因。",
-            "type": "string"
-          },
-          "token": {
-            "description": "机器人 token 或标识。",
-            "type": "string"
+            "type": "string",
+            "description": "投递渠道上报的本地化失败原因；投递成功或未上报失败时省略。该文本不是固定的错误码集合。"
           }
-        },
-        "type": "object"
+        }
       },
       "OnceTimeFilter": {
         "description": "以 Unix 秒定义的一次性时间窗口。",
@@ -16915,99 +17334,99 @@
         "type": "object"
       },
       "PersonItem": {
+        "type": "object",
         "description": "人员资料",
+        "required": [
+          "account_id",
+          "person_id",
+          "phone_verified",
+          "email_verified"
+        ],
         "properties": {
           "account_id": {
-            "description": "账户 ID",
+            "type": "integer",
             "format": "uint64",
-            "type": "integer"
+            "description": "人员所属账户的 ID。"
           },
-          "as": {
-            "description": "主体类型：`account` —— 账户主体（注册人）；`member` —— 组织成员。",
-            "enum": [
-              "account",
-              "member"
-            ],
-            "type": "string"
-          },
-          "avatar": {
-            "description": "头像 URL。为空时不返回。",
-            "type": "string"
+          "person_id": {
+            "type": "integer",
+            "format": "uint64",
+            "description": "人员 ID：账户主体为账户 ID，其他人为成员 ID。"
           },
-          "email": {
-            "description": "邮箱地址。为空时不返回。",
-            "type": "string"
+          "person_name": {
+            "type": "string",
+            "description": "显示名称。为空时不返回。"
           },
-          "email_verified": {
-            "description": "邮箱已验证",
-            "type": "boolean"
+          "avatar": {
+            "type": "string",
+            "description": "头像 URL。为空时不返回。"
           },
           "locale": {
-            "description": "语言。为空时不返回。",
-            "type": "string"
+            "type": "string",
+            "description": "语言偏好（`zh-CN` 或 `en-US`）。未设置时省略。"
           },
-          "person_id": {
-            "description": "人员 ID",
-            "format": "uint64",
-            "type": "integer"
+          "time_zone": {
+            "type": "string",
+            "description": "IANA 时区设置：成员为其自己的设置，账户主体为账户设置。未设置时省略（未设置的成员跟随账户时区）。"
           },
-          "person_name": {
-            "description": "显示名称。为空时不返回。",
-            "type": "string"
+          "email": {
+            "type": "string",
+            "description": "邮箱地址。为空时不返回。"
           },
           "phone": {
-            "description": "手机号。为空时不返回——本接口不填充该字段。",
-            "type": "string"
+            "type": "string",
+            "description": "手机号。为空时不返回——本接口不填充该字段。"
           },
           "phone_verified": {
-            "description": "手机号是否已验证。本接口的响应中恒为 false。",
-            "type": "boolean"
+            "type": "boolean",
+            "description": "手机号是否已验证。本接口的响应中恒为 false。"
+          },
+          "email_verified": {
+            "type": "boolean",
+            "description": "邮箱已验证时为 `true`；账户主体只要设置了邮箱即为 `true`。"
+          },
+          "as": {
+            "type": "string",
+            "description": "主体类型：`account` —— 账户主体（注册人）；`member` —— 组织成员。",
+            "enum": [
+              "account",
+              "member"
+            ]
           },
           "status": {
-            "description": "人员状态。`enabled` — 已激活；`pending` — 已邀请但尚未接受；`deleted` — 已移除。为空时不返回。",
+            "type": "string",
             "enum": [
               "enabled",
               "pending",
               "deleted"
             ],
-            "type": "string"
-          },
-          "time_zone": {
-            "description": "时区。为空时不返回。",
-            "type": "string"
+            "description": "人员状态。`enabled` — 已激活；`pending` — 已邀请但尚未接受；`deleted` — 已移除。为空时不返回。"
           }
-        },
-        "required": [
-          "account_id",
-          "person_id",
-          "phone_verified",
-          "email_verified"
-        ],
-        "type": "object"
+        }
       },
       "PersonShort": {
+        "type": "object",
         "description": "Flashduty 成员信息。",
         "properties": {
-          "as": {
-            "description": "成员在当前上下文中的角色标签。",
-            "type": "string"
-          },
-          "email": {
-            "description": "成员邮箱。",
-            "format": "email",
-            "type": "string"
-          },
           "person_id": {
-            "description": "成员 ID。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "成员 ID，与 `POST /member/list` 返回的 ID 相同。"
           },
           "person_name": {
-            "description": "成员显示名称。",
-            "type": "string"
+            "type": "string",
+            "description": "成员显示名称。"
+          },
+          "email": {
+            "type": "string",
+            "format": "email",
+            "description": "成员邮箱。"
+          },
+          "as": {
+            "type": "string",
+            "description": "成员在当前上下文中的角色标签。"
           }
-        },
-        "type": "object"
+        }
       },
       "PlatformEmptyObject": {
         "additionalProperties": false,
@@ -17063,281 +17482,293 @@
         "type": "object"
       },
       "PostMortemItem": {
+        "type": "object",
         "description": "完整复盘报告，包含基础信息、正文与跟进项。",
+        "required": [
+          "meta",
+          "basics",
+          "content",
+          "follow_ups",
+          "has_active_incident"
+        ],
         "properties": {
+          "meta": {
+            "$ref": "#/components/schemas/PostMortemMeta"
+          },
           "basics": {
-            "description": "由关联故障自动汇总的基础信息：最高严重程度、最早开始/最晚关闭时间、累计持续时长与参与人。",
+            "type": "object",
+            "required": [
+              "incidents_highest_severity",
+              "incidents_earliest_start_seconds",
+              "incidents_latest_close_seconds",
+              "incidents_total_duration_seconds",
+              "responders"
+            ],
             "properties": {
+              "incidents_highest_severity": {
+                "type": "string",
+                "description": "关联故障中最高的严重程度：`Critical`、`Warning` 或 `Info`；仅在手动设置时可能为 `Ok`。",
+                "enum": [
+                  "Critical",
+                  "Warning",
+                  "Info",
+                  "Ok"
+                ]
+              },
               "incidents_earliest_start_seconds": {
-                "description": "关联故障中最早的开始时间（秒）。",
+                "type": "integer",
                 "format": "int64",
-                "type": "integer"
-              },
-              "incidents_highest_severity": {
-                "description": "关联故障的最高严重程度。",
-                "type": "string"
+                "description": "关联故障中最早的开始时间（Unix 秒）。"
               },
               "incidents_latest_close_seconds": {
-                "description": "关联故障中最晚的关闭时间（秒）。",
+                "type": "integer",
                 "format": "int64",
-                "type": "integer"
+                "description": "关联故障中最晚的关闭时间（Unix 秒）；尚未关闭的故障取其 `end_time`。"
               },
               "incidents_total_duration_seconds": {
-                "description": "累计持续时长（秒）。",
+                "type": "integer",
                 "format": "int64",
-                "type": "integer"
+                "description": "从关联故障最早开始到最晚关闭的秒数（不是各故障时长之和）。"
               },
               "responders": {
-                "description": "参与处理的成员。",
+                "type": "array",
                 "items": {
                   "$ref": "#/components/schemas/Responder"
                 },
-                "type": "array"
+                "description": "参与处理的成员。"
               }
             },
-            "required": [
-              "incidents_highest_severity",
-              "incidents_earliest_start_seconds",
-              "incidents_latest_close_seconds",
-              "incidents_total_duration_seconds",
-              "responders"
-            ],
-            "type": "object"
+            "description": "由关联故障自动汇总的基础信息：最高严重程度、最早开始/最晚关闭时间、累计持续时长与参与人。"
           },
           "content": {
-            "description": "复盘正文，对象内仅含一个 `content` 字段，值为 BlockNote JSON 字符串。",
+            "type": "object",
+            "required": [
+              "content"
+            ],
             "properties": {
               "content": {
-                "description": "正文内容（BlockNote JSON）。",
-                "type": "string"
+                "type": "string",
+                "description": "正文内容（BlockNote JSON）。"
               }
             },
-            "required": [
-              "content"
-            ],
-            "type": "object"
+            "description": "复盘正文，对象内仅含一个 `content` 字段，值为 BlockNote JSON 字符串。"
           },
           "follow_ups": {
-            "description": "跟进行动项，单字符串表示。",
-            "type": "string"
+            "type": "string",
+            "description": "跟进行动项，单字符串表示。"
           },
-          "meta": {
-            "$ref": "#/components/schemas/PostMortemMeta"
+          "has_active_incident": {
+            "type": "boolean",
+            "description": "至少有一个关联故障尚未关闭时为 `true`；全部关闭前后续行动保持锁定。每次请求实时计算。"
           }
-        },
-        "required": [
-          "meta",
-          "basics",
-          "content",
-          "follow_ups"
-        ],
-        "type": "object"
+        }
       },
       "PostMortemMeta": {
+        "type": "object",
         "description": "复盘报告元信息（列表中使用的精简结构）。",
+        "required": [
+          "account_id",
+          "title",
+          "status",
+          "post_mortem_id",
+          "template_id",
+          "incident_ids",
+          "media_count",
+          "author_ids",
+          "team_id",
+          "channel_id",
+          "is_private",
+          "generation",
+          "revision",
+          "channel_name",
+          "created_at_seconds",
+          "updated_at_seconds"
+        ],
         "properties": {
           "account_id": {
-            "description": "账号 ID。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
-          },
-          "author_ids": {
-            "description": "贡献过该复盘的成员 ID 列表。",
-            "items": {
-              "format": "int64",
-              "type": "integer"
-            },
-            "type": "array"
+            "description": "该记录所属账户的 ID；同一 `app_key` 返回的记录该值都相同。"
           },
-          "channel_id": {
-            "description": "所属协作空间 ID，为 0 表示无。",
-            "format": "int64",
-            "type": "integer"
+          "title": {
+            "type": "string",
+            "description": "复盘标题。"
           },
-          "channel_name": {
-            "description": "协作空间名称，由服务端填充。",
-            "type": "string"
+          "status": {
+            "type": "string",
+            "enum": [
+              "drafting",
+              "published"
+            ],
+            "description": "复盘状态。`drafting` 草稿中，可继续编辑；`published` 已发布。"
           },
-          "created_at_seconds": {
-            "description": "创建时间戳（秒）。",
-            "format": "int64",
-            "type": "integer"
+          "post_mortem_id": {
+            "type": "string",
+            "description": "复盘报告 ID：由账户 ID 和关联故障 ID 计算出的 32 位十六进制字符串。"
           },
-          "generation": {
-            "description": "协作文档代次。每次正文完整重置（content/reset）+1；存量旧文档为 0。",
-            "format": "int64",
-            "type": "integer"
+          "template_id": {
+            "type": "string",
+            "description": "初始化时使用的模板 ID。"
           },
           "incident_ids": {
-            "description": "关联的故障 ID 列表。",
+            "type": "array",
             "items": {
               "type": "string"
             },
-            "type": "array"
-          },
-          "is_private": {
-            "description": "为 true 时仅团队成员和管理员可查看。",
-            "type": "boolean"
+            "description": "关联的故障 ID 列表。"
           },
           "media_count": {
-            "description": "已上传的媒体文件数量。",
-            "type": "integer"
+            "type": "integer",
+            "description": "已上传的媒体文件数量。"
           },
-          "post_mortem_id": {
-            "description": "按账号和故障 ID 确定性派生的复盘报告 ID。",
-            "type": "string"
+          "author_ids": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "int64"
+            },
+            "description": "贡献过该复盘的成员 ID 列表。"
           },
-          "revision": {
-            "description": "正文乐观并发修订号，全局单调递增；协作保存和正文重置都会使其递增。",
+          "team_id": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "所属团队 ID，为 0 表示无。"
           },
-          "status": {
-            "description": "复盘状态。`drafting` 草稿中，可继续编辑；`published` 已发布。",
-            "enum": [
-              "drafting",
-              "published"
-            ],
-            "type": "string"
+          "channel_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "所属协作空间 ID，为 0 表示无。"
           },
-          "team_id": {
-            "description": "所属团队 ID，为 0 表示无。",
+          "is_private": {
+            "type": "boolean",
+            "description": "为 true 时仅团队成员和管理员可查看。"
+          },
+          "generation": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "协作文档代次。每次正文完整重置（content/reset）+1；存量旧文档为 0。"
           },
-          "template_id": {
-            "description": "初始化时使用的模板 ID。",
-            "type": "string"
+          "revision": {
+            "type": "integer",
+            "format": "int64",
+            "description": "正文乐观并发修订号，全局单调递增；协作保存和正文重置都会使其递增。"
           },
-          "title": {
-            "description": "复盘标题。",
-            "type": "string"
+          "channel_name": {
+            "type": "string",
+            "description": "协作空间名称，由服务端填充。"
+          },
+          "created_at_seconds": {
+            "type": "integer",
+            "format": "int64",
+            "description": "创建时间戳（秒）。"
           },
           "updated_at_seconds": {
-            "description": "最后更新时间戳（秒）。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "最后更新时间戳（秒）。"
           }
-        },
+        }
+      },
+      "PostMortemTemplate": {
+        "type": "object",
+        "description": "故障复盘报告模板。",
         "required": [
           "account_id",
-          "title",
-          "status",
-          "post_mortem_id",
           "template_id",
-          "incident_ids",
-          "media_count",
-          "author_ids",
+          "name",
+          "description",
+          "content",
+          "content_markdown",
           "team_id",
-          "channel_id",
-          "is_private",
-          "generation",
-          "revision",
-          "channel_name",
           "created_at_seconds",
           "updated_at_seconds"
         ],
-        "type": "object"
-      },
-      "PostMortemTemplate": {
-        "description": "故障复盘报告模板。",
         "properties": {
           "account_id": {
-            "description": "模板所属账号 ID。内置模板为 0。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
-          },
-          "content": {
-            "description": "用于初始化复盘正文的 BlockNote JSON 内容。",
-            "type": "string"
+            "description": "模板所属账户 ID；内置模板为 0。"
           },
-          "content_markdown": {
-            "description": "模板内容的 Markdown 版本，供 AI 生成使用。",
-            "type": "string"
+          "template_id": {
+            "type": "string",
+            "description": "模板 ID：内置模板为 `post_mortem_default_tmpl_zh-cn` 或 `post_mortem_default_tmpl_en-us`，自定义模板为服务端生成的 ID。"
           },
-          "created_at_seconds": {
-            "description": "模板创建时间的 Unix 秒级时间戳。",
-            "format": "int64",
-            "type": "integer"
+          "name": {
+            "type": "string",
+            "description": "控制台展示的模板名称。"
           },
           "description": {
-            "description": "模板描述。",
-            "type": "string"
+            "type": "string",
+            "description": "模板描述。"
           },
-          "name": {
-            "description": "控制台展示的模板名称。",
-            "type": "string"
+          "content": {
+            "type": "string",
+            "description": "模板正文，为序列化成字符串的 BlockNote 编辑器 JSON（块数组）。"
+          },
+          "content_markdown": {
+            "type": "string",
+            "description": "模板内容的 Markdown 版本，供 AI 生成使用。"
           },
           "team_id": {
-            "description": "管理团队 ID。内置模板为 0。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "管理团队 ID；内置模板为 0。"
           },
-          "template_id": {
-            "description": "模板 ID。内置模板使用稳定的 `post_mortem_default_tmpl_*` ID。",
-            "type": "string"
+          "created_at_seconds": {
+            "type": "integer",
+            "format": "int64",
+            "description": "创建时间，Unix 秒级时间戳；内置模板为 0。"
           },
           "updated_at_seconds": {
-            "description": "模板最近更新时间的 Unix 秒级时间戳。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "最后更新时间，Unix 秒级时间戳；内置模板为 0。"
           }
-        },
-        "required": [
-          "account_id",
-          "template_id",
-          "name",
-          "description",
-          "content",
-          "content_markdown",
-          "team_id",
-          "created_at_seconds",
-          "updated_at_seconds"
-        ],
-        "type": "object"
+        }
       },
       "PreflightResult": {
+        "type": "object",
         "description": "在允许发起手动运行前计算出的就绪检查结果。",
         "properties": {
-          "app_name": {
-            "description": "规则所属的 App。当前始终为 ai-sre；手动运行目前仅支持该 App。",
-            "type": "string"
+          "ok": {
+            "type": "boolean",
+            "description": "所有就绪检查是否通过。200 响应中恒为 `true`；预检失败时直接返回错误。"
           },
           "checks": {
-            "description": "按执行顺序列出的就绪检查项名称。当前固定为：rule_loaded、actor_authorized、app_allowed、runtime_scope_resolved、rule_config_valid。",
+            "type": "array",
             "items": {
               "type": "string"
             },
-            "type": "array"
-          },
-          "ok": {
-            "description": "全部就绪检查是否通过。凡是能返回给调用者的响应中该值恒为 true——预检失败会直接返回 400/403 错误，而不是 ok=false 的响应体。",
-            "type": "boolean"
-          },
-          "owner_id": {
-            "description": "规则所有者 person ID。",
-            "format": "int64",
-            "type": "integer"
+            "description": "按执行顺序列出的就绪检查项名称。当前固定为：rule_loaded、actor_authorized、app_allowed、runtime_scope_resolved、rule_config_valid。"
           },
           "scope": {
-            "description": "本次运行解析出的作用域，与规则的 run_scope 一致。可选值：`person`（个人规则，以创建者身份运行）、`team`（团队规则，归属团队运行）。",
+            "type": "string",
             "enum": [
               "person",
               "team"
             ],
-            "type": "string"
+            "description": "本次运行解析出的作用域，与规则的 run_scope 一致。可选值：`person`（个人规则，以创建者身份运行）、`team`（团队规则，归属团队运行）。"
+          },
+          "owner_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "规则所有者 person ID。"
           },
           "team_id": {
-            "description": "规则的作用域团队 ID；0 表示个人规则。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "规则的作用域团队 ID；0 表示个人规则。"
+          },
+          "app_name": {
+            "type": "string",
+            "description": "规则所属的 App。当前始终为 ai-sre；手动运行目前仅支持该 App。"
           },
           "warnings": {
-            "description": "预检过程中给出的非致命警告。没有警告时省略或为空数组。",
+            "type": "array",
             "items": {
               "type": "string"
             },
-            "type": "array"
+            "description": "预检给出的非致命警告。当前不会填充，因此不返回该字段。"
           }
         },
         "required": [
@@ -17347,54 +17778,29 @@
           "owner_id",
           "team_id",
           "app_name"
-        ],
-        "type": "object"
-      },
-      "PreviewIncidentCardFixedField": {
-        "description": "已应用隐藏规则后，为受支持 IM 预览返回的固定故障卡片字段。",
-        "properties": {
-          "field": {
-            "description": "故障卡片字段名。\n\n| 值 | 含义 |\n|---|---|\n| `channel` | 触发该故障的告警来源通道名称；仅当通道名非空时返回。 |\n| `snoozed_before` | 故障暂缓（Snooze）截止时间，格式为 `YYYY-MM-DD HH:MM:SS`；仅当故障处于暂缓状态时返回。 |\n| `severity` | 故障等级标签；仅当等级非空时返回。 |\n| `responders` | 当前处理人姓名列表，以空格分隔；仅当存在处理人时返回。 |\n| `aggregate_alert_count` | 聚合到该故障的告警数量；仅当数量大于 1 时返回。 |",
-            "enum": [
-              "channel",
-              "snoozed_before",
-              "severity",
-              "responders",
-              "aggregate_alert_count"
-            ],
-            "type": "string"
-          },
-          "value": {
-            "description": "固定字段的渲染显示值。",
-            "type": "string"
-          }
-        },
-        "required": [
-          "field",
-          "value"
-        ],
-        "type": "object"
+        ]
       },
       "PreviewRemoteConfigRequest": {
         "description": "预览请求。省略 `config` 时预览当前生效配置。",
         "properties": {
           "app_version": {
-            "description": "模拟客户端上报的应用版本。",
+            "description": "模拟客户端上报的应用版本，与规则的 `match.app_version` 精确比较（不支持范围或前缀匹配）。不传表示未上报。",
             "type": "string"
           },
           "application_id": {
-            "description": "RUM 应用 ID。",
+            "description": "RUM 应用 ID，可通过 `POST /rum/application/list` 获取。",
             "type": "string"
           },
           "config": {
-            "$ref": "#/components/schemas/RemoteConfig"
+            "$ref": "#/components/schemas/RemoteConfig",
+            "description": "要评估的草稿配置，按 `POST /rum/application/remote-config/update` 的规则校验。不传则评估线上配置。"
           },
           "env": {
-            "description": "模拟客户端上报的环境。",
+            "description": "模拟客户端上报的环境，与规则的 `match.env` 精确比较。不传表示未上报，依赖 `env` 的规则不会命中。",
             "type": "string"
           },
           "sdk": {
-            "description": "模拟客户端上报的 SDK 名称与版本，如 `web@2.4.1`。",
+            "description": "模拟客户端上报的 SDK 标识，例如 `web@2.4.1`，与规则的 `match.sdk` 精确比较。不传表示未上报。",
             "type": "string"
           }
         },
@@ -17407,173 +17813,348 @@
         "description": "模拟客户端将拿到的配置值。",
         "properties": {
           "hit_rule_index": {
-            "description": "决定结果的规则下标（从 0 开始）；仅命中默认值时为 -1。",
+            "description": "第一个命中规则在 `config.rules` 中的下标（从 0 开始）；没有规则命中（只用了 `default`）或配置已关闭/不存在时为 `-1`。",
             "type": "integer"
           },
           "values": {
-            "$ref": "#/components/schemas/RemoteConfigValues"
+            "$ref": "#/components/schemas/RemoteConfigValues",
+            "description": "`default` 与命中规则 `set` 合并后的结果。两者都未设置的字段会被省略；空对象表示客户端保留全部初始化参数。"
           }
         },
-        "type": "object"
+        "type": "object",
+        "required": [
+          "values",
+          "hit_rule_index"
+        ]
       },
       "PreviewTemplateRequest": {
-        "description": "模板预览请求。",
+        "type": "object",
         "properties": {
           "content": {
-            "description": "要渲染的模板内容。",
-            "type": "string"
+            "type": "string",
+            "description": "按通道 `type` 渲染的模板内容。为空或不传时预览该通道的内置预设内容；`push` 类型忽略此字段。"
           },
-          "feishu_app_card_v2_enabled": {
-            "type": "boolean",
-            "description": "按飞书应用卡片 v2 消息渲染预览。"
+          "type": {
+            "type": "string",
+            "description": "要预览的通道，其他取值返回 `InvalidParameter`。\n- `email`：邮件正文（HTML 模板）。\n- `sms`、`voice`：短信文本和语音电话话术。\n- `push`：移动 App 推送（内容固定，忽略 `content`）。\n- `dingtalk`、`wecom`、`feishu`、`zoom`、`telegram`、`slack`：机器人（Webhook）消息。\n- `feishu_app`、`dingtalk_app`、`wecom_app`、`slack_app`、`teams_app`：IM 应用卡片。",
+            "enum": [
+              "email",
+              "sms",
+              "voice",
+              "push",
+              "dingtalk",
+              "wecom",
+              "feishu",
+              "zoom",
+              "telegram",
+              "slack",
+              "feishu_app",
+              "dingtalk_app",
+              "wecom_app",
+              "slack_app",
+              "teams_app"
+            ]
           },
-          "feishu_app_card_v2_preserve_blank_lines": {
-            "type": "boolean",
-            "description": "飞书应用卡片 v2 预览保留正文中的空行。"
+          "incident_id": {
+            "type": "string",
+            "description": "用于渲染的故障 ID（24 位十六进制，可通过 `/incident/list` 获取），须为账户内存在的故障，否则返回 `InvalidParameter`。不传时使用模拟故障。",
+            "pattern": "^[0-9a-fA-F]{24}$"
           },
           "incident_card_hidden_fields": {
             "$ref": "#/components/schemas/IncidentCardHiddenFields",
             "description": "预览时按 IM 应用隐藏的故障卡片字段。"
           },
-          "incident_id": {
-            "description": "用于渲染模板的故障 ID，省略时使用模拟数据。MongoDB ObjectID 十六进制字符串。",
-            "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
+          "feishu_app_card_v2_table_enabled": {
+            "type": "boolean",
+            "default": false,
+            "description": "将 `feishu_app` 内容中的 Markdown 表格渲染为飞书卡片原生表格，与模板的同名设置一致。"
           },
-          "type": {
-            "description": "模板渠道类型，用于选择渲染引擎。`email` 按 Go html/template 渲染，其他渠道按 text/template 渲染。取值与模板渠道字段一致，如 `email`、`sms`、`voice`、`dingtalk`、`wecom`、`feishu`、`feishu_app`、`dingtalk_app`、`wecom_app`、`slack_app`、`teams_app`、`telegram`、`slack`、`zoom`。",
-            "type": "string"
+          "feishu_app_card_v2_preserve_blank_lines": {
+            "type": "boolean",
+            "description": "飞书应用卡片 v2 预览保留正文中的空行。"
+          },
+          "wecom_markdown_v2_enabled": {
+            "type": "boolean",
+            "default": false,
+            "description": "按 `markdown_v2` 消息预览 `wecom` 内容，与模板的同名设置一致（大小上限 4,096 字节）。"
           }
         },
         "required": [
-          "content",
           "type"
         ],
-        "type": "object"
+        "description": "模板预览请求。"
       },
       "PreviewTemplateResponse": {
-        "description": "模板预览结果。",
+        "type": "object",
         "properties": {
+          "success": {
+            "type": "boolean",
+            "description": "模板是否渲染成功。"
+          },
           "content": {
-            "description": "渲染后的模板输出，success 为 true 时返回。",
-            "type": "string"
+            "type": "string",
+            "description": "渲染后的模板内容；`success` 为 `false` 时为空字符串。"
           },
-          "fixed_fields": {
-            "description": "已应用隐藏规则后，为受支持 IM 预览返回的固定故障卡片字段。",
+          "message": {
+            "type": "string",
+            "description": "渲染失败的原因（调用方语言）；`success` 为 `true` 时为空字符串。"
+          },
+          "card": {
+            "type": "object",
+            "description": "渲染结果外层的消息框架，使用账户语言。仅 `email`、`feishu_app`、`dingtalk_app`、`wecom_app`、`slack_app`、`teams_app` 返回，其他类型省略。",
+            "required": [
+              "title",
+              "elements"
+            ],
+            "properties": {
+              "title": {
+                "type": "string",
+                "description": "邮件主题或卡片标题。"
+              },
+              "elements": {
+                "type": "array",
+                "description": "按显示顺序排列的卡片元素。",
+                "items": {
+                  "type": "object",
+                  "required": [
+                    "type"
+                  ],
+                  "properties": {
+                    "type": {
+                      "type": "string",
+                      "enum": [
+                        "template",
+                        "markdown",
+                        "divider",
+                        "actions"
+                      ],
+                      "description": "元素类型。\n- `template`：渲染后的模板（`content`）所在位置。\n- `markdown`：通道 Markdown 格式的固定文本，见 `content`。\n- `divider`：分隔线。\n- `actions`：一排按钮，见 `actions`。"
+                    },
+                    "content": {
+                      "type": "string",
+                      "description": "`markdown` 元素的文本；其他类型省略。"
+                    },
+                    "actions": {
+                      "type": "array",
+                      "description": "`actions` 元素的按钮；其他类型省略。",
+                      "items": {
+                        "type": "object",
+                        "required": [
+                          "text"
+                        ],
+                        "properties": {
+                          "text": {
+                            "type": "string",
+                            "description": "按钮文字。"
+                          },
+                          "style": {
+                            "type": "string",
+                            "enum": [
+                              "primary",
+                              "danger",
+                              "select"
+                            ],
+                            "description": "按钮样式：`primary`（主按钮）、`danger`（危险操作）、`select`（下拉菜单）。普通按钮省略。"
+                          }
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "blocks": {
+            "type": "array",
+            "description": "收件端如何展示 `content`，按块拆分。对原样显示文本的通道省略。",
             "items": {
-              "$ref": "#/components/schemas/PreviewIncidentCardFixedField"
-            },
-            "type": "array"
+              "type": "object",
+              "required": [
+                "type"
+              ],
+              "properties": {
+                "type": {
+                  "type": "string",
+                  "enum": [
+                    "markdown",
+                    "table"
+                  ],
+                  "description": "块类型：`markdown`（文本，见 `content`）或 `table`（表格，见 `columns`/`rows`）。"
+                },
+                "content": {
+                  "type": "string",
+                  "description": "`markdown` 块的文本。"
+                },
+                "native": {
+                  "type": "boolean",
+                  "description": "`table` 块以卡片原生表格展示时为 `true`，否则省略。"
+                },
+                "columns": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  },
+                  "description": "`table` 块的列名。"
+                },
+                "rows": {
+                  "type": "array",
+                  "items": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    }
+                  },
+                  "description": "`table` 块的单元格值，每行一个数组。"
+                },
+                "page_size": {
+                  "type": "integer",
+                  "description": "原生表格每页显示的行数；未设置时省略。"
+                }
+              }
+            }
           },
-          "message": {
-            "description": "渲染失败的错误说明，success 为 false 时返回。",
-            "type": "string"
+          "notices": {
+            "type": "array",
+            "description": "关于内容实际投递方式的提示；没有时省略。",
+            "items": {
+              "type": "object",
+              "required": [
+                "code"
+              ],
+              "properties": {
+                "code": {
+                  "type": "string",
+                  "enum": [
+                    "table_not_rendered",
+                    "native_table_fallback",
+                    "content_too_large"
+                  ],
+                  "description": "提示类型。\n- `table_not_rendered`：该通道不支持 Markdown 表格，表格按文本发送。\n- `native_table_fallback`：表格无法渲染为卡片原生表格，改用 Markdown 发送；`reason` 说明原因（`too_many_tables`、`too_many_columns`、`too_many_rows`、`cell_too_long`、`unsupported_cell`、`card_too_large`）。\n- `content_too_large`：内容超过 `size_limit_bytes`；`reason` 为 `truncated`（截断后发送）、`compact_fallback`（改用精简格式发送）或 `rejected`（通道会拒收）。"
+                },
+                "reason": {
+                  "type": "string",
+                  "description": "`code` 的具体原因，取值见 `code` 说明；`table_not_rendered` 时省略。"
+                }
+              }
+            }
           },
-          "success": {
-            "description": "模板是否渲染成功。",
-            "type": "boolean"
+          "size_bytes": {
+            "type": "integer",
+            "description": "渲染结果的字节数，在任何截断之前统计。"
+          },
+          "size_limit_bytes": {
+            "type": "integer",
+            "description": "通道的大小上限（字节）：机器人通道（以及未开启 `markdown_v2` 的 `wecom`）为 4,000，开启 `markdown_v2` 的 `wecom` 为 4,096，`slack_app` 为 15,000，`feishu_app` 为 30,720；无上限的通道为 `0`。"
           }
         },
         "required": [
           "success",
           "content",
-          "message"
+          "message",
+          "size_bytes",
+          "size_limit_bytes"
         ],
-        "type": "object"
+        "description": "模板预览结果。"
       },
       "PublishedArtifactItem": {
+        "type": "object",
         "description": "产物库中的一个已发布产物。时间字段均为 Unix 毫秒时间戳。",
         "properties": {
           "artifact_id": {
-            "description": "产物 ID（`art_` 前缀）。同时也是公开分享链接的标识。",
-            "type": "string"
+            "type": "string",
+            "description": "产物 ID（`art_` 前缀）。同时也是公开分享链接的标识。"
           },
-          "can_edit": {
-            "description": "调用者是否可管理该产物（重命名、转移、删除、分享）：创建者、归属团队任一成员、或来源会话的管理者。",
-            "type": "boolean"
+          "title": {
+            "type": "string",
+            "description": "产物在产物库中的展示标题。"
           },
-          "content_type": {
-            "description": "文件的 MIME 类型。",
-            "type": "string"
+          "team_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "归属空间。`0` 表示个人产物：只出现在创建者的列表中，可由创建者或能管理来源会话的成员管理。大于 0 时为归属团队 ID：出现在该团队成员的列表中，团队任一成员都可管理。首次发布时取自来源会话，可通过 `/safari/artifact/gallery/update` 修改。"
           },
-          "created_at": {
-            "description": "产物发布的 Unix 毫秒时间戳。",
+          "team_name": {
+            "type": "string",
+            "description": "归属团队的名称。个人产物不返回该字段。"
+          },
+          "person_id": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "产物创建者的成员 ID，即首次发布时来源会话的所有者。重新发布或转移空间都不会改变它。"
           },
           "creator_name": {
-            "description": "创建者的显示名称。",
-            "type": "string"
-          },
-          "file_id": {
-            "description": "当前承载产物内容的文件 ID（`pf_` 前缀）。每次重新发布都会变化。",
-            "type": "string"
+            "type": "string",
+            "description": "创建者的显示名称。"
           },
           "is_mine": {
-            "description": "调用者是否为创建者。",
-            "type": "boolean"
-          },
-          "name": {
-            "description": "底层文件名（含扩展名）。",
-            "type": "string"
-          },
-          "person_id": {
-            "description": "创建者的成员 ID。",
-            "format": "int64",
-            "type": "integer"
+            "type": "boolean",
+            "description": "调用者（`app_key` 调用时为 key 所属成员）是创建者时为 `true`，即 `person_id` 等于调用者的成员 ID。"
           },
-          "public_url": {
-            "description": "匿名公开链接 —— 由 CDN 承载的控制台 `/share/artifact/<artifact_id>` 页面。仅在分享开启时返回；任何拿到链接的人无需登录即可查看。",
-            "type": "string"
+          "can_edit": {
+            "type": "boolean",
+            "description": "调用者是否可管理该产物（重命名、转移、删除、分享）：创建者、归属团队任一成员、或来源会话的管理者。"
           },
           "session_id": {
-            "description": "产出该文件的来源会话 ID（`sess_` 前缀）。",
-            "type": "string"
+            "type": "string",
+            "description": "产出该文件的来源会话 ID（`sess_` 前缀）。"
           },
           "session_title": {
-            "description": "来源会话的标题。会话已删除时不返回该字段。",
-            "type": "string"
+            "type": "string",
+            "description": "来源会话的标题。会话已删除时不返回该字段。"
           },
-          "share_enabled": {
-            "description": "是否已开启匿名公开分享。为 false 时不返回该字段。",
-            "type": "boolean"
+          "file_id": {
+            "type": "string",
+            "description": "当前承载产物内容的文件 ID（`pf_` 前缀）。每次重新发布都会变化。"
           },
-          "share_file_id": {
-            "description": "公开快照所基于的文件 ID。当 `share_enabled` 为 true 且 `file_id` 与 `share_file_id` 不一致时，公开快照已过期 —— 调用 `/safari/artifact/gallery/share/sync` 刷新。",
-            "type": "string"
+          "name": {
+            "type": "string",
+            "description": "底层文件名（含扩展名）。底层文件记录缺失时为空字符串。"
           },
-          "shared_at": {
-            "description": "最近一次开启分享或更新快照的 Unix 毫秒时间戳。仅在分享开启时返回。",
+          "size": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "文件大小，单位字节。"
           },
-          "shared_by": {
-            "description": "开启分享的成员 ID。仅在分享开启时返回。",
+          "content_type": {
+            "type": "string",
+            "description": "MIME 类型，在文件产出时按文件扩展名推断：`text/html`（.html/.htm）、`text/markdown`（.md）、`text/plain`（.txt/.log）、`text/csv`、`text/yaml`（.yaml/.yml）、`text/x-python`、`text/x-go`、`text/x-sh`、`application/json`、`application/xml`、`application/pdf`、`image/png`、`image/jpeg`、`image/gif`、`image/svg+xml`、`image/webp`、`application/zip`、`application/gzip`（.tar/.gz/.tgz）；其他扩展名为 `application/octet-stream`。底层文件记录缺失时为空字符串。"
+          },
+          "created_at": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "产物发布的 Unix 毫秒时间戳。"
           },
-          "size": {
-            "description": "文件大小，单位字节。",
+          "updated_at": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "产物记录最近一次变更（重命名、转移、重新发布或分享状态变化）的 Unix 毫秒时间戳。"
           },
-          "team_id": {
-            "description": "归属团队 ID。`0` 表示个人产物（仅创建者可管理）；大于 0 表示团队产物。",
+          "pinned_at": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "调用者在控制台产物库中置顶该产物的 Unix 毫秒时间戳。置顶按成员各自记录；调用者未置顶时不返回该字段。置顶的产物在 `/safari/artifact/gallery/list` 中排在最前。"
           },
-          "team_name": {
-            "description": "归属团队的名称。个人产物不返回该字段。",
-            "type": "string"
+          "share_enabled": {
+            "type": "boolean",
+            "description": "是否已开启匿名公开分享。为 false 时不返回该字段。"
           },
-          "title": {
-            "description": "产物在产物库中的展示标题。",
-            "type": "string"
+          "public_url": {
+            "type": "string",
+            "description": "匿名公开链接 —— 由 CDN 承载的控制台 `/share/artifact/<artifact_id>` 页面。仅在分享开启时返回；任何拿到链接的人无需登录即可查看。"
           },
-          "updated_at": {
-            "description": "产物最近一次更新（重命名、转移或重新发布）的 Unix 毫秒时间戳。",
+          "shared_by": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "开启分享的成员 ID；之后同步快照不会改变它。仅在分享开启时返回。"
+          },
+          "shared_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "最近一次开启分享或更新快照的 Unix 毫秒时间戳。仅在分享开启时返回。"
+          },
+          "share_file_id": {
+            "type": "string",
+            "description": "公开快照所基于的文件 ID。当 `share_enabled` 为 true 且 `file_id` 与 `share_file_id` 不一致时，公开快照已过期 —— 调用 `/safari/artifact/gallery/share/sync` 刷新。"
           }
         },
         "required": [
@@ -17591,16 +18172,15 @@
           "content_type",
           "created_at",
           "updated_at"
-        ],
-        "type": "object"
+        ]
       },
       "QueryDataRequest": {
+        "description": "结构化查询接口的请求体。",
         "allOf": [
           {
             "$ref": "#/components/schemas/QueryRowsRequest"
           }
-        ],
-        "description": "稳定结构化查询接口的请求。字段与已下线的 rows 接口一致。"
+        ]
       },
       "QueryDataResponse": {
         "description": "与 Edge 版本无关的稳定结构化查询响应。",
@@ -17772,43 +18352,59 @@
         ]
       },
       "QueryRowsRequest": {
+        "type": "object",
+        "required": [
+          "ds_type",
+          "ds_name",
+          "expr"
+        ],
         "properties": {
           "account_id": {
-            "description": "可选的一致性校验。若提供,必须等于已认证账户;不一致将被拒绝。业务执行始终使用已认证账户。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "可选的一致性校验。若提供，必须等于已认证账户，否则请求以 `AccessDenied` 失败。查询始终以已认证账户执行。"
           },
-          "args": {
-            "additionalProperties": {
-              "type": "string"
-            },
-            "description": "透传给 monit-edge 的多态键值扩展参数。所有值必须是字符串，键一律按数据源加前缀（如 `sls.project`、`loki.type`）。校验规则取决于 `ds_type`：SLS 必须提供 `sls.project` 与 `sls.logstore`；Elasticsearch 的 `es.type` 只接受 `sql` 或不传，其他值一律拒绝；Loki 与 VictoriaLogs 的 `<source>.type` 接受 `stats`、`raw` 或不传，其中 `raw` 还必须给出时间范围——`<source>.start` + `<source>.end`，或 `<source>.timespan.value` + `<source>.timespan.unit`（单位取 `s`/`m`/`h`/`d`）。Prometheus 及其余 SQL 类数据源完全忽略 `args`。",
-            "type": "object"
-          },
-          "delay_seconds": {
-            "default": 0,
-            "description": "应用于点查询(Prometheus、Loki stats、VictoriaLogs stats)的回看偏移,单位秒。明细 / raw 查询忽略该字段。",
-            "type": "integer"
+          "ds_type": {
+            "type": "string",
+            "description": "数据源类型，需要与 `ds_name` 一起匹配账户下一个已启用的数据源。\n\n- `prometheus`：Prometheus 兼容数据源，`expr` 为 PromQL。\n- `loki`：Grafana Loki，`expr` 为 LogQL。\n- `victorialogs`：VictoriaLogs。\n- `sls`：阿里云日志服务（SLS）。\n- `tencent_cls`：腾讯云日志服务（CLS），需要 monit-edge v0.66.0 或更高版本。\n- `elasticsearch`：Elasticsearch。\n- `mysql`：MySQL，`expr` 为 SQL。\n- `postgres`：PostgreSQL，`expr` 为 SQL。\n- `oracle`：Oracle 数据库，`expr` 为 SQL。\n- `clickhouse`：ClickHouse，`expr` 为 SQL。\n\n其他数据源类型（例如 MongoDB、Redis、Kafka）会被拒绝。",
+            "enum": [
+              "clickhouse",
+              "elasticsearch",
+              "loki",
+              "mysql",
+              "oracle",
+              "postgres",
+              "prometheus",
+              "sls",
+              "tencent_cls",
+              "victorialogs"
+            ]
           },
           "ds_name": {
-            "description": "数据源名称;必须匹配租户下已配置的数据源。",
-            "type": "string"
-          },
-          "ds_type": {
-            "description": "数据源类型;必须匹配租户下已配置的数据源。示例:`prometheus`、`loki`、`victorialogs`、`sls`、`elasticsearch`、`mysql`、`postgres`、`oracle`、`clickhouse`。",
-            "type": "string"
+            "type": "string",
+            "description": "数据源名称，可从 `/monit/datasource/list` 获取。数据源必须已启用；账户下不存在该名称的数据源时返回 HTTP 400。"
           },
           "expr": {
-            "description": "查询表达式。语法取决于 `ds_type`,由对应的 monit-edge 客户端解释(Prometheus 用 PromQL,Loki 用 LogQL,SQL 类数据源用 SQL,等等)。",
-            "type": "string"
+            "type": "string",
+            "description": "使用 `ds_type` 对应查询语言的表达式（`prometheus` 为 PromQL，`loki` 为 LogQL，SQL 类数据源为 SQL，等等）。必填，最大 64 KiB（`tencent_cls` 为 12 KiB）。此接口不支持 Loki 的 `$__auto`，请使用固定时长，例如 `[5m]`。Prometheus 表达式在下发前会做语法检查。",
+            "minLength": 1
+          },
+          "delay_seconds": {
+            "type": "integer",
+            "description": "回看偏移，单位秒，取值 0 到 86400。应用于点查询（Prometheus、Loki stats、VictoriaLogs stats）；明细 / raw 查询忽略该字段。当 `args` 带有绝对时间 `<source>.time` 且 Edge 为 v0.74.0 或更高版本时，以绝对时间为准，不再应用此偏移。",
+            "default": 0,
+            "minimum": 0,
+            "maximum": 86400
+          },
+          "args": {
+            "type": "object",
+            "description": "额外的查询参数，字符串键值对；键按数据源加前缀（例如 `sls.project`、`loki.type`）。最多 128 项，键最长 256 字节，值最长 64 KiB，总计不超过 128 KiB。可接受的参数取决于 `ds_type`：\n\n- `prometheus`：可选 `prometheus.time`，评估时间，Unix 秒，不能晚于当前时间。\n- `loki`、`victorialogs`：`<source>.type` 取 `stats`（默认）或 `raw`。`stats` 可带 `<source>.time`（Unix 秒，不能晚于当前时间）。`raw` 必须给出时间范围，可用 `<source>.start` + `<source>.end`（Unix 秒），或 `<source>.timespan.value` + `<source>.timespan.unit`（`s`、`m`、`h` 或 `d`），跨度不超过 6 小时，并可带 `<source>.limit`，取值 1 到 1001。\n- `sls`：必须提供 `sls.project` 和 `sls.logstore`。可选 `sls.lines`（1 到 100）、`sls.offset`（0 或更大），以及不超过 6 小时的时间范围，可用 `sls.from` + `sls.to`（Unix 秒）或 `sls.timespan.value` + `sls.timespan.unit` 给出。\n- `tencent_cls`：必须提供 `tencent_cls.region`、`tencent_cls.topic_id`、`tencent_cls.query_mode`（`raw` 或 `analysis`）和 `tencent_cls.syntax`（`cql` 或 `lucene`）。可选 `tencent_cls.limit`（1 到 100，仅 `raw` 模式，需要 monit-edge v0.67.0 或更高版本），以及时间范围，可用 `tencent_cls.from` + `tencent_cls.to`（Unix 秒）或 `tencent_cls.timespan.value` + `tencent_cls.timespan.unit` 给出，`raw` 模式不超过 6 小时，`analysis` 模式不超过 24 小时。其他任何键都会被拒绝。\n- `elasticsearch`：`es.type` 只能为 `sql` 或不传，其他值会被拒绝。\n- `mysql`、`postgres`、`oracle`、`clickhouse`：未定义任何参数。\n\n绝对时间 `<source>.time` 只对其对应的数据源类型有效。v0.74.0 之前的 Edge 通过回看偏移近似实现，且只接受最近 86,400 秒内的时间。",
+            "additionalProperties": {
+              "type": "string"
+            }
           }
         },
-        "required": [
-          "ds_type",
-          "ds_name",
-          "expr"
-        ],
-        "type": "object"
+        "description": "要执行的查询。`ds_type` 与 `ds_name` 共同选定数据源；`expr` 与 `args` 由该类型的数据源解释。"
       },
       "QuerySample": {
         "properties": {
@@ -17878,29 +18474,35 @@
             "type": "string"
           },
           "custom": {
-            "additionalProperties": {},
-            "description": "应用自定义的透传值，原样下发给宿主应用。最多 5 个键，键长不超过 64 字节，单值不超过 4 KB JSON 且嵌套不超过 3 层，总计不超过 16 KB。持有公开 client token 的任何人都能读到它。",
+            "additionalProperties": {
+              "description": "任意 JSON 值：字符串、数字、布尔、数组或对象。"
+            },
+            "description": "SDK 原样交给宿主应用的自由键值对，平台不解析其内容。最多 5 个键，每个键 1–64 字节，每个值为合法 JSON、不超过 4 KB 且嵌套不超过 3 层，总计不超过 16 KB。持有公开 client token 的任何人都能读到它。为空时响应中省略。",
             "maxProperties": 5,
             "type": "object"
           },
           "default": {
-            "$ref": "#/components/schemas/RemoteConfigValues"
+            "$ref": "#/components/schemas/RemoteConfigValues",
+            "description": "所有客户端都会收到的值，命中的规则可覆盖其中的字段。"
           },
           "enabled": {
-            "description": "总开关。为 false 时引擎不下发任何值，SDK 沿用初始化值。",
+            "description": "总开关。为 `false` 时 SDK 配置下发端不返回任何值，SDK 回退到初始化参数；`default` 和 `rules` 仍会保留。不传时视为 `false`。",
             "type": "boolean"
           },
           "refresh_on_foreground": {
-            "description": "允许客户端回到前台时重新拉取配置，而不是等待下一次轮询。",
+            "description": "为 `true` 时，客户端回到前台时会重新拉取配置，而不是等待下一次轮询。默认 `false`；为 `false` 时响应中省略。",
             "type": "boolean"
           },
           "rules": {
-            "description": "定向规则，按顺序评估；每个应用最多 20 条。",
+            "description": "定向规则，按顺序评估，第一条命中的规则生效。最多 20 条。保存时未带规则则可能为 `null`。",
             "items": {
               "$ref": "#/components/schemas/RemoteConfigRule"
             },
             "maxItems": 20,
-            "type": "array"
+            "type": [
+              "array",
+              "null"
+            ]
           }
         },
         "type": "object"
@@ -17909,18 +18511,19 @@
         "description": "一个已发布的远程配置版本。",
         "properties": {
           "config": {
-            "$ref": "#/components/schemas/RemoteConfig"
+            "$ref": "#/components/schemas/RemoteConfig",
+            "description": "该版本生效的配置内容。"
           },
           "content_hash": {
-            "description": "配置内容的哈希；控制台用它识别内容相同的版本。",
+            "description": "所存配置的指纹：SHA-256 的前 16 位十六进制字符。哈希相同的版本内容完全相同。较早的版本可能为空。",
             "type": "string"
           },
           "equivalent_to": {
-            "description": "与本版本内容相同的最早版本号（当不是本版本自身时返回）。",
+            "description": "具有相同 `content_hash` 的最早保留版本，例如回滚所恢复的版本。本版本自身就是最早版本时省略。",
             "type": "integer"
           },
           "reason": {
-            "description": "发布该版本时操作者留下的说明，未填写则为空。",
+            "description": "发布或回滚时通过 `reason` 填写的自由文本备注（非枚举）；未填写时为 `\"\"`。",
             "type": "string"
           },
           "updated_at": {
@@ -17934,7 +18537,7 @@
             "type": "integer"
           },
           "updated_by_name": {
-            "description": "发布该版本的成员名称。",
+            "description": "发布该版本的成员在发布时的名称，最多保留 128 个字符。",
             "type": "string"
           },
           "version": {
@@ -17942,18 +18545,35 @@
             "type": "integer"
           }
         },
-        "type": "object"
+        "type": "object",
+        "required": [
+          "config",
+          "version",
+          "content_hash",
+          "reason",
+          "updated_by",
+          "updated_by_name",
+          "updated_at"
+        ]
       },
       "RemoteConfigRule": {
-        "description": "单条定向规则：当 `match` 条件满足时，`set` 覆盖 `default`。规则按顺序评估，第一条命中的规则生效——规则顺序即优先级。",
+        "description": "单条定向规则：`match` 的所有条件都满足时，`set` 覆盖 `default`。第一条命中的规则生效并停止评估，规则顺序即优先级。`set` 至少要设置一个值。",
         "properties": {
           "match": {
             "additionalProperties": {
               "maxLength": 256,
+              "minLength": 1,
               "type": "string"
             },
-            "description": "SDK 配置请求必须相等的键值对。键仅支持 `env`、`app_version`、`sdk`；值最长 256 字节。",
+            "description": "针对 SDK 配置请求上报内容的条件，各条件之间为“与”关系，按字符串精确比较。键仅支持 `env`、`app_version`、`sdk`；值为 1–256 字节。SDK 未上报的键一定不命中。",
             "minProperties": 1,
+            "propertyNames": {
+              "enum": [
+                "env",
+                "app_version",
+                "sdk"
+              ]
+            },
             "type": "object"
           },
           "set": {
@@ -17970,7 +18590,7 @@
         "description": "配置可设置的 SDK 参数。每个字段都是可选的：规则与默认值都未设置的字段不会出现在 SDK 响应中，SDK 将沿用初始化值。",
         "properties": {
           "defaultPrivacyLevel": {
-            "description": "Session Replay 默认的页面脱敏方式。",
+            "description": "Session Replay 默认的页面脱敏方式：\n\n- `mask`：替换页面文本并隐藏输入值。\n- `mask-user-input`：保留页面文本，只隐藏用户输入的内容。\n- `allow`：按原样录制页面；已上传的内容无法事后脱敏。",
             "enum": [
               "mask",
               "mask-user-input",
@@ -17996,7 +18616,7 @@
             ]
           },
           "sessionReplaySampleRate": {
-            "description": "Session Replay 采样率（0-100）。",
+            "description": "录制 Session Replay 的会话比例，百分比（0–100）。",
             "maximum": 100,
             "minimum": 0,
             "type": [
@@ -18005,7 +18625,7 @@
             ]
           },
           "sessionSampleRate": {
-            "description": "会话采样率（0-100）。",
+            "description": "会话采集比例，百分比（0–100）。",
             "maximum": 100,
             "minimum": 0,
             "type": [
@@ -18014,7 +18634,7 @@
             ]
           },
           "traceSampleRate": {
-            "description": "Trace 采样率（0-100）：哪些会话会在请求中注入 Trace 头。",
+            "description": "向请求注入链路头的会话比例，百分比（0–100）。按会话决定：一个会话要么全部请求都带链路头，要么都不带。",
             "maximum": 100,
             "minimum": 0,
             "type": [
@@ -18045,28 +18665,28 @@
         "type": "object"
       },
       "ReopenIncidentRequest": {
+        "type": "object",
         "description": "重新打开故障的参数。",
+        "required": [
+          "incident_ids"
+        ],
         "properties": {
           "incident_ids": {
-            "description": "待重开的故障 ID 列表，单次最多 100 条。",
+            "type": "array",
             "items": {
-              "pattern": "^[0-9a-fA-F]{24}$",
-              "type": "string"
+              "type": "string",
+              "pattern": "^[0-9a-fA-F]{24}$"
             },
             "maxItems": 100,
-            "minItems": 1,
-            "type": "array"
+            "description": "待重开的故障 ID 列表，单次最多 100 条。",
+            "minItems": 1
           },
           "reason": {
-            "description": "可选，记录到时间线的重开原因。",
+            "type": "string",
             "maxLength": 1024,
-            "type": "string"
+            "description": "可选的重开原因（自由文本），会记录在 `i_reopen` 时间线条目中。最多 1,024 个字符。"
           }
-        },
-        "required": [
-          "incident_ids"
-        ],
-        "type": "object"
+        }
       },
       "ReorderIncidentCommentTypesRequest": {
         "description": "调整评论类型顺序的参数。",
@@ -18087,77 +18707,77 @@
         "type": "object"
       },
       "ResetIncidentFieldRequest": {
+        "type": "object",
         "description": "更新故障自定义字段值的参数。",
+        "required": [
+          "incident_id",
+          "field_name"
+        ],
         "properties": {
+          "incident_id": {
+            "type": "string",
+            "pattern": "^[0-9a-fA-F]{24}$",
+            "description": "故障 ID（MongoDB ObjectID）。"
+          },
           "field_name": {
-            "description": "自定义字段名称，必须与账号下定义的字段匹配。",
-            "type": "string"
+            "type": "string",
+            "description": "自定义字段名（字段的 `field_name`，而非显示名称）。字段必须存在且处于启用状态；可通过 `POST /field/list` 查询。"
           },
           "field_value": {
-            "description": "字段新值，类型需与字段定义一致。"
-          },
-          "incident_id": {
-            "description": "故障 ID（MongoDB ObjectID）。",
-            "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
+            "description": "新值，类型须与字段匹配：`checkbox` 传布尔值，`single_select` 传一个选项，`multi_select` 传选项数组，`text` 传字符串。省略或传 `null` 表示清空该字段。"
           }
-        },
-        "required": [
-          "incident_id",
-          "field_name"
-        ],
-        "type": "object"
+        }
       },
       "ResetPostMortemBasicsRequest": {
+        "type": "object",
         "description": "写回复盘报告的故障基础信息。",
+        "required": [
+          "post_mortem_id",
+          "incidents_highest_severity",
+          "incidents_earliest_start_seconds"
+        ],
         "properties": {
-          "incidents_earliest_start_seconds": {
-            "description": "最早关联故障开始时间的 Unix 秒级时间戳。",
-            "format": "int64",
-            "minimum": 1,
-            "type": "integer"
+          "post_mortem_id": {
+            "type": "string",
+            "description": "复盘 ID，可通过 `POST /incident/post-mortem/list` 获取。"
           },
           "incidents_highest_severity": {
-            "description": "关联故障中的最高严重级别：`Critical`、`Warning`、`Info` 或 `Ok`。",
+            "type": "string",
+            "description": "关联故障中的最高严重程度。\n- `Critical`：严重。\n- `Warning`：警告。\n- `Info`：提醒。\n- `Ok`：已恢复。",
             "enum": [
               "Critical",
               "Warning",
               "Info",
               "Ok"
-            ],
-            "type": "string"
+            ]
+          },
+          "incidents_earliest_start_seconds": {
+            "type": "integer",
+            "format": "int64",
+            "minimum": 1,
+            "description": "最早关联故障开始时间的 Unix 秒级时间戳。"
           },
           "incidents_latest_close_seconds": {
-            "description": "最晚关联故障关闭时间的 Unix 秒级时间戳；仍未关闭时为 0。",
+            "type": "integer",
             "format": "int64",
             "minimum": 0,
-            "type": "integer"
+            "description": "关联故障中最晚的关闭时间，Unix 秒级时间戳。0（省略时也为 0）表示尚未关闭。"
           },
           "incidents_total_duration_seconds": {
-            "description": "故障总持续时间，单位秒。",
+            "type": "integer",
             "format": "int64",
             "minimum": 0,
-            "type": "integer"
-          },
-          "post_mortem_id": {
-            "description": "复盘 ID，可通过 `POST /incident/post-mortem/list` 获取。",
-            "type": "string"
+            "description": "故障总时长（秒）；省略时为 0。"
           },
           "responder_ids": {
-            "description": "写入报告的响应人成员 ID。",
+            "type": "array",
             "items": {
-              "format": "int64",
-              "type": "integer"
+              "type": "integer",
+              "format": "int64"
             },
-            "type": "array"
+            "description": "作为报告处理人员保存的成员 ID。会替换已保存的列表；省略或传 `[]` 表示清空。无法解析为人员的 ID 会被丢弃。"
           }
-        },
-        "required": [
-          "post_mortem_id",
-          "incidents_highest_severity",
-          "incidents_earliest_start_seconds"
-        ],
-        "type": "object"
+        }
       },
       "ResetPostMortemContentRequest": {
         "description": "完整替换草稿状态故障复盘正文的参数。",
@@ -18195,72 +18815,88 @@
         "type": "object"
       },
       "ResetPostMortemFollowUpsRequest": {
+        "type": "object",
         "description": "替换复盘后续行动项的参数。",
-        "properties": {
-          "follow_ups": {
-            "description": "自由文本格式的后续行动项。",
-            "type": "string"
-          },
-          "post_mortem_id": {
-            "description": "复盘 ID，可通过 `POST /incident/post-mortem/list` 获取。",
-            "type": "string"
-          }
-        },
         "required": [
           "post_mortem_id"
         ],
-        "type": "object"
+        "properties": {
+          "post_mortem_id": {
+            "type": "string",
+            "description": "复盘 ID，可通过 `POST /incident/post-mortem/list` 获取。"
+          },
+          "follow_ups": {
+            "type": "string",
+            "description": "后续行动文本，会替换已保存的内容。若为控制台后续行动格式的 JSON 数组（元素含 `title`、`status`、`priority`、`assignee_ids` 等），还会同步为结构化的后续行动事项。"
+          }
+        }
       },
       "ResetPostMortemStatusRequest": {
+        "type": "object",
         "description": "更新复盘报告状态的参数。",
+        "required": [
+          "post_mortem_id",
+          "status"
+        ],
         "properties": {
           "post_mortem_id": {
-            "description": "复盘 ID，可通过 `POST /incident/post-mortem/list` 获取。",
-            "type": "string"
+            "type": "string",
+            "description": "复盘 ID，可通过 `POST /incident/post-mortem/list` 获取。"
           },
           "status": {
-            "description": "目标报告状态：`drafting` 草稿，`published` 已发布。",
+            "type": "string",
             "enum": [
               "drafting",
               "published"
             ],
-            "type": "string"
+            "description": "目标报告状态。\n- `drafting`：编辑中，仍可通过正文重置替换正文。\n- `published`：已发布；正文不再引用的媒体文件会被删除。"
           }
-        },
-        "required": [
-          "post_mortem_id",
-          "status"
-        ],
-        "type": "object"
+        }
       },
       "ResetPostMortemTitleRequest": {
+        "type": "object",
         "description": "更新复盘报告标题的参数。",
+        "required": [
+          "post_mortem_id",
+          "title"
+        ],
         "properties": {
           "post_mortem_id": {
-            "description": "复盘 ID，可通过 `POST /incident/post-mortem/list` 获取。",
-            "type": "string"
+            "type": "string",
+            "description": "复盘 ID，可通过 `POST /incident/post-mortem/list` 获取。"
           },
           "title": {
-            "description": "新的报告标题。",
-            "type": "string"
+            "type": "string",
+            "maxLength": 256,
+            "description": "新的报告标题，最多 256 个字符。"
           }
-        },
-        "required": [
-          "post_mortem_id",
-          "title"
-        ],
-        "type": "object"
+        }
       },
       "ResetWorkItemAssigneesRequest": {
-        "description": "整体替换跟进事项的负责人集合。",
+        "type": "object",
+        "description": "整体替换跟进事项的负责人集合。`assignees` 与 `assignee_ids` 必须且只能传一个。",
+        "required": [
+          "work_item_id",
+          "version"
+        ],
         "properties": {
+          "work_item_id": {
+            "type": "string",
+            "maxLength": 128,
+            "description": "跟进事项 ID（不透明字符串，最长 128 字符）。"
+          },
+          "version": {
+            "type": "integer",
+            "format": "int64",
+            "description": "事项当前的 `version`（≥ 1），用于乐观锁。"
+          },
           "assignee_ids": {
-            "description": "替换后负责人集合的旧版别名，等价于全部为 `person` 的 `assignees`。与 `assignees` 互斥，同时出现会报错。空数组表示清空所有负责人。",
+            "type": "array",
             "items": {
-              "format": "int64",
-              "type": "integer"
+              "type": "integer",
+              "format": "int64"
             },
-            "type": "array"
+            "description": "替换后负责人集合的旧版别名，等价于全部为 `person` 的 `assignees`。与 `assignees` 互斥，同时出现会报错。空数组表示清空所有负责人。"
           },
           "assignees": {
             "description": "替换后的负责人集合。每项为 `{type, id?}`。`type` 取 `person` 或 `ai_sre`；`ai_sre` 不带 `id`。与 `assignee_ids` 互斥，同时出现会报错。`assignee_ids` 是旧版别名，等价于全部为 `person`。最多 20 项。空数组表示清空所有负责人。",
@@ -18269,23 +18905,8 @@
             },
             "maxItems": 20,
             "type": "array"
-          },
-          "version": {
-            "description": "事项当前版本号，用于乐观锁。必须与存储的版本一致。",
-            "format": "int64",
-            "type": "integer"
-          },
-          "work_item_id": {
-            "description": "跟进事项 ID（不透明字符串，最长 128 字符）。",
-            "maxLength": 128,
-            "type": "string"
           }
-        },
-        "required": [
-          "work_item_id",
-          "version"
-        ],
-        "type": "object"
+        }
       },
       "ResolveIncidentRequest": {
         "description": "恢复故障的参数。",
@@ -18458,51 +19079,51 @@
         ]
       },
       "ResponderInsightResponse": {
+        "type": "object",
         "properties": {
           "items": {
-            "description": "按处理人员聚合的故障响应指标行；启用 `split_hours` 或 `aggregate_unit` 时会进一步按时段或时间桶拆分。",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/ResponderInsightItem"
             },
-            "type": "array"
+            "description": "按响应人的指标行，按时间桶从新到旧排列。某时间桶内没有故障的响应人不产生行。"
           }
-        },
-        "type": "object"
+        }
       },
       "ResponseEnvelope": {
+        "type": "object",
         "description": "所有 Flashduty 公开 API 共用的标准响应结构。成功时 `data` 为接口专属载荷且不含 `error`；失败时 `error` 存在而 `data` 缺失。`request_id` 始终存在，并会同步写入 `Flashcat-Request-Id` 响应头。",
         "properties": {
-          "data": {
-            "description": "端点专属数据负载，具体结构见各操作 200 响应中的 schema。"
+          "request_id": {
+            "type": "string",
+            "description": "本次请求的唯一 ID，与 Flashcat-Request-Id 响应头一致。反馈问题时请携带该 ID。",
+            "example": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
           },
           "error": {
             "$ref": "#/components/schemas/DutyError"
           },
-          "request_id": {
-            "description": "本次请求的唯一 ID，与 Flashcat-Request-Id 响应头一致。反馈问题时请携带该 ID。",
-            "example": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
-            "type": "string"
+          "data": {
+            "description": "接口返回的数据，格式见各接口的 200 响应。没有返回数据的接口会返回 `{}` 或完全不带 `data`。"
           }
         },
         "required": [
           "request_id"
-        ],
-        "type": "object"
+        ]
       },
       "RevertRemoteConfigRequest": {
         "description": "将历史版本的内容重新发布为新的版本号。",
         "properties": {
           "application_id": {
-            "description": "RUM 应用 ID。",
+            "description": "RUM 应用 ID，可通过 `POST /rum/application/list` 获取。",
             "type": "string"
           },
           "reason": {
-            "description": "操作者说明。控制台留空时会自动填入 `rolled back to vN`。",
+            "description": "可选的自由文本备注（非枚举），最多 255 个字符，按原样保存，并在 `POST /rum/application/remote-config/history/list` 的 `reason` 中返回。不传时服务端不会自动填充。",
             "maxLength": 255,
             "type": "string"
           },
           "version": {
-            "description": "要重新发布的历史版本号。",
+            "description": "要恢复的版本号，必须是 `POST /rum/application/remote-config/history/list` 中仍保留的版本。",
             "minimum": 1,
             "type": "integer"
           }
@@ -18517,53 +19138,53 @@
         "description": "回滚创建的版本。",
         "properties": {
           "version": {
-            "description": "回滚生成的新的版本号。",
+            "description": "回滚生成的新版本号（此前最大版本号 + 1）。",
             "type": "integer"
           }
         },
         "type": "object"
       },
       "RoleDeleteRequest": {
+        "type": "object",
+        "required": [
+          "role_id"
+        ],
         "description": "删除角色请求。",
         "properties": {
-          "is_force": {
-            "default": false,
-            "description": "为 false（默认）时，若仍有成员持有该角色，删除失败并返回 `ReferenceExist` 错误，`data.refs` 中列出持有成员；为 true 时先从所有持有成员解除该角色，再删除角色。",
-            "type": "boolean"
-          },
           "role_id": {
-            "description": "要删除的角色 ID。可通过 `POST /role/list` 获取（内置角色：2=Admin，6=Responder，8=Viewer）。",
+            "type": "integer",
             "format": "uint64",
-            "type": "integer"
+            "description": "要删除的角色 ID。可通过 `POST /role/list` 获取（内置角色：2=Admin，6=Responder，8=Viewer）。"
+          },
+          "is_force": {
+            "type": "boolean",
+            "default": false,
+            "description": "为 false（默认）时，只要还有成员持有该角色，删除就会失败并返回 `ReferenceExist`，持有成员列在 `data.refs` 中。为 true 时，先从所有持有成员解除该角色再删除。不会跳过单点登录默认角色检查。"
           }
-        },
+        }
+      },
+      "RoleGrantRequest": {
+        "type": "object",
         "required": [
+          "member_ids",
           "role_id"
         ],
-        "type": "object"
-      },
-      "RoleGrantRequest": {
         "description": "向成员授予或撤销角色的请求。",
         "properties": {
           "member_ids": {
-            "description": "要授予/撤销角色的成员 ID 列表。",
+            "type": "array",
             "items": {
-              "format": "uint64",
-              "type": "integer"
+              "type": "integer",
+              "format": "uint64"
             },
-            "type": "array"
+            "description": "要授予或解除该角色的成员 ID（取自 `POST /member/list`）。必须全部是本账户成员，不能重复。"
           },
           "role_id": {
-            "description": "要授予或撤销的角色 ID，可通过 `POST /role/list` 获取。",
+            "type": "integer",
             "format": "uint64",
-            "type": "integer"
+            "description": "要授予或撤销的角色 ID，可通过 `POST /role/list` 获取。"
           }
-        },
-        "required": [
-          "member_ids",
-          "role_id"
-        ],
-        "type": "object"
+        }
       },
       "RoleIDRequest": {
         "properties": {
@@ -18592,63 +19213,63 @@
         "type": "object"
       },
       "RoleItem": {
+        "type": "object",
         "description": "角色及其权限集合。",
+        "required": [
+          "role_id",
+          "role_name",
+          "description",
+          "status",
+          "permission_ids",
+          "editable",
+          "created_at",
+          "updated_at"
+        ],
         "properties": {
-          "created_at": {
-            "description": "创建时间（Unix 秒）。",
-            "format": "int64",
-            "type": "integer"
-          },
-          "description": {
-            "description": "角色描述。",
-            "type": "string"
-          },
-          "editable": {
-            "description": "内置角色为 false，不可修改。",
-            "type": "boolean"
-          },
-          "permission_ids": {
-            "description": "该角色授予的权限 ID 列表。",
-            "items": {
-              "format": "uint64",
-              "type": "integer"
-            },
-            "type": "array"
-          },
           "role_id": {
-            "description": "唯一角色 ID。",
+            "type": "integer",
             "format": "uint64",
-            "type": "integer"
+            "description": "角色 ID。内置角色使用固定 ID：`2`（Admin）、`6`（Responder）、`8`（Viewer）。"
           },
           "role_name": {
-            "description": "角色显示名称。",
-            "type": "string"
+            "type": "string",
+            "description": "角色名称，在账户内唯一。内置角色在所有语言下都命名为 `Admin`、`Responder`、`Viewer`。"
+          },
+          "description": {
+            "type": "string",
+            "description": "角色描述。内置角色的描述随请求语言本地化。"
           },
           "status": {
-            "description": "角色状态。",
+            "type": "string",
             "enum": [
               "enabled",
               "disabled"
             ],
-            "type": "string"
+            "description": "角色状态。`enabled`——启用；`disabled`——已通过 `POST /role/disable` 禁用。内置角色始终为 `enabled`；已删除的角色不会返回。"
+          },
+          "permission_ids": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "uint64"
+            },
+            "description": "该角色授予的权限 ID，升序排列，可通过 `POST /role/permission/list` 解析。没有权限时为空数组。"
+          },
+          "editable": {
+            "type": "boolean",
+            "description": "内置角色（Admin、Responder、Viewer）为 `false`；自定义角色为 `true`。"
+          },
+          "created_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "角色创建时间，Unix 时间戳（秒）。内置角色为固定值。"
           },
           "updated_at": {
-            "description": "最近更新时间（Unix 秒）。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "最近更新时间（Unix 秒）。"
           }
-        },
-        "required": [
-          "role_id",
-          "role_name",
-          "description",
-          "status",
-          "permission_ids",
-          "editable",
-          "created_at",
-          "updated_at"
-        ],
-        "type": "object"
+        }
       },
       "RoleListRequest": {
         "description": "查询角色列表的过滤参数。",
@@ -18673,43 +19294,43 @@
         "type": "object"
       },
       "RoleListResponse": {
+        "type": "object",
         "description": "角色列表结果。",
+        "required": [
+          "total",
+          "items"
+        ],
         "properties": {
+          "total": {
+            "type": "integer",
+            "description": "返回的角色数：自定义角色数加上 3 个内置角色（`no_global` 为 true 时不含内置角色）。"
+          },
           "items": {
-            "description": "角色数组；默认包含账户自建角色和内置全局角色（`no_global=true` 时不含全局角色），无结果时为空数组。",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/RoleItem"
             },
-            "type": "array"
-          },
-          "total": {
-            "description": "角色总数。",
-            "type": "integer"
+            "description": "角色数组；默认包含账户自建角色和内置全局角色（`no_global=true` 时不含全局角色），无结果时为空数组。"
           }
-        },
-        "required": [
-          "total",
-          "items"
-        ],
-        "type": "object"
+        }
       },
       "RolePermissionListRequest": {
+        "type": "object",
         "description": "查询权限列表的过滤参数。",
         "properties": {
           "role_ids": {
-            "description": "按角色 ID 过滤，只返回这些角色已授予的权限。",
+            "type": "array",
             "items": {
-              "format": "uint64",
-              "type": "integer"
+              "type": "integer",
+              "format": "uint64"
             },
-            "type": "array"
+            "description": "要返回或标记其已授予权限的角色 ID（内置或自定义）。不存在的 ID 会被忽略。"
           },
           "with_all": {
-            "description": "若为 true，返回所有权限并用 is_granted 标记哪些已授予。",
-            "type": "boolean"
+            "type": "boolean",
+            "description": "为 true 时返回全部权限，并用 `is_granted` 标记 `role_ids` 授予的权限。为 false（默认）时只返回已授予的权限。"
           }
-        },
-        "type": "object"
+        }
       },
       "RolePermissionListResponse": {
         "description": "权限列表结果。",
@@ -18728,37 +19349,37 @@
         "type": "object"
       },
       "RoleUpsertRequest": {
+        "type": "object",
+        "required": [
+          "role_name"
+        ],
         "description": "创建或更新自定义角色的参数。",
         "properties": {
+          "role_id": {
+            "type": "integer",
+            "format": "uint64",
+            "description": "要更新的自定义角色 ID。省略或置为 0 表示创建新角色。不要传内置角色 ID `2`、`6`、`8`。"
+          },
+          "role_name": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 39,
+            "description": "角色显示名称，1–39 个字符。"
+          },
           "description": {
-            "description": "角色描述。",
+            "type": "string",
             "maxLength": 499,
-            "type": "string"
+            "description": "角色描述，最多 499 个字符。更新时不传会清空原有描述。"
           },
           "permission_ids": {
-            "description": "要授予的权限 ID 列表，会替换现有权限集合。",
+            "type": "array",
             "items": {
-              "format": "uint64",
-              "type": "integer"
+              "type": "integer",
+              "format": "uint64"
             },
-            "type": "array"
-          },
-          "role_id": {
-            "description": "角色 ID，省略或置为 0 表示创建。",
-            "format": "uint64",
-            "type": "integer"
-          },
-          "role_name": {
-            "description": "角色显示名称，1–39 个字符。",
-            "maxLength": 39,
-            "minLength": 1,
-            "type": "string"
+            "description": "角色授予的权限 ID（取自 `POST /role/permission/list`）。整体替换原有权限；不传或传空数组会使角色没有任何权限。"
           }
-        },
-        "required": [
-          "role_name"
-        ],
-        "type": "object"
+        }
       },
       "RoleUpsertResponse": {
         "description": "角色创建/更新结果。",
@@ -18780,177 +19401,177 @@
         "type": "object"
       },
       "RouteCase": {
+        "type": "object",
         "description": "路由规则中的单个 case 分支。当其全部条件命中后,告警将分发到所配置的协作空间。",
+        "required": [
+          "if"
+        ],
         "properties": {
-          "channel_ids": {
-            "description": "目标协作空间 ID。当 `routing_mode` 为 `standard`（或为空）时必填；`name_mapping` 模式下返回 `null`。",
+          "if": {
+            "type": "array",
+            "description": "条件之间为 AND 关系；空列表匹配所有事件。必填。",
             "items": {
-              "format": "int64",
-              "type": "integer"
-            },
+              "$ref": "#/components/schemas/RouteMatchCondition"
+            }
+          },
+          "channel_ids": {
             "type": [
               "array",
               "null"
-            ]
-          },
-          "fallthrough": {
-            "description": "为 `true` 时,本 case 命中后继续向下匹配;为 `false` 则在首次命中后停止。",
-            "type": "boolean"
-          },
-          "if": {
-            "description": "匹配条件列表,条件之间为 AND 关系。",
+            ],
             "items": {
-              "$ref": "#/components/schemas/RouteMatchCondition"
+              "type": "integer",
+              "format": "int64"
             },
-            "type": "array"
+            "description": "目标协作空间 ID。当 `routing_mode` 为 `standard`（或为空）时必填；`name_mapping` 模式下返回 `null`。"
           },
-          "name_mapping_label": {
-            "description": "用作目标协作空间名的标签键。当 `routing_mode` 为 `name_mapping` 时必填。",
-            "type": "string"
+          "fallthrough": {
+            "type": "boolean",
+            "description": "为 `true` 时，本 case 命中后继续匹配后续 case，所有命中 case 的协作空间合并；为 `false` 时在本 case 停止。"
           },
           "routing_mode": {
-            "description": "路由模式。`standard`（默认，留空时亦按此处理）按固定的协作空间 ID 路由；`name_mapping` 通过读取告警事件中某个标签的值来动态匹配协作空间名称。",
+            "type": "string",
             "enum": [
               "standard",
               "name_mapping"
             ],
-            "type": "string"
+            "description": "路由模式。`standard` 路由到固定的 `channel_ids`；`name_mapping` 路由到名称与事件中 `name_mapping_label` 字段值相同的已启用协作空间。留空按 `standard` 处理，响应中不返回该字段。"
+          },
+          "name_mapping_label": {
+            "type": "string",
+            "description": "其取值用作目标协作空间名称的事件字段，例如 `labels.service`。`routing_mode` 为 `name_mapping` 时必填；没有同名的已启用协作空间时，该 case 不产生协作空间。"
           }
-        },
-        "required": [
-          "if"
-        ],
-        "type": "object"
+        }
       },
       "RouteDefault": {
+        "type": "object",
         "description": "默认分支。当所有 case 均未命中(或命中的 case 没有有效协作空间)时使用。",
         "properties": {
           "channel_ids": {
-            "description": "兜底使用的协作空间 ID 列表。",
+            "type": "array",
             "items": {
-              "format": "int64",
-              "type": "integer"
+              "type": "integer",
+              "format": "int64"
             },
-            "type": "array"
+            "description": "没有任何 case 得到协作空间时使用的协作空间。空列表视为没有默认分支。"
           }
-        },
-        "type": "object"
+        }
       },
       "RouteInfoRequest": {
+        "type": "object",
         "description": "查询单个集成路由规则所需的参数。",
+        "required": [
+          "integration_id"
+        ],
         "properties": {
           "integration_id": {
-            "description": "集成 ID,必须大于 0。",
-            "exclusiveMinimum": 0,
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "共享集成 ID，大于 0，可通过 `POST /integration/list` 获取。",
+            "exclusiveMinimum": 0
           }
-        },
-        "required": [
-          "integration_id"
-        ],
-        "type": "object"
+        }
       },
       "RouteItem": {
-        "description": "集成的路由规则。告警按 `cases` 顺序依次匹配，未命中的将进入 `default` 分支。当集成未配置规则时返回 `null`。",
+        "type": "object",
+        "description": "共享集成的路由规则。告警按顺序匹配 `cases`；没有任何 case 得到协作空间时使用 `default`。",
+        "required": [
+          "version",
+          "updated_by",
+          "creator_id"
+        ],
         "properties": {
+          "integration_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "所属集成 ID。"
+          },
           "cases": {
-            "description": "有序的 case 分支列表。",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/RouteCase"
             },
-            "type": "array"
-          },
-          "created_at": {
-            "description": "创建时间,Unix 秒级时间戳。",
-            "format": "int64",
-            "type": "integer"
-          },
-          "creator_id": {
-            "description": "创建人员 ID。",
-            "format": "int64",
-            "type": "integer"
-          },
-          "default": {
-            "$ref": "#/components/schemas/RouteDefault"
-          },
-          "deleted_at": {
-            "description": "软删除时间戳（Unix 秒）。规则有效时不返回此字段。",
-            "format": "int64",
-            "type": "integer"
-          },
-          "integration_id": {
-            "description": "所属集成 ID。",
-            "format": "int64",
-            "type": "integer"
+            "description": "有序的 case 分支列表。"
           },
           "sections": {
-            "description": "可选的分区,用于将多个 case 进行视觉分组。",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/RouteSection"
             },
-            "type": "array"
+            "description": "可选的分区,用于将多个 case 进行视觉分组。"
+          },
+          "default": {
+            "$ref": "#/components/schemas/RouteDefault"
           },
           "status": {
-            "description": "规则状态。`enabled` 生效中；`deleted` 已删除，仅在历史版本中可见。",
+            "type": "string",
             "enum": [
               "enabled",
               "deleted"
             ],
-            "type": "string"
+            "description": "规则状态。这些接口只返回 `enabled` 的规则，`deleted` 的规则（例如集成已删除）不会返回。"
           },
-          "updated_at": {
-            "description": "最后更新时间,Unix 秒级时间戳。",
+          "version": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "版本号，每次 `POST /route/upsert` 递增。服务端不会用它做并发校验。"
           },
           "updated_by": {
-            "description": "最后一次修改人员 ID。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "最后一次修改人员 ID。"
           },
-          "version": {
-            "description": "单调递增的版本号,每次更新加 1,可用于乐观并发控制。",
+          "creator_id": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "创建人员 ID。"
+          },
+          "deleted_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "软删除时间，Unix 秒级时间戳。这些接口只返回有效规则，因此不会返回此字段。"
+          },
+          "created_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "创建时间,Unix 秒级时间戳。"
+          },
+          "updated_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "最后更新时间,Unix 秒级时间戳。"
           }
-        },
-        "required": [
-          "version",
-          "updated_by",
-          "creator_id"
-        ],
-        "type": "object"
+        }
       },
       "RouteMatchCondition": {
+        "type": "object",
         "description": "单个匹配条件。同一 case 内的所有条件之间为 AND 关系。",
+        "required": [
+          "key",
+          "oper",
+          "vals"
+        ],
         "properties": {
           "key": {
-            "description": "用于与告警事件比对的字段键(如 `alert_severity`、`labels.service`)。",
-            "type": "string"
+            "type": "string",
+            "description": "要匹配的告警或变更事件字段：`title`、`description`、`severity`（别名 `alert_severity`、`event_severity`）、`status`、`alert_key`、`change_key`、`title_rule`、`integration_id`（别名 `data_source_id`），或任意 `labels.<name>`。未知字段返回 `InvalidParameter`。"
           },
           "oper": {
-            "description": "匹配运算符。`IN` 表示字段值命中 `vals` 中任一项;`NOTIN` 表示均不命中。",
+            "type": "string",
             "enum": [
               "IN",
               "NOTIN"
             ],
-            "type": "string"
+            "description": "匹配操作符。`IN`：字段值匹配 `vals` 中任意一项即命中；`NOTIN`：与所有项都不匹配才命中。字段缺失时 `IN` 不命中，`NOTIN` 命中。"
           },
           "vals": {
-            "description": "用于比对的值列表。每项支持字面量、通配符（`*`、`?`）、以斜杠包裹的正则表达式（`/pattern/`）、CIDR（`cidr:10.0.0.0/8`）以及数值比较（`num:lt:100`）。",
+            "type": "array",
             "items": {
               "type": "string"
             },
-            "type": "array"
+            "description": "要比较的值，至少一项。每项的匹配方式：普通字符串精确匹配；含 `*` 或 `?` 时按通配符匹配整个值；用斜杠包裹时按正则表达式匹配，如 `/^db-/`（可匹配值的任意位置）；`cidr:<网段>` 匹配 IP 范围，如 `cidr:203.0.113.0/24`；`num:<op>:<数字>` 做数值比较，`op` 为 `lt`、`le`、`gt`、`ge`，如 `num:gt:90`。"
           }
-        },
-        "required": [
-          "key",
-          "oper",
-          "vals"
-        ],
-        "type": "object"
+        }
       },
       "RouteSection": {
         "description": "用于将连续的多个 case 在视觉上分组的逻辑分区。",
@@ -19270,75 +19891,24 @@
         "type": "object"
       },
       "RuleFieldsUpdateRequest": {
+        "type": "object",
+        "required": [
+          "ids",
+          "fields"
+        ],
         "properties": {
-          "annotations": {
-            "additionalProperties": {
-              "type": "string"
-            },
-            "description": "附加注解键值对，随告警事件下发；键不允许以 `$` 开头（该前缀保留给查询字段）。仅当 `fields` 包含 `annotations` 时生效。",
-            "type": "object"
-          },
-          "annotations_patch": {
-            "$ref": "#/components/schemas/StringMapPatch",
-            "description": "注解的增量更新，仅在 `fields` 包含 `annotations` 时生效；与 `annotations` 同时发送时优先使用本字段。"
-          },
-          "channel_ids": {
-            "description": "告警发送到的协作空间 ID 列表，可为空。仅当 `fields` 包含 `channel_ids` 时生效。",
-            "items": {
-              "format": "uint64",
-              "type": "integer"
-            },
-            "type": "array"
-          },
-          "cron_pattern": {
-            "description": "调度表达式：6 段（含秒）cron 表达式或 `@every 30s` 间隔描述，不允许 `CRON_TZ=`/`TZ=` 前缀。仅当 `fields` 包含 `cron_pattern` 时生效。",
-            "type": "string"
-          },
-          "debug_log_enabled": {
-            "description": "是否开启调试日志，开启后 edge 评估该规则时输出详细日志，用于排查问题。仅当 `fields` 包含 `debug_log_enabled` 时生效。",
-            "type": "boolean"
-          },
-          "delay_seconds": {
-            "description": "评估时查询窗口向前偏移的秒数，用于补偿数据摄入延迟。仅当 `fields` 包含 `delay_seconds` 时生效。",
-            "type": "integer"
-          },
-          "description": {
-            "description": "规则描述（Markdown）。仅当 `fields` 包含 `description` 时生效。",
-            "type": "string"
-          },
-          "ds_ids": {
-            "description": "数据源 ID 列表，与 `ds_list` 合并后共同决定规则监控的数据源，使用 ID 可避免数据源改名后失效。仅当 `fields` 包含 `ds_ids` 时生效。",
-            "items": {
-              "format": "uint64",
-              "type": "integer"
-            },
-            "type": "array"
-          },
-          "ds_list": {
-            "description": "数据源名称匹配模式列表，支持通配符。仅当 `fields` 包含 `ds_list` 时生效。",
-            "items": {
-              "type": "string"
-            },
-            "type": "array"
-          },
-          "ds_type": {
-            "description": "数据源类型标识。仅当 `fields` 包含 `ds_type` 时生效。",
-            "type": "string"
-          },
-          "enabled": {
-            "description": "是否启用规则。置为 `false` 时服务端会清理该规则的活跃告警。仅当 `fields` 包含 `enabled` 时生效。",
-            "type": "boolean"
-          },
-          "enabled_times": {
-            "description": "规则生效的时间窗口数组，元素结构见 `EnabledTime`。仅当 `fields` 包含 `enabled_times` 时生效。",
+          "ids": {
+            "type": "array",
             "items": {
-              "$ref": "#/components/schemas/EnabledTime"
+              "type": "integer",
+              "format": "uint64"
             },
-            "type": "array"
+            "description": "要更新的规则 ID 列表，至少包含一个 ID。"
           },
           "fields": {
-            "description": "要更新的字段名列表。只有列出的字段会被更新，新值从同名请求字段读取；未列出的字段即使传值也会被忽略。",
+            "type": "array",
             "items": {
+              "type": "string",
               "enum": [
                 "labels",
                 "ds_type",
@@ -19355,51 +19925,102 @@
                 "channel_ids",
                 "repeat_interval",
                 "repeat_total"
-              ],
+              ]
+            },
+            "description": "要更新的字段名列表。每个列出的字段取同名请求字段的值，未传值时设为零值；未列出的字段即使传值也会被忽略。出现未知字段名时整个调用返回 `InvalidParameter`。"
+          },
+          "labels": {
+            "type": "object",
+            "additionalProperties": {
               "type": "string"
             },
-            "type": "array"
+            "description": "自定义标签键值对，整体替换现有标签。仅当 `fields` 包含 `labels` 时生效；不能与 `labels_patch` 同时传入。"
           },
-          "ids": {
-            "description": "要更新的规则 ID 列表。",
+          "ds_type": {
+            "type": "string",
+            "description": "数据源类型标识。启用的规则必须使用支持告警的类型：`prometheus`、`elasticsearch`、`loki`、`clickhouse`、`mysql`、`oracle`、`postgres`、`sls`、`tencent_cls`、`victorialogs`。仅当 `fields` 包含 `ds_type` 时生效。"
+          },
+          "ds_list": {
+            "type": "array",
             "items": {
-              "format": "uint64",
-              "type": "integer"
+              "type": "string"
             },
-            "type": "array"
+            "description": "数据源名称匹配模式列表，支持通配符。仅当 `fields` 包含 `ds_list` 时生效。"
           },
-          "labels": {
+          "ds_ids": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "uint64"
+            },
+            "description": "数据源 ID 列表，与 `ds_list` 合并后共同决定规则监控的数据源，使用 ID 可避免数据源改名后失效。仅当 `fields` 包含 `ds_ids` 时生效。"
+          },
+          "enabled": {
+            "type": "boolean",
+            "description": "是否启用规则。置为 `false` 时服务端会清理该规则的活跃告警。仅当 `fields` 包含 `enabled` 时生效。"
+          },
+          "debug_log_enabled": {
+            "type": "boolean",
+            "description": "是否开启调试日志，开启后 edge 评估该规则时输出详细日志，用于排查问题。仅当 `fields` 包含 `debug_log_enabled` 时生效。"
+          },
+          "cron_pattern": {
+            "type": "string",
+            "description": "调度表达式：6 段（含秒）cron 表达式或 `@every 30s` 间隔描述，不允许 `CRON_TZ=`/`TZ=` 前缀。仅当 `fields` 包含 `cron_pattern` 时生效。"
+          },
+          "timezone": {
+            "type": "string",
+            "description": "规则执行时区，取 IANA 时区名（如 `Asia/Shanghai`、`UTC`）；为空时按 `Asia/Shanghai` 处理。仅当 `fields` 包含 `timezone` 时生效。",
+            "default": "Asia/Shanghai"
+          },
+          "delay_seconds": {
+            "type": "integer",
+            "description": "评估时查询窗口向前偏移的秒数，用于补偿数据摄入延迟。仅当 `fields` 包含 `delay_seconds` 时生效。"
+          },
+          "enabled_times": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/EnabledTime"
+            },
+            "description": "规则生效的时间窗口数组，元素结构见 `EnabledTime`。仅当 `fields` 包含 `enabled_times` 时生效。"
+          },
+          "annotations": {
+            "type": "object",
             "additionalProperties": {
               "type": "string"
             },
-            "description": "自定义标签键值对，整体替换现有标签。仅当 `fields` 包含 `labels` 时生效。",
-            "type": "object"
+            "description": "随告警事件下发的注解键值对，整体替换现有注解，键不允许以 `$` 开头（该前缀保留给查询字段）。仅当 `fields` 包含 `annotations` 时生效；不能与 `annotations_patch` 同时传入。"
           },
-          "labels_patch": {
-            "$ref": "#/components/schemas/StringMapPatch",
-            "description": "标签的增量更新，仅在 `fields` 包含 `labels` 时生效；与 `labels` 同时发送时优先使用本字段。"
+          "description": {
+            "type": "string",
+            "description": "规则描述，按规则现有的 `description_type` 渲染（本接口无法修改该格式）。仅当 `fields` 包含 `description` 时生效。"
+          },
+          "channel_ids": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "uint64"
+            },
+            "description": "告警发送到的协作空间 ID 列表，可为空。仅当 `fields` 包含 `channel_ids` 时生效。"
           },
           "repeat_interval": {
-            "description": "告警通知重复间隔（秒）。仅当 `fields` 包含 `repeat_interval` 时生效。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "告警通知重复间隔（秒）；小于 1 时按 3600 处理，最大 2147483647。仅当 `fields` 包含 `repeat_interval` 时生效。"
           },
           "repeat_total": {
-            "description": "最大重复通知次数。仅当 `fields` 包含 `repeat_total` 时生效。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "最大重复通知次数；小于 1 时按 3 处理，最大 2147483647。仅当 `fields` 包含 `repeat_total` 时生效。"
           },
-          "timezone": {
-            "default": "Asia/Shanghai",
-            "description": "告警规则执行时区，IANA 时区名，默认 `Asia/Shanghai`。",
-            "type": "string"
+          "labels_patch": {
+            "$ref": "#/components/schemas/StringMapPatch",
+            "description": "标签的增量更新，未提及的标签保持不变。要求 `fields` 包含 `labels`，且不能与 `labels` 同时传入，否则返回 `InvalidParameter`。"
+          },
+          "annotations_patch": {
+            "$ref": "#/components/schemas/StringMapPatch",
+            "description": "注解的增量更新，未提及的注解保持不变。要求 `fields` 包含 `annotations`，且不能与 `annotations` 同时传入，否则返回 `InvalidParameter`。"
           }
-        },
-        "required": [
-          "ids",
-          "fields"
-        ],
-        "type": "object"
+        }
       },
       "RuleIDRequest": {
         "properties": {
@@ -19415,20 +20036,20 @@
         "type": "object"
       },
       "RuleIDsRequest": {
+        "type": "object",
+        "required": [
+          "ids"
+        ],
         "properties": {
           "ids": {
-            "description": "规则 ID 列表。",
+            "type": "array",
             "items": {
-              "format": "uint64",
-              "type": "integer"
+              "type": "integer",
+              "format": "uint64"
             },
-            "type": "array"
+            "description": "要删除的告警规则 ID 列表，至少包含一个 ID，可通过 `POST /monit/rule/list/basic` 获取。"
           }
-        },
-        "required": [
-          "ids"
-        ],
-        "type": "object"
+        }
       },
       "RuleImportRequest": {
         "description": "要导入的告警规则导出对象数组。",
@@ -19445,51 +20066,51 @@
         "type": "array"
       },
       "RuleListRequest": {
+        "type": "object",
         "description": "按文件夹查询规则的过滤参数。",
         "properties": {
           "folder_id": {
-            "description": "文件夹 ID，必须是已存在的文件夹；传 `0` 会返回 `folder_not_found` 错误。",
+            "type": "integer",
             "format": "uint64",
-            "type": "integer"
+            "description": "要列出的文件夹 ID，必须是调用者有管理权限的已存在文件夹；传 `0` 或不存在的 ID 返回 `InvalidParameter`。"
           },
           "include_descendants": {
-            "description": "是否同时包含所有子孙文件夹中的规则。为 `true` 时返回的每项仅包含 `id`、`folder_id`、`name` 三个字段；配合 `query` / `limit` 用于规则选择器场景。",
-            "type": "boolean"
+            "type": "boolean",
+            "description": "是否同时搜索所有子孙文件夹。为 `true` 时结果按名称排序、受 `limit` 限制，且每项只填充 `id`、`folder_id`、`name`（其余字段为零值）；可配合 `query` 用于规则选择器场景。"
+          },
+          "query": {
+            "type": "string",
+            "description": "按规则名称子串过滤；纯数字时还会匹配该 ID 的规则。仅在 `include_descendants` 为 `true` 时生效。"
           },
           "limit": {
+            "type": "integer",
             "default": 50,
-            "description": "返回规则数量上限，仅在 `include_descendants` 为 `true` 时生效。默认 50，最大 100。",
             "maximum": 100,
-            "type": "integer"
-          },
-          "query": {
-            "description": "规则名模糊过滤，仅在 `include_descendants` 为 `true` 时生效。",
-            "type": "string"
+            "description": "返回规则数量上限，仅在 `include_descendants` 为 `true` 时生效。默认 50，最大 100。"
           }
-        },
-        "type": "object"
+        }
       },
       "RuleMoveRequest": {
+        "type": "object",
+        "required": [
+          "ids",
+          "dest_folder_id"
+        ],
         "properties": {
-          "dest_folder_id": {
-            "description": "目标文件夹 ID，可通过 `POST /monit/folder/list` 获取。",
-            "format": "uint64",
-            "type": "integer"
-          },
           "ids": {
-            "description": "要移动的规则 ID 列表。",
+            "type": "array",
             "items": {
-              "format": "uint64",
-              "type": "integer"
+              "type": "integer",
+              "format": "uint64"
             },
-            "type": "array"
+            "description": "要移动的规则 ID 列表，至少包含一个 ID。"
+          },
+          "dest_folder_id": {
+            "type": "integer",
+            "format": "uint64",
+            "description": "目标文件夹 ID，可通过 `POST /monit/folder/list` 获取。不能为 0；文件夹不存在或调用者对其无管理权限时，整个调用返回 `AccessDenied`。"
           }
-        },
-        "required": [
-          "ids",
-          "dest_folder_id"
-        ],
-        "type": "object"
+        }
       },
       "RuleNameMessageListResponse": {
         "description": "批量规则操作中每条规则的处理结果列表。",
@@ -19502,12 +20123,15 @@
         "description": "应用的告警配置。",
         "properties": {
           "channel_ids": {
-            "description": "接收告警的协作空间 ID 列表，仅在 `delivery_mode` 为 `oncall` 时使用。",
+            "description": "接收告警的协作空间 ID 列表，仅在 `delivery_mode` 为 `oncall` 时使用；`webhook` 模式下作为草稿保留。从未设置时可能为 `null`。",
             "items": {
               "format": "int64",
               "type": "integer"
             },
-            "type": "array"
+            "type": [
+              "array",
+              "null"
+            ]
           },
           "delivery_mode": {
             "description": "告警投递方式：`oncall` 经 Flashduty On-call 投递，`webhook` 直接 POST 到 `webhook_url`。空值按 `oncall` 处理；创建/更新时空值会落库为部署默认值（纯 RUM 私有化部署默认 `webhook`，其他场景默认 `oncall`）。为空（历史数据）时省略该字段。",
@@ -19518,7 +20142,7 @@
             "type": "string"
           },
           "enabled": {
-            "description": "是否启用告警。",
+            "description": "是否开启告警。`false` 表示关闭告警，此时不校验 `webhook_url`。",
             "type": "boolean"
           },
           "integration_id": {
@@ -19527,7 +20151,7 @@
             "type": "integer"
           },
           "webhook_url": {
-            "description": "`delivery_mode` 为 `webhook` 时接收告警事件的 URL，该模式下必填，其他模式下忽略；为空时省略该字段。",
+            "description": "`delivery_mode` 为 `webhook` 时接收告警事件的 URL。该模式下 `enabled` 为 `true` 时必填；必须使用 `http` 或 `https`，在 Flashduty 云端不能解析到私有、回环、链路本地或保留地址。`oncall` 模式下忽略。为空时响应中省略该字段。",
             "format": "uri",
             "type": "string"
           }
@@ -19551,7 +20175,7 @@
             "type": "string"
           },
           "is_private": {
-            "description": "是否仅限团队成员访问。",
+            "description": "为 `true` 时，仅账户所有者、账户管理员、创建者和所属团队成员可以查看或编辑该应用。默认 `false`。",
             "type": "boolean"
           },
           "links": {
@@ -19567,11 +20191,11 @@
             "description": "要关联的代码仓库，有序；第一个为主仓库。最多 10 个。"
           },
           "no_geo": {
-            "description": "不推断地理位置。",
+            "description": "为 `true` 时不根据客户端 IP 推断地理位置。默认 `false`。",
             "type": "boolean"
           },
           "no_ip": {
-            "description": "不采集 IP 地址。",
+            "description": "为 `true` 时不采集客户端 IP 地址。默认 `false`。",
             "type": "boolean"
           },
           "team_id": {
@@ -19582,7 +20206,7 @@
           },
           "tracing": {
             "$ref": "#/components/schemas/RumApplicationTracing",
-            "description": "APM 链路追踪集成配置，可选。"
+            "description": "可选的 APM 链路集成配置。不传时保存为空配置（`enabled: false`，`open_type` 和 `endpoint` 为空）。"
           },
           "type": {
             "description": "平台标识：\n\n| 值 | 含义 |\n|---|---|\n| `browser` | 浏览器 Web 应用（JavaScript SDK） |\n| `ios` | 苹果 iOS 应用 |\n| `android` | Android 应用 |\n| `react-native` | React Native 应用 |\n| `flutter` | Flutter 应用 |\n| `kotlin-multiplatform` | Kotlin Multiplatform 应用 |\n| `roku` | Roku 频道应用 |\n| `unity` | Unity 应用 |\n| `miniprogram` | 微信小程序 |\n| `harmony` | 鸿蒙 HarmonyOS 应用 |\n| `electron` | Electron 桌面应用 |",
@@ -19613,7 +20237,7 @@
         "description": "创建 RUM 应用的结果。",
         "properties": {
           "application_id": {
-            "description": "自动生成的唯一应用 ID。",
+            "description": "服务端生成的应用 ID（22 位短 UUID），在其他应用接口中作为 `application_id` 使用。",
             "type": "string"
           },
           "application_name": {
@@ -19621,11 +20245,16 @@
             "type": "string"
           },
           "client_token": {
-            "description": "用于 RUM SDK 初始化的令牌。",
+            "description": "用于初始化 RUM SDK 的令牌，也可通过 `POST /rum/application/info` 获取。",
             "type": "string"
           }
         },
-        "type": "object"
+        "type": "object",
+        "required": [
+          "application_id",
+          "application_name",
+          "client_token"
+        ]
       },
       "RumApplicationIDRequest": {
         "description": "包含单个应用 ID 的请求。",
@@ -19644,7 +20273,7 @@
         "description": "批量查询应用信息请求。",
         "properties": {
           "application_ids": {
-            "description": "最多 200 个应用 ID，可通过 `POST /rum/application/list` 获取。",
+            "description": "最多 200 个应用 ID。重复 ID 会被去重，不存在或已删除的 ID 会被跳过。可通过 `POST /rum/application/list` 获取 ID。",
             "items": {
               "type": "string"
             },
@@ -19661,26 +20290,29 @@
         "description": "批量查询应用信息响应。",
         "properties": {
           "items": {
-            "description": "与请求的 `application_ids`（最多 200 个，自动去重）匹配的应用信息列表。",
+            "description": "在请求的 `application_ids` 中找到的应用，顺序不固定。均未找到时为空数组。",
             "items": {
               "$ref": "#/components/schemas/RumApplicationItem"
             },
             "type": "array"
           }
         },
-        "type": "object"
+        "type": "object",
+        "required": [
+          "items"
+        ]
       },
       "RumApplicationItem": {
         "description": "单个 RUM 应用。",
         "properties": {
           "account_id": {
-            "description": "账户 ID。",
+            "description": "应用所属 Flashduty 账户的 ID。",
             "format": "int64",
             "type": "integer"
           },
           "alerting": {
             "$ref": "#/components/schemas/RumApplicationAlerting",
-            "description": "应用的告警配置。"
+            "description": "应用的告警配置，始终为对象。"
           },
           "application_id": {
             "description": "唯一应用 ID。",
@@ -19700,17 +20332,17 @@
             "type": "integer"
           },
           "created_by": {
-            "description": "创建者成员 ID。",
+            "description": "创建者的成员 ID。创建者始终可以编辑该应用。",
             "format": "int64",
             "type": "integer"
           },
           "is_private": {
-            "description": "为 `true` 时仅团队成员可访问。",
+            "description": "为 `true` 时，仅账户所有者、账户管理员、创建者和所属团队成员可以查看或编辑该应用。",
             "type": "boolean"
           },
           "links": {
             "$ref": "#/components/schemas/RumApplicationLinks",
-            "description": "外部链接集成配置。"
+            "description": "外部链接集成配置，始终为对象；从未保存过任何系统时 `systems` 可能为 `null`。"
           },
           "repositories": {
             "type": "array",
@@ -19718,7 +20350,7 @@
               "$ref": "#/components/schemas/RumApplicationRepository"
             },
             "maxItems": 10,
-            "description": "关联的代码仓库，有序；第一个为主仓库。关联本身不授予任何访问权限：AI 会话只能读取本账户 GitHub App 安装已授权的仓库。"
+            "description": "关联的源码仓库，按顺序排列，第一个为主仓库；未关联时为空数组。关联本身不授予访问权限：AI 会话只能读取账户的 GitHub App 安装已授权的仓库。"
           },
           "no_geo": {
             "description": "为 `true` 时不推断地理位置。",
@@ -19729,7 +20361,7 @@
             "type": "boolean"
           },
           "status": {
-            "description": "应用状态。取值：`enabled`（启用中，正常接收数据）、`disabled`（已停用）、`deleted`（已删除的软删除标记；所有查询都会过滤该状态，响应中实际不会出现）。",
+            "description": "应用状态：\n\n- `enabled`：SDK 的 `client_token` 可用，正常采集数据。通过接口创建的应用都处于此状态。\n- `disabled`：`client_token` 被拒绝，不再采集新数据。没有公开接口会设置此状态。\n- `deleted`：软删除标记；已删除的应用不会出现在任何响应中，因此不会返回该值。",
             "enum": [
               "enabled",
               "disabled",
@@ -19738,13 +20370,13 @@
             "type": "string"
           },
           "team_id": {
-            "description": "所属团队 ID。",
+            "description": "所属团队 ID。该团队成员可以编辑该应用，应用为私有时也只有他们（及管理员、创建者）可见。",
             "format": "int64",
             "type": "integer"
           },
           "tracing": {
             "$ref": "#/components/schemas/RumApplicationTracing",
-            "description": "APM 链路追踪集成配置。"
+            "description": "APM 链路集成配置。始终为对象；从未配置时为 `enabled: false`，`open_type` 与 `endpoint` 为空。"
           },
           "type": {
             "description": "平台标识：\n\n| 值 | 含义 |\n|---|---|\n| `browser` | 浏览器 Web 应用（JavaScript SDK） |\n| `ios` | 苹果 iOS 应用 |\n| `android` | Android 应用 |\n| `react-native` | React Native 应用 |\n| `flutter` | Flutter 应用 |\n| `kotlin-multiplatform` | Kotlin Multiplatform 应用 |\n| `roku` | Roku 频道应用 |\n| `unity` | Unity 应用 |\n| `miniprogram` | 微信小程序 |\n| `harmony` | 鸿蒙 HarmonyOS 应用 |\n| `electron` | Electron 桌面应用 |",
@@ -19774,13 +20406,33 @@
             "type": "integer"
           }
         },
-        "type": "object"
+        "type": "object",
+        "required": [
+          "account_id",
+          "application_id",
+          "application_name",
+          "type",
+          "client_token",
+          "team_id",
+          "is_private",
+          "no_ip",
+          "no_geo",
+          "alerting",
+          "tracing",
+          "links",
+          "repositories",
+          "status",
+          "created_by",
+          "updated_by",
+          "created_at",
+          "updated_at"
+        ]
       },
       "RumApplicationLink": {
         "description": "在匹配的 RUM 事件详情页展示的外部系统链接。",
         "properties": {
           "enabled": {
-            "description": "是否启用该外部系统链接。",
+            "description": "是否显示该外部系统链接。不传时视为 `false`。",
             "type": "boolean"
           },
           "event_types": {
@@ -19801,15 +20453,15 @@
             "type": "array"
           },
           "icon_color": {
-            "description": "链接图标显示颜色。",
+            "description": "链接图标的显示颜色，例如 `#0F766E`。为空时响应中省略。",
             "type": "string"
           },
           "icon_text": {
-            "description": "链接图标中显示的短文本。",
+            "description": "链接图标中显示的短文本，例如 `S3`。为空时响应中省略。",
             "type": "string"
           },
           "id": {
-            "description": "外部系统的稳定客户端标识。",
+            "description": "客户端自定义的外部系统标识，按原样保存，服务端不做校验。",
             "type": "string"
           },
           "name": {
@@ -19834,7 +20486,7 @@
         "description": "应用的外部链接集成配置。",
         "properties": {
           "enabled": {
-            "description": "是否启用外部链接集成。",
+            "description": "外部链接集成的总开关。不传时视为 `false`。",
             "type": "boolean"
           },
           "systems": {
@@ -19857,11 +20509,11 @@
         "description": "查询 RUM 应用列表的过滤参数。",
         "properties": {
           "asc": {
-            "description": "为 `true` 时升序排列。",
+            "description": "为 `true` 时升序；默认 `false`（降序）。",
             "type": "boolean"
           },
           "is_my_team": {
-            "description": "为 `true` 时仅返回当前用户所在团队的应用。",
+            "description": "为 `true` 时只返回调用者所在团队拥有的应用；调用者不属于任何团队时不生效。",
             "type": "boolean"
           },
           "limit": {
@@ -19884,7 +20536,7 @@
             "type": "integer"
           },
           "query": {
-            "description": "按应用名称做子串匹配搜索。",
+            "description": "按应用名称做子串匹配（SQL `LIKE`，因此 `%` 和 `_` 会被当作通配符）。",
             "type": "string"
           },
           "team_id": {
@@ -19903,7 +20555,7 @@
             "type": "boolean"
           },
           "items": {
-            "description": "当前页的 RUM 应用列表。",
+            "description": "当前页的 RUM 应用；无匹配时为空数组。",
             "items": {
               "$ref": "#/components/schemas/RumApplicationItem"
             },
@@ -19914,24 +20566,30 @@
             "type": "integer"
           }
         },
-        "type": "object"
+        "type": "object",
+        "required": [
+          "has_next_page",
+          "total",
+          "items"
+        ]
       },
       "RumApplicationTracing": {
         "description": "APM 链路追踪集成配置。",
         "properties": {
           "enabled": {
-            "description": "是否启用链路追踪集成。",
+            "description": "是否在 RUM 事件上显示链路链接。",
             "type": "boolean"
           },
           "endpoint": {
-            "description": "链路 Endpoint URL（http 或 https）。",
+            "description": "链路系统地址，必须以 `http` 或 `https` 开头。只要传入 `tracing` 就必填，即使 `enabled` 为 `false`。从未配置链路时，响应中为空字符串。",
             "type": "string"
           },
           "open_type": {
-            "description": "链路链接的打开方式。取值：`popup`（在弹窗中打开链路详情）、`tab`（在新标签页中打开）。",
+            "description": "链路链接的打开方式：\n\n- `popup`：在弹窗中打开链路详情。\n- `tab`：在新的浏览器标签页中打开。\n- `\"\"`（空）：仅在从未配置链路时返回；请求中不接受。",
             "enum": [
               "popup",
-              "tab"
+              "tab",
+              ""
             ],
             "type": "string"
           }
@@ -19948,7 +20606,7 @@
         "properties": {
           "alerting": {
             "$ref": "#/components/schemas/RumApplicationAlerting",
-            "description": "告警配置；不传则保持不变。",
+            "description": "告警配置。传入时整体替换已保存的告警配置（`integration_id` 由服务端维护除外）。不传则保持不变。",
             "x-flashduty-preserve-absence": true
           },
           "application_id": {
@@ -19965,7 +20623,7 @@
             ]
           },
           "is_private": {
-            "description": "是否仅限所属团队成员访问；`false` 显式改为公开访问；不传则保持不变。",
+            "description": "`true` 表示仅账户所有者、账户管理员、创建者和所属团队成员可访问；`false` 表示账户内所有人可见。不传则保持不变。",
             "type": [
               "boolean",
               "null"
@@ -19973,7 +20631,7 @@
           },
           "links": {
             "$ref": "#/components/schemas/RumApplicationLinks",
-            "description": "外部链接集成配置；不传则保持不变。",
+            "description": "外部链接集成配置。传入时整体替换已保存的对象（包括整个 `systems` 列表）。不传则保持不变。",
             "x-flashduty-preserve-absence": true
           },
           "repositories": {
@@ -20000,7 +20658,7 @@
             ]
           },
           "team_id": {
-            "description": "应用所属团队 ID，可通过 `POST /team/list` 获取；不传则保持不变。",
+            "description": "新的所属团队 ID，可通过 `POST /team/list` 获取。不传则保持不变。更换团队会改变可编辑该应用的人员。",
             "exclusiveMinimum": 0,
             "format": "int64",
             "type": [
@@ -20010,7 +20668,7 @@
           },
           "tracing": {
             "$ref": "#/components/schemas/RumApplicationTracing",
-            "description": "APM 链路追踪集成配置；不传则保持不变。"
+            "description": "APM 链路集成配置。传入时整体替换已保存的对象，且必须包含合法的 `open_type` 和 `endpoint`。不传则保持不变。"
           },
           "type": {
             "description": "应用类型，不传则不修改。平台标识：\n\n| 值 | 含义 |\n|---|---|\n| `browser` | 浏览器 Web 应用（JavaScript SDK） |\n| `ios` | 苹果 iOS 应用 |\n| `android` | Android 应用 |\n| `react-native` | React Native 应用 |\n| `flutter` | Flutter 应用 |\n| `kotlin-multiplatform` | Kotlin Multiplatform 应用 |\n| `roku` | Roku 频道应用 |\n| `unity` | Unity 应用 |\n| `miniprogram` | 微信小程序 |\n| `harmony` | 鸿蒙 HarmonyOS 应用 |\n| `electron` | Electron 桌面应用 |",
@@ -20042,15 +20700,15 @@
         "description": "单个返回列的元信息。",
         "properties": {
           "name": {
-            "description": "列名。",
+            "description": "列名或 `sql` 中写的别名；`time_series` 查询的时间桶列为 `ts`。",
             "type": "string"
           },
           "nullable": {
-            "description": "该列的值是否可能为 null。",
+            "description": "该列取值是否可能为 `null`。驱动无法判断时为 `true`。",
             "type": "boolean"
           },
           "type": {
-            "description": "该列的后端数据库类型名称。",
+            "description": "数据库驱动报告的列类型名，如 `VARCHAR`、`BIGINT`、`DOUBLE`、`DATETIME`。取决于所选列或表达式，取值集合不固定，可作为解析 `values` 的参考。",
             "type": "string"
           }
         },
@@ -20065,11 +20723,11 @@
         "description": "单个 RUM 数据查询定义。",
         "properties": {
           "disable_sampling": {
-            "description": "为 true 时，请求查询引擎尽可能避免采样。",
+            "description": "为 `true` 时始终查询全量数据，响应不会出现 `sampling`。为 `false`（默认）时，服务端可能对大时间跨度的聚合查询进行抽样。",
             "type": "boolean"
           },
           "dql": {
-            "description": "可选的 RUM DQL 过滤表达式，会和 SQL 校验一起使用。",
+            "description": "可选的 RUM DQL 过滤表达式，会被转换后以 `AND` 方式并入 `sql` 的 `WHERE` 子句。DQL 解析失败时在该查询的 `error` 中返回。",
             "type": "string"
           },
           "format": {
@@ -20087,28 +20745,28 @@
           },
           "interval": {
             "default": 3600,
-            "description": "`time_series` 查询的时间桶间隔，单位秒。",
+            "description": "`time_series` 查询的最小时间桶宽度，单位为**毫秒**，默认 3600（即 3.6 秒）。实际桶宽取固定档位中同时不小于该值和「时间跨度 ÷ `max_points`」的最小一档，并在结果的 `interval` 中返回。`table` 查询忽略此字段。",
             "exclusiveMinimum": 0,
             "format": "int64",
             "type": "integer"
           },
           "max_points": {
             "default": 1226,
-            "description": "`time_series` 查询最多返回的点数。",
+            "description": "`time_series` 查询的时间桶数量上限，默认 1226。服务端会放大桶宽，使时间范围内的桶数不超过该值。`table` 查询忽略此字段。",
             "exclusiveMinimum": 0,
             "format": "int64",
             "type": "integer"
           },
           "search_after_ctx": {
-            "description": "上一次表格查询返回的不透明游标，用于继续分页。",
+            "description": "上一次响应返回的 `search_after_ctx`，用于获取同一 `table` 查询的下一页。仅对不含聚合、带 `ORDER BY` 且无 `OFFSET` 的查询生效。传入无效值会导致该查询失败。",
             "type": "string"
           },
           "sql": {
-            "description": "要执行的 RUM SQL 查询。",
+            "description": "RUM SQL `SELECT` 语句。`FROM` 填写数据表名（`sessions`、`views`、`actions`、`errors`、`resources`、`long_tasks`、`vitals`、`issues`、`sourcemaps`），列名为 `POST /rum/field/list` 返回的 `field_key`。服务端会自动追加账户与时间范围过滤。",
             "type": "string"
           },
           "time_zone": {
-            "description": "计算时间函数时使用的 IANA 时区名称，例如 `Asia/Shanghai`。",
+            "description": "IANA 时区名，如 `Asia/Shanghai`，用于让 `time_series` 的时间桶边界按当地时间对齐；不传时按 UTC 对齐。`table` 查询忽略此字段；无效时区会使整个请求返回 `InvalidParameter`。",
             "type": "string"
           }
         },
@@ -20128,7 +20786,7 @@
           },
           "error": {
             "$ref": "#/components/schemas/DutyError",
-            "description": "子查询失败的错误详情；查询成功时省略。"
+            "description": "查询在请求校验通过后失败时返回（表或列不存在、`dql` 或 `search_after_ctx` 无效、数据库报错），错误码固定为 `InternalError`。查询成功时不返回。"
           }
         },
         "type": "object"
@@ -20176,14 +20834,14 @@
         "description": "单个 RUM 数据查询返回的行数据和元信息。",
         "properties": {
           "fields": {
-            "description": "返回值矩阵的列元信息。",
+            "description": "列元数据，每个返回列一项，顺序与 `values` 一致。`time_series` 查询的第一列为 `ts`。",
             "items": {
               "$ref": "#/components/schemas/RumDataFieldMeta"
             },
             "type": "array"
           },
           "interval": {
-            "description": "时序查询实际使用的时间桶间隔，单位秒；`table` 格式查询时省略。",
+            "description": "`time_series` 查询实际使用的时间桶宽度，单位为**毫秒**。`table` 查询不返回此字段。",
             "format": "int64",
             "type": "integer"
           },
@@ -20192,14 +20850,17 @@
             "description": "采样元信息；查询未使用采样时省略。"
           },
           "search_after_ctx": {
-            "description": "用于继续表格查询分页的不透明游标；非游标分页的表格查询或没有更多分页时省略。",
+            "description": "不含聚合、带 `ORDER BY` 且无 `OFFSET` 的 `table` 查询的下一页游标。仅当本页行数达到 `LIMIT` 时返回，否则不返回。",
             "type": "string"
           },
           "values": {
-            "description": "查询返回的行数据。每一行按下标与 `fields` 对齐。",
+            "description": "按列组织的结果值：`values[i]` 是列 `fields[i]` 在所有行上的取值列表。查询无结果时各列为 `null`。日期时间值以 RFC 3339 字符串返回。",
             "items": {
               "items": {},
-              "type": "array"
+              "type": [
+                "array",
+                "null"
+              ]
             },
             "type": "array"
           }
@@ -20218,7 +20879,7 @@
             "type": "boolean"
           },
           "scale_factor": {
-            "description": "将采样计数放大为全量估算值时使用的倍率。",
+            "description": "将抽样结果换算为全量估计值的倍数。`values` 中的 `COUNT`、`SUM`、`COUNT(DISTINCT)` 列已乘以该值；其他聚合按抽样数据的计算结果原样返回。",
             "type": "number"
           }
         },
@@ -20236,13 +20897,13 @@
             "type": "string"
           },
           "description": {
-            "description": "规则描述，最多 512 个字符。",
+            "description": "规则描述，最多 512 个字符，不传时为空字符串。",
             "maxLength": 512,
             "type": "string"
           },
           "filters": {
             "$ref": "#/components/schemas/RumErrorIngestionOrFilters",
-            "description": "用于匹配错误的过滤条件（OR-of-ANDs 结构）；命中的错误会被丢弃，不再采集入库。"
+            "description": "用于匹配错误的过滤条件（OR-of-ANDs 结构）。命中的错误仍会入库，但不会被归入任何问题。"
           },
           "rule_name": {
             "description": "规则名称，1-128 个字符。",
@@ -20285,11 +20946,11 @@
         "description": "单条过滤条件，匹配错误的某一个字段。",
         "properties": {
           "key": {
-            "description": "字段 key。取值范围：`error.usr_id`、`error.usr_email`、`error.error_type`、`error.error_message`、`error.error_stack`、`error.view_url`、`error.env`、`error.version`、`error.service`、`error.browser_name`、`error.browser_version`、`error.fingerprint`、`error.is_crash`，或以 `context.` 为前缀、最多三级嵌套的自定义上下文字段。",
+            "description": "要匹配的字段。可选 `error.usr_id`、`error.usr_email`、`error.error_type`、`error.error_message`、`error.error_stack`、`error.view_url`、`error.env`、`error.version`、`error.service`、`error.browser_name`、`error.browser_version`、`error.fingerprint`、`error.is_crash`（取值为 `true` 或 `false`），或以 `context.` 开头、指向错误自定义上下文的路径。上下文对象按点号展开，最多 3 级（`context.a.b.c`）；更深的对象按其 JSON 文本比较，数组类型的值无法匹配。",
             "type": "string"
           },
           "oper": {
-            "description": "匹配方式：`IN` 表示字段值命中 `vals` 中任意一项即匹配，`NOTIN` 表示都不命中才匹配。",
+            "description": "匹配方式：\n- `IN`：字段值命中 `vals` 中任意一项即匹配；错误中不存在的上下文字段永不匹配。\n- `NOTIN`：字段值与 `vals` 中每一项都不命中才匹配；错误中不存在的上下文字段总是匹配。",
             "enum": [
               "IN",
               "NOTIN"
@@ -20297,7 +20958,7 @@
             "type": "string"
           },
           "vals": {
-            "description": "待匹配的取值列表，至少 1 项。每项为精确字符串，或使用通配符（`*`/`?`）、正则（以 `/` 包裹）、`cidr:` 前缀、`num:lt|le|gt|ge:` 前缀表示的特殊匹配模式。",
+            "description": "待匹配的取值列表，至少 1 项。每项可以是：精确字符串（区分大小写）；使用 `*`/`?` 的通配符模式（需匹配整个值）；以 `/` 包裹的正则（未加锚点时匹配值中任意位置）；`cidr:<网段>`（字段值按 IP 解析）；或 `num:lt|le|gt|ge:<数字>`（字段值按数字解析，非数字不匹配）。",
             "items": {
               "type": "string"
             },
@@ -20316,28 +20977,28 @@
         "description": "某一历史版本下，应用全部规则的快照。",
         "properties": {
           "rules": {
-            "description": "此版本下应用的完整规则列表。",
+            "description": "生成此版本的那次变更之前，该应用全部未删除规则的完整列表。应用创建第一条规则时生成的版本中该列表为空。",
             "items": {
               "$ref": "#/components/schemas/RumErrorIngestionRuleSnapshotItem"
             },
             "type": "array"
           },
           "updated_at": {
-            "description": "快照生成时间，Unix 毫秒时间戳。",
+            "description": "生成此版本的那次变更发生的时间，Unix 毫秒时间戳。",
             "format": "int64",
             "type": "integer"
           },
           "updated_by": {
-            "description": "触发此次快照的成员 ID。",
+            "description": "做出此次变更（生成此版本）的成员 ID。",
             "format": "int64",
             "type": "integer"
           },
           "updated_by_name": {
-            "description": "触发此次快照的成员名称。",
+            "description": "该成员在变更时的显示名称。",
             "type": "string"
           },
           "version": {
-            "description": "历史版本号，从 1 开始递增。",
+            "description": "历史版本号，从 1 开始，每次写操作加 1。可传给 `POST /rum/error-ingestion/rules/history/revert` 进行回滚。",
             "type": "integer"
           }
         },
@@ -20359,20 +21020,23 @@
           },
           "asc": {
             "default": false,
-            "description": "按升序排序，默认按降序排序。",
+            "description": "`true` 为升序；`false`（默认）为降序，最新的在前。",
             "type": "boolean"
           },
           "limit": {
             "default": 20,
-            "description": "每页条数，默认 20，服务端上限 100；小于等于 0 时回退为默认值。",
+            "description": "每页条数。默认 20；超过 100 时按 100 处理，小于等于 0 时回退为 20。",
             "format": "int64",
-            "maximum": 100,
             "type": "integer"
           },
           "orderby": {
             "default": "updated_at",
-            "description": "排序字段：`updated_at` 或 `version`；无法识别的值会回退为 `updated_at`。",
-            "type": "string"
+            "description": "排序字段：\n- `updated_at`：生成该版本的变更时间（默认）。\n- `version`：版本号。\n传入其他值时回退为 `updated_at`。",
+            "type": "string",
+            "enum": [
+              "updated_at",
+              "version"
+            ]
           },
           "p": {
             "default": 0,
@@ -20391,7 +21055,7 @@
         "description": "分页返回的错误采集规则历史。",
         "properties": {
           "has_next_page": {
-            "description": "是否还有下一页历史记录。",
+            "description": "本页之后还有更多版本时为 `true`。",
             "type": "boolean"
           },
           "items": {
@@ -20402,7 +21066,7 @@
             "type": "array"
           },
           "total": {
-            "description": "该应用的历史版本总数。",
+            "description": "该应用历史版本的总数（不受分页影响）。",
             "format": "int64",
             "type": "integer"
           }
@@ -20444,7 +21108,7 @@
         "type": "object"
       },
       "RumErrorIngestionOrFilters": {
-        "description": "OR-of-ANDs 过滤器集合：外层数组为 OR，一个错误只要匹配其中任意一个内层 AND 组即视为命中该规则。",
+        "description": "OR-of-ANDs 过滤器集合：外层数组为 OR，一个错误只要匹配其中任意一个内层 AND 组即视为命中该规则。外层数组为空时规则永不命中；内层出现空 AND 组时会命中所有错误。",
         "items": {
           "description": "AND 组：仅当组内每个条件都匹配时，该组才算命中。",
           "items": {
@@ -20477,20 +21141,20 @@
         "description": "错误采集规则。",
         "properties": {
           "created_at": {
-            "description": "规则创建时间，Unix 毫秒时间戳。",
+            "description": "规则创建时间，Unix 毫秒时间戳；通过历史回滚恢复的规则会重置为回滚时间。",
             "format": "int64",
             "type": "integer"
           },
           "description": {
-            "description": "规则描述，最多 512 个字符。",
+            "description": "规则描述，最多 512 个字符；未填写时为空字符串。",
             "type": "string"
           },
           "filters": {
             "$ref": "#/components/schemas/RumErrorIngestionOrFilters",
-            "description": "该规则的过滤条件。"
+            "description": "规则的过滤条件。命中的错误会入库，但不会被归入任何问题。"
           },
           "rule_id": {
-            "description": "规则 ID。",
+            "description": "规则 ID，由服务端在 `create` 时生成，更新和历史回滚后保持不变。",
             "type": "string"
           },
           "rule_name": {
@@ -20498,7 +21162,7 @@
             "type": "string"
           },
           "status": {
-            "description": "规则当前状态。",
+            "description": "规则状态：\n- `enabled`：对新上报的错误生效。\n- `disabled`：规则保留但不生效。",
             "enum": [
               "enabled",
               "disabled"
@@ -20506,7 +21170,7 @@
             "type": "string"
           },
           "updated_at": {
-            "description": "规则最近更新时间，Unix 毫秒时间戳。",
+            "description": "最近一次更新、启用或禁用的时间，Unix 毫秒时间戳；通过历史回滚恢复的规则会重置为回滚时间。",
             "format": "int64",
             "type": "integer"
           }
@@ -20544,7 +21208,7 @@
         "description": "历史快照中的一条规则记录，包含内部存储字段（区别于 `list` 返回的精简字段集）。",
         "properties": {
           "account_id": {
-            "description": "账户 ID。",
+            "description": "规则所属账户的 ID。",
             "format": "int64",
             "type": "integer"
           },
@@ -20563,12 +21227,12 @@
             "type": "integer"
           },
           "deleted_at": {
-            "description": "软删除时间，Unix 毫秒时间戳；未删除时为 0。",
+            "description": "软删除时间，Unix 毫秒时间戳。此处恒为 `0`，因为快照只包含未删除的规则。",
             "format": "int64",
             "type": "integer"
           },
           "description": {
-            "description": "规则描述。",
+            "description": "该规则在此快照版本中的描述；未填写时为空字符串。",
             "type": "string"
           },
           "filters": {
@@ -20576,20 +21240,20 @@
             "description": "该规则在此快照版本中的过滤条件。"
           },
           "id": {
-            "description": "内部行 ID。",
+            "description": "内部存储行 ID，任何接口都不接受该值，请使用 `rule_id`。通过历史回滚恢复规则后会变化。",
             "format": "int64",
             "type": "integer"
           },
           "rule_id": {
-            "description": "规则 ID。",
+            "description": "规则 ID，与 `list` 返回的该规则 ID 相同。",
             "type": "string"
           },
           "rule_name": {
-            "description": "规则名称。",
+            "description": "该规则在此快照版本中的名称。",
             "type": "string"
           },
           "status": {
-            "description": "该规则在此快照版本中的状态。",
+            "description": "该规则在此快照版本中的状态：\n- `enabled`：对新上报的错误生效。\n- `disabled`：规则保留但不生效。",
             "enum": [
               "enabled",
               "disabled"
@@ -20602,7 +21266,7 @@
             "type": "integer"
           },
           "updated_by": {
-            "description": "最近更新者成员 ID。",
+            "description": "此快照之前最后一次修改该规则的成员 ID。",
             "format": "int64",
             "type": "integer"
           }
@@ -20667,7 +21331,7 @@
         "description": "分面值分布统计的请求参数。",
         "properties": {
           "dql": {
-            "description": "统计前应用的 RUM DQL 过滤表达式。",
+            "description": "统计前应用的 RUM DQL 过滤表达式，其中的字段会按 `scope` 校验。",
             "type": "string"
           },
           "end_time": {
@@ -20677,11 +21341,11 @@
             "type": "integer"
           },
           "facet_key": {
-            "description": "要统计值分布的字段键；必须是该 `scope` 下已注册的字段，可用字段可通过 `POST /rum/field/list` 查询。",
+            "description": "要统计取值分布的字段 key，如 `error_type`。必须是所给 `scope` 下 `show_type` 为 `list`、`value_type` 非数组类型的分面字段。可通过 `POST /rum/field/list` 查询候选字段。",
             "type": "string"
           },
           "facet_value": {
-            "description": "设置后，统计前会先过滤 `facet_key` 等于该值的事件。接受字符串、数字或布尔值。"
+            "description": "传入时只统计 `facet_key` 等于该值的事件。JSON 类型须与字段的 `value_type` 一致（字符串、数字或布尔），不一致返回 `InvalidParameter`。不传时排除取值为 `null` 的事件。"
           },
           "kind": {
             "description": "符号类型，仅在 `scope` 为 `sourcemap` 时使用，且只对 `android`/`harmony` 有意义：`mapping`（默认）选择 ProGuard/R8 mapping 或 ArkTS Sourcemap，`native` 选择 native .so 符号。",
@@ -20713,7 +21377,7 @@
             "type": "string"
           },
           "sql": {
-            "description": "仅含 WHERE 子句（无 SELECT）的 SQL 附加过滤条件。",
+            "description": "额外的 SQL 过滤条件，只写 `WHERE` 后面的条件本身（不含 `WHERE` 关键字），如 `env = 'prod'`。出现 `SELECT` 会被拒绝。",
             "type": "string"
           },
           "start_time": {
@@ -20805,7 +21469,7 @@
             "type": "string"
           },
           "group": {
-            "description": "字段的展示分组。",
+            "description": "控制台中对字段分组展示所用的组名，如 `error`、`action`、`device`；无分组时为空。",
             "type": "string"
           },
           "is_facet": {
@@ -20817,7 +21481,7 @@
             "type": "boolean"
           },
           "scopes": {
-            "description": "该字段所属的 RUM scope 列表。",
+            "description": "该字段所属的 RUM scope，取值与请求中的 `scopes` 相同（如 `error`、`issue`）。",
             "items": {
               "type": "string"
             },
@@ -20832,15 +21496,34 @@
             "type": "string"
           },
           "status": {
-            "description": "字段状态，如 `active`。",
+            "description": "字段状态。`enabled`：字段在用；`disabled`：字段已定义但被停用。已删除的字段不会返回。",
+            "enum": [
+              "enabled",
+              "disabled"
+            ],
             "type": "string"
           },
           "unit_family": {
-            "description": "计量单位族，如 `time`、`bytes`。无量纲字段为空。",
+            "description": "计量单位族。`time`：时长或时间戳（具体见 `unit_name`）；`bytes`：字节大小；无量纲字段为空字符串。",
+            "enum": [
+              "",
+              "time",
+              "bytes"
+            ],
             "type": "string"
           },
           "unit_name": {
-            "description": "具体计量单位，如 `millisecond`、`byte`。",
+            "description": "存储值的单位。时长：`nanosecond`、`microsecond`、`millisecond`、`second`；时间戳：`unix_millisecond`、`unix_second`；大小：`byte`；无量纲字段为空字符串。大多数内置时长字段以 `nanosecond` 存储。",
+            "enum": [
+              "",
+              "nanosecond",
+              "microsecond",
+              "millisecond",
+              "second",
+              "unix_millisecond",
+              "unix_second",
+              "byte"
+            ],
             "type": "string"
           },
           "value_type": {
@@ -20941,11 +21624,11 @@
             "type": "boolean"
           },
           "console_origin": {
-            "description": "用于拼接 `issue_url` 列的控制台地址，如 `https://console.flashcat.cloud`；服务无法自行推断（SaaS、私有化与 dev 环境地址不同）。",
+            "description": "用于拼接 `issue_url` 列的控制台地址，如 `https://console.flashcat.cloud`，末尾的 `/` 会被去掉；服务无法自行推断。不传时 `issue_url` 只包含路径 `/rum/error-tracking/issue/<issue_id>`。",
             "type": "string"
           },
           "dql": {
-            "description": "DQL 高级过滤查询，不能与 `sql` 同时使用。",
+            "description": "DQL 高级过滤查询。字段名必须属于 `issue` 范围（可通过 `POST /rum/field/list` 并传 `scopes: [\"issue\"]` 查询）；不带字段名的全文检索词匹配错误信息。不能与 `sql` 同时使用。",
             "type": "string"
           },
           "end_time": {
@@ -20958,7 +21641,7 @@
             "type": "boolean"
           },
           "export_fields": {
-            "description": "要导出的 CSV 列，按出现顺序排列。未知键会被参数校验拒绝；传空数组则使用默认列集。\n\n| 值 | 列内容 |\n|---|---|\n| `issue_id` | Issue ID |\n| `issue_url` | Issue 详情页的控制台链接（基于 `console_origin` 拼接） |\n| `application_name` | 所属应用名称 |\n| `service` | 服务名 |\n| `error_type` | 错误类型 |\n| `error_message` | 错误信息 |\n| `status` | 处理状态 |\n| `severity` | 严重性 |\n| `is_crash` | 是否导致崩溃 |\n| `error_count` | 错误发生次数 |\n| `session_count` | 受影响会话数 |\n| `first_seen_at` | 首次出现时间（按 `time_zone` 渲染） |\n| `first_seen_version` | 首次出现时的应用版本 |\n| `last_seen_at` | 最近出现时间（按 `time_zone` 渲染） |\n| `last_seen_version` | 最近出现时的应用版本 |\n| `versions` | 涉及的所有版本 |\n| `suspected_cause` | 疑似根因分类 |\n| `resolved_at` | 解决时间（按 `time_zone` 渲染） |",
+            "description": "要导出的 CSV 列，按出现顺序排列。未知键会被参数校验拒绝，重复键会被去掉。传空数组或不传时导出下表中除 `sample_first_*` 外的全部列。\n\n| 值 | 列内容 |\n|---|---|\n| `issue_id` | Issue ID |\n| `issue_url` | Issue 详情页的控制台链接（基于 `console_origin` 拼接） |\n| `application_name` | 所属应用名称 |\n| `service` | 服务名 |\n| `error_type` | 错误类型 |\n| `error_message` | 错误信息 |\n| `status` | 处理状态 |\n| `severity` | 严重性 |\n| `is_crash` | 是否导致崩溃 |\n| `error_count` | 错误发生次数 |\n| `session_count` | 受影响会话数 |\n| `first_seen_at` | 首次出现时间（按 `time_zone` 渲染） |\n| `first_seen_version` | 首次出现时的应用版本 |\n| `last_seen_at` | 最近出现时间（按 `time_zone` 渲染） |\n| `last_seen_version` | 最近出现时的应用版本 |\n| `versions` | 涉及的所有版本 |\n| `suspected_cause` | 疑似根因分类 |\n| `resolved_at` | 解决时间（按 `time_zone` 渲染）；未解决时为空 |\n| `sample_time` | 时间窗内最近一条错误事件的事件发生时间（按 `time_zone` 渲染） |\n| `sample_version` | 时间窗内最近一条错误事件的应用版本 |\n| `sample_view` | 时间窗内最近一条错误事件的页面名称，名称为空时为页面 URL |\n| `sample_session_id` | 时间窗内最近一条错误事件的会话 ID |\n| `sample_device` | 时间窗内最近一条错误事件的设备品牌与型号 |\n| `sample_os` | 时间窗内最近一条错误事件的操作系统名称与版本 |\n| `sample_browser` | 时间窗内最近一条错误事件的浏览器名称与版本 |\n| `sample_stack` | 时间窗内最近一条错误事件的错误堆栈，最多保留前 20 行 |\n| `sample_first_time` | 时间窗内最早一条错误事件的事件发生时间（按 `time_zone` 渲染） |\n| `sample_first_version` | 时间窗内最早一条错误事件的应用版本 |\n| `sample_first_view` | 时间窗内最早一条错误事件的页面名称，名称为空时为页面 URL |\n| `sample_first_session_id` | 时间窗内最早一条错误事件的会话 ID |\n| `sample_first_device` | 时间窗内最早一条错误事件的设备品牌与型号 |\n| `sample_first_os` | 时间窗内最早一条错误事件的操作系统名称与版本 |\n| `sample_first_browser` | 时间窗内最早一条错误事件的浏览器名称与版本 |\n| `sample_first_stack` | 时间窗内最早一条错误事件的错误堆栈，最多保留前 20 行 |",
             "items": {
               "enum": [
                 "issue_id",
@@ -20978,7 +21661,23 @@
                 "last_seen_version",
                 "versions",
                 "suspected_cause",
-                "resolved_at"
+                "resolved_at",
+                "sample_time",
+                "sample_version",
+                "sample_view",
+                "sample_session_id",
+                "sample_device",
+                "sample_os",
+                "sample_browser",
+                "sample_stack",
+                "sample_first_time",
+                "sample_first_version",
+                "sample_first_view",
+                "sample_first_session_id",
+                "sample_first_device",
+                "sample_first_os",
+                "sample_first_browser",
+                "sample_first_stack"
               ],
               "type": "string"
             },
@@ -21007,11 +21706,11 @@
             "type": "integer"
           },
           "sql": {
-            "description": "SQL 式高级过滤查询，不能与 `dql` 同时使用。",
+            "description": "SQL 风格的 WHERE 条件，用于高级过滤，不带 `WHERE` 关键字（例如 `error_count > 100`）。字段名必须属于 `issue` 范围；包含 `SELECT` 的内容会被拒绝。不能与 `dql` 同时使用。",
             "type": "string"
           },
           "start_time": {
-            "description": "时间范围起始，Unix 毫秒时间戳。",
+            "description": "时间范围起点，Unix 毫秒时间戳（秒级时间戳会被拒绝）。默认按 Issue 创建时间匹配，`by_intersection` 为 `true` 时按活跃区间匹配。",
             "format": "int64",
             "type": "integer"
           },
@@ -21052,7 +21751,7 @@
             "type": "array"
           },
           "time_zone": {
-            "description": "渲染 CSV 时间戳所用的 IANA 时区名，如 `Asia/Shanghai`、`UTC`；默认 `Asia/Shanghai`。",
+            "description": "用于渲染 CSV 时间列和文件名的 IANA 时区，如 `Asia/Shanghai` 或 `UTC`。默认 `Asia/Shanghai`。时区名无效时返回 `InvalidParameter`。",
             "type": "string"
           }
         },
@@ -21103,7 +21802,7 @@
                 "type": "string"
               },
               "type": {
-                "description": "错误类型，来自错误事件的 `error_type` 字段（由 SDK 上报）。",
+                "description": "SDK 在错误事件 `error_type` 字段中上报的错误类型，为自由文本而非固定取值。浏览器错误为 JavaScript 异常名，如 `Error`、`TypeError`、`ReferenceError`。",
                 "type": "string"
               }
             },
@@ -21153,7 +21852,7 @@
             "type": "object"
           },
           "regression": {
-            "description": "回溯元数据，仅在已解决的 Issue 再次出现时存在。",
+            "description": "回归记录。仅在已解决的 Issue 因错误再次出现被重新打开后存在；Issue 再次被解决时清除。",
             "properties": {
               "regressed_at": {
                 "description": "检测到回溯的时间，Unix 毫秒时间戳。",
@@ -21173,15 +21872,23 @@
             "type": "object"
           },
           "resolved_at": {
-            "description": "标记为已解决的时间，Unix 时间戳（毫秒）；未解决时为 0。",
+            "description": "Issue 被标记为已解决（用户操作或系统自动）的时间，Unix 毫秒时间戳；未解决时为 `0`。",
             "format": "int64",
             "type": "integer"
           },
           "resolved_by": {
-            "description": "将 Issue 标记为已解决的用户 Person ID；未解决时为 0。",
+            "description": "将 Issue 标记为已解决的用户 Person ID；未解决或由系统自动解决时为 `0`。",
             "format": "int64",
             "type": "integer"
           },
+          "resolve_mode": {
+            "description": "Issue 已解决后错误再次出现时的处理方式：`any` 表示再次出现即重新打开；`version` 表示仅当错误出现在该 Issue 未出现过的应用版本中时才重新打开（不带版本的错误总会重新打开）。新建 Issue 和自动解决使用 `version`；通过 `POST /rum/issue/update` 解决且未传 `resolve_mode` 时设为 `any`。",
+            "enum": [
+              "any",
+              "version"
+            ],
+            "type": "string"
+          },
           "service": {
             "description": "产生该 Issue 的服务名，来自错误事件的 `service` 字段。",
             "type": "string"
@@ -21192,7 +21899,7 @@
             "type": "integer"
           },
           "severity": {
-            "description": "Issue 严重性：`Critical`（严重）、`Warning`（警告）、`Info`（提示）；引入严重性之前创建的历史 Issue 为空字符串。",
+            "description": "Issue 严重性，在 Issue 创建时确定：由第一条命中的已启用预设严重性规则决定（见 `POST /rum/issue/preset-severity/rules/list`），未命中时使用内置规则（崩溃为 `Critical`，其他错误按环境与错误信息关键词打分）。错误只会归入严重性相同或更高的已有 Issue，因此同一错误可能按严重性分成多个 Issue。引入严重性之前创建的旧 Issue 为空字符串。",
             "enum": [
               "Critical",
               "Warning",
@@ -21201,7 +21908,7 @@
             "type": "string"
           },
           "status": {
-            "description": "Issue 的处理状态；已软删除（`deleted`）的 Issue 不会出现在响应中。\n\n| 值 | 含义 |\n|---|---|\n| `for_review` | 待处理 |\n| `reviewed` | 已查看 |\n| `ignored` | 已忽略 |\n| `resolved` | 已解决 |",
+            "description": "Issue 的处理状态；已软删除（`deleted`）的 Issue 不会返回。错误 14 天未再出现，或应用发布了不再上报该错误的新版本时，系统会自动将 Issue 置为已解决；已解决的 Issue 再次出现错误时会重新打开为 `for_review`（见 `resolve_mode`）。\n\n| 值 | 含义 |\n|---|---|\n| `for_review` | 待处理 |\n| `reviewed` | 已查看 |\n| `ignored` | 已忽略 |\n| `resolved` | 已解决 |",
             "enum": [
               "for_review",
               "reviewed",
@@ -21219,7 +21926,7 @@
                 "type": "integer"
               },
               "reason": {
-                "description": "根因判定的理由说明，仅 AI 自动分析时生成；未启用 AI 或尚未分析时为空字符串。",
+                "description": "根因判定的自由文本说明，仅由 AI 分析生成；未启用 AI 分析、尚未分析或根因由用户指定时为空字符串。",
                 "type": "string"
               },
               "source": {
@@ -21256,14 +21963,40 @@
             "type": "integer"
           },
           "versions": {
-            "description": "该 Issue 出现过错误的应用版本列表（去重）；事件未携带版本信息时可能包含空字符串。",
+            "description": "该 Issue 出现过错误的应用版本列表（去重）；事件未携带版本信息时可能包含空字符串。从未记录版本列表的 Issue 返回 `null`。",
             "items": {
               "type": "string"
             },
-            "type": "array"
+            "type": [
+              "array",
+              "null"
+            ]
           }
         },
-        "type": "object"
+        "type": "object",
+        "required": [
+          "team_id",
+          "issue_id",
+          "application_id",
+          "application_name",
+          "service",
+          "status",
+          "error_count",
+          "session_count",
+          "is_crash",
+          "age",
+          "resolved_at",
+          "resolved_by",
+          "resolve_mode",
+          "created_at",
+          "updated_at",
+          "first_seen",
+          "last_seen",
+          "error",
+          "suspected_cause",
+          "versions",
+          "severity"
+        ]
       },
       "RumIssueListRequest": {
         "description": "查询 Issue 列表的过滤参数。",
@@ -21284,7 +22017,7 @@
             "type": "boolean"
           },
           "dql": {
-            "description": "DQL 高级过滤查询，不能与 `sql` 同时使用。",
+            "description": "DQL 高级过滤查询。字段名必须属于 `issue` 范围（可通过 `POST /rum/field/list` 并传 `scopes: [\"issue\"]` 查询）；不带字段名的全文检索词匹配错误信息。不能与 `sql` 同时使用。",
             "type": "string"
           },
           "end_time": {
@@ -21319,11 +22052,11 @@
             "type": "integer"
           },
           "sql": {
-            "description": "SQL 式高级过滤查询，不能与 `dql` 同时使用。",
+            "description": "SQL 风格的 WHERE 条件，用于高级过滤，不带 `WHERE` 关键字（例如 `error_count > 100`）。字段名必须属于 `issue` 范围；包含 `SELECT` 的内容会被拒绝。不能与 `dql` 同时使用。",
             "type": "string"
           },
           "start_time": {
-            "description": "时间范围起始，Unix 毫秒时间戳。",
+            "description": "时间范围起点，Unix 毫秒时间戳（秒级时间戳会被拒绝）。默认按 Issue 创建时间匹配，`by_intersection` 为 `true` 时按活跃区间匹配。",
             "format": "int64",
             "type": "integer"
           },
@@ -21398,7 +22131,7 @@
             "type": "string"
           },
           "status": {
-            "description": "新状态。设为 `resolved` 会记录解决时间与操作人；从 `resolved` 改为其他状态会将其清除。\n\n| 值 | 含义 |\n|---|---|\n| `for_review` | 待处理 |\n| `reviewed` | 已查看 |\n| `ignored` | 已忽略 |\n| `resolved` | 已解决 |",
+            "description": "新状态。将未解决的 Issue 设为 `resolved` 会记录解决时间与操作人并清除 `regression`；从 `resolved` 改为其他状态会清除解决时间与操作人。不传则保持当前状态。\n\n| 值 | 含义 |\n|---|---|\n| `for_review` | 待处理 |\n| `reviewed` | 已查看 |\n| `ignored` | 已忽略 |\n| `resolved` | 已解决 |",
             "enum": [
               "for_review",
               "reviewed",
@@ -21407,6 +22140,14 @@
             ],
             "type": "string"
           },
+          "resolve_mode": {
+            "description": "Issue 已解决后错误再次出现时的处理方式。只在同时传 `status: resolved` 时生效，此时不传默认为 `any`；传其他状态时忽略。\n\n| 值 | 含义 |\n|---|---|\n| `any` | 错误再次出现即重新打开 |\n| `version` | 仅当错误出现在该 Issue 未出现过的应用版本中时才重新打开；不带版本的错误总会重新打开 |",
+            "enum": [
+              "any",
+              "version"
+            ],
+            "type": "string"
+          },
           "suspected_cause": {
             "description": "新的疑似原因；设置后原因来源会标记为 `user`（用户指定），覆盖自动判定结果。取值：\n\n| 值 | 含义 |\n|---|---|\n| `api.failed_request` | API/接口请求失败 |\n| `network.error` | 网络连接错误 |\n| `code.exception` | 代码异常 |\n| `code.invalid_object_access` | 非法对象访问 |\n| `code.invalid_argument` | 非法参数 |\n| `unknown` | 未知原因 |",
             "enum": [
@@ -21438,7 +22179,7 @@
             "type": "string"
           },
           "filters": {
-            "description": "OR-of-ANDs 过滤结构：外层数组之间为 OR，内层数组内为 AND。当至少一个内层 AND 分组完全匹配时，该规则命中此错误。",
+            "description": "OR-of-ANDs 过滤结构：外层数组之间为 OR，内层数组内为 AND。当至少一个内层 AND 分组完全匹配时，该规则命中此错误。外层为空数组时永不命中；内层为空分组时命中所有错误。",
             "items": {
               "items": {
                 "$ref": "#/components/schemas/RumPresetSeverityRuleFilterCondition"
@@ -21497,7 +22238,7 @@
         "description": "AND 分组内的单条过滤条件。",
         "properties": {
           "key": {
-            "description": "过滤属性键。预设严重性规则仅支持以下 Error 级别属性。\n\n| 值 | 含义 |\n|---|---|\n| `error.usr_id` | 用户 ID |\n| `error.usr_email` | 用户邮箱 |\n| `error.view_url` | 错误发生页面的完整 URL |\n| `error.view_url_path` | 错误发生页面的 URL 路径 |\n| `error.error_type` | 错误类型 |\n| `error.error_message` | 错误信息 |\n| `error.env` | 环境（如 production/staging） |\n| `error.service` | 服务名 |\n| `error.device_type` | 设备类型 |\n| `error.os_name` | 操作系统名称 |\n| `error.browser_name` | 浏览器名称 |\n| `error.is_crash` | 是否为崩溃错误（布尔） |",
+            "description": "过滤属性键。预设严重性规则仅支持以下 Error 级别属性。\n\n| 值 | 含义 |\n|---|---|\n| `error.usr_id` | 用户 ID |\n| `error.usr_email` | 用户邮箱 |\n| `error.view_url` | 错误发生页面的完整 URL |\n| `error.view_url_path` | 错误发生页面的 URL 路径 |\n| `error.error_type` | 错误类型 |\n| `error.error_message` | 错误信息 |\n| `error.env` | 环境（如 production/staging） |\n| `error.service` | 服务名 |\n| `error.device_type` | 设备类型 |\n| `error.os_name` | 操作系统名称 |\n| `error.browser_name` | 浏览器名称 |\n| `error.is_crash` | 是否为崩溃错误，按字符串 `true` 或 `false` 比较 |",
             "enum": [
               "error.usr_id",
               "error.usr_email",
@@ -21515,7 +22256,7 @@
             "type": "string"
           },
           "oper": {
-            "description": "匹配语义：`IN` 表示字段值匹配 `vals` 中任意一个即命中；`NOTIN` 表示一个都不匹配才命中（字段缺失时也视为命中）。",
+            "description": "匹配语义：`IN` 表示属性值匹配 `vals` 中任意一个即命中；`NOTIN` 表示一个都不匹配才命中。错误未携带的属性按空字符串参与比较。",
             "enum": [
               "IN",
               "NOTIN"
@@ -21523,7 +22264,7 @@
             "type": "string"
           },
           "vals": {
-            "description": "待匹配的值列表。每一项支持精确字符串匹配、通配符（`*`/`?`）、正则（用 `/.../` 包裹）、面向 IP 类字段的 CIDR（`cidr:10.0.0.0/8`），或数值比较（如 `num:gt:100`、`num:le:50`）。",
+            "description": "待匹配的值列表，至少一项且不能为空字符串。每一项可以是：区分大小写的整值精确匹配；含 `*`/`?` 的通配符（匹配整个值）；用 `/.../` 包裹的正则（未用 `^`/`$` 锚定时匹配值中任意位置）；面向 IP 类值的 `cidr:<网段>`，如 `cidr:10.0.0.0/8`；或数值比较 `num:<op>:<数字>`，`op` 为 `lt`、`le`、`gt`、`ge` 之一，如 `num:gt:100`。`error.is_crash` 请使用 `true` 或 `false`。",
             "items": {
               "type": "string"
             },
@@ -21693,7 +22434,7 @@
             "type": "string"
           },
           "filters": {
-            "description": "OR-of-ANDs 过滤结构：外层数组之间为 OR，内层数组内为 AND。当至少一个内层 AND 分组完全匹配时，该规则命中此错误。",
+            "description": "OR-of-ANDs 过滤结构：外层数组之间为 OR，内层数组内为 AND。当至少一个内层 AND 分组完全匹配时，该规则命中此错误。外层为空数组时永不命中；内层为空分组时命中所有错误。",
             "items": {
               "items": {
                 "$ref": "#/components/schemas/RumPresetSeverityRuleFilterCondition"
@@ -21797,7 +22538,7 @@
             "type": "string"
           },
           "filters": {
-            "description": "OR-of-ANDs 过滤结构：外层数组之间为 OR，内层数组内为 AND。当至少一个内层 AND 分组完全匹配时，该规则命中此错误。",
+            "description": "OR-of-ANDs 过滤结构：外层数组之间为 OR，内层数组内为 AND。当至少一个内层 AND 分组完全匹配时，该规则命中此错误。外层为空数组时永不命中；内层为空分组时命中所有错误。",
             "items": {
               "items": {
                 "$ref": "#/components/schemas/RumPresetSeverityRuleFilterCondition"
@@ -21921,7 +22662,7 @@
             ]
           },
           "filters": {
-            "description": "OR-of-ANDs 过滤结构：外层数组之间为 OR，内层数组内为 AND。当至少一个内层 AND 分组完全匹配时，该规则命中此错误。",
+            "description": "新的 OR-of-ANDs 过滤结构，整体替换当前结构。不传或传 `null` 则保持不变。外层数组之间为 OR，内层数组内为 AND；外层为空数组时永不命中，内层为空分组时命中所有错误。",
             "items": {
               "items": {
                 "$ref": "#/components/schemas/RumPresetSeverityRuleFilterCondition"
@@ -21981,15 +22722,15 @@
         "type": "object"
       },
       "RumReplayForegroundPeriod": {
-        "description": "App 处于前台的一段时间区间（移动端会话）。",
+        "description": "视图处于前台（获得焦点）的一段时间。",
         "properties": {
           "end": {
-            "description": "前台区间结束的 Unix 毫秒时间戳。",
+            "description": "前台时间段的结束，表示距 `view_id` 对应视图开始时刻的**纳秒**数（不是 Unix 时间戳）。",
             "format": "int64",
             "type": "integer"
           },
           "start": {
-            "description": "前台区间开始的 Unix 毫秒时间戳。",
+            "description": "前台时间段的开始，表示距 `view_id` 对应视图开始时刻的**纳秒**数（不是 Unix 时间戳）。",
             "format": "int64",
             "type": "integer"
           },
@@ -22003,7 +22744,7 @@
       "RumReplaySession": {
         "properties": {
           "end": {
-            "description": "会话结束（或活跃会话最后更新）的 Unix 毫秒时间戳。",
+            "description": "会话结束时间（Unix 毫秒）：取会话记录的结束时间与所返回视图最晚结束时间中的较大值。",
             "format": "int64",
             "type": "integer"
           },
@@ -22012,7 +22753,7 @@
             "type": "boolean"
           },
           "server_time_delta": {
-            "description": "客户端与 Flashduty 服务端之间的时钟偏移（毫秒），用于校正客户端时间戳。",
+            "description": "恒为 `0`：时间戳按客户端记录原样返回，不做时钟偏差校正。",
             "format": "int64",
             "type": "integer"
           },
@@ -22044,7 +22785,20 @@
       "RumReplayView": {
         "properties": {
           "container_source": {
-            "description": "该视图嵌套展示时，容器应用的 SDK 平台（如原生应用内的 WebView）；未嵌套时省略。",
+            "description": "嵌入该视图的宿主应用的 SDK 平台（例如原生应用中的 WebView）。视图未被嵌入时不返回。\n\n| 取值 | 含义 |\n|---|---|\n| `browser` | Web 浏览器应用 |\n| `ios` | Apple iOS 应用 |\n| `android` | Android 应用 |\n| `react-native` | React Native 应用 |\n| `flutter` | Flutter 应用 |\n| `kotlin-multiplatform` | Kotlin Multiplatform 应用 |\n| `roku` | Roku 频道应用 |\n| `unity` | Unity 应用 |\n| `miniprogram` | 微信小程序 |\n| `harmony` | HarmonyOS 应用 |\n| `electron` | Electron 桌面应用 |",
+            "enum": [
+              "browser",
+              "ios",
+              "android",
+              "react-native",
+              "flutter",
+              "kotlin-multiplatform",
+              "roku",
+              "unity",
+              "miniprogram",
+              "harmony",
+              "electron"
+            ],
             "type": "string"
           },
           "container_view_id": {
@@ -22061,7 +22815,7 @@
             "type": "boolean"
           },
           "loading_type": {
-            "description": "进入该视图的方式，如 `initial_load`、`route_change`。",
+            "description": "SDK 上报的视图进入方式。Web：`initial_load`、`route_change`；移动端：`activity_display`、`activity_redisplay`、`fragment_display`、`fragment_redisplay`、`view_controller_display`、`view_controller_redisplay`。未上报时为空。",
             "type": "string"
           },
           "name": {
@@ -22069,7 +22823,7 @@
             "type": "string"
           },
           "server_time_delta": {
-            "description": "客户端与 Flashduty 服务端之间的时钟偏移（毫秒），用于校正客户端时间戳。",
+            "description": "恒为 `0`：时间戳按客户端记录原样返回，不做时钟偏差校正。",
             "format": "int64",
             "type": "integer"
           },
@@ -22185,7 +22939,7 @@
             "type": "integer"
           },
           "session_investigate.free_cnt": {
-            "description": "每个应用、每个计费窗口的异常追踪会话免费额度。",
+            "description": "每个应用在每个计费窗口内的 investigate（错误追踪） 会话免费额度。负数表示不限量。",
             "format": "int64",
             "type": "integer"
           },
@@ -22195,11 +22949,11 @@
             "type": "integer"
           },
           "session_limit_reached": {
-            "description": "`version=free` 的账户在所有应用的免费会话额度合计用尽后为 `true`；非免费套餐恒为 `false`。",
+            "description": "`version=free` 的账户在当前窗口内的 investigate 或 replay 会话数达到「单应用免费额度 × 应用数」时为 `true`。非免费套餐、或账户尚无应用时始终为 `false`。",
             "type": "boolean"
           },
           "session_measure.free_cnt": {
-            "description": "每个应用、每个计费窗口的性能监控会话免费额度。",
+            "description": "每个应用在每个计费窗口内的 measure（性能） 会话免费额度。负数表示不限量。",
             "format": "int64",
             "type": "integer"
           },
@@ -22209,7 +22963,7 @@
             "type": "integer"
           },
           "session_replay.free_cnt": {
-            "description": "每个应用、每个计费窗口的会话重放免费额度。",
+            "description": "每个应用在每个计费窗口内的 会话回放 会话免费额度。负数表示不限量。",
             "format": "int64",
             "type": "integer"
           },
@@ -22296,7 +23050,7 @@
             "description": "录制该会话的设备。"
           },
           "foreground_periods": {
-            "description": "会话内的前台时间区间（仅移动端会话；Web 端为空）。",
+            "description": "视图处于前台（获得焦点）的时间段，汇总自所有返回的视图。SDK 未上报时为空数组。",
             "items": {
               "$ref": "#/components/schemas/RumReplayForegroundPeriod"
             },
@@ -22307,7 +23061,7 @@
             "description": "会话的起止时间与状态。"
           },
           "views": {
-            "description": "会话内录制的全部视图，按时间顺序排列。",
+            "description": "该会话中带有回放数据的视图，按开始时间升序排列。",
             "items": {
               "$ref": "#/components/schemas/RumReplayView"
             },
@@ -22324,7 +23078,7 @@
             "type": "string"
           },
           "ts": {
-            "description": "会话起始时间的 Unix 毫秒时间戳。可选；当 `session_id` 在不同时间窗口内被复用时用于区分。",
+            "description": "会话开始时间，Unix 毫秒时间戳，可选。传入时必须与会话开始时间完全一致；用于在 `session_id` 被复用时选中其中一个会话。",
             "exclusiveMinimum": 0,
             "format": "int64",
             "type": "integer"
@@ -22354,7 +23108,7 @@
             "type": "string"
           },
           "ts": {
-            "description": "Unix 毫秒时间戳。设置该字段且 `search_after_ctx` 为空时，将从该时间点之前最近的一个全量快照分段开始，而非从头开始。",
+            "description": "Unix 毫秒时间戳。传入且 `search_after_ctx` 为空时，从该时间点及之前最近的全量快照分段开始分页（最多向前查找 4 小时）；找不到时从头开始。",
             "exclusiveMinimum": 0,
             "format": "int64",
             "type": "integer"
@@ -22377,14 +23131,14 @@
         "description": "分段的预签名下载地址，仅当 `url_mode` 为 `true` 时返回。",
         "properties": {
           "items": {
-            "description": "预签名、限时（1 小时内有效）的下载地址，用于获取每个分段的原始压缩字节。",
+            "description": "各分段对象的预签名下载地址，1 小时内有效。对象内容为 zlib 压缩数据，解压后即为分段 JSON。",
             "items": {
               "type": "string"
             },
             "type": "array"
           },
           "search_after_ctx": {
-            "description": "用于下一次调用 `search_after_ctx` 的分页游标。为该会话最后一页时为空。",
+            "description": "下一次调用时作为 `search_after_ctx` 传入的游标。本页返回满 `limit` 个分段时即会给出（下一页可能为空）；不足 `limit` 时为空字符串。",
             "type": "string"
           }
         },
@@ -22394,11 +23148,11 @@
         "description": "发送 RUM 告警样例 Webhook 的参数。",
         "properties": {
           "application_id": {
-            "description": "RUM 应用 ID，可通过 `POST /rum/application/list` 获取。",
+            "description": "RUM 应用 ID，其名称会写入样例事件的 `labels.application_name`。调用者须对该应用有编辑权。可通过 `POST /rum/application/list` 获取应用 ID。",
             "type": "string"
           },
           "webhook_url": {
-            "description": "接收样例告警事件的 Webhook URL。",
+            "description": "接收样例告警事件的 Webhook URL，必须使用 `http` 或 `https`。不会被保存：如需保存，请通过 `POST /rum/application/update` 设置 `alerting.webhook_url`。",
             "format": "uri",
             "type": "string"
           }
@@ -22413,15 +23167,15 @@
         "description": "Webhook 测试投递结果。",
         "properties": {
           "message": {
-            "description": "成功时为 `ok`，失败时为投递错误信息。",
+            "description": "成功时为 `ok`。否则：对端返回错误状态码时为 `unexpected status <code>`，未收到响应时为 `request failed: <error>`。",
             "type": "string"
           },
           "ok": {
-            "description": "Webhook 端点是否接受了样例事件。",
+            "description": "对端（跟随重定向后）返回 400 以下状态码时为 `true`，否则为 `false`。",
             "type": "boolean"
           },
           "status_code": {
-            "description": "Webhook 端点返回的 HTTP 状态码。未收到响应时为 0。",
+            "description": "最后一次投递尝试的 HTTP 状态码。未收到响应（连接错误或超时）时为 `0`。",
             "type": "integer"
           }
         },
@@ -22587,108 +23341,135 @@
         "type": "object"
       },
       "ScheduleByPersonResponse": {
+        "type": "object",
         "description": "成员的值班状态：正在值班的班次、下一次值班，以及其参与的全部启用排班。",
         "properties": {
           "current": {
-            "$ref": "#/components/schemas/MemberOncallInterval"
+            "oneOf": [
+              {
+                "$ref": "#/components/schemas/MemberOncallInterval"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "正在进行的班次；成员当前不在班时为 `null`。"
           },
           "next": {
-            "$ref": "#/components/schemas/MemberOncallInterval"
+            "oneOf": [
+              {
+                "$ref": "#/components/schemas/MemberOncallInterval"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "下一次值班（不含 `end_at`）；45 天内没有时为 `null`。"
           },
           "schedules": {
+            "type": "array",
             "description": "该成员参与的全部启用排班。",
             "items": {
               "$ref": "#/components/schemas/MemberScheduleItem"
-            },
-            "type": "array"
+            }
           }
         },
         "required": [
           "schedules"
-        ],
-        "type": "object"
+        ]
       },
       "ScheduleCalculatedLayer": {
+        "type": "object",
         "description": "单个分层的计算结果。",
+        "required": [
+          "layer_name",
+          "name",
+          "mode",
+          "schedules"
+        ],
         "properties": {
           "layer_name": {
-            "description": "分层显示名称。",
-            "type": "string"
-          },
-          "mode": {
-            "description": "分层模式：0 = 普通轮转，1 = 覆盖。",
-            "type": "integer"
+            "type": "string",
+            "description": "分层名称；`final_schedule` 中为空字符串。"
           },
           "name": {
-            "description": "分层内部名称。",
-            "type": "string"
+            "type": "string",
+            "description": "与 `layer_name` 相同。"
+          },
+          "mode": {
+            "type": "integer",
+            "enum": [
+              0,
+              1
+            ],
+            "description": "来源分层的类型：`0` = 轮转分层，`1` = 覆盖分层。`final_schedule` 中恒为 `0`。"
           },
           "schedules": {
-            "description": "计算出的班次；该层无排班时为 null。",
-            "items": {
-              "$ref": "#/components/schemas/ScheduleCalculatedSchedule"
-            },
             "type": [
               "array",
               "null"
-            ]
+            ],
+            "items": {
+              "$ref": "#/components/schemas/ScheduleCalculatedSchedule"
+            },
+            "description": "计算出的班次；该层无排班时为 null。"
           }
-        },
-        "required": [
-          "layer_name",
-          "name",
-          "mode",
-          "schedules"
-        ],
-        "type": "object"
+        }
       },
       "ScheduleCalculatedSchedule": {
+        "type": "object",
         "description": "分层内计算出的值班时段。",
+        "required": [
+          "start",
+          "end",
+          "group",
+          "index"
+        ],
         "properties": {
+          "start": {
+            "type": "integer",
+            "format": "int64",
+            "description": "时段开始时间（Unix 秒）。"
+          },
           "end": {
-            "description": "时段结束时间（Unix 秒）。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "时段结束时间（Unix 秒）。"
           },
           "group": {
-            "$ref": "#/components/schemas/ScheduleGroup",
-            "description": "覆盖该班次的值班组；null 表示覆盖空档。"
-          },
-          "index": {
-            "description": "轮转内索引。",
-            "type": "integer"
-          },
-          "start": {
-            "description": "时段开始时间（Unix 秒）。",
-            "format": "int64",
-            "type": "integer"
+            "oneOf": [
+              {
+                "$ref": "#/components/schemas/ScheduleGroup"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "该班次的值班组；为 `null` 表示该时段无人值班。"
+          },
+          "index": {
+            "type": "integer",
+            "description": "该班次来源分层在值班表分层列表中的位置（从 0 开始）。"
           }
-        },
-        "required": [
-          "start",
-          "end",
-          "group",
-          "index"
-        ],
-        "type": "object"
+        }
       },
       "ScheduleDayMask": {
+        "type": "object",
         "description": "按星期几生效的掩码配置。",
         "properties": {
           "repeat": {
-            "description": "参与轮转的星期数（0 = 周日）。与 restrict_mode = 2（按周）互斥。",
-            "items": {
-              "maximum": 6,
-              "minimum": 0,
-              "type": "integer"
-            },
             "type": [
               "array",
               "null"
-            ]
+            ],
+            "items": {
+              "type": "integer",
+              "minimum": 0,
+              "maximum": 6
+            },
+            "description": "分层值班的星期：`0` = 周日 … `6` = 周六，按值班表时区计算。为空或包含全部 7 天表示每天。不能与 `restrict_mode` 为 2 同时使用。"
           }
-        },
-        "type": "object"
+        }
       },
       "ScheduleEmptyObject": {
         "description": "空响应。",
@@ -22727,45 +23508,45 @@
         "type": "object"
       },
       "ScheduleGroup": {
+        "type": "object",
         "description": "值班分层内的值班组。",
+        "required": [
+          "group_name",
+          "name",
+          "members",
+          "start",
+          "end"
+        ],
         "properties": {
-          "end": {
-            "description": "值班组结束时间（Unix 秒）。",
-            "format": "int64",
-            "type": "integer"
-          },
           "group_name": {
-            "description": "值班组显示名称，仅设置旧字段 name 时为 null。",
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "值班组显示名称，仅设置旧字段 name 时为 null。"
+          },
+          "name": {
+            "type": "string",
+            "description": "值班组内部名称。"
           },
           "members": {
-            "description": "值班组成员。",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/ScheduleMember"
             },
-            "type": "array"
-          },
-          "name": {
-            "description": "值班组内部名称。",
-            "type": "string"
+            "description": "值班组成员。"
           },
           "start": {
-            "description": "值班组开始时间（Unix 秒）。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "计算结果中该组班次的开始时间（Unix 秒）；在分层定义中为 `0`，作为输入时忽略。"
+          },
+          "end": {
+            "type": "integer",
+            "format": "int64",
+            "description": "计算结果中该组班次的结束时间（Unix 秒）；在分层定义中为 `0`，作为输入时忽略。"
           }
-        },
-        "required": [
-          "group_name",
-          "name",
-          "members",
-          "start",
-          "end"
-        ],
-        "type": "object"
+        }
       },
       "ScheduleIDResponse": {
         "description": "创建值班表后返回的 ID 响应。",
@@ -22782,21 +23563,21 @@
         "type": "object"
       },
       "ScheduleIDsBodyRequest": {
-        "description": "携带值班表 ID 列表的请求体（删除/启用/禁用使用）。",
+        "type": "object",
+        "description": "携带值班表 ID 列表的请求。",
+        "required": [
+          "schedule_ids"
+        ],
         "properties": {
           "schedule_ids": {
-            "description": "要操作的值班表 ID 列表，可通过 `POST /schedule/list` 获取。",
+            "type": "array",
             "items": {
-              "format": "int64",
-              "type": "integer"
+              "type": "integer",
+              "format": "int64"
             },
-            "type": "array"
+            "description": "要操作的值班表 ID 列表，可通过 `POST /schedule/list` 获取。"
           }
-        },
-        "required": [
-          "schedule_ids"
-        ],
-        "type": "object"
+        }
       },
       "ScheduleIDsRequest": {
         "description": "批量查询值班表使用的请求体。",
@@ -22816,686 +23597,832 @@
         "type": "object"
       },
       "ScheduleImNotify": {
+        "type": "object",
         "description": "IM Webhook 通知条目。",
+        "required": [
+          "type",
+          "settings"
+        ],
         "properties": {
+          "type": {
+            "type": "string",
+            "enum": [
+              "feishu",
+              "dingtalk",
+              "wecom",
+              "slack",
+              "telegram",
+              "zoom",
+              "feishu_app",
+              "dingtalk_app",
+              "slack_app",
+              "teams_app"
+            ],
+            "description": "通知发送目标：\n- `feishu`、`dingtalk`、`wecom`、`slack`：由 `settings.token` 指定的群机器人 webhook。\n- `telegram`：使用 `settings.token` 的机器人，发送到 `settings.chat_ids`。\n- `zoom`：使用 `settings.token` 和 `settings.verify_token` 的 Zoom 机器人。\n- `feishu_app`、`dingtalk_app`、`slack_app`、`teams_app`：通过 IM 集成（`settings.data_source_id`）发送到 `settings.chat_ids` 中的群聊。\n其他取值会被保存但不会发送。"
+          },
           "settings": {
             "$ref": "#/components/schemas/ScheduleImNotifySettings",
             "description": "Webhook 渠道配置。"
-          },
-          "type": {
-            "description": "IM 提供方类型（如 feishu_app、dingtalk_app、wecom_app、teams_app、slack_app）。",
-            "type": "string"
           }
-        },
-        "required": [
-          "type",
-          "settings"
-        ],
-        "type": "object"
+        }
       },
       "ScheduleImNotifySettings": {
+        "type": "object",
         "description": "IM Webhook 通知通道配置。",
+        "required": [
+          "token",
+          "alias",
+          "data_source_id",
+          "chat_ids",
+          "verify_token",
+          "sign_secret"
+        ],
         "properties": {
+          "token": {
+            "type": "string",
+            "description": "`feishu`、`dingtalk`、`wecom`、`slack`、`telegram`、`zoom` 类型使用的机器人 webhook token；`*_app` 类型为空。"
+          },
           "alias": {
-            "description": "通道别名。",
-            "type": "string"
+            "type": "string",
+            "description": "该条目的显示别名；发送时不使用。"
+          },
+          "data_source_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "`*_app` 类型使用的 IM 集成 ID；机器人类型为 `0`。"
           },
           "chat_ids": {
-            "description": "会话 ID 列表。",
+            "type": "array",
             "items": {
               "type": "string"
             },
-            "type": "array"
+            "description": "目标会话 ID：`*_app` 类型为 IM 集成中的群聊 ID，`telegram` 类型为 Telegram chat ID。"
           },
-          "data_source_id": {
-            "description": "数据源 ID。",
-            "format": "int64",
-            "type": "integer"
+          "verify_token": {
+            "type": "string",
+            "description": "校验 token，`zoom` 类型使用。"
           },
           "sign_secret": {
-            "description": "签名密钥。",
-            "type": "string"
-          },
-          "token": {
-            "description": "Webhook token。",
-            "type": "string"
-          },
-          "verify_token": {
-            "description": "验签 token。",
-            "type": "string"
+            "type": "string",
+            "description": "机器人签名密钥，随条目保存。"
           }
-        },
-        "required": [
-          "token",
-          "alias",
-          "data_source_id",
-          "chat_ids",
-          "verify_token",
-          "sign_secret"
-        ],
-        "type": "object"
+        }
       },
       "ScheduleInfoRequest": {
-        "description": "值班表详情请求。start/end 指定计算值班分层的时间窗口，跨度必须小于 45 天。",
+        "type": "object",
+        "description": "值班表详情请求。`start`/`end` 指定计算班次的窗口，相差不超过 45 天。",
+        "required": [
+          "schedule_id",
+          "start",
+          "end"
+        ],
         "properties": {
-          "end": {
-            "description": "窗口结束时间（Unix 秒，10 位）。",
-            "format": "int64",
-            "type": "integer"
-          },
           "schedule_id": {
-            "description": "值班表 ID，可通过 `POST /schedule/list` 获取。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "值班表 ID，可通过 `POST /schedule/list` 获取。"
           },
           "start": {
-            "description": "窗口开始时间（Unix 秒，10 位）。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "窗口开始时间（Unix 秒，10 位）。"
+          },
+          "end": {
+            "type": "integer",
+            "format": "int64",
+            "description": "窗口结束时间（Unix 秒，10 位）。"
           }
-        },
+        }
+      },
+      "ScheduleItem": {
+        "type": "object",
+        "description": "info、list、infos、self、preview 接口返回的值班表。哪些计算字段有值取决于具体接口，见各接口说明。",
         "required": [
+          "id",
+          "name",
+          "account_id",
+          "group_id",
+          "time_zone",
+          "disabled",
+          "create_at",
+          "create_by",
+          "update_at",
+          "update_by",
+          "layers",
+          "schedule_layers",
+          "final_schedule",
+          "notify",
           "schedule_id",
-          "start",
-          "end"
+          "schedule_name",
+          "team_id",
+          "description",
+          "layer_schedules",
+          "status",
+          "cur_oncall",
+          "next_oncall"
         ],
-        "type": "object"
-      },
-      "ScheduleItem": {
-        "description": "/schedule/info、/schedule/preview、/schedule/list 返回的完整值班表详情。",
         "properties": {
-          "account_id": {
-            "description": "账户 ID。",
+          "id": {
+            "type": [
+              "integer",
+              "null"
+            ],
             "format": "int64",
-            "type": "integer"
+            "description": "值班表 ID。/schedule/preview 返回时为 null。"
           },
-          "create_at": {
-            "description": "创建时间（Unix 秒）。",
-            "format": "int64",
-            "type": "integer"
+          "name": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "旧版值班表名称字段（与 schedule_name 同义）。/schedule/preview 返回时为 null。"
           },
-          "create_by": {
-            "description": "创建人 ID。",
+          "account_id": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
-          },
-          "cur_oncall": {
-            "$ref": "#/components/schemas/ScheduleOncallGroup",
-            "description": "当前正在值班的组，无人值班时为 null。"
+            "description": "值班表所属账户的 ID。"
           },
-          "description": {
-            "description": "值班表描述。/schedule/preview 返回时为 null。",
+          "group_id": {
             "type": [
-              "string",
+              "integer",
               "null"
-            ]
+            ],
+            "format": "int64",
+            "description": "旧版团队/组 ID。/schedule/preview 返回时为 null。"
+          },
+          "time_zone": {
+            "type": "string",
+            "description": "值班表的 IANA 时区（如 `Asia/Shanghai`），交接时间、限制时段、星期和定时通知都按该时区计算。创建时设置，之后不可修改。空字符串表示未设置，按 `Asia/Shanghai` 计算。"
           },
           "disabled": {
-            "description": "禁用标记（0 = 启用，1 = 禁用），已废弃。/schedule/preview 返回时为 null。",
             "type": [
               "integer",
               "null"
-            ]
+            ],
+            "enum": [
+              0,
+              1,
+              null
+            ],
+            "description": "值班表是否禁用：`0` = 启用，`1` = 禁用（禁用的值班表不发送换班通知，并会被 `/schedule/self`、`/schedule/by-person` 跳过）。与 `status` 取值相同。`/schedule/preview` 中除非请求传入，否则为 `null`。"
           },
-          "end": {
-            "description": "时间窗口结束（Unix 秒）。为 0（未请求窗口）时省略。",
+          "create_at": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
-          },
-          "field": {
-            "description": "旧版字段更新接口使用的字段名。",
-            "type": "string"
+            "description": "创建时间（Unix 秒）。"
           },
-          "final_schedule": {
-            "$ref": "#/components/schemas/ScheduleCalculatedLayer",
-            "description": "所有分层合并后的最终值班结果。"
+          "create_by": {
+            "type": "integer",
+            "format": "int64",
+            "description": "创建人 ID。"
           },
-          "group_id": {
-            "description": "旧版团队/组 ID。/schedule/preview 返回时为 null。",
+          "update_at": {
+            "type": "integer",
             "format": "int64",
-            "type": [
-              "integer",
-              "null"
-            ]
+            "description": "更新时间（Unix 秒）。"
           },
-          "id": {
-            "description": "值班表 ID。/schedule/preview 返回时为 null。",
+          "update_by": {
+            "type": "integer",
             "format": "int64",
-            "type": [
-              "integer",
-              "null"
-            ]
+            "description": "更新人 ID。"
           },
-          "layer_schedules": {
-            "description": "schedule_layers 的兼容别名，未计算时为 null。",
-            "items": {
-              "$ref": "#/components/schemas/ScheduleCalculatedLayer"
-            },
+          "layers": {
             "type": [
               "array",
               "null"
-            ]
-          },
-          "layers": {
-            "description": "值班表定义的轮转层。未加载层信息时为 null（例如 `/schedule/infos`，或未传 start/end 的 `/schedule/list`）。",
+            ],
             "items": {
               "$ref": "#/components/schemas/ScheduleLayer"
             },
+            "description": "值班表定义的轮转层。未加载层信息时为 null（例如 `/schedule/infos`，或未传 start/end 的 `/schedule/list`）。"
+          },
+          "schedule_layers": {
             "type": [
               "array",
               "null"
-            ]
+            ],
+            "items": {
+              "$ref": "#/components/schemas/ScheduleCalculatedLayer"
+            },
+            "description": "请求窗口内各个未隐藏分层的班次。未计算窗口时为 `null`（`/schedule/infos`、`/schedule/self`、未传 `start`/`end` 的 `/schedule/list`）。"
           },
-          "name": {
-            "description": "旧版值班表名称字段（与 schedule_name 同义）。/schedule/preview 返回时为 null。",
-            "type": [
-              "string",
-              "null"
-            ]
+          "final_schedule": {
+            "$ref": "#/components/schemas/ScheduleCalculatedLayer",
+            "description": "窗口内所有分层合并后的时间线：分层重叠时，覆盖分层优先于轮转分层，靠后的分层优先于靠前的分层。在 `/schedule/self` 中只保留调用者本人的班次。未计算时为空（`schedules` 为 `null`）。"
           },
-          "next_oncall": {
-            "$ref": "#/components/schemas/ScheduleOncallGroup",
-            "description": "下一次值班的组，未知时为 null。"
+          "start": {
+            "type": "integer",
+            "format": "int64",
+            "description": "窗口开始时间（Unix 秒）。仅 `/schedule/preview` 回显，其他接口省略。"
+          },
+          "end": {
+            "type": "integer",
+            "format": "int64",
+            "description": "窗口结束时间（Unix 秒）。仅 `/schedule/preview` 回显，其他接口省略。"
           },
           "notify": {
-            "$ref": "#/components/schemas/ScheduleNotify",
-            "description": "通知配置，未配置时为 null。"
+            "oneOf": [
+              {
+                "$ref": "#/components/schemas/ScheduleNotify"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "换班通知配置；未配置时为 `null`。"
           },
           "schedule_id": {
-            "description": "值班表 ID。`/schedule/preview` 返回时为 null。",
-            "format": "int64",
             "type": [
               "integer",
               "null"
-            ]
-          },
-          "schedule_layers": {
-            "description": "按请求时间窗口计算出的各层排班，未计算时为 null。",
-            "items": {
-              "$ref": "#/components/schemas/ScheduleCalculatedLayer"
-            },
-            "type": [
-              "array",
-              "null"
-            ]
+            ],
+            "format": "int64",
+            "description": "值班表 ID。`/schedule/preview` 返回时为 null。"
           },
           "schedule_name": {
-            "description": "值班表显示名称。/schedule/preview 返回时为 null。",
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "值班表显示名称。/schedule/preview 返回时为 null。"
           },
-          "start": {
-            "description": "时间窗口开始（Unix 秒）。为 0（未请求窗口）时省略。",
+          "team_id": {
+            "type": [
+              "integer",
+              "null"
+            ],
             "format": "int64",
-            "type": "integer"
+            "description": "所属团队 ID。/schedule/preview 返回时为 null。"
           },
-          "status": {
-            "description": "旧版状态字段，已废弃。/schedule/preview 返回时为 null。",
+          "description": {
             "type": [
-              "integer",
+              "string",
               "null"
-            ]
+            ],
+            "description": "值班表描述。/schedule/preview 返回时为 null。"
           },
-          "team_id": {
-            "description": "所属团队 ID。/schedule/preview 返回时为 null。",
-            "format": "int64",
+          "layer_schedules": {
+            "type": [
+              "array",
+              "null"
+            ],
+            "items": {
+              "$ref": "#/components/schemas/ScheduleCalculatedLayer"
+            },
+            "description": "与 `schedule_layers` 内容相同，仅 `/schedule/info` 和 `/schedule/preview` 填充；其他接口为 `null`。"
+          },
+          "status": {
             "type": [
               "integer",
               "null"
-            ]
+            ],
+            "enum": [
+              0,
+              1,
+              null
+            ],
+            "description": "`disabled` 的镜像：`0` = 启用，`1` = 禁用。在 `/schedule/update` 中通过该字段启用或禁用值班表。`/schedule/preview` 中除非请求传入，否则为 `null`。"
           },
-          "update_at": {
-            "description": "更新时间（Unix 秒）。",
-            "format": "int64",
-            "type": "integer"
+          "cur_oncall": {
+            "oneOf": [
+              {
+                "$ref": "#/components/schemas/ScheduleOncallGroup"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "此刻正在进行的班次；无人值班或接口不计算时（`/schedule/infos`、`/schedule/self`、未传窗口的 `/schedule/list`）为 `null`。"
           },
-          "update_by": {
-            "description": "更新人 ID。",
-            "format": "int64",
-            "type": "integer"
+          "next_oncall": {
+            "oneOf": [
+              {
+                "$ref": "#/components/schemas/ScheduleOncallGroup"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "当前班次之后第一个有人值班的班次；45 天内找不到或接口不计算时为 `null`。"
           }
-        },
+        }
+      },
+      "ScheduleLayer": {
+        "type": "object",
+        "description": "值班表中的一个分层。轮转分层（`mode` 为 0）在 `groups` 之间依次轮换；覆盖分层（`mode` 为 1）在 `layer_start` 到 `layer_end` 期间由第一个值班组值班。仅响应字段（`account_id`、`schedule_id`、`create_*`、`update_*`）在请求中会被忽略。",
         "required": [
-          "id",
-          "name",
           "account_id",
-          "group_id",
-          "disabled",
+          "name",
+          "schedule_id",
+          "hidden",
+          "mode",
+          "weight",
+          "groups",
+          "rotation_duration",
+          "handoff_time",
+          "enable_time",
+          "expire_time",
+          "restrict_mode",
+          "restrict_start",
+          "restrict_end",
+          "restrict_periods",
+          "day_mask",
           "create_at",
           "create_by",
           "update_at",
           "update_by",
-          "layers",
-          "schedule_layers",
-          "final_schedule",
-          "notify",
-          "schedule_id",
-          "schedule_name",
-          "team_id",
-          "description",
-          "layer_schedules",
-          "status",
-          "cur_oncall",
-          "next_oncall"
+          "fair_rotation",
+          "rotation_unit",
+          "rotation_value",
+          "mask_continuous_enabled"
         ],
-        "type": "object"
-      },
-      "ScheduleLayer": {
-        "description": "值班表中的单个分层。",
         "properties": {
           "account_id": {
-            "description": "账户 ID。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "分层所属账户的 ID，由服务端填写。"
           },
-          "create_at": {
-            "description": "创建时间（Unix 秒）。",
-            "format": "int64",
-            "type": "integer"
+          "name": {
+            "type": "string",
+            "description": "分层名称。`name` 与 `layer_name` 至少提供一个；都提供时以 `layer_name` 为准。"
           },
-          "create_by": {
-            "description": "创建人 ID。",
+          "schedule_id": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
-          },
-          "day_mask": {
-            "$ref": "#/components/schemas/ScheduleDayMask",
-            "description": "星期掩码。"
+            "description": "分层所属值班表的 ID，由服务端填写。"
           },
-          "enable_time": {
-            "description": "分层生效时间（Unix 秒）。",
-            "format": "int64",
-            "type": "integer"
+          "hidden": {
+            "type": "integer",
+            "enum": [
+              0,
+              1
+            ],
+            "description": "为 `1` 时该分层不出现在 `schedule_layers` 中，但其班次仍参与 `final_schedule` 的合并。`0`（默认）正常显示。"
           },
-          "expire_time": {
-            "description": "分层失效时间（Unix 秒，0 表示永不过期）。",
-            "format": "int64",
-            "type": "integer"
+          "mode": {
+            "type": "integer",
+            "description": "分层类型：\n- `0`：轮转分层——各值班组按 `rotation_unit`/`rotation_value` 依次轮换。\n- `1`：覆盖分层——`groups` 中第一个值班组在 `layer_start` 至 `layer_end` 整段时间值班，优先于轮转分层。",
+            "enum": [
+              0,
+              1
+            ]
           },
-          "fair_rotation": {
-            "description": "是否启用公平轮转。",
-            "type": "boolean"
+          "weight": {
+            "type": "integer",
+            "description": "按传入值保存；计算班次时不使用。"
           },
           "groups": {
-            "description": "参与轮转的值班组，未设置时为 null。",
-            "items": {
-              "$ref": "#/components/schemas/ScheduleGroup"
-            },
             "type": [
               "array",
               "null"
-            ]
+            ],
+            "items": {
+              "$ref": "#/components/schemas/ScheduleGroup"
+            },
+            "description": "分层的值班组，按轮换顺序排列。每个组需要 `group_name`（或 `name`），且每个成员槽位至少包含一人。`start`/`end` 作为输入时忽略。"
+          },
+          "rotation_duration": {
+            "type": "integer",
+            "format": "int64",
+            "description": "轮转时长（秒），是 `rotation_unit` + `rotation_value` 的旧版替代写法：只传该字段时服务端据此推算单位和数量（按整周、整天或整小时），只传后两者时服务端回填该字段（一个月按 30 天计）。"
           },
           "handoff_time": {
-            "description": "轮转交接时间，以一周内的秒数偏移表示（星期 x 86400 + 当日秒数），不是 Unix 绝对时间戳。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "按周轮转的交接时刻，表示自周一 00:00（值班表时区）起的秒数（`星期 × 86400 + 当日秒数`，周一 = 0 … 周日 = 6），不是 Unix 时间戳。用 `handoff` 设置更方便。"
           },
-          "hidden": {
-            "description": "是否在页面上隐藏（0 = 否，1 = 是）。",
-            "type": "integer"
+          "enable_time": {
+            "type": "integer",
+            "format": "int64",
+            "description": "分层生效时间（Unix 秒）。对轮转分层，其时分同时也是每天的交接时刻。传了 `layer_start` 时以其为准。"
           },
-          "layer_end": {
-            "description": "分层结束时间（Unix 秒）。null 表示无结束时间。",
+          "expire_time": {
+            "type": "integer",
             "format": "int64",
-            "type": [
-              "integer",
-              "null"
-            ]
+            "description": "分层失效时间（Unix 秒）；`0` 表示永不失效。不能早于 `enable_time`。传了 `layer_end` 时以其为准。"
           },
-          "layer_name": {
-            "description": "面向用户的层名称，未设置时为 null。",
-            "type": [
-              "string",
-              "null"
+          "restrict_mode": {
+            "type": "integer",
+            "description": "将分层限制在 `restrict_periods` 给出的时间窗口内：\n- `0`：不限制。\n- `1`：按天限制；偏移量为自 00:00 起的秒数（0–86400）。\n- `2`：按周限制；偏移量为自周一 00:00 起的秒数（0–604800）。不能与 `day_mask` 同时使用。\n窗口按值班表时区计算。",
+            "enum": [
+              0,
+              1,
+              2
             ]
           },
-          "layer_start": {
-            "description": "层生效时间（Unix 秒），未设置时为 null。",
+          "restrict_start": {
+            "type": "integer",
+            "format": "int64",
+            "description": "旧版单窗口的开始偏移（秒）；请改用 `restrict_periods`。"
+          },
+          "restrict_end": {
+            "type": "integer",
             "format": "int64",
+            "description": "旧版单窗口的结束偏移（秒）；请改用 `restrict_periods`。"
+          },
+          "restrict_periods": {
             "type": [
-              "integer",
+              "array",
               "null"
-            ]
+            ],
+            "items": {
+              "$ref": "#/components/schemas/ScheduleRestrictPeriod"
+            },
+            "description": "分层值班的时间窗口，含义由 `restrict_mode` 决定。窗口之外该分层无人值班。未设置时为 `null`。"
           },
-          "mask_continuous_enabled": {
-            "description": "是否启用连续掩码。",
-            "type": "boolean"
+          "day_mask": {
+            "$ref": "#/components/schemas/ScheduleDayMask",
+            "description": "轮转分层值班的星期。"
           },
-          "mode": {
-            "description": "分层模式：0 = 普通轮转，1 = 覆盖。",
-            "enum": [
-              0,
-              1
-            ],
-            "type": "integer"
+          "create_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "创建时间（Unix 秒）。"
           },
-          "name": {
-            "description": "分层内部名称。",
-            "type": "string"
+          "create_by": {
+            "type": "integer",
+            "format": "int64",
+            "description": "创建人 ID。"
           },
-          "restrict_end": {
-            "description": "旧版限制区间结束偏移（秒）。",
+          "update_at": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "更新时间（Unix 秒）。"
           },
-          "restrict_mode": {
-            "description": "限制模式：0 = 不限制，1 = day，2 = week。",
-            "enum": [
-              0,
-              1,
-              2
-            ],
-            "type": "integer"
+          "update_by": {
+            "type": "integer",
+            "format": "int64",
+            "description": "更新人 ID。"
           },
-          "restrict_periods": {
-            "description": "每个轮转周期内的限制时段，未设置时为 null。",
-            "items": {
-              "$ref": "#/components/schemas/ScheduleRestrictPeriod"
-            },
+          "layer_name": {
             "type": [
-              "array",
+              "string",
               "null"
-            ]
+            ],
+            "description": "控制台显示的分层名称；响应中与 `name` 相同。"
           },
-          "restrict_start": {
-            "description": "旧版限制区间开始偏移（秒）。",
+          "fair_rotation": {
+            "type": "boolean",
+            "description": "为 `true` 时，每一整轮的起始组依次后移一位，避免总由同一组开头。`false`（默认）每轮都从第一组开始。"
+          },
+          "layer_start": {
+            "type": [
+              "integer",
+              "null"
+            ],
             "format": "int64",
-            "type": "integer"
+            "description": "与 `enable_time` 相同；请求中优先于 `enable_time`。`enable_time` 为 0 时为 `null`。"
           },
-          "rotation_duration": {
-            "description": "轮转周期（秒）。",
+          "layer_end": {
+            "type": [
+              "integer",
+              "null"
+            ],
             "format": "int64",
-            "type": "integer"
+            "description": "与 `expire_time` 相同；请求中优先于 `expire_time`。`null` 表示永不结束。"
           },
           "rotation_unit": {
+            "type": "string",
             "description": "轮转单位。值班人按该单位依次轮换。\n| 值 | 含义 |\n|---|---|\n| `hour` | 按小时轮转。 |\n| `day` | 按天轮转。 |\n| `week` | 按周轮转。 |\n| `month` | 按月轮转。 |",
             "enum": [
               "hour",
               "day",
               "week",
               "month"
-            ],
-            "type": "string"
+            ]
           },
           "rotation_value": {
-            "description": "轮转数量（每周期的 rotation_unit 个数）。",
+            "type": "integer",
             "format": "int64",
-            "minimum": 0,
-            "type": "integer"
+            "description": "每个值班组连续值班多少个 `rotation_unit` 后交接。轮转分层需要提供该字段（配合 `rotation_unit`）或 `rotation_duration`。",
+            "minimum": 0
           },
-          "schedule_id": {
-            "description": "所属值班表 ID。",
-            "format": "int64",
-            "type": "integer"
+          "mask_continuous_enabled": {
+            "type": "boolean",
+            "description": "仅当 `day_mask` 选择了 1–6 个星期时生效。为 `true` 时，每个值班日从分层生效时刻的钟点起，到次日同一钟点止，而不是从零点到零点。"
           },
-          "update_at": {
-            "description": "更新时间（Unix 秒）。",
-            "format": "int64",
-            "type": "integer"
+          "starts_at": {
+            "type": "object",
+            "writeOnly": true,
+            "description": "仅用于请求。以值班表时区的墙钟日期和时刻表示分层开始时间，覆盖 `layer_start`/`enable_time`。",
+            "required": [
+              "date"
+            ],
+            "properties": {
+              "date": {
+                "type": "string",
+                "description": "日期，格式 `YYYY-MM-DD`。"
+              },
+              "time": {
+                "type": "string",
+                "description": "时刻，格式 `HH:MM`（24 小时制），默认 `00:00`。"
+              }
+            }
           },
-          "update_by": {
-            "description": "更新人 ID。",
-            "format": "int64",
-            "type": "integer"
+          "ends_at": {
+            "type": "object",
+            "writeOnly": true,
+            "description": "仅用于请求。以值班表时区的墙钟日期和时刻表示分层结束时间，覆盖 `layer_end`/`expire_time`。传 `{\"date\": \"\"}` 表示永不结束。",
+            "properties": {
+              "date": {
+                "type": "string",
+                "description": "日期，格式 `YYYY-MM-DD`。"
+              },
+              "time": {
+                "type": "string",
+                "description": "时刻，格式 `HH:MM`（24 小时制），默认 `00:00`。"
+              }
+            }
           },
-          "weight": {
-            "description": "分层权重，用于排序。",
-            "type": "integer"
+          "handoff": {
+            "type": "object",
+            "writeOnly": true,
+            "required": [
+              "weekday",
+              "time"
+            ],
+            "description": "仅用于请求。以值班表时区表示的交接星期和时刻；会设置 `handoff_time` 以及 `enable_time` 的时分。",
+            "properties": {
+              "weekday": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 7,
+                "description": "ISO 星期：`1` = 周一 … `7` = 周日。"
+              },
+              "time": {
+                "type": "string",
+                "description": "时刻，格式 `HH:MM`（24 小时制）。"
+              }
+            }
+          },
+          "restricts_wall": {
+            "type": "array",
+            "writeOnly": true,
+            "description": "仅用于请求。以值班表时区墙钟时间表示的限制窗口，会替换 `restrict_periods`。`restrict_mode` 为 1 时使用 `from`/`to`（`to` 为 `00:00` 表示到当天结束）；为 2 时还需设置 `from_day`/`to_day`。`restrict_mode` 为 0 时会被拒绝。",
+            "items": {
+              "type": "object",
+              "properties": {
+                "from_day": {
+                  "type": "integer",
+                  "minimum": 1,
+                  "maximum": 7,
+                  "description": "窗口开始的 ISO 星期（仅 `restrict_mode` 为 2 时）：`1` = 周一 … `7` = 周日。"
+                },
+                "from": {
+                  "type": "string",
+                  "description": "窗口开始时刻，`HH:MM`。"
+                },
+                "to_day": {
+                  "type": "integer",
+                  "minimum": 1,
+                  "maximum": 7,
+                  "description": "窗口结束的 ISO 星期（仅 `restrict_mode` 为 2 时）。"
+                },
+                "to": {
+                  "type": "string",
+                  "description": "窗口结束时刻，`HH:MM`。"
+                }
+              }
+            }
           }
-        },
-        "required": [
-          "account_id",
-          "name",
-          "schedule_id",
-          "hidden",
-          "mode",
-          "weight",
-          "groups",
-          "rotation_duration",
-          "handoff_time",
-          "enable_time",
-          "expire_time",
-          "restrict_mode",
-          "restrict_start",
-          "restrict_end",
-          "restrict_periods",
-          "day_mask",
-          "create_at",
-          "create_by",
-          "update_at",
-          "update_by",
-          "fair_rotation",
-          "rotation_unit",
-          "rotation_value",
-          "mask_continuous_enabled"
-        ],
-        "type": "object"
+        }
       },
       "ScheduleListRequest": {
-        "description": "值班表列表请求。limit 默认 10、最大 100，p 默认 1。is_my_team 与 is_my_manage 不能同时为 true。",
+        "type": "object",
+        "description": "值班表列表过滤条件。`limit` 默认 10，最大 100；`p` 默认 1。`is_my_team` 与 `is_my_manage` 不能同时为 true。",
         "properties": {
-          "end": {
-            "description": "窗口结束时间（Unix 秒）。",
-            "format": "int64",
-            "type": "integer"
-          },
-          "is_my_manage": {
-            "description": "仅返回当前用户在其团队内创建的值班表。",
-            "type": "boolean"
+          "query": {
+            "type": "string",
+            "description": "对值班表名称或描述做子串匹配。"
           },
-          "is_my_team": {
-            "description": "仅返回当前用户所在团队的值班表。",
-            "type": "boolean"
+          "p": {
+            "type": "integer",
+            "description": "页码（从 1 开始）。",
+            "default": 1
           },
           "limit": {
+            "type": "integer",
+            "description": "每页条数。默认 10；超过 100 按 100 处理。",
             "default": 10,
-            "description": "每页条数，默认 10、最大 100。",
-            "maximum": 100,
-            "type": "integer"
-          },
-          "p": {
-            "default": 1,
-            "description": "页码（从 1 开始）。",
-            "type": "integer"
+            "maximum": 100
           },
-          "query": {
-            "description": "按值班表名称或描述匹配的关键字。",
-            "type": "string"
+          "is_my_team": {
+            "type": "boolean",
+            "description": "只返回调用者所在团队的值班表。调用者不属于任何团队时返回空列表。"
           },
-          "start": {
-            "description": "与 end 同时传入时，响应会包含计算后的分层值班结果；跨度必须小于 45 天。",
-            "format": "int64",
-            "type": "integer"
+          "is_my_manage": {
+            "type": "boolean",
+            "description": "只返回调用者所在团队的值班表以及调用者创建的值班表。"
           },
           "team_ids": {
-            "description": "按团队 ID 过滤。",
+            "type": "array",
             "items": {
-              "format": "int64",
-              "type": "integer"
+              "type": "integer",
+              "format": "int64"
             },
-            "type": "array"
+            "description": "只返回这些团队的值班表；同时设置 `is_my_team`/`is_my_manage` 时取交集。"
+          },
+          "start": {
+            "type": "integer",
+            "format": "int64",
+            "description": "窗口开始时间，10 位 Unix 秒。与 `end` 同时传入时计算分层和班次。"
+          },
+          "end": {
+            "type": "integer",
+            "format": "int64",
+            "description": "窗口结束时间，10 位 Unix 秒，晚于 `start` 且相差不超过 45 天。只传 `end` 不传 `start` 会被拒绝。"
           }
-        },
-        "type": "object"
+        }
       },
       "ScheduleListResponse": {
+        "type": "object",
         "description": "值班表列表响应。",
+        "required": [
+          "items",
+          "total"
+        ],
         "properties": {
           "items": {
-            "description": "当前页的值班表；无匹配时为 null。",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/ScheduleItem"
             },
-            "type": [
-              "array",
-              "null"
-            ]
+            "description": "本页的值班表；无匹配时为空数组。"
           },
           "total": {
-            "description": "符合过滤条件的总条数。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "符合过滤条件的总条数。"
           }
-        },
-        "required": [
-          "items",
-          "total"
-        ],
-        "type": "object"
+        }
       },
       "ScheduleMember": {
+        "type": "object",
         "description": "值班组内成员条目。",
+        "required": [
+          "role_id",
+          "person_ids"
+        ],
         "properties": {
+          "role_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "该槽位人员的值班角色 ID；`0` 表示不指定角色。",
+            "minimum": 0
+          },
           "person_ids": {
-            "description": "该角色下的用户 ID 列表。",
+            "type": "array",
             "items": {
-              "format": "int64",
-              "type": "integer"
+              "type": "integer",
+              "format": "int64"
             },
-            "minItems": 1,
-            "type": "array"
-          },
-          "role_id": {
-            "description": "值班角色 ID。",
-            "format": "int64",
-            "minimum": 0,
-            "type": "integer"
+            "description": "该槽位的成员 ID，至少一个。",
+            "minItems": 1
           }
-        },
-        "required": [
-          "role_id",
-          "person_ids"
-        ],
-        "type": "object"
+        }
       },
       "ScheduleNotify": {
+        "type": "object",
         "description": "值班表的通知配置。",
+        "required": [
+          "fixed_time",
+          "by",
+          "webhooks"
+        ],
         "properties": {
           "advance_in_time": {
-            "description": "提前通知时间（秒）；为 `0` 时在排班开始时通知；不传则不发送提前通知。",
-            "format": "int64",
             "type": [
               "integer",
               "null"
-            ]
-          },
-          "by": {
-            "$ref": "#/components/schemas/ScheduleNotifyBy",
-            "description": "接收人通知偏好，未配置时为 null。"
+            ],
+            "format": "int64",
+            "description": "换班通知提前量（秒）：`0` 在班次开始时通知，`300` 提前 5 分钟。不传或为 `null` 则不发送换班通知。"
           },
           "fixed_time": {
-            "$ref": "#/components/schemas/ScheduleFixedTimeNotifyInfo",
-            "description": "定时通知配置，未配置时为 null。"
+            "oneOf": [
+              {
+                "$ref": "#/components/schemas/ScheduleFixedTimeNotifyInfo"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "在固定时间发送值班信息；未配置时为 `null`。"
+          },
+          "by": {
+            "oneOf": [
+              {
+                "$ref": "#/components/schemas/ScheduleNotifyBy"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "发给值班人员本人的个人通知；未配置时为 `null`。"
           },
           "im": {
+            "type": "object",
             "additionalProperties": {
               "type": "string"
             },
-            "description": "旧版 IM 类型到 token 的映射。",
-            "type": "object"
+            "description": "旧版的机器人类型到 webhook token 的映射。读取时会把 `webhooks` 中没有的条目并入 `webhooks`；请改用 `webhooks`。"
           },
           "webhooks": {
-            "description": "IM Webhook 通知渠道，未配置时为 null。",
-            "items": {
-              "$ref": "#/components/schemas/ScheduleImNotify"
-            },
             "type": [
               "array",
               "null"
-            ]
+            ],
+            "items": {
+              "$ref": "#/components/schemas/ScheduleImNotify"
+            },
+            "description": "接收换班通知的群聊或机器人；未配置时为 `null`。"
           }
-        },
-        "required": [
-          "fixed_time",
-          "by",
-          "webhooks"
-        ],
-        "type": "object"
+        }
       },
       "ScheduleNotifyBy": {
+        "type": "object",
         "description": "接收人的通知偏好。",
+        "required": [
+          "follow_preference",
+          "personal_channels"
+        ],
         "properties": {
           "follow_preference": {
-            "description": "是否跟随个人通知偏好。",
-            "type": "boolean"
+            "type": "boolean",
+            "description": "`true`：按每个人自己设置的换班通知偏好渠道发送，忽略 `personal_channels`。`false`：使用 `personal_channels`。"
           },
           "personal_channels": {
-            "description": "个人通知通道列表。",
+            "type": [
+              "array",
+              "null"
+            ],
             "items": {
               "type": "string"
             },
-            "type": "array"
+            "description": "`follow_preference` 为 `false` 时使用的渠道：`email`、`sms`、`push`（移动端推送），以及 IM 应用 `feishu_app`、`dingtalk_app`、`wecom_app`、`teams_app`、`slack_app`。IM 应用可写成 `<类型>:<集成 ID>` 指定集成（如 `feishu_app:5427276014131`）。未知取值会被保存但不会使用。未设置时为 `null`。"
           }
-        },
-        "required": [
-          "follow_preference",
-          "personal_channels"
-        ],
-        "type": "object"
+        }
       },
       "ScheduleOncallGroup": {
+        "type": "object",
         "description": "当前或下一次值班组快照。",
+        "required": [
+          "start",
+          "end",
+          "group",
+          "update_at",
+          "weight",
+          "index"
+        ],
         "properties": {
+          "start": {
+            "type": "integer",
+            "format": "int64",
+            "description": "时段开始时间（Unix 秒）。"
+          },
           "end": {
-            "description": "时段结束时间（Unix 秒）。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "时段结束时间（Unix 秒）。"
           },
           "group": {
             "$ref": "#/components/schemas/ScheduleGroup",
             "description": "该班次正在值班的值班组。"
           },
-          "index": {
-            "description": "轮转内索引。",
-            "type": "integer"
-          },
-          "start": {
-            "description": "时段开始时间（Unix 秒）。",
-            "format": "int64",
-            "type": "integer"
-          },
           "update_at": {
-            "description": "更新时间（Unix 秒）。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "更新时间（Unix 秒级时间戳）；在这些响应中恒为 `0`。"
           },
           "weight": {
-            "description": "来源分层权重。",
-            "type": "integer"
+            "type": "integer",
+            "description": "在这些响应中恒为 `0`。"
+          },
+          "index": {
+            "type": "integer",
+            "description": "在这些响应中恒为 `0`。"
           }
-        },
-        "required": [
-          "start",
-          "end",
-          "group",
-          "update_at",
-          "weight",
-          "index"
-        ],
-        "type": "object"
+        }
       },
       "ScheduleRestrictPeriod": {
-        "description": "轮转周期内的限制时段。restrict_start 与 restrict_end 为秒级偏移，除非都为 0，否则不能相等。",
+        "type": "object",
+        "description": "一天或一周内的一个值班窗口（见 `restrict_mode`）。开始晚于结束时表示跨越午夜（或跨越周末）。`{0, 0}` 表示全天或全周。除此之外开始和结束不能相等。",
+        "required": [
+          "restrict_start",
+          "restrict_end"
+        ],
         "properties": {
-          "restrict_end": {
-            "description": "限制区间结束偏移。",
+          "restrict_start": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "窗口开始偏移（秒）：`restrict_mode` 为 1 时自 00:00 起算，为 2 时自周一 00:00 起算。"
           },
-          "restrict_start": {
-            "description": "限制区间开始偏移。",
+          "restrict_end": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "窗口结束偏移（秒），起算点与 `restrict_start` 相同。"
           }
-        },
-        "required": [
-          "restrict_start",
-          "restrict_end"
-        ],
-        "type": "object"
+        }
       },
       "ScheduleSelfRequest": {
         "description": "查询当前用户值班表的参数。start 和 end 为必填的 10 位 Unix 秒级时间戳，时间窗口不得超过 45 天。",
@@ -23518,169 +24445,194 @@
         "type": "object"
       },
       "ScheduleSelfResponse": {
-        "description": "/schedule/self 与 /schedule/infos 的响应，仅返回 items。",
+        "type": "object",
+        "description": "`/schedule/self` 和 `/schedule/infos` 的响应。",
+        "required": [
+          "items"
+        ],
         "properties": {
           "items": {
-            "description": "分配给当前用户的值班表（或匹配请求 ID 的值班表）；无时为 null。",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/ScheduleItem"
             },
-            "type": [
-              "array",
-              "null"
-            ]
+            "description": "匹配的值班表；无匹配时为空数组。"
           }
-        },
-        "required": [
-          "items"
-        ],
-        "type": "object"
+        }
       },
       "ScheduleUpsertRequest": {
-        "description": "值班表创建/更新/预览请求体。服务端接受与值班表详情模型相同的结构，此处仅列出关键字段。创建时必填 `schedule_name`（或旧字段 `name`），更新时必填 `schedule_id`，预览时必填 `start` 和 `end`。",
+        "type": "object",
+        "description": "`/schedule/create`、`/schedule/update`、`/schedule/preview` 的请求体。创建时必须提供 `schedule_name`（或旧字段 `name`），更新时必须提供 `schedule_id`，预览时必须提供 `start`/`end`。",
         "properties": {
+          "schedule_id": {
+            "type": [
+              "integer",
+              "null"
+            ],
+            "format": "int64",
+            "description": "值班表 ID，更新时必填，可通过 `POST /schedule/list` 获取。"
+          },
+          "schedule_name": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "值班表名称，最长 40 个字符，账户内唯一。更新时不传则保持原名称。",
+            "maxLength": 40
+          },
+          "name": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "旧版名称字段，仅在创建且 `schedule_name` 为空时使用。更新时忽略。",
+            "maxLength": 40
+          },
           "description": {
-            "description": "值班表描述，最长 500 字符。",
-            "maxLength": 500,
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "值班表描述，最长 500 个字符。更新时不传保持原值，传空字符串则清空。",
+            "maxLength": 500
           },
-          "disabled": {
-            "description": "0 = 启用，1 = 禁用。缺省时为启用。",
+          "team_id": {
             "type": [
               "integer",
               "null"
-            ]
-          },
-          "end": {
-            "description": "预览窗口结束时间（Unix 秒，10 位），/schedule/preview 必填，且距 start 不超过 45 天。",
+            ],
             "format": "int64",
-            "type": "integer"
+            "description": "所属团队 ID，可通过 `POST /team/list` 获取。创建时不传则不归属任何团队（`0`）；更新时不传保持原团队。"
+          },
+          "time_zone": {
+            "type": "string",
+            "description": "值班表墙钟规则所用的 IANA 时区，如 `Asia/Shanghai`、`UTC`；`EST` 之类的缩写以及 `Etc/GMT±N` 会被拒绝。创建时设置（不传则按 `Asia/Shanghai` 计算），之后不可修改——更新时不传或传当前值。预览时用于指定计算时区。"
           },
           "layers": {
-            "description": "轮转分层。",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/ScheduleLayer"
             },
-            "type": "array"
-          },
-          "name": {
-            "description": "旧版名称字段，当 schedule_name 为空时使用。",
-            "maxLength": 40,
-            "type": [
-              "string",
-              "null"
-            ]
+            "description": "轮转分层。更新时该列表会替换全部已有分层，不传即删除所有分层。"
           },
           "notify": {
-            "$ref": "#/components/schemas/ScheduleNotify",
-            "description": "值班轮换通知配置。"
+            "oneOf": [
+              {
+                "$ref": "#/components/schemas/ScheduleNotify"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "换班通知配置。更新时不传保持原配置；传入则整体替换。"
           },
-          "schedule_id": {
-            "description": "值班表 ID，更新时必填，可通过 `POST /schedule/list` 获取。",
+          "start": {
+            "type": "integer",
             "format": "int64",
-            "type": [
-              "integer",
-              "null"
-            ]
+            "description": "预览窗口开始时间，10 位 Unix 秒。`/schedule/preview` 必填；创建和更新时忽略。"
           },
-          "schedule_name": {
-            "description": "值班表显示名称，最长 40 字符。",
-            "maxLength": 40,
+          "end": {
+            "type": "integer",
+            "format": "int64",
+            "description": "预览窗口结束时间，10 位 Unix 秒，晚于 `start` 且相差不超过 45 天。`/schedule/preview` 必填；创建和更新时忽略。"
+          },
+          "disabled": {
             "type": [
-              "string",
+              "integer",
               "null"
-            ]
-          },
-          "start": {
-            "description": "预览窗口开始时间（Unix 秒，10 位），/schedule/preview 必填。",
-            "format": "int64",
-            "type": "integer"
+            ],
+            "enum": [
+              0,
+              1,
+              null
+            ],
+            "description": "仅创建时生效：`0` = 启用（默认），`1` = 禁用。更新时忽略，请改用 `status`。"
           },
-          "team_id": {
-            "description": "所属团队 ID，可通过 `POST /team/list` 获取。",
-            "format": "int64",
+          "status": {
             "type": [
               "integer",
               "null"
-            ]
+            ],
+            "enum": [
+              0,
+              1,
+              null
+            ],
+            "description": "`0` = 启用，`1` = 禁用。更新时不传保持当前状态。创建时优先于 `disabled`。"
           }
-        },
-        "type": "object"
+        }
       },
       "ServiceDeskPlusRequestListRequest": {
+        "type": "object",
         "description": "查询 ServiceDeskPlus 请求同步记录的过滤条件。按故障 ID 查询时可不传时间窗口；否则必须传入不超过 30 天的 Unix 秒时间窗口。",
         "properties": {
-          "asc": {
-            "description": "为 `true` 时按内部记录 ID 升序返回；否则降序。",
-            "type": "boolean"
+          "start_time": {
+            "type": "integer",
+            "format": "int64",
+            "minimum": 0,
+            "description": "时间窗口起点（Unix 秒）。按 `incident_id` 查询时可省略。"
+          },
+          "end_time": {
+            "type": "integer",
+            "format": "int64",
+            "minimum": 0,
+            "description": "时间窗口终点（Unix 秒），必须大于等于 `start_time`。按 `incident_id` 查询时可省略。"
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "success",
+              "failed"
+            ],
+            "description": "按同步状态过滤：`success` 成功，`failed` 失败。"
           },
           "channel_ids": {
-            "description": "协作空间 ID 列表。",
+            "type": "array",
             "items": {
-              "format": "int64",
-              "type": "integer"
+              "type": "integer",
+              "format": "int64"
             },
-            "type": "array"
+            "description": "协作空间 ID 列表。"
           },
-          "end_time": {
-            "description": "时间窗口终点（Unix 秒），必须大于等于 `start_time`。按 `incident_id` 查询时可省略。",
+          "integration_id": {
+            "type": "integer",
             "format": "int64",
             "minimum": 0,
-            "type": "integer"
+            "description": "ServiceDeskPlus 集成 ID。"
           },
           "incident_id": {
-            "description": "Flashduty 故障 ID。提供后可不传时间窗口。",
+            "type": "string",
             "maxLength": 64,
-            "type": "string"
+            "description": "Flashduty 故障 ID。提供后可不传时间窗口。"
           },
-          "integration_id": {
-            "description": "ServiceDeskPlus 集成 ID。",
-            "format": "int64",
-            "minimum": 0,
-            "type": "integer"
+          "request_id": {
+            "type": "string",
+            "maxLength": 64,
+            "description": "ServiceDeskPlus 请求 ID。"
           },
-          "limit": {
-            "default": 20,
-            "description": "分页大小，默认 20，最大 100。",
-            "format": "int64",
-            "maximum": 100,
-            "minimum": 0,
-            "type": "integer"
+          "asc": {
+            "type": "boolean",
+            "description": "为 `true` 时按内部记录 ID 升序返回；否则降序。"
           },
           "p": {
-            "description": "页码，从 1 开始。使用 `search_after_ctx` 时忽略。",
+            "type": "integer",
             "format": "int64",
             "minimum": 0,
-            "type": "integer"
-          },
-          "request_id": {
-            "description": "ServiceDeskPlus 请求 ID。",
-            "maxLength": 64,
-            "type": "string"
+            "description": "不支持；本接口只通过 `search_after_ctx` 翻页，该值会被忽略。"
           },
-          "search_after_ctx": {
-            "description": "分页游标：首页留空，翻页时传上一页响应中的 `search_after_ctx`。",
-            "type": "string"
-          },
-          "start_time": {
-            "description": "时间窗口起点（Unix 秒）。按 `incident_id` 查询时可省略。",
+          "limit": {
+            "type": "integer",
             "format": "int64",
             "minimum": 0,
-            "type": "integer"
+            "maximum": 100,
+            "default": 20,
+            "description": "分页大小，默认 20，最大 100。"
           },
-          "status": {
-            "description": "按同步状态过滤：`success` 成功，`failed` 失败。",
-            "enum": [
-              "success",
-              "failed"
-            ],
-            "type": "string"
+          "search_after_ctx": {
+            "type": "string",
+            "description": "分页游标：首页留空，翻页时传上一页响应中的 `search_after_ctx`。"
           }
-        },
-        "type": "object"
+        }
       },
       "ServiceDeskPlusRequestListResponse": {
         "description": "分页的 ServiceDeskPlus 请求同步记录列表。",
@@ -23845,29 +24797,26 @@
         "type": "object"
       },
       "SessionGetResponse": {
+        "type": "object",
         "description": "一个会话及其事件的一页（向更早方向分页）。",
         "properties": {
+          "session": {
+            "$ref": "#/components/schemas/SessionItem"
+          },
           "events": {
-            "description": "最近事件，按 (created_at, event_id) 升序排列。",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/EventItem"
             },
-            "type": "array"
+            "description": "最新的一页事件（更早的页通过 `search_after_ctx` 获取），按 (`created_at`, `event_id`) 升序排列。不含内部控制事件。始终为数组。"
           },
           "has_more_older": {
-            "description": "当本页之外仍有更早的事件时为 true。",
-            "type": "boolean"
+            "type": "boolean",
+            "description": "当本页之外仍有更早的事件时为 true。"
           },
           "search_after_ctx": {
-            "description": "不透明游标；作为 search_after_ctx 回传以获取更早的一页。has_more_older 为 false 时省略。",
-            "type": "string"
-          },
-          "session": {
-            "$ref": "#/components/schemas/SessionItem"
-          },
-          "suggest_init": {
-            "description": "账户级引导标志：当账户在任何范围内都没有知识时为 true；并非该会话独有的属性。",
-            "type": "boolean"
+            "type": "string",
+            "description": "不透明游标；作为 search_after_ctx 回传以获取更早的一页。has_more_older 为 false 时省略。"
           },
           "pending_messages": {
             "type": "array",
@@ -23881,214 +24830,252 @@
           "session",
           "events",
           "has_more_older",
-          "suggest_init",
           "pending_messages"
-        ],
-        "type": "object"
+        ]
       },
       "SessionItem": {
+        "type": "object",
         "description": "单条智能体会话记录。",
         "properties": {
-          "access_source": {
-            "description": "调用者获得该会话访问权限的方式；未解析到访问来源时省略。可选值：\n| 值 | 含义 |\n| --- | --- |\n| `owner` | 调用者是会话创建者（完全权限） |\n| `team_member` | 调用者是会话绑定团队的成员（完全权限） |\n| `manager` | 管理者授权（保留值；当前版本不产生该来源） |\n| `share_link` | 通过有效分享链接获得（仅查看/复刻，不能继续或管理） |\n| `participant` | 同账户非成员通过可参与的团队会话获得（仅查看/继续/复刻） |",
-            "enum": [
-              "owner",
-              "team_member",
-              "manager",
-              "share_link",
-              "participant"
-            ],
-            "type": "string"
+          "session_id": {
+            "type": "string",
+            "description": "会话标识。"
+          },
+          "parent_session_id": {
+            "type": "string",
+            "description": "子智能体（子）会话的父会话 ID；否则为空。"
+          },
+          "session_name": {
+            "type": "string",
+            "description": "会话标题；未命名会话可能为空。"
           },
           "app_name": {
-            "description": "拥有该会话的智能体应用。",
-            "type": "string"
+            "type": "string",
+            "description": "拥有该会话的智能体应用。"
           },
-          "archived_at": {
-            "description": "归档时间，Unix 毫秒时间戳；0 表示未归档。",
-            "format": "int64",
-            "type": "integer"
+          "entry_kind": {
+            "type": "string",
+            "description": "创建该会话的入口：\n- `web`：Web 控制台（子智能体子会话以及早于该字段创建的会话也返回此值）\n- `im`：IM 机器人或 IM 端 H5\n- `api`：公开 API\n- `automation`：自动化规则（无人值守运行）",
+            "enum": [
+              "web",
+              "im",
+              "api",
+              "automation"
+            ]
           },
-          "bound_environment": {
-            "$ref": "#/components/schemas/EnvironmentBinding"
+          "person_id": {
+            "type": "string",
+            "description": "创建者人员 ID。"
           },
-          "can_continue": {
-            "description": "调用者可在此会话中继续发起新轮次时为 true。",
-            "type": "boolean"
+          "ref": {
+            "type": "string",
+            "description": "会话关联的业务对象，以带前缀的引用表示（例如故障引用）。未关联时不返回。"
           },
-          "can_fork": {
-            "description": "调用者可从此会话创建分支时为 true。",
-            "type": "boolean"
+          "creator_name": {
+            "type": "string",
+            "description": "会话创建者的显示名。仅 `POST /safari/session/list` 返回；名称查询失败时不返回。"
           },
-          "can_manage": {
-            "description": "当调用者可重命名/归档/删除该会话时为 true；个人会话仅创建者可管理，团队会话允许创建者、账户管理员或团队成员管理。",
-            "type": "boolean"
+          "team_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "所属团队 ID；0 表示未绑定团队。创建后不可变更。"
+          },
+          "team_name": {
+            "type": "string",
+            "description": "解析出的团队名称；未绑定或团队已删除时为空。"
+          },
+          "automation": {
+            "type": "object",
+            "description": "产生该会话的自动化规则。仅 `POST /safari/session/get` 返回，且只针对由自动化规则发起的会话。",
+            "properties": {
+              "rule_id": {
+                "type": "string",
+                "description": "自动化规则 ID。"
+              },
+              "rule_name": {
+                "type": "string",
+                "description": "规则名称；规则已删除时为空。"
+              },
+              "trigger_kind": {
+                "type": "string",
+                "enum": [
+                  "schedule",
+                  "manual",
+                  "http_post",
+                  "oncall_incident",
+                  "war_room_created",
+                  ""
+                ],
+                "description": "本次运行的触发方式：\n- `schedule`：规则的定时计划触发\n- `manual`：手动运行（控制台或 `POST /safari/automation/rule/run`）\n- `http_post`：调用了规则的 HTTP 触发地址\n- `oncall_incident`：On-call 故障事件匹配了该规则\n- `war_room_created`：创建了作战室\n- `\"\"`：运行记录已不存在"
+              },
+              "can_edit": {
+                "type": "boolean",
+                "description": "调用者可打开并管理该规则时为 true；规则已删除时为 false。"
+              }
+            },
+            "required": [
+              "rule_id",
+              "rule_name",
+              "trigger_kind",
+              "can_edit"
+            ]
+          },
+          "is_mine": {
+            "type": "boolean",
+            "description": "当该会话由调用者创建时为 true。"
           },
           "can_view": {
-            "description": "调用者可查看此会话时为 true。",
-            "type": "boolean"
+            "type": "boolean",
+            "description": "调用者可读取该会话时为 true：创建者、团队成员以及团队会话所在账户的其他成员恒为 true；其他情况需通过有效分享链接。"
           },
-          "context_resolved": {
-            "$ref": "#/components/schemas/ContextResolvedItem"
+          "can_continue": {
+            "type": "boolean",
+            "description": "调用者可在此会话中继续发起新轮次时为 true。"
           },
-          "context_window": {
-            "description": "所绑定模型的最大上下文 token 数。0 表示未知。",
-            "format": "int64",
-            "type": "integer"
+          "can_manage": {
+            "type": "boolean",
+            "description": "调用者可重命名、归档或删除该会话时为 true：个人会话仅创建者；团队会话为创建者或所属团队成员。账户所有者和管理员没有豁免。"
           },
-          "created_at": {
-            "description": "会话创建时间，Unix 毫秒时间戳。",
-            "format": "int64",
-            "type": "integer"
+          "can_fork": {
+            "type": "boolean",
+            "description": "调用者可从此会话创建分支时为 true。"
           },
-          "current_context_tokens": {
-            "description": "截至最近一轮的 LLM 上下文窗口的 token 数。0 表示尚无已完成的轮次。",
-            "format": "int64",
-            "type": "integer"
+          "access_source": {
+            "type": "string",
+            "description": "调用者获得访问权限的方式；无访问权限时不返回。可选值：\n| 值 | 含义 |\n| --- | --- |\n| `owner` | 调用者创建了该会话（完全权限） |\n| `team_member` | 调用者属于会话所属团队（完全权限） |\n| `manager` | 保留值；当前版本不会返回 |\n| `share_link` | 通过有效分享链接获得（仅查看和复刻；子智能体子会话仅查看） |\n| `participant` | 同一账户的其他成员访问团队会话（可查看、继续、复刻，不可管理） |",
+            "enum": [
+              "owner",
+              "team_member",
+              "manager",
+              "share_link",
+              "participant"
+            ]
           },
-          "current_turn_active_ms": {
-            "description": "本轮（当前或最近一轮）的实际工作时长（毫秒），不含等待 ask_user 的时间；每次新轮次开始时重置为 0。",
-            "format": "int64",
-            "type": "integer"
+          "share_enabled": {
+            "type": "boolean",
+            "description": "会话的分享链接处于启用状态时为 true。"
           },
-          "current_turn_started_at": {
-            "description": "本轮（当前或最近一轮）开始时间，Unix 毫秒时间戳；尚未开始任何轮次时为 0。",
+          "share_version": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "分享链接的版本号；撤销分享时会递增。"
           },
-          "current_turn_tokens": {
-            "description": "当前进行中轮次的 token 总数（输入+输出+推理），涵盖父会话及其所有子智能体；仅由 session/get 在会话运行时计算，session/list 响应及空闲时恒为 0。",
+          "shared_at": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "最近一次启用分享的时间，Unix 毫秒时间戳；从未分享时为 0。"
           },
-          "current_turn_wait_ms": {
-            "description": "当前轮次累计的 ask_user 人工等待时长（毫秒）；每次新轮次开始时重置为 0。",
+          "shared_by": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "最近一次启用分享的人员 ID；从未分享时为 0。"
           },
-          "entry_kind": {
-            "description": "创建该会话的入口来源。可选值：\n| 值 | 含义 |\n| --- | --- |\n| `web` | Web 控制台界面创建 |\n| `im` | IM 客户端（IM 机器人/IM 端 H5）创建 |\n| `api` | 通过公开 API 创建 |\n| `automation` | 由自动化规则触发创建（无人值守运行） |\n| `subagent` | 父会话经 agent_dispatch 派生的子会话（审计标签；运行时按 web 工具面执行） |",
+          "status": {
+            "type": "string",
+            "description": "生命周期状态。响应中恒为 `enabled`：已删除的会话不会被返回。",
             "enum": [
-              "web",
-              "im",
-              "api",
-              "automation",
-              "subagent"
-            ],
-            "type": "string"
-          },
-          "has_unread": {
-            "description": "当存在调用者尚未查看的助手输出时为 true。",
-            "type": "boolean"
+              "enabled"
+            ]
           },
           "incognito": {
-            "description": "无痕（不持久化记忆）会话时为 true。",
-            "type": "boolean"
-          },
-          "is_mine": {
-            "description": "当该会话由调用者创建时为 true。",
-            "type": "boolean"
-          },
-          "is_running": {
-            "description": "当该会话当前有正在进行的智能体轮次时为 true。",
-            "type": "boolean"
+            "type": "boolean",
+            "description": "无痕（不持久化记忆）会话时为 true。"
           },
-          "standing_tasks": {
+          "created_at": {
             "type": "integer",
-            "description": "渲染响应时仍存活的进程型任务数（后台命令或 monitor）。"
+            "format": "int64",
+            "description": "会话创建时间，Unix 毫秒时间戳。"
           },
-          "last_event_at": {
-            "description": "最近一条助手侧事件的时间，Unix 毫秒时间戳。",
+          "updated_at": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "会话最近更新时间，Unix 毫秒时间戳。"
           },
-          "parent_session_id": {
-            "description": "子智能体（子）会话的父会话 ID；否则为空。",
-            "type": "string"
+          "template_staging_round_id": {
+            "type": "string",
+            "description": "当前 save→validate 轮次 ID（仅 template-assistant）；否则为空。"
           },
-          "person_id": {
-            "description": "创建者人员 ID。",
-            "type": "string"
+          "state": {
+            "type": "object",
+            "additionalProperties": true,
+            "description": "原始会话状态键值表。仅 `POST /safari/session/get` 返回；为空时不返回。"
           },
-          "creator_name": {
-            "type": "string",
-            "description": "会话创建者的显示名，渲染响应时解析得到；成员查询失败时不返回该字段。"
+          "bound_environment": {
+            "$ref": "#/components/schemas/EnvironmentBinding"
           },
-          "pinned_at": {
-            "description": "调用者的个人置顶时间，Unix 毫秒时间戳；0 表示未置顶。",
-            "format": "int64",
-            "type": "integer"
+          "context_resolved": {
+            "$ref": "#/components/schemas/ContextResolvedItem"
           },
-          "session_id": {
-            "description": "会话标识。",
-            "type": "string"
+          "token_usage": {
+            "$ref": "#/components/schemas/SessionTokenUsage"
           },
-          "session_name": {
-            "description": "会话标题；未命名会话可能为空。",
-            "type": "string"
+          "current_context_tokens": {
+            "type": "integer",
+            "format": "int64",
+            "description": "截至最近一轮的 LLM 上下文窗口的 token 数。0 表示尚无已完成的轮次。"
           },
-          "share_enabled": {
-            "description": "会话的分享链接处于启用状态时为 true。",
-            "type": "boolean"
+          "context_window": {
+            "type": "integer",
+            "format": "int64",
+            "description": "会话所用模型的最大上下文长度（token）。仅 `POST /safari/session/get` 计算；列表响应中及查询失败时为 0。"
           },
-          "share_version": {
-            "description": "分享链接的版本号；撤销分享时会递增。",
+          "archived_at": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "归档时间，Unix 毫秒时间戳；0 表示未归档。"
           },
-          "shared_at": {
-            "description": "最近一次启用分享的时间，Unix 毫秒时间戳；从未分享时为 0。",
+          "pinned_at": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "调用者置顶该会话的时间，Unix 毫秒时间戳；未置顶为 0。置顶按用户区分。仅 `POST /safari/session/list` 填充；`POST /safari/session/get` 中恒为 0。"
           },
-          "shared_by": {
-            "description": "最近一次启用分享的人员 ID；从未分享时为 0。",
+          "last_event_at": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "最近一条助手侧事件的时间，Unix 毫秒时间戳；仅用户消息不会推进该值。为 0 时不返回。"
           },
-          "state": {
-            "additionalProperties": true,
-            "description": "原始会话状态包（会话级键）。为空时省略。",
-            "type": "object"
+          "is_running": {
+            "type": "boolean",
+            "description": "当该会话当前有正在进行的智能体轮次时为 true。"
           },
-          "status": {
-            "description": "生命周期状态。可选值：`enabled`（正常可用）、`deleted`（已删除，软删除，不可再访问）。",
-            "enum": [
-              "enabled",
-              "deleted"
-            ],
-            "type": "string"
+          "standing_tasks": {
+            "type": "integer",
+            "description": "生成响应时该会话仍存活的进程型任务数（后台命令或 monitor）；没有或无法读取时为 0。"
           },
-          "team_id": {
-            "description": "所属团队 ID；0 表示未绑定团队。创建后不可变更。",
-            "format": "int64",
-            "type": "integer"
+          "has_unread": {
+            "type": "boolean",
+            "description": "存在调用者尚未查看的助手输出时为 true；`is_running` 为 true 时恒为 false。仅 `POST /safari/session/list` 计算；`POST /safari/session/get` 中恒为 false。"
           },
-          "team_name": {
-            "description": "解析出的团队名称；未绑定或团队已删除时为空。",
-            "type": "string"
+          "has_open_tasks": {
+            "type": "boolean",
+            "description": "会话仍有未结束的任务（如运行中的子智能体或后台进程）时为 true，用于区分「轮次已交接」与「会话已完结」。仅 `POST /safari/session/get` 返回；为 false 或查询失败时不返回，因此缺省应视为未知，而非空闲。"
           },
-          "template_staging_round_id": {
-            "description": "当前 save→validate 轮次 ID（仅 template-assistant）；否则为空。",
-            "type": "string"
+          "current_turn_started_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "本轮（当前或最近一轮）开始时间，Unix 毫秒时间戳；尚未开始任何轮次时为 0。"
           },
-          "token_usage": {
-            "$ref": "#/components/schemas/SessionTokenUsage"
+          "current_turn_active_ms": {
+            "type": "integer",
+            "format": "int64",
+            "description": "本轮（当前或最近一轮）的实际工作时长（毫秒），不含等待 ask_user 的时间；每次新轮次开始时重置为 0。"
           },
-          "updated_at": {
-            "description": "会话最近更新时间，Unix 毫秒时间戳。",
+          "current_turn_wait_ms": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "当前轮次累计的 ask_user 人工等待时长（毫秒）；每次新轮次开始时重置为 0。"
           },
-          "has_open_tasks": {
-            "type": "boolean",
-            "description": "会话是否还有未结任务，用于区分「回合已交接」与「会话已完结」。尽力而为：读取失败时该字段不返回（`omitempty`），调用方应视为「未知」，不能据此判定会话空闲。"
+          "current_turn_tokens": {
+            "type": "integer",
+            "format": "int64",
+            "description": "当前进行中轮次的 token 总数（输入+输出+推理），涵盖父会话及其所有子智能体；仅由 session/get 在会话运行时计算，session/list 响应及空闲时恒为 0。"
           }
         },
         "required": [
           "session_id",
           "session_name",
           "app_name",
+          "entry_kind",
           "person_id",
           "team_id",
           "is_mine",
@@ -24115,14 +25102,15 @@
           "current_turn_active_ms",
           "current_turn_wait_ms",
           "current_turn_tokens"
-        ],
-        "type": "object"
+        ]
       },
       "SessionListRequest": {
+        "type": "object",
         "description": "查询智能体会话列表的过滤条件。`all` 表示调用者自己的个人会话和可访问团队的团队会话；账户管理员不可见他人的个人会话。",
         "properties": {
           "app_name": {
-            "description": "要查询其会话的智能体应用。可选值：\n| 值 | 含义 |\n| --- | --- |\n| `ask-ai` | Ask AI 问答助手 |\n| `support` | 客服支持智能体 |\n| `support-website` | 官网站点客服智能体（经 A2A 暴露，不内置于控制台） |\n| `support-flashcat` | Flashcat 站点客服智能体（经 A2A 暴露） |\n| `ai-sre` | AI SRE 主应用 |\n| `template-assistant` | 通知模板助手（模板编辑/校验场景） |\n| `swe` | 内部基准评测应用（不对外开放） |",
+            "type": "string",
+            "description": "要查询其会话的智能体应用。可选值：\n| 值 | 含义 |\n| --- | --- |\n| `ask-ai` | Ask AI 问答助手 |\n| `support` | 客服支持智能体 |\n| `support-website` | 官网站点客服智能体（经 A2A 暴露，不内置于控制台） |\n| `support-flashcat` | Flashcat 站点客服智能体（经 A2A 暴露） |\n| `ai-sre` | AI SRE 主应用 |\n| `template-assistant` | 通知模板助手（模板编辑/校验场景） |\n| `query-assistant` | 监控查询语句编写助手 |\n| `swe` | 软件工程智能体应用（控制台不提供入口） |",
             "enum": [
               "ask-ai",
               "support",
@@ -24130,82 +25118,60 @@
               "support-flashcat",
               "ai-sre",
               "template-assistant",
+              "query-assistant",
               "swe"
-            ],
-            "type": "string"
-          },
-          "asc": {
-            "description": "为 true 时升序，false 时降序。仅在与 `orderby` 同时提供时生效；省略 `orderby` 时始终按 `updated_at` 降序。",
-            "type": "boolean"
-          },
-          "entry_kinds": {
-            "description": "仅返回由这些入口产生的会话；为空则返回所有类型。",
-            "items": {
-              "enum": [
-                "web",
-                "im",
-                "api",
-                "automation"
-              ],
-              "type": "string"
-            },
-            "type": "array"
-          },
-          "include_subagent_sessions": {
-            "description": "是否在列表中包含子智能体派生的会话。",
-            "type": "boolean"
+            ]
           },
-          "keyword": {
-            "description": "按会话名称关键字过滤。",
-            "maxLength": 64,
-            "type": "string"
+          "p": {
+            "type": "integer",
+            "description": "页码，从 1 开始。",
+            "default": 1,
+            "minimum": 1
           },
           "limit": {
-            "default": 20,
+            "type": "integer",
             "description": "每页数量，1–100。",
-            "maximum": 100,
             "minimum": 1,
-            "type": "integer"
+            "maximum": 100,
+            "default": 20
           },
           "orderby": {
+            "type": "string",
             "description": "排序字段：`created_at` 按创建时间，`updated_at` 按最近更新时间；省略时默认 `updated_at`。",
             "enum": [
               "created_at",
               "updated_at"
-            ],
-            "type": "string"
+            ]
           },
-          "p": {
-            "default": 1,
-            "description": "页码，从 1 开始。",
-            "minimum": 1,
-            "type": "integer"
+          "asc": {
+            "type": "boolean",
+            "description": "为 true 时升序，false 时降序。仅在与 `orderby` 同时提供时生效；省略 `orderby` 时始终按 `updated_at` 降序。"
+          },
+          "include_subagent_sessions": {
+            "type": "boolean",
+            "description": "为 true 时同时列出子智能体派发产生的子会话。默认 false（只返回顶层会话）。"
+          },
+          "keyword": {
+            "type": "string",
+            "description": "只返回 `session_name` 包含该文本的会话；首尾空格会被忽略。",
+            "maxLength": 64
           },
           "scope": {
-            "description": "可见范围：`all`（自己的个人会话 + 可访问团队会话）、`personal` 或 `team`；默认 `all`。",
+            "type": "string",
+            "description": "可见范围：\n- `all`（默认）：调用者创建的会话，加上绑定到调用者所在团队的会话\n- `personal`：调用者自己创建且未绑定团队（`team_id` = 0）的会话\n- `team`：绑定到调用者所在团队的会话；调用者不属于任何团队时为空",
             "enum": [
               "all",
               "personal",
               "team"
-            ],
-            "type": "string"
-          },
-          "status": {
-            "description": "归档分桶：active（默认）返回未归档，archived 返回已归档，all 返回全部。",
-            "enum": [
-              "active",
-              "archived",
-              "all"
-            ],
-            "type": "string"
+            ]
           },
           "team_ids": {
-            "description": "可选的团队过滤；与 `scope` 取交集，且不会扩大访问范围。",
+            "type": "array",
             "items": {
-              "format": "int64",
-              "type": "integer"
+              "type": "integer",
+              "format": "int64"
             },
-            "type": "array"
+            "description": "可选的团队过滤；与 `scope` 取交集，且不会扩大访问范围。"
           },
           "person_ids": {
             "type": "array",
@@ -24214,39 +25180,55 @@
               "format": "int64"
             },
             "description": "按会话发起人过滤：只返回由这些成员发起的会话（`person_id` 命中其一即保留）。与 `scope`、`team_ids` 取交集，因此不会让调用方看到本来无权限的会话。"
+          },
+          "entry_kinds": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "enum": [
+                "web",
+                "im",
+                "api",
+                "automation"
+              ]
+            },
+            "description": "仅返回由这些入口创建的会话：`web`（控制台）、`im`（IM 机器人或 IM 端 H5）、`api`（公开 API）、`automation`（自动化规则）。为空则返回所有入口。"
+          },
+          "status": {
+            "type": "string",
+            "description": "归档过滤：\n- `active`（默认）：未归档的会话\n- `archived`：仅已归档的会话\n- `all`：两者都返回",
+            "enum": [
+              "active",
+              "archived",
+              "all"
+            ]
           }
         },
         "required": [
           "app_name"
-        ],
-        "type": "object"
+        ]
       },
       "SessionListResponse": {
+        "type": "object",
         "description": "一页智能体会话。",
         "properties": {
+          "total": {
+            "type": "integer",
+            "format": "int64",
+            "description": "匹配过滤条件的会话数（忽略分页）。第 1 页额外插入的置顶会话不计入。"
+          },
           "sessions": {
-            "description": "当前页的会话。",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/SessionItem"
             },
-            "type": "array"
-          },
-          "suggest_init": {
-            "description": "账户级引导标志：当账户在任何范围内都没有知识时为 true；与本次调用的过滤条件无关。",
-            "type": "boolean"
-          },
-          "total": {
-            "description": "匹配过滤条件的会话总数（忽略分页）。",
-            "format": "int64",
-            "type": "integer"
+            "description": "当前页的会话：第 1 页先是调用者置顶且匹配的会话（最近置顶在前），后跟最多 `limit` 条按请求顺序排列的其他会话。"
           }
         },
         "required": [
           "total",
-          "sessions",
-          "suggest_init"
-        ],
-        "type": "object"
+          "sessions"
+        ]
       },
       "SessionTokenUsage": {
         "description": "跨所有轮次的会话级 token 累计汇总。账户计费的权威来源。",
@@ -24281,32 +25263,33 @@
         "type": "object"
       },
       "SignedURLs": {
+        "type": "object",
         "description": "短期有效的文件下载/预览签名链接。",
         "properties": {
-          "content_type": {
-            "description": "文件的 MIME 类型。",
-            "type": "string"
-          },
           "download_url": {
-            "description": "以下载方式（attachment）返回文件的相对链接（`/safari/artifact/stream?...`）。使用前需拼接 API 域名 `https://api.flashcat.cloud`；有效期见 `expires_in`。",
-            "type": "string"
+            "type": "string",
+            "description": "以下载方式（attachment）返回文件的相对链接（`/safari/artifact/stream?...`）。使用前需拼接 API 域名 `https://api.flashcat.cloud`；有效期见 `expires_in`。"
+          },
+          "preview_url": {
+            "type": "string",
+            "description": "与 `download_url` 相同，但以 inline 方式返回，用于浏览器内预览。"
           },
           "expires_in": {
-            "description": "两个链接的有效期，单位秒（300）。",
-            "type": "integer"
+            "type": "integer",
+            "description": "两个链接的有效期，单位秒。固定为 `300`。"
           },
           "name": {
-            "description": "文件名（含扩展名）。",
-            "type": "string"
-          },
-          "preview_url": {
-            "description": "与 `download_url` 相同，但以 inline 方式返回，用于浏览器内预览。",
-            "type": "string"
+            "type": "string",
+            "description": "文件名（含扩展名）。"
           },
           "size": {
-            "description": "文件大小，单位字节。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "文件大小，单位字节。"
+          },
+          "content_type": {
+            "type": "string",
+            "description": "MIME 类型，在文件产出时按文件扩展名推断：`text/html`（.html/.htm）、`text/markdown`（.md）、`text/plain`（.txt/.log）、`text/csv`、`text/yaml`（.yaml/.yml）、`text/x-python`、`text/x-go`、`text/x-sh`、`application/json`、`application/xml`、`application/pdf`、`image/png`、`image/jpeg`、`image/gif`、`image/svg+xml`、`image/webp`、`application/zip`、`application/gzip`（.tar/.gz/.tgz）；其他扩展名为 `application/octet-stream`。"
           }
         },
         "required": [
@@ -24316,112 +25299,111 @@
           "name",
           "size",
           "content_type"
-        ],
-        "type": "object"
+        ]
       },
       "SilenceRuleItem": {
+        "type": "object",
+        "required": [
+          "account_id",
+          "channel_id",
+          "rule_name",
+          "description",
+          "time_filters",
+          "time_filter",
+          "filters",
+          "is_directly_discard",
+          "status",
+          "rule_id",
+          "updated_by",
+          "created_at",
+          "updated_at",
+          "is_effective"
+        ],
         "properties": {
           "account_id": {
-            "description": "规则所属账户 ID。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "规则所属账户 ID。"
           },
           "channel_id": {
-            "description": "规则所属协作空间 ID。",
-            "format": "int64",
-            "type": "integer"
-          },
-          "created_at": {
-            "description": "创建时间，Unix 时间戳（秒）。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "规则所属协作空间 ID。"
           },
-          "deleted_at": {
-            "description": "删除时间，Unix 秒时间戳。仅在策略被软删除时返回；已删除的策略不会出现在列表响应中。",
-            "format": "int64",
-            "type": "integer"
+          "rule_name": {
+            "type": "string",
+            "description": "静默策略名称，1–39 个字符。"
           },
           "description": {
-            "description": "规则描述。",
-            "type": "string"
-          },
-          "filters": {
-            "$ref": "#/components/schemas/FilterGroup",
-            "description": "告警事件匹配条件；命中的事件在时间窗口内被静默。"
+            "type": "string",
+            "description": "规则描述。"
           },
           "from_incident_id": {
-            "description": "策略关联的故障 ID。始终返回；零值 ObjectID `000000000000000000000000` 表示该策略并非从故障创建。",
+            "type": "string",
             "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
-          },
-          "is_auto_delete": {
-            "description": "为 true 时，静默规则在时间窗结束后会被自动删除；默认为 false。",
-            "type": "boolean"
+            "description": "策略关联的故障 ID。始终返回；零值 ObjectID `000000000000000000000000` 表示该策略并非从故障创建。"
           },
-          "is_directly_discard": {
-            "description": "为 true 时静默的告警直接丢弃，不会生成故障。",
-            "type": "boolean"
+          "time_filters": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/TimeFilter"
+            },
+            "description": "周期性静默窗口。当策略使用一次性 `time_filter` 时为空。"
           },
-          "is_effective": {
-            "description": "策略的时间窗口是否覆盖当前时刻（按响应时刻计算）。",
-            "type": "boolean"
+          "time_filter": {
+            "$ref": "#/components/schemas/OnceTimeFilter",
+            "description": "一次性静默窗口。当策略使用周期性 `time_filters` 时，该字段以零值返回。"
           },
-          "rule_id": {
-            "description": "规则 ID（MongoDB ObjectID）。",
-            "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
+          "filters": {
+            "$ref": "#/components/schemas/FilterGroup",
+            "description": "告警事件匹配条件（AND 组之间为 OR），时间窗口内命中的事件被静默。"
           },
-          "rule_name": {
-            "description": "规则名称。",
-            "type": "string"
+          "is_directly_discard": {
+            "type": "boolean",
+            "description": "为 true 时，命中的告警事件被直接丢弃；为 false 时，告警仍会记录，但标记为被该策略静默。"
           },
           "status": {
-            "description": "规则状态：`enabled` 启用，`disabled` 停用；已删除的规则不会出现在列表中。",
+            "type": "string",
             "enum": [
               "enabled",
               "disabled"
             ],
-            "type": "string"
+            "description": "规则状态：`enabled` 启用，`disabled` 停用；已删除的规则不会出现在列表中。"
           },
-          "time_filter": {
-            "$ref": "#/components/schemas/OnceTimeFilter",
-            "description": "一次性静默窗口。当策略使用周期性 `time_filters` 时，该字段以零值返回。"
+          "rule_id": {
+            "type": "string",
+            "pattern": "^[0-9a-fA-F]{24}$",
+            "description": "规则 ID（MongoDB ObjectID）。"
           },
-          "time_filters": {
-            "description": "周期性静默窗口。当策略使用一次性 `time_filter` 时为空。",
-            "items": {
-              "$ref": "#/components/schemas/TimeFilter"
-            },
-            "type": "array"
+          "updated_by": {
+            "type": "integer",
+            "format": "int64",
+            "description": "最近一次更新该规则的用户 ID。"
+          },
+          "created_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "创建时间，Unix 时间戳（秒）。"
           },
           "updated_at": {
-            "description": "最近更新时间，Unix 时间戳（秒）。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "最近更新时间，Unix 时间戳（秒）。"
           },
-          "updated_by": {
-            "description": "最近一次更新该规则的用户 ID。",
+          "is_effective": {
+            "type": "boolean",
+            "description": "策略的时间窗口是否覆盖当前时刻（按响应时刻计算）。"
+          },
+          "is_auto_delete": {
+            "type": "boolean",
+            "description": "为 true 时，策略在一次性窗口结束约 24 小时后被永久移除；周期窗口的策略不会被移除。仅在为 `true` 时返回。"
+          },
+          "deleted_at": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "删除时间，Unix 秒时间戳。仅在策略被软删除时返回；已删除的策略不会出现在列表响应中。"
           }
-        },
-        "required": [
-          "account_id",
-          "channel_id",
-          "rule_name",
-          "description",
-          "time_filters",
-          "time_filter",
-          "filters",
-          "is_directly_discard",
-          "status",
-          "rule_id",
-          "updated_by",
-          "created_at",
-          "updated_at",
-          "is_effective"
-        ],
-        "type": "object"
+        }
       },
       "SkillDeleteRequest": {
         "description": "按 ID 删除技能。",
@@ -24450,125 +25432,151 @@
         "type": "object"
       },
       "SkillItem": {
+        "type": "object",
         "description": "AI SRE 技能 —— 智能体可加载的 SKILL.md 打包资源。",
         "properties": {
+          "skill_id": {
+            "type": "string",
+            "description": "技能唯一 ID（前缀 `skill_`）。"
+          },
           "account_id": {
+            "type": "integer",
             "description": "所属账户 ID。",
-            "format": "int64",
-            "type": "integer"
+            "format": "int64"
           },
-          "author": {
-            "description": "技能作者。",
-            "type": "string"
-          },
-          "can_edit": {
-            "description": "调用者是否可编辑该技能。",
-            "type": "boolean"
-          },
-          "checksum": {
-            "description": "技能压缩包的 SHA-256 校验和。",
-            "type": "string"
+          "team_id": {
+            "type": "integer",
+            "description": "团队范围：0 表示账户级；>0 表示所属团队。",
+            "format": "int64"
           },
-          "content": {
-            "description": "完整的 SKILL.md 内容；列表响应中省略。",
-            "type": "string"
+          "skill_name": {
+            "type": "string",
+            "description": "技能名称，在其作用域内唯一（账户范围或单个团队内）。"
           },
-          "created": {
-            "description": "仅在“从会话安装”响应中出现：true 表示新建，false 表示原地更新。",
-            "type": "boolean"
+          "description": {
+            "type": "string",
+            "description": "来自 SKILL.md frontmatter 的可读描述。"
           },
-          "created_at": {
-            "description": "创建时间，Unix 毫秒时间戳。",
-            "format": "int64",
-            "type": "integer"
+          "description_en": {
+            "type": "string",
+            "description": "可选的英文描述。英文语言环境下的界面响应优先使用该字段而非 `description`；当 `description` 被本地化展示时，技能目录也会用它作为稳定的选型信号。"
           },
-          "created_by": {
-            "description": "创建该技能的成员 ID。",
-            "format": "int64",
-            "type": "integer"
+          "content": {
+            "type": "string",
+            "description": "完整的 SKILL.md 内容；列表响应中省略。"
           },
-          "description": {
-            "description": "来自 SKILL.md frontmatter 的可读描述。",
-            "type": "string"
+          "version": {
+            "type": "string",
+            "description": "frontmatter 中的技能版本。"
           },
-          "description_en": {
-            "description": "可选的英文描述。英文语言环境下的界面响应优先使用该字段而非 `description`；当 `description` 被本地化展示时，技能目录也会用它作为稳定的选型信号。",
-            "type": "string"
+          "tags": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "从 frontmatter 解析的标签。"
           },
-          "is_modified": {
-            "description": "当市场来源技能被本地修改时为 true（自动更新将跳过）。",
-            "type": "boolean"
+          "author": {
+            "type": "string",
+            "description": "技能作者。"
           },
           "license": {
-            "description": "技能许可证。",
-            "type": "string"
-          },
-          "s3_key": {
-            "description": "技能压缩包在对象存储中的 key。",
-            "type": "string"
+            "type": "string",
+            "description": "技能许可证。"
           },
-          "skill_id": {
-            "description": "技能唯一 ID（前缀 `skill_`）。",
-            "type": "string"
+          "tools": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "所需工具（内置或 `mcp:server/tool`）。"
           },
-          "skill_name": {
-            "description": "技能名称，在其作用域内唯一（账户范围或单个团队内）。",
-            "type": "string"
+          "venues": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "enum": [
+                "cloud",
+                "byoc"
+              ]
+            },
+            "description": "技能限定可用的执行环境：`cloud`（托管沙箱）和/或 `byoc`（自建 runner）。为空时不返回，表示所有环境均可用。"
           },
-          "source_template_name": {
-            "description": "该技能安装来源的市场模板名称；自建技能为空。",
-            "type": "string"
+          "s3_key": {
+            "type": "string",
+            "description": "技能压缩包在对象存储中的 key。"
           },
-          "source_template_version": {
-            "description": "安装时的模板版本。",
-            "type": "string"
+          "checksum": {
+            "type": "string",
+            "description": "技能压缩包的 SHA-256 校验和。"
           },
           "status": {
-            "description": "技能状态。已删除的技能不会出现在任何 API 响应中，因此只会返回这两种状态。",
+            "type": "string",
+            "description": "技能状态：`enabled`（智能体会加载）或 `disabled`（保留但不加载）。已删除的技能不会出现在响应中。",
             "enum": [
               "enabled",
               "disabled"
-            ],
-            "type": "string"
+            ]
           },
-          "tags": {
-            "description": "从 frontmatter 解析的标签。",
-            "items": {
-              "type": "string"
-            },
-            "type": "array"
+          "created_by": {
+            "type": "integer",
+            "description": "创建该技能的成员 ID。",
+            "format": "int64"
           },
-          "team_id": {
-            "description": "团队范围：0 表示账户级；>0 表示所属团队。",
+          "created_at": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "创建时间，Unix 毫秒时间戳。"
           },
-          "tools": {
-            "description": "所需工具（内置或 `mcp:server/tool`）。",
-            "items": {
-              "type": "string"
-            },
-            "type": "array"
+          "updated_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "最近更新时间，Unix 毫秒时间戳。"
+          },
+          "can_edit": {
+            "type": "boolean",
+            "description": "调用者可修改该技能时为 true：账户级技能为账户所有者和管理员，团队技能为该团队成员。"
+          },
+          "source_template_name": {
+            "type": "string",
+            "description": "该技能安装来源的市场模板名称；自建技能为空。"
+          },
+          "source_template_version": {
+            "type": "string",
+            "description": "安装时的模板版本。"
           },
           "update_available": {
-            "description": "当市场存在更新版本时为 true。",
-            "type": "boolean"
+            "type": "boolean",
+            "description": "该技能的市场来源模板有更新版本时为 true。仅 `POST /safari/skill/list` 计算；其他响应中恒为 false。"
           },
-          "updated_at": {
-            "description": "最近更新时间，Unix 毫秒时间戳。",
-            "format": "int64",
-            "type": "integer"
+          "is_modified": {
+            "type": "boolean",
+            "description": "市场安装的技能被本地修改（例如上传了新压缩包）时为 true；市场自动更新会跳过它。"
           },
-          "venues": {
-            "description": "限定技能可用的执行环境类型（EnvironmentKind 字符串，如 `byoc`）；为空时省略，表示所有环境均可用。",
-            "items": {
-              "type": "string"
-            },
-            "type": "array"
+          "created": {
+            "type": "boolean",
+            "description": "这些接口不会返回该字段；仅「从会话安装」流程会设置。"
           },
-          "version": {
-            "description": "frontmatter 中的技能版本。",
-            "type": "string"
+          "examples": {
+            "type": "array",
+            "description": "SKILL.md frontmatter 中声明的示例问题（最多 10 条），作为推荐提问展示。没有时不返回。",
+            "items": {
+              "type": "object",
+              "properties": {
+                "zh": {
+                  "type": "string",
+                  "description": "中文问题文本。"
+                },
+                "en": {
+                  "type": "string",
+                  "description": "英文问题文本。"
+                }
+              },
+              "required": [
+                "zh",
+                "en"
+              ]
+            }
           }
         },
         "required": [
@@ -24584,53 +25592,52 @@
           "can_edit",
           "update_available",
           "is_modified"
-        ],
-        "type": "object"
+        ]
       },
       "SkillListRequest": {
+        "type": "object",
         "description": "技能列表的分页、搜索与团队过滤条件。",
         "properties": {
-          "include_account": {
-            "description": "是否包含账户级（team_id=0）记录，默认 true。当 `scope` 为 `account` 或 `team` 时该字段会被忽略。",
-            "type": [
-              "boolean",
-              "null"
-            ]
-          },
-          "limit": {
-            "default": 20,
-            "description": "每页数量。",
-            "type": "integer"
-          },
           "p": {
-            "default": 1,
-            "description": "页码，从 1 开始。",
-            "type": "integer"
+            "type": "integer",
+            "description": "页码，从 1 开始；小于 1 时按 1 处理。",
+            "default": 1
           },
-          "query": {
-            "description": "跨技能名称、描述、英文描述、技能 ID、市场来源模板名称与作者的全文搜索。",
-            "maxLength": 128,
-            "type": "string"
+          "limit": {
+            "type": "integer",
+            "description": "每页条数；小于 1 时按 20 处理。",
+            "default": 20
           },
           "scope": {
-            "description": "将结果限制为 `all`（默认）、仅 `account`（team_id=0）、或仅 `team`（排除账户级记录）；设置后会覆盖 `include_account`。",
+            "type": "string",
+            "description": "要返回的技能范围；设置后覆盖 `include_account`：\n- `all`（默认）：账户级技能（除非 `include_account` 为 false）加上调用者所在团队的技能\n- `account`：仅账户级技能（`team_id` = 0）\n- `team`：仅调用者所在团队的技能",
             "enum": [
               "all",
               "account",
               "team"
-            ],
-            "type": "string"
+            ]
+          },
+          "query": {
+            "type": "string",
+            "description": "跨技能名称、描述、英文描述、技能 ID、市场来源模板名称与作者的全文搜索。",
+            "maxLength": 128
           },
           "team_ids": {
-            "description": "按团队 ID 过滤；为空则使用调用者可见范围。",
+            "type": "array",
             "items": {
-              "format": "int64",
-              "type": "integer"
+              "type": "integer",
+              "format": "int64"
             },
-            "type": "array"
+            "description": "将团队级结果限定为这些团队 ID；调用者不属于的团队会被忽略。为空表示调用者所在的全部团队。"
+          },
+          "include_account": {
+            "type": [
+              "boolean",
+              "null"
+            ],
+            "description": "是否包含账户级（team_id=0）记录，默认 true。当 `scope` 为 `account` 或 `team` 时该字段会被忽略。"
           }
-        },
-        "type": "object"
+        }
       },
       "SkillListResponse": {
         "description": "分页的技能列表。",
@@ -24702,31 +25709,31 @@
         "type": "object"
       },
       "SkillUploadRequest": {
+        "type": "object",
         "description": "上传技能压缩包的 multipart 表单。",
         "properties": {
           "file": {
-            "description": "技能压缩包（.skill / .zip / .tar.gz / .tgz），最大 100MB；超限文件会在读取正文前即被拒绝。",
+            "type": "string",
             "format": "binary",
-            "type": "string"
+            "description": "技能压缩包（`.skill`、`.zip`、`.tar.gz` 或 `.tgz`），最大 100 MB，`SKILL.md` 位于根目录或唯一的顶层文件夹内。"
+          },
+          "team_id": {
+            "type": "integer",
+            "description": "新建或按名称覆盖的技能所在作用域：0 表示账户级（默认），>0 表示该团队。同时设置 `replace=true` 和 `skill_id` 时忽略。",
+            "format": "int64"
           },
           "replace": {
-            "description": "为 true 时覆盖已有技能而非在名称冲突时报错 —— 若提供 `skill_id` 则按其匹配，否则按技能名称匹配。",
-            "type": "boolean"
+            "type": "boolean",
+            "description": "为 true 时覆盖已有技能，而不是在名称冲突时报错：覆盖 `skill_id` 指定的技能，否则覆盖 `team_id` 中的同名技能。可取 `true`、`1`、`yes`、`on`（不区分大小写），其他值视为 false。"
           },
           "skill_id": {
-            "description": "定向替换指定技能时的技能 ID（需配合 `replace=true`）。",
-            "type": "string"
-          },
-          "team_id": {
-            "description": "新建/upsert 技能的团队范围：0 表示账户级。通过 `skill_id` 定向替换时会忽略该字段。",
-            "format": "int64",
-            "type": "integer"
+            "type": "string",
+            "description": "要覆盖的技能 ID，来自 `POST /safari/skill/list`。仅与 `replace=true` 一起使用，否则忽略。"
           }
         },
         "required": [
           "file"
-        ],
-        "type": "object"
+        ]
       },
       "SnoozeIncidentRequest": {
         "description": "暂停故障通知的参数。",
@@ -24799,11 +25806,6 @@
             "type": "string"
           }
         },
-        "required": [
-          "uuid",
-          "name",
-          "is_system"
-        ],
         "type": "object"
       },
       "SourcemapCodeSnippet": {
@@ -24875,7 +25877,7 @@
             "type": "string"
           },
           "key": {
-            "description": "唯一标识该 Sourcemap 文件的存储键。",
+            "description": "记录标识：根据上传文件的身份（存储路径，或 native 符号的服务/版本/构建标识）计算出的 32 位十六进制 MD5 摘要。",
             "type": "string"
           },
           "metadata": {
@@ -24936,7 +25938,7 @@
             "type": "boolean"
           },
           "build_id": {
-            "description": "仅 Android。按 Gradle 插件构建标识过滤。最多 200 个字符。",
+            "description": "按构建 ID 子串过滤（Android Gradle 插件构建标识，或 native 符号的 build ID）。最多 200 个字符。",
             "maxLength": 200,
             "type": "string"
           },
@@ -25008,7 +26010,7 @@
             "type": "string"
           },
           "uuid": {
-            "description": "仅 iOS。按 dSYM bundle UUID 过滤。最多 200 个字符。",
+            "description": "仅 iOS。按 dSYM UUID 子串过滤，匹配前会转为大写并去掉连字符。最多 200 个字符。",
             "maxLength": 200,
             "type": "string"
           },
@@ -25050,7 +26052,7 @@
         "description": "错误栈 enrich 请求。",
         "properties": {
           "arch": {
-            "description": "Android NDK 架构，例如 `arm`、`arm64`、`x86` 或 `x64`。",
+            "description": "native CPU 架构，如 `arm`、`arm64`、`x86`、`x64`。`type: android` 且 `source_type` 为空时，传入 `arch` 即按 NDK native 符号化。",
             "type": "string"
           },
           "binary_images": {
@@ -25087,7 +26089,7 @@
             "type": "string"
           },
           "source_type": {
-            "description": "Android 错误来源类型；native 符号化时配合 `arch` 传入 `ndk`。",
+            "description": "SDK 上报的错误 `error.source_type`，会改变符号化路由：`android` 下值中含 `ndk` 时使用 NDK native 符号；`flutter` 与 `react-native` 下 `ios` 使用 dSYM、`android`/`ndk` 使用 Android 符号；`electron` 下 `macos`、`windows`、`linux` 使用 Breakpad 符号。其他类型忽略此字段。",
             "type": "string"
           },
           "stack": {
@@ -25205,68 +26207,42 @@
         "type": "object"
       },
       "StatusPageChangeItem": {
+        "type": "object",
         "description": "状态页事件（故障或维护）。",
+        "required": [
+          "change_id",
+          "type",
+          "title"
+        ],
         "properties": {
-          "affected_components": {
-            "description": "当前受此事件影响的组件及其状态。无受影响组件时不返回。",
-            "items": {
-              "$ref": "#/components/schemas/AffectedStatusPageComponentItem"
-            },
-            "type": "array"
-          },
-          "auto_update_by_schedule": {
-            "description": "仅维护事件：是否按计划窗口自动推进状态。为 false 时不返回。",
-            "type": "boolean"
-          },
           "change_id": {
-            "description": "事件 ID。",
-            "format": "int64",
-            "type": "integer"
-          },
-          "close_at_seconds": {
-            "description": "事件结束时间（Unix 秒）。维护事件为计划结束时间；已关闭事件为进入终态（`resolved`/`completed`）的时间。未设置时不返回。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
-          },
-          "description": {
-            "description": "事件描述（Markdown）。为空时不返回。",
-            "type": "string"
-          },
-          "is_retrospective": {
-            "description": "是否为回溯（历史）事件。为 false 时不返回。",
-            "type": "boolean"
-          },
-          "linked_change_ids": {
-            "description": "关联的事件 ID 列表（相关故障、发布等）。为空时不返回。",
-            "items": {
-              "type": "string"
-            },
-            "type": "array"
-          },
-          "notify_subscribers": {
-            "description": "创建本事件时是否通知订阅者。为 false 时不返回。",
-            "type": "boolean"
+            "description": "事件 ID，由 `POST /status-page/change/create` 返回；调用其他事件接口时作为 `change_id` 传入。"
           },
           "page_id": {
-            "description": "所属状态页 ID。为 0 时不返回（已存储事件必有值）。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "所属状态页 ID。为 0 时不返回（已存储事件必有值）。"
           },
-          "responder_ids": {
-            "description": "事件负责成员 ID 列表。未指派负责成员时不返回。",
-            "items": {
-              "format": "int64",
-              "type": "integer"
-            },
-            "type": "array"
+          "type": {
+            "type": "string",
+            "enum": [
+              "incident",
+              "maintenance"
+            ],
+            "description": "事件类型。`incident` 为非计划的故障事件；`maintenance` 为计划内的维护事件。类型决定可用的状态取值。"
           },
-          "start_at_seconds": {
-            "description": "事件开始时间（Unix 秒），取自第一条时间线更新。为 0 时不返回。",
-            "format": "int64",
-            "type": "integer"
+          "title": {
+            "type": "string",
+            "description": "事件标题。"
+          },
+          "description": {
+            "type": "string",
+            "description": "事件描述（Markdown）。为空时不返回。"
           },
           "status": {
-            "description": "事件当前状态。故障事件支持 `investigating`/`identified`/`monitoring`/`resolved`；维护事件支持 `scheduled`/`ongoing`/`completed`。为空时不返回（已存储事件必有值）。",
+            "type": "string",
             "enum": [
               "investigating",
               "identified",
@@ -25276,34 +26252,60 @@
               "ongoing",
               "completed"
             ],
-            "type": "string"
+            "description": "事件当前状态。故障事件支持 `investigating`/`identified`/`monitoring`/`resolved`；维护事件支持 `scheduled`/`ongoing`/`completed`。为空时不返回（已存储事件必有值）。"
           },
-          "title": {
-            "description": "事件标题。",
-            "type": "string"
+          "affected_components": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/AffectedStatusPageComponentItem"
+            },
+            "description": "当前受此事件影响的组件及其状态。无受影响组件时不返回。"
           },
-          "type": {
-            "description": "事件类型。`incident` 为非计划的故障事件；`maintenance` 为计划内的维护事件。类型决定可用的状态取值。",
-            "enum": [
-              "incident",
-              "maintenance"
-            ],
-            "type": "string"
+          "responder_ids": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "int64"
+            },
+            "description": "事件负责成员 ID 列表。未指派负责成员时不返回。"
+          },
+          "linked_change_ids": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "关联的事件 ID 列表（相关故障、发布等）。为空时不返回。"
+          },
+          "start_at_seconds": {
+            "type": "integer",
+            "format": "int64",
+            "description": "事件开始时间，Unix 时间戳（秒）。故障为第一条时间线更新的时间；维护为创建时指定的计划开始时间，未指定时取第一条更新的时间。为 0 时省略。"
+          },
+          "close_at_seconds": {
+            "type": "integer",
+            "format": "int64",
+            "description": "事件结束时间（Unix 秒）。维护事件为计划结束时间；已关闭事件为进入终态（`resolved`/`completed`）的时间。未设置时不返回。"
+          },
+          "is_retrospective": {
+            "type": "boolean",
+            "description": "是否为回溯（历史）事件。为 false 时不返回。"
           },
           "updates": {
-            "description": "事件的时间线更新列表，按时间排序。事件无时间线更新时不返回。",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/StatusPageChangeUpdateItem"
             },
-            "type": "array"
+            "description": "事件的时间线更新列表，按时间排序。事件无时间线更新时不返回。"
+          },
+          "notify_subscribers": {
+            "type": "boolean",
+            "description": "创建本事件时是否通知订阅者。为 false 时不返回。"
+          },
+          "auto_update_by_schedule": {
+            "type": "boolean",
+            "description": "仅维护事件：是否按计划窗口自动推进状态。为 false 时不返回。"
           }
-        },
-        "required": [
-          "change_id",
-          "type",
-          "title"
-        ],
-        "type": "object"
+        }
       },
       "StatusPageChangeListResponse": {
         "description": "状态页事件列表。",
@@ -25335,26 +26337,24 @@
         "type": "object"
       },
       "StatusPageChangeUpdateItem": {
+        "type": "object",
         "description": "状态页事件的单条时间线更新。",
+        "required": [
+          "update_id",
+          "at_seconds"
+        ],
         "properties": {
+          "update_id": {
+            "type": "string",
+            "description": "时间线更新 ID（ULID 字符串），由服务端生成；修改或删除该更新时作为 `update_id` 传入。"
+          },
           "at_seconds": {
-            "description": "更新时间戳（Unix 秒）。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
-          },
-          "component_changes": {
-            "description": "本次更新应用的组件状态变更。本次更新无组件状态变更时不返回。",
-            "items": {
-              "$ref": "#/components/schemas/StatusPageComponentChangeItem"
-            },
-            "type": "array"
-          },
-          "description": {
-            "description": "更新说明（Markdown）。为空时不返回。",
-            "type": "string"
+            "description": "更新时间戳（Unix 秒）。"
           },
           "status": {
-            "description": "本次更新后的事件状态。当更新不改变整体状态时省略。前四个值仅适用于 incident 类型，后三个仅适用于 maintenance 类型。\n| 值 | 含义 |\n|---|---|\n| `investigating` | 排查中（incident）。 |\n| `identified` | 已定位原因（incident）。 |\n| `monitoring` | 已修复，观察中（incident）。 |\n| `resolved` | 已解决（incident）。 |\n| `scheduled` | 已计划（maintenance）。 |\n| `ongoing` | 进行中（maintenance）。 |\n| `completed` | 已完成（maintenance）。 |",
+            "type": "string",
             "enum": [
               "investigating",
               "identified",
@@ -25364,32 +26364,39 @@
               "ongoing",
               "completed"
             ],
-            "type": "string"
+            "description": "本次更新后的事件状态。当更新不改变整体状态时省略。前四个值仅适用于 incident 类型，后三个仅适用于 maintenance 类型。\n| 值 | 含义 |\n|---|---|\n| `investigating` | 排查中（incident）。 |\n| `identified` | 已定位原因（incident）。 |\n| `monitoring` | 已修复，观察中（incident）。 |\n| `resolved` | 已解决（incident）。 |\n| `scheduled` | 已计划（maintenance）。 |\n| `ongoing` | 进行中（maintenance）。 |\n| `completed` | 已完成（maintenance）。 |"
           },
-          "update_id": {
-            "description": "更新 ID。",
-            "type": "string"
+          "description": {
+            "type": "string",
+            "description": "更新说明（Markdown）。为空时不返回。"
+          },
+          "component_changes": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/StatusPageComponentChangeItem"
+            },
+            "description": "本次更新应用的组件状态变更。本次更新无组件状态变更时不返回。"
           }
-        },
-        "required": [
-          "update_id",
-          "at_seconds"
-        ],
-        "type": "object"
+        }
       },
       "StatusPageComponentChangeItem": {
+        "type": "object",
         "description": "时间线更新中的组件状态变更。",
+        "required": [
+          "component_id",
+          "status"
+        ],
         "properties": {
           "component_id": {
-            "description": "组件 ID。",
-            "type": "string"
+            "type": "string",
+            "description": "状态发生变化的组件 ID，对应 `GET /status-page/info` 中的 `component_id`。"
           },
           "component_name": {
-            "description": "组件显示名称。读取时由后端填充，写入时忽略。为空时不返回。",
-            "type": "string"
+            "type": "string",
+            "description": "组件显示名称。读取时由后端填充，写入时忽略。为空时不返回。"
           },
           "status": {
-            "description": "组件新状态。故障事件支持 `operational`/`degraded`/`partial_outage`/`full_outage`；维护事件支持 `operational`/`under_maintenance`。",
+            "type": "string",
             "enum": [
               "operational",
               "degraded",
@@ -25397,14 +26404,9 @@
               "full_outage",
               "under_maintenance"
             ],
-            "type": "string"
+            "description": "组件新状态。故障事件支持 `operational`/`degraded`/`partial_outage`/`full_outage`；维护事件支持 `operational`/`under_maintenance`。"
           }
-        },
-        "required": [
-          "component_id",
-          "status"
-        ],
-        "type": "object"
+        }
       },
       "StatusPageComponentItem": {
         "description": "状态页组件。",
@@ -25450,23 +26452,23 @@
         "type": "object"
       },
       "StatusPageDraftCreateResponse": {
+        "type": "object",
         "description": "存储状态页草稿的结果。",
-        "properties": {
-          "created_at": {
-            "description": "创建时间，Unix epoch 秒。",
-            "format": "int64",
-            "type": "integer"
-          },
-          "draft_id": {
-            "description": "草稿 ID，格式为 `draft_[A-Za-z0-9]{22}`；控制台审核链接会携带它。",
-            "type": "string"
-          }
-        },
         "required": [
           "draft_id",
           "created_at"
         ],
-        "type": "object"
+        "properties": {
+          "draft_id": {
+            "type": "string",
+            "description": "草稿 ID，格式为 `draft_[A-Za-z0-9]{22}`；发布时作为 `draft_id` 传给 `POST /status-page/change/create` 或 `POST /status-page/change/timeline/create`。"
+          },
+          "created_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "创建时间，Unix epoch 秒。"
+          }
+        }
       },
       "StatusPageInfoResponse": {
         "allOf": [
@@ -25490,108 +26492,123 @@
         "type": "object"
       },
       "StatusPageItem": {
+        "type": "object",
         "properties": {
-          "components": {
-            "description": "状态页跟踪的组件。",
-            "items": {
-              "$ref": "#/components/schemas/StatusPageComponentItem"
-            },
-            "type": "array"
+          "page_id": {
+            "type": "integer",
+            "description": "状态页 ID。",
+            "format": "int64"
+          },
+          "name": {
+            "type": "string",
+            "description": "状态页显示名称。"
+          },
+          "url_name": {
+            "type": "string",
+            "description": "状态页的 URL 安全 slug，在账户内同类型状态页中唯一。"
+          },
+          "type": {
+            "type": "string",
+            "description": "状态页可见性类型。`public` 为公开状态页，任何人可访问，订阅方式为邮件；`internal` 为内部状态页，仅账户成员可访问，订阅方式为 IM。",
+            "enum": [
+              "public",
+              "internal"
+            ]
+          },
+          "custom_domain": {
+            "type": "string",
+            "description": "指向状态页的自定义域名。未设置时不返回。"
+          },
+          "logo": {
+            "type": "string",
+            "description": "状态页 Logo 图片。未设置时不返回。"
+          },
+          "dark_logo": {
+            "type": "string",
+            "description": "状态页暗色模式 Logo 图片。未设置时不返回。"
           },
-          "contact_info": {
-            "description": "联系方式，mailto 或网站 URL。未设置时不返回。",
-            "type": "string"
+          "logo_url": {
+            "type": "string",
+            "description": "点击 Logo 时跳转的 URL。未设置时不返回。"
           },
-          "custom_domain": {
-            "description": "指向状态页的自定义域名。未设置时不返回。",
-            "type": "string"
+          "favicon": {
+            "type": "string",
+            "description": "状态页的网站图标。未设置时不返回。"
           },
-          "custom_links": {
-            "description": "状态页上展示的自定义导航链接。未设置时不返回。",
-            "items": {
-              "additionalProperties": {
-                "type": "string"
-              },
-              "type": "object"
-            },
-            "type": "array"
+          "page_header": {
+            "type": "string",
+            "description": "状态页头部内容。未设置时不返回。"
           },
-          "dark_logo": {
-            "description": "状态页暗色模式 Logo 图片。未设置时不返回。",
-            "type": "string"
+          "page_footer": {
+            "type": "string",
+            "description": "状态页底部内容。未设置时不返回。"
           },
           "date_view": {
+            "type": "string",
             "description": "时间线的展示方式。`calendar` 以日历视图展示事件日期；`list` 以列表视图展示。未设置时不返回。",
             "enum": [
               "calendar",
               "list"
-            ],
-            "type": "string"
+            ]
           },
           "display_uptime_mode": {
+            "type": "string",
             "description": "可用率的展示方式。`chart_and_percentage` 同时展示可用率图表与百分比数值；`chart` 仅展示图表；`none` 不展示可用率。未设置时不返回。",
             "enum": [
               "chart_and_percentage",
               "chart",
               "none"
-            ],
-            "type": "string"
-          },
-          "favicon": {
-            "description": "状态页的网站图标。未设置时不返回。",
-            "type": "string"
-          },
-          "logo": {
-            "description": "状态页 Logo 图片。未设置时不返回。",
-            "type": "string"
-          },
-          "logo_url": {
-            "description": "点击 Logo 时跳转的 URL。未设置时不返回。",
-            "type": "string"
-          },
-          "name": {
-            "description": "状态页显示名称。",
-            "type": "string"
+            ]
           },
-          "page_footer": {
-            "description": "状态页底部内容。未设置时不返回。",
-            "type": "string"
+          "custom_links": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "key": {
+                  "type": "string",
+                  "description": "页面上显示的链接文字。"
+                },
+                "value": {
+                  "type": "string",
+                  "description": "链接文字指向的地址，例如 `https://www.example.com`。"
+                }
+              },
+              "additionalProperties": {
+                "type": "string"
+              }
+            },
+            "description": "状态页上展示的自定义导航链接。未设置时不返回。"
           },
-          "page_header": {
-            "description": "状态页头部内容。未设置时不返回。",
-            "type": "string"
+          "contact_info": {
+            "type": "string",
+            "description": "联系方式，mailto 或网站 URL。未设置时不返回。"
           },
-          "page_id": {
-            "description": "状态页 ID。",
-            "format": "int64",
-            "type": "integer"
+          "components": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/StatusPageComponentItem"
+            },
+            "description": "状态页跟踪的组件。"
           },
           "sections": {
-            "description": "对组件进行分组的分组列表。",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/StatusPageSectionItem"
             },
-            "type": "array"
+            "description": "对组件进行分组的分组列表。"
           },
           "subscription": {
             "$ref": "#/components/schemas/StatusPageSubscriptionItem",
             "description": "订阅渠道开关。"
           },
           "template_preference": {
-            "description": "偏好的事件模板类型：`pre_defined` 或 `message`。从未设置时不返回。",
-            "type": "string"
-          },
-          "type": {
-            "description": "状态页可见性类型。`public` 为公开状态页，任何人可访问，订阅方式为邮件；`internal` 为内部状态页，仅账户成员可访问，订阅方式为 IM。",
+            "type": "string",
+            "description": "控制台发布事件时使用的模板模式：`message`（状态描述：按状态预设的描述文字）或 `pre_defined`（完整状态更新：包含标题、状态和描述的完整示例）。从未设置时省略，控制台此时按 `message` 处理。",
             "enum": [
-              "public",
-              "internal"
-            ],
-            "type": "string"
-          },
-          "url_name": {
-            "description": "URL 安全的别名，在账户内唯一。",
-            "type": "string"
+              "pre_defined",
+              "message"
+            ]
           }
         },
         "required": [
@@ -25602,8 +26619,7 @@
           "components",
           "sections",
           "subscription"
-        ],
-        "type": "object"
+        ]
       },
       "StatusPageMessageTemplate": {
         "description": "消息模板：某一事件类型下、按状态划分的通知文案。在 `POST /status-page/template/upsert` 中，省略 `template_id` 表示创建，提供则表示更新；更新时仅应用非空字段。",
@@ -25635,136 +26651,136 @@
         "type": "object"
       },
       "StatusPageMigrationJob": {
+        "type": "object",
         "description": "迁移任务的当前状态及进度。",
+        "required": [
+          "job_id",
+          "account_id",
+          "source_page_id",
+          "target_page_id",
+          "phase",
+          "status",
+          "progress",
+          "created_at",
+          "updated_at"
+        ],
         "properties": {
-          "account_id": {
-            "description": "所属账户 ID。",
-            "format": "int64",
-            "type": "integer"
+          "job_id": {
+            "type": "string",
+            "description": "迁移任务 ID。"
           },
-          "created_at": {
-            "description": "任务创建时间（Unix 时间戳，秒）。",
+          "account_id": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "所属账户 ID。"
           },
-          "error": {
-            "description": "`status` 为 `failed` 时的终态错误信息。任务未失败时不返回该字段。",
-            "type": "string"
+          "source_page_id": {
+            "type": "string",
+            "description": "Atlassian Statuspage 源状态页 ID。"
           },
-          "job_id": {
-            "description": "迁移任务 ID。",
-            "type": "string"
+          "target_page_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Flashduty 目标状态页 ID。结构迁移在状态页创建或复用前为 0；订阅者迁移为请求中的 `target_page_id`。"
           },
           "phase": {
-            "description": "当前迁移阶段。`structure` 迁移页面结构（分区与组件）；`history` 迁移历史故障、维护记录与事件模板；`subscribers` 迁移邮件订阅者。",
+            "type": "string",
             "enum": [
               "structure",
               "history",
               "subscribers"
             ],
-            "type": "string"
-          },
-          "progress": {
-            "$ref": "#/components/schemas/StatusPageMigrationProgress",
-            "description": "按实体类型的进度计数。"
-          },
-          "source_page_id": {
-            "description": "Atlassian Statuspage 源状态页 ID。",
-            "type": "string"
+            "description": "当前迁移阶段。`structure` 迁移页面结构（分区与组件）；`history` 迁移历史故障、维护记录与事件模板；`subscribers` 迁移邮件订阅者。"
           },
           "status": {
-            "description": "任务当前状态。\n| 值 | 含义 |\n|---|---|\n| `running` | 执行中。 |\n| `completed` | 已全部完成。 |\n| `failed` | 执行失败，`error` 字段含失败原因。 |\n| `cancelled` | 已被取消。 |",
+            "type": "string",
             "enum": [
               "running",
               "completed",
               "failed",
               "cancelled"
             ],
-            "type": "string"
+            "description": "任务当前状态。\n| 值 | 含义 |\n|---|---|\n| `running` | 执行中。 |\n| `completed` | 已全部完成。 |\n| `failed` | 执行失败，`error` 字段含失败原因。 |\n| `cancelled` | 已被取消。 |"
           },
-          "target_page_id": {
-            "description": "Flashduty 目标状态页 ID。任务产出后设置，或由订阅者迁移接口上游传入。",
+          "progress": {
+            "$ref": "#/components/schemas/StatusPageMigrationProgress",
+            "description": "按实体类型的进度计数。"
+          },
+          "error": {
+            "type": "string",
+            "description": "`status` 为 `failed` 时的终态错误信息。任务未失败时不返回该字段。"
+          },
+          "created_at": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "任务创建时间（Unix 时间戳，秒）。"
           },
           "updated_at": {
-            "description": "任务最近一次状态更新时间（Unix 时间戳，秒）。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "任务最近一次状态更新时间（Unix 时间戳，秒）。"
           }
-        },
-        "required": [
-          "job_id",
-          "account_id",
-          "source_page_id",
-          "target_page_id",
-          "phase",
-          "status",
-          "progress",
-          "created_at",
-          "updated_at"
-        ],
-        "type": "object"
+        }
       },
       "StatusPageMigrationProgress": {
+        "type": "object",
         "description": "迁移任务的进度计数。",
+        "required": [
+          "total_steps",
+          "completed_steps",
+          "components_imported",
+          "sections_imported",
+          "incidents_imported",
+          "maintenances_imported",
+          "subscribers_imported",
+          "templates_imported",
+          "subscribers_skipped"
+        ],
         "properties": {
+          "total_steps": {
+            "type": "integer",
+            "description": "任务总步数：结构迁移为 5（状态页、分组、组件、故障与维护、模板），订阅者迁移为 1。"
+          },
           "completed_steps": {
-            "description": "已完成的步骤数。",
-            "type": "integer"
+            "type": "integer",
+            "description": "已完成的步骤数。"
           },
           "components_imported": {
-            "description": "已从源状态页导入的组件数量。",
-            "type": "integer"
+            "type": "integer",
+            "description": "已从源状态页导入的组件数量。"
+          },
+          "sections_imported": {
+            "type": "integer",
+            "description": "已从源状态页导入的分区（对应 Atlassian component group）数量。"
           },
           "incidents_imported": {
-            "description": "已导入的历史故障数量。",
-            "type": "integer"
+            "type": "integer",
+            "description": "已导入的历史故障数量。"
           },
           "maintenances_imported": {
-            "description": "已导入的计划维护数量。",
-            "type": "integer"
-          },
-          "sections_imported": {
-            "description": "已从源状态页导入的分区（对应 Atlassian component group）数量。",
-            "type": "integer"
+            "type": "integer",
+            "description": "已导入的计划维护数量。"
           },
           "subscribers_imported": {
-            "description": "已成功导入的邮件订阅者数量。",
-            "type": "integer"
-          },
-          "subscribers_skipped": {
-            "description": "跳过的订阅者数量（例如重复）。",
-            "type": "integer"
+            "type": "integer",
+            "description": "已成功导入的邮件订阅者数量。"
           },
           "templates_imported": {
-            "description": "已成功导入的事件模板数量；导入失败的模板会被跳过并记入 `warnings`。",
-            "type": "integer"
+            "type": "integer",
+            "description": "已成功导入的事件模板数量；导入失败的模板会被跳过并记入 `warnings`。"
           },
-          "total_steps": {
-            "description": "任务包含的总步骤数。",
-            "type": "integer"
+          "subscribers_skipped": {
+            "type": "integer",
+            "description": "因非邮件订阅、无邮箱地址或已被隔离而跳过的源订阅者数量。目标页上已存在的接收人不计入此数。"
           },
           "warnings": {
-            "description": "任务执行过程中记录的非致命警告。无告警时不返回该字段。",
+            "type": "array",
             "items": {
               "type": "string"
             },
-            "type": "array"
+            "description": "任务执行过程中记录的非致命警告。无告警时不返回该字段。"
           }
-        },
-        "required": [
-          "total_steps",
-          "completed_steps",
-          "components_imported",
-          "sections_imported",
-          "incidents_imported",
-          "maintenances_imported",
-          "subscribers_imported",
-          "templates_imported",
-          "subscribers_skipped"
-        ],
-        "type": "object"
+        }
       },
       "StatusPageMigrationStartResponse": {
         "description": "启动迁移任务的结果。",
@@ -25780,14 +26796,27 @@
         "type": "object"
       },
       "StatusPagePreDefinedTemplate": {
+        "type": "object",
         "description": "预定义事件模板：可复用的事件草稿（标题、类型、状态、描述）。在 `POST /status-page/template/upsert` 中，省略 `template_id` 表示创建，提供则表示更新；更新时仅应用非空字段。",
         "properties": {
-          "description": {
-            "description": "模板正文（Markdown）。",
-            "type": "string"
+          "template_id": {
+            "type": "string",
+            "description": "模板 ID。省略表示创建新模板；提供表示更新已有模板。"
+          },
+          "title": {
+            "type": "string",
+            "description": "模板标题。"
+          },
+          "type": {
+            "type": "string",
+            "enum": [
+              "incident",
+              "maintenance"
+            ],
+            "description": "模板适用的事件类型：`incident` 为非计划故障，`maintenance` 为计划维护。仅创建时设置，更新时忽略。"
           },
           "status": {
-            "description": "模板对应的事件状态。故障事件支持 `investigating`/`identified`/`monitoring`/`resolved`；维护事件支持 `scheduled`/`ongoing`/`completed`。",
+            "type": "string",
             "enum": [
               "investigating",
               "identified",
@@ -25797,26 +26826,13 @@
               "ongoing",
               "completed"
             ],
-            "type": "string"
-          },
-          "template_id": {
-            "description": "模板 ID。省略表示创建新模板；提供表示更新已有模板。",
-            "type": "string"
+            "description": "模板对应的事件状态。故障事件支持 `investigating`/`identified`/`monitoring`/`resolved`；维护事件支持 `scheduled`/`ongoing`/`completed`。"
           },
-          "title": {
-            "description": "模板标题。",
-            "type": "string"
-          },
-          "type": {
-            "description": "模板适用的事件类型：`incident` 故障，`maintenance` 计划维护。",
-            "enum": [
-              "incident",
-              "maintenance"
-            ],
-            "type": "string"
+          "description": {
+            "type": "string",
+            "description": "模板正文（Markdown）。"
           }
-        },
-        "type": "object"
+        }
       },
       "StatusPageSectionItem": {
         "properties": {
@@ -25904,70 +26920,69 @@
         "type": "object"
       },
       "StringMapPatch": {
-        "description": "map 字段的增量更新：`set` 中的键会被插入或覆盖，`delete` 中的键会被删除，其余键保持不变。",
+        "type": "object",
+        "description": "map 字段的增量更新：`set` 中的键会被插入或覆盖，`delete` 中的键会被删除，其余键保持不变。`set` / `delete` 至少一个非空，键不能为空白，同一个键不能同时出现在两者中，也不能在 `delete` 中重复。",
         "properties": {
-          "delete": {
-            "description": "要删除的键。",
-            "items": {
+          "set": {
+            "type": "object",
+            "additionalProperties": {
               "type": "string"
             },
-            "type": "array"
+            "description": "要插入或覆盖的键值对。"
           },
-          "set": {
-            "additionalProperties": {
+          "delete": {
+            "type": "array",
+            "items": {
               "type": "string"
             },
-            "description": "要插入或覆盖的键值对。",
-            "type": "object"
+            "description": "要删除的键。"
           }
-        },
-        "type": "object"
+        }
       },
       "SuccessEnvelope": {
+        "type": "object",
         "description": "成功响应结构。2xx 响应中 `request_id` 标识本次调用（同时出现在 `Flashcat-Request-Id` 响应头中），`data` 为接口业务 payload。失败响应使用不同结构，参见 `ErrorResponse`。",
         "properties": {
-          "data": {
-            "description": "每个接口自己的业务 payload，详见各接口的 200 响应 schema。"
-          },
           "request_id": {
+            "type": "string",
             "description": "本次请求的唯一 ID，也会在 Flashcat-Request-Id 响应头中返回。反馈问题时请一并附上。",
-            "example": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
-            "type": "string"
+            "example": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
+          },
+          "data": {
+            "description": "接口返回的数据，格式见各接口的 200 响应。没有返回数据的接口会返回 `{}` 或完全不带 `data`。"
           }
         },
         "required": [
-          "request_id",
-          "data"
-        ],
-        "type": "object"
+          "request_id"
+        ]
       },
       "TeamBriefItem": {
+        "type": "object",
         "description": "批量响应中的团队简要信息。",
         "properties": {
-          "person_ids": {
-            "description": "团队成员的人员 ID 数组；团队无成员时为空数组（不为 null）。",
-            "items": {
-              "format": "uint64",
-              "type": "integer"
-            },
-            "type": "array"
-          },
           "team_id": {
-            "description": "团队 ID。",
+            "type": "integer",
             "format": "uint64",
-            "type": "integer"
+            "description": "团队 ID，取自请求中的 `team_ids`。"
           },
           "team_name": {
-            "description": "团队名称。",
-            "type": "string"
+            "type": "string",
+            "description": "团队名称。结果包含已删除的团队，因此可能是已不在 `POST /team/list` 中出现的团队名称。"
+          },
+          "person_ids": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "uint64"
+            },
+            "description": "团队成员的人员 ID 数组；团队无成员时为空数组（不为 null）。"
           }
         },
         "required": [
           "team_id",
           "team_name",
           "person_ids"
-        ],
-        "type": "object"
+        ]
       },
       "TeamDeleteRequest": {
         "anyOf": [
@@ -26059,107 +27074,110 @@
         "type": "object"
       },
       "TeamInfosResponse": {
+        "type": "object",
         "description": "批量团队查询结果。",
+        "required": [
+          "items"
+        ],
         "properties": {
           "items": {
-            "description": "按请求 `team_ids` 命中的团队简要信息数组；未命中任何 ID 时可能为 null。",
+            "type": [
+              "array",
+              "null"
+            ],
             "items": {
               "$ref": "#/components/schemas/TeamBriefItem"
             },
-            "type": "array"
+            "description": "匹配到的团队简要信息（包括已删除的团队）；没有任何 ID 匹配时为 `null`。"
           }
-        },
-        "required": [
-          "items"
-        ],
-        "type": "object"
+        }
       },
       "TeamItem": {
+        "type": "object",
         "description": "团队及其成员信息。",
+        "required": [
+          "account_id",
+          "team_id",
+          "team_name",
+          "description",
+          "status",
+          "updated_by_name",
+          "updated_by",
+          "creator_id",
+          "creator_name",
+          "created_at",
+          "updated_at",
+          "person_ids",
+          "ref_id"
+        ],
         "properties": {
           "account_id": {
-            "description": "所属账户 ID。",
+            "type": "integer",
             "format": "uint64",
-            "type": "integer"
-          },
-          "created_at": {
-            "description": "创建时间（Unix 秒）。",
-            "format": "int64",
-            "type": "integer"
+            "description": "所属账户 ID。"
           },
-          "creator_id": {
-            "description": "创建人成员 ID。",
+          "team_id": {
+            "type": "integer",
             "format": "uint64",
-            "type": "integer"
+            "description": "唯一团队 ID。"
           },
-          "creator_name": {
-            "description": "创建者显示名称。当前接口不填充该字段，恒为空字符串；请用 `creator_id` 调用 `POST /person/infos` 解析。",
-            "type": "string"
+          "team_name": {
+            "type": "string",
+            "description": "团队显示名称，1–39 个字符，账户内唯一。"
           },
           "description": {
-            "description": "自定义描述。",
-            "type": "string"
-          },
-          "person_ids": {
-            "description": "团队成员的成员 ID 列表。",
-            "items": {
-              "format": "uint64",
-              "type": "integer"
-            },
-            "type": "array"
-          },
-          "ref_id": {
-            "description": "外部引用 ID，用于与第三方 HR 系统集成。",
-            "type": "string"
+            "type": "string",
+            "description": "自定义描述。"
           },
           "status": {
-            "description": "团队状态。`enabled` —— 正常；`deleted` —— 已删除（仅按 `team_id` 查询已删除团队时可能返回；列表及按名称/ref_id 查询均排除已删除团队）。",
+            "type": "string",
             "enum": [
               "enabled",
               "deleted"
             ],
-            "type": "string"
+            "description": "团队状态。`enabled` —— 正常；`deleted` —— 已删除（仅按 `team_id` 查询已删除团队时可能返回；列表及按名称/ref_id 查询均排除已删除团队）。"
           },
-          "team_id": {
-            "description": "唯一团队 ID。",
+          "updated_by_name": {
+            "type": "string",
+            "description": "最后编辑人的名称：成员名称；账户主体编辑时为账户名称；无法解析时为空字符串。"
+          },
+          "updated_by": {
+            "type": "integer",
             "format": "uint64",
-            "type": "integer"
+            "description": "最后修改人成员 ID。"
           },
-          "team_name": {
-            "description": "团队显示名称，1–39 个字符，账户内唯一。",
-            "type": "string"
+          "creator_id": {
+            "type": "integer",
+            "format": "uint64",
+            "description": "创建人成员 ID。"
+          },
+          "creator_name": {
+            "type": "string",
+            "description": "创建者显示名称。当前接口不填充该字段，恒为空字符串；请用 `creator_id` 调用 `POST /person/infos` 解析。"
+          },
+          "created_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "创建时间（Unix 秒）。"
           },
           "updated_at": {
-            "description": "最近更新时间（Unix 秒）。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "最近更新时间（Unix 秒）。"
           },
-          "updated_by": {
-            "description": "最后修改人成员 ID。",
-            "format": "uint64",
-            "type": "integer"
+          "person_ids": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "uint64"
+            },
+            "description": "团队成员的人员 ID（即成员 ID；账户主体在团队中时为账户 ID）。团队没有成员时为空数组。"
           },
-          "updated_by_name": {
-            "description": "最后修改人显示名称。",
-            "type": "string"
+          "ref_id": {
+            "type": "string",
+            "description": "外部引用 ID，用于与第三方 HR 系统集成。"
           }
-        },
-        "required": [
-          "account_id",
-          "team_id",
-          "team_name",
-          "description",
-          "status",
-          "updated_by_name",
-          "updated_by",
-          "creator_id",
-          "creator_name",
-          "created_at",
-          "updated_at",
-          "person_ids",
-          "ref_id"
-        ],
-        "type": "object"
+        }
       },
       "TeamListRequest": {
         "description": "查询团队列表的过滤参数。",
@@ -26203,95 +27221,95 @@
         "type": "object"
       },
       "TeamListResponse": {
+        "type": "object",
         "description": "分页团队列表。",
-        "properties": {
-          "items": {
-            "description": "当前页的团队数组，与 `p`、`limit`、`total` 配合分页；空页时为空数组。",
-            "items": {
-              "$ref": "#/components/schemas/TeamItem"
-            },
-            "type": "array"
-          },
-          "limit": {
-            "description": "本次使用的分页大小。",
-            "type": "integer"
-          },
-          "p": {
-            "description": "当前页码。",
-            "type": "integer"
-          },
-          "total": {
-            "description": "符合过滤条件的团队总数。",
-            "type": "integer"
-          }
-        },
         "required": [
           "p",
           "limit",
           "total",
           "items"
         ],
-        "type": "object"
+        "properties": {
+          "p": {
+            "type": "integer",
+            "description": "请求中的页码；未传 `p` 时为 `0`（返回的是第一页）。"
+          },
+          "limit": {
+            "type": "integer",
+            "description": "实际使用的每页条数；未传 `limit` 时为 20。"
+          },
+          "total": {
+            "type": "integer",
+            "description": "符合筛选条件的未删除团队总数（跨所有页）。"
+          },
+          "items": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/TeamItem"
+            },
+            "description": "当前页的团队数组，与 `p`、`limit`、`total` 配合分页；空页时为空数组。"
+          }
+        }
       },
       "TeamUpsertRequest": {
+        "type": "object",
+        "required": [
+          "team_name"
+        ],
         "description": "创建或更新团队的参数。",
         "properties": {
-          "countryCode": {
-            "description": "默认国家区号，用于 `phones` 中未采用 E.164 格式的手机号。",
-            "type": "string"
+          "team_id": {
+            "type": "integer",
+            "format": "uint64",
+            "description": "要更新的团队 ID。省略或置为 0 表示创建新团队；非 0 时必须是本账户已有团队的 ID。"
+          },
+          "team_name": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 39,
+            "description": "团队显示名称，1–39 个字符。"
           },
           "description": {
-            "description": "自定义描述。",
+            "type": "string",
             "maxLength": 500,
-            "type": "string"
+            "description": "自由文本描述，最多 500 个字符。更新时不传会清空原有描述。"
           },
-          "emails": {
-            "description": "按邮箱匹配现有成员加入团队；未匹配到成员的地址会被静默忽略，不会发起邀请。",
+          "person_ids": {
+            "type": "array",
             "items": {
-              "format": "email",
-              "type": "string"
+              "type": "integer",
+              "format": "uint64"
             },
-            "type": "array"
+            "description": "要加入团队的人员 ID（成员 ID；账户主体使用账户 ID）。与 `emails`、`phones` 合并后整体替换成员列表；不是本账户成员的 ID 会被忽略。"
           },
-          "person_ids": {
-            "description": "设置为团队成员的成员 ID 列表，会替换现有成员列表。",
+          "emails": {
+            "type": "array",
             "items": {
-              "format": "uint64",
-              "type": "integer"
+              "type": "string",
+              "format": "email"
             },
-            "type": "array"
+            "description": "要加入团队的已有成员邮箱，与 `person_ids`、`phones` 合并。匹配不到成员的邮箱会被忽略，不会发出邀请。"
           },
           "phones": {
-            "description": "按手机号把已存在的成员加入团队。非 E.164 格式的号码会按 `countryCode` 解析；无法解析的号码导致整个请求返回 400。能解析但不属于任何现有成员的号码会被静默忽略。",
+            "type": "array",
             "items": {
               "type": "string"
             },
-            "type": "array"
+            "description": "要加入团队的已有成员手机号，与 `person_ids`、`emails` 合并。不带 `+` 前缀的号码按 `countryCode` 解析；无法解析的号码会使整个请求返回 `400`，匹配不到成员的号码会被忽略。"
+          },
+          "countryCode": {
+            "type": "string",
+            "description": "`phones` 中不带 `+` 前缀号码的地区提示：ISO 3166-1 alpha-2 地区代码（如 `CN`，未传时默认）或数字区号（如 `86`）。"
           },
           "ref_id": {
-            "description": "供 HR 系统集成使用的外部引用 ID。",
-            "type": "string"
+            "type": "string",
+            "description": "外部引用 ID（如 HR 系统中的部门 ID），可在 `POST /team/info`、`POST /team/delete` 中作为查找键。更新时不传会清空原值。"
           },
           "reset_if_name_exist": {
-            "description": "为 true 且 `team_id` 为 0 时，若已存在同名团队，则原地更新该团队，而不是返回名称冲突错误。",
-            "type": "boolean"
-          },
-          "team_id": {
-            "description": "团队 ID，省略或置为 0 表示创建新团队。",
-            "format": "uint64",
-            "type": "integer"
-          },
-          "team_name": {
-            "description": "团队显示名称，1–39 个字符。",
-            "maxLength": 39,
-            "minLength": 1,
-            "type": "string"
-          }
-        },
-        "required": [
-          "team_name"
-        ],
-        "type": "object"
+            "type": "boolean",
+            "description": "为 true 且 `team_id` 为 0 时，若已存在同名团队，则原地更新该团队，而不是返回名称冲突错误。"
+          }
+        }
       },
       "TeamUpsertResponse": {
         "description": "创建或更新团队的结果。",
@@ -26313,50 +27331,111 @@
         "type": "object"
       },
       "TemplateCreateRequest": {
+        "type": "object",
         "description": "创建通知模板。",
+        "required": [
+          "template_name"
+        ],
         "properties": {
+          "team_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "所属团队 ID，可通过 `POST /team/list` 获取；`0`（默认）表示账户级。非 0 时须为已存在的团队。",
+            "default": 0
+          },
+          "template_name": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 39,
+            "description": "模板名称，1–39 个字符，在账户未删除的模板中唯一，且不能与内置预设模板在任一支持语言下的名称相同。",
+            "example": "Prod incident default"
+          },
           "description": {
-            "description": "自定义描述。最多 500 字符。",
+            "type": "string",
             "maxLength": 500,
-            "type": "string"
+            "description": "自定义描述。最多 500 字符。"
+          },
+          "email": {
+            "type": "string",
+            "description": "邮件正文模板源（Go `html/template` 语法）。"
+          },
+          "sms": {
+            "type": "string",
+            "description": "短信模板源（Go `text/template` 语法）。"
+          },
+          "voice": {
+            "type": "string",
+            "description": "语音呼叫脚本模板源。"
           },
           "dingtalk": {
-            "description": "钉钉群机器人消息模板源。",
-            "type": "string"
+            "type": "string",
+            "description": "钉钉群机器人消息模板源。"
           },
-          "dingtalk_app": {
-            "description": "钉钉应用消息模板源。",
-            "type": "string"
+          "wecom": {
+            "type": "string",
+            "description": "企业微信群机器人消息模板源。"
           },
-          "dingtalk_app_war_room_enabled": {
+          "wecom_markdown_v2_enabled": {
             "type": "boolean",
-            "description": "钉钉应用卡片展示「创建作战室」按钮。"
-          },
-          "email": {
-            "description": "邮件正文模板源（Go `html/template` 语法）。",
-            "type": "string"
+            "description": "企业微信机器人通知使用 `markdown_v2` 消息格式而非普通 markdown。开启时 `wecom` 渲染结果不得超过 4,096 字节。"
           },
           "feishu": {
-            "description": "飞书群机器人消息模板源。",
-            "type": "string"
+            "type": "string",
+            "description": "飞书群机器人消息模板源。"
           },
           "feishu_app": {
-            "description": "飞书应用消息模板源。",
-            "type": "string"
+            "type": "string",
+            "description": "飞书应用消息模板源。"
+          },
+          "feishu_app_card_v2_table_enabled": {
+            "type": "boolean",
+            "default": false,
+            "description": "将 `feishu_app` 内容中的 Markdown 表格渲染为飞书卡片原生表格。"
           },
           "feishu_app_card_v2_preserve_blank_lines": {
             "type": "boolean",
             "description": "飞书应用卡片 v2 消息保留正文中的空行。"
           },
-          "feishu_app_card_v2_table_enabled": {
-            "default": false,
-            "description": "是否在飞书应用卡片中以表格渲染告警标签，默认关闭。",
-            "type": "boolean"
-          },
           "feishu_app_war_room_enabled": {
             "type": "boolean",
             "description": "飞书应用卡片展示「创建作战室」按钮。"
           },
+          "dingtalk_app_war_room_enabled": {
+            "type": "boolean",
+            "description": "钉钉应用卡片展示「创建作战室」按钮。"
+          },
+          "slack_app_war_room_enabled": {
+            "type": "boolean",
+            "description": "Slack 应用卡片展示「创建作战室」按钮。"
+          },
+          "dingtalk_app": {
+            "type": "string",
+            "description": "钉钉应用消息模板源。"
+          },
+          "wecom_app": {
+            "type": "string",
+            "description": "企业微信应用消息模板源。"
+          },
+          "slack_app": {
+            "type": "string",
+            "description": "Slack 应用消息模板源。"
+          },
+          "teams_app": {
+            "type": "string",
+            "description": "Microsoft Teams 应用消息模板源。"
+          },
+          "telegram": {
+            "type": "string",
+            "description": "Telegram 机器人消息模板源。"
+          },
+          "slack": {
+            "type": "string",
+            "description": "Slack 机器人消息模板源。"
+          },
+          "zoom": {
+            "type": "string",
+            "description": "Zoom 机器人消息模板源。"
+          },
           "incident_card_closed_action_apps": {
             "type": "array",
             "items": {
@@ -26373,70 +27452,9 @@
           },
           "incident_card_hidden_fields": {
             "$ref": "#/components/schemas/IncidentCardHiddenFields",
-            "description": "按 IM 应用类型隐藏的故障卡片字段。"
-          },
-          "slack": {
-            "description": "Slack 机器人消息模板源。",
-            "type": "string"
-          },
-          "slack_app": {
-            "description": "Slack 应用消息模板源。",
-            "type": "string"
-          },
-          "slack_app_war_room_enabled": {
-            "type": "boolean",
-            "description": "Slack 应用卡片展示「创建作战室」按钮。"
-          },
-          "sms": {
-            "description": "短信模板源（Go `text/template` 语法）。",
-            "type": "string"
-          },
-          "team_id": {
-            "default": 0,
-            "description": "团队归属。0 表示账户全局共享。",
-            "format": "int64",
-            "type": "integer"
-          },
-          "teams_app": {
-            "description": "Microsoft Teams 应用消息模板源。",
-            "type": "string"
-          },
-          "telegram": {
-            "description": "Telegram 机器人消息模板源。",
-            "type": "string"
-          },
-          "template_name": {
-            "description": "模板名称，同一账户内唯一，长度 1–39 个字符。",
-            "example": "Prod incident default",
-            "maxLength": 39,
-            "minLength": 1,
-            "type": "string"
-          },
-          "voice": {
-            "description": "语音呼叫脚本模板源。",
-            "type": "string"
-          },
-          "wecom": {
-            "description": "企业微信群机器人消息模板源。",
-            "type": "string"
-          },
-          "wecom_app": {
-            "description": "企业微信应用消息模板源。",
-            "type": "string"
-          },
-          "wecom_markdown_v2_enabled": {
-            "type": "boolean",
-            "description": "企业微信群机器人通知使用 `markdown_v2` 消息格式，而非普通 markdown。"
-          },
-          "zoom": {
-            "description": "Zoom 机器人消息模板源。",
-            "type": "string"
+            "description": "按 IM 应用类型配置要隐藏的故障卡片字段。"
           }
-        },
-        "required": [
-          "template_name"
-        ],
-        "type": "object"
+        }
       },
       "TemplateCreateResponse": {
         "description": "创建模板响应。",
@@ -26475,70 +27493,152 @@
         "type": "object"
       },
       "TemplateItem": {
+        "type": "object",
         "description": "一个通知模板。每个通道字段中存放该通道的模板源字符串；空字符串表示该通道没有自定义模板。",
+        "required": [
+          "account_id",
+          "team_id",
+          "template_id",
+          "template_name",
+          "description",
+          "email",
+          "sms",
+          "voice",
+          "dingtalk",
+          "wecom",
+          "feishu",
+          "feishu_app",
+          "feishu_app_card_v2_table_enabled",
+          "wecom_markdown_v2_enabled",
+          "feishu_app_card_v2_preserve_blank_lines",
+          "feishu_app_war_room_enabled",
+          "dingtalk_app_war_room_enabled",
+          "slack_app_war_room_enabled",
+          "dingtalk_app",
+          "wecom_app",
+          "slack_app",
+          "teams_app",
+          "telegram",
+          "slack",
+          "zoom",
+          "status",
+          "creator_id",
+          "updated_by",
+          "created_at",
+          "updated_at",
+          "incident_card_closed_action_apps",
+          "incident_card_hidden_fields"
+        ],
         "properties": {
           "account_id": {
-            "description": "所属账户 ID。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "所属账户 ID。"
           },
-          "created_at": {
-            "description": "创建时间（Unix 秒）。",
+          "team_id": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "所属团队 ID，0 表示账户全局共享。"
           },
-          "creator_id": {
-            "description": "创建人成员 ID。",
-            "format": "int64",
-            "type": "integer"
+          "template_id": {
+            "type": "string",
+            "pattern": "^[0-9a-fA-F]{24}$",
+            "description": "模板 ID（24 位十六进制）。内置预设模板的 ID 固定为 `6321aad26c12104586a88916`。",
+            "example": "6605a1b2c3d4e5f6a7b8c9d0"
           },
-          "deleted_at": {
-            "description": "软删除时间（Unix 秒）。模板未删除时字段缺省（omitempty）。",
-            "format": "int64",
-            "type": "integer"
+          "template_name": {
+            "type": "string",
+            "description": "模板名称，同一账户内唯一。"
           },
           "description": {
-            "description": "自定义描述。",
-            "type": "string"
+            "type": "string",
+            "description": "描述文字（最多 500 字符），未填写时为空字符串。"
+          },
+          "email": {
+            "type": "string",
+            "description": "邮件正文模板源（Go `html/template` 语法）。"
+          },
+          "sms": {
+            "type": "string",
+            "description": "短信模板源（Go `text/template` 语法）。"
+          },
+          "voice": {
+            "type": "string",
+            "description": "语音呼叫脚本模板源。"
           },
           "dingtalk": {
-            "description": "钉钉群机器人消息模板源。",
-            "type": "string"
+            "type": "string",
+            "description": "钉钉群机器人消息模板源。"
           },
-          "dingtalk_app": {
-            "description": "钉钉应用消息模板源。",
-            "type": "string"
+          "wecom": {
+            "type": "string",
+            "description": "企业微信群机器人消息模板源。"
           },
-          "dingtalk_app_war_room_enabled": {
+          "wecom_markdown_v2_enabled": {
             "type": "boolean",
-            "description": "钉钉应用卡片是否展示「创建作战室」按钮；故障已关闭或无响应人时不展示。"
-          },
-          "email": {
-            "description": "邮件正文模板源（Go `html/template` 语法）。",
-            "type": "string"
+            "description": "企业微信群机器人通知是否使用 `markdown_v2` 消息格式。"
           },
           "feishu": {
-            "description": "飞书群机器人消息模板源。",
-            "type": "string"
+            "type": "string",
+            "description": "飞书群机器人消息模板源。"
           },
           "feishu_app": {
-            "description": "飞书应用消息模板源。",
-            "type": "string"
+            "type": "string",
+            "description": "飞书应用消息模板源。"
+          },
+          "feishu_app_card_v2_table_enabled": {
+            "type": "boolean",
+            "description": "`feishu_app` 内容中的 Markdown 表格是否渲染为飞书卡片原生表格。"
           },
           "feishu_app_card_v2_preserve_blank_lines": {
             "type": "boolean",
             "description": "飞书应用卡片 v2 消息是否保留正文中的空行。"
           },
-          "feishu_app_card_v2_table_enabled": {
-            "description": "是否在飞书应用卡片中以表格渲染告警标签。",
-            "type": "boolean"
-          },
           "feishu_app_war_room_enabled": {
             "type": "boolean",
             "description": "飞书应用卡片是否展示「创建作战室」按钮；故障无响应人时不展示。"
           },
+          "dingtalk_app_war_room_enabled": {
+            "type": "boolean",
+            "description": "钉钉应用卡片是否展示「创建作战室」按钮；故障已关闭或无响应人时不展示。"
+          },
+          "slack_app_war_room_enabled": {
+            "type": "boolean",
+            "description": "Slack 应用卡片是否展示「创建作战室」按钮；故障已关闭或无响应人时不展示。"
+          },
+          "dingtalk_app": {
+            "type": "string",
+            "description": "钉钉应用消息模板源。"
+          },
+          "wecom_app": {
+            "type": "string",
+            "description": "企业微信应用消息模板源。"
+          },
+          "slack_app": {
+            "type": "string",
+            "description": "Slack 应用消息模板源。"
+          },
+          "teams_app": {
+            "type": "string",
+            "description": "Microsoft Teams 应用消息模板源。"
+          },
+          "telegram": {
+            "type": "string",
+            "description": "Telegram 机器人消息模板源。"
+          },
+          "slack": {
+            "type": "string",
+            "description": "Slack 机器人消息模板源。"
+          },
+          "zoom": {
+            "type": "string",
+            "description": "Zoom 机器人消息模板源。"
+          },
           "incident_card_closed_action_apps": {
-            "type": "array",
+            "type": [
+              "array",
+              "null"
+            ],
             "items": {
               "type": "string",
               "enum": [
@@ -26549,185 +27649,106 @@
                 "teams_app"
               ]
             },
-            "description": "已关闭故障的卡片仍保留自定义操作按钮的 IM 应用。可选值：`feishu_app`、`dingtalk_app`、`wecom_app`、`slack_app`、`teams_app`；空列表表示所有应用都隐藏这些按钮。"
+            "description": "对已关闭故障的卡片仍保留自定义操作按钮的 IM 应用（未关闭的故障总会显示）。取值：`feishu_app`、`dingtalk_app`、`wecom_app`、`slack_app`、`teams_app`。为空或 `null` 时，所有应用的已关闭故障卡片都隐藏这些按钮。"
           },
           "incident_card_hidden_fields": {
             "$ref": "#/components/schemas/IncidentCardHiddenFields",
             "description": "按 IM 应用类型配置的故障卡片隐藏字段，未配置时为空对象。"
           },
-          "slack": {
-            "description": "Slack 机器人消息模板源。",
-            "type": "string"
-          },
-          "slack_app": {
-            "description": "Slack 应用消息模板源。",
-            "type": "string"
-          },
-          "slack_app_war_room_enabled": {
-            "type": "boolean",
-            "description": "Slack 应用卡片是否展示「创建作战室」按钮；故障已关闭或无响应人时不展示。"
-          },
-          "sms": {
-            "description": "短信模板源（Go `text/template` 语法）。",
-            "type": "string"
-          },
           "status": {
-            "description": "模板生命周期状态。`enabled` 启用中，可被分派策略引用发送通知；`disabled` 停用，不再用于新通知；`deleted` 已删除，列表接口不返回。",
+            "type": "string",
+            "description": "模板状态。\n- `enabled`：可被分派策略使用。\n- `disabled`：不再用于新通知；无法通过本 API 设置。\n- `deleted`：已被 `/template/delete` 软删除；不出现在 `/template/list` 中，但 `/template/info` 仍会返回。",
             "enum": [
               "enabled",
               "disabled",
               "deleted"
-            ],
-            "type": "string"
-          },
-          "team_id": {
-            "description": "所属团队 ID，0 表示账户全局共享。",
-            "format": "int64",
-            "type": "integer"
-          },
-          "teams_app": {
-            "description": "Microsoft Teams 应用消息模板源。",
-            "type": "string"
-          },
-          "telegram": {
-            "description": "Telegram 机器人消息模板源。",
-            "type": "string"
-          },
-          "template_id": {
-            "description": "模板 ID。",
-            "example": "6605a1b2c3d4e5f6a7b8c9d0",
-            "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
-          },
-          "template_name": {
-            "description": "模板名称，同一账户内唯一。",
-            "type": "string"
+            ]
           },
-          "updated_at": {
-            "description": "最近更新时间（Unix 秒）。",
+          "creator_id": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "创建人成员 ID。"
           },
           "updated_by": {
-            "description": "最后修改人成员 ID。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
-          },
-          "voice": {
-            "description": "语音呼叫脚本模板源。",
-            "type": "string"
-          },
-          "wecom": {
-            "description": "企业微信群机器人消息模板源。",
-            "type": "string"
+            "description": "最后修改人成员 ID。"
           },
-          "wecom_app": {
-            "description": "企业微信应用消息模板源。",
-            "type": "string"
+          "deleted_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "软删除时间（Unix 秒）。模板未删除时字段缺省（omitempty）。"
           },
-          "wecom_markdown_v2_enabled": {
-            "type": "boolean",
-            "description": "企业微信群机器人通知是否使用 `markdown_v2` 消息格式。"
+          "created_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "创建时间（Unix 秒）。"
           },
-          "zoom": {
-            "description": "Zoom 机器人消息模板源。",
-            "type": "string"
+          "updated_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "最近更新时间（Unix 秒）。"
           }
-        },
-        "required": [
-          "account_id",
-          "team_id",
-          "template_id",
-          "template_name",
-          "description",
-          "email",
-          "sms",
-          "voice",
-          "dingtalk",
-          "wecom",
-          "feishu",
-          "feishu_app",
-          "feishu_app_card_v2_table_enabled",
-          "wecom_markdown_v2_enabled",
-          "feishu_app_card_v2_preserve_blank_lines",
-          "feishu_app_war_room_enabled",
-          "dingtalk_app_war_room_enabled",
-          "slack_app_war_room_enabled",
-          "dingtalk_app",
-          "wecom_app",
-          "slack_app",
-          "teams_app",
-          "telegram",
-          "slack",
-          "zoom",
-          "status",
-          "creator_id",
-          "updated_by",
-          "created_at",
-          "updated_at",
-          "incident_card_closed_action_apps",
-          "incident_card_hidden_fields"
-        ],
-        "type": "object"
+        }
       },
       "TemplateListRequest": {
+        "type": "object",
         "description": "分页过滤条件。默认 p=1、limit=20，limit 上限为 100。",
         "properties": {
-          "asc": {
-            "default": false,
-            "description": "升序排序。",
-            "type": "boolean"
-          },
-          "creator_id": {
-            "description": "按创建人成员 ID 过滤，成员 ID 可通过 `POST /member/list` 获取。",
-            "format": "int64",
-            "type": [
-              "integer",
-              "null"
-            ]
-          },
-          "is_my_team": {
-            "default": false,
-            "description": "为 true 时只返回当前成员所属团队范围内的模板。",
-            "type": "boolean"
+          "p": {
+            "type": "integer",
+            "description": "页码，从 1 开始。",
+            "minimum": 1,
+            "default": 1,
+            "example": 1
           },
           "limit": {
-            "default": 20,
+            "type": "integer",
             "description": "分页大小，最大 100。",
-            "example": 20,
-            "maximum": 100,
             "minimum": 1,
-            "type": "integer"
+            "maximum": 100,
+            "default": 20,
+            "example": 20
           },
           "orderby": {
-            "description": "排序字段。",
+            "type": "string",
+            "description": "排序字段：`created_at`（默认，创建时间）或 `updated_at`（最后更新时间）。",
             "enum": [
               "created_at",
               "updated_at"
-            ],
-            "type": "string"
+            ]
           },
-          "p": {
-            "default": 1,
-            "description": "页码，从 1 开始。",
-            "example": 1,
-            "minimum": 1,
-            "type": "integer"
+          "asc": {
+            "type": "boolean",
+            "description": "为 `true` 时正序；默认最新的在前。",
+            "default": false
           },
-          "query": {
-            "description": "按模板名称做正则或子串匹配。",
-            "type": "string"
+          "is_my_team": {
+            "type": "boolean",
+            "description": "为 `true` 时只返回调用方所在团队的模板。同时传了 `team_ids` 时只保留两者共有的团队；两者没有共同团队时不按团队过滤，返回所有团队的模板。调用方不属于任何团队时返回空结果。",
+            "default": false
           },
           "team_ids": {
-            "description": "按团队 ID 列表过滤。",
+            "type": "array",
             "items": {
-              "format": "int64",
-              "type": "integer"
+              "type": "integer",
+              "format": "int64"
             },
-            "type": "array"
+            "description": "只返回这些团队 ID（可通过 `POST /team/list` 获取）的模板；`0` 表示账户级模板。为空或不传时不按团队过滤。与 `is_my_team` 的组合方式见该字段说明。"
+          },
+          "creator_id": {
+            "type": [
+              "integer",
+              "null"
+            ],
+            "format": "int64",
+            "description": "按创建人成员 ID 过滤，成员 ID 可通过 `POST /member/list` 获取。"
+          },
+          "query": {
+            "type": "string",
+            "description": "对 `template_name` 做不区分大小写的正则匹配；不合法的正则按普通文本匹配。"
           }
-        },
-        "type": "object"
+        }
       },
       "TemplateListResponse": {
         "description": "通知模板的分页列表。",
@@ -26759,231 +27780,231 @@
         "type": "object"
       },
       "TemplateUpdateRequest": {
+        "type": "object",
         "description": "更新已存在的模板。",
+        "required": [
+          "template_id",
+          "template_name"
+        ],
         "properties": {
-          "description": {
-            "description": "自定义描述。最多 500 字符。省略时保持当前内容；传空字符串表示清空。",
-            "maxLength": 500,
+          "template_id": {
+            "type": "string",
+            "pattern": "^[0-9a-fA-F]{24}$",
+            "description": "目标模板 ID，可通过 `POST /template/list` 获取。",
+            "example": "6605a1b2c3d4e5f6a7b8c9d0"
+          },
+          "team_id": {
             "type": [
-              "string",
+              "integer",
               "null"
-            ]
+            ],
+            "format": "int64",
+            "description": "团队归属。0 表示账户全局共享。省略时保持模板当前的团队归属。"
           },
-          "dingtalk": {
-            "description": "钉钉群机器人消息模板源。省略时保持当前内容；传空字符串表示清空。",
+          "template_name": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 39,
+            "description": "模板名称，1–39 个字符。每次调用都必填且会被写入；不能与其他模板重名。"
+          },
+          "description": {
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "maxLength": 500,
+            "description": "自定义描述。最多 500 字符。省略时保持当前内容；传空字符串表示清空。"
           },
-          "dingtalk_app": {
-            "description": "钉钉应用消息模板源。省略时保持当前内容；传空字符串表示清空。",
+          "email": {
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "邮件正文模板源（Go `html/template` 语法）。省略时保持当前内容；传空字符串表示清空。"
           },
-          "dingtalk_app_war_room_enabled": {
+          "sms": {
             "type": [
-              "boolean",
+              "string",
               "null"
             ],
-            "description": "设置后决定钉钉应用卡片是否展示「创建作战室」按钮；省略时保持当前设置。"
+            "description": "短信模板源（Go `text/template` 语法）。省略时保持当前内容；传空字符串表示清空。"
           },
-          "email": {
-            "description": "邮件正文模板源（Go `html/template` 语法）。省略时保持当前内容；传空字符串表示清空。",
+          "voice": {
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "语音呼叫脚本模板源。省略时保持当前内容；传空字符串表示清空。"
           },
-          "feishu": {
-            "description": "飞书群机器人消息模板源。省略时保持当前内容；传空字符串表示清空。",
+          "dingtalk": {
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "钉钉群机器人消息模板源。省略时保持当前内容；传空字符串表示清空。"
           },
-          "feishu_app": {
-            "description": "飞书应用消息模板源。省略时保持当前内容；传空字符串表示清空。",
+          "wecom": {
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "企业微信群机器人消息模板源。省略时保持当前内容；传空字符串表示清空。"
           },
-          "feishu_app_card_v2_preserve_blank_lines": {
+          "wecom_markdown_v2_enabled": {
             "type": [
               "boolean",
               "null"
             ],
-            "description": "设置后决定飞书应用卡片 v2 消息是否保留正文空行；省略时保持当前设置。"
+            "description": "企业微信机器人通知使用 `markdown_v2` 消息格式而非普通 markdown。开启时 `wecom` 渲染结果不得超过 4,096 字节。不传则保持不变。"
           },
-          "feishu_app_card_v2_table_enabled": {
-            "description": "设置后开启或关闭飞书应用卡片中的告警标签表格渲染；省略时保持当前设置。",
+          "feishu": {
             "type": [
-              "boolean",
+              "string",
               "null"
-            ]
+            ],
+            "description": "飞书群机器人消息模板源。省略时保持当前内容；传空字符串表示清空。"
           },
-          "feishu_app_war_room_enabled": {
+          "feishu_app": {
             "type": [
-              "boolean",
+              "string",
               "null"
             ],
-            "description": "设置后决定飞书应用卡片是否展示「创建作战室」按钮；省略时保持当前设置。"
+            "description": "飞书应用消息模板源。省略时保持当前内容；传空字符串表示清空。"
           },
-          "incident_card_closed_action_apps": {
-            "type": "array",
-            "items": {
-              "type": "string",
-              "enum": [
-                "feishu_app",
-                "dingtalk_app",
-                "wecom_app",
-                "slack_app",
-                "teams_app"
-              ]
-            },
-            "description": "传入时整体替换保留自定义操作按钮的应用列表。可选值：`feishu_app`、`dingtalk_app`、`wecom_app`、`slack_app`、`teams_app`；不传该字段则保持不变。"
-          },
-          "incident_card_hidden_fields": {
-            "$ref": "#/components/schemas/IncidentCardHiddenFields",
-            "description": "按 IM 应用类型隐藏的故障卡片字段。"
-          },
-          "slack": {
-            "description": "Slack 机器人消息模板源。省略时保持当前内容；传空字符串表示清空。",
+          "feishu_app_card_v2_table_enabled": {
             "type": [
-              "string",
+              "boolean",
               "null"
-            ]
+            ],
+            "description": "将 `feishu_app` 内容中的 Markdown 表格渲染为飞书卡片原生表格。不传则保持不变。"
           },
-          "slack_app": {
-            "description": "Slack 应用消息模板源。省略时保持当前内容；传空字符串表示清空。",
+          "feishu_app_card_v2_preserve_blank_lines": {
             "type": [
-              "string",
+              "boolean",
               "null"
-            ]
+            ],
+            "description": "设置后决定飞书应用卡片 v2 消息是否保留正文空行；省略时保持当前设置。"
           },
-          "slack_app_war_room_enabled": {
+          "feishu_app_war_room_enabled": {
             "type": [
               "boolean",
               "null"
             ],
-            "description": "设置后决定 Slack 应用卡片是否展示「创建作战室」按钮；省略时保持当前设置。"
+            "description": "设置后决定飞书应用卡片是否展示「创建作战室」按钮；省略时保持当前设置。"
           },
-          "sms": {
-            "description": "短信模板源（Go `text/template` 语法）。省略时保持当前内容；传空字符串表示清空。",
+          "dingtalk_app_war_room_enabled": {
             "type": [
-              "string",
+              "boolean",
               "null"
-            ]
+            ],
+            "description": "设置后决定钉钉应用卡片是否展示「创建作战室」按钮；省略时保持当前设置。"
           },
-          "team_id": {
-            "description": "团队归属。0 表示账户全局共享。省略时保持模板当前的团队归属。",
-            "format": "int64",
+          "slack_app_war_room_enabled": {
             "type": [
-              "integer",
+              "boolean",
               "null"
-            ]
+            ],
+            "description": "设置后决定 Slack 应用卡片是否展示「创建作战室」按钮；省略时保持当前设置。"
           },
-          "teams_app": {
-            "description": "Microsoft Teams 应用消息模板源。省略时保持当前内容；传空字符串表示清空。",
+          "dingtalk_app": {
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "钉钉应用消息模板源。省略时保持当前内容；传空字符串表示清空。"
           },
-          "telegram": {
-            "description": "Telegram 机器人消息模板源。省略时保持当前内容；传空字符串表示清空。",
+          "wecom_app": {
             "type": [
               "string",
               "null"
-            ]
-          },
-          "template_id": {
-            "description": "目标模板 ID，可通过 `POST /template/list` 获取。",
-            "example": "6605a1b2c3d4e5f6a7b8c9d0",
-            "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
-          },
-          "template_name": {
-            "description": "模板名称，长度 1–39 个字符。",
-            "maxLength": 39,
-            "minLength": 1,
-            "type": "string"
+            ],
+            "description": "企业微信应用消息模板源。省略时保持当前内容；传空字符串表示清空。"
           },
-          "voice": {
-            "description": "语音呼叫脚本模板源。省略时保持当前内容；传空字符串表示清空。",
+          "slack_app": {
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "Slack 应用消息模板源。省略时保持当前内容；传空字符串表示清空。"
           },
-          "wecom": {
-            "description": "企业微信群机器人消息模板源。省略时保持当前内容；传空字符串表示清空。",
+          "teams_app": {
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "Microsoft Teams 应用消息模板源。省略时保持当前内容；传空字符串表示清空。"
           },
-          "wecom_app": {
-            "description": "企业微信应用消息模板源。省略时保持当前内容；传空字符串表示清空。",
+          "telegram": {
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "Telegram 机器人消息模板源。省略时保持当前内容；传空字符串表示清空。"
           },
-          "wecom_markdown_v2_enabled": {
+          "slack": {
             "type": [
-              "boolean",
+              "string",
               "null"
             ],
-            "description": "设置后切换企业微信群机器人通知的 `markdown_v2` / 普通 markdown 格式；省略时保持当前设置。"
+            "description": "Slack 机器人消息模板源。省略时保持当前内容；传空字符串表示清空。"
           },
           "zoom": {
-            "description": "Zoom 机器人消息模板源。省略时保持当前内容；传空字符串表示清空。",
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "Zoom 机器人消息模板源。省略时保持当前内容；传空字符串表示清空。"
+          },
+          "incident_card_closed_action_apps": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "enum": [
+                "feishu_app",
+                "dingtalk_app",
+                "wecom_app",
+                "slack_app",
+                "teams_app"
+              ]
+            },
+            "description": "传入时整体替换保留自定义操作按钮的应用列表。可选值：`feishu_app`、`dingtalk_app`、`wecom_app`、`slack_app`、`teams_app`；不传该字段则保持不变。"
+          },
+          "incident_card_hidden_fields": {
+            "$ref": "#/components/schemas/IncidentCardHiddenFields",
+            "description": "按 IM 应用类型配置要隐藏的故障卡片字段。传入时整体替换已存的值；不传则保持不变。"
           }
-        },
-        "required": [
-          "template_id",
-          "template_name"
-        ],
-        "type": "object"
+        }
       },
       "TimeFilter": {
-        "description": "周期性时间窗口。`start`/`end` 采用 24 小时制 `HH:MM`；`repeat` 采用 ISO 风格的星期索引（0=周日 … 6=周六）。",
+        "type": "object",
+        "description": "周期时间窗口。`start`、`end` 为 24 小时制 `HH:MM`，`start` 不得晚于 `end`（窗口不能跨零点）；`00:00`–`00:00` 表示全天。",
         "properties": {
-          "cal_id": {
-            "description": "可选日历 ID，将窗口限制为日历中的匹配日期。",
-            "type": "string"
+          "start": {
+            "type": "string",
+            "description": "窗口开始时间，`HH:MM`，包含该分钟。"
           },
           "end": {
-            "description": "窗口结束时间（`HH:MM`）。",
-            "type": "string"
-          },
-          "is_off": {
-            "description": "为 true 时匹配日历中标记为休息日的日期。",
-            "type": "boolean"
+            "type": "string",
+            "description": "窗口结束时间，`HH:MM`，包含该分钟（`23:59` 持续到午夜）。"
           },
           "repeat": {
-            "description": "窗口每周生效的日期，空表示每天。",
+            "type": "array",
             "items": {
-              "maximum": 6,
+              "type": "integer",
               "minimum": 0,
-              "type": "integer"
+              "maximum": 6
             },
-            "type": "array"
+            "description": "窗口生效的星期：`0` 为周日 … `6` 为周六。为空表示每天。"
           },
-          "start": {
-            "description": "窗口开始时间（`HH:MM`）。",
-            "type": "string"
+          "cal_id": {
+            "type": "string",
+            "description": "服务日历 ID，来自 `POST /calendar/list`（如 `cal.xxxx`）。设置后，窗口只在该日历的工作日或休息日生效，由 `is_off` 决定。"
+          },
+          "is_off": {
+            "type": "boolean",
+            "description": "与 `cal_id` 搭配使用：`true` 仅在日历的休息日生效，`false` 仅在工作日生效。"
           }
-        },
-        "type": "object"
+        }
       },
       "TryLinkPersonRequest": {
         "description": "尝试自动关联 IM 账号的参数。",
@@ -27000,21 +28021,31 @@
         "type": "object"
       },
       "TryLinkPersonResponse": {
-        "description": "本次调用新关联的人员。如果没有成员可关联，响应中的 `new_linked_person_ids` 可能为空数组，或整个 `data` 字段被省略。",
+        "type": "object",
+        "description": "本次关联尝试的结果。",
+        "required": [
+          "new_linked_person_ids",
+          "unmatched_count",
+          "no_contact_count"
+        ],
         "properties": {
           "new_linked_person_ids": {
-            "description": "本次调用中新关联成功的人员 ID。",
+            "type": "array",
             "items": {
-              "format": "int64",
-              "type": "integer"
+              "type": "integer",
+              "format": "int64"
             },
-            "type": "array"
+            "description": "本次调用中新关联到该 IM 应用的成员 ID，没有新关联时为空数组。"
+          },
+          "unmatched_count": {
+            "type": "integer",
+            "description": "有邮箱或手机号、已查询但未新关联的成员数：IM 平台中未找到、该 IM 账号已关联其他成员，或查询失败。"
+          },
+          "no_contact_count": {
+            "type": "integer",
+            "description": "因既无邮箱也无手机号而被跳过的未关联成员数。"
           }
-        },
-        "required": [
-          "new_linked_person_ids"
-        ],
-        "type": "object"
+        }
       },
       "UnackIncidentRequest": {
         "description": "取消认领故障的参数。",
@@ -27036,302 +28067,327 @@
         "type": "object"
       },
       "UnsubscribeRuleItem": {
+        "type": "object",
         "description": "排除规则记录。",
+        "required": [
+          "account_id",
+          "channel_id",
+          "rule_name",
+          "description",
+          "filters",
+          "status",
+          "rule_id",
+          "updated_by",
+          "created_at",
+          "updated_at"
+        ],
         "properties": {
           "account_id": {
-            "description": "规则所属账户 ID。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "规则所属账户 ID。"
           },
           "channel_id": {
-            "description": "规则所属协作空间 ID。",
-            "format": "int64",
-            "type": "integer"
-          },
-          "created_at": {
-            "description": "创建时间，Unix 时间戳（秒）。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "规则所属协作空间 ID。"
           },
-          "deleted_at": {
-            "description": "删除时间，Unix 秒时间戳。仅在规则被软删除时返回；已删除的规则不会出现在列表响应中。",
-            "format": "int64",
-            "type": "integer"
+          "rule_name": {
+            "type": "string",
+            "description": "排除规则名称，1–39 个字符。"
           },
           "description": {
-            "description": "规则描述。",
-            "type": "string"
+            "type": "string",
+            "description": "规则描述。"
           },
           "filters": {
             "$ref": "#/components/schemas/FilterGroup",
-            "description": "告警事件匹配条件（OR-of-AND 结构）；命中的事件被完全丢弃。为空时规则不匹配任何事件。"
-          },
-          "rule_id": {
-            "description": "规则 ID（MongoDB ObjectID）。",
-            "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
-          },
-          "rule_name": {
-            "description": "规则名称。",
-            "type": "string"
+            "description": "告警事件匹配条件（AND 组之间为 OR），命中的事件被直接丢弃。为空表示不匹配任何事件；若最近一次更新未传 `filters`，此处为 `null`。"
           },
           "status": {
-            "description": "规则状态：`enabled` 启用，`disabled` 停用；已删除的规则不会出现在列表中。",
+            "type": "string",
             "enum": [
               "enabled",
               "disabled"
             ],
-            "type": "string"
+            "description": "规则状态：`enabled` 启用，`disabled` 停用；已删除的规则不会出现在列表中。"
+          },
+          "rule_id": {
+            "type": "string",
+            "pattern": "^[0-9a-fA-F]{24}$",
+            "description": "规则 ID（MongoDB ObjectID）。"
+          },
+          "updated_by": {
+            "type": "integer",
+            "format": "int64",
+            "description": "最近一次更新该规则的用户 ID。"
+          },
+          "created_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "创建时间，Unix 时间戳（秒）。"
           },
           "updated_at": {
-            "description": "最近更新时间，Unix 时间戳（秒）。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "最近更新时间，Unix 时间戳（秒）。"
           },
-          "updated_by": {
-            "description": "最近一次更新该规则的用户 ID。",
+          "deleted_at": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "删除时间，Unix 秒时间戳。仅在规则被软删除时返回；已删除的规则不会出现在列表响应中。"
           }
-        },
-        "required": [
-          "account_id",
-          "channel_id",
-          "rule_name",
-          "description",
-          "filters",
-          "status",
-          "rule_id",
-          "updated_by",
-          "created_at",
-          "updated_at"
-        ],
-        "type": "object"
+        }
       },
       "UpdateChannelRequest": {
+        "type": "object",
+        "required": [
+          "channel_id"
+        ],
         "description": "更新协作空间所需参数，仅传入的字段会被更新。",
         "properties": {
-          "auto_resolve_mode": {
-            "description": "自动恢复计时模式：`trigger` 在故障触发时启动计时，`update` 在每次告警更新时重新计时。仅在请求同时携带 `auto_resolve_timeout` 时生效。",
-            "enum": [
-              "trigger",
-              "update"
-            ],
-            "type": "string"
-          },
-          "auto_resolve_timeout": {
-            "description": "自动恢复超时，单位秒。0 表示不自动恢复，最长 30 天。",
+          "channel_id": {
+            "type": "integer",
             "format": "int64",
-            "maximum": 2592000,
-            "minimum": 0,
+            "description": "要更新的协作空间 ID，可通过 `POST /channel/list` 获取。"
+          },
+          "team_id": {
             "type": [
               "integer",
               "null"
-            ]
-          },
-          "channel_id": {
-            "description": "要更新的协作空间 ID，可通过 `POST /channel/list` 获取。",
+            ],
             "format": "int64",
-            "type": "integer"
+            "description": "新的所属团队 ID，可通过 `POST /team/list` 获取，必须存在。不传或传 `null` 保持原值。"
+          },
+          "managing_team_ids": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "int64"
+            },
+            "maxItems": 3,
+            "description": "替换可管理该协作空间的其他团队，最多 3 个，每个 ID 都必须存在。传 `[]` 清空；不传保持原值。"
           },
           "channel_name": {
-            "description": "新的协作空间名称，1 到 59 个字符。",
-            "maxLength": 59,
-            "minLength": 1,
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "minLength": 1,
+            "maxLength": 59,
+            "description": "新的协作空间名称，1–59 个字符，账户内唯一。不传或传 `null` 保持原值。"
           },
           "description": {
-            "description": "新的描述信息，最多 500 个字符。",
-            "maxLength": 500,
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "maxLength": 500,
+            "description": "新的描述信息，最多 500 个字符。"
           },
-          "disable_auto_close": {
-            "description": "禁用故障自动关闭。",
+          "auto_resolve_timeout": {
             "type": [
-              "boolean",
+              "integer",
               "null"
-            ]
+            ],
+            "format": "int64",
+            "minimum": 0,
+            "maximum": 2592000,
+            "description": "自动恢复超时，单位秒。0 表示不自动恢复，最长 30 天。"
           },
-          "disable_outlier_detection": {
-            "description": "禁用新奇故障检测。",
+          "auto_resolve_mode": {
+            "type": "string",
+            "enum": [
+              "trigger",
+              "update"
+            ],
+            "description": "自动恢复的计时方式：`trigger` 在故障触发时开始计时，只计一次；`update` 每当有新告警并入时重新计时。只有与 `auto_resolve_timeout` 一起传入才生效；只传 `auto_resolve_timeout` 时模式重置为 `trigger`。"
+          },
+          "is_private": {
             "type": [
               "boolean",
               "null"
-            ]
+            ],
+            "description": "为 true 时仅管理团队可见。"
           },
-          "event_group": {
-            "$ref": "#/components/schemas/EventGroup",
-            "description": "告警事件合并配置。仅在传入时更新。"
+          "group": {
+            "$ref": "#/components/schemas/Group",
+            "description": "告警聚合配置；传入时整体替换原配置。"
           },
           "flapping": {
             "$ref": "#/components/schemas/Flapping",
-            "description": "抖动检测配置。"
-          },
-          "group": {
-            "$ref": "#/components/schemas/Group",
-            "description": "告警聚合配置。"
+            "description": "抖动检测配置；传入时整体替换原配置。"
           },
-          "is_external_report_enabled": {
-            "description": "允许外部上报人向该协作空间上报故障。",
+          "disable_outlier_detection": {
             "type": [
               "boolean",
               "null"
-            ]
+            ],
+            "description": "禁用新奇故障检测。"
           },
-          "is_private": {
-            "description": "为 true 时仅管理团队可见。",
+          "disable_auto_close": {
             "type": [
               "boolean",
               "null"
-            ]
-          },
-          "managing_team_ids": {
-            "description": "可管理该协作空间的其他团队 ID，最多 3 个。",
-            "items": {
-              "format": "int64",
-              "type": "integer"
-            },
-            "maxItems": 3,
-            "type": "array"
+            ],
+            "description": "禁用故障自动关闭。"
           },
-          "team_id": {
-            "description": "新的所属团队 ID，可通过 `POST /team/list` 获取。",
-            "format": "int64",
+          "is_external_report_enabled": {
             "type": [
-              "integer",
+              "boolean",
               "null"
-            ]
+            ],
+            "description": "`true` 开启外部上报并生成新令牌，在响应中返回（旧令牌随即失效）；`false` 关闭外部上报并清空令牌。"
+          },
+          "event_group": {
+            "$ref": "#/components/schemas/EventGroup",
+            "description": "告警事件合并配置；传入时整体替换原配置。"
           }
-        },
-        "required": [
-          "channel_id"
-        ],
-        "type": "object"
+        }
       },
       "UpdateChannelResponse": {
-        "description": "更新协作空间的响应。仅在请求中将 `is_external_report_enabled` 设为 `true` 时返回有效字段，否则所有字段为空。",
+        "type": "object",
+        "description": "仅当请求中 `is_external_report_enabled` 为 `true` 时包含 `external_report_token`，否则 `data` 为空对象。",
         "properties": {
           "external_report_token": {
-            "description": "新生成的外部上报令牌。仅在请求中将 `is_external_report_enabled` 设为 `true` 时返回。调用方应保存此值，之后无法再次获取。",
-            "type": "string"
+            "type": "string",
+            "description": "新生成的外部上报令牌，旧令牌随即失效。之后可通过 `POST /channel/info` 返回的 `external_report_token` 再次读取。"
           }
-        },
-        "type": "object"
+        }
       },
       "UpdateDropRuleRequest": {
+        "type": "object",
         "description": "更新排除规则所需参数。",
+        "required": [
+          "channel_id",
+          "rule_id",
+          "rule_name"
+        ],
         "properties": {
           "channel_id": {
-            "description": "所属协作空间 ID，可通过 `POST /channel/list` 获取。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
-          },
-          "description": {
-            "description": "规则描述，最多 500 个字符。",
-            "maxLength": 500,
-            "type": "string"
-          },
-          "filters": {
-            "$ref": "#/components/schemas/FilterGroup",
-            "description": "告警事件匹配条件（OR-of-AND 结构）；命中的事件被完全丢弃。为空时规则不匹配任何事件。"
+            "description": "所属协作空间 ID，可通过 `POST /channel/list` 获取。"
           },
           "rule_id": {
-            "description": "排除规则 ID（MongoDB ObjectID）。",
+            "type": "string",
             "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
+            "description": "排除规则 ID（MongoDB ObjectID）。"
           },
           "rule_name": {
-            "description": "规则名称，1 到 39 个字符。",
-            "maxLength": 39,
+            "type": "string",
             "minLength": 1,
-            "type": "string"
+            "maxLength": 39,
+            "description": "规则名称，1 到 39 个字符。"
+          },
+          "description": {
+            "type": "string",
+            "maxLength": 500,
+            "description": "规则描述，最多 500 个字符。不传会清空原描述。"
+          },
+          "filters": {
+            "$ref": "#/components/schemas/FilterGroup",
+            "description": "告警事件匹配条件（AND 组之间为 OR），命中的事件被直接丢弃。可用字段：`title`、`description`、`severity`（别名 `alert_severity`、`event_severity`）、`status`、`alert_key`、`title_rule`、`integration_id`（别名 `data_source_id`），或任意 `labels.<name>`。会整体替换原条件；不传则清空条件，规则不再匹配任何事件。"
           }
-        },
+        }
+      },
+      "UpdateEscalationRuleRequest": {
+        "type": "object",
+        "description": "更新分派策略所需参数。",
         "required": [
           "channel_id",
           "rule_id",
-          "rule_name"
+          "template_id",
+          "rule_name",
+          "layers"
         ],
-        "type": "object"
-      },
-      "UpdateEscalationRuleRequest": {
-        "description": "更新分派策略所需参数。",
         "properties": {
-          "aggr_window": {
-            "description": "延迟窗口，单位秒，0 表示不延迟。",
-            "type": "integer"
-          },
           "channel_id": {
-            "description": "所属协作空间 ID，可通过 `POST /channel/list` 获取。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
-          },
-          "description": {
-            "description": "策略描述，最多 500 个字符。",
-            "maxLength": 500,
-            "type": "string"
-          },
-          "filters": {
-            "$ref": "#/components/schemas/FilterGroup",
-            "description": "故障级匹配条件（OR-of-AND 结构）：策略匹配的是告警聚合而成的故障，而不是告警本身。不传或为空时对空间内所有故障生效。"
+            "description": "所属协作空间 ID，可通过 `POST /channel/list` 获取。"
           },
-          "layers": {
-            "description": "分派环节列表，至少包含一个环节。",
-            "items": {
-              "$ref": "#/components/schemas/EscalateLayer"
-            },
-            "type": "array"
+          "rule_id": {
+            "type": "string",
+            "pattern": "^[0-9a-fA-F]{24}$",
+            "description": "分派策略 ID（MongoDB ObjectID）。"
           },
           "priority": {
-            "description": "匹配优先级，数值越小越优先。",
             "type": [
               "integer",
               "null"
-            ]
+            ],
+            "description": "匹配顺序，数值越小越先匹配。不传或传 `null` 时保持原值。"
           },
-          "rule_id": {
-            "description": "分派策略 ID（MongoDB ObjectID）。",
+          "aggr_window": {
+            "type": "integer",
+            "description": "新分派故障首次通知前的延迟（秒），`0` 表示立即通知。不传会重置为 `0`。"
+          },
+          "template_id": {
+            "type": "string",
             "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
+            "description": "通知模板 ID（24 位十六进制），可通过 `POST /template/list` 获取，必须存在。"
           },
           "rule_name": {
-            "description": "策略名称，1 到 39 个字符。",
-            "maxLength": 39,
+            "type": "string",
             "minLength": 1,
-            "type": "string"
+            "maxLength": 39,
+            "description": "策略名称，1 到 39 个字符。"
           },
-          "template_id": {
-            "description": "通知模板 ID（MongoDB ObjectID）。",
-            "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
+          "description": {
+            "type": "string",
+            "maxLength": 500,
+            "description": "策略描述，最多 500 个字符。不传会清空原描述。"
+          },
+          "layers": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/EscalateLayer"
+            },
+            "description": "分派环节列表，至少包含一个环节。"
           },
           "time_filters": {
-            "description": "可选的周期性生效时间窗口。",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/TimeFilter"
             },
-            "type": "array"
+            "description": "策略可参与匹配的周期时间窗口。会整体替换原窗口；不传或为空表示任何时间。"
+          },
+          "filters": {
+            "$ref": "#/components/schemas/FilterGroup",
+            "description": "故障匹配条件（AND 组之间为 OR），匹配的是告警所属的故障而不是告警本身。可用字段：`title`、`description`、`severity`（别名 `incident_severity`、`alert_severity`）、`status`（别名 `incident_status`、`alert_status`）、`dedup_key`、`integration_id`（别名 `data_source_id`），或任意 `labels.<name>`。会整体替换原条件；不传或为空时匹配协作空间内的所有故障。"
           }
-        },
-        "required": [
-          "channel_id",
-          "rule_id",
-          "template_id",
-          "rule_name",
-          "layers"
-        ],
-        "type": "object"
+        }
       },
       "UpdateFieldRequest": {
+        "type": "object",
+        "required": [
+          "field_id"
+        ],
         "properties": {
+          "field_id": {
+            "type": "string",
+            "pattern": "^[a-f0-9]{24}$",
+            "description": "字段 ID，24 位十六进制 ObjectID。"
+          },
+          "display_name": {
+            "type": "string",
+            "maxLength": 39,
+            "description": "新的显示名称（最长 39 字符），须在未删除字段中保持唯一。每次都会写入。"
+          },
+          "description": {
+            "type": "string",
+            "description": "新描述。每次都会写入：不传即清空描述。"
+          },
+          "options": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "替换后的选项列表，规则与创建时相同。注意：更新接口总是用提交的值覆盖 `display_name`、`description`、`options` 和 `default_value`，因此 `single_select`/`multi_select` 字段每次更新都必须传非空 `options`。"
+          },
           "default_value": {
-            "description": "替换后的默认值，类型须与字段当前 `field_type` 匹配。",
+            "description": "新的默认值，类型须与字段的 `field_type` 一致。每次都会写入：不传即清空默认值。",
             "oneOf": [
               {
                 "type": "boolean"
@@ -27340,184 +28396,160 @@
                 "type": "string"
               },
               {
+                "type": "array",
                 "items": {
                   "type": "string"
-                },
-                "type": "array"
+                }
               },
               {
                 "type": "null"
               }
             ]
-          },
-          "description": {
-            "description": "新描述。",
-            "type": "string"
-          },
-          "display_name": {
-            "description": "新的展示名，账号内仍须唯一。",
-            "maxLength": 39,
-            "type": "string"
-          },
-          "field_id": {
-            "description": "字段 ID，24 位十六进制 ObjectID。",
-            "pattern": "^[a-f0-9]{24}$",
-            "type": "string"
-          },
-          "options": {
-            "description": "替换后的选项列表，规则与创建时相同。注意：更新接口总是用提交的值覆盖 `display_name`、`description`、`options` 和 `default_value`，因此 `single_select`/`multi_select` 字段每次更新都必须传非空 `options`。",
-            "items": {
-              "type": "string"
-            },
-            "type": "array"
           }
-        },
-        "required": [
-          "field_id"
-        ],
-        "type": "object"
+        }
       },
       "UpdateIncidentCommentTypeRequest": {
+        "type": "object",
         "description": "更新评论类型的参数。部分更新：`name` 和 `color` 至少提供一个。",
+        "required": [
+          "comment_type_id"
+        ],
         "properties": {
-          "color": {
-            "description": "新的标签颜色，#RRGGBB 格式十六进制值，统一转为大写。",
-            "pattern": "^#[0-9A-Fa-f]{6}$",
-            "type": "string"
-          },
           "comment_type_id": {
-            "description": "要更新的评论类型 ID（24 位十六进制 ObjectID）。",
+            "type": "string",
             "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
+            "description": "要更新的评论类型 ID（24 位十六进制 ObjectID）。"
           },
           "name": {
-            "description": "新的展示名称。存储前去除首尾空白；账户内唯一（不区分大小写）。最多 40 个字符。",
+            "type": "string",
             "maxLength": 40,
-            "type": "string"
+            "description": "新的展示名称。存储前去除首尾空白；账户内唯一（不区分大小写）。最多 40 个字符。不得包含控制字符或文字方向控制字符。"
+          },
+          "color": {
+            "type": "string",
+            "pattern": "^#[0-9A-Fa-f]{6}$",
+            "description": "新的标签颜色，#RRGGBB 格式十六进制值，统一转为大写。"
           }
-        },
-        "required": [
-          "comment_type_id"
-        ],
-        "type": "object"
+        }
       },
       "UpdateIncidentFieldsRequest": {
-        "description": "更新故障可编辑字段的参数。至少需要提供一个字段；handler 只会更新显式传入的字段。",
+        "type": "object",
+        "description": "要更新的故障字段。除 `incident_id` 外至少要有一个非空字段；未传或为空的字段保持原值。",
+        "required": [
+          "incident_id"
+        ],
         "properties": {
-          "description": {
-            "description": "新描述。",
-            "maxLength": 6144,
-            "minLength": 3,
-            "type": "string"
-          },
-          "impact": {
-            "description": "新影响描述。",
-            "maxLength": 6144,
-            "minLength": 3,
-            "type": "string"
-          },
           "incident_id": {
-            "description": "故障 ID（MongoDB ObjectID）。",
+            "type": "string",
             "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
+            "description": "故障 ID（MongoDB ObjectID）。"
           },
-          "incident_severity": {
-            "description": "新严重程度：`Info` 提示、`Warning` 警告、`Critical` 严重。",
-            "enum": [
-              "Info",
-              "Warning",
-              "Critical"
-            ],
-            "type": "string"
+          "title": {
+            "type": "string",
+            "minLength": 3,
+            "maxLength": 200,
+            "description": "新标题。"
           },
-          "resolution": {
-            "description": "新解决方案说明。",
+          "description": {
+            "type": "string",
+            "minLength": 3,
             "maxLength": 6144,
+            "description": "新描述。"
+          },
+          "impact": {
+            "type": "string",
             "minLength": 3,
-            "type": "string"
+            "maxLength": 6144,
+            "description": "新影响描述。"
           },
           "root_cause": {
-            "description": "新根因分析。",
-            "maxLength": 6144,
+            "type": "string",
             "minLength": 3,
-            "type": "string"
+            "maxLength": 6144,
+            "description": "新根因分析。"
           },
-          "title": {
-            "description": "新标题。",
-            "maxLength": 200,
+          "resolution": {
+            "type": "string",
             "minLength": 3,
-            "type": "string"
+            "maxLength": 6144,
+            "description": "新解决方案说明。"
+          },
+          "incident_severity": {
+            "type": "string",
+            "enum": [
+              "Info",
+              "Warning",
+              "Critical"
+            ],
+            "description": "新严重程度：`Info` 提示、`Warning` 警告、`Critical` 严重。"
           }
-        },
-        "required": [
-          "incident_id"
-        ],
-        "type": "object"
+        }
       },
       "UpdateInhibitRuleRequest": {
+        "type": "object",
         "description": "更新抑制策略所需参数。",
+        "required": [
+          "channel_id",
+          "rule_id",
+          "rule_name",
+          "equals"
+        ],
         "properties": {
           "channel_id": {
-            "description": "所属协作空间 ID，可通过 `POST /channel/list` 获取。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "所属协作空间 ID，可通过 `POST /channel/list` 获取。"
+          },
+          "rule_id": {
+            "type": "string",
+            "pattern": "^[0-9a-fA-F]{24}$",
+            "description": "抑制策略 ID（MongoDB ObjectID）。"
+          },
+          "rule_name": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 39,
+            "description": "策略名称，1 到 39 个字符。"
           },
           "description": {
-            "description": "策略描述，最多 500 个字符。",
+            "type": "string",
             "maxLength": 500,
-            "type": "string"
+            "description": "策略描述，最多 500 个字符。不传会清空原描述。"
           },
           "equals": {
-            "description": "源（抑制方）告警与目标（被抑制）告警之间必须取值相等的字段键，例如 `data_source_id` 或 `labels.cluster`。",
+            "type": "array",
             "items": {
               "type": "string"
             },
-            "type": "array"
-          },
-          "is_directly_discard": {
-            "description": "为 true 时，命中的告警事件被完全丢弃；为 false 时，告警仍会被记录，但标记为被本策略静默。",
-            "type": "boolean"
-          },
-          "rule_id": {
-            "description": "抑制策略 ID（MongoDB ObjectID）。",
-            "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
-          },
-          "rule_name": {
-            "description": "策略名称，1 到 39 个字符。",
-            "maxLength": 39,
-            "minLength": 1,
-            "type": "string"
+            "description": "源告警与新事件取值必须相同的字段。只有 `title`、`severity` 和 `labels.<name>` 有效；其他字段（例如 `data_source_id`）虽能保存，但会导致策略永远不生效。必须传入；空数组同样使策略不生效。"
           },
           "source_filters": {
             "$ref": "#/components/schemas/FilterGroup",
-            "description": "源告警需要满足的条件，针对已存的活跃告警求值。支持的键：`status`、`incident_status`、`alert_status`、`severity`、`incident_severity`、`alert_severity`、`title`、`description` 或任意 `labels.<name>`。为空时策略不生效。"
+            "description": "源告警（起抑制作用的告警）需满足的条件，匹配对象是协作空间内已存储的活跃告警。可用字段：`title`、`description`、`severity`（别名 `incident_severity`、`alert_severity`）、`status`（别名 `incident_status`、`alert_status`），或任意 `labels.<name>`。为空时策略不生效。不传会清空原条件。"
           },
           "target_filters": {
             "$ref": "#/components/schemas/FilterGroup",
-            "description": "目标（被抑制）告警事件需要满足的条件；为空表示所有事件都是抑制目标。"
+            "description": "新进入的告警事件需满足的条件，满足才会被抑制；为空表示所有新事件都是抑制对象。可用字段：`title`、`description`、`severity`（别名 `alert_severity`、`event_severity`）、`status`、`alert_key`、`title_rule`、`integration_id`（别名 `data_source_id`），或任意 `labels.<name>`。不传会清空原条件。"
+          },
+          "is_directly_discard": {
+            "type": "boolean",
+            "description": "为 true 时，命中的告警事件被直接丢弃；为 false 时，告警仍会记录，但标记为被该策略抑制。不传会设为 `false`。"
           }
-        },
-        "required": [
-          "channel_id",
-          "rule_id",
-          "rule_name",
-          "equals"
-        ],
-        "type": "object"
+        }
       },
       "UpdateRemoteConfigRequest": {
         "description": "发布一个全新的远程配置版本。客户端需提交完整对象而非增量补丁：规则顺序承载语义。",
         "properties": {
           "application_id": {
-            "description": "RUM 应用 ID。",
+            "description": "RUM 应用 ID，可通过 `POST /rum/application/list` 获取。",
             "type": "string"
           },
           "config": {
-            "$ref": "#/components/schemas/RemoteConfig"
+            "$ref": "#/components/schemas/RemoteConfig",
+            "description": "要发布的完整配置。"
           },
           "reason": {
-            "description": "操作者留下的发布说明，原样保存。",
+            "description": "可选的自由文本备注（非枚举），说明发布该版本的原因，最多 255 个字符；按原样保存，并在 `POST /rum/application/remote-config/history/list` 的 `reason` 中返回。",
             "maxLength": 255,
             "type": "string"
           }
@@ -27532,474 +28564,493 @@
         "description": "本次发布分配到的版本号。",
         "properties": {
           "version": {
-            "description": "新发布的版本号。",
+            "description": "为本次发布分配的版本号（此前最大版本号 + 1）。",
             "type": "integer"
           }
         },
         "type": "object"
       },
       "UpdateSilenceRuleRequest": {
+        "type": "object",
         "description": "更新静默策略所需参数。`time_filter` 与 `time_filters` 必须且只能传一个，`filters` 不能为空。",
+        "required": [
+          "channel_id",
+          "rule_id",
+          "rule_name"
+        ],
         "properties": {
           "channel_id": {
-            "description": "所属协作空间 ID，可通过 `POST /channel/list` 获取。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
-          },
-          "description": {
-            "description": "策略描述，最多 500 个字符。",
-            "maxLength": 500,
-            "type": "string"
-          },
-          "filters": {
-            "$ref": "#/components/schemas/FilterGroup",
-            "description": "要静默的告警匹配条件，必填且不能为空。"
-          },
-          "is_auto_delete": {
-            "description": "为 true 时，静默规则在时间窗结束后会被自动删除；默认为 false。",
-            "type": "boolean"
-          },
-          "is_directly_discard": {
-            "description": "为 true 时，命中的告警事件被完全丢弃；为 false 时，告警仍会被记录，但标记为被本策略静默。",
-            "type": "boolean"
+            "description": "所属协作空间 ID，可通过 `POST /channel/list` 获取。"
           },
           "rule_id": {
-            "description": "静默策略 ID（MongoDB ObjectID）。",
+            "type": "string",
             "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
+            "description": "静默策略 ID（MongoDB ObjectID）。"
           },
           "rule_name": {
-            "description": "策略名称，1 到 39 个字符。",
-            "maxLength": 39,
+            "type": "string",
             "minLength": 1,
-            "type": "string"
+            "maxLength": 39,
+            "description": "策略名称，1 到 39 个字符。"
           },
-          "time_filter": {
-            "$ref": "#/components/schemas/OnceTimeFilter",
-            "description": "一次性静默时间窗口。与 `time_filters` 互斥，两者必须配置其一。"
+          "description": {
+            "type": "string",
+            "maxLength": 500,
+            "description": "策略描述，最多 500 个字符。不传会清空原描述。"
           },
           "time_filters": {
-            "description": "周期性时间窗口，与 `time_filter` 互斥。",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/TimeFilter"
             },
-            "type": "array"
+            "description": "周期性时间窗口，与 `time_filter` 互斥。"
+          },
+          "time_filter": {
+            "$ref": "#/components/schemas/OnceTimeFilter",
+            "description": "一次性静默时间窗口。与 `time_filters` 互斥，两者必须配置其一。"
+          },
+          "filters": {
+            "$ref": "#/components/schemas/FilterGroup",
+            "description": "告警事件匹配条件（AND 组之间为 OR），时间窗口内命中的事件被静默。必填，且至少包含一个条件。可用字段：`title`、`description`、`severity`（别名 `alert_severity`、`event_severity`）、`status`、`alert_key`、`title_rule`、`integration_id`（别名 `data_source_id`），或任意 `labels.<name>`。"
+          },
+          "is_directly_discard": {
+            "type": "boolean",
+            "description": "为 true 时，命中的告警事件被直接丢弃；为 false 时，告警仍会记录，但标记为被该策略静默。不传会设为 `false`。"
+          },
+          "is_auto_delete": {
+            "type": "boolean",
+            "description": "为 true 时，使用一次性 `time_filter` 的策略在 `end_time`（或最近一次更新时间，取较晚者）约 24 小时后被永久移除。通过 `from_incident_id` 创建的策略同样按此方式清理。使用周期 `time_filters` 的策略不会被自动移除。不传会设为 `false`。"
           }
-        },
-        "required": [
-          "channel_id",
-          "rule_id",
-          "rule_name"
-        ],
-        "type": "object"
+        }
       },
       "UpdateStatusPageChangeRequest": {
+        "type": "object",
         "description": "更新状态页事件可编辑字段所需的参数。",
+        "required": [
+          "page_id",
+          "change_id"
+        ],
         "properties": {
-          "change_id": {
-            "description": "目标事件 ID，可通过 `GET /status-page/change/list` 获取。",
-            "format": "int64",
-            "type": "integer"
-          },
-          "linked_changes": {
-            "description": "关联的事件 ID 列表。传入完整替换列表。",
-            "items": {
-              "type": "string"
-            },
-            "type": "array"
-          },
           "page_id": {
-            "description": "状态页 ID，可通过 `GET /status-page/list` 获取。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "状态页 ID，可通过 `GET /status-page/list` 获取。"
           },
-          "responders": {
-            "description": "事件负责成员 ID 列表。传入完整替换列表。",
-            "items": {
-              "format": "int64",
-              "type": "integer"
-            },
-            "type": "array"
+          "change_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "目标事件 ID，可通过 `GET /status-page/change/list` 获取。"
           },
           "title": {
-            "description": "新的事件标题，最多 255 个字符。留空表示保持原值。",
-            "maxLength": 255,
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "maxLength": 255,
+            "description": "新的事件标题，最多 255 个字符。留空表示保持原值。"
+          },
+          "responders": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "int64"
+            },
+            "description": "该事件的负责人成员 ID，整体替换原列表。省略或传空数组时保留原列表。"
+          },
+          "linked_changes": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "关联事件 ID，整体替换原列表。省略或传空数组时保留原列表。"
           }
-        },
-        "required": [
-          "page_id",
-          "change_id"
-        ],
-        "type": "object"
+        }
       },
       "UpdateStatusPageChangeTimelineRequest": {
+        "type": "object",
         "description": "更新状态页事件已有时间线条目所需的参数。`at_seconds` 与 `description` 至少提供一个；未提供的字段保持原值。",
+        "required": [
+          "page_id",
+          "change_id",
+          "update_id"
+        ],
         "properties": {
-          "at_seconds": {
-            "description": "新的更新时间戳（Unix 秒）。",
+          "page_id": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "状态页 ID，可通过 `GET /status-page/list` 获取。"
           },
           "change_id": {
-            "description": "所属事件 ID，可通过 `GET /status-page/change/list` 获取。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "所属事件 ID，可通过 `GET /status-page/change/list` 获取。"
           },
-          "description": {
-            "description": "新的更新说明（Markdown）。",
-            "type": "string"
+          "update_id": {
+            "type": "string",
+            "description": "目标时间线更新 ID，可通过 `GET /status-page/change/info` 获取。"
           },
-          "page_id": {
-            "description": "状态页 ID，可通过 `GET /status-page/list` 获取。",
+          "at_seconds": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "新的更新时间，Unix 时间戳（秒），不能早于前一条更新、也不能晚于后一条更新。省略或传 0 时保持不变。"
           },
-          "update_id": {
-            "description": "目标时间线更新 ID，可通过 `GET /status-page/change/info` 获取。",
-            "type": "string"
+          "description": {
+            "type": "string",
+            "description": "新的更新描述（Markdown）。省略或传空字符串时保持不变；修改最新一条更新时会同步更新事件描述。"
           }
-        },
-        "required": [
-          "page_id",
-          "change_id",
-          "update_id"
-        ],
-        "type": "object"
+        }
       },
       "UpdateStatusPageRequest": {
+        "type": "object",
         "description": "更新已有状态页所需的参数。除 `page_id` 外均为可选字段；省略某字段或传 null 表示保持其原值。",
+        "required": [
+          "page_id"
+        ],
         "properties": {
-          "contact_info": {
-            "description": "联系信息，例如 mailto 或网站 URL。省略或传 null 表示保持原值。",
+          "page_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "状态页 ID，可通过 `GET /status-page/list` 获取。"
+          },
+          "name": {
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "状态页展示名称。省略或传 null 表示保持原值。",
+            "maxLength": 255
           },
-          "custom_domain": {
-            "description": "公开状态页使用的自定义域名。省略或传 null 表示保持原值。",
-            "maxLength": 255,
+          "url_name": {
             "type": [
               "string",
               "null"
-            ]
-          },
-          "custom_links": {
-            "description": "状态页展示的自定义导航链接。省略或传空数组表示保持当前链接。",
-            "items": {
-              "additionalProperties": {
-                "type": "string"
-              },
-              "type": "object"
-            },
-            "type": "array"
+            ],
+            "description": "URL 安全 slug；会规范化为小写，非字母数字字符替换为连字符，且在账户内同类型状态页中必须唯一。省略或传 null 时保持不变。",
+            "maxLength": 255
           },
-          "dark_logo": {
-            "description": "状态页暗色模式 Logo 图片。省略或传 null 表示保持原值。",
+          "custom_domain": {
             "type": [
               "string",
               "null"
-            ]
-          },
-          "date_view": {
-            "description": "事件日期展示方式。省略或传 null 表示保持原值。`calendar` 为日历视图；`list` 为列表视图。",
-            "enum": [
-              "calendar",
-              "list"
             ],
+            "description": "公开状态页的自定义域名，不能被其他状态页占用；内部页不可设置。省略或传 null 时保持不变；传空字符串会移除域名。",
+            "maxLength": 255
+          },
+          "page_title": {
             "type": [
               "string",
               "null"
-            ]
-          },
-          "display_uptime_mode": {
-            "description": "可用率展示方式。省略或传 null 表示保持原值。`chart_and_percentage` 同时展示图表与百分比；`chart` 仅展示图表；`none` 不展示。",
-            "enum": [
-              "chart_and_percentage",
-              "chart",
-              "none"
             ],
+            "description": "为兼容保留的字段，服务端不会存储，传入无效果。"
+          },
+          "logo": {
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "状态页 Logo 图片。省略或传 null 表示保持原值。"
           },
-          "favicon": {
-            "description": "状态页的网站图标。省略或传 null 表示保持原值。",
+          "dark_logo": {
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "状态页暗色模式 Logo 图片。省略或传 null 表示保持原值。"
           },
-          "logo": {
-            "description": "状态页 Logo 图片。省略或传 null 表示保持原值。",
+          "logo_url": {
             "type": [
               "string",
               "null"
-            ]
-          },
-          "logo_url": {
+            ],
             "description": "点击 Logo 时跳转的 URL。省略或传 null 表示保持原值。",
-            "maxLength": 255,
+            "maxLength": 255
+          },
+          "favicon": {
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "状态页的网站图标。省略或传 null 表示保持原值。"
           },
-          "name": {
-            "description": "状态页展示名称。省略或传 null 表示保持原值。",
-            "maxLength": 255,
+          "page_header": {
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "状态页页头内容。省略或传 null 表示保持原值。"
           },
           "page_footer": {
-            "description": "状态页页脚内容。省略或传 null 表示保持原值。",
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "状态页页脚内容。省略或传 null 表示保持原值。"
           },
-          "page_header": {
-            "description": "状态页页头内容。省略或传 null 表示保持原值。",
+          "date_view": {
             "type": [
               "string",
               "null"
+            ],
+            "description": "事件日期的展示方式：`calendar` 为日历视图，`list` 为列表视图。省略或传 null 时保持不变；传空字符串会清空该设置。",
+            "enum": [
+              "calendar",
+              "list",
+              "",
+              null
             ]
           },
-          "page_id": {
-            "description": "状态页 ID，可通过 `GET /status-page/list` 获取。",
-            "format": "int64",
-            "type": "integer"
-          },
-          "page_title": {
-            "description": "状态页浏览器标题。省略或传 null 表示保持原值。",
+          "display_uptime_mode": {
             "type": [
               "string",
               "null"
+            ],
+            "description": "可用率的展示方式：`chart_and_percentage` 同时显示图表和百分比，`chart` 只显示图表，`none` 不显示。省略或传 null 时保持不变；传空字符串会清空该设置。",
+            "enum": [
+              "chart_and_percentage",
+              "chart",
+              "none",
+              "",
+              null
             ]
           },
-          "subscription": {
-            "$ref": "#/components/schemas/StatusPageSubscriptionItem",
-            "description": "订阅渠道开关。省略或传 null 表示保持原值。"
+          "custom_links": {
+            "type": "array",
+            "description": "状态页展示的自定义导航链接。省略或传空数组表示保持当前链接。",
+            "items": {
+              "type": "object",
+              "properties": {
+                "key": {
+                  "type": "string",
+                  "description": "页面上显示的链接文字。"
+                },
+                "value": {
+                  "type": "string",
+                  "description": "链接文字指向的地址，例如 `https://www.example.com`。"
+                }
+              },
+              "additionalProperties": {
+                "type": "string"
+              }
+            }
           },
-          "template_preference": {
-            "description": "偏好的事件模板类型：`pre_defined` 或 `message`。省略或传 null 表示保持原值。",
+          "contact_info": {
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "联系信息，例如 mailto 或网站 URL。省略或传 null 表示保持原值。"
           },
-          "url_name": {
-            "description": "URL 安全的状态页路径，在账户和状态页类型内唯一。省略或传 null 表示保持原值。",
-            "maxLength": 255,
+          "subscription": {
+            "$ref": "#/components/schemas/StatusPageSubscriptionItem",
+            "description": "订阅渠道开关。公开页只能开启 `email`，内部页只能开启 `im`。省略或传 null 时保持不变。"
+          },
+          "template_preference": {
             "type": [
               "string",
               "null"
+            ],
+            "description": "控制台发布事件时使用的模板模式：`message`（状态描述：按状态预设的描述文字）或 `pre_defined`（完整状态更新：包含标题、状态和描述的完整示例）。省略或传 null 时保持不变；服务端不校验取值。",
+            "enum": [
+              "pre_defined",
+              "message",
+              null
             ]
           }
-        },
-        "required": [
-          "page_id"
-        ],
-        "type": "object"
+        }
       },
       "UpdateWorkItemRequest": {
-        "description": "跟进事项的部分更新。未提供的字段保持不变；显式传 `null` 则清空该字段。",
+        "type": "object",
+        "description": "跟进事项的部分更新。未提供的字段以及传 `null` 的字段均保持不变。",
+        "required": [
+          "work_item_id",
+          "version"
+        ],
         "properties": {
-          "description": {
-            "description": "新描述（最长 65,535 字符）。",
-            "maxLength": 65535,
+          "work_item_id": {
+            "type": "string",
+            "maxLength": 128,
+            "description": "跟进事项 ID（不透明字符串，最长 128 字符）。"
+          },
+          "version": {
+            "type": "integer",
+            "format": "int64",
+            "description": "事项当前的 `version`（≥ 1），用于乐观锁。"
+          },
+          "title": {
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "新标题，最多 512 个字符；首尾空白会被去除且不能为空。传 `null` 或省略则保持不变。",
+            "maxLength": 512
           },
-          "priority": {
-            "description": "新的客户端自定义优先级（最长 64 字符）。",
-            "maxLength": 64,
+          "description": {
             "type": [
               "string",
               "null"
-            ]
+            ],
+            "description": "新描述，最多 65,535 个字符；传 `\"\"` 表示清空。传 `null` 或省略则保持不变。",
+            "maxLength": 65535
           },
           "status": {
-            "description": "新的客户端自定义状态，取 `open`、`in_progress`、`done`、`cancelled` 之一。",
+            "type": [
+              "string",
+              "null"
+            ],
             "enum": [
               "open",
               "in_progress",
               "done",
-              "cancelled"
+              "cancelled",
+              null
             ],
-            "maxLength": 64,
-            "type": [
-              "string",
-              "null"
-            ]
+            "description": "新状态。传 `null` 或省略则保持不变。\n- `open`：未开始。\n- `in_progress`：处理中。\n- `done`：已完成。\n- `cancelled`：已取消。"
           },
-          "title": {
-            "description": "新标题（最长 512 字符）。",
-            "maxLength": 512,
+          "priority": {
             "type": [
               "string",
               "null"
-            ]
-          },
-          "version": {
-            "description": "事项当前版本号，用于乐观锁。必须与存储的版本一致。",
-            "format": "int64",
-            "type": "integer"
-          },
-          "work_item_id": {
-            "description": "跟进事项 ID（不透明字符串，最长 128 字符）。",
-            "maxLength": 128,
-            "type": "string"
+            ],
+            "description": "新的优先级（自由文本），最多 64 个字符；传 `\"\"` 表示清空。传 `null` 或省略则保持不变。",
+            "maxLength": 64
           }
-        },
-        "required": [
-          "work_item_id",
-          "version"
-        ],
-        "type": "object"
+        }
       },
       "UpsertPostMortemTemplateRequest": {
+        "type": "object",
         "description": "创建或更新故障复盘模板的参数。",
+        "required": [
+          "name",
+          "content"
+        ],
         "properties": {
-          "content": {
-            "description": "BlockNote JSON 模板内容。",
-            "type": "string"
-          },
-          "content_markdown": {
-            "description": "模板内容的 Markdown 版本。",
-            "type": "string"
+          "template_id": {
+            "type": "string",
+            "description": "要替换的自定义模板 ID。省略表示创建新模板（ID 由服务端生成）。"
           },
-          "description": {
-            "description": "模板描述。",
-            "type": "string"
+          "team_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "管理团队 ID。创建时必填，且团队必须存在。更新时传入不同的团队 ID 会迁移模板；省略或传 0 保持当前团队。"
           },
           "name": {
-            "description": "模板名称。",
-            "type": "string"
+            "type": "string",
+            "description": "控制台中显示的模板名称。"
           },
-          "team_id": {
-            "description": "管理团队 ID。创建自定义模板时必填。",
-            "format": "int64",
-            "type": "integer"
+          "description": {
+            "type": "string",
+            "description": "模板描述；省略时为空。"
           },
-          "template_id": {
-            "description": "模板 ID。创建新模板时省略；更新已有模板时传入。",
-            "type": "string"
+          "content": {
+            "type": "string",
+            "description": "模板正文，为序列化成字符串的 BlockNote 编辑器 JSON（块数组）。基于该模板创建的报告以此为初始正文。"
+          },
+          "content_markdown": {
+            "type": "string",
+            "description": "正文的 Markdown 版本，AI 生成报告时作为提纲使用。省略时为空。"
           }
-        },
-        "required": [
-          "name",
-          "content"
-        ],
-        "type": "object"
+        }
       },
       "UpsertRouteRequest": {
-        "description": "创建或更新集成路由规则的参数。当指定集成尚无规则时执行创建,否则覆盖原有规则。`cases` 与 `default` 至少需要提供其一。",
+        "type": "object",
+        "description": "创建集成的路由规则；已存在时整体替换。`cases` 与 `default` 至少提供其一。",
+        "required": [
+          "integration_id"
+        ],
         "properties": {
+          "integration_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "共享集成 ID，可通过 `POST /integration/list` 获取。协作空间专属集成会返回 `InvalidParameter`。"
+          },
           "cases": {
-            "description": "有序的 case 分支列表,自上而下依次匹配。",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/RouteCase"
             },
-            "type": "array"
-          },
-          "default": {
-            "$ref": "#/components/schemas/RouteDefault",
-            "description": "兜底分支，所有 case 均未命中时使用。"
-          },
-          "integration_id": {
-            "description": "所属集成 ID。",
-            "format": "int64",
-            "type": "integer"
+            "description": "有序的 case 分支列表,自上而下依次匹配。"
           },
           "sections": {
-            "description": "可选的分区,用于将连续的 case 进行视觉分组。",
+            "type": "array",
             "items": {
               "$ref": "#/components/schemas/RouteSection"
             },
-            "type": "array"
+            "description": "可选的分区,用于将连续的 case 进行视觉分组。"
+          },
+          "default": {
+            "$ref": "#/components/schemas/RouteDefault",
+            "description": "没有任何 case 得到协作空间时使用的兜底分支。不传会删除已有的默认分支。"
           },
           "version": {
-            "description": "预留给乐观并发控制使用；当前服务端忽略该字段——每次 upsert 时服务端会自动递增 `version`。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "会被忽略。服务端每次写入都会递增 `version`，不会与此值比较。"
           }
-        },
-        "required": [
-          "integration_id"
-        ],
-        "type": "object"
+        }
       },
       "UpsertStatusPageComponentRequest": {
+        "type": "object",
         "description": "创建或更新状态页服务组件的请求参数。",
+        "required": [
+          "page_id",
+          "components"
+        ],
         "properties": {
+          "page_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "状态页 ID，可通过 `GET /status-page/list` 获取。"
+          },
           "components": {
+            "type": "array",
             "description": "要创建或更新的组件列表。",
             "items": {
+              "type": "object",
+              "required": [
+                "name"
+              ],
               "properties": {
-                "available_since_seconds": {
-                  "description": "组件可用起始时间（Unix 秒）。创建时缺省取当前时间；更新时覆盖原值。",
-                  "format": "int64",
-                  "type": "integer"
-                },
                 "component_id": {
-                  "description": "组件 ID。省略则创建新组件；提供则更新已有组件。",
-                  "type": "string"
-                },
-                "description": {
-                  "description": "组件描述。",
-                  "type": "string"
-                },
-                "hide_all": {
-                  "description": "为 true 时，在汇总接口中完全隐藏该组件。",
-                  "type": "boolean"
+                  "type": "string",
+                  "description": "组件 ID。省略则创建新组件；提供则更新已有组件。"
                 },
-                "hide_uptime": {
-                  "description": "为 true 时，在汇总接口中隐藏该组件的可用率数据。",
-                  "type": "boolean"
+                "section_id": {
+                  "type": "string",
+                  "description": "所属分组 ID，必须是该状态页已有的分组。省略时组件位于顶层（更新时同样生效）。"
                 },
                 "name": {
-                  "description": "组件显示名称。",
-                  "type": "string"
+                  "type": "string",
+                  "description": "组件显示名称，在状态页内必须唯一。"
+                },
+                "description": {
+                  "type": "string",
+                  "description": "组件描述。"
                 },
                 "order_id": {
-                  "description": "在所属区域中的显示顺序。",
+                  "type": "integer",
                   "format": "int64",
-                  "type": "integer"
+                  "description": "在所属分组内的显示顺序；更新时未传则重置为 0。"
                 },
-                "section_id": {
-                  "description": "所属区域 ID。省略则将组件置于顶层。",
-                  "type": "string"
-                }
-              },
-              "required": [
-                "name"
-              ],
-              "type": "object"
+                "hide_uptime": {
+                  "type": "boolean",
+                  "description": "为 true 时，在汇总接口中隐藏该组件的可用率数据。"
+                },
+                "hide_all": {
+                  "type": "boolean",
+                  "description": "为 true 时，在汇总接口中完全隐藏该组件。"
+                },
+                "available_since_seconds": {
+                  "type": "integer",
+                  "format": "int64",
+                  "description": "组件开始可用的时间，Unix 时间戳（秒），作为可用率统计的起点。仅创建时生效，默认取当前时间；更新时忽略。"
+                }
+              }
             },
-            "minItems": 1,
-            "type": "array"
-          },
-          "page_id": {
-            "description": "状态页 ID，可通过 `GET /status-page/list` 获取。",
-            "format": "int64",
-            "type": "integer"
+            "minItems": 1
           }
-        },
-        "required": [
-          "page_id",
-          "components"
-        ],
-        "type": "object"
+        }
       },
       "UpsertStatusPageComponentResponse": {
         "description": "创建或更新状态页组件的结果。",
@@ -28018,57 +29069,57 @@
         "type": "object"
       },
       "UpsertStatusPageSectionRequest": {
+        "type": "object",
         "description": "创建或更新状态页区域的请求参数。",
+        "required": [
+          "page_id",
+          "sections"
+        ],
         "properties": {
           "page_id": {
-            "description": "状态页 ID，可通过 `GET /status-page/list` 获取。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "状态页 ID，可通过 `GET /status-page/list` 获取。"
           },
           "sections": {
+            "type": "array",
             "description": "要创建或更新的区域列表。",
             "items": {
+              "type": "object",
+              "required": [
+                "name"
+              ],
               "properties": {
-                "description": {
-                  "description": "区域描述。",
-                  "type": "string"
-                },
-                "hide_all": {
-                  "description": "为 true 时，在汇总接口中完全隐藏该区域。",
-                  "type": "boolean"
-                },
-                "hide_uptime": {
-                  "description": "为 true 时，隐藏该区域下所有组件的可用率数据。",
-                  "type": "boolean"
+                "section_id": {
+                  "type": "string",
+                  "description": "区域 ID。省略则创建新区域；提供则更新已有区域。"
                 },
                 "name": {
-                  "description": "区域显示名称。",
-                  "type": "string"
+                  "type": "string",
+                  "description": "分组显示名称，在状态页内必须唯一。"
+                },
+                "description": {
+                  "type": "string",
+                  "description": "区域描述。"
                 },
                 "order_id": {
-                  "description": "显示顺序。",
+                  "type": "integer",
                   "format": "int64",
-                  "type": "integer"
+                  "description": "分组的显示顺序；更新时未传则重置为 0。"
                 },
-                "section_id": {
-                  "description": "区域 ID。省略则创建新区域；提供则更新已有区域。",
-                  "type": "string"
+                "hide_uptime": {
+                  "type": "boolean",
+                  "description": "为 true 时，隐藏该区域下所有组件的可用率数据。"
+                },
+                "hide_all": {
+                  "type": "boolean",
+                  "description": "为 true 时，在汇总接口中完全隐藏该区域。"
                 }
-              },
-              "required": [
-                "name"
-              ],
-              "type": "object"
+              }
             },
-            "minItems": 1,
-            "type": "array"
+            "minItems": 1
           }
-        },
-        "required": [
-          "page_id",
-          "sections"
-        ],
-        "type": "object"
+        }
       },
       "UpsertStatusPageSectionResponse": {
         "description": "创建或更新状态页区域的结果。",
@@ -28154,130 +29205,140 @@
         "type": "object"
       },
       "WarRoom": {
-        "description": "从 IM 侧拉取的战情室实时详情。若群组已在 IM 侧被删除则返回空对象。",
+        "type": "object",
+        "description": "从 IM 平台读取的作战室群组信息。IM 查询失败时（例如群组已在 Flashduty 之外解散），所有字段均为空字符串。",
+        "required": [
+          "chat_id",
+          "chat_name",
+          "share_link"
+        ],
         "properties": {
           "chat_id": {
-            "description": "IM 侧的群/会话 ID。",
-            "type": "string"
+            "type": "string",
+            "description": "IM 侧的群/会话 ID。"
           },
           "chat_name": {
-            "description": "群组显示名称。",
-            "type": "string"
+            "type": "string",
+            "description": "群组显示名称。"
           },
           "share_link": {
-            "description": "加入链接，若 IM 提供。",
-            "type": "string"
+            "type": "string",
+            "description": "加入链接，若 IM 提供。"
           }
-        },
-        "required": [
-          "chat_id",
-          "chat_name",
-          "share_link"
-        ],
-        "type": "object"
+        }
       },
       "WarRoomDataSourceItem": {
-        "description": "IM 集成（数据源）条目。",
+        "type": "object",
         "properties": {
-          "account_id": {
-            "description": "该集成所属账户。",
-            "format": "int64",
-            "type": "integer"
-          },
-          "category": {
-            "description": "插件类别；本接口返回的 IM 集成固定为 `im`。",
-            "type": "string"
-          },
-          "created_at": {
-            "description": "集成创建时的 Unix 时间戳（秒）。",
-            "format": "int64",
-            "type": "integer"
-          },
-          "creator_id": {
-            "description": "创建该集成的人员。",
-            "format": "int64",
-            "type": "integer"
-          },
           "data_source_id": {
+            "type": "integer",
             "description": "集成 ID。",
-            "format": "int64",
-            "type": "integer"
-          },
-          "description": {
-            "description": "集成描述。",
-            "type": "string"
-          },
-          "exclusive_data_source_id": {
-            "description": "历史遗留的独占集成关联 ID，已废弃。",
-            "format": "int64",
-            "type": "integer"
+            "format": "int64"
           },
-          "integration_id": {
-            "description": "集成 ID，data_source_id 的别名。",
-            "format": "int64",
-            "type": "integer"
+          "account_id": {
+            "type": "integer",
+            "description": "该集成所属账户。",
+            "format": "int64"
           },
-          "integration_key": {
-            "description": "告警源向该集成推送时使用的推送密钥。",
-            "type": "string"
+          "team_id": {
+            "type": "integer",
+            "description": "拥有该集成的团队。",
+            "format": "int64"
           },
-          "last_time": {
-            "description": "该数据源最近活动时间的 Unix 秒级时间戳。固定为 `0`，本接口不填充该字段。",
-            "format": "int64",
-            "type": "integer"
+          "plugin_id": {
+            "type": "integer",
+            "description": "该集成对应的插件 ID。",
+            "format": "int64"
           },
           "name": {
-            "description": "集成名称。",
-            "type": "string"
+            "type": "string",
+            "description": "集成名称。"
           },
-          "no_editable": {
-            "description": "集成是否为只读。",
-            "type": "boolean"
+          "status": {
+            "type": "string",
+            "description": "集成状态：`enabled` 启用、`disabled` 禁用。已删除的集成不会返回。",
+            "enum": [
+              "enabled",
+              "disabled"
+            ]
           },
-          "plugin_id": {
-            "description": "该集成对应的插件 ID。",
-            "format": "int64",
-            "type": "integer"
+          "category": {
+            "type": "string",
+            "description": "插件类别。本接口只返回 IM 集成，因此固定为 `im`。",
+            "enum": [
+              "im"
+            ]
           },
           "plugin_type": {
-            "description": "IM 集成插件类型标识，如 `feishu_app`、`dingtalk_app`、`wecom_app`、`slack_app`、`teams_app`。",
-            "type": "string"
+            "type": "string",
+            "description": "IM 集成类型：`feishu_app` 飞书，`dingtalk_app` 钉钉，`wecom_app` 企业微信，`slack_app` Slack，`teams_app` Microsoft Teams。",
+            "enum": [
+              "feishu_app",
+              "dingtalk_app",
+              "wecom_app",
+              "slack_app",
+              "teams_app"
+            ]
           },
           "plugin_type_name": {
-            "description": "集成插件类型的本地化显示名称。",
-            "type": "string"
+            "type": "string",
+            "description": "集成插件类型的本地化显示名称。"
+          },
+          "description": {
+            "type": "string",
+            "description": "集成描述。"
+          },
+          "integration_key": {
+            "type": "string",
+            "description": "告警源向该集成推送时使用的推送密钥。"
           },
           "ref_id": {
-            "description": "集成的外部引用 ID。",
-            "type": "string"
+            "type": "string",
+            "description": "集成的外部引用 ID。"
           },
           "settings": {
+            "type": "object",
             "additionalProperties": true,
-            "description": "集成的插件特定配置。",
-            "type": "object"
+            "description": "集成的插件配置，包含 `war_room_enabled: true`；密钥类字段掩码为 `******`。"
           },
-          "status": {
-            "description": "集成状态：`enabled` 启用、`disabled` 禁用。已删除的集成不会返回。",
-            "enum": [
-              "enabled",
-              "disabled"
-            ],
-            "type": "string"
+          "no_editable": {
+            "type": "boolean",
+            "description": "集成是否为只读。"
           },
-          "team_id": {
-            "description": "拥有该集成的团队。",
+          "creator_id": {
+            "type": "integer",
+            "description": "创建该集成的人员。",
+            "format": "int64"
+          },
+          "updated_by": {
+            "type": "integer",
+            "description": "最近更新该集成的人员。",
+            "format": "int64"
+          },
+          "created_at": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "集成创建时的 Unix 时间戳（秒）。"
           },
           "updated_at": {
-            "description": "集成最近更新时的 Unix 时间戳（秒）。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "集成最近更新时的 Unix 时间戳（秒）。"
           },
-          "updated_by": {
-            "description": "最近更新该集成的人员。",
+          "last_time": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "该数据源最近活动时间的 Unix 秒级时间戳。固定为 `0`，本接口不填充该字段。"
+          },
+          "exclusive_data_source_id": {
+            "type": "integer",
+            "description": "已废弃，本接口中恒为 `0`。",
+            "format": "int64"
+          },
+          "integration_id": {
+            "type": "integer",
+            "description": "集成 ID，与 `data_source_id` 相同。",
+            "format": "int64"
           }
         },
         "required": [
@@ -28303,51 +29364,69 @@
           "exclusive_data_source_id",
           "integration_id"
         ],
-        "type": "object"
+        "description": "IM 集成（数据源）条目。"
       },
       "WarRoomItem": {
+        "type": "object",
         "description": "战情室记录。",
+        "required": [
+          "account_id",
+          "integration_id",
+          "created_by",
+          "chat_id",
+          "incident_id",
+          "status",
+          "created_at",
+          "plugin_type",
+          "chat_name"
+        ],
         "properties": {
           "account_id": {
-            "description": "账号 ID。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
-          },
-          "chat_id": {
-            "description": "IM 侧的群/会话 ID。",
-            "type": "string"
+            "description": "该记录所属账户的 ID；同一 `app_key` 返回的记录该值都相同。"
           },
-          "created_at": {
-            "description": "创建时间戳（秒）。",
+          "integration_id": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "IM 集成 ID。"
           },
           "created_by": {
-            "description": "创建成员 ID。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "创建成员 ID。"
+          },
+          "chat_id": {
+            "type": "string",
+            "description": "IM 侧的群/会话 ID。"
           },
           "incident_id": {
-            "description": "关联的故障 ID（MongoDB ObjectID）。",
+            "type": "string",
             "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
+            "description": "关联的故障 ID（MongoDB ObjectID）。"
           },
-          "integration_id": {
-            "description": "IM 集成 ID。",
+          "status": {
+            "type": "string",
+            "description": "记录状态。列表中恒为 `enabled`，已删除的作战室不会返回。",
+            "enum": [
+              "enabled"
+            ]
+          },
+          "created_at": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "作战室创建的 Unix 时间戳（秒）。"
           },
           "plugin_type": {
-            "description": "IM 插件类型（如 `feishu`、`dingtalk`、`wecom`、`slack`）。",
-            "type": "string"
-          },
-          "status": {
-            "description": "作战室记录状态：`enabled` 生效中，`deleted` 已解散。",
+            "type": "string",
+            "description": "IM 集成的插件类型：`feishu_app`（飞书）、`dingtalk_app`（钉钉）、`wecom_app`（企业微信）、`slack_app`（Slack）。集成已不存在时为空字符串。",
             "enum": [
-              "enabled",
-              "deleted"
-            ],
-            "type": "string"
+              "feishu_app",
+              "dingtalk_app",
+              "wecom_app",
+              "slack_app",
+              ""
+            ]
           },
           "chat_name": {
             "type": "string",
@@ -28357,161 +29436,175 @@
             "type": "boolean",
             "description": "该作战室背后的 IM 集成已禁用或已不存在时为 true。"
           }
-        },
-        "required": [
-          "account_id",
-          "integration_id",
-          "created_by",
-          "chat_id",
-          "incident_id",
-          "status",
-          "created_at",
-          "plugin_type",
-          "chat_name"
-        ],
-        "type": "object"
+        }
       },
       "WarRoomPersonItem": {
+        "type": "object",
         "properties": {
           "account_id": {
+            "type": "integer",
             "description": "该人员所属账户。",
-            "format": "int64",
-            "type": "integer"
+            "format": "int64"
           },
-          "as": {
-            "description": "人员在相关上下文中担任的角色。",
-            "type": "string"
+          "person_id": {
+            "type": "integer",
+            "description": "人员 ID：成员 ID；若为账户所有者（`as` = `account`）则为账户 ID。",
+            "format": "int64"
+          },
+          "person_name": {
+            "type": "string",
+            "description": "人员显示名称。"
           },
           "avatar": {
-            "description": "人员头像图片 URL。",
-            "type": "string"
+            "type": "string",
+            "description": "人员头像图片 URL。"
           },
           "email": {
-            "description": "人员邮箱地址。",
-            "type": "string"
+            "type": "string",
+            "description": "邮箱地址；成员未验证时不返回。"
           },
-          "locale": {
-            "description": "人员偏好的语言区域。",
-            "type": "string"
+          "phone": {
+            "type": "string",
+            "description": "手机号；成员未验证时不返回。"
           },
-          "person_id": {
-            "description": "人员 ID。",
-            "format": "int64",
-            "type": "integer"
+          "locale": {
+            "type": "string",
+            "description": "偏好语言，例如 `zh-CN` 或 `en-US`。"
           },
-          "person_name": {
-            "description": "人员显示名称。",
-            "type": "string"
+          "time_zone": {
+            "type": "string",
+            "description": "IANA 时区名，例如 `Asia/Shanghai`。"
           },
-          "phone": {
-            "description": "人员电话号码。",
-            "type": "string"
+          "as": {
+            "type": "string",
+            "enum": [
+              "account",
+              "member"
+            ],
+            "description": "人员身份类型。\n- `account`：账户所有者。\n- `member`：账户内的普通成员。"
           },
           "status": {
-            "description": "人员当前状态。",
-            "type": "string"
-          },
-          "time_zone": {
-            "description": "人员所在时区。",
-            "type": "string"
+            "type": "string",
+            "enum": [
+              "enabled",
+              "pending",
+              "deleted"
+            ],
+            "description": "成员状态。\n- `enabled`：正常。\n- `pending`：已邀请但尚未加入。\n- `deleted`：已从账户移除。"
           }
         },
         "required": [
           "account_id",
           "person_id"
-        ],
-        "type": "object"
+        ]
       },
       "WebhookHistoryDetail": {
+        "type": "object",
         "description": "单条 Webhook 投递记录的完整详情，在 `WebhookHistoryItem` 基础上增加查询时解析的关联对象信息。无匹配记录时，`data` 为空对象。",
+        "required": [
+          "integration_id",
+          "event_id",
+          "webhook_type",
+          "event_type",
+          "endpoint",
+          "attempt",
+          "duration",
+          "status",
+          "status_code",
+          "event_time"
+        ],
         "properties": {
-          "attempt": {
-            "description": "尝试次数。",
-            "type": "integer"
-          },
-          "channel_id": {
-            "description": "协作空间 ID（若有）。",
+          "integration_id": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
-          },
-          "channel_name": {
-            "description": "查询时解析出的关联协作空间名称。",
-            "type": "string"
-          },
-          "duration": {
-            "description": "整次尝试耗时（毫秒）。",
-            "type": "integer"
-          },
-          "endpoint": {
-            "description": "目标地址。",
-            "type": "string"
-          },
-          "error_message": {
-            "description": "投递失败时的错误信息。",
-            "type": "string"
+            "description": "发出该请求的 Webhook 集成 ID。"
           },
           "event_id": {
-            "description": "事件 ID。",
-            "type": "string"
+            "type": "string",
+            "description": "本条推送记录的 ID：推送日期（`YYYYMMDD`）加随机后缀。可传给 `POST /webhook/history/detail`。"
           },
-          "event_time": {
-            "description": "事件时间，格式 `YYYY-MM-DD HH:MM:SS.ffffff`。",
-            "type": "string"
+          "webhook_type": {
+            "type": "string",
+            "description": "来源对象类型：`incident`（故障）或 `alert`（告警）。",
+            "enum": [
+              "incident",
+              "alert"
+            ]
           },
           "event_type": {
-            "description": "事件类型代码。`i_*` 为故障事件（如 `i_new` 故障创建），`a_*` 为告警事件（如 `a_new` 告警触发）。",
-            "type": "string"
+            "type": "string",
+            "description": "事件类型代码。`i_*` 为故障事件（如 `i_new` 故障创建），`a_*` 为告警事件（如 `a_new` 告警触发）。"
           },
-          "integration_id": {
-            "description": "集成 ID。",
+          "channel_id": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "协作空间 ID（若有）。"
           },
           "ref_id": {
-            "description": "来源对象 ID。",
-            "type": "string"
+            "type": "string",
+            "description": "来源对象 ID。"
           },
-          "ref_title": {
-            "description": "查询时解析出的来源故障或告警标题。",
-            "type": "string"
+          "request_headers": {
+            "type": "string",
+            "description": "序列化的出站请求头。"
           },
           "request_body": {
-            "description": "出站请求体。",
-            "type": "string"
+            "type": "string",
+            "description": "发送给目标地址的 JSON 请求体，超过存储上限的部分被截断。"
           },
-          "request_headers": {
-            "description": "序列化的出站请求头。",
-            "type": "string"
+          "endpoint": {
+            "type": "string",
+            "description": "目标地址。"
           },
-          "response_body": {
-            "description": "响应体。",
-            "type": "string"
+          "attempt": {
+            "type": "integer",
+            "description": "本次推送的 HTTP 尝试次数；仅在连接错误时重试。"
           },
-          "response_headers": {
-            "description": "序列化的响应头。",
-            "type": "string"
+          "duration": {
+            "type": "integer",
+            "description": "本次推送（含重试）的总耗时，单位毫秒。"
           },
           "status": {
-            "description": "投递结果。",
+            "type": "string",
             "enum": [
               "success",
               "failed"
             ],
-            "type": "string"
+            "description": "推送结果：目标地址返回 HTTP 200 时为 `success`；连接错误或返回其他状态码时为 `failed`。"
           },
           "status_code": {
-            "description": "HTTP 状态码。",
-            "type": "integer"
+            "type": "integer",
+            "description": "目标地址返回的 HTTP 状态码；未收到响应时为 `0`。"
           },
-          "webhook_type": {
-            "description": "来源对象类型：`incident`（故障）或 `alert`（告警）。",
-            "enum": [
-              "incident",
-              "alert"
-            ],
-            "type": "string"
+          "error_message": {
+            "type": "string",
+            "description": "推送失败时的错误信息（连接错误或非预期状态码），会被截断。成功时不返回。"
+          },
+          "response_headers": {
+            "type": "string",
+            "description": "序列化的响应头。"
+          },
+          "response_body": {
+            "type": "string",
+            "description": "目标地址返回的响应体，超过存储上限的部分被截断。为空或未收到响应时不返回。"
+          },
+          "event_time": {
+            "type": "string",
+            "description": "事件时间，格式 `YYYY-MM-DD HH:MM:SS.ffffff`。"
+          },
+          "ref_title": {
+            "type": "string",
+            "description": "查询时解析出的来源故障或告警标题。"
+          },
+          "channel_name": {
+            "type": "string",
+            "description": "查询时解析出的关联协作空间名称。"
           }
-        },
+        }
+      },
+      "WebhookHistoryItem": {
+        "type": "object",
+        "description": "一次 Webhook 投递记录。带 `omitempty` 的字段在取零值时会被省略。",
         "required": [
           "integration_id",
           "event_id",
@@ -28524,103 +29617,86 @@
           "status_code",
           "event_time"
         ],
-        "type": "object"
-      },
-      "WebhookHistoryItem": {
-        "description": "一次 Webhook 投递记录。带 `omitempty` 的字段在取零值时会被省略。",
         "properties": {
-          "attempt": {
-            "description": "尝试次数。",
-            "type": "integer"
-          },
-          "channel_id": {
-            "description": "事件所属协作空间 ID（若有）。",
+          "integration_id": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
-          },
-          "duration": {
-            "description": "整次尝试耗时（毫秒）。",
-            "type": "integer"
-          },
-          "endpoint": {
-            "description": "目标地址。",
-            "type": "string"
-          },
-          "error_message": {
-            "description": "投递失败时的错误信息。",
-            "type": "string"
+            "description": "发出该请求的 Webhook 集成 ID。"
           },
           "event_id": {
-            "description": "本次投递的唯一事件 ID。",
-            "type": "string"
+            "type": "string",
+            "description": "本条推送记录的 ID：推送日期（`YYYYMMDD`）加随机后缀。可传给 `POST /webhook/history/detail`。"
           },
-          "event_time": {
-            "description": "事件时间，格式 `YYYY-MM-DD HH:MM:SS.ffffff`。",
-            "type": "string"
+          "webhook_type": {
+            "type": "string",
+            "description": "来源对象类型：`incident`（故障）或 `alert`（告警）。",
+            "enum": [
+              "incident",
+              "alert"
+            ]
           },
           "event_type": {
-            "description": "事件类型代码。`i_*` 为故障事件（如 `i_new` 故障创建），`a_*` 为告警事件（如 `a_new` 告警触发）。",
-            "type": "string"
+            "type": "string",
+            "description": "事件类型代码。`i_*` 为故障事件（如 `i_new` 故障创建），`a_*` 为告警事件（如 `a_new` 告警触发）。"
           },
-          "integration_id": {
-            "description": "触发 Webhook 的集成 ID。",
+          "channel_id": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "事件所属协作空间 ID（若有）。"
           },
           "ref_id": {
-            "description": "来源对象 ID（故障或告警 ID）。",
-            "type": "string"
+            "type": "string",
+            "description": "来源对象 ID（故障或告警 ID）。"
+          },
+          "request_headers": {
+            "type": "string",
+            "description": "序列化的出站请求头。"
           },
           "request_body": {
-            "description": "出站请求体。",
-            "type": "string"
+            "type": "string",
+            "description": "发送给目标地址的 JSON 请求体，超过存储上限的部分被截断。"
           },
-          "request_headers": {
-            "description": "序列化的出站请求头。",
-            "type": "string"
+          "endpoint": {
+            "type": "string",
+            "description": "目标地址。"
           },
-          "response_body": {
-            "description": "目标返回的响应体。",
-            "type": "string"
+          "attempt": {
+            "type": "integer",
+            "description": "本次推送的 HTTP 尝试次数；仅在连接错误时重试。"
           },
-          "response_headers": {
-            "description": "序列化的响应头。",
-            "type": "string"
+          "duration": {
+            "type": "integer",
+            "description": "本次推送（含重试）的总耗时，单位毫秒。"
           },
           "status": {
-            "description": "投递结果。",
+            "type": "string",
             "enum": [
               "success",
               "failed"
             ],
-            "type": "string"
+            "description": "推送结果：目标地址返回 HTTP 200 时为 `success`；连接错误或返回其他状态码时为 `failed`。"
           },
           "status_code": {
-            "description": "目标返回的 HTTP 状态码。",
-            "type": "integer"
+            "type": "integer",
+            "description": "目标地址返回的 HTTP 状态码；未收到响应时为 `0`。"
           },
-          "webhook_type": {
-            "description": "来源对象类型：`incident`（故障）或 `alert`（告警）。",
-            "enum": [
-              "incident",
-              "alert"
-            ],
-            "type": "string"
+          "error_message": {
+            "type": "string",
+            "description": "推送失败时的错误信息（连接错误或非预期状态码），会被截断。成功时不返回。"
+          },
+          "response_headers": {
+            "type": "string",
+            "description": "序列化的响应头。"
+          },
+          "response_body": {
+            "type": "string",
+            "description": "目标地址返回的响应体，超过存储上限的部分被截断。为空或未收到响应时不返回。"
+          },
+          "event_time": {
+            "type": "string",
+            "description": "事件时间，格式 `YYYY-MM-DD HH:MM:SS.ffffff`。"
           }
-        },
-        "required": [
-          "integration_id",
-          "event_id",
-          "webhook_type",
-          "event_type",
-          "endpoint",
-          "attempt",
-          "duration",
-          "status",
-          "status_code",
-          "event_time"
-        ],
-        "type": "object"
+        }
       },
       "WorkItemAssignee": {
         "description": "跟进事项的一名负责人。",
@@ -28645,165 +29721,165 @@
         "type": "object"
       },
       "WorkItemCreateResult": {
+        "type": "object",
         "description": "创建跟进事项的结果。",
+        "required": [
+          "item"
+        ],
         "properties": {
+          "item": {
+            "$ref": "#/components/schemas/WorkItemItem"
+          },
           "added_assignee_ids": {
-            "description": "新添加（并已通知）的负责人成员 ID。",
+            "type": "array",
             "items": {
-              "format": "int64",
-              "type": "integer"
+              "type": "integer",
+              "format": "int64"
             },
-            "type": "array"
+            "description": "本次新增（并已通知）的人员负责人成员 ID；不含 AI SRE。没有时不返回。"
           },
           "idempotent_replay": {
-            "description": "为 true 表示本次调用以相同幂等键重放了之前的请求，未创建新事项。",
-            "type": "boolean"
-          },
-          "item": {
-            "$ref": "#/components/schemas/WorkItemItem"
+            "type": "boolean",
+            "description": "为 true 表示本次调用以相同幂等键重放了之前的请求，未创建新事项。"
           }
-        },
-        "required": [
-          "item"
-        ],
-        "type": "object"
+        }
       },
       "WorkItemItem": {
+        "type": "object",
         "description": "结构化的故障跟进事项（行动项或复盘后续行动）及其负责人。",
+        "required": [
+          "work_item_id",
+          "item_type",
+          "incident_id",
+          "title",
+          "status",
+          "source_kind",
+          "version",
+          "assignee_ids",
+          "assignees",
+          "created_by",
+          "updated_by",
+          "created_at_seconds",
+          "updated_at_seconds"
+        ],
         "properties": {
-          "agent_session_id": {
-            "description": "执行该事项的 AI SRE 会话 ID。没有会话时省略。",
-            "type": "string"
+          "work_item_id": {
+            "type": "string",
+            "maxLength": 128,
+            "description": "跟进事项 ID（不透明字符串，最长 128 字符）。"
           },
-          "agent_session_venue": {
-            "description": "该 AI SRE 会话所在位置：`web` 或 `im`。没有会话时省略。",
+          "item_type": {
+            "type": "string",
             "enum": [
-              "web",
-              "im"
+              "action",
+              "follow_up"
             ],
-            "type": "string"
-          },
-          "assignee_ids": {
-            "description": "当前人员负责人的成员 ID。不含 AI SRE。不会为 null；空数组表示没有人员负责人。",
-            "items": {
-              "format": "int64",
-              "type": "integer"
-            },
-            "type": "array"
-          },
-          "assignees": {
-            "description": "当前负责人。每项为 `{type, id?}`。`type` 取 `person` 或 `ai_sre`；`ai_sre` 不带 `id`。不会为 null；空数组表示未指派。`assignee_ids` 是其中仅含 `person` 的子集。",
-            "items": {
-              "$ref": "#/components/schemas/WorkItemAssignee"
-            },
-            "type": "array"
+            "description": "事项类型。\n- `action`：未关闭故障上的待办。\n- `follow_up`：复盘后续行动，在已关闭故障上创建或由行动项转换而来。"
           },
-          "converted_at_seconds": {
-            "description": "转化时间，Unix 秒级时间戳。仅转化后返回。",
-            "format": "int64",
-            "type": "integer"
-          },
-          "converted_by": {
-            "description": "将行动项转化为后续行动的操作人成员 ID。仅转化后返回。",
-            "format": "int64",
-            "type": "integer"
+          "incident_id": {
+            "type": "string",
+            "pattern": "^[0-9a-fA-F]{24}$",
+            "description": "事项锚定的故障 ID（MongoDB ObjectID）。"
           },
-          "created_at_seconds": {
-            "description": "创建时间，Unix 秒级时间戳。",
-            "format": "int64",
-            "type": "integer"
+          "post_mortem_id": {
+            "type": "string",
+            "description": "复盘 ID（32 位十六进制字符串）。仅绑定了复盘的后续行动返回；否则不返回。"
           },
-          "created_by": {
-            "description": "创建者成员 ID。",
-            "format": "int64",
-            "type": "integer"
+          "title": {
+            "type": "string",
+            "maxLength": 512,
+            "description": "事项标题（最长 512 字符）。"
           },
           "description": {
-            "description": "可选的详细描述（最长 65,535 字符）。",
+            "type": "string",
             "maxLength": 65535,
-            "type": "string"
-          },
-          "incident_id": {
-            "description": "事项锚定的故障 ID（MongoDB ObjectID）。",
-            "pattern": "^[0-9a-fA-F]{24}$",
-            "type": "string"
-          },
-          "item_type": {
-            "description": "`action` 表示锚定在活动故障上的行动项；`follow_up` 表示复盘后续行动。",
-            "enum": [
-              "action",
-              "follow_up"
-            ],
-            "type": "string"
-          },
-          "legacy_source_id": {
-            "description": "该事项迁移自旧版后续行动的原始标识。仅当 `source_kind` 为 `legacy_follow_up` 时返回。",
-            "type": "string"
+            "description": "可选的详细描述（最长 65,535 字符）。"
           },
-          "post_mortem_id": {
-            "description": "故障复盘 ID（32 位十六进制字符串）。后续行动绑定复盘后返回。",
-            "type": "string"
+          "status": {
+            "type": "string",
+            "maxLength": 64,
+            "description": "事项状态：`open`（未开始）、`in_progress`（处理中）、`done`（已完成）或 `cancelled`（已取消）。`done` 和 `cancelled` 视为已结束。较早的事项可能仍保存其他自由文本，此类值视为未结束。"
           },
           "priority": {
-            "description": "可选的客户端自定义优先级（最长 64 字符）。",
+            "type": "string",
             "maxLength": 64,
-            "type": "string"
+            "description": "优先级（自由文本），最多 64 个字符；为空时不返回。控制台使用 `high`、`medium`、`low`，但通过 API 设置的任意字符串都会原样返回。"
           },
           "source_kind": {
-            "description": "`native` 表示通过本 API 创建的事项；`legacy_follow_up` 表示从旧版复盘后续行动迁移而来的事项。",
+            "type": "string",
             "enum": [
               "native",
               "legacy_follow_up"
             ],
-            "type": "string"
+            "description": "`native` 表示通过本 API 创建的事项；`legacy_follow_up` 表示从旧版复盘后续行动迁移而来的事项。"
           },
-          "status": {
-            "description": "客户端自定义状态（最长 64 字符），没有固定状态机。",
-            "maxLength": 64,
+          "legacy_source_id": {
+            "type": "string",
+            "description": "该事项迁移自旧版后续行动的原始标识。仅当 `source_kind` 为 `legacy_follow_up` 时返回。"
+          },
+          "version": {
+            "type": "integer",
+            "format": "int64",
+            "description": "乐观锁版本号，每次变更递增。"
+          },
+          "assignee_ids": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "int64"
+            },
+            "description": "当前人员负责人的成员 ID。不含 AI SRE。不会为 null；空数组表示没有人员负责人。"
+          },
+          "assignees": {
+            "description": "当前负责人。每项为 `{type, id?}`。`type` 取 `person` 或 `ai_sre`；`ai_sre` 不带 `id`。不会为 null；空数组表示未指派。`assignee_ids` 是其中仅含 `person` 的子集。",
+            "items": {
+              "$ref": "#/components/schemas/WorkItemAssignee"
+            },
+            "type": "array"
+          },
+          "agent_session_id": {
+            "description": "执行该事项的 AI SRE 会话 ID。没有会话时省略。",
             "type": "string"
           },
-          "title": {
-            "description": "事项标题（最长 512 字符）。",
-            "maxLength": 512,
+          "agent_session_venue": {
+            "description": "该 AI SRE 会话所在位置：`web` 或 `im`。没有会话时省略。",
+            "enum": [
+              "web",
+              "im"
+            ],
             "type": "string"
           },
-          "updated_at_seconds": {
-            "description": "最后更新时间，Unix 秒级时间戳。",
+          "created_by": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "创建者成员 ID。"
           },
           "updated_by": {
-            "description": "最后更新人成员 ID。",
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "最后更新人成员 ID。"
           },
-          "version": {
-            "description": "乐观锁版本号，每次变更递增。",
+          "converted_by": {
+            "type": "integer",
             "format": "int64",
-            "type": "integer"
+            "description": "将行动项转化为后续行动的操作人成员 ID。仅转化后返回。"
           },
-          "work_item_id": {
-            "description": "跟进事项 ID（不透明字符串，最长 128 字符）。",
-            "maxLength": 128,
-            "type": "string"
+          "converted_at_seconds": {
+            "type": "integer",
+            "format": "int64",
+            "description": "转化时间，Unix 秒级时间戳。仅转化后返回。"
+          },
+          "created_at_seconds": {
+            "type": "integer",
+            "format": "int64",
+            "description": "创建时间，Unix 秒级时间戳。"
+          },
+          "updated_at_seconds": {
+            "type": "integer",
+            "format": "int64",
+            "description": "最后更新时间，Unix 秒级时间戳。"
           }
-        },
-        "required": [
-          "work_item_id",
-          "item_type",
-          "incident_id",
-          "title",
-          "status",
-          "source_kind",
-          "version",
-          "assignee_ids",
-          "assignees",
-          "created_by",
-          "updated_by",
-          "created_at_seconds",
-          "updated_at_seconds"
-        ],
-        "type": "object"
+        }
       },
       "WorkItemListResult": {
         "description": "游标分页的跟进事项列表。",
@@ -28835,33 +29911,33 @@
         "type": "object"
       },
       "WorkItemMutationResult": {
-        "description": "变更跟进事项的结果。",
+        "type": "object",
+        "description": "跟进事项变更结果。删除操作不返回 `item`。",
         "properties": {
+          "item": {
+            "$ref": "#/components/schemas/WorkItemItem"
+          },
           "added_assignee_ids": {
-            "description": "新添加（并已通知）的负责人成员 ID。",
+            "type": "array",
             "items": {
-              "format": "int64",
-              "type": "integer"
+              "type": "integer",
+              "format": "int64"
             },
-            "type": "array"
-          },
-          "idempotent_replay": {
-            "description": "为 true 表示本次调用以相同幂等键重放了之前的请求。",
-            "type": "boolean"
-          },
-          "item": {
-            "$ref": "#/components/schemas/WorkItemItem"
+            "description": "本次新增（并已通知）的人员负责人成员 ID；不含 AI SRE。没有时不返回。"
           },
           "removed_assignee_ids": {
-            "description": "被移除（不通知）的负责人成员 ID。",
+            "type": "array",
             "items": {
-              "format": "int64",
-              "type": "integer"
+              "type": "integer",
+              "format": "int64"
             },
-            "type": "array"
+            "description": "本次移除的人员负责人成员 ID（不会通知）。没有时不返回。"
+          },
+          "idempotent_replay": {
+            "type": "boolean",
+            "description": "为 true 表示本次调用以相同幂等键重放了之前的请求。"
           }
-        },
-        "type": "object"
+        }
       },
       "AlertRuleV2": {
         "type": "object",
@@ -28891,11 +29967,11 @@
             "additionalProperties": {
               "type": "string"
             },
-            "description": "自定义标签。"
+            "description": "附加到该规则每个告警事件上的自定义标签。键会去除首尾空白，不能为空，且不能以 `__alert_rule_` 开头（保留前缀）；包含 `{{` 的值会在事件投递时按模板渲染；`job` 与 `instance` 的值最长 255 个字符。序列化后的对象不得超过 1024 个字符。"
           },
           "ds_type": {
             "type": "string",
-            "description": "数据源类型标识（如 `prometheus`、`elasticsearch`）。"
+            "description": "规则查询的数据源类型。规则启用时必须是支持告警的类型：`prometheus`、`elasticsearch`、`loki`、`clickhouse`、`mysql`、`oracle`、`postgres`、`sls`、`tencent_cls`、`victorialogs`。"
           },
           "ds_list": {
             "type": "array",
@@ -28926,7 +30002,7 @@
           },
           "cron_pattern": {
             "type": "string",
-            "description": "调度表达式：6 段（含秒）cron 表达式或 `@every 30s` 间隔描述。不允许以 `CRON_TZ=` 或 `TZ=` 开头，时区请填写到 `timezone` 字段。"
+            "description": "调度表达式：6 段（含秒）cron 表达式（如 `0 * * * * *`）、`@hourly` 等描述符，或 `@every <时长>`（须为整数秒且不小于 `1s`，如 `@every 30s`）。不允许以 `CRON_TZ=` 或 `TZ=` 开头，时区请填写到 `timezone` 字段。"
           },
           "timezone": {
             "type": "string",
@@ -28963,15 +30039,15 @@
                   "items": {
                     "type": "integer"
                   },
-                  "description": "星期几（0=周日）。"
+                  "description": "时间窗口适用的星期，`0` = 周日至 `6` = 周六；不能为空，不能重复。"
                 },
                 "stime": {
                   "type": "string",
-                  "description": "开始时间，如 `09:00`。"
+                  "description": "开始时间，24 小时制 `HH:MM` 格式，如 `09:00`。"
                 },
                 "etime": {
                   "type": "string",
-                  "description": "结束时间，如 `18:00`。"
+                  "description": "结束时间，24 小时制 `HH:MM` 格式，如 `18:00`。"
                 }
               }
             }
@@ -28994,7 +30070,7 @@
           },
           "description": {
             "type": "string",
-            "description": "规则描述，Markdown 格式。"
+            "description": "规则描述，按 `description_type` 以纯文本或 Markdown 渲染。"
           },
           "channel_ids": {
             "type": "array",
@@ -29007,12 +30083,12 @@
           "repeat_interval": {
             "type": "integer",
             "format": "int64",
-            "description": "通知重复间隔（秒）。小于 1 时按默认值 3600 处理。"
+            "description": "通知重复间隔（秒）。小于 1 时按默认值 3600 处理，最大 2147483647。"
           },
           "repeat_total": {
             "type": "integer",
             "format": "int64",
-            "description": "最大重复通知次数。小于 1 时按默认值 3 处理。"
+            "description": "最大重复通知次数。小于 1 时按默认值 3 处理，最大 2147483647。"
           },
           "investigation_targets": {
             "type": "array",
@@ -29020,7 +30096,7 @@
               "$ref": "#/components/schemas/InvestigationTarget"
             },
             "maxItems": 20,
-            "description": "告警事件详情页关联的排障入口列表，最多 20 项，不允许重复。更新接口中该字段按 presence 处理：省略时保留原配置，传 `[]` 清空。",
+            "description": "告警事件详情页关联的排障入口列表，最多 20 项，不允许重复，序列化后不超过 32 KiB。更新接口中该字段按 presence 处理：省略时保留原配置，传 `[]` 清空；传 `null` 会被拒绝。",
             "x-flashduty-preserve-absence": true
           },
           "creator_id": {
@@ -29105,7 +30181,7 @@
           },
           "relate_queries": {
             "type": "array",
-            "description": "可选的辅助查询，其结果作为上下文附加到告警事件中。每项须有唯一的 `name`（不与任何 query 名称重复）且 `expr` 非空。",
+            "description": "可选的辅助查询，其结果作为上下文附加到告警事件中。每项须有唯一的 `name`（不与任何 query 名称重复）且 `expr` 非空。响应中始终返回，没有时为 `[]`。",
             "items": {
               "type": "object",
               "properties": {
@@ -29424,7 +30500,7 @@
       },
       "DashboardQuery": {
         "type": "object",
-        "description": "仪表盘与排障入口共用的查询内容。",
+        "description": "仪表盘面板与告警规则排障入口共用的查询内容。两种场景的模板语法不同：仪表盘面板引用仪表盘变量（`${name}`），排障入口引用事件标签（`{{ }}`）。",
         "properties": {
           "mode": {
             "type": "string",
@@ -29433,18 +30509,18 @@
               "range",
               "window"
             ],
-            "description": "求值模式：`instant` 在单个时间点求值，`range` 求值一条按步长采样的曲线，`window` 返回时间窗口内的原始数据。"
+            "description": "求值模式：`instant` = 在单个时间点求值；`range` = 在时间范围内按步长求值得到曲线；`window` = 返回时间范围内的原始数据行。Prometheus 与 Loki 面板接受 `instant` 或 `range`（Loki 的 `logs` 面板需要 `range`）；MySQL 面板需要 `window`。"
           },
           "expr": {
             "type": "string",
-            "description": "目标数据源语法下的查询表达式，可通过 `{{ }}` 模板引用事件标签。"
+            "description": "数据源语法下的查询表达式。在仪表盘面板中可以 `${name}`、`${name:raw}`（原样插入单个值）或 `${name:regex}`（多个值拼成正则多选）引用变量，在 Prometheus 与 Loki 中也可写 `$name`；需要字面量时写 `$${...}`。不带格式化符时，多选或 `all` 变量以及 `=~`/`!~` 中的值会以正则形式插入，因此不能用在 `=` 或 `!=` 之后。MySQL 查询不支持变量。在排障入口中，表达式可通过 `{{ }}` 模板引用事件标签。"
           },
           "args": {
             "type": "object",
             "additionalProperties": {
               "type": "string"
             },
-            "description": "命名查询参数，默认空对象。值按原样透传，不允许包含 `{{ }}` 模板。"
+            "description": "命名查询参数，默认空对象。在仪表盘面板中，除 Loki 与 MySQL 数据源外，值可使用 `${name}` 模板。在排障入口中，键和值都不允许包含 `{{ }}` 模板。"
           },
           "min_step_seconds": {
             "type": [
@@ -29454,7 +30530,7 @@
             "format": "int64",
             "minimum": 1,
             "maximum": 9007199254740,
-            "description": "最小步长（秒）。仅在 `mode` 为 `range` 时可用，且必须大于 0；省略或传 null 由服务端决定。"
+            "description": "最小步长（秒），必须大于 0。在排障入口中仅当 `mode` 为 `range` 时可用。省略或传 null 由服务端决定。"
           }
         },
         "required": [
@@ -29571,7 +30647,7 @@
       },
       "DashboardDefinition": {
         "type": "object",
-        "description": "以可移植 `dashboard.v1` 文档形式存储的完整仪表盘内容。未知字段、重复字段、NaN/Inf、超范围数字与尾随值都会被拒绝；序列化后不得超过 1 MiB。",
+        "description": "以可移植 `dashboard.v1` 文档形式存储的完整仪表盘内容。未知字段、重复字段、尾随值以及超过 32 层的嵌套都会被拒绝，序列化后不得超过 1 MiB。上限：10 个 tab，每个 tab 10 个 section、30 个面板、100 条查询，每个仪表盘 100 个面板、300 条查询，20 个变量。",
         "properties": {
           "title": {
             "type": "string",
@@ -29603,7 +30679,7 @@
               "$ref": "#/components/schemas/DashboardVariable"
             },
             "maxItems": 20,
-            "description": "仪表盘变量，最多 20 个。名称在定义内必须唯一且符合变量名正则。"
+            "description": "仪表盘变量，最多 20 个，名称唯一。变量之间可以相互引用，但不能形成循环。"
           },
           "tabs": {
             "type": "array",
@@ -29612,7 +30688,7 @@
             },
             "minItems": 1,
             "maxItems": 10,
-            "description": "Tab，1～10 个。标题唯一，且所有 tab/section ID 必须是整份定义内唯一的 canonical UUIDv7。"
+            "description": "Tab，1～10 个。所有 tab、section 与面板的 `id` 必须是整份定义内只出现一次的 canonical UUIDv7。Tab 标题无需唯一。"
           }
         },
         "required": [
@@ -29667,7 +30743,7 @@
             "type": "string",
             "minLength": 1,
             "maxLength": 189,
-            "description": "Tab 标题，1～189 个 Unicode 字符，在 tab 之间唯一。"
+            "description": "Tab 标题，去除首尾空白后 1～189 个 Unicode 字符。"
           },
           "description": {
             "type": "string",
@@ -29680,7 +30756,7 @@
               "$ref": "#/components/schemas/DashboardPanel"
             },
             "maxItems": 30,
-            "description": "直接放在该 tab 上的面板，最多 30 个。"
+            "description": "直接放在该 tab 上的面板。一个 tab 内顶层面板与各 section 面板合计最多 30 个，查询最多 100 条。"
           },
           "sections": {
             "type": "array",
@@ -29728,7 +30804,7 @@
               "$ref": "#/components/schemas/DashboardPanel"
             },
             "maxItems": 30,
-            "description": "该 section 内的面板，最多 30 个。"
+            "description": "该 section 内的面板；计入所在 tab 合计 30 个面板的上限。"
           }
         },
         "required": [
@@ -29740,7 +30816,7 @@
       },
       "DashboardPanel": {
         "type": "object",
-        "description": "单个可视化面板。同一容器内的面板不得重叠；24 列网格在保存时校验。",
+        "description": "单个可视化面板。除 `text` 外所有类型都必须填写 `datasource_ref`，`text` 面板不允许填写。同一容器内的面板不得重叠；24 列网格在保存时校验。",
         "properties": {
           "id": {
             "type": "string",
@@ -29835,17 +30911,18 @@
             "type": "integer",
             "format": "uint64",
             "minimum": 1,
-            "description": "数据源 ID。`kind` 为 `fixed` 时必填，为 `variable` 时禁止设置。"
+            "description": "数据源 ID。`kind` 为 `fixed` 时必填，为 `variable` 时禁止设置。",
+            "maximum": 9007199254740991
           },
           "name": {
             "type": "string",
             "pattern": "^[A-Za-z_][A-Za-z0-9_]{0,63}$",
-            "description": "数据源变量名。`kind` 为 `variable` 时必填，为 `fixed` 时禁止设置。"
+            "description": "同一份定义中某个 `datasource` 类型变量的名称。`kind` 为 `variable` 时必填，为 `fixed` 时不允许填写。"
           },
           "datasource_type": {
             "type": "string",
             "pattern": "^[a-z][a-z0-9_]{0,63}$",
-            "description": "数据源类型标识，例如 `prometheus`、`victorialogs`。"
+            "description": "数据源类型标识：以小写字母开头，由小写字母、数字和下划线组成。取值集合是开放的，保存时接受任何符合格式的值，但仪表盘运行时只支持 `prometheus`、`mysql`、`loki` 数据源；其他类型的面板在运行时会失败。`kind` 为 `variable` 时必须与所引用数据源变量的 `datasource_type` 一致。"
           }
         },
         "required": [
@@ -29868,7 +30945,7 @@
           "legend_alias": {
             "type": "string",
             "maxLength": 1024,
-            "description": "可选图例名；支持与 `expr` 相同的变量模板。"
+            "description": "可选图例名，最多 1024 个 Unicode 字符。控制台会把 `{{label}}` 替换为该序列对应标签的值（如 `{{env}} requests`）；这里不会替换仪表盘变量。"
           }
         },
         "required": [
@@ -29912,7 +30989,7 @@
           "name": {
             "type": "string",
             "pattern": "^[A-Za-z_][A-Za-z0-9_]{0,63}$",
-            "description": "在 `{{ }}` 模板中引用的变量名，最多 64 个字符。以 `__` 开头的名称保留给内置时间变量。"
+            "description": "变量名，在定义内唯一。查询中以 `${name}` 引用（在 Prometheus 与 Loki 表达式中也可写 `$name`）。以 `__` 开头的名称保留给内置变量 `__interval`、`__rate_interval`、`__range`、`__auto`。"
           },
           "label": {
             "type": "string",
@@ -29922,7 +30999,7 @@
           "datasource_type": {
             "type": "string",
             "pattern": "^[a-z][a-z0-9_]{0,63}$",
-            "description": "候选项来自的数据源类型。"
+            "description": "作为候选项的数据源类型；候选项为账户下该类型的已启用数据源。取值集合是开放的，保存时接受任何符合格式的值，但仪表盘运行时只支持 `prometheus`、`mysql`、`loki` 数据源；其他类型的面板在运行时会失败。"
           },
           "name_patterns": {
             "type": "array",
@@ -29937,7 +31014,8 @@
           "default_datasource_id": {
             "type": "integer",
             "format": "uint64",
-            "description": "默认数据源 ID。若默认值不可用，运行时按名称、再按 ID 取第一个候选项。"
+            "description": "默认数据源 ID。若默认值不可用，运行时按名称、再按 ID 取第一个候选项。",
+            "maximum": 9007199254740991
           }
         },
         "required": [
@@ -29960,7 +31038,7 @@
           "name": {
             "type": "string",
             "pattern": "^[A-Za-z_][A-Za-z0-9_]{0,63}$",
-            "description": "在 `{{ }}` 模板中引用的变量名，最多 64 个字符。以 `__` 开头的名称保留给内置时间变量。"
+            "description": "变量名，在定义内唯一。查询中以 `${name}` 引用（在 Prometheus 与 Loki 表达式中也可写 `$name`）。以 `__` 开头的名称保留给内置变量 `__interval`、`__rate_interval`、`__range`、`__auto`。"
           },
           "label": {
             "type": "string",
@@ -30004,7 +31082,7 @@
           "name": {
             "type": "string",
             "pattern": "^[A-Za-z_][A-Za-z0-9_]{0,63}$",
-            "description": "在 `{{ }}` 模板中引用的变量名，最多 64 个字符。以 `__` 开头的名称保留给内置时间变量。"
+            "description": "变量名，在定义内唯一。查询中以 `${name}` 引用（在 Prometheus 与 Loki 表达式中也可写 `$name`）。以 `__` 开头的名称保留给内置变量 `__interval`、`__rate_interval`、`__range`、`__auto`。"
           },
           "label": {
             "type": "string",
@@ -30065,7 +31143,7 @@
       },
       "DashboardSelection": {
         "type": "object",
-        "description": "变量取值的具体选择。空的 `values` 数组是合法输入，表示未解析——服务端不会为其回退到默认值。",
+        "description": "变量取值的具体选择。作为已保存变量的 `default` 时，`values` 不能为空，`single` 模式下必须恰好一个值。在运行时请求中，空的 `values` 数组是合法输入，表示未解析——服务端不会为其回退到默认值。",
         "properties": {
           "kind": {
             "type": "string",
@@ -30152,7 +31230,7 @@
           },
           "metric": {
             "type": "string",
-            "description": "可选指标名，用于限定参与计算的序列。"
+            "description": "可选的指标选择器，用于限定参与计算的序列；可通过 `${name}` 或 `$name` 引用其他变量。"
           },
           "label_filters": {
             "type": "array",
@@ -30174,7 +31252,7 @@
           "label": {
             "type": "string",
             "pattern": "^[A-Za-z_][A-Za-z0-9_:.\\-]{0,189}$",
-            "description": "标签名。"
+            "description": "要匹配的 Prometheus 标签名，如 `job`；由字母、数字、`_`、`:`、`.`、`-` 组成，以字母或 `_` 开头。"
           },
           "op": {
             "type": "string",
@@ -30189,7 +31267,7 @@
           "value": {
             "type": "string",
             "minLength": 1,
-            "description": "匹配值；可通过 `{{ }}` 引用其他变量。"
+            "description": "匹配值；可通过 `${name}` 引用其他变量。多选或含 `all` 的变量需搭配 `=~` 或 `!~`。"
           }
         },
         "required": [
@@ -30211,7 +31289,7 @@
           },
           "expr": {
             "type": "string",
-            "description": "SQL 语句；可通过 `{{ }}` 引用其他变量。"
+            "description": "其结果作为候选项的 SQL 语句。SQL 变量查询只在 MySQL 数据源上运行，而 MySQL 查询不支持引用变量。"
           },
           "args": {
             "type": "object",
@@ -30250,7 +31328,7 @@
           },
           "expr": {
             "type": "string",
-            "description": "日志查询表达式；可通过 `{{ }}` 引用其他变量。数据源为 Loki 时可为空，此时会列出该字段在所有流中的取值。"
+            "description": "日志查询表达式；可通过 `${name}` 引用其他变量。日志变量查询只在 Loki 数据源上运行，此时 `expr` 可为空，表示列出该字段在所有流中的取值。"
           },
           "args": {
             "type": "object",
@@ -30273,7 +31351,7 @@
         ]
       },
       "DashboardVizConfig": {
-        "description": "可视化配置。`kind` 决定使用哪个分支以及哪个同级的配置对象必需；`time_series` 还携带通用的数值配置。",
+        "description": "可视化配置。`kind` 决定使用哪个分支，从而决定允许哪些同级字段；`time_series`、`stat`、`bar`、`gauge` 还带有通用数值字段 `unit`、`decimals`、`threshold`。出现其他类型的字段会被拒绝。",
         "oneOf": [
           {
             "$ref": "#/components/schemas/DashboardTimeSeriesViz"
@@ -30340,7 +31418,7 @@
               "bytes_per_second",
               "bits_per_second"
             ],
-            "description": "面板数值的展示单位：`unitless` = 原始数值；`ratio` = 占比（0–1 的小数）；`percent` = 百分比；`milliseconds` = 毫秒；`seconds` = 秒；`bytes` = 字节；`bits` = 比特；`count_per_second` = 每秒计数；`bytes_per_second` = 每秒字节数；`bits_per_second` = 每秒比特数。"
+            "description": "面板数值的展示单位：`unitless` = 原始数值；`ratio` = 占比（0–1 的小数）；`percent` = 百分比；`milliseconds` = 毫秒；`seconds` = 秒；`bytes` = 字节；`bits` = 比特；`count_per_second` = 每秒计数；`bytes_per_second` = 每秒字节数；`bits_per_second` = 每秒比特数。省略时默认为 `unitless`。"
           },
           "decimals": {
             "type": [
@@ -30348,7 +31426,8 @@
               "null"
             ],
             "minimum": 0,
-            "description": "固定小数位；省略或传 null 由前端决定。"
+            "description": "固定小数位数，0～15；省略或传 null 由控制台决定。",
+            "maximum": 15
           },
           "threshold": {
             "$ref": "#/components/schemas/DashboardThreshold"
@@ -30380,15 +31459,14 @@
             "additionalProperties": {
               "$ref": "#/components/schemas/DashboardColumnOption"
             },
-            "description": "按字段名索引的列展示覆盖配置，最多 100 项。"
+            "description": "按结果字段名设置的列展示覆盖项，最多 100 项。键名不能为空，最多 1024 个 Unicode 字符，且不能是 `frame_index` 或 `field_index`。"
           },
           "sort": {
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/DashboardFieldSort"
             },
-            "maxItems": 2,
-            "description": "初始排序键；字段需唯一。"
+            "description": "初始排序键，按顺序生效；每个字段只能出现一次。"
           },
           "link_columns": {
             "type": "array",
@@ -30434,7 +31512,7 @@
               "bytes_per_second",
               "bits_per_second"
             ],
-            "description": "面板数值的展示单位：`unitless` = 原始数值；`ratio` = 占比（0–1 的小数）；`percent` = 百分比；`milliseconds` = 毫秒；`seconds` = 秒；`bytes` = 字节；`bits` = 比特；`count_per_second` = 每秒计数；`bytes_per_second` = 每秒字节数；`bits_per_second` = 每秒比特数。"
+            "description": "面板数值的展示单位：`unitless` = 原始数值；`ratio` = 占比（0–1 的小数）；`percent` = 百分比；`milliseconds` = 毫秒；`seconds` = 秒；`bytes` = 字节；`bits` = 比特；`count_per_second` = 每秒计数；`bytes_per_second` = 每秒字节数；`bits_per_second` = 每秒比特数。省略时默认为 `unitless`。"
           },
           "decimals": {
             "type": [
@@ -30442,7 +31520,8 @@
               "null"
             ],
             "minimum": 0,
-            "description": "固定小数位；省略或传 null 由前端决定。"
+            "description": "固定小数位数，0～15；省略或传 null 由控制台决定。",
+            "maximum": 15
           },
           "threshold": {
             "$ref": "#/components/schemas/DashboardThreshold"
@@ -30452,7 +31531,9 @@
             "items": {
               "type": "string"
             },
-            "description": "被归约为展示取值的字段。"
+            "description": "归约为展示值的结果字段；至少一个且不可重复。按名称精确匹配，不能是 `frame_index` 或 `field_index`。",
+            "minItems": 1,
+            "uniqueItems": true
           },
           "reducer": {
             "type": "string",
@@ -30503,7 +31584,7 @@
               "bytes_per_second",
               "bits_per_second"
             ],
-            "description": "面板数值的展示单位：`unitless` = 原始数值；`ratio` = 占比（0–1 的小数）；`percent` = 百分比；`milliseconds` = 毫秒；`seconds` = 秒；`bytes` = 字节；`bits` = 比特；`count_per_second` = 每秒计数；`bytes_per_second` = 每秒字节数；`bits_per_second` = 每秒比特数。"
+            "description": "面板数值的展示单位：`unitless` = 原始数值；`ratio` = 占比（0–1 的小数）；`percent` = 百分比；`milliseconds` = 毫秒；`seconds` = 秒；`bytes` = 字节；`bits` = 比特；`count_per_second` = 每秒计数；`bytes_per_second` = 每秒字节数；`bits_per_second` = 每秒比特数。省略时默认为 `unitless`。"
           },
           "decimals": {
             "type": [
@@ -30511,21 +31592,25 @@
               "null"
             ],
             "minimum": 0,
-            "description": "固定小数位；省略或传 null 由前端决定。"
+            "description": "固定小数位数，0～15；省略或传 null 由控制台决定。",
+            "maximum": 15
           },
           "threshold": {
             "$ref": "#/components/schemas/DashboardThreshold"
           },
           "category_field": {
             "type": "string",
-            "description": "提供类目轴的字段。"
+            "description": "提供类目轴的结果字段；必填，最多 1024 个 Unicode 字符，不能是 `frame_index` 或 `field_index`。",
+            "minLength": 1
           },
           "value_fields": {
             "type": "array",
             "items": {
               "type": "string"
             },
-            "description": "提供柱值的字段。"
+            "description": "提供柱值的结果字段；至少一个且不可重复。名称不能是 `frame_index` 或 `field_index`。",
+            "minItems": 1,
+            "uniqueItems": true
           },
           "data_link": {
             "$ref": "#/components/schemas/DashboardDataLink"
@@ -30568,7 +31653,7 @@
               "bytes_per_second",
               "bits_per_second"
             ],
-            "description": "面板数值的展示单位：`unitless` = 原始数值；`ratio` = 占比（0–1 的小数）；`percent` = 百分比；`milliseconds` = 毫秒；`seconds` = 秒；`bytes` = 字节；`bits` = 比特；`count_per_second` = 每秒计数；`bytes_per_second` = 每秒字节数；`bits_per_second` = 每秒比特数。"
+            "description": "面板数值的展示单位：`unitless` = 原始数值；`ratio` = 占比（0–1 的小数）；`percent` = 百分比；`milliseconds` = 毫秒；`seconds` = 秒；`bytes` = 字节；`bits` = 比特；`count_per_second` = 每秒计数；`bytes_per_second` = 每秒字节数；`bits_per_second` = 每秒比特数。省略时默认为 `unitless`。"
           },
           "decimals": {
             "type": [
@@ -30576,7 +31661,8 @@
               "null"
             ],
             "minimum": 0,
-            "description": "固定小数位；省略或传 null 由前端决定。"
+            "description": "固定小数位数，0～15；省略或传 null 由控制台决定。",
+            "maximum": 15
           },
           "threshold": {
             "$ref": "#/components/schemas/DashboardThreshold"
@@ -30586,7 +31672,9 @@
             "items": {
               "type": "string"
             },
-            "description": "被归约为仪表值的字段。"
+            "description": "归约为仪表值的结果字段；至少一个且不可重复。按名称精确匹配，不能是 `frame_index` 或 `field_index`。",
+            "minItems": 1,
+            "uniqueItems": true
           },
           "reducer": {
             "type": "string",
@@ -30669,7 +31757,7 @@
           "markdown": {
             "type": "string",
             "maxLength": 65536,
-            "description": "Markdown 正文，最多 64 KiB。仅限白名单节点（标题、列表、表格、链接、代码）可通过校验。"
+            "description": "Markdown 正文，最多 64 KiB。允许段落、标题、列表、引用、代码块与行内代码、强调、表格、分隔线与链接。链接必须是 `https://` 地址或以 `/` 开头的站内相对路径。图片、原始 HTML 与 `${` 模板会以 `InvalidParameter` 拒绝，而不是被过滤掉。"
           }
         },
         "required": [
@@ -30747,7 +31835,7 @@
               "bytes_per_second",
               "bits_per_second"
             ],
-            "description": "列展示单位覆盖：`unitless` = 原始数值；`ratio` = 占比（0–1 的小数）；`percent` = 百分比；`milliseconds` = 毫秒；`seconds` = 秒；`bytes` = 字节；`bits` = 比特；`count_per_second` = 每秒计数；`bytes_per_second` = 每秒字节数；`bits_per_second` = 每秒比特数。"
+            "description": "列展示单位覆盖：`unitless` = 原始数值；`ratio` = 占比（0–1 的小数）；`percent` = 百分比；`milliseconds` = 毫秒；`seconds` = 秒；`bytes` = 字节；`bits` = 比特；`count_per_second` = 每秒计数；`bytes_per_second` = 每秒字节数；`bits_per_second` = 每秒比特数。省略时默认为 `unitless`。"
           },
           "threshold": {
             "$ref": "#/components/schemas/DashboardThreshold"
@@ -30772,7 +31860,7 @@
           "field": {
             "type": "string",
             "minLength": 1,
-            "description": "排序字段名。"
+            "description": "排序依据的结果字段名；最多 1024 个 Unicode 字符，不能是 `frame_index` 或 `field_index`。"
           },
           "direction": {
             "type": "string",
@@ -30790,12 +31878,12 @@
       },
       "DashboardDataLink": {
         "type": "object",
-        "description": "从表格列或柱状图面板下钻到另一个仪表盘的链接。目标仪表盘必须存在，且映射来源需与源面板的结构匹配。",
+        "description": "从表格或柱状图面板下钻到另一个仪表盘的链接。保存时只校验 ID 格式，指向不存在仪表盘的链接也会被接受。允许的映射来源取决于源面板类型。",
         "properties": {
           "dashboard_id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "目标仪表盘 ID。"
+            "description": "要打开的仪表盘 ID；必须是 canonical UUIDv7。"
           },
           "target_id": {
             "type": "string",
@@ -30811,7 +31899,7 @@
             "additionalProperties": {
               "$ref": "#/components/schemas/DashboardLinkMapping"
             },
-            "description": "把目标变量名映射到某个来源值，例如表格列或源变量。"
+            "description": "要在目标仪表盘中设置的变量值，键为目标变量名（需符合 `^[A-Za-z_][A-Za-z0-9_]{0,63}$`）；每项说明取值来源。无映射时传 `{}`。"
           }
         },
         "required": [
@@ -30833,15 +31921,15 @@
               "series",
               "value"
             ],
-            "description": "取值来源：`variable` = 仪表盘变量；`row_column` = 表格列（必须同时给出 `column`）；`category` = 柱状图的类目；`series` = 序列名；`value` = 数值本身。`category`、`series`、`value` 仅对柱状图面板有效。"
+            "description": "取值来源：`variable` = 源仪表盘某个变量的当前值（需填 `name`），表格与柱状图面板可用；`row_column` = 被点击行在某表格列的值（需填 `column`），仅表格面板；`category` = 被点击柱的类目，`series` = 其序列名，`value` = 其数值——这三种仅柱状图面板可用，且不带额外字段。"
           },
           "column": {
             "type": "string",
-            "description": "来源列名；`source` 为 `row_column` 时必填。"
+            "description": "要读取的表格列（结果字段）；`source` 为 `row_column` 时必填，否则不允许填写。"
           },
           "name": {
             "type": "string",
-            "description": "来源仪表盘变量名；`source` 为 `variable` 时必填。"
+            "description": "要读取的源仪表盘变量；`source` 为 `variable` 时必填，且必须存在于同一份定义中；其他来源不允许填写。"
           }
         },
         "required": [
@@ -30855,11 +31943,11 @@
           "id": {
             "type": "integer",
             "format": "uint64",
-            "description": "成员 ID。"
+            "description": "执行该操作的成员 ID。"
           },
           "name": {
             "type": "string",
-            "description": "成员展示名。"
+            "description": "成员展示名，记录于操作发生时。"
           }
         },
         "required": [
@@ -30942,13 +32030,13 @@
           "dashboard_id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "仪表盘 ID。"
+            "description": "仪表盘 ID；传给 `POST /monit/dashboard/get` 可获取完整定义。"
           },
           "folder_id": {
             "type": "integer",
             "format": "uint64",
             "minimum": 1,
-            "description": "目录 ID。"
+            "description": "仪表盘所在目录的 ID。"
           },
           "folder_breadcrumb": {
             "type": "array",
@@ -30963,7 +32051,7 @@
           },
           "description": {
             "type": "string",
-            "description": "仪表盘描述；未设置时为空串。"
+            "description": "仪表盘描述；未设置时省略。"
           },
           "revision": {
             "type": "integer",
@@ -31019,7 +32107,7 @@
           "dashboard_id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "仪表盘 ID。"
+            "description": "回收站中仪表盘的 ID；可传给 `POST /monit/dashboard/restore`。"
           },
           "folder_id": {
             "type": "integer",
@@ -31040,13 +32128,13 @@
           },
           "description": {
             "type": "string",
-            "description": "仪表盘描述；未设置时为空串。"
+            "description": "仪表盘描述；未设置时省略。"
           },
           "revision": {
             "type": "integer",
             "format": "uint64",
             "minimum": 1,
-            "description": "删除时的版本号。"
+            "description": "回收站中该仪表盘的当前版本号（删除时已加 1）；恢复时作为 `expected_revision` 传入。"
           },
           "deleted_by": {
             "$ref": "#/components/schemas/DashboardActor"
@@ -31081,7 +32169,7 @@
           "total": {
             "type": "integer",
             "format": "int64",
-            "description": "已删除仪表盘总数。"
+            "description": "调用方可见的已删除仪表盘总数（跨所有分页）。"
           }
         },
         "required": [
@@ -31091,11 +32179,11 @@
       },
       "DashboardUpdateOutput": {
         "type": "object",
-        "description": "更新或移动的结果。`changed` 为 false 表示本次写入是空操作——规范化后的序列化定义与已存内容逐字节相同，此时 `resource` 仍描述该未变化的仪表盘。",
+        "description": "更新或移动的结果。`changed` 为 false 表示未做任何写入——更新时规范化后的定义与 `schema_version` 均与已存内容相同；移动时仪表盘已在目标目录中。此时 `revision` 不变，`resource` 描述未变化的仪表盘。",
         "properties": {
           "changed": {
             "type": "boolean",
-            "description": "已存储的仪表盘是否真的发生了变化。"
+            "description": "是否发生了写入并使 `revision` 加 1。"
           },
           "resource": {
             "$ref": "#/components/schemas/DashboardResource"
@@ -31113,13 +32201,13 @@
           "dashboard_id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "仪表盘 ID。"
+            "description": "已移入回收站的仪表盘 ID。"
           },
           "revision": {
             "type": "integer",
             "format": "uint64",
             "minimum": 1,
-            "description": "本次删除记录的版本号。"
+            "description": "删除后的版本号；恢复时作为 `expected_revision` 传入。"
           }
         },
         "required": [
@@ -31134,7 +32222,7 @@
           "dashboard_id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "仪表盘 ID。"
+            "description": "该版本所属的仪表盘 ID。"
           },
           "revision": {
             "type": "integer",
@@ -31151,7 +32239,7 @@
           "message": {
             "type": "string",
             "maxLength": 1024,
-            "description": "可选提交说明；最多 1024 个 Unicode 字符。"
+            "description": "调用 `POST /monit/dashboard/update` 时传入的说明；未提供时，以及创建、移动、删除、恢复产生的版本上，此字段省略。"
           },
           "actor": {
             "$ref": "#/components/schemas/DashboardActor"
@@ -31193,7 +32281,7 @@
           "dashboard_id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "仪表盘 ID。"
+            "description": "该版本所属的仪表盘 ID。"
           },
           "schema_version": {
             "type": "string",
@@ -31220,7 +32308,7 @@
           "message": {
             "type": "string",
             "maxLength": 1024,
-            "description": "可选提交说明。"
+            "description": "调用 `POST /monit/dashboard/update` 时传入的说明；未提供时省略。"
           },
           "actor": {
             "$ref": "#/components/schemas/DashboardActor"
@@ -31280,7 +32368,7 @@
           "dashboard_id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "仪表盘 ID。"
+            "description": "仪表盘 ID，与请求中传入的一致。"
           },
           "title": {
             "type": "string",
@@ -31288,7 +32376,7 @@
           },
           "description": {
             "type": "string",
-            "description": "仪表盘描述；未设置时为空串。"
+            "description": "仪表盘描述；未设置时省略。"
           },
           "revision": {
             "type": "integer",
@@ -31317,7 +32405,7 @@
             "type": "integer",
             "format": "uint64",
             "minimum": 1,
-            "description": "目录 ID。"
+            "description": "仪表盘所在目录的 ID。"
           },
           "breadcrumb": {
             "type": "array",
@@ -31343,7 +32431,7 @@
           },
           "label": {
             "type": "string",
-            "description": "展示名；未设置时为空串。"
+            "description": "展示名；未设置时省略。"
           },
           "kind": {
             "type": "string",
@@ -31370,15 +32458,15 @@
           "id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "Tab ID。"
+            "description": "Tab ID；作为 `target_id` 传入可把大纲收窄到该 tab。"
           },
           "title": {
             "type": "string",
-            "description": "Tab 标题。"
+            "description": "定义中保存的 tab 标题。"
           },
           "description": {
             "type": "string",
-            "description": "Tab 描述；未设置时为空串。"
+            "description": "Tab 描述；未设置时省略。"
           },
           "breadcrumb": {
             "type": "array",
@@ -31417,7 +32505,7 @@
           "id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "Section ID。"
+            "description": "Section ID；作为 `target_id` 传入可把大纲收窄到该 section。"
           },
           "title": {
             "type": "string",
@@ -31425,7 +32513,7 @@
           },
           "description": {
             "type": "string",
-            "description": "Section 描述；未设置时为空串。"
+            "description": "Section 描述；未设置时省略。"
           },
           "breadcrumb": {
             "type": "array",
@@ -31456,7 +32544,7 @@
           "id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "面板 ID。"
+            "description": "面板 ID；可作为 `POST /monit/dashboard/panel/run` 的 `panel_id`，或在此作为 `target_id`。"
           },
           "title": {
             "type": "string",
@@ -31464,7 +32552,7 @@
           },
           "description": {
             "type": "string",
-            "description": "面板描述；未设置时为空串。"
+            "description": "面板描述；未设置时省略。"
           },
           "breadcrumb": {
             "type": "array",
@@ -31478,7 +32566,7 @@
           },
           "datasource_type": {
             "type": "string",
-            "description": "面板查询的数据源类型；面板无数据源（text 面板）时为空串。"
+            "description": "面板 `datasource_ref` 中的数据源类型，如 `prometheus`、`mysql`、`loki`；text 面板没有数据源，此字段省略。取值集合是开放的，原样返回保存时的类型。"
           }
         },
         "required": [
@@ -31544,7 +32632,7 @@
           "dashboard_id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "仪表盘的 canonical UUIDv7。"
+            "description": "由调用方生成的小写 canonical UUIDv7，作为仪表盘的永久 ID。"
           },
           "schema_version": {
             "type": "string",
@@ -31557,7 +32645,7 @@
             "type": "integer",
             "format": "uint64",
             "minimum": 1,
-            "description": "创建到哪个目录。必须是调用方有写权限的目录。"
+            "description": "创建到哪个目录；该目录必须存在且 `app_key` 所属成员可访问，否则返回 `FolderNotFound`。"
           },
           "definition": {
             "$ref": "#/components/schemas/DashboardDefinition"
@@ -31660,7 +32748,7 @@
             "type": "integer",
             "format": "uint64",
             "minimum": 1,
-            "description": "目标目录 ID。"
+            "description": "目标目录 ID；该目录必须存在且调用方可访问，否则返回 `FolderNotFound`。"
           }
         },
         "required": [
@@ -31671,7 +32759,7 @@
       },
       "DashboardDeleteRequest": {
         "type": "object",
-        "description": "把仪表盘移入回收站。定义会保留 30 天，因此可用恢复接口撤销删除。",
+        "description": "把仪表盘移入回收站。删除 30 天后被永久清除；在此之前可用恢复接口撤销删除。",
         "properties": {
           "dashboard_id": {
             "type": "string",
@@ -31703,7 +32791,7 @@
             "type": "integer",
             "format": "uint64",
             "minimum": 1,
-            "description": "调用方最后读到的版本号。若与已存版本不一致，写入会以 `DashboardRevisionConflict` 失败。"
+            "description": "回收站中该仪表盘的当前版本号，即删除接口返回或回收站列表中显示的值。不一致时以 `DashboardRevisionConflict` 失败。"
           },
           "folder_id": {
             "type": [
@@ -31712,7 +32800,7 @@
             ],
             "format": "uint64",
             "minimum": 1,
-            "description": "目标目录。省略则恢复到原目录；当原目录已不可写时调用会以 `RestoreFolderRequired` 失败，此时必须显式指定。"
+            "description": "目标目录。省略或传 null 表示恢复到原目录；若原目录已不存在，调用会以 `RestoreFolderRequired` 失败，此时必须指定目标目录。"
           }
         },
         "required": [
@@ -31749,12 +32837,12 @@
             "type": "integer",
             "format": "uint64",
             "minimum": 1,
-            "description": "要列出仪表盘的目录。"
+            "description": "要列出其直接包含的仪表盘的目录；不包含子目录。"
           },
           "query": {
             "type": "string",
             "maxLength": 128,
-            "description": "可选空格分隔的搜索词，匹配标题与描述；最多 128 个 Unicode 字符。"
+            "description": "可选的搜索词，以空白分隔，最多 128 个 Unicode 字符。标题或描述中包含每一个词的仪表盘才会命中。"
           },
           "sort": {
             "type": "array",
@@ -31788,7 +32876,7 @@
             "type": "string",
             "minLength": 1,
             "maxLength": 128,
-            "description": "空格分隔的搜索词；至少一个单词，最多 128 个 Unicode 字符。"
+            "description": "以空白分隔的搜索词；至少一个词，最多 128 个 Unicode 字符。标题或描述中包含每一个词的仪表盘才会命中。"
           },
           "sort": {
             "type": "array",
@@ -31847,13 +32935,15 @@
             "type": "integer",
             "format": "int64",
             "minimum": 0,
-            "description": "Unix 时间戳（毫秒）。"
+            "description": "窗口起点，Unix 毫秒时间戳。须不小于 0 且小于 `to_ms`。",
+            "maximum": 9007199254740991
           },
           "to_ms": {
             "type": "integer",
             "format": "int64",
             "minimum": 1,
-            "description": "Unix 时间戳（毫秒）。"
+            "description": "窗口终点，Unix 毫秒时间戳。须大于 `from_ms`；`instant` 查询在该时间点求值。",
+            "maximum": 9007199254740991
           }
         },
         "required": [
@@ -31863,15 +32953,15 @@
       },
       "DashboardRuntimeError": {
         "type": "object",
-        "description": "变量级或查询级的失败。单个分支失败不会导致整个调用失败。",
+        "description": "单个变量或单条查询的失败。单个变量或查询失败不会导致整个调用失败。",
         "properties": {
           "reason": {
             "type": "string",
-            "description": "机器可读的失败原因。已观察到的取值包括 `invalid_request`、`variable_invalid`、`panel_missing`、`field_missing`、`datasource_permission_denied`、`timeout`、`panel_deadline`、`panel_canceled`、`canceled`、`overloaded`、`source_too_large`、`edge_unavailable`、`edge_upgrade_required`、`edge_version_unknown`、`mixed_edge_versions`、`internal`。"
+            "description": "机器可读的失败原因。取值集合是开放的，当前有：\n- `invalid_request`：查询或数据源配置被拒绝（数据源类型或查询模式不受支持、不允许 `args` 的地方传了参数、参数格式错误）。\n- `variable_invalid`：变量无法使用（既无选择也无默认值、所选值不在候选项中、依赖项未解析、替换出错、候选项列表不可用）。\n- `panel_missing`：面板不在该仪表盘中（仅出现在查询解析接口）。\n- `datasource_permission_denied`：数据源不存在、已停用、调用方无权访问，或没有可访问的数据源匹配该变量。\n- `field_missing`、`value_not_scalar`、`empty_field_name`、`duplicate_field_name`、`field_type_changed`：结果与面板可视化不匹配，或 SQL 变量查询返回了不可用的列。\n- `timeout`：数据源调用超时；`panel_deadline`：运行触达 35 秒总时限。\n- `canceled`、`panel_canceled`：调用被取消。\n- `overloaded`：数据源一侧正在限流。\n- `too_many_rows`、`result_too_large`、`source_too_large`：超出行数、大小或候选项数量上限。\n- `edge_unavailable`、`no_active_edge`、`edge_upgrade_required`、`edge_version_unknown`、`mixed_edge_versions`：数据源所属的 Edge 集群未连接、版本过旧、版本未知或版本混用。\n- `internal`：服务端意外错误。"
           },
           "message": {
             "type": "string",
-            "description": "失败的可读详情。"
+            "description": "面向展示和排查的可读详情；措辞不保证稳定，请勿据此解析。"
           }
         },
         "required": [
@@ -31881,18 +32971,18 @@
       },
       "DashboardRuntimeDatasource": {
         "type": "object",
-        "description": "运行时查询实际绑定的数据源。",
+        "description": "运行时变量或查询实际绑定的数据源。",
         "properties": {
           "id": {
             "type": "integer",
             "format": "uint64",
             "minimum": 1,
-            "description": "数据源 ID。"
+            "description": "数据源 ID，与数据源列表接口返回的一致。"
           },
           "type": {
             "type": "string",
             "pattern": "^[a-z][a-z0-9_]{0,63}$",
-            "description": "数据源类型标识。"
+            "description": "数据源类型标识。已解析的查询和 `query` 变量只会是 `prometheus`、`mysql` 或 `loki`；`datasource` 变量选中的数据源可以是该变量所配置的任意类型标识。"
           },
           "name": {
             "type": "string",
@@ -31907,12 +32997,12 @@
       },
       "DashboardResolvedVariable": {
         "type": "object",
-        "description": "单个已解析变量。数据源不可达、表达式错误或结果为空时，`candidates` 会不完整并填充 `error`，而不是让请求整体失败。",
+        "description": "单个已解析变量。出现失败（既无选择也无默认值、所选值不在候选项中、依赖项未解析、数据源不可达、查询结果不可用）时，会填充 `error` 并省略 `selection`，而不是让请求整体失败。",
         "properties": {
           "name": {
             "type": "string",
             "pattern": "^[A-Za-z_][A-Za-z0-9_]{0,63}$",
-            "description": "变量名。"
+            "description": "变量名，与仪表盘或草稿中的定义一致。"
           },
           "kind": {
             "type": "string",
@@ -31928,7 +33018,7 @@
             "items": {
               "$ref": "#/components/schemas/DashboardCandidate"
             },
-            "description": "解析出的候选项，最多 1000 个。"
+            "description": "可选项，最多 1000 个；没有候选项或解析失败时为空数组。顺序：`custom` 保持定义顺序，`datasource` 按名称再按 ID 排序，`query` 按值排序。"
           },
           "selection": {
             "$ref": "#/components/schemas/DashboardSelection"
@@ -31963,13 +33053,13 @@
             "additionalProperties": {
               "$ref": "#/components/schemas/DashboardSelection"
             },
-            "description": "已做出的选择，按变量名索引，最多 20 项。未在此给出的变量回退到其存储的默认值。"
+            "description": "已做出的选择，按变量名索引，最多 20 项。未给出的变量回退到其存储的默认值；出现仪表盘未定义的变量名时，调用以 HTTP 400 失败。",
+            "maxProperties": 20
           }
         },
         "required": [
           "dashboard_id",
-          "time",
-          "variables"
+          "time"
         ]
       },
       "DashboardVariablesResolveResponse": {
@@ -31979,7 +33069,7 @@
           "dashboard_id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "仪表盘 ID。"
+            "description": "变量所属的仪表盘 ID，与请求一致。"
           },
           "revision": {
             "type": "integer",
@@ -32016,7 +33106,7 @@
           "ref_id": {
             "type": "string",
             "pattern": "^[A-Z]$",
-            "description": "面板内的查询引用名。"
+            "description": "面板内的查询引用名：单个字母 `A`–`Z`。"
           },
           "datasource": {
             "$ref": "#/components/schemas/DashboardRuntimeDatasource"
@@ -32028,27 +33118,24 @@
               "instant",
               "window"
             ],
-            "description": "求值模式：`range` = 按步长采样的时序；`instant` = 单个时间点；`window` = 有界时间窗口内的原始行。"
+            "description": "求值模式：`range` = 按步长采样的时序；`instant` = 单个时间点；`window` = 有界时间窗口内的行。Prometheus、Loki 查询使用 `range` 或 `instant`；MySQL 查询使用 `window`。"
           },
           "expr": {
             "type": "string",
-            "description": "已完成变量替换的表达式。"
+            "description": "已完成变量替换的表达式。请求中 `preserve_builtin_variables` 为 `true` 时，内置时间变量原样保留。"
           },
           "args": {
             "type": "object",
             "additionalProperties": {
               "type": "string"
             },
-            "description": "查询参数；无参数时为空对象。"
+            "description": "查询参数；无参数时为空对象。只有 Loki 查询带参数：`loki.limit`（1～1000 的十进制整数，日志条数上限）和 `loki.direction`（`latest` 或 `earliest`）。"
           },
           "min_step_seconds": {
-            "type": [
-              "integer",
-              "null"
-            ],
+            "type": "integer",
             "format": "int64",
             "minimum": 1,
-            "description": "最小步长（秒）；未设置时为 null。"
+            "description": "面板查询设置的最小步长（秒）；未设置时不返回。"
           }
         },
         "required": [
@@ -32061,12 +33148,12 @@
       },
       "DashboardResolvedPanelQueries": {
         "type": "object",
-        "description": "单个面板的解析结果。所有查询都成功时 `state` 为 `success`，部分成功为 `partial`，全部失败为 `error`。",
+        "description": "单个面板的解析结果。所有查询都成功时 `state` 为 `success`，部分成功为 `partial`，全部失败为 `error`。`error` 只描述第一个失败。",
         "properties": {
           "panel_id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "面板 ID。"
+            "description": "面板 ID，与 `panel_ids` 中的某一项一致。"
           },
           "state": {
             "type": "string",
@@ -32075,14 +33162,14 @@
               "partial",
               "error"
             ],
-            "description": "该面板查询的整体状态：`success` = 全部查询解析成功；`partial` = 部分成功；`error` = 全部失败。"
+            "description": "该面板查询的解析状态：`success` = 全部查询解析成功；`partial` = 部分成功、部分失败；`error` = 全部失败，包括面板不存在的情况。"
           },
           "queries": {
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/DashboardResolvedQuery"
             },
-            "description": "解析成功的查询。"
+            "description": "解析成功的查询，顺序与面板中的查询一致。失败的查询不出现；全部失败时为空数组。"
           },
           "error": {
             "$ref": "#/components/schemas/DashboardRuntimeError"
@@ -32121,7 +33208,8 @@
             "additionalProperties": {
               "$ref": "#/components/schemas/DashboardSelection"
             },
-            "description": "按变量名索引的选择，最多 20 项。"
+            "description": "按变量名索引的选择，最多 20 项。未给出的变量回退到存储的默认值；出现仪表盘未定义的变量名时，调用以 HTTP 400 失败。",
+            "maxProperties": 20
           },
           "max_data_points": {
             "type": [
@@ -32130,7 +33218,7 @@
             ],
             "minimum": 2,
             "maximum": 5000,
-            "description": "用于计算 step 并渲染内置时间变量的降采样目标，2～5000 个点；省略或传 null 时服务端默认 100。"
+            "description": "每条序列的目标最大点数，用于计算步长并渲染内置时间变量。取值 2～5000；省略或传 null 时默认 100。"
           },
           "preserve_builtin_variables": {
             "type": "boolean",
@@ -32140,18 +33228,17 @@
         "required": [
           "dashboard_id",
           "panel_ids",
-          "time",
-          "variables"
+          "time"
         ]
       },
       "DashboardQueriesResolveResponse": {
         "type": "object",
-        "description": "每个请求的面板对应一个条目，顺序与请求一致。",
+        "description": "所请求面板的已解析查询，以及解析时采用的生效变量选择。不会执行任何查询。",
         "properties": {
           "dashboard_id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "仪表盘 ID。"
+            "description": "查询所依据的仪表盘 ID，与请求一致。"
           },
           "revision": {
             "type": "integer",
@@ -32167,14 +33254,14 @@
             "additionalProperties": {
               "$ref": "#/components/schemas/DashboardSelection"
             },
-            "description": "解析成功的变量选择。"
+            "description": "解析成功的变量的生效选择，按变量名索引；解析失败的变量不出现。"
           },
           "panels": {
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/DashboardResolvedPanelQueries"
             },
-            "description": "每个面板的结果。"
+            "description": "每个请求的面板对应一个条目，顺序与请求一致。"
           }
         },
         "required": [
@@ -32192,12 +33279,12 @@
           "max_concurrency": {
             "type": "integer",
             "minimum": 1,
-            "description": "该面板查询的并发上限。"
+            "description": "该面板同时执行的查询数上限；固定为 6。"
           },
           "execution_count": {
             "type": "integer",
             "minimum": 0,
-            "description": "发起的查询数量。"
+            "description": "解析成功并被派发执行的查询数量；解析失败的查询不计入。"
           }
         },
         "required": [
@@ -32207,12 +33294,12 @@
       },
       "DashboardPanelRunRef": {
         "type": "object",
-        "description": "面板运行中单条查询的结果。原始执行载荷随数据源类型而异且原样透传，因此此处不做 schema 约束。",
+        "description": "面板运行或预览中单条查询的结果。原始执行载荷随数据源类型而异且原样透传，因此此处不做 schema 约束。",
         "properties": {
           "ref_id": {
             "type": "string",
             "pattern": "^[A-Z]$",
-            "description": "面板内的查询引用名。"
+            "description": "面板内的查询引用名：单个字母 `A`–`Z`，与面板 `queries` 中的设置一致。"
           },
           "state": {
             "type": "string",
@@ -32221,16 +33308,16 @@
               "error",
               "incompatible"
             ],
-            "description": "单条查询的执行状态：`success` = 查询执行成功；`error` = 查询执行失败；`incompatible` = 数据源接受了调用，但查询模式或字段选择与该数据源类型不匹配。"
+            "description": "单条查询的状态：`success` = 查询已执行，且带有 `execution`；`error` = 查询无法解析或执行，或运行被取消、超时，原因见 `error`；`incompatible` = 查询已执行，但结果与面板可视化不匹配（例如配置的字段缺失或不是数值），此时仍带有 `execution`，`error` 说明不匹配的原因。"
           },
           "child_request_id": {
             "type": "string",
-            "description": "底层数据源执行的请求 ID；排查单条查询时可用。"
+            "description": "底层数据源执行的请求 ID；排查单条查询时可用。查询没有到达数据源时不返回。"
           },
           "execution": {
             "type": "object",
             "additionalProperties": true,
-            "description": "数据源专属的执行载荷，原样透传。"
+            "description": "数据源专属的执行结果，原样透传。`state` 为 `success` 或 `incompatible` 时存在，`error` 时不返回。"
           },
           "error": {
             "$ref": "#/components/schemas/DashboardRuntimeError"
@@ -32243,7 +33330,7 @@
       },
       "DashboardPanelRunRequest": {
         "type": "object",
-        "description": "对已存仪表盘执行某个面板。省略 `revision` 表示按当前版本运行；传入它可拒绝过期响应。",
+        "description": "执行已存仪表盘的某个面板。省略 `revision`（或传 0）表示按当前版本运行；传入它可让过期调用被拒绝。文本面板不能运行。",
         "properties": {
           "dashboard_id": {
             "type": "string",
@@ -32253,13 +33340,12 @@
           "panel_id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "要执行的面板。"
+            "description": "要执行的面板 ID。必须属于该仪表盘，否则返回 `TargetNotFound`（HTTP 404）。"
           },
           "revision": {
             "type": "integer",
             "format": "uint64",
-            "minimum": 1,
-            "description": "版本护栏；设置时必须等于当前版本号。"
+            "description": "版本护栏。设置（非 0）时必须等于仪表盘当前版本号，否则以 `DashboardRevisionConflict`（HTTP 409）失败。省略或传 0 表示不校验。"
           },
           "time": {
             "$ref": "#/components/schemas/DashboardAbsoluteTimeRange"
@@ -32269,7 +33355,8 @@
             "additionalProperties": {
               "$ref": "#/components/schemas/DashboardSelection"
             },
-            "description": "按变量名索引的选择，最多 20 项。"
+            "description": "按变量名索引的选择，最多 20 项。未给出的变量回退到存储的默认值；出现仪表盘未定义的变量名时，调用以 HTTP 400 失败。",
+            "maxProperties": 20
           },
           "max_data_points": {
             "type": [
@@ -32278,29 +33365,28 @@
             ],
             "minimum": 2,
             "maximum": 5000,
-            "description": "降采样目标，2～5000 个点；省略或传 null 时服务端默认 100。"
+            "description": "`range` 查询每条序列的目标最大点数，服务端据此推算查询步长。取值 2～5000；省略或传 null 时默认 100。"
           }
         },
         "required": [
           "dashboard_id",
           "panel_id",
-          "time",
-          "variables"
+          "time"
         ]
       },
       "DashboardPanelRunResponse": {
         "type": "object",
-        "description": "面板执行结果。`run_state` 汇总各查询状态：全部成功为 `success`，部分成功为 `partial`，否则为 `incompatible`、`cancelled` 或 `error`。整个响应上限 8 MiB。",
+        "description": "面板执行结果。即使所有查询都失败也返回 HTTP 200，请查看 `run_state` 以及各 ref 的 `state`、`error`。响应超过 8 MiB 时以 `EntityTooLarge`（HTTP 413）拒绝，而不会截断。",
         "properties": {
           "dashboard_id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "仪表盘 ID。"
+            "description": "被运行的仪表盘 ID，与请求一致。"
           },
           "panel_id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "面板 ID。"
+            "description": "被运行的面板 ID，与请求一致。"
           },
           "revision": {
             "type": "integer",
@@ -32317,7 +33403,7 @@
               "cancelled",
               "error"
             ],
-            "description": "本次运行的整体状态：`success` = 全部查询成功；`partial` = 部分成功；`incompatible` = 至少一条查询与其数据源类型不兼容；`cancelled` = 运行被取消；`error` = 全部查询失败。"
+            "description": "本次运行的整体状态：`success` = 全部查询成功；`partial` = 至少一个查询成功且至少一个未成功；`cancelled` = 没有查询成功，且客户端取消了请求；`incompatible` = 没有查询成功，且至少一个查询已执行但结果与面板可视化不匹配；`error` = 没有查询成功且没有 `incompatible`（面板没有查询时也是 `error`）。"
           },
           "time": {
             "$ref": "#/components/schemas/DashboardAbsoluteTimeRange"
@@ -32327,14 +33413,14 @@
             "additionalProperties": {
               "$ref": "#/components/schemas/DashboardSelection"
             },
-            "description": "解析成功的变量选择。"
+            "description": "解析成功的变量的生效选择，按变量名索引；解析失败的变量不出现。"
           },
           "refs": {
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/DashboardPanelRunRef"
             },
-            "description": "面板中每条查询对应一个条目。"
+            "description": "面板中每条查询对应一个条目，顺序与面板中的查询一致。解析失败的查询以 `state` 为 `error` 出现。"
           },
           "display": {
             "$ref": "#/components/schemas/DashboardVizConfig"
@@ -32370,13 +33456,13 @@
           "dashboard_id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "`existing` 时必填，`new` 时禁止设置。"
+            "description": "`existing` 时必填，`new` 时禁止设置。调用方须能访问该仪表盘所在目录。"
           },
           "folder_id": {
             "type": "integer",
             "format": "uint64",
             "minimum": 1,
-            "description": "`new` 时必填，`existing` 时禁止设置。"
+            "description": "`new` 时必填，`existing` 时禁止设置。须是调用方可访问的目录，否则返回 `FolderNotFound`（HTTP 404）。"
           }
         },
         "required": [
@@ -32396,14 +33482,15 @@
               "$ref": "#/components/schemas/DashboardVariable"
             },
             "maxItems": 20,
-            "description": "草稿变量，最多 20 个。"
+            "description": "草稿变量，最多 20 个。按与已存定义相同的规则校验（名称、依赖、选项上限），且不得超过 1 MiB。"
           },
           "selections": {
             "type": "object",
             "additionalProperties": {
               "$ref": "#/components/schemas/DashboardSelection"
             },
-            "description": "按变量名索引的选择，最多 20 项。"
+            "description": "按变量名索引的选择，最多 20 项。未给出的变量回退到其草稿默认值；出现不在 `variables` 中的变量名时，调用以 HTTP 400 失败。",
+            "maxProperties": 20
           },
           "time": {
             "$ref": "#/components/schemas/DashboardAbsoluteTimeRange"
@@ -32412,7 +33499,6 @@
         "required": [
           "context",
           "variables",
-          "selections",
           "time"
         ]
       },
@@ -32425,14 +33511,14 @@
             "items": {
               "$ref": "#/components/schemas/DashboardResolvedVariable"
             },
-            "description": "已解析的变量。"
+            "description": "已解析的变量，顺序与草稿 `variables` 一致。"
           },
           "selections": {
             "type": "object",
             "additionalProperties": {
               "$ref": "#/components/schemas/DashboardSelection"
             },
-            "description": "按变量名索引的生效选择。"
+            "description": "按变量名索引的生效选择；只包含解析成功的变量。"
           }
         },
         "required": [
@@ -32442,7 +33528,7 @@
       },
       "DashboardPanelPreviewRequest": {
         "type": "object",
-        "description": "内联执行一个草稿面板，不会产生仪表盘新版本。同样受 1 MiB 定义体积上限约束。",
+        "description": "内联执行一个草稿面板，不会产生仪表盘新版本。草稿 `panel` 与 `variables` 合计不得超过 1 MiB，请求体不得超过 2 MiB。",
         "properties": {
           "context": {
             "$ref": "#/components/schemas/DashboardDraftContext"
@@ -32456,14 +33542,15 @@
               "$ref": "#/components/schemas/DashboardVariable"
             },
             "maxItems": 20,
-            "description": "该面板可能引用的草稿变量。"
+            "description": "该面板可引用的草稿变量，最多 20 个。必填；面板查询只能使用此处列出的变量。"
           },
           "selections": {
             "type": "object",
             "additionalProperties": {
               "$ref": "#/components/schemas/DashboardSelection"
             },
-            "description": "按变量名索引的选择。"
+            "description": "按变量名索引的选择，最多 20 项。未给出的变量回退到其草稿中的默认值。",
+            "maxProperties": 20
           },
           "time": {
             "$ref": "#/components/schemas/DashboardAbsoluteTimeRange"
@@ -32475,25 +33562,24 @@
             ],
             "minimum": 2,
             "maximum": 5000,
-            "description": "降采样目标，2～5000 个点。"
+            "description": "`range` 查询每条序列的目标最大点数，服务端据此推算查询步长。取值 2～5000；省略或传 null 时默认 100。"
           }
         },
         "required": [
           "context",
           "panel",
           "variables",
-          "selections",
           "time"
         ]
       },
       "DashboardPanelPreviewResponse": {
         "type": "object",
-        "description": "草稿面板执行结果。与已存面板运行结构相同，只是不含仪表盘标识。",
+        "description": "草稿面板执行结果。与已存面板运行结构相同，只是不含 `dashboard_id` 和 `revision`。即使所有查询都失败也返回 HTTP 200；响应超过 8 MiB 时以 `EntityTooLarge`（HTTP 413）拒绝。",
         "properties": {
           "panel_id": {
             "type": "string",
             "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-            "description": "面板 ID。"
+            "description": "草稿面板的 ID，与请求中的 `panel.id` 相同。"
           },
           "run_state": {
             "type": "string",
@@ -32504,7 +33590,7 @@
               "cancelled",
               "error"
             ],
-            "description": "本次运行的整体状态：`success` = 全部查询成功；`partial` = 部分成功；`incompatible` = 至少一条查询与其数据源类型不兼容；`cancelled` = 运行被取消；`error` = 全部查询失败。"
+            "description": "本次运行的整体状态：`success` = 全部查询成功；`partial` = 至少一个查询成功且至少一个未成功；`cancelled` = 没有查询成功，且客户端取消了请求；`incompatible` = 没有查询成功，且至少一个查询已执行但结果与面板可视化不匹配；`error` = 没有查询成功且没有 `incompatible`（面板没有查询时也是 `error`）。"
           },
           "time": {
             "$ref": "#/components/schemas/DashboardAbsoluteTimeRange"
@@ -32514,14 +33600,14 @@
             "additionalProperties": {
               "$ref": "#/components/schemas/DashboardSelection"
             },
-            "description": "解析成功的变量选择。"
+            "description": "解析成功的变量的生效选择，按变量名索引；解析失败的变量不出现。"
           },
           "refs": {
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/DashboardPanelRunRef"
             },
-            "description": "面板中每条查询对应一个条目。"
+            "description": "面板中每条查询对应一个条目，顺序与面板中的查询一致。解析失败的查询以 `state` 为 `error` 出现。"
           },
           "display": {
             "$ref": "#/components/schemas/DashboardVizConfig"
@@ -32542,12 +33628,12 @@
       },
       "FolderItem": {
         "type": "object",
-        "description": "监控节点（目录）。目录构成树；`parent_path` 是以逗号分隔的祖先 ID 列表，调用方可据此在客户端重建树并自行搜索。",
+        "description": "监控文件夹。文件夹构成一棵树；`parent_path` 是以逗号分隔的祖先 ID 列表，调用方可据此重建树并在客户端搜索。",
         "properties": {
           "id": {
             "type": "integer",
             "format": "uint64",
-            "description": "目录 ID。"
+            "description": "文件夹 ID。更新、移动、删除该文件夹时作为 `id` 传入；在其下嵌套文件夹时作为 `parent_id` 或 `dest_parent_id`；告警规则和仪表盘上的 `folder_id` 也使用该值。"
           },
           "account_id": {
             "type": "integer",
@@ -32566,7 +33652,7 @@
           "team_id": {
             "type": "integer",
             "format": "uint64",
-            "description": "目录归属的团队；账户级时为 0。"
+            "description": "文件夹所属团队的 ID；未归属任何团队时为 0。团队成员可以查看和修改该文件夹。"
           },
           "name": {
             "type": "string",
@@ -32579,7 +33665,7 @@
           "creator_id": {
             "type": "integer",
             "format": "uint64",
-            "description": "创建者成员 ID。"
+            "description": "创建者的成员 ID；创建者始终可以查看和修改该文件夹。"
           },
           "creator_name": {
             "type": "string",
@@ -32588,7 +33674,7 @@
           "updater_id": {
             "type": "integer",
             "format": "uint64",
-            "description": "最后更新者成员 ID。"
+            "description": "最后更新人的成员 ID。更新和移动都会写入该值。"
           },
           "updater_name": {
             "type": "string",
@@ -32597,12 +33683,12 @@
           "created_at": {
             "type": "integer",
             "format": "int64",
-            "description": "Unix 时间戳（秒）。"
+            "description": "创建时间，Unix 时间戳，单位秒。"
           },
           "updated_at": {
             "type": "integer",
             "format": "int64",
-            "description": "Unix 时间戳（秒）。"
+            "description": "最后一次更新或移动的时间，Unix 时间戳，单位秒。"
           }
         },
         "required": [
@@ -32651,7 +33737,7 @@
           },
           "category": {
             "type": "string",
-            "description": "按分类过滤，支持逗号分隔多个值，例如 `event.alert,event.change`。"
+            "description": "按大类过滤，多个值用逗号分隔。取值：`event.alert`（告警事件）、`event.change`（变更事件）、`im`（IM 机器人）、`webhook`（自定义 Webhook）。未知值不会报错，但匹配不到结果。"
           },
           "asc": {
             "type": [
@@ -32677,7 +33763,7 @@
         "properties": {
           "plugin_type": {
             "type": "string",
-            "description": "创建集成时作为 `plugin_type` 传入的类型标识。",
+            "description": "创建集成时作为 `plugin_type` 传入的类型标识，如 `standard.alert`、`prometheus.alert`、`zabbix.alert`、`feishu`。类型会随新集成增加，完整列表以本接口返回为准。",
             "example": "standard.alert"
           },
           "plugin_type_name": {
@@ -32701,7 +33787,11 @@
           },
           "status": {
             "type": "string",
-            "description": "该类型在平台侧的状态。"
+            "description": "该类型的平台状态：`enabled` 可正常使用；`disabled` 表示平台已停用该类型，`POST /integration/create` 与 `POST /integration/update` 会返回 `InvalidParameter`。",
+            "enum": [
+              "enabled",
+              "disabled"
+            ]
           },
           "supports_api_create": {
             "type": "boolean",
@@ -32771,23 +33861,23 @@
           },
           "category": {
             "type": "string",
-            "description": "按分类过滤，支持逗号分隔多个值。"
+            "description": "按大类过滤，多个值用逗号分隔。取值：`event.alert`（告警事件）、`event.change`（变更事件）、`im`（IM 机器人）、`webhook`（自定义 Webhook）。未知值不会报错，但匹配不到结果。"
           },
           "type": {
             "type": "string",
-            "description": "已废弃；与 `plugin_type` 同时传入时会合并生效。"
+            "description": "已弃用，等同于 `plugin_type`（逗号分隔的类型标识，如 `prometheus.alert`、`zabbix.alert`）。同时传入 `plugin_type` 时忽略本字段。"
           },
           "plugin_type": {
             "type": "string",
-            "description": "按集成类型过滤，支持逗号分隔多个值。"
+            "description": "按集成类型过滤，多个值用逗号分隔，如 `standard.alert,prometheus.alert`；取值为 `POST /integration/type/list` 返回的 `plugin_type`。"
           },
           "status": {
             "type": "string",
-            "description": "按状态过滤，支持逗号分隔多个值。"
+            "description": "按状态过滤，多个值用逗号分隔：`enabled`（接收事件）、`disabled`（已暂停）。"
           },
           "name": {
             "type": "string",
-            "description": "按集成名称过滤。"
+            "description": "按集成名称过滤，名称包含该文本即匹配。"
           },
           "ref_ids": {
             "type": "array",
@@ -32845,7 +33935,7 @@
           "integration_id": {
             "type": "integer",
             "format": "int64",
-            "description": "集成 ID。"
+            "description": "集成 ID，可作为 `integration_id` 传给其他 `/integration/*` 接口。"
           },
           "team_id": {
             "type": "integer",
@@ -32997,7 +34087,7 @@
             "type": "integer",
             "format": "int64",
             "minimum": 1,
-            "description": "集成 ID。",
+            "description": "公共集成 ID，可从 `POST /integration/list` 获取。ID 不存在或属于协作空间专属集成时返回 `ResourceNotFound`。",
             "example": 6113996590131
           }
         }
@@ -33030,7 +34120,7 @@
           "integration_id": {
             "type": "integer",
             "format": "int64",
-            "description": "集成 ID。"
+            "description": "集成 ID，可作为 `integration_id` 传给其他 `/integration/*` 接口。"
           },
           "team_id": {
             "type": "integer",
@@ -33242,7 +34332,7 @@
             "type": "integer",
             "format": "int64",
             "minimum": 1,
-            "description": "集成 ID。",
+            "description": "公共集成 ID，可从 `POST /integration/list` 获取。ID 不存在或属于协作空间专属集成时返回 `ResourceNotFound`。",
             "example": 6113996590131
           },
           "name": {
@@ -33293,7 +34383,7 @@
             "type": "integer",
             "format": "int64",
             "minimum": 1,
-            "description": "集成 ID。",
+            "description": "公共集成 ID，可从 `POST /integration/list` 获取。ID 不存在或属于协作空间专属集成时返回 `ResourceNotFound`。",
             "example": 6113996590131
           }
         }
@@ -33314,26 +34404,26 @@
       },
       "FolderCreateRequest": {
         "type": "object",
-        "description": "监控目录请求。",
+        "description": "创建监控文件夹的请求。",
         "properties": {
           "name": {
             "type": "string",
-            "description": "目录名称；不能包含句点、斜杠或逗号。",
+            "description": "文件夹名称；必填，不能包含句点（`.`）、斜杠（`/`）或逗号（`,`）。",
             "minLength": 1
           },
           "note": {
             "type": "string",
-            "description": "备注；更新时省略或传空字符串会清空备注。"
+            "description": "自由格式的备注。省略时为空。"
           },
           "parent_id": {
             "type": "integer",
-            "description": "父目录 ID；0 或省略时创建顶层目录。",
+            "description": "父文件夹 ID；为 0 或省略时创建根文件夹。调用方必须有权修改该父文件夹。",
             "format": "uint64",
             "minimum": 0
           },
           "team_id": {
             "type": "integer",
-            "description": "团队 ID；0 表示账户范围。更新时省略会重置为 0。",
+            "description": "文件夹所属团队的 ID；为 0 或省略表示不归属任何团队。团队成员可以查看和修改该文件夹及其下的全部内容。",
             "format": "uint64",
             "minimum": 0
           }
@@ -33344,26 +34434,26 @@
       },
       "FolderUpdateRequest": {
         "type": "object",
-        "description": "监控目录请求。",
+        "description": "更新监控文件夹的请求。可编辑字段会整体替换。",
         "properties": {
           "id": {
             "type": "integer",
-            "description": "目录 ID。",
+            "description": "要更新的文件夹 ID，来自 `/monit/folder/list` 或创建响应。",
             "format": "uint64",
             "minimum": 1
           },
           "name": {
             "type": "string",
-            "description": "目录名称；不能包含句点、斜杠或逗号。",
+            "description": "新的文件夹名称；必填，不能包含句点（`.`）、斜杠（`/`）或逗号（`,`）。",
             "minLength": 1
           },
           "note": {
             "type": "string",
-            "description": "备注；更新时省略或传空字符串会清空备注。"
+            "description": "新的备注。省略或为空会清空备注。"
           },
           "team_id": {
             "type": "integer",
-            "description": "团队 ID；0 表示账户范围。更新时省略会重置为 0。",
+            "description": "新的团队 ID；为 0 或省略会移除团队归属。",
             "format": "uint64",
             "minimum": 0
           }
@@ -33375,17 +34465,17 @@
       },
       "FolderMoveRequest": {
         "type": "object",
-        "description": "监控目录请求。",
+        "description": "移动监控文件夹及其后代的请求。",
         "properties": {
           "id": {
             "type": "integer",
-            "description": "目录 ID。",
+            "description": "要移动的文件夹 ID，来自 `/monit/folder/list`。",
             "format": "uint64",
             "minimum": 1
           },
           "dest_parent_id": {
             "type": "integer",
-            "description": "目标父目录 ID；移至顶层时必须显式传 0。",
+            "description": "新的父文件夹 ID；传 0 表示移至根级别。该字段不能省略。不能等于 `id`，也不能是该文件夹的后代。",
             "format": "uint64",
             "minimum": 0
           }
@@ -33397,11 +34487,11 @@
       },
       "FolderDeleteRequest": {
         "type": "object",
-        "description": "监控目录请求。",
+        "description": "删除监控文件夹的请求。",
         "properties": {
           "id": {
             "type": "integer",
-            "description": "目录 ID。",
+            "description": "要删除的文件夹 ID，来自 `/monit/folder/list`。该文件夹必须为空。",
             "format": "uint64",
             "minimum": 1
           }
@@ -33416,13 +34506,13 @@
         "properties": {
           "folder_id": {
             "type": "integer",
-            "description": "目录 ID。",
+            "description": "该项所描述的文件夹 ID，与 `/monit/folder/list` 中的 `id` 对应。",
             "format": "uint64",
             "minimum": 0
           },
           "has_issue": {
             "type": "boolean",
-            "description": "本目录或可见后代目录是否存在活跃告警或规则运行问题。"
+            "description": "文件夹自身或任一后代文件夹中的规则存在活跃告警或运行问题（`runtime_state` 为 `offline`、`abnormal`、`stale` 或 `no_datasource`）时为 `true`。调用方不可读文件夹中的规则不计入。"
           }
         },
         "required": [
@@ -33436,7 +34526,7 @@
         "properties": {
           "items": {
             "type": "array",
-            "description": "目录摘要列表。",
+            "description": "调用方可见的每个文件夹对应一项健康摘要，按 `folder_id` 升序排列。",
             "items": {
               "$ref": "#/components/schemas/FolderHealthItem"
             }
@@ -33449,15 +34539,10 @@
     },
     "securitySchemes": {
       "AppKeyAuth": {
-        "description": "在 Flashduty 控制台 账户 → APP Key 中签发的 app_key。调用任何公开 API 时都必须携带。它等同于所属账户的身份凭证，请妥善保管。",
+        "type": "apiKey",
         "in": "query",
         "name": "app_key",
-        "type": "apiKey"
-      },
-      "AutomationTriggerBearerAuth": {
-        "description": "自动化 HTTP POST 触发器生成的一次性 Bearer Token。不要把它当作 app_key 使用。",
-        "scheme": "bearer",
-        "type": "http"
+        "description": "在 Flashduty 控制台 我的 → APP Key 中创建的 APP Key。可通过 query 参数 `app_key` 或请求头 `Fd-App-Key` 传入。实际可访问范围是该 APP Key 的权限范围与创建者当前角色权限的交集，请妥善保管。"
       }
     }
   },
@@ -33470,67 +34555,76 @@
   "paths": {
     "/account/info": {
       "post": {
+        "summary": "查看主体信息",
         "description": "返回当前主体（账户）的基本信息与设置。",
         "operationId": "account-read-info",
+        "tags": [
+          "平台/账户设置"
+        ],
+        "security": [
+          {
+            "AppKeyAuth": []
+          }
+        ],
         "requestBody": {
           "content": {
             "application/json": {
-              "example": {},
               "schema": {
                 "type": "object"
-              }
+              },
+              "example": {}
             }
           }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/AccountInfo"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "account_id": 1001,
                     "account_name": "acme",
-                    "avatar": "https://cdn.flashcat.cloud/avatar/acme.png",
-                    "country_code": "CN",
-                    "created_at": 1716960000,
                     "domain": "acme",
-                    "email": "ops@acme.example",
                     "extra_domains": [
                       "acme-corp"
                     ],
-                    "locale": "zh-CN",
                     "phone": "138****8000",
+                    "country_code": "CN",
+                    "email": "ops@acme.example",
+                    "avatar": "https://example.com/avatar/acme.png",
+                    "locale": "zh-CN",
+                    "time_zone": "Asia/Shanghai",
+                    "created_at": 1716960000,
                     "restrictions": {
-                      "allow_subdomain": true,
+                      "ips": [
+                        "203.0.113.0/24"
+                      ],
                       "email_domains": [
                         "acme.example"
                       ],
-                      "ips": [
-                        "203.0.113.0/24"
-                      ]
-                    },
-                    "time_zone": "Asia/Shanghai"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/AccountInfo"
-                        }
-                      },
-                      "type": "object"
+                      "allow_subdomain": true
                     }
-                  ]
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -33538,6 +34632,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -33545,82 +34642,69 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "security": [
-          {
-            "AppKeyAuth": []
-          }
-        ],
-        "summary": "查看主体信息",
-        "tags": [
-          "平台/账户设置"
-        ],
         "x-mint": {
-          "content": "| 权限 | 描述 |\n| --- | --- |\n| 无 | 无 — 任意有效的 app_key 均可调用此操作。 |\n\n在 [平台 API 参考](/zh/api-reference/platform/account/account-read-info) 中查看此操作。",
-          "href": "/zh/api-reference/platform/account/account-read-info",
           "metadata": {
             "sidebarTitle": "查看主体信息"
-          }
+          },
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 但对调用凭据有要求，见使用说明 |\n\n## 使用说明\n\n- 需要账户主体的凭据（如账户主体创建的 App Key）；使用成员凭据调用会返回 `401 Unauthorized`。成员可改用 `POST /member/info`。\n- `restrictions` 仅在配置过加入限制或访问限制时返回；`mp_plat`、`mp_account_id` 仅对通过云市场开通的账户返回。",
+          "href": "/zh/api-reference/platform/account/account-read-info"
         }
       }
     },
     "/alert-event/list": {
       "post": {
-        "description": "返回跨所有告警的原始告警事件分页列表，支持按集成、协作空间、时间范围和严重程度过滤。",
         "operationId": "alert-event-read-list",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "end_time": 1712707200,
-                "limit": 20,
-                "severities": "Critical",
-                "start_time": 1712620800
-              },
-              "schema": {
-                "$ref": "#/components/schemas/AlertEventGlobalListRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "查询原始告警事件列表",
+        "description": "返回跨所有告警的原始告警事件分页列表，支持按集成、协作空间、时间范围和严重程度过滤。",
+        "tags": [
+          "On-call/告警管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- `start_time` 和 `end_time` 均为必填的 Unix 时间戳（秒）。`start_time` 必须小于 `end_time`，跨度不超过 31 天。\n- 结果会根据调用方的协作空间数据访问权限进行过滤。\n- `severities` 为逗号分隔的列表，按 `event_severity` 匹配，如 `\"Critical,Warning\"`。取值不做校验，未知值（或 `Ok`）不会匹配任何事件。\n- 传入上次响应中的 `search_after_ctx` 获取下一页；不传时按 `p`/`limit` 页码分页，且 `p * limit` 不超过 10,000。",
+          "href": "/zh/api-reference/on-call/alerts/alert-event-read-list",
+          "metadata": {
+            "sidebarTitle": "查询原始告警事件列表"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "has_next_page": false,
-                    "items": [
-                      {
-                        "alert_id": "663a1b2c3d4e5f6789abcdef",
-                        "event_id": "663a1b2c3d4e5f6789abc001",
-                        "event_severity": "Critical",
-                        "event_time": 1712650000,
-                        "title": "CPU usage > 90%"
-                      }
-                    ],
-                    "total": 1
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/AlertEventGlobalListResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "total": 1,
+                    "has_next_page": false,
+                    "items": [
+                      {
+                        "event_id": "663a1b2c3d4e5f6789abc001",
+                        "alert_id": "663a1b2c3d4e5f6789abcdef",
+                        "title": "CPU usage > 90%",
+                        "event_severity": "Critical",
+                        "event_time": 1712650000
+                      }
+                    ],
+                    "search_after_ctx": "663a1b2c3d4e5f6789abc001"
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -33628,6 +34712,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -33635,80 +34722,82 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "查询原始告警事件列表",
-        "tags": [
-          "On-call/告警管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间查看**（`on-call`） |\n\n## 使用说明\n\n- `start_time` 和 `end_time` 均为必填的 Unix 时间戳（秒）。`start_time` 必须小于 `end_time`，跨度不超过 31 天。\n- 结果会根据调用方的协作空间数据访问权限进行过滤。\n- `severities` 为逗号分隔的字符串，如 `\"Critical,Warning\"`。",
-          "href": "/zh/api-reference/on-call/alerts/alert-event-read-list",
-          "metadata": {
-            "sidebarTitle": "查询原始告警事件列表"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/AlertEventGlobalListRequest"
+              },
+              "example": {
+                "start_time": 1712620800,
+                "end_time": 1712707200,
+                "limit": 20,
+                "severities": "Critical"
+              }
+            }
           }
         }
       }
     },
     "/alert/event/list": {
       "post": {
-        "description": "通过游标或页码分页返回指定告警的原始事件。",
         "operationId": "alert-read-event-list",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "alert_id": "663a1b2c3d4e5f6789abcdef",
-                "limit": 20
-              },
-              "schema": {
-                "$ref": "#/components/schemas/AlertEventListRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "查询告警事件列表",
+        "description": "通过游标或页码分页返回指定告警的原始事件。",
+        "tags": [
+          "On-call/告警管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间查看**（`on-call`） 或 **协作空间管理**（`on-call`） 或 **故障查看**（`on-call`） 或 **故障管理**（`on-call`） |\n\n## 使用说明\n\n- 默认按最新事件优先返回；设置 `asc=true` 可按最早事件优先读取。\n- 使用上次响应中的 `search_after_ctx` 搭配 `limit` 获取下一页。\n- 也支持通过 `p` 使用页码分页，但 `p * limit` 必须在 10,000 条以内。\n- 账户中不存在的 `alert_id` 返回 `InvalidParameter`。",
+          "href": "/zh/api-reference/on-call/alerts/alert-read-event-list",
+          "metadata": {
+            "sidebarTitle": "查询告警事件列表"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "has_next_page": true,
-                    "items": [
-                      {
-                        "alert_id": "663a1b2c3d4e5f6789abcdef",
-                        "event_id": "663a1b2c3d4e5f6789abc001",
-                        "event_severity": "Critical",
-                        "event_status": "Critical",
-                        "event_time": 1712650000,
-                        "labels": {
-                          "host": "web-01"
-                        },
-                        "title": "CPU usage > 90%"
-                      }
-                    ],
-                    "search_after_ctx": "663a1b2c3d4e5f6789abc001",
-                    "total": 57
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/AlertEventListResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "total": 57,
+                    "has_next_page": true,
+                    "search_after_ctx": "663a1b2c3d4e5f6789abc001",
+                    "items": [
+                      {
+                        "event_id": "663a1b2c3d4e5f6789abc001",
+                        "alert_id": "663a1b2c3d4e5f6789abcdef",
+                        "title": "CPU usage > 90%",
+                        "event_severity": "Critical",
+                        "event_status": "Critical",
+                        "event_time": 1712650000,
+                        "labels": {
+                          "host": "web-01"
+                        }
+                      }
+                    ]
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -33716,6 +34805,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -33723,77 +34815,78 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "查询告警事件列表",
-        "tags": [
-          "On-call/告警管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间查看**（`on-call`） |\n\n## 使用说明\n\n- 默认按最新事件优先返回；设置 `asc=true` 可按最早事件优先读取。\n- 使用上次响应中的 `search_after_ctx` 搭配 `limit` 获取下一页。\n- 也支持通过 `p` 使用页码分页，但 `p * limit` 必须在 10,000 条以内。\n- 单条告警可能累积大量原始事件，热点告警建议优先使用游标分页。",
-          "href": "/zh/api-reference/on-call/alerts/alert-read-event-list",
-          "metadata": {
-            "sidebarTitle": "查询告警事件列表"
-          }
-        }
-      }
-    },
-    "/alert/feed": {
-      "post": {
-        "description": "返回单条告警的动态记录（评论、状态变更、合并、静默事件），支持分页查询。",
-        "operationId": "alert-read-feed",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/AlertEventListRequest"
+              },
               "example": {
                 "alert_id": "663a1b2c3d4e5f6789abcdef",
-                "asc": false,
                 "limit": 20
-              },
-              "schema": {
-                "$ref": "#/components/schemas/AlertFeedRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/alert/feed": {
+      "post": {
+        "operationId": "alert-read-feed",
+        "summary": "查询告警动态",
+        "description": "返回单条告警的动态记录（评论、状态变更、合并、静默事件），支持分页查询。",
+        "tags": [
+          "On-call/告警管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 使用 `p`（页码，从 1 开始）和 `limit`（最大 100，默认 20）进行分页。\n- 将 `asc` 设为 `true` 可按时间正序返回。\n- 使用 `types` 过滤特定动态类型（如 `a_comm`、`a_merge`）。\n- 账户中不存在的 `alert_id` 返回 `InvalidParameter`。",
+          "href": "/zh/api-reference/on-call/alerts/alert-read-feed",
+          "metadata": {
+            "sidebarTitle": "查询告警动态"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "has_next_page": false,
-                    "items": [
-                      {
-                        "created_at": 1712651000,
-                        "creator_id": 80011,
-                        "detail": {
-                          "comment": "Investigating now."
-                        },
-                        "ref_id": "663a1b2c3d4e5f6789abcdef",
-                        "type": "a_comm"
-                      }
-                    ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/AlertFeedResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "has_next_page": false,
+                    "items": [
+                      {
+                        "ref_id": "663a1b2c3d4e5f6789abcdef",
+                        "type": "a_comm",
+                        "detail": {
+                          "comment": "Investigating now."
+                        },
+                        "account_id": 10023,
+                        "creator_id": 80011,
+                        "created_at": 1712651000000,
+                        "updated_at": 1712651000000
+                      }
+                    ]
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -33801,6 +34894,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -33808,69 +34904,71 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "查询告警动态",
-        "tags": [
-          "On-call/告警管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间查看**（`on-call`） |\n\n## 使用说明\n\n- 使用 `p`（页码，从 1 开始）和 `limit`（最大 100，默认 20）进行分页。\n- 将 `asc` 设为 `true` 可按时间正序返回。\n- 使用 `types` 过滤特定动态类型（如 `a_comm`、`a_merge`）。",
-          "href": "/zh/api-reference/on-call/alerts/alert-read-feed",
-          "metadata": {
-            "sidebarTitle": "查询告警动态"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/AlertFeedRequest"
+              },
+              "example": {
+                "alert_id": "663a1b2c3d4e5f6789abcdef",
+                "limit": 20,
+                "asc": false
+              }
+            }
           }
         }
       }
     },
     "/alert/info": {
       "post": {
-        "description": "通过告警 ID 返回单条告警的完整详情，包括关联故障和事件数量。",
         "operationId": "alert-read-info",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "alert_id": "663a1b2c3d4e5f6789abcdef"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/AlertInfoRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "查看告警详情",
+        "description": "通过告警 ID 返回单条告警的完整详情，包括关联故障和事件数量。",
+        "tags": [
+          "On-call/告警管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间查看**（`on-call`） 或 **协作空间管理**（`on-call`） 或 **故障查看**（`on-call`） 或 **故障管理**（`on-call`） |\n\n## 使用说明\n\n- `alert_id` 为 ObjectID 十六进制字符串，可从 `POST /alert/list` 或 `POST /alert-event/list` 获取。\n- 账户中不存在的 `alert_id` 返回 `InvalidParameter`。",
+          "href": "/zh/api-reference/on-call/alerts/alert-read-info",
+          "metadata": {
+            "sidebarTitle": "查看告警详情"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "alert_id": "663a1b2c3d4e5f6789abcdef",
-                    "alert_severity": "Critical",
-                    "alert_status": "Critical",
-                    "event_cnt": 3,
-                    "start_time": 1712650000,
-                    "title": "CPU usage > 90%"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/AlertItem"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "alert_id": "663a1b2c3d4e5f6789abcdef",
+                    "title": "CPU usage > 90%",
+                    "alert_severity": "Critical",
+                    "alert_status": "Critical",
+                    "start_time": 1712650000,
+                    "event_cnt": 3
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -33878,6 +34976,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -33885,92 +34986,90 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "查看告警详情",
-        "tags": [
-          "On-call/告警管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间查看**（`on-call`） |\n\n## 使用说明\n\n- `alert_id` 为 ObjectID 十六进制字符串，可从 `POST /alert/list` 或 `POST /alert-event/list` 获取。",
-          "href": "/zh/api-reference/on-call/alerts/alert-read-info",
-          "metadata": {
-            "sidebarTitle": "查看告警详情"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/AlertInfoRequest"
+              },
+              "example": {
+                "alert_id": "663a1b2c3d4e5f6789abcdef"
+              }
+            }
           }
         }
       }
     },
     "/alert/list": {
       "post": {
-        "description": "返回满足过滤条件的告警列表，支持游标分页。",
         "operationId": "alert-read-list",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "end_time": 1712707200,
-                "is_active": true,
-                "limit": 20,
-                "start_time": 1712620800
-              },
-              "schema": {
-                "$ref": "#/components/schemas/AlertListRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "查询告警列表",
+        "description": "返回满足过滤条件的告警列表，支持游标分页。",
+        "tags": [
+          "On-call/告警管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间查看**（`on-call`） 或 **协作空间管理**（`on-call`） 或 **故障查看**（`on-call`） 或 **故障管理**（`on-call`） 或 **集成中心查看**（`on-call`） 或 **集成中心管理**（`on-call`） |\n\n## 使用说明\n\n- `start_time` 和 `end_time` 为必填的 Unix 时间戳（秒），按告警的 `start_time` 过滤，跨度不超过 31 天。\n- `by_updated_at` 为 `true` 时，在 `start_time` 过滤之外再按相同区间过滤 `updated_at`，且跨度不超过 7 天。\n- `start_time` 早于账户数据保留期时会被调整为保留期起点；`end_time` 早于该起点时返回 `InvalidParameter`。\n- 传入上次响应中的 `search_after_ctx` 获取下一页；不传时按 `p`/`limit` 页码分页，且 `p * limit` 不超过 10,000。\n- `total` 最多为 1,000。页码模式下 `has_next_page` 基于这个封顶后的总数计算，读到第 1,000 条后会变为 `false`，即使还有更多匹配的告警。每个非空页都会返回最后一条告警的 `search_after_ctx`；要读取 1,000 条以后的数据，请传回该值改用游标模式，游标模式下 `has_next_page` 是准确的。\n- 结果会根据调用方的协作空间数据访问权限进行过滤。\n- 将 `is_active` 设为 `true` 可仅返回活跃（触发中）告警；设为 `false` 返回已恢复告警。",
+          "href": "/zh/api-reference/on-call/alerts/alert-read-list",
+          "metadata": {
+            "sidebarTitle": "查询告警列表"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/AlertListResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
+                    "total": 1,
                     "has_next_page": false,
                     "items": [
                       {
-                        "account_id": 10023,
                         "alert_id": "663a1b2c3d4e5f6789abcdef",
+                        "integration_id": 10001,
+                        "channel_id": 20001,
+                        "account_id": 10023,
+                        "title": "CPU usage > 90%",
                         "alert_severity": "Critical",
                         "alert_status": "Critical",
-                        "channel_id": 20001,
-                        "channel_name": "Production",
-                        "created_at": 1712650000,
+                        "start_time": 1712650000,
+                        "last_time": 1712655000,
                         "end_time": 0,
-                        "event_cnt": 3,
-                        "ever_muted": false,
-                        "integration_id": 10001,
-                        "integration_name": "Prometheus",
-                        "integration_type": "prometheus",
                         "labels": {
                           "host": "web-01"
                         },
-                        "last_time": 1712655000,
-                        "start_time": 1712650000,
-                        "title": "CPU usage > 90%",
-                        "updated_at": 1712655000
+                        "ever_muted": false,
+                        "created_at": 1712650000,
+                        "updated_at": 1712655000,
+                        "integration_name": "Prometheus",
+                        "integration_type": "prometheus",
+                        "channel_name": "Production",
+                        "event_cnt": 3
                       }
                     ],
-                    "total": 1
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/AlertListResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                    "search_after_ctx": "663a1b2c3d4e5f6789abcdef"
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -33978,6 +35077,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -33985,73 +35087,74 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "查询告警列表",
-        "tags": [
-          "On-call/告警管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间查看**（`on-call`） |\n\n## 使用说明\n\n- `start_time` 和 `end_time` 均为必填的 Unix 时间戳（秒），最大跨度 31 天。\n- 使用上次响应中的 `search_after_ctx` 获取下一页。\n- 结果会根据调用方的协作空间数据访问权限进行过滤。\n- 将 `is_active` 设为 `true` 可仅返回活跃（触发中）告警；设为 `false` 返回已恢复告警。",
-          "href": "/zh/api-reference/on-call/alerts/alert-read-list",
-          "metadata": {
-            "sidebarTitle": "查询告警列表"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/AlertListRequest"
+              },
+              "example": {
+                "start_time": 1712620800,
+                "end_time": 1712707200,
+                "limit": 20,
+                "is_active": true
+              }
+            }
           }
         }
       }
     },
     "/alert/list-by-ids": {
       "post": {
-        "description": "通过多个告警 ID 一次性返回多条告警详情。 注意：本接口不分页——`total`、`has_next_page` 恒为 `0`/`false`，`search_after_ctx` 不会返回。",
         "operationId": "alert-read-list-by-ids",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "alert_ids": [
-                  "663a1b2c3d4e5f6789abcdef"
-                ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/AlertListByIDsRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "批量查询告警",
+        "description": "按告警 ID 一次返回多条告警详情，不分页。",
+        "tags": [
+          "On-call/告警管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间查看**（`on-call`） 或 **协作空间管理**（`on-call`） 或 **故障查看**（`on-call`） 或 **故障管理**（`on-call`） |\n\n## 使用说明\n\n- 格式错误的 ID 会使请求返回 `InvalidParameter`；格式正确但账户中不存在的 ID 不会出现在 `items` 中。\n- 响应不分页：`total` 恒为 `0`，`has_next_page` 恒为 `false`，不返回 `search_after_ctx`。",
+          "href": "/zh/api-reference/on-call/alerts/alert-read-list-by-ids",
+          "metadata": {
+            "sidebarTitle": "批量查询告警"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "has_next_page": false,
-                    "items": [
-                      {
-                        "alert_id": "663a1b2c3d4e5f6789abcdef",
-                        "title": "CPU usage > 90%"
-                      }
-                    ],
-                    "total": 0
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/AlertListResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "total": 0,
+                    "has_next_page": false,
+                    "items": [
+                      {
+                        "alert_id": "663a1b2c3d4e5f6789abcdef",
+                        "title": "CPU usage > 90%"
+                      }
+                    ]
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -34059,6 +35162,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -34066,65 +35172,64 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "批量查询告警",
-        "tags": [
-          "On-call/告警管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间查看**（`on-call`） |\n\n## 使用说明\n\n- 所有 `alert_ids` 必须属于调用方账户，任何无效 ID 都会导致整个请求失败。",
-          "href": "/zh/api-reference/on-call/alerts/alert-read-list-by-ids",
-          "metadata": {
-            "sidebarTitle": "批量查询告警"
-          }
-        }
-      }
-    },
-    "/alert/merge": {
-      "post": {
-        "description": "将一条或多条告警关联到已有故障。若来源告警之前属于其他故障，且合并后该故障中没有其他告警，则该故障将自动关闭。",
-        "operationId": "alert-write-merge",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/AlertListByIDsRequest"
+              },
               "example": {
                 "alert_ids": [
                   "663a1b2c3d4e5f6789abcdef"
-                ],
-                "incident_id": "663a000000000000deadbeef"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/AlertMergeRequest"
+                ]
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/alert/merge": {
+      "post": {
+        "operationId": "alert-write-merge",
+        "summary": "将告警合并到故障",
+        "description": "将一条或多条告警移入已有故障，并关闭因此变空的来源故障。",
+        "tags": [
+          "On-call/告警管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- `alert_ids` 中的每个 ID 和 `incident_id` 都必须属于调用方账户，不存在的 ID 返回 `InvalidParameter`。\n- 已在目标故障中的告警会被跳过。来源故障合并后若不再有告警，会被关闭。\n- `title` 和 `owner_id` 仅在与目标故障当前值不同时才会更新。\n- 同一账户同一时间只处理一个故障变更，并发调用返回 `RequestTooFrequently`。",
+          "href": "/zh/api-reference/on-call/alerts/alert-write-merge",
+          "metadata": {
+            "sidebarTitle": "将告警合并到故障"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/EmptyResponse"
+                          "$ref": "#/components/schemas/EmptyObject"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -34132,6 +35237,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -34139,47 +35247,66 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "将告警合并到故障",
-        "tags": [
-          "On-call/告警管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间查看**（`on-call`） |\n\n## 使用说明\n\n- 所有 `alert_ids` 和 `incident_id` 必须属于调用方账户。\n- 可选填 `title` 和 `owner_id` 以同时更新目标故障。",
-          "href": "/zh/api-reference/on-call/alerts/alert-write-merge",
-          "metadata": {
-            "sidebarTitle": "将告警合并到故障"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/AlertMergeRequest"
+              },
+              "example": {
+                "alert_ids": [
+                  "663a1b2c3d4e5f6789abcdef"
+                ],
+                "incident_id": "663a000000000000deadbeef"
+              }
+            }
           }
         }
       }
     },
     "/alert/pipeline/info": {
       "post": {
-        "description": "返回指定集成的告警处理规则配置。",
         "operationId": "alert-read-pipeline-info",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "integration_id": 10001
-              },
-              "schema": {
-                "$ref": "#/components/schemas/AlertPipelineInfoRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "查看告警处理规则",
+        "description": "返回指定集成的告警处理规则配置。",
+        "tags": [
+          "On-call/告警管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间查看**（`on-call`） 或 **协作空间管理**（`on-call`） 或 **集成中心查看**（`on-call`） 或 **集成中心管理**（`on-call`） |\n\n## 使用说明\n\n- 该集成未配置告警处理规则时，响应只包含 `request_id`，不返回 `data` 字段。\n- `integration_id` 可以是账户中任意账户级或协作空间专属集成；不存在的 ID 返回 `InvalidParameter`。",
+          "href": "/zh/api-reference/on-call/alerts/alert-read-pipeline-info",
+          "metadata": {
+            "sidebarTitle": "查看告警处理规则"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/AlertPipelineItem"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
-                    "created_at": 1710000000,
-                    "creator_id": 80011,
                     "integration_id": 10001,
                     "rules": [
                       {
+                        "kind": "title_reset",
                         "if": [
                           {
                             "key": "labels.env",
@@ -34189,43 +35316,27 @@
                             ]
                           }
                         ],
-                        "kind": "title_reset",
                         "settings": {
                           "title": "[TPL]{{.Labels.service}} / {{.Labels.check}}"
                         }
                       },
                       {
-                        "if": null,
                         "kind": "severity_reset",
+                        "if": null,
                         "settings": {
                           "severity": "Warning"
                         }
                       }
                     ],
                     "status": "enabled",
-                    "updated_at": 1712000000,
-                    "updated_by": 80011
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/AlertPipelineItem"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                    "creator_id": 80011,
+                    "updated_by": 80011,
+                    "created_at": 1710000000,
+                    "updated_at": 1712000000
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -34233,6 +35344,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -34240,52 +35354,65 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "查看告警处理规则",
-        "tags": [
-          "On-call/告警管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **集成中心查看**（`on-call`） |\n\n## 使用说明\n\n- 若该集成尚未配置告警处理规则，则 data 为 `null`。\n- 调用方需有该集成的访问权限。",
-          "href": "/zh/api-reference/on-call/alerts/alert-read-pipeline-info",
-          "metadata": {
-            "sidebarTitle": "查看告警处理规则"
-          }
-        }
-      }
-    },
-    "/alert/pipeline/list": {
-      "post": {
-        "description": "返回多个集成的告警处理规则配置。",
-        "operationId": "alert-read-pipeline-list",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {
-                "integration_ids": [
-                  10001,
-                  10002
-                ]
-              },
               "schema": {
-                "$ref": "#/components/schemas/AlertPipelineListRequest"
+                "$ref": "#/components/schemas/AlertPipelineInfoRequest"
+              },
+              "example": {
+                "integration_id": 10001
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/alert/pipeline/list": {
+      "post": {
+        "operationId": "alert-read-pipeline-list",
+        "summary": "批量查询告警处理规则",
+        "description": "返回多个集成的告警处理规则配置。",
+        "tags": [
+          "On-call/告警管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **集成中心查看**（`on-call`） 或 **集成中心管理**（`on-call`） |\n\n## 使用说明\n\n- `integration_ids` 中每个 ID 都必须是账户中的集成；只要有一个不存在，整个请求返回 `InvalidParameter`。\n- `items` 中每个已配置规则的集成对应一项，未配置的集成不出现。",
+          "href": "/zh/api-reference/on-call/alerts/alert-read-pipeline-list",
+          "metadata": {
+            "sidebarTitle": "批量查询告警处理规则"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/AlertPipelineListResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "items": [
                       {
-                        "created_at": 1710000000,
-                        "creator_id": 80011,
                         "integration_id": 10001,
                         "rules": [
                           {
+                            "kind": "alert_inhibit",
                             "if": [
                               {
                                 "key": "labels.cluster",
@@ -34295,14 +35422,13 @@
                                 ]
                               }
                             ],
-                            "kind": "alert_inhibit",
                             "settings": {
                               "equals": [
-                                "service"
+                                "labels.service"
                               ],
                               "source_filters": [
                                 {
-                                  "key": "alert_severity",
+                                  "key": "severity",
                                   "oper": "IN",
                                   "vals": [
                                     "Critical"
@@ -34313,31 +35439,91 @@
                           }
                         ],
                         "status": "enabled",
-                        "updated_at": 1712000000,
-                        "updated_by": 80011
+                        "creator_id": 80011,
+                        "updated_by": 80011,
+                        "created_at": 1710000000,
+                        "updated_at": 1712000000
                       }
                     ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "429": {
+            "$ref": "#/components/responses/TooManyRequests"
+          },
+          "500": {
+            "$ref": "#/components/responses/ServerError"
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/AlertPipelineListRequest"
+              },
+              "example": {
+                "integration_ids": [
+                  10001,
+                  10002
+                ]
+              }
+            }
+          }
+        }
+      }
+    },
+    "/alert/pipeline/upsert": {
+      "post": {
+        "operationId": "alert-write-pipeline-upsert",
+        "summary": "创建或更新告警处理规则",
+        "description": "为集成设置告警处理规则，将完全替换已有配置。",
+        "tags": [
+          "On-call/告警管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） 或 **集成中心管理**（`on-call`） |\n\n## 使用说明\n\n- 用 `rules` 整体替换该集成的规则列表；传空数组会清空所有规则。最多 50 条。\n- 规则按数组顺序作用于该集成收到的每个事件，在事件生成告警之前执行；`alert_drop` 或命中的 `alert_inhibit` 会丢弃事件并停止后续处理。\n- `integration_id` 可以是账户级集成，也可以是协作空间专属集成；账户中不存在的 ID 返回 `InvalidParameter`。\n- 写操作还需对象权限：主体账户、管理员、集成创建者或其所属团队成员可操作（协作空间专属集成看协作空间所属团队）；未设置团队时，拥有接口权限的调用方均可操作。\n- `alert_inhibit` 规则需要 Standard 及以上套餐，否则返回 `NoLicense`。\n- 成功时响应只包含 `request_id`，不返回 `data` 字段。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "href": "/zh/api-reference/on-call/alerts/alert-write-pipeline-upsert",
+          "metadata": {
+            "sidebarTitle": "创建或更新告警处理规则"
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "成功",
+            "content": {
+              "application/json": {
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/AlertPipelineListResponse"
+                          "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -34345,6 +35531,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -34352,30 +35541,18 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "批量查询告警处理规则",
-        "tags": [
-          "On-call/告警管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **集成中心查看**（`on-call`） |\n\n## 使用说明\n\n- 所有 `integration_ids` 必须对调用方可访问。",
-          "href": "/zh/api-reference/on-call/alerts/alert-read-pipeline-list",
-          "metadata": {
-            "sidebarTitle": "批量查询告警处理规则"
-          }
-        }
-      }
-    },
-    "/alert/pipeline/upsert": {
-      "post": {
-        "description": "为集成设置告警处理规则，将完全替换已有配置。",
-        "operationId": "alert-write-pipeline-upsert",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/AlertPipelineUpsertRequest"
+              },
               "example": {
                 "integration_id": 10001,
                 "rules": [
                   {
+                    "kind": "title_reset",
                     "if": [
                       {
                         "key": "labels.env",
@@ -34385,53 +35562,80 @@
                         ]
                       }
                     ],
-                    "kind": "title_reset",
                     "settings": {
                       "title": "[TPL]{{.Labels.service}} / {{.Labels.check}}"
                     }
                   },
                   {
-                    "if": null,
                     "kind": "severity_reset",
+                    "if": null,
                     "settings": {
                       "severity": "Warning"
                     }
                   }
                 ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/AlertPipelineUpsertRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/audit/operation/list": {
+      "post": {
+        "operationId": "audit-read-operation-list",
+        "summary": "查看事件类型列表",
+        "description": "返回所有会记录到审计日志中的操作名称，可用于 `operations` 过滤参数。",
+        "tags": [
+          "平台/审计日志"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **审计查看**（`organization`） |\n\n## 使用说明\n\n- 将响应中的 `name` 值作为 `POST /audit/search` 的 `operations` 过滤值。\n- `name_cn` 是控制台中显示的中文标签，不随请求语言变化；`name` 是用于过滤的稳定值。",
+          "href": "/zh/api-reference/platform/audit-logs/audit-read-operation-list",
+          "metadata": {
+            "sidebarTitle": "查看事件类型列表"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": null,
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/EmptyResponse"
+                          "$ref": "#/components/schemas/AuditOperationListResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "items": [
+                      {
+                        "name": "template:write:create",
+                        "name_cn": "创建模板"
+                      },
+                      {
+                        "name": "template:write:delete",
+                        "name_cn": "删除模板"
+                      },
+                      {
+                        "name": "incident:write:acknowledge",
+                        "name_cn": "认领故障"
+                      }
+                    ]
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -34439,6 +35643,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -34446,75 +35653,82 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "创建或更新告警处理规则",
-        "tags": [
-          "On-call/告警管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **集成中心管理**（`on-call`） |\n\n## 使用说明\n\n- 每条处理规则最多 50 条规则。\n- 每条规则包含 `kind`（`title_reset`、`description_reset`、`severity_reset`、`alert_drop`、`alert_inhibit` 之一）、可选的 `if` 过滤器，以及与 kind 对应的 `settings`。\n- `alert_inhibit` 类型需要 Standard 及以上许可证。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
-          "href": "/zh/api-reference/on-call/alerts/alert-write-pipeline-upsert",
-          "metadata": {
-            "sidebarTitle": "创建或更新告警处理规则"
-          }
-        }
-      }
-    },
-    "/audit/operation/list": {
-      "post": {
-        "description": "返回所有会记录到审计日志中的操作名称，可用于 `operations` 过滤参数。",
-        "operationId": "audit-read-operation-list",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {},
               "schema": {
                 "$ref": "#/components/schemas/AuditOperationListRequest"
-              }
+              },
+              "example": {}
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/audit/search": {
+      "post": {
+        "operationId": "audit-read-search",
+        "summary": "检索审计日志",
+        "description": "按时间范围返回游标分页的操作审计日志列表。",
+        "tags": [
+          "平台/审计日志"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **审计查看**（`organization`） |\n\n## 使用说明\n\n- 必须指定时间范围，跨度最长 90 天。`start_time` 和 `end_time` 均为 Unix 时间戳（**秒**）。\n- 使用上一次响应中的 `search_after_ctx` 获取下一页。该游标是不透明的，请勿自行构造。\n- 可查询的保留期取决于账户的 License。超出保留期的查询会直接返回空结果，而不是报错。\n- 建议显式传 `limit`（1–99）以便稳定分页；不传或为 0 时由服务端决定每页条数，可能一次返回全部结果。结果按时间倒序返回。",
+          "href": "/zh/api-reference/platform/audit-logs/audit-read-search",
+          "metadata": {
+            "sidebarTitle": "检索审计日志"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "items": [
-                      {
-                        "name": "template:write:create",
-                        "name_cn": "创建模板"
-                      },
-                      {
-                        "name": "template:write:delete",
-                        "name_cn": "删除模板"
-                      },
-                      {
-                        "name": "incident:write:acknowledge",
-                        "name_cn": "认领故障"
-                      }
-                    ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/AuditOperationListResponse"
+                          "$ref": "#/components/schemas/AuditSearchResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "total": 2,
+                    "search_after_ctx": "",
+                    "docs": [
+                      {
+                        "created_at": 1712700123456,
+                        "account_id": 10023,
+                        "member_id": 80011,
+                        "member_name": "Alice",
+                        "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                        "ip": "203.0.113.42",
+                        "operation": "template:write:create",
+                        "operation_name": "创建模板",
+                        "body": "{\"template_name\":\"Prod default\"}",
+                        "params": [],
+                        "is_dangerous": false,
+                        "is_write": true,
+                        "principal_kind": "member",
+                        "credential_type": "",
+                        "credential_id": 0
+                      }
+                    ]
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -34522,6 +35736,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -34529,90 +35746,71 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "查看事件类型列表",
-        "tags": [
-          "平台/审计日志"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **审计查看**（`organization`） |\n\n## 使用说明\n\n- 将本接口返回的 `name` 值作为 `POST /audit/search` 的 `operations` 过滤参数使用。\n- `name_cn` 是控制台展示的中文标签；`name` 是用于过滤的稳定字段值。",
-          "href": "/zh/api-reference/platform/audit-logs/audit-read-operation-list",
-          "metadata": {
-            "sidebarTitle": "查看事件类型列表"
-          }
-        }
-      }
-    },
-    "/audit/search": {
-      "post": {
-        "description": "按时间范围返回游标分页的操作审计日志列表。",
-        "operationId": "audit-read-search",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/AuditSearchRequest"
+              },
               "example": {
+                "start_time": 1712620800,
                 "end_time": 1712707200,
                 "limit": 20,
                 "operations": [
                   "template:write:create",
                   "template:write:delete"
-                ],
-                "start_time": 1712620800
-              },
-              "schema": {
-                "$ref": "#/components/schemas/AuditSearchRequest"
+                ]
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/calendar/create": {
+      "post": {
+        "operationId": "calendarCreate",
+        "summary": "创建服务日历",
+        "description": "创建个人服务日历，并设置每周工作日与关联的节假日日历。",
+        "tags": [
+          "On-call/日历管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **服务日历管理**（`on-call`） |\n\n## 使用说明\n\n- 5 个日历的上限仅在调用方为主体账户时校验：账户已有 5 个日历后，主体账户的创建请求返回 `InvalidParameter`；其他成员发起的调用不受此上限限制。\n- `cal_name` 在账户内必须唯一，`timezone` 必须是合法的 IANA 时区，非零 `team_id` 必须是账户中的团队，否则返回 `InvalidParameter`。\n- 每次调用都会记录到账户审计日志。",
+          "href": "/zh/api-reference/on-call/calendars/calendar-create",
+          "metadata": {
+            "sidebarTitle": "创建服务日历"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "docs": [
-                      {
-                        "account_id": 10023,
-                        "body": "{\"template_name\":\"Prod default\"}",
-                        "created_at": 1712700123456,
-                        "credential_id": 0,
-                        "credential_type": "",
-                        "ip": "203.0.113.42",
-                        "is_dangerous": false,
-                        "is_write": true,
-                        "member_id": 80011,
-                        "member_name": "Alice",
-                        "operation": "template:write:create",
-                        "operation_name": "创建模板",
-                        "params": [],
-                        "principal_kind": "member",
-                        "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                      }
-                    ],
-                    "search_after_ctx": "",
-                    "total": 2
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/AuditSearchResponse"
+                          "$ref": "#/components/schemas/CalendarCreateResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "cal_id": "cal.QiNvtdKs4Wj52kZhT3LafM",
+                    "cal_name": "API Test Calendar"
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -34620,6 +35818,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -34627,26 +35828,13 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "检索审计日志",
-        "tags": [
-          "平台/审计日志"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **审计查看**（`organization`） |\n\n## 使用说明\n\n- 时间范围必填。最大跨度 90 天，`start_time` 和 `end_time` 均为 Unix 时间戳（**秒**）。\n- 使用上次响应中的 `search_after_ctx` 获取下一页。该 token 是不透明的，请勿手动构造。\n- 可查询的时间窗口受账户许可证限制，超出保留期的查询会静默返回空结果，而不是报错。\n- `limit` 取值 0–99；省略（或传 0）表示不分页，返回窗口内全部匹配记录。记录按时间倒序返回。",
-          "href": "/zh/api-reference/platform/audit-logs/audit-read-search",
-          "metadata": {
-            "sidebarTitle": "检索审计日志"
-          }
-        }
-      }
-    },
-    "/calendar/create": {
-      "post": {
-        "description": "创建个人服务日历。每个账户默认最多 5 个日历，可通过 Flashcat-Break-Cal-Limit 请求头突破限制。",
-        "operationId": "calendarCreate",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CalendarCreateRequest"
+              },
               "example": {
                 "cal_name": "Production On-Call Calendar",
                 "description": "Calendar for production on-call team",
@@ -34658,113 +35846,53 @@
                   4,
                   5
                 ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/CalendarCreateRequest"
               }
             }
-          },
-          "required": true
-        },
-        "responses": {
-          "200": {
-            "content": {
-              "application/json": {
-                "example": {
-                  "data": {
-                    "cal_id": "cal.QiNvtdKs4Wj52kZhT3LafM",
-                    "cal_name": "API Test Calendar"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/CalendarCreateResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
-                }
-              }
-            },
-            "description": "成功"
-          },
-          "400": {
-            "$ref": "#/components/responses/BadRequest"
-          },
-          "401": {
-            "$ref": "#/components/responses/Unauthorized"
-          },
-          "429": {
-            "$ref": "#/components/responses/TooManyRequests"
-          },
-          "500": {
-            "$ref": "#/components/responses/ServerError"
-          }
-        },
-        "summary": "创建服务日历",
-        "tags": [
-          "On-call/日历管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **服务日历管理**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/calendars/calendar-create",
-          "metadata": {
-            "sidebarTitle": "创建服务日历"
           }
         }
       }
     },
     "/calendar/delete": {
       "post": {
-        "description": "删除个人服务日历。当日历被分派或静默策略引用时删除会失败。",
         "operationId": "calendarDelete",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "cal_id": "cal.QiNvtdKs4Wj52kZhT3LafM"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/CalendarIDRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "删除服务日历",
+        "description": "删除个人服务日历及其事件，前提是没有策略引用它。",
+        "tags": [
+          "On-call/日历管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **服务日历管理**（`on-call`） |\n\n## 使用说明\n\n- 日历仍被分派策略或静默策略使用时，返回 HTTP 400，`error.code` 为 `ReferenceExist`，`data.refs` 列出引用方。\n- 日历自有的事件会一并删除。\n- 仅个人日历可修改，且仅限主体账户、管理员、日历创建者或日历所属团队成员操作，其他调用方返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志。",
+          "href": "/zh/api-reference/on-call/calendars/calendar-delete",
+          "metadata": {
+            "sidebarTitle": "删除服务日历"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/CalendarEmptyObject"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -34772,70 +35900,72 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
           "500": {
             "$ref": "#/components/responses/ServerError"
           }
-        },
-        "summary": "删除服务日历",
-        "tags": [
-          "On-call/日历管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **服务日历管理**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/calendars/calendar-delete",
-          "metadata": {
-            "sidebarTitle": "删除服务日历"
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CalendarIDRequest"
+              },
+              "example": {
+                "cal_id": "cal.QiNvtdKs4Wj52kZhT3LafM"
+              }
+            }
           }
         }
       }
     },
     "/calendar/event/delete": {
       "post": {
-        "description": "按 event_id 删除个人日历的一个事件，或清除该日历自己在 [start_at, end_at) 这些日期上的事件。event_id 与 start_at/end_at 二选一，start_at 和 end_at 须同时传入。清除后这些日期回到关联节假日日历和每周工作日设置的判定。",
         "operationId": "calEventDelete",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "cal_id": "cal.QiNvtdKs4Wj52kZhT3LafM",
-                "event_id": "cale.KyG9XWTCU5CucbwukEVBQ4"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/CalEventIDRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "删除日历事件",
+        "description": "按 ID 删除个人日历的一个事件，或清除该日历自有事件在某个日期范围内的部分。",
+        "tags": [
+          "On-call/日历管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **服务日历管理**（`on-call`） |\n\n## 使用说明\n\n- 传 `event_id`，或同时传 `start_at` 与 `end_at`（格式 `YYYY-MM-DD`，覆盖 [`start_at`, `end_at`)）；其他组合返回 `InvalidParameter`。\n- 清除后这些日期回到关联节假日日历和每周工作日设置的判定。\n- 仅个人日历可修改，且仅限主体账户、管理员、日历创建者或日历所属团队成员操作，其他调用方返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志。",
+          "href": "/zh/api-reference/on-call/calendars/cal-event-delete",
+          "metadata": {
+            "sidebarTitle": "删除日历事件"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/CalendarEmptyObject"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -34843,6 +35973,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -34850,69 +35983,85 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "删除日历事件",
-        "tags": [
-          "On-call/日历管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **服务日历管理**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/calendars/cal-event-delete",
-          "metadata": {
-            "sidebarTitle": "删除日历事件"
-          }
-        }
-      }
-    },
-    "/calendar/event/list": {
-      "post": {
-        "description": "返回个人日历在指定年/月/日范围内的事件列表。未同时传入 month 和 day 时返回整年数据。响应中的 days 给出范围内每一天的判定结果。",
-        "operationId": "calEventList",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CalEventIDRequest"
+              },
               "example": {
                 "cal_id": "cal.QiNvtdKs4Wj52kZhT3LafM",
-                "month": 5,
-                "year": 2024
-              },
-              "schema": {
-                "$ref": "#/components/schemas/CalEventListRequest"
+                "event_id": "cale.KyG9XWTCU5CucbwukEVBQ4"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/calendar/event/list": {
+      "post": {
+        "operationId": "calEventList",
+        "summary": "查询日历事件列表",
+        "description": "返回个人日历在指定年、月或日内的事件，以及每一天的判定结果。",
+        "tags": [
+          "On-call/日历管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- `year` 默认为当前年份；不传 `month` 时返回整年，传 `day` 时必须同时传 `month`。\n- `items` 合并了日历自有事件（ID 为 `cale.*`）、设置了 `workdays` 时按非工作日逐日生成的 `non_work.YYYYMMDD` 条目，以及关联节假日日历的事件；`total` 统计全部条目。\n- `days` 给出范围内每一天的判定结果。\n- 仅支持个人日历（`cal_id` 以 `cal.` 开头），其他 ID 返回 `InvalidParameter`。",
+          "href": "/zh/api-reference/on-call/calendars/cal-event-list",
+          "metadata": {
+            "sidebarTitle": "查询日历事件列表"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/CalEventListResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "items": [
                       {
                         "account_id": 2451002751131,
-                        "cal_id": "cal.QiNvtdKs4Wj52kZhT3LafM",
-                        "created_at": 1775972034,
                         "creator_id": 2476444212131,
+                        "cal_id": "cal.QiNvtdKs4Wj52kZhT3LafM",
+                        "event_id": "cale.KyG9XWTCU5CucbwukEVBQ4",
+                        "summary": "Test Holiday",
                         "description": "A test holiday event",
+                        "start_at": "2026-05-01",
                         "end_at": "2026-05-02",
-                        "event_id": "cale.KyG9XWTCU5CucbwukEVBQ4",
                         "is_off": true,
-                        "start_at": "2026-05-01",
-                        "summary": "Test Holiday",
+                        "created_at": 1775972034,
                         "updated_at": 1775972034
                       },
                       {
                         "account_id": 2451002751131,
-                        "cal_id": "cal.QiNvtdKs4Wj52kZhT3LafM",
-                        "created_at": 0,
                         "creator_id": 2451002751131,
+                        "cal_id": "cal.QiNvtdKs4Wj52kZhT3LafM",
+                        "event_id": "non_work.20260502",
+                        "summary": "non-working day (Saturday)",
                         "description": "",
+                        "start_at": "2026-05-02",
                         "end_at": "2026-05-03",
-                        "event_id": "non_work.20260502",
                         "is_off": true,
-                        "start_at": "2026-05-02",
-                        "summary": "non-working day (Saturday)",
+                        "created_at": 0,
                         "updated_at": 0
                       }
                     ],
@@ -34937,27 +36086,10 @@
                         "is_off": false
                       }
                     }
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/CalEventListResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -34965,6 +36097,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -34972,71 +36107,68 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "查询日历事件列表",
-        "tags": [
-          "On-call/日历管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |",
-          "href": "/zh/api-reference/on-call/calendars/cal-event-list",
-          "metadata": {
-            "sidebarTitle": "查询日历事件列表"
-          }
-        }
-      }
-    },
-    "/calendar/event/upsert": {
-      "post": {
-        "description": "创建或更新日历自己的事件（休息日或工作日覆盖），作用于 [start_at, end_at) 这些日期。不传 event_id 时创建新事件；传入的 event_id 必须是该日历已有的事件。写入时会把该日历自己的其他事件从这些日期上移除：完全落在范围内的事件被删除，部分重叠的被截短，跨越整个范围的被拆成两段，因此这些日期以最后一次写入为准。end_at 必须晚于 start_at。",
-        "operationId": "calEventUpsert",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CalEventListRequest"
+              },
               "example": {
                 "cal_id": "cal.QiNvtdKs4Wj52kZhT3LafM",
-                "description": "International Workers Day holiday",
-                "end_at": "2024-05-06",
-                "is_off": true,
-                "start_at": "2024-05-01",
-                "summary": "Labour Day"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/CalEventUpsertRequest"
+                "year": 2024,
+                "month": 5
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/calendar/event/upsert": {
+      "post": {
+        "operationId": "calEventUpsert",
+        "summary": "创建或更新日历事件",
+        "description": "创建或更新个人日历自有的事件：休息日或工作日覆盖。",
+        "tags": [
+          "On-call/日历管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **服务日历管理**（`on-call`） |\n\n## 使用说明\n\n- 事件覆盖 [`start_at`, `end_at`) 这些日期，格式为 `YYYY-MM-DD`；`end_at` 必须晚于 `start_at`。\n- 不传 `event_id` 时创建新事件；传入的 `event_id` 必须是该日历已有的事件。\n- 写入时会把该日历自己的其他事件从这些日期上移除：完全落在范围内的事件被删除，部分重叠的被截短，跨越整个范围的被拆成两段，因此这些日期以最后一次写入为准。\n- 仅个人日历可修改，且仅限主体账户、管理员、日历创建者或日历所属团队成员操作，其他调用方返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志。",
+          "href": "/zh/api-reference/on-call/calendars/cal-event-upsert",
+          "metadata": {
+            "sidebarTitle": "创建或更新日历事件"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "cal_id": "cal.QiNvtdKs4Wj52kZhT3LafM",
-                    "event_id": "cale.KyG9XWTCU5CucbwukEVBQ4",
-                    "summary": "Test Holiday"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/CalEventUpsertResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "cal_id": "cal.QiNvtdKs4Wj52kZhT3LafM",
+                    "event_id": "cale.KyG9XWTCU5CucbwukEVBQ4",
+                    "summary": "Test Holiday"
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -35044,6 +36176,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -35051,54 +36186,71 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "创建或更新日历事件",
-        "tags": [
-          "On-call/日历管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **服务日历管理**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/calendars/cal-event-upsert",
-          "metadata": {
-            "sidebarTitle": "创建或更新日历事件"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CalEventUpsertRequest"
+              },
+              "example": {
+                "cal_id": "cal.QiNvtdKs4Wj52kZhT3LafM",
+                "summary": "Labour Day",
+                "start_at": "2024-05-01",
+                "end_at": "2024-05-06",
+                "is_off": true,
+                "description": "International Workers Day holiday"
+              }
+            }
           }
         }
       }
     },
     "/calendar/info": {
       "post": {
-        "description": "返回服务日历的详细信息。",
         "operationId": "calendarInfo",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "cal_id": "cal.eh9gvPtWeH3xXgKeVSRxRg"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/CalendarIDRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "获取服务日历详情",
+        "description": "按 ID 返回账户中一个服务日历的详情。",
+        "tags": [
+          "On-call/日历管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 不存在的 `cal_id` 返回 `InvalidParameter`。",
+          "href": "/zh/api-reference/on-call/calendars/calendar-info",
+          "metadata": {
+            "sidebarTitle": "获取服务日历详情"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/CalendarItem"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "account_id": 2451002751131,
+                    "team_id": 2477033058131,
                     "cal_id": "cal.eh9gvPtWeH3xXgKeVSRxRg",
                     "cal_name": "Stock Exchange Calendar",
-                    "created_at": 1702455630,
-                    "creator_id": 2476444212131,
                     "description": "A stock market trading calendar example",
-                    "kind": "personal",
-                    "status": "enabled",
-                    "team_id": 2477033058131,
                     "timezone": "Asia/Shanghai",
-                    "updated_at": 1775529526,
-                    "updated_by": 3790925372131,
+                    "kind": "personal",
                     "workdays": [
                       0,
                       1,
@@ -35107,28 +36259,16 @@
                       4,
                       5,
                       6
-                    ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/CalendarItem"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                    ],
+                    "created_at": 1702455630,
+                    "updated_at": 1775529526,
+                    "creator_id": 2476444212131,
+                    "updated_by": 3790925372131,
+                    "status": "enabled"
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -35136,6 +36276,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -35143,56 +36286,68 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "获取服务日历详情",
-        "tags": [
-          "On-call/日历管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |",
-          "href": "/zh/api-reference/on-call/calendars/calendar-info",
-          "metadata": {
-            "sidebarTitle": "获取服务日历详情"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CalendarIDRequest"
+              },
+              "example": {
+                "cal_id": "cal.eh9gvPtWeH3xXgKeVSRxRg"
+              }
+            }
           }
         }
       }
     },
     "/calendar/list": {
       "post": {
-        "description": "返回当前账户可见的服务日历列表。",
         "operationId": "calendarList",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "kind": "personal"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/CalendarListRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "查询服务日历列表",
+        "description": "返回当前账户可见的服务日历列表。",
+        "tags": [
+          "On-call/日历管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 不传 `kind` 时返回个人日历。`region.official.holiday` 返回公共节假日日历，默认按调用方语言区域过滤，`no_locale` 为 `true` 时不过滤；其 `cal_id` 可填入 `extra_cal_ids`。\n- 列表不分页，`total` 等于返回的条目数。",
+          "href": "/zh/api-reference/on-call/calendars/calendar-list",
+          "metadata": {
+            "sidebarTitle": "查询服务日历列表"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/CalendarListResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "items": [
                       {
                         "account_id": 2451002751131,
+                        "team_id": 2477033058131,
                         "cal_id": "cal.eh9gvPtWeH3xXgKeVSRxRg",
                         "cal_name": "Stock Exchange Calendar",
-                        "created_at": 1702455630,
-                        "creator_id": 2476444212131,
                         "description": "A stock market trading calendar example",
-                        "kind": "personal",
-                        "status": "enabled",
-                        "team_id": 2477033058131,
                         "timezone": "Asia/Shanghai",
-                        "updated_at": 1775529526,
-                        "updated_by": 3790925372131,
+                        "kind": "personal",
                         "workdays": [
                           0,
                           1,
@@ -35201,48 +36356,108 @@
                           4,
                           5,
                           6
-                        ]
+                        ],
+                        "created_at": 1702455630,
+                        "updated_at": 1775529526,
+                        "creator_id": 2476444212131,
+                        "updated_by": 3790925372131,
+                        "status": "enabled"
                       },
                       {
                         "account_id": 2451002751131,
+                        "team_id": 0,
                         "cal_id": "cal.VZYkchxJhGELSF4jzkUAud",
                         "cal_name": "HK Stock Exchange Calendar",
-                        "created_at": 1702968470,
-                        "creator_id": 2451002751131,
                         "description": "Hong Kong Stock Exchange trading days calendar",
+                        "timezone": "Asia/Shanghai",
+                        "kind": "personal",
                         "extra_cal_ids": [
                           "zh-cn.china.official"
                         ],
-                        "kind": "personal",
-                        "status": "enabled",
-                        "team_id": 0,
-                        "timezone": "Asia/Shanghai",
+                        "created_at": 1702968470,
                         "updated_at": 1775188967,
-                        "updated_by": 3790925372131
+                        "creator_id": 2451002751131,
+                        "updated_by": 3790925372131,
+                        "status": "enabled"
                       }
                     ],
                     "total": 8
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "429": {
+            "$ref": "#/components/responses/TooManyRequests"
+          },
+          "500": {
+            "$ref": "#/components/responses/ServerError"
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CalendarListRequest"
+              },
+              "example": {
+                "kind": "personal"
+              }
+            }
+          }
+        }
+      }
+    },
+    "/calendar/update": {
+      "post": {
+        "operationId": "calendarUpdate",
+        "summary": "更新服务日历",
+        "description": "更新个人服务日历，仅修改传入的字段。",
+        "tags": [
+          "On-call/日历管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **服务日历管理**（`on-call`） |\n\n## 使用说明\n\n- 除 `cal_id` 外至少传一个字段，否则返回 `InvalidParameter`。\n- 传入 `workdays` 或 `extra_cal_ids` 会整体替换原列表（空数组即清空）；`team_id: 0` 表示取消团队归属。\n- `cal_name` 在账户内必须唯一。\n- 仅个人日历可修改，且仅限主体账户、管理员、日历创建者或日历所属团队成员操作，其他调用方返回 `AccessDenied`。\n- 成功时响应只包含 `request_id`，不返回 `data` 字段。\n- 每次调用都会记录到账户审计日志。",
+          "href": "/zh/api-reference/on-call/calendars/calendar-update",
+          "metadata": {
+            "sidebarTitle": "更新服务日历"
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "成功",
+            "content": {
+              "application/json": {
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/CalendarListResponse"
+                          "$ref": "#/components/schemas/CalendarEmptyObject"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -35250,6 +36465,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -35257,26 +36475,13 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "查询服务日历列表",
-        "tags": [
-          "On-call/日历管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |",
-          "href": "/zh/api-reference/on-call/calendars/calendar-list",
-          "metadata": {
-            "sidebarTitle": "查询服务日历列表"
-          }
-        }
-      }
-    },
-    "/calendar/update": {
-      "post": {
-        "description": "更新个人服务日历，仅更新传入的非空字段。",
-        "operationId": "calendarUpdate",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CalendarUpdateRequest"
+              },
               "example": {
                 "cal_id": "cal.QiNvtdKs4Wj52kZhT3LafM",
                 "cal_name": "Production On-Call Calendar (Updated)",
@@ -35288,40 +36493,79 @@
                   4,
                   5
                 ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/CalendarUpdateRequest"
               }
-            }
-          },
-          "required": true
+            }
+          }
+        }
+      }
+    },
+    "/change/list": {
+      "post": {
+        "operationId": "change-read-list",
+        "summary": "查询变更列表",
+        "description": "在指定时间窗口内查询变更记录，支持过滤、搜索与分页。",
+        "tags": [
+          "On-call/变更管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- `start_time` 和 `end_time` 均为必填：`start_time` 必须小于 `end_time`，且时间跨度不超过 31 天。\n- 变更的 `[start_time, last_time]` 区间与查询时间窗有重叠即视为匹配。\n- 将 `include_events` 设为 `true` 可在 `events` 中附带每个变更的原始变更事件。",
+          "href": "/zh/api-reference/on-call/changes/change-read-list",
+          "metadata": {
+            "sidebarTitle": "查询变更列表"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/CalendarEmptyObject"
+                          "$ref": "#/components/schemas/ListChangeResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "total": 1,
+                    "has_next_page": false,
+                    "items": [
+                      {
+                        "change_id": "664a1b2c3d4e5f6a7b8c9d0e",
+                        "account_id": 10001,
+                        "channel_id": 5001,
+                        "channel_name": "Production",
+                        "channel_status": "enabled",
+                        "integration_id": 362,
+                        "integration_name": "GitHub Deploy",
+                        "title": "Deploy api-server v2.3.1",
+                        "description": "Rolling deploy to production cluster",
+                        "change_key": "deploy-api-server-2311",
+                        "change_status": "Done",
+                        "start_time": 1716962400,
+                        "last_time": 1716962700,
+                        "end_time": 1716963000,
+                        "labels": {
+                          "service": "api-server",
+                          "env": "prod"
+                        },
+                        "link": "https://github.com/acme/api-server/actions/runs/123"
+                      }
+                    ]
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -35329,6 +36573,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -35336,97 +36583,74 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "更新服务日历",
-        "tags": [
-          "On-call/日历管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **服务日历管理**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/calendars/calendar-update",
-          "metadata": {
-            "sidebarTitle": "更新服务日历"
-          }
-        }
-      }
-    },
-    "/change/list": {
-      "post": {
-        "description": "在指定时间窗口内查询变更记录，支持过滤、搜索与分页。",
-        "operationId": "change-read-list",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ListChangeRequest"
+              },
               "example": {
-                "asc": false,
+                "start_time": 1716960000,
                 "end_time": 1717046400,
-                "include_events": false,
+                "p": 1,
+                "limit": 10,
                 "integration_ids": [
                   362
                 ],
-                "limit": 10,
                 "orderby": "start_time",
-                "p": 1,
-                "start_time": 1716960000
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ListChangeRequest"
+                "asc": false,
+                "include_events": false
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/channel/create": {
+      "post": {
+        "operationId": "channelCreate",
+        "summary": "创建协作空间",
+        "description": "创建协作空间，可同时创建默认分派策略和协作空间专属集成。",
+        "tags": [
+          "On-call/协作空间"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- `channel_name` 在账户内必须唯一，重名返回 `InvalidParameter`。\n- `group.method` 为 `p` 需要 Standard 及以上许可证，为 `i` 需要 Pro 许可证。超过当前套餐的协作空间数量上限同样返回 `NoLicense`。\n- 传入 `escalate_rule` 时，会同时创建一条名为 `Default` 的已启用分派策略，只有一个环节，对 `escalate_rule.target` 通知一次。\n- `plugin_ids` 中的每个 ID 会创建一个该类型的协作空间专属集成，集成名称为该类型名称。\n- `is_external_report_enabled` 为 `true` 时，响应中会额外返回 `external_report_token`。\n- 每次调用都会记录到账户审计日志。",
+          "href": "/zh/api-reference/on-call/channels/channel-create",
+          "metadata": {
+            "sidebarTitle": "创建协作空间"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "has_next_page": false,
-                    "items": [
-                      {
-                        "account_id": 10001,
-                        "change_id": "664a1b2c3d4e5f6a7b8c9d0e",
-                        "change_key": "deploy-api-server-2311",
-                        "change_status": "Done",
-                        "channel_id": 5001,
-                        "channel_name": "Production",
-                        "channel_status": "enabled",
-                        "description": "Rolling deploy to production cluster",
-                        "end_time": 1716963000,
-                        "integration_id": 362,
-                        "integration_name": "GitHub Deploy",
-                        "labels": {
-                          "env": "prod",
-                          "service": "api-server"
-                        },
-                        "last_time": 1716962700,
-                        "link": "https://github.com/acme/api-server/actions/runs/123",
-                        "start_time": 1716962400,
-                        "title": "Deploy api-server v2.3.1"
-                      }
-                    ],
-                    "total": 1
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/ListChangeResponse"
+                          "$ref": "#/components/schemas/ChannelCreateResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "channel_id": 6294542005131,
+                    "channel_name": "Production Alerts"
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -35434,6 +36658,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -35441,74 +36668,76 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "查询变更列表",
-        "tags": [
-          "On-call/变更管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n",
-          "href": "/zh/api-reference/on-call/changes/change-read-list",
-          "metadata": {
-            "sidebarTitle": "查询变更列表"
-          }
-        }
-      }
-    },
-    "/channel/create": {
-      "post": {
-        "description": "创建一个新的协作空间用于故障管理。",
-        "operationId": "channelCreate",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CreateChannelRequest"
+              },
               "example": {
-                "auto_resolve_mode": "trigger",
-                "auto_resolve_timeout": 86400,
+                "team_id": 3521074710131,
                 "channel_name": "Production Alerts",
                 "description": "Handles all production environment alerts",
                 "group": {
                   "method": "p",
+                  "equals": [
+                    [
+                      "labels.service"
+                    ]
+                  ],
                   "time_window": 10,
                   "window_type": "tumbling"
                 },
-                "team_id": 3521074710131
-              },
-              "schema": {
-                "$ref": "#/components/schemas/CreateChannelRequest"
+                "auto_resolve_timeout": 86400,
+                "auto_resolve_mode": "trigger"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/channel/delete": {
+      "post": {
+        "operationId": "channelDelete",
+        "summary": "删除协作空间",
+        "description": "删除已禁用的协作空间，并一并删除其下的策略和协作空间专属集成。",
+        "tags": [
+          "On-call/协作空间"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 仅 `disabled` 状态的协作空间可删除，其他状态返回 `InvalidParameter`。\n- 若仍有共享集成的路由规则（任一 case 或默认分支）指向该协作空间，返回 HTTP 400，`error.code` 为 `ReferenceExist`，`data.refs` 列出引用它的集成。请先通过 `POST /route/upsert` 把它从这些路由中移除。\n- 协作空间下的分派、静默、排除、抑制和订阅策略以及专属集成全部删除。协作空间本身为软删除：`POST /channel/info` 仍可查到，`status` 为 `deleted`。\n- `channel_id` 不存在时返回 `InvalidParameter`。\n- 调用者还必须拥有该协作空间的编辑权：账户所有者或管理员、协作空间创建者，或其管理团队成员（`managing_team_ids` 为空时为所属团队成员），否则返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志。",
+          "href": "/zh/api-reference/on-call/channels/channel-delete",
+          "metadata": {
+            "sidebarTitle": "删除协作空间"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "channel_id": 6294542005131,
-                    "channel_name": "API Test Channel"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/ChannelCreateResponse"
+                          "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -35516,6 +36745,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -35523,62 +36755,62 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "创建协作空间",
-        "tags": [
-          "On-call/协作空间"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/channels/channel-create",
-          "metadata": {
-            "sidebarTitle": "创建协作空间"
-          }
-        }
-      }
-    },
-    "/channel/delete": {
-      "post": {
-        "description": "删除协作空间。仅 `disabled` 状态的协作空间可删除，其下的分派、静默、排除和抑制策略会一并删除。当仍有集成路由引用该空间时调用失败。",
-        "operationId": "channelDelete",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {
-                "channel_id": 3521074710131
-              },
               "schema": {
                 "$ref": "#/components/schemas/ChannelIDRequest"
+              },
+              "example": {
+                "channel_id": 3521074710131
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/channel/disable": {
+      "post": {
+        "operationId": "channelDisable",
+        "summary": "禁用协作空间",
+        "description": "禁用协作空间；禁用期间新进入的告警事件全部丢弃。",
+        "tags": [
+          "On-call/协作空间"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 仅 `enabled` 状态的协作空间可禁用，其他状态返回 `InvalidParameter`。\n- 策略与集成均保留。告警处理链路最长约一分钟后才感知到新状态。\n- `channel_id` 不存在时返回 `InvalidParameter`。\n- 调用者还必须拥有该协作空间的编辑权：账户所有者或管理员、协作空间创建者，或其管理团队成员（`managing_team_ids` 为空时为所属团队成员），否则返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志。",
+          "href": "/zh/api-reference/on-call/channels/channel-disable",
+          "metadata": {
+            "sidebarTitle": "禁用协作空间"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -35586,6 +36818,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -35593,62 +36828,62 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "删除协作空间",
-        "tags": [
-          "On-call/协作空间"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/channels/channel-delete",
-          "metadata": {
-            "sidebarTitle": "删除协作空间"
-          }
-        }
-      }
-    },
-    "/channel/disable": {
-      "post": {
-        "description": "禁用协作空间以停止故障路由（不删除）；禁用后新事件会被直接丢弃。仅 `enabled` 状态的协作空间可禁用。",
-        "operationId": "channelDisable",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {
-                "channel_id": 3521074710131
-              },
               "schema": {
                 "$ref": "#/components/schemas/ChannelIDRequest"
+              },
+              "example": {
+                "channel_id": 3521074710131
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/channel/enable": {
+      "post": {
+        "operationId": "channelEnable",
+        "summary": "启用协作空间",
+        "description": "启用已禁用的协作空间，使其重新处理新的告警事件。",
+        "tags": [
+          "On-call/协作空间"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 仅 `disabled` 状态的协作空间可启用，其他状态返回 `InvalidParameter`。\n- `channel_id` 不存在时返回 `InvalidParameter`。\n- 调用者还必须拥有该协作空间的编辑权：账户所有者或管理员、协作空间创建者，或其管理团队成员（`managing_team_ids` 为空时为所属团队成员），否则返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志。",
+          "href": "/zh/api-reference/on-call/channels/channel-enable",
+          "metadata": {
+            "sidebarTitle": "启用协作空间"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -35656,6 +36891,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -35663,62 +36901,65 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "禁用协作空间",
-        "tags": [
-          "On-call/协作空间"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/channels/channel-disable",
-          "metadata": {
-            "sidebarTitle": "禁用协作空间"
-          }
-        }
-      }
-    },
-    "/channel/enable": {
-      "post": {
-        "description": "启用协作空间以恢复故障路由。仅 `disabled` 状态的协作空间可启用。",
-        "operationId": "channelEnable",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {
-                "channel_id": 3521074710131
-              },
               "schema": {
                 "$ref": "#/components/schemas/ChannelIDRequest"
+              },
+              "example": {
+                "channel_id": 3521074710131
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/channel/escalate/rule/create": {
+      "post": {
+        "operationId": "channelEscalateRuleCreate",
+        "summary": "创建分派策略",
+        "description": "创建分派策略，决定协作空间的故障通知谁、如何通知。",
+        "tags": [
+          "On-call/协作空间"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 策略按 `priority` 从小到大匹配，第一条启用且 `time_filters`、`filters` 都命中新故障的策略负责该故障，其后的策略不再匹配。不传 `priority` 时排在现有策略之后。\n- `template_id` 必须是已存在的通知模板，`person_ids` 中的成员必须存在，`team_ids` 中的团队必须有成员，否则返回 `InvalidParameter`。\n- 新建的策略为 `enabled` 状态。\n- `channel_id` 不存在时返回 `InvalidParameter`。\n- 调用者还必须拥有该协作空间的编辑权：账户所有者或管理员、协作空间创建者，或其管理团队成员（`managing_team_ids` 为空时为所属团队成员），否则返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志。",
+          "href": "/zh/api-reference/on-call/channels/channel-escalate-rule-create",
+          "metadata": {
+            "sidebarTitle": "创建分派策略"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/EmptyResponse"
+                          "$ref": "#/components/schemas/RuleCreateResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "rule_id": "69db2f72a0fe7db6448b1506",
+                    "rule_name": "On-call escalation"
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -35726,6 +36967,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -35733,155 +36977,81 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "启用协作空间",
-        "tags": [
-          "On-call/协作空间"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/channels/channel-enable",
-          "metadata": {
-            "sidebarTitle": "启用协作空间"
-          }
-        }
-      }
-    },
-    "/channel/escalate/rule/create": {
-      "post": {
-        "description": "创建分派策略，定义故障发生时通知谁以及何时通知。",
-        "operationId": "channelEscalateRuleCreate",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CreateEscalationRuleRequest"
+              },
               "example": {
                 "channel_id": 3521074710131,
+                "rule_name": "On-call escalation",
+                "template_id": "6321aad26c12104586a88916",
                 "description": "Notify primary on-call, then escalate to secondary after 30 minutes",
                 "layers": [
                   {
-                    "escalate_window": 30,
-                    "force_escalate": false,
-                    "max_times": 3,
-                    "notify_step": 10,
                     "target": {
-                      "by": {
-                        "follow_preference": true
-                      },
                       "person_ids": [
                         3790925372131
-                      ]
-                    }
+                      ],
+                      "by": {
+                        "follow_preference": true
+                      }
+                    },
+                    "max_times": 3,
+                    "notify_step": 10,
+                    "escalate_window": 30,
+                    "force_escalate": false
                   }
-                ],
-                "rule_name": "On-call escalation",
-                "template_id": "6321aad26c12104586a88916"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/CreateEscalationRuleRequest"
+                ]
               }
             }
-          },
-          "required": true
-        },
-        "responses": {
-          "200": {
-            "content": {
-              "application/json": {
-                "example": {
-                  "data": {
-                    "rule_id": "69db2f72a0fe7db6448b1506",
-                    "rule_name": "Test escalation rule"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/RuleCreateResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
-                }
-              }
-            },
-            "description": "成功"
-          },
-          "400": {
-            "$ref": "#/components/responses/BadRequest"
-          },
-          "401": {
-            "$ref": "#/components/responses/Unauthorized"
-          },
-          "429": {
-            "$ref": "#/components/responses/TooManyRequests"
-          },
-          "500": {
-            "$ref": "#/components/responses/ServerError"
-          }
-        },
-        "summary": "创建分派策略",
-        "tags": [
-          "On-call/协作空间"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/channels/channel-escalate-rule-create",
-          "metadata": {
-            "sidebarTitle": "创建分派策略"
           }
         }
       }
     },
     "/channel/escalate/rule/delete": {
       "post": {
-        "description": "删除分派策略。仅 `disabled` 状态的策略可删除。",
         "operationId": "channelEscalateRuleDelete",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "channel_id": 3521074710131,
-                "rule_id": "6621b23f4a2c5e0012ab34cd"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ChannelRuleIDRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "删除分派策略",
+        "description": "删除已禁用的分派策略，使其不再出现在协作空间的策略列表中。",
+        "tags": [
+          "On-call/协作空间"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 仅 `disabled` 状态的策略可删除，其他状态返回 `InvalidParameter`。\n- 策略为软删除：不再出现在列表中，但 `POST /channel/escalate/rule/info` 仍可查到，`status` 为 `deleted`。\n- `channel_id` 或 `rule_id` 不存在时返回 `InvalidParameter`。\n- 调用者还必须拥有该协作空间的编辑权：账户所有者或管理员、协作空间创建者，或其管理团队成员（`managing_team_ids` 为空时为所属团队成员），否则返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志。",
+          "href": "/zh/api-reference/on-call/channels/channel-escalate-rule-delete",
+          "metadata": {
+            "sidebarTitle": "删除分派策略"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -35889,6 +37059,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -35896,63 +37069,63 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "删除分派策略",
-        "tags": [
-          "On-call/协作空间"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/channels/channel-escalate-rule-delete",
-          "metadata": {
-            "sidebarTitle": "删除分派策略"
-          }
-        }
-      }
-    },
-    "/channel/escalate/rule/disable": {
-      "post": {
-        "description": "禁用分派策略而不删除。仅 `enabled` 状态的策略可禁用。",
-        "operationId": "channelEscalateRuleDisable",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ChannelRuleIDRequest"
+              },
               "example": {
                 "channel_id": 3521074710131,
                 "rule_id": "6621b23f4a2c5e0012ab34cd"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ChannelRuleIDRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/channel/escalate/rule/disable": {
+      "post": {
+        "operationId": "channelEscalateRuleDisable",
+        "summary": "禁用分派策略",
+        "description": "禁用分派策略但不删除。",
+        "tags": [
+          "On-call/协作空间"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 仅 `enabled` 状态的策略可禁用，其他状态返回 `InvalidParameter`。\n- 禁用后的策略不再接收新故障，已通过它分派的故障也不再收到它的通知和升级。\n- `channel_id` 或 `rule_id` 不存在时返回 `InvalidParameter`。\n- 调用者还必须拥有该协作空间的编辑权：账户所有者或管理员、协作空间创建者，或其管理团队成员（`managing_team_ids` 为空时为所属团队成员），否则返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志。",
+          "href": "/zh/api-reference/on-call/channels/channel-escalate-rule-disable",
+          "metadata": {
+            "sidebarTitle": "禁用分派策略"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -35960,6 +37133,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -35967,63 +37143,63 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "禁用分派策略",
-        "tags": [
-          "On-call/协作空间"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/channels/channel-escalate-rule-disable",
-          "metadata": {
-            "sidebarTitle": "禁用分派策略"
-          }
-        }
-      }
-    },
-    "/channel/escalate/rule/enable": {
-      "post": {
-        "description": "启用已禁用的分派策略。仅 `disabled` 状态的策略可启用。",
-        "operationId": "channelEscalateRuleEnable",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ChannelRuleIDRequest"
+              },
               "example": {
                 "channel_id": 3521074710131,
                 "rule_id": "6621b23f4a2c5e0012ab34cd"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ChannelRuleIDRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/channel/escalate/rule/enable": {
+      "post": {
+        "operationId": "channelEscalateRuleEnable",
+        "summary": "启用分派策略",
+        "description": "启用已禁用的分派策略，使其重新参与新故障的分派。",
+        "tags": [
+          "On-call/协作空间"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 仅 `disabled` 状态的策略可启用，其他状态返回 `InvalidParameter`。\n- `channel_id` 或 `rule_id` 不存在时返回 `InvalidParameter`。\n- 调用者还必须拥有该协作空间的编辑权：账户所有者或管理员、协作空间创建者，或其管理团队成员（`managing_team_ids` 为空时为所属团队成员），否则返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志。",
+          "href": "/zh/api-reference/on-call/channels/channel-escalate-rule-enable",
+          "metadata": {
+            "sidebarTitle": "启用分派策略"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -36031,6 +37207,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -36038,95 +37217,95 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "启用分派策略",
-        "tags": [
-          "On-call/协作空间"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/channels/channel-escalate-rule-enable",
-          "metadata": {
-            "sidebarTitle": "启用分派策略"
-          }
-        }
-      }
-    },
-    "/channel/escalate/rule/info": {
-      "post": {
-        "description": "获取指定分派策略的详细信息。",
-        "operationId": "channelEscalateRuleInfo",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {
-                "channel_id": 1001,
-                "rule_id": "6621b23f4a2c5e0012ab34d0"
-              },
               "schema": {
                 "$ref": "#/components/schemas/ChannelRuleIDRequest"
+              },
+              "example": {
+                "channel_id": 3521074710131,
+                "rule_id": "6621b23f4a2c5e0012ab34cd"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/channel/escalate/rule/info": {
+      "post": {
+        "operationId": "channelEscalateRuleInfo",
+        "summary": "获取分派策略详情",
+        "description": "返回协作空间下的单条分派策略，包括环节、时间窗口和过滤条件。",
+        "tags": [
+          "On-call/协作空间"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间查看**（`on-call`） 或 **协作空间管理**（`on-call`） 或 **故障查看**（`on-call`） 或 **故障管理**（`on-call`） |\n\n## 使用说明\n\n- 已删除的策略仍会返回，`status` 为 `deleted`。\n- `channel_id` 或 `rule_id` 不存在时返回 `InvalidParameter`。",
+          "href": "/zh/api-reference/on-call/channels/channel-escalate-rule-info",
+          "metadata": {
+            "sidebarTitle": "获取分派策略详情"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/EscalateRuleItem"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "account_id": 2451002751131,
-                    "aggr_window": 0,
                     "channel_id": 6193426913131,
-                    "created_at": 1773997289,
+                    "priority": 0,
+                    "aggr_window": 0,
+                    "rule_name": "Default",
                     "description": "",
-                    "filters": [],
                     "layers": [
                       {
-                        "escalate_window": 30,
-                        "force_escalate": false,
                         "max_times": 1,
                         "notify_step": 10,
                         "target": {
-                          "by": {
-                            "follow_preference": true
-                          },
                           "person_ids": [
                             3790925372131
                           ],
+                          "by": {
+                            "follow_preference": true
+                          },
                           "webhooks": null
-                        }
+                        },
+                        "escalate_window": 30,
+                        "force_escalate": false
                       }
                     ],
-                    "priority": 0,
-                    "rule_id": "69bd0ce95a238693176c1d66",
-                    "rule_name": "Default",
+                    "time_filters": [],
+                    "filters": [],
                     "status": "enabled",
                     "template_id": "6321aad26c12104586a88916",
-                    "time_filters": [],
-                    "updated_at": 1773997289,
-                    "updated_by": 3790925372131
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/EscalateRuleItem"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                    "rule_id": "69bd0ce95a238693176c1d66",
+                    "updated_by": 3790925372131,
+                    "created_at": 1773997289,
+                    "updated_at": 1773997289
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -36134,6 +37313,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -36141,98 +37323,172 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "获取分派策略详情",
-        "tags": [
-          "On-call/协作空间"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间查看**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/channels/channel-escalate-rule-info",
-          "metadata": {
-            "sidebarTitle": "获取分派策略详情"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ChannelRuleIDRequest"
+              },
+              "example": {
+                "channel_id": 1001,
+                "rule_id": "6621b23f4a2c5e0012ab34d0"
+              }
+            }
           }
         }
       }
     },
     "/channel/escalate/rule/list": {
       "post": {
-        "description": "查询协作空间下的所有分派策略。",
         "operationId": "channelEscalateRuleList",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "channel_id": 1001
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ChannelScopedListRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "查询分派策略列表",
+        "description": "按匹配顺序列出协作空间的分派策略。",
+        "tags": [
+          "On-call/协作空间"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间查看**（`on-call`） 或 **协作空间管理**（`on-call`） 或 **故障查看**（`on-call`） 或 **故障管理**（`on-call`） |\n\n## 使用说明\n\n- `channel_id` 不存在时返回 `InvalidParameter`。",
+          "href": "/zh/api-reference/on-call/channels/channel-escalate-rule-list",
+          "metadata": {
+            "sidebarTitle": "查询分派策略列表"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/ListEscalationRulesResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "items": [
                       {
                         "account_id": 2451002751131,
-                        "aggr_window": 0,
                         "channel_id": 6193426913131,
-                        "created_at": 1773997289,
+                        "priority": 0,
+                        "aggr_window": 0,
+                        "rule_name": "Default",
                         "description": "",
-                        "filters": [],
                         "layers": [
                           {
-                            "escalate_window": 30,
-                            "force_escalate": false,
                             "max_times": 1,
                             "notify_step": 10,
                             "target": {
-                              "by": {
-                                "follow_preference": true
-                              },
                               "person_ids": [
                                 3790925372131
                               ],
+                              "by": {
+                                "follow_preference": true
+                              },
                               "webhooks": null
-                            }
+                            },
+                            "escalate_window": 30,
+                            "force_escalate": false
                           }
                         ],
-                        "priority": 0,
-                        "rule_id": "69bd0ce95a238693176c1d66",
-                        "rule_name": "Default",
+                        "time_filters": [],
+                        "filters": [],
                         "status": "enabled",
                         "template_id": "6321aad26c12104586a88916",
-                        "time_filters": [],
-                        "updated_at": 1773997289,
-                        "updated_by": 3790925372131
+                        "rule_id": "69bd0ce95a238693176c1d66",
+                        "updated_by": 3790925372131,
+                        "created_at": 1773997289,
+                        "updated_at": 1773997289
                       }
                     ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "429": {
+            "$ref": "#/components/responses/TooManyRequests"
+          },
+          "500": {
+            "$ref": "#/components/responses/ServerError"
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ChannelScopedListRequest"
+              },
+              "example": {
+                "channel_id": 1001
+              }
+            }
+          }
+        }
+      }
+    },
+    "/channel/escalate/rule/update": {
+      "post": {
+        "operationId": "channelEscalateRuleUpdate",
+        "summary": "更新分派策略",
+        "description": "整体替换已有分派策略的配置。",
+        "tags": [
+          "On-call/协作空间"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 整体替换：未传的 `description`、`aggr_window`、`time_filters`、`filters` 会被重置为空或 `0`。只有 `priority` 未传时保持原值。\n- 校验规则与创建相同。不会改变策略的 `status`，启停请使用启用、禁用接口。\n- `channel_id` 或 `rule_id` 不存在时返回 `InvalidParameter`。\n- 调用者还必须拥有该协作空间的编辑权：账户所有者或管理员、协作空间创建者，或其管理团队成员（`managing_team_ids` 为空时为所属团队成员），否则返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志。",
+          "href": "/zh/api-reference/on-call/channels/channel-escalate-rule-update",
+          "metadata": {
+            "sidebarTitle": "更新分派策略"
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "成功",
+            "content": {
+              "application/json": {
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/ListEscalationRulesResponse"
+                          "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -36240,6 +37496,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -36247,31 +37506,24 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "查询分派策略列表",
-        "tags": [
-          "On-call/协作空间"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间查看**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/channels/channel-escalate-rule-list",
-          "metadata": {
-            "sidebarTitle": "查询分派策略列表"
-          }
-        }
-      }
-    },
-    "/channel/escalate/rule/update": {
-      "post": {
-        "description": "更新已有分派策略的配置。",
-        "operationId": "channelEscalateRuleUpdate",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/UpdateEscalationRuleRequest"
+              },
               "example": {
                 "channel_id": 1001,
+                "rule_id": "6621b23f4a2c5e0012ab34d0",
+                "template_id": "6621b23f4a2c5e0012ab34d1",
+                "rule_name": "Default escalation",
                 "layers": [
                   {
                     "target": {
+                      "person_ids": [
+                        42
+                      ],
                       "by": {
                         "critical": [
                           "voice"
@@ -36279,50 +37531,62 @@
                         "warning": [
                           "sms"
                         ]
-                      },
-                      "person_ids": [
-                        42
-                      ]
+                      }
                     }
                   }
-                ],
-                "rule_id": "6621b23f4a2c5e0012ab34d0",
-                "rule_name": "Default escalation",
-                "template_id": "6621b23f4a2c5e0012ab34d1"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/UpdateEscalationRuleRequest"
+                ]
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/channel/info": {
+      "post": {
+        "operationId": "channelInfo",
+        "summary": "获取协作空间详情",
+        "description": "返回单个协作空间的完整配置，以及近 30 天内活跃故障的统计。",
+        "tags": [
+          "On-call/协作空间"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 已删除的协作空间仍会返回，`status` 为 `deleted`。\n- 私有协作空间（`is_private: true`）仅对账户所有者或管理员、创建者、所属团队或管理团队成员可见，其他调用者返回 `AccessDenied`。\n- 此接口不返回 `team_name`、`creator_name`、`is_starred`，需要时请用 `POST /channel/list`。\n- `channel_id` 不存在时返回 `InvalidParameter`。",
+          "href": "/zh/api-reference/on-call/channels/channel-info",
+          "metadata": {
+            "sidebarTitle": "获取协作空间详情"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/EmptyResponse"
+                          "$ref": "#/components/schemas/ChannelItem"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "channel_id": 1001,
+                    "channel_name": "Production Alerts",
+                    "status": "enabled",
+                    "team_id": 10
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -36330,6 +37594,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -36337,67 +37604,70 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "更新分派策略",
-        "tags": [
-          "On-call/协作空间"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/channels/channel-escalate-rule-update",
-          "metadata": {
-            "sidebarTitle": "更新分派策略"
-          }
-        }
-      }
-    },
-    "/channel/info": {
-      "post": {
-        "description": "获取指定协作空间的详细信息。",
-        "operationId": "channelInfo",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {
-                "channel_id": 1001
-              },
               "schema": {
                 "$ref": "#/components/schemas/ChannelInfoRequest"
+              },
+              "example": {
+                "channel_id": 1001
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/channel/infos": {
+      "post": {
+        "operationId": "channelInfos",
+        "summary": "批量获取协作空间",
+        "description": "一次返回最多 1,000 个协作空间的 ID、名称和状态。",
+        "tags": [
+          "On-call/协作空间"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 不存在的 ID 会被忽略；已删除的协作空间也会返回，`status` 为 `deleted`。\n- 结果按协作空间创建顺序排列，而不是 `channel_ids` 的顺序。\n- 私有协作空间不做可见性过滤，同样返回。",
+          "href": "/zh/api-reference/on-call/channels/channel-infos",
+          "metadata": {
+            "sidebarTitle": "批量获取协作空间"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "channel_id": 1001,
-                    "channel_name": "Production Alerts",
-                    "status": "enabled",
-                    "team_id": 10
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/ChannelItem"
+                          "$ref": "#/components/schemas/ChannelInfosResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "items": [
+                      {
+                        "channel_id": 1001,
+                        "channel_name": "Production Alerts",
+                        "status": "enabled"
+                      }
+                    ]
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -36405,6 +37675,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -36412,73 +37685,68 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "获取协作空间详情",
-        "tags": [
-          "On-call/协作空间"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |",
-          "href": "/zh/api-reference/on-call/channels/channel-info",
-          "metadata": {
-            "sidebarTitle": "获取协作空间详情"
-          }
-        }
-      }
-    },
-    "/channel/infos": {
-      "post": {
-        "description": "通过 ID 列表批量获取协作空间信息。",
-        "operationId": "channelInfos",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ChannelInfosRequest"
+              },
               "example": {
                 "channel_ids": [
                   1001,
                   1002
                 ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ChannelInfosRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/channel/inhibit/rule/create": {
+      "post": {
+        "operationId": "channelInhibitRuleCreate",
+        "summary": "创建抑制策略",
+        "description": "创建抑制策略，在相关的源告警仍处于活跃状态时屏蔽新的告警事件。",
+        "tags": [
+          "On-call/协作空间"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 需要 Standard 及以上许可证，否则返回 `NoLicense`。\n- 当新事件命中 `target_filters`，且同一协作空间内存在一条未恢复、`alert_key` 不同、命中 `source_filters`、在该事件前 10 分钟内开始、并且 `equals` 中每个字段取值都相同的告警时，该事件被抑制。\n- `equals` 或 `source_filters` 为空，或新事件缺少 `equals` 中列出的标签时，该策略永远不会生效。\n- 抑制策略在排除和静默策略之后检查，命中第一条即生效。\n- `channel_id` 不存在时返回 `InvalidParameter`。\n- 调用者还必须拥有该协作空间的编辑权：账户所有者或管理员、协作空间创建者，或其管理团队成员（`managing_team_ids` 为空时为所属团队成员），否则返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志。",
+          "href": "/zh/api-reference/on-call/channels/channel-inhibit-rule-create",
+          "metadata": {
+            "sidebarTitle": "创建抑制策略"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "items": [
-                      {
-                        "channel_id": 1001,
-                        "channel_name": "Production Alerts",
-                        "status": "enabled"
-                      }
-                    ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/ChannelInfosResponse"
+                          "$ref": "#/components/schemas/RuleCreateResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "rule_id": "69db2f69a0fe7db6448b1504",
+                    "rule_name": "Suppress Info when Critical fires"
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -36486,6 +37754,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -36493,35 +37764,21 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "批量获取协作空间",
-        "tags": [
-          "On-call/协作空间"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |",
-          "href": "/zh/api-reference/on-call/channels/channel-infos",
-          "metadata": {
-            "sidebarTitle": "批量获取协作空间"
-          }
-        }
-      }
-    },
-    "/channel/inhibit/rule/create": {
-      "post": {
-        "description": "创建一条抑制策略，当高优先级告警触发时抑制低优先级告警。",
-        "operationId": "channelInhibitRuleCreate",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CreateInhibitRuleRequest"
+              },
               "example": {
                 "channel_id": 3521074710131,
+                "rule_name": "Suppress Info when Critical fires",
                 "description": "When a Critical alert fires, suppress matching Info alerts",
                 "equals": [
                   "labels.cluster",
                   "labels.service"
                 ],
-                "is_directly_discard": false,
-                "rule_name": "Suppress Info when Critical fires",
                 "source_filters": [
                   [
                     {
@@ -36543,44 +37800,55 @@
                       ]
                     }
                   ]
-                ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/CreateInhibitRuleRequest"
+                ],
+                "is_directly_discard": false
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/channel/inhibit/rule/delete": {
+      "post": {
+        "operationId": "channelInhibitRuleDelete",
+        "summary": "删除抑制策略",
+        "description": "删除已禁用的抑制策略，使其不再出现在协作空间的策略列表中。",
+        "tags": [
+          "On-call/协作空间"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 仅 `disabled` 状态的策略可删除，其他状态返回 `InvalidParameter`。\n- `channel_id` 或 `rule_id` 不存在时返回 `InvalidParameter`。\n- 调用者还必须拥有该协作空间的编辑权：账户所有者或管理员、协作空间创建者，或其管理团队成员（`managing_team_ids` 为空时为所属团队成员），否则返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志。",
+          "href": "/zh/api-reference/on-call/channels/channel-inhibit-rule-delete",
+          "metadata": {
+            "sidebarTitle": "删除抑制策略"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "rule_id": "69db2f69a0fe7db6448b1504",
-                    "rule_name": "Test inhibit rule"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/RuleCreateResponse"
+                          "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -36588,6 +37856,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -36595,63 +37866,63 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "创建抑制策略",
-        "tags": [
-          "On-call/协作空间"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/channels/channel-inhibit-rule-create",
-          "metadata": {
-            "sidebarTitle": "创建抑制策略"
-          }
-        }
-      }
-    },
-    "/channel/inhibit/rule/delete": {
-      "post": {
-        "description": "删除抑制策略。仅 `disabled` 状态的策略可删除。",
-        "operationId": "channelInhibitRuleDelete",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ChannelRuleIDRequest"
+              },
               "example": {
                 "channel_id": 3521074710131,
                 "rule_id": "6621b23f4a2c5e0012ab34cd"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ChannelRuleIDRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/channel/inhibit/rule/disable": {
+      "post": {
+        "operationId": "channelInhibitRuleDisable",
+        "summary": "禁用抑制策略",
+        "description": "禁用抑制策略但不删除。",
+        "tags": [
+          "On-call/协作空间"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 仅 `enabled` 状态的策略可禁用，其他状态返回 `InvalidParameter`。\n- `channel_id` 或 `rule_id` 不存在时返回 `InvalidParameter`。\n- 调用者还必须拥有该协作空间的编辑权：账户所有者或管理员、协作空间创建者，或其管理团队成员（`managing_team_ids` 为空时为所属团队成员），否则返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志。",
+          "href": "/zh/api-reference/on-call/channels/channel-inhibit-rule-disable",
+          "metadata": {
+            "sidebarTitle": "禁用抑制策略"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -36659,6 +37930,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -36666,63 +37940,63 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "删除抑制策略",
-        "tags": [
-          "On-call/协作空间"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/channels/channel-inhibit-rule-delete",
-          "metadata": {
-            "sidebarTitle": "删除抑制策略"
-          }
-        }
-      }
-    },
-    "/channel/inhibit/rule/disable": {
-      "post": {
-        "description": "禁用抑制策略而不删除。仅 `enabled` 状态的策略可禁用。",
-        "operationId": "channelInhibitRuleDisable",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ChannelRuleIDRequest"
+              },
               "example": {
                 "channel_id": 3521074710131,
                 "rule_id": "6621b23f4a2c5e0012ab34cd"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ChannelRuleIDRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/channel/inhibit/rule/enable": {
+      "post": {
+        "operationId": "channelInhibitRuleEnable",
+        "summary": "启用抑制策略",
+        "description": "启用已禁用的抑制策略，使其重新抑制命中的告警事件。",
+        "tags": [
+          "On-call/协作空间"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 需要 Standard 及以上许可证，否则返回 `NoLicense`。\n- 仅 `disabled` 状态的策略可启用，其他状态返回 `InvalidParameter`。\n- `channel_id` 或 `rule_id` 不存在时返回 `InvalidParameter`。\n- 调用者还必须拥有该协作空间的编辑权：账户所有者或管理员、协作空间创建者，或其管理团队成员（`managing_team_ids` 为空时为所属团队成员），否则返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志。",
+          "href": "/zh/api-reference/on-call/channels/channel-inhibit-rule-enable",
+          "metadata": {
+            "sidebarTitle": "启用抑制策略"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -36730,6 +38004,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -36737,138 +38014,77 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "禁用抑制策略",
-        "tags": [
-          "On-call/协作空间"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/channels/channel-inhibit-rule-disable",
-          "metadata": {
-            "sidebarTitle": "禁用抑制策略"
-          }
-        }
-      }
-    },
-    "/channel/inhibit/rule/enable": {
-      "post": {
-        "description": "启用已禁用的抑制策略。仅 `disabled` 状态的策略可启用。",
-        "operationId": "channelInhibitRuleEnable",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ChannelRuleIDRequest"
+              },
               "example": {
                 "channel_id": 3521074710131,
                 "rule_id": "6621b23f4a2c5e0012ab34cd"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ChannelRuleIDRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/channel/inhibit/rule/list": {
+      "post": {
+        "operationId": "channelInhibitRuleList",
+        "summary": "查询抑制策略列表",
+        "description": "按创建时间先后列出协作空间的抑制策略。",
+        "tags": [
+          "On-call/协作空间"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间查看**（`on-call`） 或 **协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- `channel_id` 不存在时返回 `InvalidParameter`。",
+          "href": "/zh/api-reference/on-call/channels/channel-inhibit-rule-list",
+          "metadata": {
+            "sidebarTitle": "查询抑制策略列表"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/EmptyResponse"
+                          "$ref": "#/components/schemas/ListInhibitRulesResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
-                }
-              }
-            },
-            "description": "成功"
-          },
-          "400": {
-            "$ref": "#/components/responses/BadRequest"
-          },
-          "401": {
-            "$ref": "#/components/responses/Unauthorized"
-          },
-          "429": {
-            "$ref": "#/components/responses/TooManyRequests"
-          },
-          "500": {
-            "$ref": "#/components/responses/ServerError"
-          }
-        },
-        "summary": "启用抑制策略",
-        "tags": [
-          "On-call/协作空间"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/channels/channel-inhibit-rule-enable",
-          "metadata": {
-            "sidebarTitle": "启用抑制策略"
-          }
-        }
-      }
-    },
-    "/channel/inhibit/rule/list": {
-      "post": {
-        "description": "查询为指定协作空间配置的所有抑制策略。",
-        "operationId": "channelInhibitRuleList",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "channel_id": 1001
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ChannelScopedListRequest"
-              }
-            }
-          },
-          "required": true
-        },
-        "responses": {
-          "200": {
-            "content": {
-              "application/json": {
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "items": [
                       {
                         "account_id": 2451002751131,
                         "channel_id": 5967964835131,
-                        "created_at": 1773979184,
-                        "description": "",
-                        "equals": [
-                          "data_source_id",
-                          "labels._account_id"
-                        ],
-                        "is_directly_discard": false,
-                        "rule_id": "69bcc630b9e63df36603e425",
                         "rule_name": "Suppress downstream alerts",
+                        "description": "",
                         "source_filters": [
                           [
                             {
                               "key": "severity",
                               "oper": "IN",
                               "vals": [
-                                "Info"
+                                "Critical"
                               ]
                             }
                           ]
                         ],
-                        "status": "enabled",
                         "target_filters": [
                           [
                             {
@@ -36880,31 +38096,22 @@
                             }
                           ]
                         ],
-                        "updated_at": 1773979184,
-                        "updated_by": 3790925372131
+                        "equals": [
+                          "labels.cluster",
+                          "labels.service"
+                        ],
+                        "is_directly_discard": false,
+                        "status": "enabled",
+                        "rule_id": "69bcc630b9e63df36603e425",
+                        "updated_by": 3790925372131,
+                        "created_at": 1773979184,
+                        "updated_at": 1773979184
                       }
                     ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/ListInhibitRulesResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -36912,6 +38119,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -36919,67 +38129,150 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "查询抑制策略列表",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ChannelScopedListRequest"
+              },
+              "example": {
+                "channel_id": 1001
+              }
+            }
+          }
+        }
+      }
+    },
+    "/channel/inhibit/rule/update": {
+      "post": {
+        "operationId": "channelInhibitRuleUpdate",
+        "summary": "更新抑制策略",
+        "description": "整体替换已有抑制策略的配置。",
         "tags": [
           "On-call/协作空间"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间查看**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/channels/channel-inhibit-rule-list",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 整体替换：未传的 `source_filters`、`target_filters` 会被清空，未传 `is_directly_discard` 视为 `false`，未传 `description` 会被清空。\n- `channel_id` 或 `rule_id` 不存在时返回 `InvalidParameter`。\n- 调用者还必须拥有该协作空间的编辑权：账户所有者或管理员、协作空间创建者，或其管理团队成员（`managing_team_ids` 为空时为所属团队成员），否则返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志。",
+          "href": "/zh/api-reference/on-call/channels/channel-inhibit-rule-update",
           "metadata": {
-            "sidebarTitle": "查询抑制策略列表"
+            "sidebarTitle": "更新抑制策略"
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "成功",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/EmptyResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "429": {
+            "$ref": "#/components/responses/TooManyRequests"
+          },
+          "500": {
+            "$ref": "#/components/responses/ServerError"
           }
-        }
-      }
-    },
-    "/channel/inhibit/rule/update": {
-      "post": {
-        "description": "更新已有抑制策略的配置。",
-        "operationId": "channelInhibitRuleUpdate",
+        },
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/UpdateInhibitRuleRequest"
+              },
               "example": {
                 "channel_id": 1001,
+                "rule_id": "6621b23f4a2c5e0012ab34ce",
+                "rule_name": "Suppress downstream",
                 "equals": [
                   "labels.cluster"
-                ],
-                "rule_id": "6621b23f4a2c5e0012ab34ce",
-                "rule_name": "Suppress downstream"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/UpdateInhibitRuleRequest"
+                ]
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/channel/list": {
+      "post": {
+        "operationId": "channelList",
+        "summary": "查询协作空间列表",
+        "description": "分页查询调用者可见的协作空间，支持过滤和排序。",
+        "tags": [
+          "On-call/协作空间"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 不加过滤条件时返回账户内全部协作空间，但不包含调用者无权访问的私有协作空间。已删除的协作空间不会返回。\n- `is_my_team` 与 `is_my_starred` 同时为 `true` 时返回 `InvalidParameter`。`is_my_managed` 优先于这两者。使用 `is_my_managed` 或 `is_my_team` 时忽略 `team_ids`。\n- `is_brief: true` 时每项只含 `channel_id`、`channel_name`、`description`、`status`、`is_starred`，并一次返回全部结果。\n- 请始终传入 `p`。不传时虽然返回第一页，但只要有结果 `has_next_page` 就恒为 `true`。",
+          "href": "/zh/api-reference/on-call/channels/channel-list",
+          "metadata": {
+            "sidebarTitle": "查询协作空间列表"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/EmptyResponse"
+                          "$ref": "#/components/schemas/ListChannelsResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "total": 42,
+                    "has_next_page": true,
+                    "items": [
+                      {
+                        "channel_id": 1001,
+                        "channel_name": "Production Alerts",
+                        "status": "enabled"
+                      }
+                    ]
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -36987,6 +38280,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -36994,75 +38290,68 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "更新抑制策略",
-        "tags": [
-          "On-call/协作空间"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/channels/channel-inhibit-rule-update",
-          "metadata": {
-            "sidebarTitle": "更新抑制策略"
-          }
-        }
-      }
-    },
-    "/channel/list": {
-      "post": {
-        "description": "查询当前用户可访问的协作空间列表，支持过滤条件。",
-        "operationId": "channelList",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ListChannelsRequest"
+              },
               "example": {
-                "asc": false,
+                "p": 1,
                 "limit": 20,
                 "orderby": "created_at",
-                "p": 1
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ListChannelsRequest"
+                "asc": false
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/channel/silence/rule/create": {
+      "post": {
+        "operationId": "channelSilenceRuleCreate",
+        "summary": "创建静默策略",
+        "description": "创建静默策略，在时间窗口内屏蔽或丢弃命中的告警事件。",
+        "tags": [
+          "On-call/协作空间"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- `time_filter`（一次性窗口）与 `time_filters`（周期窗口）必须且只能设置其一，且 `filters` 至少包含一个条件，否则返回 `InvalidParameter`。\n- 每个进入的事件依次经过排除策略、静默策略、抑制策略。命中第一条启用、时间窗口覆盖当前时刻且 `filters` 匹配的静默策略即生效。\n- 设置 `from_incident_id` 时，每个故障只能有一条启用的静默策略，再次创建返回 `InvalidParameter`。\n- `channel_id` 不存在时返回 `InvalidParameter`。\n- 调用者还必须拥有该协作空间的编辑权：账户所有者或管理员、协作空间创建者，或其管理团队成员（`managing_team_ids` 为空时为所属团队成员），否则返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志。",
+          "href": "/zh/api-reference/on-call/channels/channel-silence-rule-create",
+          "metadata": {
+            "sidebarTitle": "创建静默策略"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "has_next_page": true,
-                    "items": [
-                      {
-                        "channel_id": 1001,
-                        "channel_name": "Production Alerts",
-                        "status": "enabled"
-                      }
-                    ],
-                    "total": 42
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/ListChannelsResponse"
+                          "$ref": "#/components/schemas/RuleCreateResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "rule_id": "69db2f66a0fe7db6448b1503",
+                    "rule_name": "Maintenance window silence"
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -37070,6 +38359,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -37077,29 +38369,21 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "查询协作空间列表",
-        "tags": [
-          "On-call/协作空间"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |",
-          "href": "/zh/api-reference/on-call/channels/channel-list",
-          "metadata": {
-            "sidebarTitle": "查询协作空间列表"
-          }
-        }
-      }
-    },
-    "/channel/silence/rule/create": {
-      "post": {
-        "description": "创建一条静默策略，用于抑制满足特定条件的通知。",
-        "operationId": "channelSilenceRuleCreate",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CreateSilenceRuleRequest"
+              },
               "example": {
                 "channel_id": 3521074710131,
+                "rule_name": "Maintenance window silence",
                 "description": "Silence all Info alerts during planned maintenance",
+                "time_filter": {
+                  "start_time": 1773388800,
+                  "end_time": 1773414000
+                },
                 "filters": [
                   [
                     {
@@ -37111,49 +38395,54 @@
                     }
                   ]
                 ],
-                "is_directly_discard": false,
-                "rule_name": "Maintenance window silence",
-                "time_filter": {
-                  "end_time": 1773414000,
-                  "start_time": 1773388800
-                }
-              },
-              "schema": {
-                "$ref": "#/components/schemas/CreateSilenceRuleRequest"
+                "is_directly_discard": false
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/channel/silence/rule/delete": {
+      "post": {
+        "operationId": "channelSilenceRuleDelete",
+        "summary": "删除静默策略",
+        "description": "删除已禁用的静默策略，使其不再出现在协作空间的策略列表中。",
+        "tags": [
+          "On-call/协作空间"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 仅 `disabled` 状态的策略可删除，其他状态返回 `InvalidParameter`。\n- `channel_id` 或 `rule_id` 不存在时返回 `InvalidParameter`。\n- 调用者还必须拥有该协作空间的编辑权：账户所有者或管理员、协作空间创建者，或其管理团队成员（`managing_team_ids` 为空时为所属团队成员），否则返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志。",
+          "href": "/zh/api-reference/on-call/channels/channel-silence-rule-delete",
+          "metadata": {
+            "sidebarTitle": "删除静默策略"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "rule_id": "69db2f66a0fe7db6448b1503",
-                    "rule_name": "Test silence rule"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/RuleCreateResponse"
+                          "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -37161,6 +38450,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -37168,63 +38460,63 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "创建静默策略",
-        "tags": [
-          "On-call/协作空间"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/channels/channel-silence-rule-create",
-          "metadata": {
-            "sidebarTitle": "创建静默策略"
-          }
-        }
-      }
-    },
-    "/channel/silence/rule/delete": {
-      "post": {
-        "description": "删除静默策略。仅 `disabled` 状态的策略可删除。",
-        "operationId": "channelSilenceRuleDelete",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ChannelRuleIDRequest"
+              },
               "example": {
                 "channel_id": 3521074710131,
                 "rule_id": "6621b23f4a2c5e0012ab34cd"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ChannelRuleIDRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/channel/silence/rule/disable": {
+      "post": {
+        "operationId": "channelSilenceRuleDisable",
+        "summary": "禁用静默策略",
+        "description": "禁用静默策略但不删除。",
+        "tags": [
+          "On-call/协作空间"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 仅 `enabled` 状态的策略可禁用，其他状态返回 `InvalidParameter`。\n- `channel_id` 或 `rule_id` 不存在时返回 `InvalidParameter`。\n- 调用者还必须拥有该协作空间的编辑权：账户所有者或管理员、协作空间创建者，或其管理团队成员（`managing_team_ids` 为空时为所属团队成员），否则返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志。",
+          "href": "/zh/api-reference/on-call/channels/channel-silence-rule-disable",
+          "metadata": {
+            "sidebarTitle": "禁用静默策略"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -37232,6 +38524,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -37239,63 +38534,63 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "删除静默策略",
-        "tags": [
-          "On-call/协作空间"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/channels/channel-silence-rule-delete",
-          "metadata": {
-            "sidebarTitle": "删除静默策略"
-          }
-        }
-      }
-    },
-    "/channel/silence/rule/disable": {
-      "post": {
-        "description": "禁用静默策略而不删除。仅 `enabled` 状态的策略可禁用。",
-        "operationId": "channelSilenceRuleDisable",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ChannelRuleIDRequest"
+              },
               "example": {
                 "channel_id": 3521074710131,
                 "rule_id": "6621b23f4a2c5e0012ab34cd"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ChannelRuleIDRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/channel/silence/rule/enable": {
+      "post": {
+        "operationId": "channelSilenceRuleEnable",
+        "summary": "启用静默策略",
+        "description": "启用已禁用的静默策略，使其重新静默命中的告警事件。",
+        "tags": [
+          "On-call/协作空间"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 仅 `disabled` 状态的策略可启用，其他状态返回 `InvalidParameter`。\n- `channel_id` 或 `rule_id` 不存在时返回 `InvalidParameter`。\n- 调用者还必须拥有该协作空间的编辑权：账户所有者或管理员、协作空间创建者，或其管理团队成员（`managing_team_ids` 为空时为所属团队成员），否则返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志。",
+          "href": "/zh/api-reference/on-call/channels/channel-silence-rule-enable",
+          "metadata": {
+            "sidebarTitle": "启用静默策略"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -37303,6 +38598,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -37310,63 +38608,96 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "禁用静默策略",
-        "tags": [
-          "On-call/协作空间"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/channels/channel-silence-rule-disable",
-          "metadata": {
-            "sidebarTitle": "禁用静默策略"
-          }
-        }
-      }
-    },
-    "/channel/silence/rule/enable": {
-      "post": {
-        "description": "启用已禁用的静默策略。仅 `disabled` 状态的策略可启用。",
-        "operationId": "channelSilenceRuleEnable",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ChannelRuleIDRequest"
+              },
               "example": {
                 "channel_id": 3521074710131,
                 "rule_id": "6621b23f4a2c5e0012ab34cd"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ChannelRuleIDRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/channel/silence/rule/list": {
+      "post": {
+        "operationId": "channelSilenceRuleList",
+        "summary": "查询静默策略列表",
+        "description": "列出协作空间的静默策略，以及每条策略当前是否生效。",
+        "tags": [
+          "On-call/协作空间"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间查看**（`on-call`） 或 **协作空间管理**（`on-call`） 或 **故障查看**（`on-call`） 或 **故障管理**（`on-call`） |\n\n## 使用说明\n\n- 查询列表时会顺带永久移除已到自动清理时间的一次性窗口策略（见 `is_auto_delete`），这些策略不再出现。使用周期 `time_filters` 的策略不会因此被移除。\n- `channel_id` 不存在时返回 `InvalidParameter`。",
+          "href": "/zh/api-reference/on-call/channels/channel-silence-rule-list",
+          "metadata": {
+            "sidebarTitle": "查询静默策略列表"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/EmptyResponse"
+                          "$ref": "#/components/schemas/ListSilenceRulesResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "items": [
+                      {
+                        "account_id": 2451002751131,
+                        "channel_id": 5967964835131,
+                        "rule_name": "Silence Info alerts",
+                        "description": "",
+                        "from_incident_id": "000000000000000000000000",
+                        "time_filters": [],
+                        "time_filter": {
+                          "start_time": 1773388800,
+                          "end_time": 1773414000
+                        },
+                        "filters": [
+                          [
+                            {
+                              "key": "severity",
+                              "oper": "IN",
+                              "vals": [
+                                "Info"
+                              ]
+                            }
+                          ]
+                        ],
+                        "is_directly_discard": true,
+                        "status": "enabled",
+                        "rule_id": "69b3c426b4a6f5abf1f54873",
+                        "updated_by": 3790925372131,
+                        "created_at": 1773388838,
+                        "updated_at": 1773388838,
+                        "is_effective": false
+                      }
+                    ]
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -37374,6 +38705,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -37381,95 +38715,62 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "启用静默策略",
-        "tags": [
-          "On-call/协作空间"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/channels/channel-silence-rule-enable",
-          "metadata": {
-            "sidebarTitle": "启用静默策略"
-          }
-        }
-      }
-    },
-    "/channel/silence/rule/list": {
-      "post": {
-        "description": "查询为指定协作空间配置的所有静默策略。",
-        "operationId": "channelSilenceRuleList",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {
-                "channel_id": 1001
-              },
               "schema": {
                 "$ref": "#/components/schemas/ChannelScopedListRequest"
+              },
+              "example": {
+                "channel_id": 1001
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/channel/silence/rule/update": {
+      "post": {
+        "operationId": "channelSilenceRuleUpdate",
+        "summary": "更新静默策略",
+        "description": "整体替换已有静默策略的配置。",
+        "tags": [
+          "On-call/协作空间"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 时间窗口与 `filters` 的要求同创建接口。在 `time_filter` 与 `time_filters` 之间切换时，另一种会被清空。\n- `description`、`is_directly_discard`、`is_auto_delete` 总会被覆盖，未传即重置为空或 `false`。`from_incident_id` 不可修改。\n- `channel_id` 或 `rule_id` 不存在时返回 `InvalidParameter`。\n- 调用者还必须拥有该协作空间的编辑权：账户所有者或管理员、协作空间创建者，或其管理团队成员（`managing_team_ids` 为空时为所属团队成员），否则返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志。",
+          "href": "/zh/api-reference/on-call/channels/channel-silence-rule-update",
+          "metadata": {
+            "sidebarTitle": "更新静默策略"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "items": [
-                      {
-                        "account_id": 2451002751131,
-                        "channel_id": 5967964835131,
-                        "created_at": 1773388838,
-                        "description": "",
-                        "filters": [
-                          [
-                            {
-                              "key": "severity",
-                              "oper": "IN",
-                              "vals": [
-                                "Info"
-                              ]
-                            }
-                          ]
-                        ],
-                        "from_incident_id": "000000000000000000000000",
-                        "is_directly_discard": true,
-                        "is_effective": false,
-                        "rule_id": "69b3c426b4a6f5abf1f54873",
-                        "rule_name": "Silence Info alerts",
-                        "status": "enabled",
-                        "time_filter": {
-                          "end_time": 1773414000,
-                          "start_time": 1773388800
-                        },
-                        "time_filters": [],
-                        "updated_at": 1773388838,
-                        "updated_by": 3790925372131
-                      }
-                    ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/ListSilenceRulesResponse"
+                          "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -37477,6 +38778,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -37484,28 +38788,21 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "查询静默策略列表",
-        "tags": [
-          "On-call/协作空间"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间查看**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/channels/channel-silence-rule-list",
-          "metadata": {
-            "sidebarTitle": "查询静默策略列表"
-          }
-        }
-      }
-    },
-    "/channel/silence/rule/update": {
-      "post": {
-        "description": "更新已有静默策略的配置。",
-        "operationId": "channelSilenceRuleUpdate",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/UpdateSilenceRuleRequest"
+              },
               "example": {
                 "channel_id": 1001,
+                "rule_id": "6621b23f4a2c5e0012ab34cd",
+                "rule_name": "Mute during maintenance",
+                "time_filter": {
+                  "start_time": 1710000000,
+                  "end_time": 1710086400
+                },
                 "filters": [
                   [
                     {
@@ -37516,47 +38813,57 @@
                       ]
                     }
                   ]
-                ],
-                "rule_id": "6621b23f4a2c5e0012ab34cd",
-                "rule_name": "Mute during maintenance",
-                "time_filter": {
-                  "end_time": 1710086400,
-                  "start_time": 1710000000
-                }
-              },
-              "schema": {
-                "$ref": "#/components/schemas/UpdateSilenceRuleRequest"
+                ]
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/channel/unsubscribe/rule/create": {
+      "post": {
+        "operationId": "channelUnsubscribeRuleCreate",
+        "summary": "创建排除规则",
+        "description": "创建排除规则，在生成告警和故障之前丢弃命中的告警事件。",
+        "tags": [
+          "On-call/协作空间"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 排除规则最先检查，早于静默和抑制策略。命中任一启用的排除规则的事件直接丢弃，不产生告警、故障或通知。\n- 不传 `filters` 或传空列表时，该规则不匹配任何事件。\n- `channel_id` 不存在时返回 `InvalidParameter`。\n- 调用者还必须拥有该协作空间的编辑权：账户所有者或管理员、协作空间创建者，或其管理团队成员（`managing_team_ids` 为空时为所属团队成员），否则返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志。",
+          "href": "/zh/api-reference/on-call/channels/channel-unsubscribe-rule-create",
+          "metadata": {
+            "sidebarTitle": "创建排除规则"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/EmptyResponse"
+                          "$ref": "#/components/schemas/RuleCreateResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "rule_id": "69db2f6ba0fe7db6448b1505",
+                    "rule_name": "Drop test environment alerts"
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -37564,6 +38871,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -37571,28 +38881,16 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "更新静默策略",
-        "tags": [
-          "On-call/协作空间"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/channels/channel-silence-rule-update",
-          "metadata": {
-            "sidebarTitle": "更新静默策略"
-          }
-        }
-      }
-    },
-    "/channel/unsubscribe/rule/create": {
-      "post": {
-        "description": "创建排除规则，在告警成为故障之前过滤不需要的告警。",
-        "operationId": "channelUnsubscribeRuleCreate",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CreateDropRuleRequest"
+              },
               "example": {
                 "channel_id": 3521074710131,
+                "rule_name": "Drop test environment alerts",
                 "description": "Discard all alerts from the test environment before they create incidents",
                 "filters": [
                   [
@@ -37605,45 +38903,54 @@
                       ]
                     }
                   ]
-                ],
-                "rule_name": "Drop test environment alerts"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/CreateDropRuleRequest"
+                ]
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/channel/unsubscribe/rule/delete": {
+      "post": {
+        "operationId": "channelUnsubscribeRuleDelete",
+        "summary": "删除排除规则",
+        "description": "删除已禁用的排除规则，使其不再出现在协作空间的策略列表中。",
+        "tags": [
+          "On-call/协作空间"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 仅 `disabled` 状态的规则可删除，其他状态返回 `InvalidParameter`。\n- `channel_id` 或 `rule_id` 不存在时返回 `InvalidParameter`。\n- 调用者还必须拥有该协作空间的编辑权：账户所有者或管理员、协作空间创建者，或其管理团队成员（`managing_team_ids` 为空时为所属团队成员），否则返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志。",
+          "href": "/zh/api-reference/on-call/channels/channel-unsubscribe-rule-delete",
+          "metadata": {
+            "sidebarTitle": "删除排除规则"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "rule_id": "69db2f6ba0fe7db6448b1505",
-                    "rule_name": "Test drop rule"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/RuleCreateResponse"
+                          "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -37651,6 +38958,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -37658,63 +38968,63 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "创建排除规则",
-        "tags": [
-          "On-call/协作空间"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |",
-          "href": "/zh/api-reference/on-call/channels/channel-unsubscribe-rule-create",
-          "metadata": {
-            "sidebarTitle": "创建排除规则"
-          }
-        }
-      }
-    },
-    "/channel/unsubscribe/rule/delete": {
-      "post": {
-        "description": "删除排除规则。仅 `disabled` 状态的规则可删除。",
-        "operationId": "channelUnsubscribeRuleDelete",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ChannelRuleIDRequest"
+              },
               "example": {
                 "channel_id": 3521074710131,
                 "rule_id": "6621b23f4a2c5e0012ab34cd"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ChannelRuleIDRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/channel/unsubscribe/rule/disable": {
+      "post": {
+        "operationId": "channelUnsubscribeRuleDisable",
+        "summary": "禁用排除规则",
+        "description": "禁用排除规则但不删除。",
+        "tags": [
+          "On-call/协作空间"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 仅 `enabled` 状态的规则可禁用，其他状态返回 `InvalidParameter`。\n- `channel_id` 或 `rule_id` 不存在时返回 `InvalidParameter`。\n- 调用者还必须拥有该协作空间的编辑权：账户所有者或管理员、协作空间创建者，或其管理团队成员（`managing_team_ids` 为空时为所属团队成员），否则返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志。",
+          "href": "/zh/api-reference/on-call/channels/channel-unsubscribe-rule-disable",
+          "metadata": {
+            "sidebarTitle": "禁用排除规则"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -37722,6 +39032,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -37729,63 +39042,63 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "删除排除规则",
-        "tags": [
-          "On-call/协作空间"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |",
-          "href": "/zh/api-reference/on-call/channels/channel-unsubscribe-rule-delete",
-          "metadata": {
-            "sidebarTitle": "删除排除规则"
-          }
-        }
-      }
-    },
-    "/channel/unsubscribe/rule/disable": {
-      "post": {
-        "description": "禁用排除规则而不删除。仅 `enabled` 状态的规则可禁用。",
-        "operationId": "channelUnsubscribeRuleDisable",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ChannelRuleIDRequest"
+              },
               "example": {
                 "channel_id": 3521074710131,
                 "rule_id": "6621b23f4a2c5e0012ab34cd"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ChannelRuleIDRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/channel/unsubscribe/rule/enable": {
+      "post": {
+        "operationId": "channelUnsubscribeRuleEnable",
+        "summary": "启用排除规则",
+        "description": "启用已禁用的排除规则，使其重新丢弃命中的告警事件。",
+        "tags": [
+          "On-call/协作空间"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 仅 `disabled` 状态的规则可启用，其他状态返回 `InvalidParameter`。\n- `channel_id` 或 `rule_id` 不存在时返回 `InvalidParameter`。\n- 调用者还必须拥有该协作空间的编辑权：账户所有者或管理员、协作空间创建者，或其管理团队成员（`managing_team_ids` 为空时为所属团队成员），否则返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志。",
+          "href": "/zh/api-reference/on-call/channels/channel-unsubscribe-rule-enable",
+          "metadata": {
+            "sidebarTitle": "启用排除规则"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -37793,6 +39106,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -37800,118 +39116,65 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "禁用排除规则",
-        "tags": [
-          "On-call/协作空间"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |",
-          "href": "/zh/api-reference/on-call/channels/channel-unsubscribe-rule-disable",
-          "metadata": {
-            "sidebarTitle": "禁用排除规则"
-          }
-        }
-      }
-    },
-    "/channel/unsubscribe/rule/enable": {
-      "post": {
-        "description": "启用已禁用的排除规则。仅 `disabled` 状态的规则可启用。",
-        "operationId": "channelUnsubscribeRuleEnable",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ChannelRuleIDRequest"
+              },
               "example": {
                 "channel_id": 3521074710131,
                 "rule_id": "6621b23f4a2c5e0012ab34cd"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ChannelRuleIDRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/channel/unsubscribe/rule/list": {
+      "post": {
+        "operationId": "channelUnsubscribeRuleList",
+        "summary": "查询排除规则列表",
+        "description": "按创建时间先后列出协作空间的排除规则。",
+        "tags": [
+          "On-call/协作空间"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- `channel_id` 不存在时返回 `InvalidParameter`。",
+          "href": "/zh/api-reference/on-call/channels/channel-unsubscribe-rule-list",
+          "metadata": {
+            "sidebarTitle": "查询排除规则列表"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/EmptyResponse"
+                          "$ref": "#/components/schemas/ListDropRulesResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
-                }
-              }
-            },
-            "description": "成功"
-          },
-          "400": {
-            "$ref": "#/components/responses/BadRequest"
-          },
-          "401": {
-            "$ref": "#/components/responses/Unauthorized"
-          },
-          "429": {
-            "$ref": "#/components/responses/TooManyRequests"
-          },
-          "500": {
-            "$ref": "#/components/responses/ServerError"
-          }
-        },
-        "summary": "启用排除规则",
-        "tags": [
-          "On-call/协作空间"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |",
-          "href": "/zh/api-reference/on-call/channels/channel-unsubscribe-rule-enable",
-          "metadata": {
-            "sidebarTitle": "启用排除规则"
-          }
-        }
-      }
-    },
-    "/channel/unsubscribe/rule/list": {
-      "post": {
-        "description": "查询协作空间的排除规则列表。",
-        "operationId": "channelUnsubscribeRuleList",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "channel_id": 1001
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ChannelScopedListRequest"
-              }
-            }
-          },
-          "required": true
-        },
-        "responses": {
-          "200": {
-            "content": {
-              "application/json": {
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "items": [
                       {
                         "account_id": 2451002751131,
                         "channel_id": 5967964835131,
-                        "created_at": 1773978928,
+                        "rule_name": "Drop test alerts",
                         "description": "",
                         "filters": [
                           [
@@ -37924,34 +39187,17 @@
                             }
                           ]
                         ],
-                        "rule_id": "69bcc530b9e63df36603e421",
-                        "rule_name": "Drop test alerts",
                         "status": "enabled",
-                        "updated_at": 1773978928,
-                        "updated_by": 3790925372131
+                        "rule_id": "69bcc530b9e63df36603e421",
+                        "updated_by": 3790925372131,
+                        "created_at": 1773978928,
+                        "updated_at": 1773978928
                       }
                     ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/ListDropRulesResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -37959,6 +39205,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -37966,75 +39215,62 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "查询排除规则列表",
-        "tags": [
-          "On-call/协作空间"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |",
-          "href": "/zh/api-reference/on-call/channels/channel-unsubscribe-rule-list",
-          "metadata": {
-            "sidebarTitle": "查询排除规则列表"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ChannelScopedListRequest"
+              },
+              "example": {
+                "channel_id": 1001
+              }
+            }
           }
         }
       }
     },
     "/channel/unsubscribe/rule/update": {
       "post": {
-        "description": "更新已有排除规则的配置。",
         "operationId": "channelUnsubscribeRuleUpdate",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "channel_id": 1001,
-                "filters": [
-                  [
-                    {
-                      "key": "labels.env",
-                      "oper": "IN",
-                      "vals": [
-                        "test"
-                      ]
-                    }
-                  ]
-                ],
-                "rule_id": "6621b23f4a2c5e0012ab34cf",
-                "rule_name": "Drop test alerts"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/UpdateDropRuleRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "更新排除规则",
+        "description": "整体替换已有排除规则的名称、描述和匹配条件。",
+        "tags": [
+          "On-call/协作空间"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 整体替换：未传 `description` 会被清空；未传 `filters` 会清除全部条件，规则不再匹配任何事件。\n- `channel_id` 或 `rule_id` 不存在时返回 `InvalidParameter`。\n- 调用者还必须拥有该协作空间的编辑权：账户所有者或管理员、协作空间创建者，或其管理团队成员（`managing_team_ids` 为空时为所属团队成员），否则返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志。",
+          "href": "/zh/api-reference/on-call/channels/channel-unsubscribe-rule-update",
+          "metadata": {
+            "sidebarTitle": "更新排除规则"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -38042,6 +39278,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -38049,66 +39288,77 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "更新排除规则",
-        "tags": [
-          "On-call/协作空间"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |",
-          "href": "/zh/api-reference/on-call/channels/channel-unsubscribe-rule-update",
-          "metadata": {
-            "sidebarTitle": "更新排除规则"
-          }
-        }
-      }
-    },
-    "/channel/update": {
-      "post": {
-        "description": "更新已有协作空间的配置和设置。",
-        "operationId": "channelUpdate",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/UpdateDropRuleRequest"
+              },
               "example": {
                 "channel_id": 1001,
-                "channel_name": "Production Alerts (v2)",
-                "description": "Updated description"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/UpdateChannelRequest"
+                "rule_id": "6621b23f4a2c5e0012ab34cf",
+                "rule_name": "Drop test alerts",
+                "filters": [
+                  [
+                    {
+                      "key": "labels.env",
+                      "oper": "IN",
+                      "vals": [
+                        "test"
+                      ]
+                    }
+                  ]
+                ]
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/channel/update": {
+      "post": {
+        "operationId": "channelUpdate",
+        "summary": "更新协作空间",
+        "description": "更新协作空间设置，仅修改请求中出现的字段。",
+        "tags": [
+          "On-call/协作空间"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 未传或为 `null` 的字段保持原值。`group`、`flapping`、`event_group` 一旦传入即整体替换原配置。\n- 传 `managing_team_ids: []` 可清空管理团队。\n- `auto_resolve_mode` 只有与 `auto_resolve_timeout` 一起传入时才生效；只传 `auto_resolve_timeout` 时，模式会重置为 `trigger`。\n- 每次把 `is_external_report_enabled` 设为 `true` 都会生成新的 `external_report_token`，旧令牌随即失效；设为 `false` 会清空令牌。\n- `channel_name` 与其他协作空间重名时返回 `InvalidParameter`；`group.method` 为 `p` 或 `i` 但许可证不足时返回 `NoLicense`。\n- 调用者还必须拥有该协作空间的编辑权：账户所有者或管理员、协作空间创建者，或其管理团队成员（`managing_team_ids` 为空时为所属团队成员），否则返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志。",
+          "href": "/zh/api-reference/on-call/channels/channel-update",
+          "metadata": {
+            "sidebarTitle": "更新协作空间"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "external_report_token": ""
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/UpdateChannelResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "external_report_token": ""
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -38116,6 +39366,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -38123,66 +39376,70 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "更新协作空间",
-        "tags": [
-          "On-call/协作空间"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/channels/channel-update",
-          "metadata": {
-            "sidebarTitle": "更新协作空间"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/UpdateChannelRequest"
+              },
+              "example": {
+                "channel_id": 3521074710131,
+                "channel_name": "Production Alerts (v2)",
+                "description": "Updated description"
+              }
+            }
           }
         }
       }
     },
     "/datasource/im/person/try-link": {
       "post": {
-        "description": "为指定集成尝试将未绑定成员自动关联到对应的 IM 账号。",
         "operationId": "datasourceImPersonTryLink",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "integration_id": 6113996590131
-              },
-              "schema": {
-                "$ref": "#/components/schemas/TryLinkPersonRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "尝试关联 IM 人员",
+        "description": "为指定集成尝试将未绑定成员自动关联到对应的 IM 账号。",
+        "tags": [
+          "On-call/集成中心"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **集成中心管理**（`on-call`） |\n\n## 使用说明\n\n- 按邮箱和手机号查找尚未关联到该集成 IM 应用的所有账户成员；仅支持飞书、钉钉和企业微信集成，其他类型返回 `InvalidParameter`。\n- 已禁用的集成返回 `InvalidParameter`。\n- 同一集成已有关联任务在运行时返回 `RequestLocked`；IM 平台拒绝查询（缺少通讯录权限或凭证被拒）时返回 `InvalidParameter`。\n- 没有成员被新关联时，`new_linked_person_ids` 为空数组。",
+          "href": "/zh/api-reference/on-call/integrations/datasource-im-person-try-link",
+          "metadata": {
+            "sidebarTitle": "尝试关联 IM 人员"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "new_linked_person_ids": [
-                      5348648172131
-                    ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/TryLinkPersonResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "new_linked_person_ids": [
+                      5348648172131
+                    ],
+                    "unmatched_count": 2,
+                    "no_contact_count": 1
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -38190,6 +39447,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -38197,88 +39457,90 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "尝试关联 IM 人员",
-        "tags": [
-          "On-call/集成中心"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **集成中心管理**（`on-call`） |\n\n## 使用说明\n\n- 服务端使用成员邮箱和手机号在钉钉、飞书或企业微信中查找匹配用户。\n- 如果没有成员可关联，响应中的 `new_linked_person_ids` 可能为空数组，或整个 `data` 字段被省略。",
-          "href": "/zh/api-reference/on-call/integrations/datasource-im-person-try-link",
-          "metadata": {
-            "sidebarTitle": "尝试关联 IM 人员"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/TryLinkPersonRequest"
+              },
+              "example": {
+                "integration_id": 6113996590131
+              }
+            }
           }
         }
       }
     },
     "/datasource/im/war-room-enabled/list": {
       "post": {
-        "description": "查询账户下已开启作战室功能的 IM 集成。",
         "operationId": "im-war-room-enabled-list",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {},
-              "schema": {
-                "type": "object"
-              }
-            }
-          },
-          "required": true
+        "summary": "查看开启作战室功能的集成",
+        "description": "查询账户下已开启作战室功能的 IM 集成。",
+        "tags": [
+          "On-call/IM 集成"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间查看**（`on-call`） 或 **协作空间管理**（`on-call`） 或 **故障查看**（`on-call`） 或 **故障管理**（`on-call`） 或 **集成中心查看**（`on-call`） 或 **集成中心管理**（`on-call`） |\n\n## 使用说明\n\n- 返回设置中 `war_room_enabled` 为 `true` 的飞书、钉钉、企业微信、Slack 和 Microsoft Teams 集成（含已启用和已禁用），不含已删除的集成。\n- `settings` 中的密钥类字段会被掩码为 `******`。",
+          "href": "/zh/api-reference/on-call/integrations/im-war-room-enabled-list",
+          "metadata": {
+            "sidebarTitle": "查看开启作战室功能的集成"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/ListWarRoomEnabledResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "items": [
                       {
+                        "data_source_id": 362,
                         "account_id": 10001,
+                        "team_id": 0,
+                        "plugin_id": 101,
+                        "name": "Feishu Ops",
+                        "status": "enabled",
                         "category": "im",
-                        "created_at": 1716962400,
-                        "creator_id": 20001,
-                        "data_source_id": 362,
+                        "plugin_type": "feishu_app",
+                        "plugin_type_name": "Feishu",
                         "description": "Feishu war-room integration",
-                        "exclusive_data_source_id": 0,
-                        "integration_id": 362,
                         "integration_key": "ik_8f3a2b1c9d0e",
-                        "last_time": 0,
-                        "name": "Feishu Ops",
-                        "no_editable": false,
-                        "plugin_id": 101,
-                        "plugin_type": "feishu",
-                        "plugin_type_name": "Feishu",
                         "ref_id": "",
                         "settings": {
                           "war_room_enabled": true
                         },
-                        "status": "enabled",
-                        "team_id": 0,
+                        "no_editable": false,
+                        "creator_id": 20001,
+                        "updated_by": 20001,
+                        "created_at": 1716962400,
                         "updated_at": 1716962700,
-                        "updated_by": 20001
+                        "last_time": 0,
+                        "exclusive_data_source_id": 0,
+                        "integration_id": 362
                       }
                     ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/ListWarRoomEnabledResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -38286,6 +39548,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -38293,80 +39558,78 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "查看开启作战室功能的集成",
-        "tags": [
-          "On-call/IM 集成"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n",
-          "href": "/zh/api-reference/on-call/integrations/im-war-room-enabled-list",
-          "metadata": {
-            "sidebarTitle": "查看开启作战室功能的集成"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object"
+              },
+              "example": {}
+            }
           }
         }
       }
     },
     "/enrichment/info": {
       "post": {
-        "description": "返回指定集成配置的告警富化规则集。",
         "operationId": "enrichment-read-info",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "integration_id": 5001
-              },
-              "schema": {
-                "$ref": "#/components/schemas/EnrichmentInfoRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "查看富化规则",
+        "description": "返回指定集成配置的告警富化规则集。",
+        "tags": [
+          "On-call/标签增强"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间查看**（`on-call`） 或 **协作空间管理**（`on-call`） 或 **集成中心查看**（`on-call`） 或 **集成中心管理**（`on-call`） |\n\n## 使用说明\n\n- `integration_id` 必须是账户内已存在的集成，否则返回 `InvalidParameter`。\n- 集成没有配置规则集时返回 `data: null`。",
+          "href": "/zh/api-reference/on-call/alert-enrichment/enrichment-read-info",
+          "metadata": {
+            "sidebarTitle": "查看富化规则"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "created_at": 1710000000,
-                    "creator_id": 80011,
-                    "integration_id": 5001,
-                    "rules": [
-                      {
-                        "kind": "extraction",
-                        "settings": {
-                          "override": true,
-                          "pattern": "^(prod|staging|dev).*$",
-                          "result_label": "environment",
-                          "source_field": "labels.env"
-                        }
-                      }
-                    ],
-                    "status": "enabled",
-                    "updated_at": 1710000000,
-                    "updated_by": 80011
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EnrichmentItem"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "integration_id": 5001,
+                    "rules": [
+                      {
+                        "kind": "extraction",
+                        "settings": {
+                          "source_field": "labels.env",
+                          "result_label": "environment",
+                          "pattern": "^(prod|staging|dev).*$",
+                          "override": true
+                        }
+                      }
+                    ],
+                    "status": "enabled",
+                    "updated_by": 80011,
+                    "creator_id": 80011,
+                    "created_at": 1710000000,
+                    "updated_at": 1710000000
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -38374,6 +39637,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -38381,77 +39647,74 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "查看富化规则",
-        "tags": [
-          "On-call/标签增强"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间查看**（`on-call`） 或 **协作空间管理**（`on-call`） 或 **集成中心查看**（`on-call`） 或 **集成中心管理**（`on-call`） |\n\n## 使用说明\n\n- 若该集成尚未配置富化规则，返回 `null`。",
-          "href": "/zh/api-reference/on-call/alert-enrichment/enrichment-read-info",
-          "metadata": {
-            "sidebarTitle": "查看富化规则"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/EnrichmentInfoRequest"
+              },
+              "example": {
+                "integration_id": 5001
+              }
+            }
           }
         }
       }
     },
     "/enrichment/list": {
       "post": {
-        "description": "批量返回指定集成 ID 列表的告警富化规则集。",
         "operationId": "enrichment-read-list",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "integration_ids": [
-                  5001,
-                  5002
-                ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/EnrichmentListRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "批量查询富化规则",
+        "description": "批量返回指定集成 ID 列表的告警富化规则集。",
+        "tags": [
+          "On-call/标签增强"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **集成中心查看**（`on-call`） 或 **集成中心管理**（`on-call`） |\n\n## 使用说明\n\n- 每个 ID 都必须是账户内已存在的集成，否则返回 `InvalidParameter`。\n- 没有配置规则集的集成不会出现在 `items` 中。",
+          "href": "/zh/api-reference/on-call/alert-enrichment/enrichment-read-list",
+          "metadata": {
+            "sidebarTitle": "批量查询富化规则"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "items": [
-                      {
-                        "created_at": 1710000000,
-                        "creator_id": 80011,
-                        "integration_id": 5001,
-                        "rules": [],
-                        "status": "enabled",
-                        "updated_at": 1710000000,
-                        "updated_by": 80011
-                      }
-                    ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EnrichmentListResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "items": [
+                      {
+                        "integration_id": 5001,
+                        "rules": [],
+                        "status": "enabled",
+                        "updated_by": 80011,
+                        "creator_id": 80011,
+                        "created_at": 1710000000,
+                        "updated_at": 1710000000
+                      }
+                    ]
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -38459,6 +39722,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -38466,73 +39732,68 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "批量查询富化规则",
-        "tags": [
-          "On-call/标签增强"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **集成中心查看**（`on-call`） 或 **集成中心管理**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/alert-enrichment/enrichment-read-list",
-          "metadata": {
-            "sidebarTitle": "批量查询富化规则"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/EnrichmentListRequest"
+              },
+              "example": {
+                "integration_ids": [
+                  5001,
+                  5002
+                ]
+              }
+            }
           }
         }
       }
     },
     "/enrichment/mapping/api/create": {
       "post": {
-        "description": "创建新的外部 HTTP API 端点，用于通过 HTTP 查询富化告警。",
         "operationId": "mapping-api-write-create",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "api_name": "CMDB API",
-                "description": "Query CMDB for host metadata",
-                "headers": {
-                  "X-Token": "mytoken"
-                },
-                "insecure_skip_verify": false,
-                "retry_count": 1,
-                "timeout": 2,
-                "url": "https://cmdb.example.com/api/lookup"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/MappingAPICreateRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "创建映射 API",
+        "description": "登记一个外部 HTTP API，供富化规则调用以查询告警标签。",
+        "tags": [
+          "On-call/标签增强"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **映射数据管理**（`on-call`） |\n\n## 使用说明\n\n- `mapping_type` 为 `api` 的富化规则会携带配置的 `headers` 发送 `POST <url>`，请求体为 JSON `{\"result_label_keys\": [...], \"event\": {...}}`（告警事件）。API 须返回 HTTP 200 和 `{\"result_labels\": {\"<label>\": \"<value>\"}}`。\n- `url` 必须使用 `http` 或 `https`；SaaS 环境下主机名不得解析到内网 IP。\n- `timeout` 是整个请求的超时秒数（1–3，默认 2）；`retry_count` 是失败后的重试次数（0–1，默认 0）。\n- SaaS 环境下会拒绝以下敏感请求头（不区分大小写）：`Authorization`、`Proxy-Authorization`、`Cookie`、`X-Api-Key`、`X-Access-Token`、`X-Forwarded-For`、`X-Real-Ip`、`True-Client-Ip`、`X-Client-Ip`、`Host`、`X-Forwarded-Host`、`X-Forwarded-Proto`、`X-Internal-Id`、`X-User-Id`、`Transfer-Encoding`、`Upgrade`、`Connection`。\n- `api_name` 在未删除的映射 API 中必须唯一；每个账户最多 50 个未删除的映射 API。`team_id` 非 0 时必须是已存在的团队。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "href": "/zh/api-reference/on-call/alert-enrichment/mapping-api-write-create",
+          "metadata": {
+            "sidebarTitle": "创建映射 API"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "api_id": "665f1a2b3c4d5e6f7a8b9c02",
-                    "api_name": "CMDB API"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/MappingAPICreateResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "api_id": "665f1a2b3c4d5e6f7a8b9c02",
+                    "api_name": "CMDB API"
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -38540,6 +39801,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -38547,62 +39811,70 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "创建映射 API",
-        "tags": [
-          "On-call/标签增强"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **映射数据管理**（`on-call`） |\n\n## 使用说明\n\n- `url` 须以 `http://` 或 `https://` 开头，SaaS 模式下不得解析为内网 IP。\n- `timeout` 为 HTTP 读取超时秒数（1–3，默认 2）。\n- `retry_count` 为失败重试次数（0–1，默认 0）。\n- SaaS 模式下，含敏感名称的请求头（如 `authorization`、`cookie`）将被拒绝。\n- 账户最多可创建 50 个映射 API。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
-          "href": "/zh/api-reference/on-call/alert-enrichment/mapping-api-write-create",
-          "metadata": {
-            "sidebarTitle": "创建映射 API"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/MappingAPICreateRequest"
+              },
+              "example": {
+                "api_name": "CMDB API",
+                "description": "Query CMDB for host metadata",
+                "url": "https://cmdb.example.com/api/lookup",
+                "headers": {
+                  "X-Token": "mytoken"
+                },
+                "timeout": 2,
+                "retry_count": 1,
+                "insecure_skip_verify": false
+              }
+            }
           }
         }
       }
     },
     "/enrichment/mapping/api/delete": {
       "post": {
-        "description": "删除映射 API。若该 API 被富化规则引用，则拒绝删除。",
         "operationId": "mapping-api-write-delete",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "api_id": "665f1a2b3c4d5e6f7a8b9c02"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/MappingAPIIDRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "删除映射 API",
+        "description": "软删除映射 API；仍被富化规则引用时拒绝删除。",
+        "tags": [
+          "On-call/标签增强"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **映射数据管理**（`on-call`） |\n\n## 使用说明\n\n- 映射 API 被软删除（`status` 变为 `deleted`），富化规则不再调用它。\n- 若有集成的富化规则使用它（`mapping_type` 为 `api`），返回 HTTP 400 `ReferenceExist`，`data.refs` 最多列出 20 个集成（`kind` 为 `integration`）。\n- `api_id` 不存在时返回 `InvalidParameter`。\n- 仅账户管理员、映射 API 创建者或映射 API 所属团队的成员可以调用，其他人返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "href": "/zh/api-reference/on-call/alert-enrichment/mapping-api-write-delete",
+          "metadata": {
+            "sidebarTitle": "删除映射 API"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
-                        }
-                      },
-                      "type": "object"
+                        }
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -38610,6 +39882,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -38617,73 +39892,79 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "删除映射 API",
-        "tags": [
-          "On-call/标签增强"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **映射数据管理**（`on-call`） |\n\n## 使用说明\n\n- 若 API 仍被引用，响应返回 HTTP 400，`refs` 字段列出所有阻止删除的引用。\n- 仅 API 创建者、账户管理员或所属团队成员可删除。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
-          "href": "/zh/api-reference/on-call/alert-enrichment/mapping-api-write-delete",
-          "metadata": {
-            "sidebarTitle": "删除映射 API"
-          }
-        }
-      }
-    },
-    "/enrichment/mapping/api/info": {
-      "post": {
-        "description": "根据映射 API ID 返回单个映射 API 的详细信息。",
-        "operationId": "mapping-api-read-info",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {
-                "api_id": "665f1a2b3c4d5e6f7a8b9c02"
-              },
               "schema": {
                 "$ref": "#/components/schemas/MappingAPIIDRequest"
+              },
+              "example": {
+                "api_id": "665f1a2b3c4d5e6f7a8b9c02"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/enrichment/mapping/api/info": {
+      "post": {
+        "operationId": "mapping-api-read-info",
+        "summary": "查看映射 API 详情",
+        "description": "根据映射 API ID 返回单个映射 API 的详细信息。",
+        "tags": [
+          "On-call/标签增强"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 账户内不存在该 ID 的映射 API 时返回 `data: null`。\n- 已软删除的映射 API 仍会返回，此时 `status` 为 `deleted`。\n- 不做团队校验：账户内任何调用方都能读取任意映射 API，包括明文的 `headers`。",
+          "href": "/zh/api-reference/on-call/alert-enrichment/mapping-api-read-info",
+          "metadata": {
+            "sidebarTitle": "查看映射 API 详情"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "api_id": "665f1a2b3c4d5e6f7a8b9c02",
-                    "api_name": "CMDB API",
-                    "created_at": 1710000000,
-                    "creator_id": 80011,
-                    "insecure_skip_verify": false,
-                    "retry_count": 1,
-                    "status": "enabled",
-                    "timeout": 2,
-                    "updated_at": 1710000000,
-                    "url": "https://cmdb.example.com/api/lookup"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/MappingAPIItem"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "api_id": "665f1a2b3c4d5e6f7a8b9c02",
+                    "api_name": "CMDB API",
+                    "description": "Query CMDB for host metadata",
+                    "url": "https://cmdb.example.com/api/lookup",
+                    "headers": {
+                      "X-Token": "example-token"
+                    },
+                    "timeout": 2,
+                    "retry_count": 1,
+                    "insecure_skip_verify": false,
+                    "status": "enabled",
+                    "team_id": 0,
+                    "creator_id": 80011,
+                    "updated_by": 80011,
+                    "created_at": 1710000000,
+                    "updated_at": 1710000000
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -38691,6 +39972,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -38698,81 +39982,84 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "查看映射 API 详情",
-        "tags": [
-          "On-call/标签增强"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 映射 API 不存在时返回 `null`。",
-          "href": "/zh/api-reference/on-call/alert-enrichment/mapping-api-read-info",
-          "metadata": {
-            "sidebarTitle": "查看映射 API 详情"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/MappingAPIIDRequest"
+              },
+              "example": {
+                "api_id": "665f1a2b3c4d5e6f7a8b9c02"
+              }
+            }
           }
         }
       }
     },
     "/enrichment/mapping/api/list": {
       "post": {
-        "description": "返回账户下所有配置的映射 API。",
         "operationId": "mapping-api-read-list",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {},
-              "schema": {
-                "$ref": "#/components/schemas/EmptyRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "查询映射 API 列表",
+        "description": "返回账户下的全部映射 API，按创建时间倒序排列。",
+        "tags": [
+          "On-call/标签增强"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **映射数据查看**（`on-call`） 或 **映射数据管理**（`on-call`） |\n\n## 使用说明\n\n- 一次返回全部未删除的映射 API，不分页；`total` 即条目数。\n- 返回所有团队的映射 API，`headers` 以明文返回。",
+          "href": "/zh/api-reference/on-call/alert-enrichment/mapping-api-read-list",
+          "metadata": {
+            "sidebarTitle": "查询映射 API 列表"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/MappingAPIListResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
+                    "total": 1,
                     "items": [
                       {
                         "api_id": "665f1a2b3c4d5e6f7a8b9c02",
                         "api_name": "CMDB API",
-                        "created_at": 1710000000,
-                        "creator_id": 80011,
                         "description": "Query CMDB for host metadata",
+                        "url": "https://cmdb.example.com/api/lookup",
                         "headers": {
-                          "Authorization": "Bearer eyJhbGciOiJIUzI1NiJ9.example-token"
+                          "X-Token": "example-token"
                         },
-                        "insecure_skip_verify": false,
+                        "timeout": 2,
                         "retry_count": 1,
+                        "insecure_skip_verify": false,
                         "status": "enabled",
                         "team_id": 0,
-                        "timeout": 2,
-                        "updated_at": 1710000000,
-                        "url": "https://cmdb.example.com/api/lookup"
+                        "creator_id": 80011,
+                        "updated_by": 80011,
+                        "created_at": 1710000000,
+                        "updated_at": 1710000000
                       }
-                    ],
-                    "total": 1
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/MappingAPIListResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                    ]
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -38780,6 +40067,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -38787,64 +40077,60 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "查询映射 API 列表",
-        "tags": [
-          "On-call/标签增强"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **映射数据查看**（`on-call`） 或 **映射数据管理**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/alert-enrichment/mapping-api-read-list",
-          "metadata": {
-            "sidebarTitle": "查询映射 API 列表"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/EmptyRequest"
+              },
+              "example": {}
+            }
           }
         }
       }
     },
     "/enrichment/mapping/api/update": {
       "post": {
-        "description": "更新现有映射 API 的配置。",
         "operationId": "mapping-api-write-update",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "api_id": "665f1a2b3c4d5e6f7a8b9c02",
-                "retry_count": 1,
-                "timeout": 3
-              },
-              "schema": {
-                "$ref": "#/components/schemas/MappingAPIUpdateRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "更新映射 API",
+        "description": "更新现有映射 API 的配置。",
+        "tags": [
+          "On-call/标签增强"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **映射数据管理**（`on-call`） |\n\n## 使用说明\n\n- 不传的字段保持原值。`headers` 一旦传入即整体替换请求头，传 `{}` 可清空全部请求头；`team_id` 传 `0` 表示解除团队关联。\n- 传入的字段按创建时的规则校验（`url` 协议与内网地址检查、请求头规则、`timeout` 1–3、`retry_count` 0–1）；`description` 超过 500 字符会被截断。\n- `api_id` 不存在时返回 `InvalidParameter`；新的 `api_name` 不能与其他映射 API 重名。\n- 仅账户管理员、映射 API 创建者或映射 API 所属团队的成员可以调用，其他人返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "href": "/zh/api-reference/on-call/alert-enrichment/mapping-api-write-update",
+          "metadata": {
+            "sidebarTitle": "更新映射 API"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -38852,6 +40138,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -38859,66 +40148,64 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "更新映射 API",
-        "tags": [
-          "On-call/标签增强"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **映射数据管理**（`on-call`） |\n\n## 使用说明\n\n- 仅 API 创建者、账户管理员或所属团队成员可更新。\n- 所有可更新字段均为可选，仅更新提供的字段。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
-          "href": "/zh/api-reference/on-call/alert-enrichment/mapping-api-write-update",
-          "metadata": {
-            "sidebarTitle": "更新映射 API"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/MappingAPIUpdateRequest"
+              },
+              "example": {
+                "api_id": "665f1a2b3c4d5e6f7a8b9c02",
+                "timeout": 3,
+                "retry_count": 1
+              }
+            }
           }
         }
       }
     },
     "/enrichment/mapping/data/delete": {
       "post": {
-        "description": "按键名批量删除最多 100 条映射数据行。",
         "operationId": "mapping-data-write-delete",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "keys": [
-                  "server01",
-                  "server02"
-                ],
-                "schema_id": "665f1a2b3c4d5e6f7a8b9c01"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/MappingDataDeleteRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "删除映射数据",
+        "description": "按键名批量删除最多 100 条映射数据行。",
+        "tags": [
+          "On-call/标签增强"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **映射数据管理**（`on-call`） |\n\n## 使用说明\n\n- `keys` 取自 `/enrichment/mapping/data/list` 或 `/enrichment/mapping/data/upsert` 返回的行 `key`；匹配不到任何行的 key 会被忽略。\n- 映射规则必须存在且未被删除，否则返回 `InvalidParameter`。\n- 仅账户管理员、映射规则创建者或映射规则所属团队的成员可以调用，其他人返回 `AccessDenied`。\n- 同一映射规则的数据写操作（写入、删除、清空、CSV 上传）串行执行；另一个写操作进行中时调用会返回 `RequestTooFrequently`。",
+          "href": "/zh/api-reference/on-call/alert-enrichment/mapping-data-write-delete",
+          "metadata": {
+            "sidebarTitle": "删除映射数据"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -38926,6 +40213,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -38933,49 +40223,53 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "删除映射数据",
-        "tags": [
-          "On-call/标签增强"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **映射数据管理**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/alert-enrichment/mapping-data-write-delete",
-          "metadata": {
-            "sidebarTitle": "删除映射数据"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/MappingDataDeleteRequest"
+              },
+              "example": {
+                "schema_id": "665f1a2b3c4d5e6f7a8b9c01",
+                "keys": [
+                  "server01",
+                  "server02"
+                ]
+              }
+            }
           }
         }
       }
     },
     "/enrichment/mapping/data/download": {
       "post": {
-        "description": "将映射规则的所有数据行导出为 CSV 文件。",
         "operationId": "mapping-data-read-download",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "schema_id": "665f1a2b3c4d5e6f7a8b9c01"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/MappingSchemaIDRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "下载映射数据 CSV",
+        "description": "将映射规则的所有数据行导出为 CSV 文件。",
+        "tags": [
+          "On-call/标签增强"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **60 次/分钟**；**3 次/秒** |\n| 权限要求 | **集成中心查看**（`on-call`） 或 **集成中心管理**（`on-call`） 或 **映射数据查看**（`on-call`） 或 **映射数据管理**（`on-call`） |\n\n## 使用说明\n\n- 响应是 CSV 文件流（`Content-Type: application/octet-stream`），不是 JSON。`Content-Disposition` 中的文件名为映射规则名称，空格替换为 `_`。\n- 首行依次为 `source_labels` 和 `result_labels`；之后每行是一条数据，最近写入的在前。\n- 映射规则必须存在且未被删除，否则返回 JSON 格式的 `InvalidParameter` 错误。",
+          "href": "/zh/api-reference/on-call/alert-enrichment/mapping-data-read-download",
+          "metadata": {
+            "sidebarTitle": "下载映射数据 CSV"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功。返回 CSV 附件流，不是 JSON envelope。",
             "content": {
               "application/octet-stream": {
-                "example": "host,owner,team\nserver01,alice,sre\nserver02,bob,backend\n",
                 "schema": {
-                  "description": "CSV 文件流（`Content-Type: application/octet-stream`，`Content-Disposition: attachment; filename=<schema_name>.csv`）。首行为表头，按 schema 的 source_labels + result_labels 顺序排列；之后每行一条映射数据。",
+                  "type": "string",
                   "format": "binary",
-                  "type": "string"
-                }
+                  "description": "CSV 文件流（`Content-Type: application/octet-stream`，`Content-Disposition: attachment; filename=<schema_name>.csv`）。首行为表头，按 schema 的 source_labels + result_labels 顺序排列；之后每行一条映射数据。"
+                },
+                "example": "host,owner,team,service\nserver01,alice,sre,api\n"
               }
-            },
-            "description": "成功。返回 CSV 附件流，不是 JSON envelope。"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -38983,6 +40277,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -38990,82 +40287,156 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "下载映射数据 CSV",
-        "tags": [
-          "On-call/标签增强"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **集成中心查看**（`on-call`） 或 **集成中心管理**（`on-call`） 或 **映射数据查看**（`on-call`） 或 **映射数据管理**（`on-call`） |\n\n## 使用说明\n\n- 响应为 CSV 文件，包含 `Content-Disposition: attachment` 响应头。\n- CSV 标题行按顺序对应映射规则的来源标签和结果标签。",
-          "href": "/zh/api-reference/on-call/alert-enrichment/mapping-data-read-download",
-          "metadata": {
-            "sidebarTitle": "下载映射数据 CSV"
-          }
-        }
-      }
-    },
-    "/enrichment/mapping/data/list": {
-      "post": {
-        "description": "分页返回指定映射规则的数据行，可按来源标签值进行精确过滤。",
-        "operationId": "mapping-data-read-list",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/MappingSchemaIDRequest"
+              },
               "example": {
-                "asc": false,
-                "limit": 20,
-                "orderby": "updated_at",
-                "p": 1,
                 "schema_id": "665f1a2b3c4d5e6f7a8b9c01"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/MappingDataListRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/enrichment/mapping/data/list": {
+      "post": {
+        "operationId": "mapping-data-read-list",
+        "summary": "查询映射数据列表",
+        "description": "分页返回指定映射规则的数据行，可按来源标签值进行精确过滤。",
+        "tags": [
+          "On-call/标签增强"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **集成中心查看**（`on-call`） 或 **集成中心管理**（`on-call`） 或 **映射数据查看**（`on-call`） 或 **映射数据管理**（`on-call`） |\n\n## 使用说明\n\n- 映射规则必须存在且未被删除，否则返回 `InvalidParameter`。\n- `query` 按来源标签值精确过滤。不属于来源标签的键会被丢弃；只要还剩下键，就必须给出全部来源标签，否则返回 `InvalidParameter`。\n- 页码分页（`p`、`limit`）最多取到第 10,000 行（`p * limit <= 10000`），更靠后的数据请用 `search_after_ctx` 游标翻页。\n- `total` 最多统计 1,000 条匹配行；`used_cnt` 是该映射规则的实际总行数。",
+          "href": "/zh/api-reference/on-call/alert-enrichment/mapping-data-read-list",
+          "metadata": {
+            "sidebarTitle": "查询映射数据列表"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/MappingDataListResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
-                    "has_next_page": false,
                     "items": [
                       {
-                        "created_at": 1710000000,
+                        "key": "02b8754747905747f7f76d802202d214",
                         "fields": {
                           "host": "server01",
                           "owner": "alice",
-                          "service": "api",
-                          "team": "sre"
+                          "team": "sre",
+                          "service": "api"
                         },
-                        "key": "server01",
+                        "created_at": 1710000000,
                         "updated_at": 1710000000
                       }
                     ],
-                    "total": 1
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
+                    "total": 1,
+                    "has_next_page": false,
+                    "used_cnt": 1
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "429": {
+            "$ref": "#/components/responses/TooManyRequests"
+          },
+          "500": {
+            "$ref": "#/components/responses/ServerError"
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/MappingDataListRequest"
+              },
+              "example": {
+                "schema_id": "665f1a2b3c4d5e6f7a8b9c01",
+                "orderby": "updated_at",
+                "asc": false,
+                "p": 1,
+                "limit": 20
+              }
+            }
+          }
+        }
+      }
+    },
+    "/enrichment/mapping/data/truncate": {
+      "post": {
+        "operationId": "mapping-data-write-truncate",
+        "summary": "清空映射数据",
+        "description": "删除指定映射规则的全部数据行。",
+        "tags": [
+          "On-call/标签增强"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **映射数据管理**（`on-call`） |\n\n## 使用说明\n\n- 永久删除该映射规则下的全部数据行，映射规则本身保留。\n- 映射规则必须存在且未被删除，否则返回 `InvalidParameter`。\n- 仅账户管理员、映射规则创建者或映射规则所属团队的成员可以调用，其他人返回 `AccessDenied`。\n- 同一映射规则的数据写操作（写入、删除、清空、CSV 上传）串行执行；另一个写操作进行中时调用会返回 `RequestTooFrequently`。",
+          "href": "/zh/api-reference/on-call/alert-enrichment/mapping-data-write-truncate",
+          "metadata": {
+            "sidebarTitle": "清空映射数据"
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "成功",
+            "content": {
+              "application/json": {
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/MappingDataListResponse"
+                          "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -39073,6 +40444,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -39080,62 +40454,62 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "查询映射数据列表",
-        "tags": [
-          "On-call/标签增强"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **集成中心查看**（`on-call`） 或 **集成中心管理**（`on-call`） 或 **映射数据查看**（`on-call`） 或 **映射数据管理**（`on-call`） |\n\n## 使用说明\n\n- 若提供 `query`，须包含全部来源标签——不支持部分来源标签查询。\n- 支持游标分页（`search_after_ctx`）或页码分页（`p`、`limit`）。`limit` 默认 20，最大 100。\n- 响应中的 `search_after_ctx` 可用于获取下一页。",
-          "href": "/zh/api-reference/on-call/alert-enrichment/mapping-data-read-list",
-          "metadata": {
-            "sidebarTitle": "查询映射数据列表"
-          }
-        }
-      }
-    },
-    "/enrichment/mapping/data/truncate": {
-      "post": {
-        "description": "删除指定映射规则的全部数据行。",
-        "operationId": "mapping-data-write-truncate",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {
-                "schema_id": "665f1a2b3c4d5e6f7a8b9c01"
-              },
               "schema": {
                 "$ref": "#/components/schemas/MappingSchemaIDRequest"
+              },
+              "example": {
+                "schema_id": "665f1a2b3c4d5e6f7a8b9c01"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/enrichment/mapping/data/upload": {
+      "post": {
+        "operationId": "mapping-data-write-upload",
+        "summary": "通过 CSV 上传映射数据",
+        "description": "上传 CSV 文件批量导入映射数据。默认情况下，导入前先清空现有数据。",
+        "tags": [
+          "On-call/标签增强"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **60 次/分钟**；**3 次/秒** |\n| 权限要求 | **映射数据管理**（`on-call`） |\n\n## 使用说明\n\n- 请求为 `multipart/form-data`，CSV 放在 `file` 字段；`schema_id` 和 `do_not_truncate_first` 是查询参数。文件最大 100 MB。\n- CSV 首行为表头，必须包含全部来源标签和结果标签，其他列会被丢弃。值超过 2,048 字节会被拒绝；BOM 会被去除。没有数据行的文件返回 `InvalidParameter`。\n- 默认导入前先删除全部现有数据行。传 `do_not_truncate_first=TRUE` 时保留现有数据，来源标签值相同的行会被替换。\n- 来源标签值相同的多行会合并，以后出现的行为准。\n- 按导入后的行数检查行数上限（默认 10,000 行，部分账户更高），超出返回 `InvalidParameter`。\n- 数据每 100 行一批写入；某一批失败时，之前的清空和已写入的批次不会回滚。\n- 映射规则必须存在且未被删除，否则返回 `InvalidParameter`。\n- 仅账户管理员、映射规则创建者或映射规则所属团队的成员可以调用，其他人返回 `AccessDenied`。\n- 同一映射规则的数据写操作（写入、删除、清空、CSV 上传）串行执行；另一个写操作进行中时调用会返回 `RequestTooFrequently`。",
+          "href": "/zh/api-reference/on-call/alert-enrichment/mapping-data-write-upload",
+          "metadata": {
+            "sidebarTitle": "通过 CSV 上传映射数据"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -39143,6 +40517,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -39150,94 +40527,99 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "清空映射数据",
-        "tags": [
-          "On-call/标签增强"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **映射数据管理**（`on-call`） |\n\n## 使用说明\n\n- 此操作不可逆，将删除映射规则中的所有数据。\n- 本接口为高危操作。控制台 JWT 调用需二次验证码；`app_key` 调用跳过 MFA 但仍会被完整记录，请妥善保管 app_key。",
-          "href": "/zh/api-reference/on-call/alert-enrichment/mapping-data-write-truncate",
-          "metadata": {
-            "sidebarTitle": "清空映射数据"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "multipart/form-data": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "file": {
+                    "type": "string",
+                    "format": "binary",
+                    "description": "CSV 文件，最大 100 MB。表头必须包含 schema 的全部 source/result label 名称。"
+                  }
+                },
+                "required": [
+                  "file"
+                ]
+              }
+            }
           }
-        }
-      }
-    },
-    "/enrichment/mapping/data/upload": {
-      "post": {
-        "description": "上传 CSV 文件批量导入映射数据。默认情况下，导入前先清空现有数据。",
-        "operationId": "mapping-data-write-upload",
+        },
         "parameters": [
           {
-            "description": "目标映射 schema 的 ID（ObjectID hex）。",
-            "example": "665f1a2b3c4d5e6f7a8b9c01",
-            "in": "query",
             "name": "schema_id",
+            "in": "query",
             "required": true,
             "schema": {
-              "pattern": "^[0-9a-fA-F]{24}$",
-              "type": "string"
-            }
+              "type": "string",
+              "pattern": "^[0-9a-fA-F]{24}$"
+            },
+            "description": "目标映射 schema 的 ID（ObjectID hex）。",
+            "example": "665f1a2b3c4d5e6f7a8b9c01"
           },
           {
-            "description": "传 `TRUE`（大小写不敏感）时追加导入；不传且 schema 已有数据时，服务端先清空再导入。",
-            "in": "query",
             "name": "do_not_truncate_first",
+            "in": "query",
             "required": false,
             "schema": {
+              "type": "string",
               "enum": [
                 "TRUE"
-              ],
-              "type": "string"
-            }
+              ]
+            },
+            "description": "传 `TRUE`（大小写不敏感）时追加导入；不传且 schema 已有数据时，服务端先清空再导入。"
           }
+        ]
+      }
+    },
+    "/enrichment/mapping/data/upsert": {
+      "post": {
+        "operationId": "mapping-data-write-upsert",
+        "summary": "写入映射数据",
+        "description": "向映射规则中插入或更新最多 1000 条数据行，每行须包含所有来源标签和结果标签。",
+        "tags": [
+          "On-call/标签增强"
         ],
-        "requestBody": {
-          "content": {
-            "multipart/form-data": {
-              "schema": {
-                "properties": {
-                  "file": {
-                    "description": "CSV 文件，最大 100 MB。表头必须包含 schema 的全部 source/result label 名称。",
-                    "format": "binary",
-                    "type": "string"
-                  }
-                },
-                "required": [
-                  "file"
-                ],
-                "type": "object"
-              }
-            }
-          },
-          "required": true
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **映射数据管理**（`on-call`） |\n\n## 使用说明\n\n- 每行以来源标签值作为标识。来源标签值与已有行相同时整行替换，其 `created_at` 和 `updated_at` 会被重置。\n- 每行必须包含全部来源标签和结果标签（否则返回 `InvalidParameter`），其他键会被丢弃；值超过 2,048 字节会被拒绝。\n- 同一请求中来源标签值相同的多行会合并，以后出现的行为准。\n- 每个映射规则默认最多 10,000 行（部分账户更高）。会使行数超过上限的请求返回 `InvalidParameter`；只替换已有行的请求不受影响。\n- 数据每 100 行一批写入；某一批失败时，之前已写入的批次不会回滚。\n- 映射规则必须存在且未被删除，否则返回 `InvalidParameter`。\n- 仅账户管理员、映射规则创建者或映射规则所属团队的成员可以调用，其他人返回 `AccessDenied`。\n- 同一映射规则的数据写操作（写入、删除、清空、CSV 上传）串行执行；另一个写操作进行中时调用会返回 `RequestTooFrequently`。",
+          "href": "/zh/api-reference/on-call/alert-enrichment/mapping-data-write-upsert",
+          "metadata": {
+            "sidebarTitle": "写入映射数据"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/EmptyResponse"
+                          "$ref": "#/components/schemas/MappingDataUpsertResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "keys": [
+                      "server01",
+                      "server02"
+                    ]
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -39245,6 +40627,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -39252,81 +40637,79 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "通过 CSV 上传映射数据",
-        "tags": [
-          "On-call/标签增强"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **20 次/分钟**；**2 次/秒** |\n| 权限要求 | **映射数据管理**（`on-call`） |\n\n## 使用说明\n\n- 请求须使用 `Content-Type: multipart/form-data`，文件字段名为 `file`，`schema_id` 通过查询参数传入。\n- CSV 标题行须包含所有来源标签和结果标签名称。\n- 文件大小上限：100 MB。\n- 默认情况下，导入前先清空现有数据；传入查询参数 `do_not_truncate_first=TRUE` 可改为追加模式。\n- CSV 中存在重复来源标签组合时返回 400 错误。",
-          "href": "/zh/api-reference/on-call/alert-enrichment/mapping-data-write-upload",
-          "metadata": {
-            "sidebarTitle": "通过 CSV 上传映射数据"
-          }
-        }
-      }
-    },
-    "/enrichment/mapping/data/upsert": {
-      "post": {
-        "description": "向映射规则中插入或更新最多 1000 条数据行，每行须包含所有来源标签和结果标签。",
-        "operationId": "mapping-data-write-upsert",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/MappingDataUpsertRequest"
+              },
               "example": {
+                "schema_id": "665f1a2b3c4d5e6f7a8b9c01",
                 "docs": [
                   {
                     "host": "server01",
                     "owner": "alice",
-                    "service": "api",
-                    "team": "sre"
+                    "team": "sre",
+                    "service": "api"
                   },
                   {
                     "host": "server02",
                     "owner": "bob",
-                    "service": "gateway",
-                    "team": "platform"
+                    "team": "platform",
+                    "service": "gateway"
                   }
-                ],
-                "schema_id": "665f1a2b3c4d5e6f7a8b9c01"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/MappingDataUpsertRequest"
+                ]
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/enrichment/mapping/schema/create": {
+      "post": {
+        "operationId": "mapping-schema-write-create",
+        "summary": "创建映射规则",
+        "description": "创建映射规则，定义用于查找的来源标签和要填充的结果标签。",
+        "tags": [
+          "On-call/标签增强"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **映射数据管理**（`on-call`） |\n\n## 使用说明\n\n- 需要专业版或更高版本的订阅，否则返回 `NoLicense`。\n- `schema_name` 在账户未删除的映射规则中必须唯一。\n- `source_labels`（1–3 个）组成查找键，`result_labels`（1–10 个）在匹配后写入告警。标签名须匹配 `^[a-zA-Z_][a-zA-Z0-9_]*$`，列表内不得重复，两个列表不得重叠。两个列表创建后都不能修改。\n- 每个账户默认最多 20 个未删除的映射规则（部分账户上限更高），超出返回 `InvalidParameter`。\n- 同一账户并发创建会返回 `RequestTooFrequently`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "href": "/zh/api-reference/on-call/alert-enrichment/mapping-schema-write-create",
+          "metadata": {
+            "sidebarTitle": "创建映射规则"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "keys": [
-                      "server01",
-                      "server02"
-                    ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/MappingDataUpsertResponse"
+                          "$ref": "#/components/schemas/MappingSchemaCreateResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "schema_id": "665f1a2b3c4d5e6f7a8b9c01",
+                    "schema_name": "CMDB Lookup"
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -39334,6 +40717,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -39341,74 +40727,71 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "写入映射数据",
-        "tags": [
-          "On-call/标签增强"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **映射数据管理**（`on-call`） |\n\n## 使用说明\n\n- 每条数据须包含映射规则中定义的所有来源标签和结果标签的值。\n- 未知标签的值将被静默忽略。\n- 每个值最多 2048 个字符。\n- Upsert 以来源标签组合为键，来源键相同的行将被更新。\n- 单个映射规则默认最多存储 10,000 条数据。\n- 每个映射规则的写入操作有锁保护，并发 Upsert 可能返回 `ErrRequestTooFrequently`。",
-          "href": "/zh/api-reference/on-call/alert-enrichment/mapping-data-write-upsert",
-          "metadata": {
-            "sidebarTitle": "写入映射数据"
-          }
-        }
-      }
-    },
-    "/enrichment/mapping/schema/create": {
-      "post": {
-        "description": "创建新的映射规则，定义查找来源标签和待填充的结果标签。需要 Pro 计划。",
-        "operationId": "mapping-schema-write-create",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/MappingSchemaCreateRequest"
+              },
               "example": {
+                "schema_name": "CMDB Lookup",
                 "description": "Enrich alerts with CMDB data",
+                "source_labels": [
+                  "host"
+                ],
                 "result_labels": [
                   "owner",
                   "team",
                   "service"
-                ],
-                "schema_name": "CMDB Lookup",
-                "source_labels": [
-                  "host"
                 ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/MappingSchemaCreateRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/enrichment/mapping/schema/delete": {
+      "post": {
+        "operationId": "mapping-schema-write-delete",
+        "summary": "删除映射规则",
+        "description": "删除映射规则及其全部数据行；仍被富化规则或机器人 Webhook 引用时拒绝删除。",
+        "tags": [
+          "On-call/标签增强"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **映射数据管理**（`on-call`） |\n\n## 使用说明\n\n- 映射规则被软删除（`status` 变为 `deleted`），其全部数据行被永久删除。\n- 若有集成的富化规则、或分派策略中的飞书 / 企业微信 / Zoom 机器人 Webhook 引用该映射规则，返回 HTTP 400 `ReferenceExist`，`data.refs` 列出引用方（每项含 `kind`（`integration` 或 `escalate_rule`）、`name`、`href`），集成最多列出 20 个。\n- `schema_id` 不存在时返回 `InvalidParameter`。\n- 仅账户管理员、映射规则创建者或映射规则所属团队的成员可以调用，其他人返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "href": "/zh/api-reference/on-call/alert-enrichment/mapping-schema-write-delete",
+          "metadata": {
+            "sidebarTitle": "删除映射规则"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "schema_id": "665f1a2b3c4d5e6f7a8b9c01",
-                    "schema_name": "CMDB Lookup"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/MappingSchemaCreateResponse"
+                          "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -39416,6 +40799,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -39423,62 +40809,80 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "创建映射规则",
-        "tags": [
-          "On-call/标签增强"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **映射数据管理**（`on-call`） |\n\n## 使用说明\n\n- 映射规则名称在账户内唯一。\n- `source_labels`（1–3 个）为查找键，`result_labels`（1–10 个）为匹配后写入的标签。\n- 标签名须匹配 `^[a-zA-Z_][a-zA-Z0-9_]*$`，且各列表内不得重复。\n- `source_labels` 与 `result_labels` 不得重叠。\n- 账户最多可创建 20 个映射规则。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
-          "href": "/zh/api-reference/on-call/alert-enrichment/mapping-schema-write-create",
-          "metadata": {
-            "sidebarTitle": "创建映射规则"
-          }
-        }
-      }
-    },
-    "/enrichment/mapping/schema/delete": {
-      "post": {
-        "description": "删除映射规则及其所有关联数据。若该规则被富化规则或 Webhook 引用，则拒绝删除。",
-        "operationId": "mapping-schema-write-delete",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {
-                "schema_id": "665f1a2b3c4d5e6f7a8b9c01"
-              },
               "schema": {
                 "$ref": "#/components/schemas/MappingSchemaIDRequest"
+              },
+              "example": {
+                "schema_id": "665f1a2b3c4d5e6f7a8b9c01"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/enrichment/mapping/schema/info": {
+      "post": {
+        "operationId": "mapping-schema-read-info",
+        "summary": "查看映射规则详情",
+        "description": "根据映射规则 ID 返回单个映射规则的详细信息。",
+        "tags": [
+          "On-call/标签增强"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **集成中心查看**（`on-call`） 或 **集成中心管理**（`on-call`） 或 **映射数据查看**（`on-call`） 或 **映射数据管理**（`on-call`） |\n\n## 使用说明\n\n- 账户内不存在该 ID 的映射规则时返回 `data: null`。\n- 已软删除的映射规则仍会返回，此时 `status` 为 `deleted`。",
+          "href": "/zh/api-reference/on-call/alert-enrichment/mapping-schema-read-info",
+          "metadata": {
+            "sidebarTitle": "查看映射规则详情"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/EmptyResponse"
+                          "$ref": "#/components/schemas/MappingSchemaItem"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "schema_id": "665f1a2b3c4d5e6f7a8b9c01",
+                    "schema_name": "CMDB Lookup",
+                    "description": "Enrich alerts with CMDB data",
+                    "source_labels": [
+                      "host"
+                    ],
+                    "result_labels": [
+                      "owner",
+                      "team",
+                      "service"
+                    ],
+                    "status": "enabled",
+                    "team_id": 0,
+                    "creator_id": 80011,
+                    "updated_by": 80011,
+                    "created_at": 1710000000,
+                    "updated_at": 1710000000
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -39486,6 +40890,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -39493,79 +40900,85 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "删除映射规则",
-        "tags": [
-          "On-call/标签增强"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **映射数据管理**（`on-call`） |\n\n## 使用说明\n\n- 若映射规则仍被引用，响应返回 HTTP 400，`refs` 字段列出所有阻止删除的引用。\n- 仅映射规则创建者、账户管理员或所属团队成员可删除。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。\n- 本接口为高危操作。控制台 JWT 调用需二次验证码；`app_key` 调用跳过 MFA 但仍会被完整记录，请妥善保管 app_key。",
-          "href": "/zh/api-reference/on-call/alert-enrichment/mapping-schema-write-delete",
-          "metadata": {
-            "sidebarTitle": "删除映射规则"
-          }
-        }
-      }
-    },
-    "/enrichment/mapping/schema/info": {
-      "post": {
-        "description": "根据映射规则 ID 返回单个映射规则的详细信息。",
-        "operationId": "mapping-schema-read-info",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {
-                "schema_id": "665f1a2b3c4d5e6f7a8b9c01"
-              },
               "schema": {
                 "$ref": "#/components/schemas/MappingSchemaIDRequest"
+              },
+              "example": {
+                "schema_id": "665f1a2b3c4d5e6f7a8b9c01"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/enrichment/mapping/schema/list": {
+      "post": {
+        "operationId": "mapping-schema-read-list",
+        "summary": "查询映射规则列表",
+        "description": "返回账户下的全部映射规则，按创建时间倒序排列。",
+        "tags": [
+          "On-call/标签增强"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间查看**（`on-call`） 或 **协作空间管理**（`on-call`） 或 **集成中心查看**（`on-call`） 或 **集成中心管理**（`on-call`） 或 **映射数据查看**（`on-call`） 或 **映射数据管理**（`on-call`） |\n\n## 使用说明\n\n- 一次返回账户下全部未删除的映射规则，不分页；`total` 即条目数。\n- 返回所有团队的映射规则，不按团队过滤。",
+          "href": "/zh/api-reference/on-call/alert-enrichment/mapping-schema-read-list",
+          "metadata": {
+            "sidebarTitle": "查询映射规则列表"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "created_at": 1710000000,
-                    "creator_id": 80011,
-                    "description": "Enrich alerts with CMDB data",
-                    "result_labels": [
-                      "owner",
-                      "team",
-                      "service"
-                    ],
-                    "schema_id": "665f1a2b3c4d5e6f7a8b9c01",
-                    "schema_name": "CMDB Lookup",
-                    "source_labels": [
-                      "host"
-                    ],
-                    "status": "enabled",
-                    "team_id": 0,
-                    "updated_at": 1710000000
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/MappingSchemaItem"
+                          "$ref": "#/components/schemas/MappingSchemaListResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "total": 1,
+                    "items": [
+                      {
+                        "schema_id": "665f1a2b3c4d5e6f7a8b9c01",
+                        "schema_name": "CMDB Lookup",
+                        "description": "Enrich alerts with CMDB data",
+                        "source_labels": [
+                          "host"
+                        ],
+                        "result_labels": [
+                          "owner",
+                          "team",
+                          "service"
+                        ],
+                        "status": "enabled",
+                        "team_id": 0,
+                        "creator_id": 80011,
+                        "updated_by": 80011,
+                        "created_at": 1710000000,
+                        "updated_at": 1710000000
+                      }
+                    ]
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -39573,6 +40986,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -39580,82 +40996,60 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "查看映射规则详情",
-        "tags": [
-          "On-call/标签增强"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **集成中心查看**（`on-call`） 或 **集成中心管理**（`on-call`） 或 **映射数据查看**（`on-call`） 或 **映射数据管理**（`on-call`） |\n\n## 使用说明\n\n- 映射规则不存在时返回 `null`。",
-          "href": "/zh/api-reference/on-call/alert-enrichment/mapping-schema-read-info",
-          "metadata": {
-            "sidebarTitle": "查看映射规则详情"
-          }
-        }
-      }
-    },
-    "/enrichment/mapping/schema/list": {
-      "post": {
-        "description": "返回账户下所有映射规则，按创建时间升序排列。",
-        "operationId": "mapping-schema-read-list",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {},
               "schema": {
                 "$ref": "#/components/schemas/EmptyRequest"
-              }
+              },
+              "example": {}
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/enrichment/mapping/schema/update": {
+      "post": {
+        "operationId": "mapping-schema-write-update",
+        "summary": "更新映射规则",
+        "description": "更新映射规则的名称、描述或所属团队。来源标签和结果标签创建后不可更改。",
+        "tags": [
+          "On-call/标签增强"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **映射数据管理**（`on-call`） |\n\n## 使用说明\n\n- 不传的字段保持原值；`team_id` 传 `0` 表示解除团队关联。\n- `schema_id` 不存在时返回 `InvalidParameter`；新的 `schema_name` 不能与其他映射规则重名。\n- 仅账户管理员、映射规则创建者或映射规则所属团队的成员可以调用，其他人返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "href": "/zh/api-reference/on-call/alert-enrichment/mapping-schema-write-update",
+          "metadata": {
+            "sidebarTitle": "更新映射规则"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "items": [
-                      {
-                        "created_at": 1710000000,
-                        "creator_id": 80011,
-                        "description": "Enrich alerts with CMDB data",
-                        "result_labels": [
-                          "owner",
-                          "team",
-                          "service"
-                        ],
-                        "schema_id": "665f1a2b3c4d5e6f7a8b9c01",
-                        "schema_name": "CMDB Lookup",
-                        "source_labels": [
-                          "host"
-                        ],
-                        "status": "enabled",
-                        "team_id": 0,
-                        "updated_at": 1710000000
-                      }
-                    ],
-                    "total": 1
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/MappingSchemaListResponse"
+                          "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -39663,6 +41057,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -39670,64 +41067,64 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "查询映射规则列表",
-        "tags": [
-          "On-call/标签增强"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间查看**（`on-call`） 或 **协作空间管理**（`on-call`） 或 **集成中心查看**（`on-call`） 或 **集成中心管理**（`on-call`） 或 **映射数据查看**（`on-call`） 或 **映射数据管理**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/alert-enrichment/mapping-schema-read-list",
-          "metadata": {
-            "sidebarTitle": "查询映射规则列表"
-          }
-        }
-      }
-    },
-    "/enrichment/mapping/schema/update": {
-      "post": {
-        "description": "更新映射规则的名称、描述或所属团队。来源标签和结果标签创建后不可更改。",
-        "operationId": "mapping-schema-write-update",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {
-                "description": "Updated description",
-                "schema_id": "665f1a2b3c4d5e6f7a8b9c01",
-                "schema_name": "CMDB Lookup v2"
-              },
               "schema": {
                 "$ref": "#/components/schemas/MappingSchemaUpdateRequest"
+              },
+              "example": {
+                "schema_id": "665f1a2b3c4d5e6f7a8b9c01",
+                "schema_name": "CMDB Lookup v2",
+                "description": "Updated description"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/enrichment/upsert": {
+      "post": {
+        "operationId": "enrichment-write-upsert",
+        "summary": "创建或替换富化规则",
+        "description": "创建或整体替换某个集成的告警富化规则集。",
+        "tags": [
+          "On-call/标签增强"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） 或 **集成中心管理**（`on-call`） |\n\n## 使用说明\n\n- `rules` 整体替换已存的规则集，传 `[]` 可删除全部规则。\n- 集成必须存在（否则返回 `InvalidParameter`），且调用方须有权编辑该集成：账户管理员、集成创建者、能编辑其所属协作空间的成员（协作空间内的集成），或集成所属团队的成员；既无团队也不属于协作空间的集成任何成员都可编辑。其他人返回 `AccessDenied`。\n- 规则按数组顺序作用于每个进入的告警事件和变更事件，后面的规则能看到前面规则写入的标签。`if` 条件未全部满足的规则会被跳过；运行时失败的规则（正则未匹配、映射未命中、API 调用失败等）同样跳过，不影响事件本身。\n- `if` 中的条件键必须是告警或变更事件的键（如 `title`、`description`、`labels.<name>`），其他键返回 `InvalidParameter`。\n- 保存时不校验 `schema_id`、`api_id` 是否存在；指向不存在或已删除的映射规则 / API 的规则在运行时不生效。`mapping_type` 为 `api` 的 `mapping` 规则只对告警事件生效。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "href": "/zh/api-reference/on-call/alert-enrichment/enrichment-write-upsert",
+          "metadata": {
+            "sidebarTitle": "创建或替换富化规则"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -39735,6 +41132,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -39742,81 +41142,84 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "更新映射规则",
-        "tags": [
-          "On-call/标签增强"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **映射数据管理**（`on-call`） |\n\n## 使用说明\n\n- 仅映射规则创建者、账户管理员或所属团队成员可更新。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
-          "href": "/zh/api-reference/on-call/alert-enrichment/mapping-schema-write-update",
-          "metadata": {
-            "sidebarTitle": "更新映射规则"
-          }
-        }
-      }
-    },
-    "/enrichment/upsert": {
-      "post": {
-        "description": "创建或全量替换指定集成的告警富化规则集，`rules` 数组将被原子替换。",
-        "operationId": "enrichment-write-upsert",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/EnrichmentUpsertRequest"
+              },
               "example": {
                 "integration_id": 5001,
                 "rules": [
                   {
                     "kind": "extraction",
                     "settings": {
-                      "override": true,
-                      "pattern": "(?P<result>prod|staging|dev)",
+                      "source_field": "labels.env",
                       "result_label": "environment",
-                      "source_field": "labels.env"
+                      "pattern": "(?P<result>prod|staging|dev)",
+                      "override": true
                     }
                   },
                   {
                     "kind": "composition",
                     "settings": {
-                      "override": false,
                       "result_label": "full_env",
-                      "template": "{{.Labels.region}}-{{.Labels.environment}}"
+                      "template": "{{.Labels.region}}-{{.Labels.environment}}",
+                      "override": false
                     }
                   }
                 ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/EnrichmentUpsertRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/field/create": {
+      "post": {
+        "operationId": "field-write-create",
+        "summary": "创建自定义字段",
+        "description": "为账号新建一个故障自定义字段。",
+        "tags": [
+          "On-call/标签增强"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **自定义字段管理**（`on-call`） |\n\n## 使用说明\n\n- 需要标准版或更高版本的订阅，否则返回 `NoLicense`。\n- 每个账户默认最多 15 个未删除的自定义字段（部分账户上限更高），超出返回 `InvalidParameter`。\n- `field_name` 为 1–39 个字符，须匹配 `^[a-zA-Z_][a-zA-Z0-9_]*$`，唯一且创建后不可修改。已删除字段的名称只能在 `field_type` 和 `value_type` 都相同时复用。`display_name` 在未删除字段中须唯一。\n- 类型规则：`checkbox` 要求 `value_type=bool` 且不带 `options`；`single_select`/`multi_select` 要求 `value_type=string` 且 `options` 非空、不重复；`text` 要求 `value_type=string` 且不带 `options`。\n- 响应只包含 `field_id` 和 `field_name`，完整信息请调用 `/field/info`。\n- 同一账户并发创建会返回 `RequestTooFrequently`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "href": "/zh/api-reference/on-call/alert-enrichment/field-write-create",
+          "metadata": {
+            "sidebarTitle": "创建自定义字段"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/EmptyResponse"
+                          "$ref": "#/components/schemas/CreateFieldResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "field_id": "66e9d3a4f7c2b04a1c8a91b3",
+                    "field_name": "severity_class"
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -39824,6 +41227,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -39831,187 +41237,117 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "创建或替换富化规则",
-        "tags": [
-          "On-call/标签增强"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间管理**（`on-call`） 或 **集成中心管理**（`on-call`） |\n\n## 使用说明\n\n- 富化规则按顺序依次执行。\n- 每条规则有一个 `kind`：`extraction`（正则/gjson 提取）、`composition`（模板组合标签）、`mapping`（通过映射规则或 API 查找）、`drop`（删除标签）。\n- 可选的 `if` 字段为 `AndFilters` 条件，不匹配时跳过该规则。\n- `kind: extraction`：`source_field` 须为 `title`、`description` 或 `labels.*` 前缀的键；`pattern`（RE2 正则，捕获组用空格连接后写入 `result_label`）和 `g_json`（GJson 路径）二选一。\n- `kind: composition`：`template` 为基于事件结构体渲染的 Go text/template，如 `{{.Title}}`、`{{.Description}}`、`{{.Labels.key}}`。\n- `kind: mapping`：`mapping_type` 为 `schema`（默认）或 `api`；分别提供 `schema_id` 或 `api_id`。\n- `kind: drop`：`drop_labels` 列出要删除的标签键名。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
-          "href": "/zh/api-reference/on-call/alert-enrichment/enrichment-write-upsert",
-          "metadata": {
-            "sidebarTitle": "创建或替换富化规则"
-          }
-        }
-      }
-    },
-    "/field/create": {
-      "post": {
-        "description": "为账号新建一个故障自定义字段。",
-        "operationId": "field-write-create",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CreateFieldRequest"
+              },
               "example": {
-                "default_value": "Medium",
-                "description": "Business severity tier.",
-                "display_name": "Severity Class",
                 "field_name": "severity_class",
+                "display_name": "Severity Class",
+                "description": "Business severity tier.",
                 "field_type": "single_select",
+                "value_type": "string",
                 "options": [
                   "Critical",
                   "High",
                   "Medium",
                   "Low"
                 ],
-                "value_type": "string"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/CreateFieldRequest"
+                "default_value": "Medium"
               }
             }
-          },
-          "required": true
-        },
-        "responses": {
-          "200": {
-            "content": {
-              "application/json": {
-                "example": {
-                  "data": {
-                    "field_id": "66e9d3a4f7c2b04a1c8a91b3",
-                    "field_name": "severity_class"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/CreateFieldResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
-                }
-              }
-            },
-            "description": "成功"
-          },
-          "400": {
-            "$ref": "#/components/responses/BadRequest"
-          },
-          "401": {
-            "$ref": "#/components/responses/Unauthorized"
-          },
-          "429": {
-            "$ref": "#/components/responses/TooManyRequests"
-          },
-          "500": {
-            "$ref": "#/components/responses/ServerError"
-          }
-        },
-        "summary": "创建自定义字段",
-        "tags": [
-          "On-call/标签增强"
-        ],
-        "x-mint": {
-          "content": "## 调用限制\n\n| 项 | 值 |\n| ------ | ----- |\n| 速率限制 | 每账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限 | **故障可管理** (`on-call`) |\n\n## 使用说明\n\n- 每个账号最多 **15** 个自定义字段。\n- `field_name` 必须匹配 `^[a-zA-Z_][a-zA-Z0-9_]{0,39}$`，创建后不可更改；`display_name` 在账号内须唯一。\n- 类型规则：`checkbox` 仅支持 `value_type=bool` 且无 `options`；`single_select`/`multi_select` 要求 `value_type=string` 且 `options` 非空且元素唯一；`text` 仅支持 `value_type=string` 且无 `options`。\n- 响应仅包含 `field_id` 与 `field_name`，如需完整对象请调用 `/field/info`。\n- 该接口会被审计日志记录。",
-          "href": "/zh/api-reference/on-call/alert-enrichment/field-write-create",
-          "metadata": {
-            "sidebarTitle": "创建自定义字段"
           }
         }
       }
     },
     "/field/delete": {
       "post": {
-        "description": "删除自定义字段，并异步清理历史故障中的同名字段值。",
         "operationId": "field-write-delete",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "field_id": "66e9d3a4f7c2b04a1c8a91b3"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/DeleteFieldRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "删除自定义字段",
+        "description": "删除自定义字段，并异步清理历史故障中的同名字段值。",
+        "tags": [
+          "On-call/标签增强"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **自定义字段管理**（`on-call`） |\n\n## 使用说明\n\n- 若有自定义表单引用该字段，返回 HTTP 400 `ReferenceExist`，`data.refs` 列出引用的表单；需先移除引用。\n- 字段立即被标记为已删除，随后后台任务清除历史故障中的该字段值，最后删除字段记录。\n- 删除已删除的字段直接返回成功；`field_id` 不存在时返回 `InvalidParameter`。\n- 之后只有 `field_type` 和 `value_type` 都相同时才能复用该 `field_name`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "href": "/zh/api-reference/on-call/alert-enrichment/field-write-delete",
+          "metadata": {
+            "sidebarTitle": "删除自定义字段"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "type": "object"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
+            "description": "请求参数无效，或该字段仍被自定义表单引用。",
             "content": {
               "application/json": {
+                "schema": {
+                  "oneOf": [
+                    {
+                      "$ref": "#/components/schemas/ErrorResponse"
+                    },
+                    {
+                      "$ref": "#/components/schemas/FieldDeleteReferenceError"
+                    }
+                  ]
+                },
                 "examples": {
                   "fieldStillReferenced": {
                     "value": {
+                      "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                      "error": {
+                        "code": "ReferenceExist",
+                        "message": "There still are associated resources, deletion is blocked."
+                      },
                       "data": {
                         "refs": [
                           {
-                            "href": "https://console.flashcat.cloud/forms/resolve",
                             "kind": "custom_form",
-                            "name": "Resolve incident"
+                            "name": "Resolve incident",
+                            "href": "https://console.flashcat.cloud/forms/resolve"
                           }
                         ]
-                      },
-                      "error": {
-                        "code": "ReferenceExist",
-                        "message": "There still are associated resources, deletion is blocked."
-                      },
-                      "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
+                      }
                     }
                   }
-                },
-                "schema": {
-                  "oneOf": [
-                    {
-                      "$ref": "#/components/schemas/ErrorResponse"
-                    },
-                    {
-                      "$ref": "#/components/schemas/FieldDeleteReferenceError"
-                    }
-                  ]
                 }
               }
-            },
-            "description": "请求参数无效，或该字段仍被自定义表单引用。"
+            }
           },
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -40019,82 +41355,82 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "删除自定义字段",
-        "tags": [
-          "On-call/标签增强"
-        ],
-        "x-mint": {
-          "content": "## 调用限制\n\n| 项 | 值 |\n| ------ | ----- |\n| 速率限制 | 每账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限 | **故障可管理** (`on-call`) |\n\n## 使用说明\n\n- 字段会被同步标记为已删除；历史故障中的字段值会在后台清理，大型数据集可能需要时间。\n- 仅当 `field_type` 和 `value_type` 与已删除字段一致时，才能使用相同 `field_name` 重新创建。\n- 自定义表单仍使用该字段时，删除会返回 `ReferenceExist`，引用表单位于 `data.refs`；移除所有引用后才能删除。\n- 已审计 —— 变更会记录到审计日志。",
-          "href": "/zh/api-reference/on-call/alert-enrichment/field-write-delete",
-          "metadata": {
-            "sidebarTitle": "删除自定义字段"
-          }
-        }
-      }
-    },
-    "/field/info": {
-      "post": {
-        "description": "按 ID 查询单个故障自定义字段的配置。",
-        "operationId": "field-read-info",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/DeleteFieldRequest"
+              },
               "example": {
                 "field_id": "66e9d3a4f7c2b04a1c8a91b3"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/FieldInfoRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/field/info": {
+      "post": {
+        "operationId": "field-read-info",
+        "summary": "查看自定义字段",
+        "description": "按 ID 查询单个故障自定义字段的配置。",
+        "tags": [
+          "On-call/标签增强"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **自定义字段查看**（`on-call`） 或 **自定义字段管理**（`on-call`） |\n\n## 使用说明\n\n- `field_id` 不存在时返回 `InvalidParameter`。已删除的字段在 `/field/delete` 触发的后台清理完成前仍会返回，`status` 为 `deleted`；清理完成后该 ID 视为不存在。\n- `options` 和 `default_value` 的结构取决于 `field_type`，详见 `FieldItem`。",
+          "href": "/zh/api-reference/on-call/alert-enrichment/field-read-info",
+          "metadata": {
+            "sidebarTitle": "查看自定义字段"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/FieldItem"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "account_id": 80001,
-                    "created_at": 1710000000,
-                    "creator_id": 80011,
-                    "default_value": "Medium",
-                    "description": "Business severity tier.",
-                    "display_name": "Severity Class",
                     "field_id": "66e9d3a4f7c2b04a1c8a91b3",
                     "field_name": "severity_class",
+                    "display_name": "Severity Class",
+                    "description": "Business severity tier.",
                     "field_type": "single_select",
+                    "value_type": "string",
                     "options": [
                       "Critical",
                       "High",
                       "Medium",
                       "Low"
                     ],
+                    "default_value": "Medium",
                     "status": "enabled",
-                    "updated_at": 1710000000,
+                    "creator_id": 80011,
                     "updated_by": 80011,
-                    "value_type": "string"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/FieldItem"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                    "created_at": 1710000000,
+                    "updated_at": 1710000000
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -40102,6 +41438,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -40109,88 +41448,86 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "查看自定义字段",
-        "tags": [
-          "On-call/标签增强"
-        ],
-        "x-mint": {
-          "content": "## 调用限制\n\n| 项 | 值 |\n| ------ | ----- |\n| 速率限制 | 每账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限 | **故障可读** (`on-call`) 或 **故障可管理** (`on-call`) |\n\n## 使用说明\n\n- `field_id` 不存在时返回 400；已软删除的字段仍会返回，此时 `status` 为 `deleted` 且带 `deleted_at`。\n- `options` 与 `default_value` 的形态随 `field_type` 变化，详见 `FieldItem`。",
-          "href": "/zh/api-reference/on-call/alert-enrichment/field-read-info",
-          "metadata": {
-            "sidebarTitle": "查看自定义字段"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/FieldInfoRequest"
+              },
+              "example": {
+                "field_id": "66e9d3a4f7c2b04a1c8a91b3"
+              }
+            }
           }
         }
       }
     },
     "/field/list": {
       "post": {
-        "description": "返回账号下所有的故障自定义字段。",
         "operationId": "field-read-list",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "asc": false,
-                "orderby": "updated_at",
-                "query": "severity"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/FieldListRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "查看自定义字段列表",
+        "description": "返回账号下所有的故障自定义字段。",
+        "tags": [
+          "On-call/标签增强"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **自定义字段查看**（`on-call`） 或 **自定义字段管理**（`on-call`） 或 **协作空间查看**（`on-call`） 或 **协作空间管理**（`on-call`） 或 **故障查看**（`on-call`） 或 **故障管理**（`on-call`） 或 **集成中心查看**（`on-call`） 或 **集成中心管理**（`on-call`） 或 **模板查看**（`on-call`） 或 **模板管理**（`on-call`） |\n\n## 使用说明\n\n- 一次返回全部未删除的字段，无分页、无 `total`。按 `orderby`（默认 `created_at`）排序，默认倒序，`asc` 为 `true` 时正序。\n- `query` 是对 `field_name` 的正则匹配，不区分大小写；不合法的正则按普通文本匹配。",
+          "href": "/zh/api-reference/on-call/alert-enrichment/field-read-list",
+          "metadata": {
+            "sidebarTitle": "查看自定义字段列表"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/FieldListResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "items": [
-                      {
-                        "account_id": 80001,
-                        "created_at": 1710000000,
-                        "creator_id": 80011,
-                        "default_value": "Medium",
-                        "description": "Business severity tier.",
-                        "display_name": "Severity Class",
+                      {
+                        "account_id": 80001,
                         "field_id": "66e9d3a4f7c2b04a1c8a91b3",
                         "field_name": "severity_class",
+                        "display_name": "Severity Class",
+                        "description": "Business severity tier.",
                         "field_type": "single_select",
+                        "value_type": "string",
                         "options": [
                           "Critical",
                           "High",
                           "Medium",
                           "Low"
                         ],
+                        "default_value": "Medium",
                         "status": "enabled",
-                        "updated_at": 1710000000,
+                        "creator_id": 80011,
                         "updated_by": 80011,
-                        "value_type": "string"
+                        "created_at": 1710000000,
+                        "updated_at": 1710000000
                       }
                     ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/FieldListResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -40198,6 +41535,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -40205,71 +41545,64 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "查看自定义字段列表",
-        "tags": [
-          "On-call/标签增强"
-        ],
-        "x-mint": {
-          "content": "## 调用限制\n\n| 项 | 值 |\n| ------ | ----- |\n| 速率限制 | 每账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限 | **故障可读** (`on-call`) 或 **故障可管理** (`on-call`) |\n\n## 使用说明\n\n- 一次性返回全部未删除字段，无分页与 `total`。\n- `query` 仅匹配 `field_name`；非法正则会自动转义为字面量子串匹配。",
-          "href": "/zh/api-reference/on-call/alert-enrichment/field-read-list",
-          "metadata": {
-            "sidebarTitle": "查看自定义字段列表"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/FieldListRequest"
+              },
+              "example": {
+                "orderby": "updated_at",
+                "asc": false,
+                "query": "severity"
+              }
+            }
           }
         }
       }
     },
     "/field/update": {
       "post": {
-        "description": "修改已有自定义字段的可变属性。",
         "operationId": "field-write-update",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "default_value": "Medium",
-                "description": "Business severity tier.",
-                "display_name": "Severity Class",
-                "field_id": "66e9d3a4f7c2b04a1c8a91b3",
-                "options": [
-                  "Critical",
-                  "High",
-                  "Medium",
-                  "Low"
-                ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/UpdateFieldRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "变更自定义字段",
+        "description": "修改已有自定义字段的可变属性。",
+        "tags": [
+          "On-call/标签增强"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **自定义字段管理**（`on-call`） |\n\n## 使用说明\n\n- 每次调用都会用请求值覆盖 `display_name`、`description`、`options` 和 `default_value`，不传即被清空，请始终传完整的目标值。\n- `field_name`、`field_type`、`value_type` 不可修改；`options` 和 `default_value` 须满足创建时的类型规则。\n- `field_id` 不存在时返回 `InvalidParameter`；`display_name` 在未删除字段中须保持唯一。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "href": "/zh/api-reference/on-call/alert-enrichment/field-write-update",
+          "metadata": {
+            "sidebarTitle": "变更自定义字段"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "type": "object"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -40277,6 +41610,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -40284,64 +41620,71 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "变更自定义字段",
-        "tags": [
-          "On-call/标签增强"
-        ],
-        "x-mint": {
-          "content": "## 调用限制\n\n| 项 | 值 |\n| ------ | ----- |\n| 速率限制 | 每账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限 | **故障可管理** (`on-call`) |\n\n## 使用说明\n\n- 仅可修改 `display_name`、`description`、`options`、`default_value`；`field_name`、`field_type`、`value_type` 不可更改。\n- `options` 与 `default_value` 需保持与字段当前类型一致，规则同创建接口。\n- 该接口会被审计日志记录。",
-          "href": "/zh/api-reference/on-call/alert-enrichment/field-write-update",
-          "metadata": {
-            "sidebarTitle": "变更自定义字段"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/UpdateFieldRequest"
+              },
+              "example": {
+                "field_id": "66e9d3a4f7c2b04a1c8a91b3",
+                "display_name": "Severity Class",
+                "description": "Business severity tier.",
+                "options": [
+                  "Critical",
+                  "High",
+                  "Medium",
+                  "Low"
+                ],
+                "default_value": "Medium"
+              }
+            }
           }
         }
       }
     },
     "/incident/ack": {
       "post": {
-        "description": "认领一个故障以表明正在积极处理。",
         "operationId": "incidentAck",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "incident_ids": [
-                  "69da451ef77b1b51f40e83ee"
-                ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/AckIncidentRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "认领故障",
+        "description": "认领一个故障以表明正在积极处理。",
+        "tags": [
+          "On-call/故障管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **故障管理**或**协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 认领表单生效时，`custom_fields`、`summary` 和 `images` 必须符合其中可见元素及必填规则。\n- 批量操作只有在全部选中的故障解析到同一张表单时才接受表单值；否则请逐条认领。\n- 旧字段 `values` 和 `custom_values` 会被拒绝，请使用 `custom_fields`。\n- 调用成员若还不是处理人会被加入处理人，故障进入 `Processing`。重复认领自己已认领的故障不会产生变化。\n- 任一故障已关闭或 ID 不存在时整个请求返回 `InvalidParameter`。",
+          "href": "/zh/api-reference/on-call/incidents/incident-ack",
+          "metadata": {
+            "sidebarTitle": "认领故障"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -40349,6 +41692,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -40356,123 +41702,121 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "认领故障",
-        "tags": [
-          "On-call/故障管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障管理**（`on-call`） |\n\n## 使用说明\n\n- 认领表单生效时，`custom_fields`、`summary` 和 `images` 必须符合其中可见元素及必填规则。\n- 批量操作只有在全部选中的故障解析到同一张表单时才接受表单值；否则请逐条认领。\n- 旧字段 `values` 和 `custom_values` 会被拒绝，请使用 `custom_fields`。\n- 已审计 —— 变更会记录到审计日志。",
-          "href": "/zh/api-reference/on-call/incidents/incident-ack",
-          "metadata": {
-            "sidebarTitle": "认领故障"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/AckIncidentRequest"
+              },
+              "example": {
+                "incident_ids": [
+                  "69da451ef77b1b51f40e83ee"
+                ]
+              }
+            }
           }
         }
       }
     },
     "/incident/alert/list": {
       "post": {
-        "description": "查询合并到指定故障中的所有告警列表。",
         "operationId": "incidentAlertList",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "incident_id": "69da451ef77b1b51f40e83ee",
-                "include_events": true,
-                "is_active": true,
-                "limit": 100,
-                "p": 1
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ListIncidentAlertsRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "查询故障关联告警",
+        "description": "查询合并到指定故障中的所有告警列表。",
+        "tags": [
+          "On-call/故障管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障查看**或**故障管理**或**协作空间查看**或**协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 仅在需要预览每条告警的原始事件时设置 `include_events=true`。\n- 事件预览最多返回每条告警最新的 20 条事件；完整事件历史请使用 `POST /alert/event/list` 分页查询。\n- `event_cnt` 仍表示合并到每条告警的原始事件总数。\n- `p` 默认为 1；`limit` 不传或为 `0` 时每页最多返回 1,000 条告警。",
+          "href": "/zh/api-reference/on-call/incidents/incident-alert-list",
+          "metadata": {
+            "sidebarTitle": "查询故障关联告警"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/ListIncidentAlertsResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
+                    "total": 1,
                     "items": [
                       {
-                        "account_id": 2451002751131,
                         "alert_id": "69da451df77b1b51f40e83de",
+                        "integration_id": 2490562293131,
+                        "data_source_id": 2490562293131,
+                        "channel_id": 2551105804131,
+                        "account_id": 2451002751131,
+                        "description": "",
+                        "title": "CPU usage high - web-server-01",
+                        "title_rule": "",
                         "alert_key": "100128:prom-203.0.113.107:A:1579244238440766834:anydata",
                         "alert_severity": "Critical",
                         "alert_status": "Critical",
-                        "channel_id": 2551105804131,
+                        "start_time": 1775912219,
+                        "last_time": 1775969819,
+                        "end_time": 0,
+                        "labels": {
+                          "check": "cpu_usage_high",
+                          "resource": "web-server-01"
+                        },
+                        "ever_muted": false,
+                        "created_at": 1775912221,
+                        "updated_at": 1775969821,
+                        "integration_name": "FlashMonit",
+                        "integration_type": "monit.alert",
+                        "integration_ref_id": "a_2451002751131",
                         "channel_name": "Ops Channel",
                         "channel_status": "enabled",
-                        "created_at": 1775912221,
-                        "data_source_id": 2490562293131,
+                        "responder_name": "",
+                        "responder_email": "",
+                        "incident": {
+                          "incident_id": "69da451ef77b1b51f40e83ee",
+                          "title": "CPU usage high - web-server-01",
+                          "progress": "Triggered"
+                        },
+                        "event_cnt": 17,
+                        "images": null,
                         "data_source_name": "FlashMonit",
-                        "data_source_ref_id": "a_2451002751131",
                         "data_source_type": "monit.alert",
-                        "description": "",
-                        "end_time": 0,
-                        "event_cnt": 17,
+                        "data_source_ref_id": "a_2451002751131",
                         "events": [
                           {
-                            "alert_id": "69da451df77b1b51f40e83de",
                             "event_id": "69da451df77b1b51f40e83df",
+                            "alert_id": "69da451df77b1b51f40e83de",
+                            "title": "CPU usage > 90%",
                             "event_severity": "Critical",
                             "event_status": "Critical",
                             "event_time": 1712650000,
                             "labels": {
                               "host": "web-01"
-                            },
-                            "title": "CPU usage > 90%"
+                            }
                           }
-                        ],
-                        "ever_muted": false,
-                        "images": null,
-                        "incident": {
-                          "incident_id": "69da451ef77b1b51f40e83ee",
-                          "progress": "Triggered",
-                          "title": "CPU usage high - web-server-01"
-                        },
-                        "integration_id": 2490562293131,
-                        "integration_name": "FlashMonit",
-                        "integration_ref_id": "a_2451002751131",
-                        "integration_type": "monit.alert",
-                        "labels": {
-                          "check": "cpu_usage_high",
-                          "resource": "web-server-01"
-                        },
-                        "last_time": 1775969819,
-                        "responder_email": "",
-                        "responder_name": "",
-                        "start_time": 1775912219,
-                        "title": "CPU usage high - web-server-01",
-                        "title_rule": "",
-                        "updated_at": 1775969821
+                        ]
                       }
-                    ],
-                    "total": 1
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/ListIncidentAlertsResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                    ]
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -40480,6 +41824,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -40487,142 +41834,66 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "查询故障关联告警",
-        "tags": [
-          "On-call/故障管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障查看**（`on-call`） |\n\n## 使用说明\n\n- 仅在需要预览每条告警的原始事件时设置 `include_events=true`。\n- 事件预览最多返回每条告警最新的 20 条事件；完整事件历史请使用 `POST /alert/event/list` 分页查询。\n- `event_cnt` 仍表示合并到每条告警的原始事件总数。",
-          "href": "/zh/api-reference/on-call/incidents/incident-alert-list",
-          "metadata": {
-            "sidebarTitle": "查询故障关联告警"
-          }
-        }
-      }
-    },
-    "/incident/assign": {
-      "post": {
-        "description": "将故障分派到指定的升级环节或处理人员。",
-        "operationId": "incidentAssign",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {
-                "assigned_to": {
-                  "person_ids": [
-                    2476444212131
-                  ],
-                  "type": "assign"
-                },
-                "incident_id": "69da451ef77b1b51f40e83ee"
-              },
               "schema": {
-                "$ref": "#/components/schemas/AssignIncidentRequest"
+                "$ref": "#/components/schemas/ListIncidentAlertsRequest"
+              },
+              "example": {
+                "incident_id": "69da451ef77b1b51f40e83ee",
+                "is_active": true,
+                "limit": 100,
+                "p": 1,
+                "include_events": true
               }
             }
-          },
-          "required": true
-        },
-        "responses": {
-          "200": {
-            "content": {
-              "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/EmptyResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
-                }
-              }
-            },
-            "description": "成功"
-          },
-          "400": {
-            "$ref": "#/components/responses/BadRequest"
-          },
-          "401": {
-            "$ref": "#/components/responses/Unauthorized"
-          },
-          "429": {
-            "$ref": "#/components/responses/TooManyRequests"
-          },
-          "500": {
-            "$ref": "#/components/responses/ServerError"
           }
-        },
+        }
+      }
+    },
+    "/incident/assign": {
+      "post": {
+        "operationId": "incidentAssign",
         "summary": "分派故障",
+        "description": "将故障重新分派给成员或分派策略，替换当前处理人。",
         "tags": [
           "On-call/故障管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障管理**（`on-call`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **故障管理**或**协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 不在新分派对象中的处理人会被移除，保留下来的处理人维持原认领状态。若剩余处理人都未认领，故障回到 `Triggered`。同时清除暂停。\n- `assigned_to` 中 `person_ids`、`escalate_rule_id`、`emails` 都未设置时，服务端会改为重新匹配协作空间的分派策略。\n- 已关闭的故障会被跳过，不报错。\n- 服务端会填写 `assigned_at`、`id` 和 `escalate_rule_name`，未传 `type` 时自动推断。",
           "href": "/zh/api-reference/on-call/incidents/incident-assign",
           "metadata": {
             "sidebarTitle": "分派故障"
           }
-        }
-      }
-    },
-    "/incident/comment": {
-      "post": {
-        "description": "在故障时间线上添加文字评论。",
-        "operationId": "incidentComment",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "comment": "Root cause identified. [@Jane Doe](flashduty://ref/member/2476444212131) please verify the fix.",
-                "comment_type_id": "6a5895d672a064bc2d3ddfc2",
-                "incident_ids": [
-                  "69da451ef77b1b51f40e83ee"
-                ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/CommentIncidentRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -40630,6 +41901,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -40637,76 +41911,68 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/AssignIncidentRequest"
+              },
+              "example": {
+                "incident_id": "69da451ef77b1b51f40e83ee",
+                "assigned_to": {
+                  "person_ids": [
+                    2476444212131
+                  ],
+                  "type": "assign"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/incident/comment": {
+      "post": {
+        "operationId": "incidentComment",
         "summary": "评论故障",
+        "description": "在故障时间线上添加文字评论。",
         "tags": [
           "On-call/故障管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障管理**（`on-call`） |\n\n## 使用说明\n\n- 要提及成员，在 `comment` 中嵌入形如 `[@显示名](flashduty://ref/member/<member_id>)` 的 markdown 链接。被提及的成员会收到专门的个人通知，不受 `mute_reply` 影响。\n- 不带链接语法的纯 `@名字` 文本不会形成提及。\n- 服务端会将每个提及的显示名改写为成员的规范名称。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **故障管理**或**协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 要提及成员，在 `comment` 中嵌入形如 `[@显示名](flashduty://ref/member/<member_id>)` 的 markdown 链接。被提及的成员会收到专门的个人通知，不受 `mute_reply` 影响。\n- 不带链接语法的纯 `@名字` 文本不会形成提及。\n- 服务端会将每个提及的显示名改写为成员的规范名称。\n- 同一账户内有其他关闭、重开、合并、评论或删除操作正在执行时返回 `RequestTooFrequently`，稍后重试即可。",
           "href": "/zh/api-reference/on-call/incidents/incident-comment",
           "metadata": {
             "sidebarTitle": "评论故障"
-          }
-        }
-      }
-    },
-    "/incident/comment-type/create": {
-      "post": {
-        "description": "创建可附加到故障评论的评论类型。",
-        "operationId": "incidentCommentTypeCreate",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "color": "#30A46C",
-                "name": "Key finding"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/CreateIncidentCommentTypeRequest"
-              }
-            }
-          },
-          "required": true
-        },
-        "responses": {
-          "200": {
-            "content": {
-              "application/json": {
-                "example": {
-                  "data": {
-                    "comment_type_id": "6a5895d672a064bc2d3ddfc2",
-                    "item": {
-                      "account_id": 2451002751131,
-                      "color": "#30A46C",
-                      "comment_type_id": "6a5895d672a064bc2d3ddfc2",
-                      "created_at": 1784190422,
-                      "creator_id": 5068740052131,
-                      "name": "Key finding",
-                      "position": 1,
-                      "updated_at": 1784207748,
-                      "updated_by": 5068740052131
-                    }
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "成功",
+            "content": {
+              "application/json": {
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/CreateIncidentCommentTypeResponse"
+                          "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -40714,6 +41980,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -40721,62 +41990,79 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CommentIncidentRequest"
+              },
+              "example": {
+                "incident_ids": [
+                  "69da451ef77b1b51f40e83ee"
+                ],
+                "comment": "Root cause identified. [@Jane Doe](flashduty://ref/member/2476444212131) please verify the fix.",
+                "comment_type_id": "6a5895d672a064bc2d3ddfc2"
+              }
+            }
+          }
+        }
+      }
+    },
+    "/incident/comment-type/create": {
+      "post": {
+        "operationId": "incidentCommentTypeCreate",
         "summary": "创建评论类型",
+        "description": "创建可附加到故障评论的评论类型。",
         "tags": [
           "On-call/故障管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **评论类型管理**（`on-call`） |\n\n## 使用说明\n\n- 新类型追加到展示顺序的末尾。\n- 名称在账户内必须唯一（不区分大小写，忽略首尾空白）。\n- 每个账户最多可创建 10 个评论类型。\n- 该权限默认仅管理员拥有，自定义角色需显式授予。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **评论类型管理**（`on-call`） |\n\n## 使用说明\n\n- 新类型追加到展示顺序的末尾。\n- 名称在账户内必须唯一（不区分大小写，忽略首尾空白）。\n- 每个账户最多可创建 10 个评论类型。\n- 该权限默认仅管理员拥有，自定义角色需显式授予。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/on-call/incidents/incident-comment-type-create",
           "metadata": {
             "sidebarTitle": "创建评论类型"
           }
-        }
-      }
-    },
-    "/incident/comment-type/delete": {
-      "post": {
-        "description": "删除评论类型。已使用该类型的评论保留文本内容，但不再显示类型标签。",
-        "operationId": "incidentCommentTypeDelete",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "comment_type_id": "6a5895b572a064bc2d3ddfc0"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/DeleteIncidentCommentTypeRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/EmptyResponse"
+                          "$ref": "#/components/schemas/CreateIncidentCommentTypeResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "comment_type_id": "6a5895d672a064bc2d3ddfc2",
+                    "item": {
+                      "comment_type_id": "6a5895d672a064bc2d3ddfc2",
+                      "account_id": 2451002751131,
+                      "name": "Key finding",
+                      "color": "#30A46C",
+                      "position": 3,
+                      "creator_id": 5068740052131,
+                      "updated_by": 5068740052131,
+                      "created_at": 1784190422,
+                      "updated_at": 1784190422
+                    }
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -40784,6 +42070,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -40791,85 +42080,63 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CreateIncidentCommentTypeRequest"
+              },
+              "example": {
+                "name": "Key finding",
+                "color": "#30A46C"
+              }
+            }
+          }
+        }
+      }
+    },
+    "/incident/comment-type/delete": {
+      "post": {
+        "operationId": "incidentCommentTypeDelete",
         "summary": "删除评论类型",
+        "description": "永久删除评论类型；使用过它的评论保留内容，但不再显示该类型标签。",
         "tags": [
           "On-call/故障管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **评论类型管理**（`on-call`） |\n\n## 使用说明\n\n- 硬删除 —— 评论类型被永久移除，无法恢复。\n- 已引用该类型的评论会失去类型标签，其他内容不受影响。\n- 该权限默认仅管理员拥有，自定义角色需显式授予。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **评论类型管理**（`on-call`） |\n\n## 使用说明\n\n- 硬删除 —— 评论类型被永久移除，无法恢复。\n- 引用该类型的已有评论会失去类型标签，其他内容不受影响。\n- 该权限默认仅管理员拥有，自定义角色需显式授予。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/on-call/incidents/incident-comment-type-delete",
           "metadata": {
             "sidebarTitle": "删除评论类型"
           }
-        }
-      }
-    },
-    "/incident/comment-type/list": {
-      "post": {
-        "description": "获取账户下全部评论类型，按展示位置排序。",
-        "operationId": "incidentCommentTypeList",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {},
-              "schema": {
-                "$ref": "#/components/schemas/ListIncidentCommentTypesRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "items": [
-                      {
-                        "account_id": 2451002751131,
-                        "color": "#30A46C",
-                        "comment_type_id": "6a5895d672a064bc2d3ddfc2",
-                        "created_at": 1784190422,
-                        "creator_id": 5068740052131,
-                        "name": "Key finding",
-                        "position": 1,
-                        "updated_at": 1784207748,
-                        "updated_by": 5068740052131
-                      },
-                      {
-                        "account_id": 2451002751131,
-                        "color": "#998000",
-                        "comment_type_id": "6a5895b572a064bc2d3ddfc0",
-                        "created_at": 1784190389,
-                        "creator_id": 5068740052131,
-                        "name": "Hypothesis",
-                        "position": 2,
-                        "updated_at": 1785141535,
-                        "updated_by": 3790925372131
-                      }
-                    ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/ListIncidentCommentTypesResponse"
+                          "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -40877,6 +42144,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -40884,65 +42154,87 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/DeleteIncidentCommentTypeRequest"
+              },
+              "example": {
+                "comment_type_id": "6a5895b572a064bc2d3ddfc0"
+              }
+            }
+          }
+        }
+      }
+    },
+    "/incident/comment-type/list": {
+      "post": {
+        "operationId": "incidentCommentTypeList",
         "summary": "查询评论类型列表",
+        "description": "获取账户下全部评论类型，按展示位置排序。",
         "tags": [
           "On-call/故障管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障查看**（`on-call`） |\n\n## 使用说明\n\n- 一次调用返回完整列表，不分页。\n- 每个账户最多可创建 10 个评论类型。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障查看**（`on-call`）或 **评论类型管理**（`on-call`） |\n\n## 使用说明\n\n- 一次返回完整列表，不分页。\n- 每个账户最多可创建 10 个评论类型。",
           "href": "/zh/api-reference/on-call/incidents/incident-comment-type-list",
           "metadata": {
             "sidebarTitle": "查询评论类型列表"
           }
-        }
-      }
-    },
-    "/incident/comment-type/reorder": {
-      "post": {
-        "description": "传入账户全部评论类型 ID 的期望顺序，设置评论类型的展示顺序。",
-        "operationId": "incidentCommentTypeReorder",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "comment_type_ids": [
-                  "6a5895b572a064bc2d3ddfc0",
-                  "6a5895d672a064bc2d3ddfc2"
-                ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ReorderIncidentCommentTypesRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/EmptyResponse"
+                          "$ref": "#/components/schemas/ListIncidentCommentTypesResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "items": [
+                      {
+                        "comment_type_id": "6a5895d672a064bc2d3ddfc2",
+                        "account_id": 2451002751131,
+                        "name": "Key finding",
+                        "color": "#30A46C",
+                        "position": 1,
+                        "creator_id": 5068740052131,
+                        "updated_by": 5068740052131,
+                        "created_at": 1784190422,
+                        "updated_at": 1784207748
+                      },
+                      {
+                        "comment_type_id": "6a5895b572a064bc2d3ddfc0",
+                        "account_id": 2451002751131,
+                        "name": "Hypothesis",
+                        "color": "#998000",
+                        "position": 2,
+                        "creator_id": 5068740052131,
+                        "updated_by": 3790925372131,
+                        "created_at": 1784190389,
+                        "updated_at": 1785141535
+                      }
+                    ]
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -40950,6 +42242,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -40957,63 +42252,60 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ListIncidentCommentTypesRequest"
+              },
+              "example": {}
+            }
+          }
+        }
+      }
+    },
+    "/incident/comment-type/reorder": {
+      "post": {
+        "operationId": "incidentCommentTypeReorder",
         "summary": "调整评论类型顺序",
+        "description": "传入账户全部评论类型 ID 的期望顺序，设置评论类型的展示顺序。",
         "tags": [
           "On-call/故障管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **评论类型管理**（`on-call`） |\n\n## 使用说明\n\n- 全量排序 —— `comment_type_ids` 必须包含账户的全部评论类型，每个恰好出现一次，按期望顺序排列。\n- 展示位置从 1 开始重新分配：数组中的第一个 ID 即为位置 1。\n- 该权限默认仅管理员拥有，自定义角色需显式授予。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **评论类型管理**（`on-call`） |\n\n## 使用说明\n\n- 全量排序 —— `comment_type_ids` 必须包含账户的全部评论类型，每个恰好出现一次，按期望顺序排列。\n- 位置从 1 开始重新分配：数组中的第一个 ID 位置为 1。\n- 该权限默认仅管理员拥有，自定义角色需显式授予。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/on-call/incidents/incident-comment-type-reorder",
           "metadata": {
             "sidebarTitle": "调整评论类型顺序"
           }
-        }
-      }
-    },
-    "/incident/comment-type/update": {
-      "post": {
-        "description": "更新已有账户评论类型的名称和/或颜色。",
-        "operationId": "incidentCommentTypeUpdate",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "color": "#B7791F",
-                "comment_type_id": "6a5895b572a064bc2d3ddfc0"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/UpdateIncidentCommentTypeRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -41021,6 +42313,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -41028,99 +42323,65 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ReorderIncidentCommentTypesRequest"
+              },
+              "example": {
+                "comment_type_ids": [
+                  "6a5895b572a064bc2d3ddfc0",
+                  "6a5895d672a064bc2d3ddfc2"
+                ]
+              }
+            }
+          }
+        }
+      }
+    },
+    "/incident/comment-type/update": {
+      "post": {
+        "operationId": "incidentCommentTypeUpdate",
         "summary": "更新评论类型",
+        "description": "更新已有账户评论类型的名称和/或颜色。",
         "tags": [
           "On-call/故障管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **评论类型管理**（`on-call`） |\n\n## 使用说明\n\n- 部分更新 —— 仅修改提供的字段，但 `name` 和 `color` 至少提供一个。\n- 名称在账户内必须保持唯一（不区分大小写，忽略首尾空白）。\n- 该权限默认仅管理员拥有，自定义角色需显式授予。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **评论类型管理**（`on-call`） |\n\n## 使用说明\n\n- 部分更新 —— 只修改提供的字段，但 `name` 和 `color` 至少要提供一个。\n- 名称在账户内必须保持唯一（不区分大小写，忽略首尾空白）。\n- 该权限默认仅管理员拥有，自定义角色需显式授予。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/on-call/incidents/incident-comment-type-update",
           "metadata": {
             "sidebarTitle": "更新评论类型"
           }
-        }
-      }
-    },
-    "/incident/create": {
-      "post": {
-        "description": "手动创建一个新故障并分派处理人员。",
-        "operationId": "incidentCreate",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "assigned_to": {
-                  "person_ids": [
-                    2476444212131
-                  ]
-                },
-                "channel_id": 2551105804131,
-                "incident_severity": "Critical",
-                "title": "Database connection timeout on prod-db-01"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/CreateIncidentRequest"
-              }
-            },
-            "multipart/form-data": {
-              "encoding": {
-                "data": {
-                  "contentType": "application/json"
-                }
-              },
-              "schema": {
-                "properties": {
-                  "data": {
-                    "description": "JSON 编码的 CreateIncidentRequest 请求体。",
-                    "type": "string"
-                  },
-                  "images": {
-                    "description": "附加到新故障的图片文件。",
-                    "items": {
-                      "format": "binary",
-                      "type": "string"
-                    },
-                    "type": "array"
-                  }
-                },
-                "required": [
-                  "data"
-                ],
-                "type": "object"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "incident_id": "69db2ef1a0fe7db6448b14f1",
-                    "title": "API test incident for docs"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/CreateIncidentResponse"
+                          "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -41128,6 +42389,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -41135,65 +42399,173 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/UpdateIncidentCommentTypeRequest"
+              },
+              "example": {
+                "comment_type_id": "6a5895b572a064bc2d3ddfc0",
+                "color": "#B7791F"
+              }
+            }
+          }
+        }
+      }
+    },
+    "/incident/create": {
+      "post": {
+        "operationId": "incidentCreate",
         "summary": "创建故障",
+        "description": "手动创建一个新故障并分派处理人员。",
         "tags": [
           "On-call/故障管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障管理**（`on-call`） |\n\n## 使用说明\n\n- 账户的创建表单生效时，必须提供其中可见的自定义字段和必填系统字段。\n- 如需在创建时附加图片，请使用 `multipart/form-data`：在 `data` 中传 JSON 请求体，在 `images` 中传文件；完整请求不得超过 50 MiB。\n- 已审计 —— 变更会记录到审计日志。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **故障管理**（`on-call`）或 **协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 账户未配置创建表单时，只有 `incident_severity` 必填。\n- 账户配置了创建表单时，`title`（非空）、`channel_id` 和 `assigned_to` 变为必填；`fields` 只能包含表单中可见的自定义字段，且表单的必填字段必须填写。\n- 仅当创建表单包含图片上传元素时才能附加图片（最多 10 张）：使用 `multipart/form-data`，在 `data` 中传 JSON 请求体，在 `images` 中传文件；整个请求不得超过 50 MiB。\n- 分派在故障创建之后执行。未传 `assigned_to` 时由协作空间的分派策略决定；未传 `assigned_to` 的独立故障不会有处理人员。分派失败（例如 `layer_idx` 越界）时故障仍会创建，只是没有处理人员。",
           "href": "/zh/api-reference/on-call/incidents/incident-create",
           "metadata": {
             "sidebarTitle": "创建故障"
           }
-        }
-      }
-    },
-    "/incident/custom-action/do": {
-      "post": {
-        "description": "执行为故障配置的自定义操作。",
-        "operationId": "incidentCustomActionDo",
+        },
+        "responses": {
+          "200": {
+            "description": "成功",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/CreateIncidentResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "incident_id": "69db2ef1a0fe7db6448b14f1",
+                    "title": "API test incident for docs"
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "429": {
+            "$ref": "#/components/responses/TooManyRequests"
+          },
+          "500": {
+            "$ref": "#/components/responses/ServerError"
+          }
+        },
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {
-                "incident_id": "69da451ef77b1b51f40e83ee",
-                "integration_id": 2490562293131
+              "schema": {
+                "$ref": "#/components/schemas/CreateIncidentRequest"
               },
+              "example": {
+                "incident_severity": "Critical",
+                "title": "Database connection timeout on prod-db-01",
+                "channel_id": 2551105804131,
+                "assigned_to": {
+                  "person_ids": [
+                    2476444212131
+                  ]
+                }
+              }
+            },
+            "multipart/form-data": {
               "schema": {
-                "$ref": "#/components/schemas/DoIncidentCustomActionRequest"
+                "type": "object",
+                "required": [
+                  "data"
+                ],
+                "properties": {
+                  "data": {
+                    "type": "string",
+                    "description": "JSON 编码的 CreateIncidentRequest 请求体。"
+                  },
+                  "images": {
+                    "type": "array",
+                    "items": {
+                      "type": "string",
+                      "format": "binary"
+                    },
+                    "description": "附加到新故障的图片文件。"
+                  }
+                }
+              },
+              "encoding": {
+                "data": {
+                  "contentType": "application/json"
+                }
               }
-            }
-          },
-          "required": true
+            }
+          }
+        }
+      }
+    },
+    "/incident/custom-action/do": {
+      "post": {
+        "operationId": "incidentCustomActionDo",
+        "summary": "执行自定义操作",
+        "description": "执行为故障配置的自定义操作。",
+        "tags": [
+          "On-call/故障管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **故障管理**或**协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 集成必须是已启用的自定义操作集成，且其关联的协作空间包含该故障所在的协作空间，否则返回 `InvalidParameter`。\n- 服务端会以 2 秒超时把故障数据 POST 到该操作配置的地址。该请求失败时接口仍返回 HTTP 200，错误信息放在 `data.message` 中；成功时 `data` 为 `null`。\n- 执行成功后会写入一条 `i_custom` 时间线记录。",
+          "href": "/zh/api-reference/on-call/incidents/incident-custom-action-do",
+          "metadata": {
+            "sidebarTitle": "执行自定义操作"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "message": ""
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/DoIncidentCustomActionResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": null
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -41201,6 +42573,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -41208,64 +42583,63 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "执行自定义操作",
-        "tags": [
-          "On-call/故障管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障管理**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/incidents/incident-custom-action-do",
-          "metadata": {
-            "sidebarTitle": "执行自定义操作"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/DoIncidentCustomActionRequest"
+              },
+              "example": {
+                "incident_id": "69da451ef77b1b51f40e83ee",
+                "integration_id": 2490562293131
+              }
+            }
           }
         }
       }
     },
     "/incident/disable-merge": {
       "post": {
-        "description": "禁用指定故障的自动合并功能。",
         "operationId": "incidentDisableMerge",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "incident_ids": [
-                  "69da451ef77b1b51f40e83ee"
-                ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/DisableIncidentMergeRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "禁止故障合并",
+        "description": "停止将新的告警和事件合并进指定故障。",
+        "tags": [
+          "On-call/故障管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 任意有效 `app_key` 均可调用 |\n\n## 使用说明\n\n- 之后到达的事件不再合并进这些故障已有的告警，告警聚合也不再把新告警加入这些故障。\n- 不存在的故障 ID 会被忽略。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "href": "/zh/api-reference/on-call/incidents/incident-disable-merge",
+          "metadata": {
+            "sidebarTitle": "禁止故障合并"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -41273,6 +42647,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -41280,120 +42657,120 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "禁止故障合并",
-        "tags": [
-          "On-call/故障管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障管理**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/incidents/incident-disable-merge",
-          "metadata": {
-            "sidebarTitle": "禁止故障合并"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/DisableIncidentMergeRequest"
+              },
+              "example": {
+                "incident_ids": [
+                  "69da451ef77b1b51f40e83ee"
+                ]
+              }
+            }
           }
         }
       }
     },
     "/incident/feed": {
       "post": {
-        "description": "获取指定故障的时间线动态，包括状态变更、评论和系统事件。",
         "operationId": "incidentFeed",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "incident_id": "69da451ef77b1b51f40e83ee",
-                "limit": 20,
-                "p": 1
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ListIncidentFeedRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "获取故障时间线",
+        "description": "查询故障的时间线条目，包括状态变化、分派、通知、评论和工作项事件等。",
+        "tags": [
+          "On-call/故障管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障查看**或**故障管理**或**协作空间查看**或**协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 对于 `i_comm` 条目，`detail.comment_type` 在读取时根据当前账户级评论类型定义解析，因此始终反映类型的最新名称和颜色。\n- 只返回记录在故障本身上的条目；告警级别的条目请通过告警相关接口查询。\n- 条目按创建时间排序，默认最新在前，`asc` 为 `true` 时最早在前。通过 `p` 和 `limit` 分页；`has_next_page` 表示是否还有下一页，不返回总数。\n- 对于 `i_notify` 条目，`failed_reason` 是读取时填充的本地化投递失败原因。",
+          "href": "/zh/api-reference/on-call/incidents/incident-feed",
+          "metadata": {
+            "sidebarTitle": "获取故障时间线"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/ListIncidentFeedResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "has_next_page": true,
                     "items": [
                       {
-                        "account_id": 2451002751131,
-                        "created_at": 1785495329402,
-                        "creator_id": 5329873302131,
+                        "ref_id": "6a5f1e28807515413b384bce",
+                        "type": "i_wi_created",
                         "detail": {
+                          "work_item_id": "wi_68MHnkWBiyjrh6uhkxUyiZ",
+                          "item_type": "follow_up",
+                          "title": "Follow-up: schedule database failover drill",
+                          "status": "open",
                           "assignee_ids": [
                             3790925372131,
                             4756301322131
                           ],
-                          "item_type": "follow_up",
-                          "post_mortem_id": "51d65cd9525c369379ba471b5512df63",
-                          "status": "open",
-                          "title": "Follow-up: schedule database failover drill",
-                          "work_item_id": "wi_68MHnkWBiyjrh6uhkxUyiZ"
+                          "post_mortem_id": "51d65cd9525c369379ba471b5512df63"
                         },
-                        "ref_id": "6a5f1e28807515413b384bce",
-                        "type": "i_wi_created",
+                        "account_id": 2451002751131,
+                        "creator_id": 5329873302131,
+                        "created_at": 1785495329402,
                         "updated_at": 1785495329402
                       },
                       {
-                        "account_id": 2451002751131,
-                        "created_at": 1785496333926,
-                        "creator_id": 3790925372131,
+                        "ref_id": "6a5f1e28807515413b384bce",
+                        "type": "i_comm",
                         "detail": {
                           "comment": "Root cause identified: connection pool exhaustion on the primary database.",
+                          "comment_type_id": "6a5895d672a064bc2d3ddfc2",
                           "comment_type": {
-                            "color": "#30A46C",
                             "id": "6a5895d672a064bc2d3ddfc2",
-                            "name": "Key finding"
-                          },
-                          "comment_type_id": "6a5895d672a064bc2d3ddfc2"
+                            "name": "Key finding",
+                            "color": "#30A46C"
+                          }
                         },
-                        "ref_id": "6a5f1e28807515413b384bce",
-                        "type": "i_comm",
+                        "account_id": 2451002751131,
+                        "creator_id": 3790925372131,
+                        "created_at": 1785496333926,
                         "updated_at": 1785496333926
                       },
                       {
-                        "account_id": 2451002751131,
-                        "created_at": 1785496384806,
-                        "creator_id": 3790925372131,
+                        "ref_id": "6a5f1e28807515413b384bce",
+                        "type": "i_wi_completed",
                         "detail": {
-                          "from_status": "open",
+                          "work_item_id": "wi_68MHnkWBiyjrh6uhkxUyiZ",
                           "item_type": "follow_up",
-                          "post_mortem_id": "51d65cd9525c369379ba471b5512df63",
                           "title": "Follow-up: schedule database failover drill",
+                          "from_status": "open",
                           "to_status": "done",
-                          "work_item_id": "wi_68MHnkWBiyjrh6uhkxUyiZ"
+                          "post_mortem_id": "51d65cd9525c369379ba471b5512df63"
                         },
-                        "ref_id": "6a5f1e28807515413b384bce",
-                        "type": "i_wi_completed",
+                        "account_id": 2451002751131,
+                        "creator_id": 3790925372131,
+                        "created_at": 1785496384806,
                         "updated_at": 1785496384806
                       }
                     ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/ListIncidentFeedResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -41401,6 +42778,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -41408,64 +42788,64 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "获取故障时间线",
-        "tags": [
-          "On-call/故障管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障查看**（`on-call`） |\n\n## 使用说明\n\n- 对于 `i_comm` 条目，`detail.comment_type` 在读取时根据当前账户级评论类型定义解析，因此始终反映类型的最新名称和颜色。",
-          "href": "/zh/api-reference/on-call/incidents/incident-feed",
-          "metadata": {
-            "sidebarTitle": "获取故障时间线"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ListIncidentFeedRequest"
+              },
+              "example": {
+                "incident_id": "69da451ef77b1b51f40e83ee",
+                "p": 1,
+                "limit": 20
+              }
+            }
           }
         }
       }
     },
     "/incident/field/reset": {
       "post": {
-        "description": "更新故障的自定义字段值。",
         "operationId": "incidentFieldReset",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "field_name": "affected_service",
-                "field_value": "payment-service",
-                "incident_id": "69da451ef77b1b51f40e83ee"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ResetIncidentFieldRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "更新故障自定义字段",
+        "description": "更新故障的自定义字段值。",
+        "tags": [
+          "On-call/故障管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **故障管理**（`on-call`）或 **协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 字段必须在账户中存在且处于启用状态；`field_value` 必须符合字段类型和选项。\n- 省略 `field_value` 或传 `null` 会清空该故障上的这个字段。\n- 若新值与当前值相同，则不做任何修改。\n- 修改会在故障时间线上新增一条字段变更记录，并像控制台修改一样触发通知和 Webhook。",
+          "href": "/zh/api-reference/on-call/incidents/incident-field-reset",
+          "metadata": {
+            "sidebarTitle": "更新故障自定义字段"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -41473,6 +42853,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -41480,140 +42863,143 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "更新故障自定义字段",
-        "tags": [
-          "On-call/故障管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障管理**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/incidents/incident-field-reset",
-          "metadata": {
-            "sidebarTitle": "更新故障自定义字段"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ResetIncidentFieldRequest"
+              },
+              "example": {
+                "incident_id": "69da451ef77b1b51f40e83ee",
+                "field_name": "affected_service",
+                "field_value": "payment-service"
+              }
+            }
           }
         }
       }
     },
     "/incident/info": {
       "post": {
-        "description": "获取单个故障的详细信息，包括时间线、关联告警、处理人员和自定义字段。",
         "operationId": "incidentInfo",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "incident_id": "69da451ef77b1b51f40e83ee"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/IncidentInfoRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "获取故障详情",
+        "description": "按 ID 或短编号查询单个故障，包含处理人、分派、自定义字段和告警数量。",
+        "tags": [
+          "On-call/故障管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障查看**或**故障管理**或**协作空间查看**或**协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- `num` 不唯一，多个故障共用同一编号时返回最新的那个。建议优先使用 `incident_id`。\n- 本接口不填充 `alerts` 和 `account_*` 字段。告警请使用 `POST /incident/alert/list`，时间线请使用 `POST /incident/feed`。\n- `images` 中以 `img_` 开头的图片令牌会被替换为下载地址。\n- 故障不存在时返回 `InvalidParameter`。",
+          "href": "/zh/api-reference/on-call/incidents/incident-info",
+          "metadata": {
+            "sidebarTitle": "获取故障详情"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/IncidentInfo"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
+                    "incident_id": "69da451ef77b1b51f40e83ee",
                     "account_id": 2451002751131,
-                    "account_locale": "",
-                    "account_name": "",
-                    "account_time_zone": "",
-                    "ack_time": 0,
-                    "active_alert_cnt": 1,
-                    "ai_summary": "",
-                    "alert_cnt": 1,
-                    "alert_event_cnt": 17,
-                    "assigned_to": {
-                      "assigned_at": 1775972128,
-                      "escalate_rule_id": "000000000000000000000000",
-                      "escalate_rule_name": "",
-                      "id": "MvQfH9Dc8eNS8k79jmrWn6",
-                      "layer_idx": 0,
-                      "person_ids": [
-                        2476444212131
-                      ],
-                      "type": "assign"
-                    },
                     "channel_id": 2551105804131,
-                    "channel_name": "Ops Channel",
-                    "channel_status": "enabled",
-                    "close_time": 0,
-                    "closer_id": 0,
-                    "created_at": 1775912222,
-                    "creator_id": 0,
-                    "dedup_key": "100128:prom-203.0.113.107:A:1579244238440766834:anydata",
-                    "description": "",
-                    "detail_url": "https://app.flashcat.cloud/incident/detail/69da451ef77b1b51f40e83ee",
-                    "end_time": 0,
-                    "equals_md5": "",
-                    "ever_muted": false,
-                    "fields": {},
-                    "frequency": "frequent",
-                    "group_method": "n",
-                    "images": null,
-                    "impact": "",
-                    "incident_id": "69da451ef77b1b51f40e83ee",
-                    "incident_severity": "Critical",
-                    "incident_status": "Critical",
+                    "team_id": 2477033058131,
                     "integration_id": 2490562293131,
                     "integration_ids": [
                       2490562293131
                     ],
-                    "integration_type": "monit.alert",
                     "integration_types": [
                       "monit.alert"
                     ],
-                    "labels": {
-                      "check": "cpu_usage_high",
-                      "env": "production",
-                      "resource": "web-server-01"
-                    },
+                    "dedup_key": "100128:prom-203.0.113.107:A:1579244238440766834:anydata",
+                    "equals_md5": "",
+                    "start_time": 1775912219,
+                    "end_time": 0,
                     "last_time": 1775969819,
-                    "manual_overrides": [
-                      "title"
-                    ],
-                    "num": "0E83EE",
+                    "ack_time": 0,
+                    "close_time": 0,
+                    "creator_id": 0,
+                    "closer_id": 0,
                     "owner_id": 0,
-                    "post_mortem_id": "",
+                    "incident_status": "Critical",
+                    "incident_severity": "Critical",
                     "progress": "Triggered",
+                    "title": "CPU usage high - web-server-01",
+                    "description": "",
+                    "ai_summary": "",
+                    "impact": "",
+                    "root_cause": "",
                     "resolution": "",
+                    "num": "0E83EE",
+                    "frequency": "frequent",
+                    "created_at": 1775912222,
+                    "updated_at": 1775972145,
+                    "snoozed_before": 0,
+                    "group_method": "n",
+                    "ever_muted": false,
+                    "has_unfinished_work_item": false,
+                    "labels": {
+                      "check": "cpu_usage_high",
+                      "resource": "web-server-01",
+                      "env": "production"
+                    },
+                    "fields": {},
+                    "assigned_to": {
+                      "person_ids": [
+                        2476444212131
+                      ],
+                      "escalate_rule_id": "000000000000000000000000",
+                      "layer_idx": 0,
+                      "type": "assign",
+                      "assigned_at": 1775972128,
+                      "id": "MvQfH9Dc8eNS8k79jmrWn6",
+                      "escalate_rule_name": ""
+                    },
+                    "alert_cnt": 1,
+                    "active_alert_cnt": 1,
+                    "alert_event_cnt": 17,
                     "responders": [
                       {
-                        "acknowledged_at": 0,
+                        "person_id": 2476444212131,
                         "assigned_at": 1775972128,
-                        "person_id": 2476444212131
+                        "acknowledged_at": 0
                       }
                     ],
-                    "root_cause": "",
+                    "account_name": "",
+                    "account_locale": "",
+                    "account_time_zone": "",
+                    "channel_name": "Ops Channel",
+                    "channel_status": "enabled",
+                    "detail_url": "https://app.flashcat.cloud/incident/detail/69da451ef77b1b51f40e83ee",
                     "silence_url": "https://app.flashcat.cloud/channel/detail/2551105804131?tab=alertSuppression&fromIncidentId=69da451ef77b1b51f40e83ee",
-                    "snoozed_before": 0,
-                    "start_time": 1775912219,
-                    "team_id": 2477033058131,
-                    "title": "CPU usage high - web-server-01",
-                    "updated_at": 1775972145
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/IncidentInfo"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                    "integration_type": "monit.alert",
+                    "post_mortem_id": "",
+                    "images": null,
+                    "manual_overrides": [
+                      "title"
+                    ]
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -41621,6 +43007,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -41628,155 +43017,148 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "获取故障详情",
-        "tags": [
-          "On-call/故障管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障查看**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/incidents/incident-info",
-          "metadata": {
-            "sidebarTitle": "获取故障详情"
-          }
-        }
-      }
-    },
-    "/incident/list": {
-      "post": {
-        "description": "分页查询故障列表，支持按协作空间、严重程度、状态、处理人员和时间范围过滤。",
-        "operationId": "incidentList",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {
-                "channel_ids": [
-                  2551105804131
-                ],
-                "end_time": 1712000000,
-                "incident_severity": "Critical,Warning",
-                "limit": 20,
-                "p": 1,
-                "progress": "Triggered,Processing",
-                "start_time": 1711900800
-              },
               "schema": {
-                "$ref": "#/components/schemas/ListIncidentsRequest"
+                "$ref": "#/components/schemas/IncidentInfoRequest"
+              },
+              "example": {
+                "incident_id": "69da451ef77b1b51f40e83ee"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/incident/list": {
+      "post": {
+        "operationId": "incidentList",
+        "summary": "查询故障列表",
+        "description": "分页查询故障列表，支持按协作空间、严重程度、状态、处理人员和时间范围过滤。",
+        "tags": [
+          "On-call/故障管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障查看**或**故障管理**或**协作空间查看**或**协作空间管理**或**模板查看**或**模板管理**（`on-call`） |\n\n## 使用说明\n\n- 只返回调用者有权访问的协作空间中的故障。\n- `start_time` 和 `end_time` 按故障开始时间过滤，跨度最多 31 天。`start_time` 早于账户数据保留期时会被调整到保留期起点；`end_time` 早于该起点时返回 `InvalidParameter`。\n- 结果按 `start_time` 排序，默认最新在前，`asc` 为 `true` 时最早在前。\n- 可用 `p` 和 `limit` 分页，也可传入上次响应的 `search_after_ctx`，此时忽略 `p`。\n- `total` 最多为 1,000。按 `p`/`limit` 分页时，一旦 `p` × `limit` 达到 1,000，即使还有更多匹配故障 `has_next_page` 也会变为 `false`。如需继续读取，请传入每个非空页都会返回的 `search_after_ctx`；游标模式下 `has_next_page` 如实反映是否还有更多数据。\n- 不传 `progress` 时返回所有处理进度的故障。",
+          "href": "/zh/api-reference/on-call/incidents/incident-list",
+          "metadata": {
+            "sidebarTitle": "查询故障列表"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/IncidentListResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
+                    "total": 88,
                     "has_next_page": true,
+                    "search_after_ctx": "69da451ef77b1b51f40e83eb",
                     "items": [
                       {
+                        "incident_id": "69da451ef77b1b51f40e83ee",
                         "account_id": 2451002751131,
-                        "account_locale": "",
-                        "account_name": "",
-                        "account_time_zone": "",
-                        "ack_time": 0,
-                        "active_alert_cnt": 1,
-                        "ai_summary": "",
-                        "alert_cnt": 1,
-                        "alert_event_cnt": 17,
-                        "assigned_to": {
-                          "assigned_at": 1775972128,
-                          "escalate_rule_id": "000000000000000000000000",
-                          "escalate_rule_name": "",
-                          "id": "MvQfH9Dc8eNS8k79jmrWn6",
-                          "layer_idx": 0,
-                          "person_ids": [
-                            2476444212131
-                          ],
-                          "type": "assign"
-                        },
                         "channel_id": 2551105804131,
-                        "channel_name": "Ops Channel",
-                        "channel_status": "enabled",
-                        "close_time": 0,
-                        "closer_id": 0,
-                        "created_at": 1775912222,
-                        "creator_id": 0,
-                        "dedup_key": "100128:prom-203.0.113.107:A:1579244238440766834:anydata",
-                        "description": "",
-                        "detail_url": "https://app.flashcat.cloud/incident/detail/69da451ef77b1b51f40e83ee",
-                        "end_time": 0,
-                        "equals_md5": "",
-                        "ever_muted": false,
-                        "fields": {},
-                        "frequency": "frequent",
-                        "group_method": "n",
-                        "images": null,
-                        "impact": "",
-                        "incident_id": "69da451ef77b1b51f40e83ee",
-                        "incident_severity": "Critical",
-                        "incident_status": "Critical",
+                        "team_id": 2477033058131,
                         "integration_id": 2490562293131,
                         "integration_ids": [
                           2490562293131
                         ],
-                        "integration_type": "monit.alert",
                         "integration_types": [
                           "monit.alert"
                         ],
-                        "labels": {
-                          "check": "cpu_usage_high",
-                          "env": "production",
-                          "resource": "web-server-01"
-                        },
+                        "dedup_key": "100128:prom-203.0.113.107:A:1579244238440766834:anydata",
+                        "equals_md5": "",
+                        "start_time": 1775912219,
+                        "end_time": 0,
                         "last_time": 1775969819,
-                        "manual_overrides": [
-                          "title"
-                        ],
-                        "num": "0E83EE",
+                        "ack_time": 0,
+                        "close_time": 0,
+                        "creator_id": 0,
+                        "closer_id": 0,
                         "owner_id": 0,
-                        "post_mortem_id": "",
+                        "incident_status": "Critical",
+                        "incident_severity": "Critical",
                         "progress": "Triggered",
+                        "title": "CPU usage high - web-server-01",
+                        "description": "",
+                        "ai_summary": "",
+                        "impact": "",
+                        "root_cause": "",
                         "resolution": "",
+                        "num": "0E83EE",
+                        "frequency": "frequent",
+                        "created_at": 1775912222,
+                        "updated_at": 1775972145,
+                        "snoozed_before": 0,
+                        "group_method": "n",
+                        "ever_muted": false,
+                        "has_unfinished_work_item": false,
+                        "labels": {
+                          "check": "cpu_usage_high",
+                          "resource": "web-server-01",
+                          "env": "production"
+                        },
+                        "fields": {},
+                        "assigned_to": {
+                          "person_ids": [
+                            2476444212131
+                          ],
+                          "escalate_rule_id": "000000000000000000000000",
+                          "layer_idx": 0,
+                          "type": "assign",
+                          "assigned_at": 1775972128,
+                          "id": "MvQfH9Dc8eNS8k79jmrWn6",
+                          "escalate_rule_name": ""
+                        },
+                        "alert_cnt": 1,
+                        "active_alert_cnt": 1,
+                        "alert_event_cnt": 17,
                         "responders": [
                           {
-                            "acknowledged_at": 0,
+                            "person_id": 2476444212131,
                             "assigned_at": 1775972128,
-                            "person_id": 2476444212131
+                            "acknowledged_at": 0
                           }
                         ],
-                        "root_cause": "",
+                        "account_name": "",
+                        "account_locale": "",
+                        "account_time_zone": "",
+                        "channel_name": "Ops Channel",
+                        "channel_status": "enabled",
+                        "detail_url": "https://app.flashcat.cloud/incident/detail/69da451ef77b1b51f40e83ee",
                         "silence_url": "https://app.flashcat.cloud/channel/detail/2551105804131?tab=alertSuppression&fromIncidentId=69da451ef77b1b51f40e83ee",
-                        "snoozed_before": 0,
-                        "start_time": 1775912219,
-                        "team_id": 2477033058131,
-                        "title": "CPU usage high - web-server-01",
-                        "updated_at": 1775972145
+                        "integration_type": "monit.alert",
+                        "post_mortem_id": "",
+                        "images": null,
+                        "manual_overrides": [
+                          "title"
+                        ]
                       }
-                    ],
-                    "search_after_ctx": "69da451ef77b1b51f40e83eb",
-                    "total": 88
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/IncidentListResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                    ]
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -41784,6 +43166,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -41791,134 +43176,140 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "查询故障列表",
-        "tags": [
-          "On-call/故障管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障查看**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/incidents/incident-list",
-          "metadata": {
-            "sidebarTitle": "查询故障列表"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ListIncidentsRequest"
+              },
+              "example": {
+                "start_time": 1711900800,
+                "end_time": 1712000000,
+                "progress": "Triggered,Processing",
+                "incident_severity": "Critical,Warning",
+                "channel_ids": [
+                  2551105804131
+                ],
+                "limit": 20,
+                "p": 1
+              }
+            }
           }
         }
       }
     },
     "/incident/list-by-ids": {
       "post": {
-        "description": "通过故障 ID 列表批量获取故障信息。",
         "operationId": "incidentListByIds",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "incident_ids": [
-                  "69da451ef77b1b51f40e83ee",
-                  "69da451ef77b1b51f40e83ef"
-                ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ListIncidentsByIdsRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "批量查询故障",
+        "description": "通过故障 ID 列表批量获取故障信息。",
+        "tags": [
+          "On-call/故障管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障查看**或**故障管理**或**协作空间查看**（`on-call`） |\n\n## 使用说明\n\n- 不存在的 ID 会被忽略；`total` 为实际找到的故障数，`has_next_page` 恒为 `false`。\n- 结果按 `start_time` 排序，最新在前。\n- 本接口不填充 `integration_type` 和 `assigned_to.escalate_rule_name`。",
+          "href": "/zh/api-reference/on-call/incidents/incident-list-by-ids",
+          "metadata": {
+            "sidebarTitle": "批量查询故障"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/IncidentListResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
+                    "total": 1,
                     "has_next_page": false,
                     "items": [
                       {
+                        "incident_id": "69da451ef77b1b51f40e83ee",
                         "account_id": 2451002751131,
-                        "account_locale": "",
-                        "account_name": "",
-                        "account_time_zone": "",
-                        "ack_time": 0,
-                        "active_alert_cnt": 1,
-                        "ai_summary": "",
-                        "alert_cnt": 1,
-                        "alert_event_cnt": 17,
-                        "assigned_to": {
-                          "assigned_at": 0,
-                          "escalate_rule_id": "000000000000000000000000",
-                          "escalate_rule_name": "",
-                          "id": "",
-                          "layer_idx": 0,
-                          "type": ""
-                        },
                         "channel_id": 2551105804131,
-                        "channel_name": "Ops Channel",
-                        "channel_status": "enabled",
-                        "close_time": 0,
-                        "closer_id": 0,
-                        "created_at": 1775912222,
-                        "creator_id": 0,
-                        "dedup_key": "100128:prom-203.0.113.107:A:1579244238440766834:anydata",
-                        "description": "",
-                        "detail_url": "https://app.flashcat.cloud/incident/detail/69da451ef77b1b51f40e83ee",
-                        "end_time": 0,
-                        "equals_md5": "",
-                        "ever_muted": false,
-                        "fields": {},
-                        "frequency": "frequent",
-                        "group_method": "n",
-                        "images": null,
-                        "impact": "",
-                        "incident_id": "69da451ef77b1b51f40e83ee",
-                        "incident_severity": "Critical",
-                        "incident_status": "Critical",
+                        "team_id": 2477033058131,
                         "integration_id": 2490562293131,
                         "integration_ids": [
                           2490562293131
                         ],
-                        "integration_type": "monit.alert",
                         "integration_types": [
                           "monit.alert"
                         ],
-                        "labels": {},
+                        "dedup_key": "100128:prom-203.0.113.107:A:1579244238440766834:anydata",
+                        "equals_md5": "",
+                        "start_time": 1775912219,
+                        "end_time": 0,
                         "last_time": 1775969819,
-                        "manual_overrides": null,
-                        "num": "0E83EE",
+                        "ack_time": 0,
+                        "close_time": 0,
+                        "creator_id": 0,
+                        "closer_id": 0,
                         "owner_id": 0,
-                        "post_mortem_id": "",
+                        "incident_status": "Critical",
+                        "incident_severity": "Critical",
                         "progress": "Triggered",
+                        "title": "CPU usage high - web-server-01",
+                        "description": "",
+                        "ai_summary": "",
+                        "impact": "",
+                        "root_cause": "",
                         "resolution": "",
+                        "num": "0E83EE",
+                        "frequency": "frequent",
+                        "created_at": 1775912222,
+                        "updated_at": 1775972145,
+                        "snoozed_before": 0,
+                        "group_method": "n",
+                        "ever_muted": false,
+                        "has_unfinished_work_item": false,
+                        "labels": {},
+                        "fields": {},
+                        "assigned_to": {
+                          "escalate_rule_id": "000000000000000000000000",
+                          "layer_idx": 0,
+                          "type": "",
+                          "assigned_at": 0,
+                          "id": "",
+                          "escalate_rule_name": ""
+                        },
+                        "alert_cnt": 1,
+                        "active_alert_cnt": 1,
+                        "alert_event_cnt": 17,
                         "responders": [],
-                        "root_cause": "",
+                        "account_name": "",
+                        "account_locale": "",
+                        "account_time_zone": "",
+                        "channel_name": "Ops Channel",
+                        "channel_status": "enabled",
+                        "detail_url": "https://app.flashcat.cloud/incident/detail/69da451ef77b1b51f40e83ee",
                         "silence_url": "https://app.flashcat.cloud/channel/detail/2551105804131?tab=alertSuppression&fromIncidentId=69da451ef77b1b51f40e83ee",
-                        "snoozed_before": 0,
-                        "start_time": 1775912219,
-                        "team_id": 2477033058131,
-                        "title": "CPU usage high - web-server-01",
-                        "updated_at": 1775972145
+                        "integration_type": "monit.alert",
+                        "post_mortem_id": "",
+                        "images": null,
+                        "manual_overrides": null
                       }
-                    ],
-                    "total": 2
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/IncidentListResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                    ]
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -41926,6 +43317,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -41933,67 +43327,65 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "批量查询故障",
-        "tags": [
-          "On-call/故障管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障查看**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/incidents/incident-list-by-ids",
-          "metadata": {
-            "sidebarTitle": "批量查询故障"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ListIncidentsByIdsRequest"
+              },
+              "example": {
+                "incident_ids": [
+                  "69da451ef77b1b51f40e83ee",
+                  "69da451ef77b1b51f40e83ef"
+                ]
+              }
+            }
           }
         }
       }
     },
     "/incident/merge": {
       "post": {
-        "description": "将一个或多个故障合并到目标故障中。",
         "operationId": "incidentMerge",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "comment": "Merging related database connectivity incidents into one.",
-                "source_incident_ids": [
-                  "69da451ef77b1b51f40e83ef",
-                  "69da451ef77b1b51f40e83f0"
-                ],
-                "target_incident_id": "69da451ef77b1b51f40e83ee"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/MergeIncidentsRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "合并故障",
+        "description": "将一个或多个故障合并到目标故障中。",
+        "tags": [
+          "On-call/故障管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **故障管理**或**协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 源故障的全部告警会移动到目标故障，目标故障同时继承源故障的集成。\n- 仍未关闭的源故障会被关闭。`remove_source_incidents` 为 `true` 时随后永久删除源故障；否则源故障保持关闭，并在时间线写入一条指向目标故障的 `i_merge` 记录。\n- 目标故障的处理进度、处理人和分派不变；传入 `title` 时会替换目标故障标题。\n- 同一账户内有其他关闭、重开、合并、评论或删除操作正在执行时返回 `RequestTooFrequently`，稍后重试即可。",
+          "href": "/zh/api-reference/on-call/incidents/incident-merge",
+          "metadata": {
+            "sidebarTitle": "合并故障"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -42001,6 +43393,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -42008,65 +43403,69 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "合并故障",
-        "tags": [
-          "On-call/故障管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障管理**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/incidents/incident-merge",
-          "metadata": {
-            "sidebarTitle": "合并故障"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/MergeIncidentsRequest"
+              },
+              "example": {
+                "source_incident_ids": [
+                  "69da451ef77b1b51f40e83ef",
+                  "69da451ef77b1b51f40e83f0"
+                ],
+                "target_incident_id": "69da451ef77b1b51f40e83ee",
+                "comment": "Merging related database connectivity incidents into one."
+              }
+            }
           }
         }
       }
     },
     "/incident/past/list": {
       "post": {
-        "description": "查询与当前故障相关的历史故障列表，用于参考排查。",
         "operationId": "incidentPastList",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "incident_id": "69da451ef77b1b51f40e83ee",
-                "limit": 5
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ListPastIncidentsRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "查询历史相似故障",
+        "description": "查询与指定故障相似、同一协作空间内已关闭的历史故障，便于复用过往的根因和解决方案。",
+        "tags": [
+          "On-call/故障管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **100 次/分钟**；**5 次/秒** |\n| 权限要求 | **故障查看**或**故障管理**或**协作空间查看**或**协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 需要专业版及以上版本，否则返回 `NoLicense`。\n- 候选范围：同一协作空间内、开始时间在参考故障开始前 30 天内、语义相似度超过该协作空间相似度阈值的已关闭故障。\n- 排序规则：`root_cause` 与 `resolution` 文本越长越靠前；相同时 `score` 越高越靠前；再相同时 `start_time` 越新越靠前。\n- `limit` 不传或为 `0` 时默认返回 5 条。\n- `items` 为空数组表示没有找到相似故障，或参考故障尚未建立相似度索引。\n- 参考故障必须属于某个协作空间，否则返回 `InvalidParameter`。",
+          "href": "/zh/api-reference/on-call/incidents/incident-past-list",
+          "metadata": {
+            "sidebarTitle": "查询历史相似故障"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "items": []
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/ListPastIncidentsResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "items": []
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -42074,6 +43473,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -42081,69 +43483,62 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "查询历史相似故障",
-        "tags": [
-          "On-call/故障管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **100 次/分钟**；**20 次/秒** |\n| 权限要求 | **故障查看**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/incidents/incident-past-list",
-          "metadata": {
-            "sidebarTitle": "查询历史相似故障"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ListPastIncidentsRequest"
+              },
+              "example": {
+                "incident_id": "69da451ef77b1b51f40e83ee",
+                "limit": 5
+              }
+            }
           }
         }
       }
     },
     "/incident/post-mortem/basics/reset": {
       "post": {
-        "description": "替换复盘报告中记录的故障基础信息。",
         "operationId": "postmortem-write-reset-basics",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "incidents_earliest_start_seconds": 1761133512,
-                "incidents_highest_severity": "Warning",
-                "incidents_latest_close_seconds": 1761133632,
-                "incidents_total_duration_seconds": 120,
-                "post_mortem_id": "8104935102bf89dc01ac638a5261fe7e",
-                "responder_ids": [
-                  3790925372131
-                ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ResetPostMortemBasicsRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "更新故障复盘基础信息",
+        "description": "覆盖复盘报告中保存的故障基本信息（严重程度、时间、处理人员）。",
+        "tags": [
+          "On-call/故障管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 需要 On-call Pro 许可。\n- 调用方须为账户所有者或管理员，或是该报告所属团队的成员，否则返回 `AccessDenied`。\n- 整体覆盖：省略 `incidents_latest_close_seconds` 和 `incidents_total_duration_seconds` 时写为 0，省略 `responder_ids` 时清空处理人员。\n- `responder_ids` 中无法解析为人员的 ID 会被丢弃；保存的每个处理人员 `assigned_at` 为当前时间，`acknowledged_at` 为 0。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "href": "/zh/api-reference/on-call/incidents/postmortem-write-reset-basics",
+          "metadata": {
+            "sidebarTitle": "更新故障复盘基础信息"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -42151,6 +43546,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -42158,73 +43556,77 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "更新故障复盘基础信息",
-        "tags": [
-          "On-call/故障管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障管理**（`on-call`） |\n\n## 使用说明\n\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
-          "href": "/zh/api-reference/on-call/incidents/postmortem-write-reset-basics",
-          "metadata": {
-            "sidebarTitle": "更新故障复盘基础信息"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ResetPostMortemBasicsRequest"
+              },
+              "example": {
+                "post_mortem_id": "d3c9a7f2e5b14c8a9f0e6b2d4a1c7e35",
+                "incidents_highest_severity": "Critical",
+                "incidents_earliest_start_seconds": 1773890000,
+                "incidents_latest_close_seconds": 1773897200,
+                "incidents_total_duration_seconds": 7200,
+                "responder_ids": [
+                  3790925372131
+                ]
+              }
+            }
           }
         }
       }
     },
     "/incident/post-mortem/content/reset": {
       "post": {
-        "description": "用 Markdown 完整替换草稿状态故障复盘的正文。",
         "operationId": "incident-post-mortem-write-reset-content",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "expected_revision": 11,
-                "idempotency_key": "postmortem-reset-8104935102-11",
-                "markdown": "# Database saturation incident\n\nThe database pool was exhausted; added saturation alert.",
-                "post_mortem_id": "8104935102bf89dc01ac638a5261fe7e"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ResetPostMortemContentRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "重置故障复盘正文",
+        "description": "用 Markdown 完整替换草稿状态故障复盘的正文。",
+        "tags": [
+          "On-call/故障管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 需要 On-call Pro 许可。\n- 调用方须为账户所有者或管理员，或是该报告所属团队的成员，否则返回 `AccessDenied`。\n- 仅草稿状态的报告可重置，且当前修订版本必须等于 `expected_revision`；否则返回 `409 Conflict`。\n- 同一 `idempotency_key` 只能重试相同的复盘、修订版本和 Markdown 正文；复用到不同请求会返回 `409 Conflict`。\n- 同一报告的另一次重置仍在进行时返回 `RequestTooFrequently`，请稍后重试。\n- 重置成功后旧的协作（Yjs）房间会被断开，客户端需切换到新 generation 的房间 `post-mortem-{accountId}-{postMortemId}-g{N}`（generation 0 无 `-g` 后缀）。重置不可回滚。\n- Markdown 正文最大为 4 MiB。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "href": "/zh/api-reference/on-call/incidents/incident-post-mortem-write-reset-content",
+          "metadata": {
+            "sidebarTitle": "重置故障复盘正文"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "generation": 2,
-                    "markdown_bytes": 88,
-                    "markdown_sha256": "70d764e77e68f8fbfa14d72a235ac07b0110768b8380c8e3436459ebaf02a7c0",
-                    "post_mortem_id": "8104935102bf89dc01ac638a5261fe7e",
-                    "previous_generation": 1,
-                    "previous_revision": 11,
-                    "revision": 12
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/PostMortemContentResetResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "post_mortem_id": "d3c9a7f2e5b14c8a9f0e6b2d4a1c7e35",
+                    "generation": 2,
+                    "revision": 12,
+                    "previous_generation": 1,
+                    "previous_revision": 11,
+                    "markdown_bytes": 88,
+                    "markdown_sha256": "70d764e77e68f8fbfa14d72a235ac07b0110768b8380c8e3436459ebaf02a7c0"
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -42236,65 +43638,65 @@
             "$ref": "#/components/responses/Forbidden"
           },
           "409": {
+            "description": "报告不是草稿状态、修订版本已过期，或幂等键被复用到不同请求。",
             "content": {
               "application/json": {
-                "example": {
-                  "error": {
-                    "code": "Conflict",
-                    "message": "expected_revision conflict: request has 11 but current revision is 12"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
+                  "type": "object",
+                  "required": [
+                    "request_id",
+                    "error"
+                  ],
                   "properties": {
+                    "request_id": {
+                      "type": "string"
+                    },
                     "error": {
+                      "type": "object",
+                      "required": [
+                        "code",
+                        "message"
+                      ],
                       "properties": {
                         "code": {
+                          "type": "string",
                           "enum": [
                             "Conflict"
-                          ],
-                          "type": "string"
+                          ]
                         },
                         "message": {
                           "type": "string"
                         }
-                      },
-                      "required": [
-                        "code",
-                        "message"
-                      ],
-                      "type": "object"
-                    },
-                    "request_id": {
-                      "type": "string"
+                      }
                     }
-                  },
-                  "required": [
-                    "request_id",
-                    "error"
-                  ],
-                  "type": "object"
+                  }
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "error": {
+                    "code": "Conflict",
+                    "message": "expected_revision conflict: request has 11 but current revision is 12"
+                  }
                 }
               }
-            },
-            "description": "报告不是草稿状态、修订版本已过期，或幂等键被复用到不同请求。"
+            }
           },
           "413": {
+            "description": "Markdown 正文超过 4 MiB 限制。",
             "content": {
               "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "error": {
                     "code": "EntityTooLarge",
                     "message": "markdown exceeds maximum size"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "$ref": "#/components/schemas/ErrorResponse"
+                  }
                 }
               }
-            },
-            "description": "Markdown 正文超过 4 MiB 限制。"
+            }
           },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
@@ -42303,62 +43705,64 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "重置故障复盘正文",
-        "tags": [
-          "On-call/故障管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 调用方须拥有目标复盘的编辑权限。 |\n\n## 使用说明\n\n- 仅草稿状态的报告可重置，且当前修订版本必须等于 `expected_revision`；否则返回 `409 Conflict`。\n- 同一 `idempotency_key` 只能重试相同的复盘、修订版本和 Markdown 正文；复用到不同请求会返回 `409 Conflict`。\n- 重置成功后旧的协作（Yjs）房间会被断开，客户端需切换到新 generation 的房间 `post-mortem-{accountId}-{postMortemId}-g{N}`（generation 0 无 `-g` 后缀）。重置不可回滚。\n- Markdown 正文最大为 4 MiB。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
-          "href": "/zh/api-reference/on-call/incidents/incident-post-mortem-write-reset-content",
-          "metadata": {
-            "sidebarTitle": "重置故障复盘正文"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ResetPostMortemContentRequest"
+              },
+              "example": {
+                "post_mortem_id": "d3c9a7f2e5b14c8a9f0e6b2d4a1c7e35",
+                "markdown": "# Database saturation incident\n\nThe database pool was exhausted; added saturation alert.",
+                "expected_revision": 11,
+                "idempotency_key": "postmortem-reset-d3c9a7f2-11"
+              }
+            }
           }
         }
       }
     },
     "/incident/post-mortem/delete": {
       "post": {
-        "description": "删除指定的复盘报告。",
         "operationId": "incidentPostMortemDelete",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "post_mortem_id": "8104935102bf89dc01ac638a5261fe7e"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/DeletePostMortemRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "删除复盘报告",
+        "description": "永久删除故障复盘报告及其上传的媒体文件。",
+        "tags": [
+          "On-call/故障管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 任意有效 `app_key` 均可调用 |\n\n## 使用说明\n\n- 需要专业版及以上版本，否则返回 `NoLicense`。\n- 调用者必须是账户所有者或管理员，或属于该复盘报告所属团队，否则返回 `AccessDenied`。\n- 关联的故障会解除关联，其 `post_mortem_id` 变为空。\n- `post_mortem_id` 不存在时返回 `ResourceNotFound`。\n- 成功时响应不含 `data` 字段。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "href": "/zh/api-reference/on-call/incidents/incident-post-mortem-delete",
+          "metadata": {
+            "sidebarTitle": "删除复盘报告"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -42366,6 +43770,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -42373,63 +43780,61 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "删除复盘报告",
-        "tags": [
-          "On-call/故障管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障管理**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/incidents/incident-post-mortem-delete",
-          "metadata": {
-            "sidebarTitle": "删除复盘报告"
-          }
-        }
-      }
-    },
-    "/incident/post-mortem/follow-ups/reset": {
-      "post": {
-        "description": "替换复盘报告中的后续行动项。",
-        "operationId": "postmortem-write-reset-follow-ups",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/DeletePostMortemRequest"
+              },
               "example": {
-                "follow_ups": "- Add database saturation alert\n- Review cache TTL rollout",
                 "post_mortem_id": "8104935102bf89dc01ac638a5261fe7e"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ResetPostMortemFollowUpsRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/incident/post-mortem/follow-ups/reset": {
+      "post": {
+        "operationId": "postmortem-write-reset-follow-ups",
+        "summary": "更新故障复盘后续行动",
+        "description": "替换复盘报告中保存的后续行动文本。",
+        "tags": [
+          "On-call/故障管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 需要 On-call Pro 许可。\n- 调用方须为账户所有者或管理员，或是该报告所属团队的成员，否则返回 `AccessDenied`。\n- 任何报告状态下均可调用。省略 `follow_ups` 或传 `\"\"` 会清空该文本。\n- 当 `follow_ups` 是控制台后续行动格式的 JSON 数组时，其中的条目还会同步为结构化的后续行动事项（`source_kind` = `legacy_follow_up`）；其他文本不会改动结构化事项。\n- 如需管理单条后续行动，建议使用 `/incident/work-item/*` 系列接口。\n- 调用方会被加入报告的 `author_ids`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "href": "/zh/api-reference/on-call/incidents/postmortem-write-reset-follow-ups",
+          "metadata": {
+            "sidebarTitle": "更新故障复盘后续行动"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -42437,6 +43842,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -42444,50 +43852,92 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "更新故障复盘后续行动",
-        "tags": [
-          "On-call/故障管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障管理**（`on-call`） |\n\n## 使用说明\n\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
-          "href": "/zh/api-reference/on-call/incidents/postmortem-write-reset-follow-ups",
-          "metadata": {
-            "sidebarTitle": "更新故障复盘后续行动"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ResetPostMortemFollowUpsRequest"
+              },
+              "example": {
+                "post_mortem_id": "d3c9a7f2e5b14c8a9f0e6b2d4a1c7e35",
+                "follow_ups": "- Add database saturation alert\n- Review cache TTL rollout"
+              }
+            }
           }
         }
       }
     },
     "/incident/post-mortem/info": {
       "get": {
-        "description": "通过 `post_mortem_id` 获取复盘报告。先用 `/incident/post-mortem/list` 列出报告（每行标明所属故障），再用其 id 在此获取完整报告。",
         "operationId": "incidentPostMortemInfo",
-        "parameters": [
-          {
-            "description": "故障复盘 ID。由账户 ID 与关联故障 ID 集合推导出的确定性哈希值。",
-            "in": "query",
-            "name": "post_mortem_id",
-            "required": true,
-            "schema": {
-              "type": "string"
-            }
-          }
+        "summary": "获取复盘报告",
+        "description": "按 ID 查询故障复盘报告的完整内容和自动汇总的基础信息。",
+        "tags": [
+          "On-call/故障管理"
         ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 任意有效 `app_key` 均可调用 |\n\n## 使用说明\n\n- `post_mortem_id` 可通过 `POST /incident/post-mortem/list` 获取，也可取自故障的 `post_mortem_id` 字段。\n- 私有复盘报告只有账户所有者、管理员和报告所属团队成员可以查看，其他人返回 `AccessDenied`。\n- `post_mortem_id` 不存在时返回 `ResourceNotFound`。",
+          "href": "/zh/api-reference/on-call/incidents/incident-post-mortem-info",
+          "metadata": {
+            "sidebarTitle": "获取复盘报告"
+          }
+        },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/PostMortemItem"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
+                    "meta": {
+                      "account_id": 2451002751131,
+                      "title": "Postmortem1",
+                      "status": "published",
+                      "post_mortem_id": "8104935102bf89dc01ac638a5261fe7e",
+                      "template_id": "post_mortem_default_tmpl_en-us",
+                      "incident_ids": [
+                        "69bb9233331067560c718ecd"
+                      ],
+                      "media_count": 0,
+                      "author_ids": [
+                        2477273692131
+                      ],
+                      "team_id": 2477033058131,
+                      "channel_id": 3047621227131,
+                      "is_private": false,
+                      "generation": 0,
+                      "revision": 12,
+                      "channel_name": "Ops Channel",
+                      "created_at_seconds": 1773900354,
+                      "updated_at_seconds": 1773909012
+                    },
                     "basics": {
-                      "incidents_earliest_start_seconds": 1761133512,
                       "incidents_highest_severity": "Warning",
+                      "incidents_earliest_start_seconds": 1761133512,
                       "incidents_latest_close_seconds": 1761133632,
                       "incidents_total_duration_seconds": 120,
                       "responders": [
                         {
-                          "acknowledged_at": 0,
+                          "person_id": 3790925372131,
                           "assigned_at": 1761133515,
-                          "person_id": 3790925372131
+                          "acknowledged_at": 0
                         }
                       ]
                     },
@@ -42495,47 +43945,11 @@
                       "content": "{\"type\":\"doc\",\"content\":[]}"
                     },
                     "follow_ups": "",
-                    "meta": {
-                      "account_id": 2451002751131,
-                      "author_ids": [
-                        2477273692131
-                      ],
-                      "channel_id": 3047621227131,
-                      "channel_name": "Ops Channel",
-                      "created_at_seconds": 1773900354,
-                      "incident_ids": [
-                        "69bb9233331067560c718ecd"
-                      ],
-                      "is_private": false,
-                      "media_count": 0,
-                      "post_mortem_id": "8104935102bf89dc01ac638a5261fe7e",
-                      "status": "published",
-                      "team_id": 2477033058131,
-                      "template_id": "post_mortem_default_tmpl_en-us",
-                      "title": "Postmortem1",
-                      "updated_at_seconds": 1773909012
-                    }
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/PostMortemItem"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                    "has_active_incident": false
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -42543,6 +43957,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -42550,103 +43967,101 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "获取复盘报告",
-        "tags": [
-          "On-call/故障管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障查看**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/incidents/incident-post-mortem-info",
-          "metadata": {
-            "sidebarTitle": "获取复盘报告"
+        "parameters": [
+          {
+            "name": "post_mortem_id",
+            "in": "query",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "复盘报告 ID：由账户 ID 和关联故障 ID 计算出的 32 位十六进制字符串。"
           }
-        }
+        ]
       }
     },
     "/incident/post-mortem/init": {
       "post": {
-        "description": "根据一个或多个故障和模板创建复盘草稿。",
         "operationId": "postmortem-write-init",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "incident_ids": [
-                  "69bb9233331067560c718ecd"
-                ],
-                "template_id": "post_mortem_default_tmpl_en-us"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/InitPostMortemRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "初始化故障复盘",
+        "description": "根据一个或多个故障和模板创建复盘草稿。",
+        "tags": [
+          "On-call/故障管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 需要 On-call Pro 许可。\n- 报告 ID 由账户和排序后的 `incident_ids` 推导得出；用同一组故障再次调用会原样返回已有报告。\n- 任一故障已关联其他复盘时返回 `InvalidParameter`。\n- 团队、协作空间和私有设置取自首个加载到的故障所属的协作空间；不属于任何协作空间的故障无法创建复盘。\n- 标题为各故障标题以 `, ` 拼接（最多 512 个字符）；所有标题为空时使用模板名称。\n- 新报告状态为 `drafting`，正文为空；基本信息（严重程度、时间、处理人员）根据故障计算得出。\n- 这些故障中已转为后续行动但尚未绑定复盘的事项会绑定到该报告。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "href": "/zh/api-reference/on-call/incidents/postmortem-write-init",
+          "metadata": {
+            "sidebarTitle": "初始化故障复盘"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "basics": {
-                      "incidents_earliest_start_seconds": 1761133512,
-                      "incidents_highest_severity": "Warning",
-                      "incidents_latest_close_seconds": 1761133632,
-                      "incidents_total_duration_seconds": 120,
-                      "responders": [
-                        {
-                          "acknowledged_at": 0,
-                          "assigned_at": 1761133515,
-                          "person_id": 3790925372131
-                        }
-                      ]
-                    },
-                    "content": {
-                      "content": "{\"type\":\"doc\",\"content\":[]}"
-                    },
-                    "follow_ups": "",
-                    "meta": {
-                      "account_id": 2451002751131,
-                      "author_ids": [
-                        2477273692131
-                      ],
-                      "channel_id": 3047621227131,
-                      "channel_name": "Ops Channel",
-                      "created_at_seconds": 1773900354,
-                      "incident_ids": [
-                        "69bb9233331067560c718ecd"
-                      ],
-                      "is_private": false,
-                      "media_count": 0,
-                      "post_mortem_id": "8104935102bf89dc01ac638a5261fe7e",
-                      "status": "published",
-                      "team_id": 2477033058131,
-                      "template_id": "post_mortem_default_tmpl_en-us",
-                      "title": "Postmortem1",
-                      "updated_at_seconds": 1773909012
-                    }
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/PostMortemItem"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "meta": {
+                      "account_id": 2451002751131,
+                      "title": "Database connection timeout on prod-db-01",
+                      "status": "drafting",
+                      "post_mortem_id": "d3c9a7f2e5b14c8a9f0e6b2d4a1c7e35",
+                      "template_id": "post_mortem_default_tmpl_en-us",
+                      "incident_ids": [
+                        "69bb9233331067560c718ecd"
+                      ],
+                      "media_count": 0,
+                      "author_ids": [
+                        3790925372131
+                      ],
+                      "team_id": 2477033058131,
+                      "channel_id": 2551105804131,
+                      "is_private": false,
+                      "generation": 0,
+                      "revision": 0,
+                      "channel_name": "Ops Channel",
+                      "created_at_seconds": 1773900354,
+                      "updated_at_seconds": 1773900354
+                    },
+                    "basics": {
+                      "incidents_highest_severity": "Critical",
+                      "incidents_earliest_start_seconds": 1773890000,
+                      "incidents_latest_close_seconds": 1773897200,
+                      "incidents_total_duration_seconds": 7200,
+                      "responders": [
+                        {
+                          "person_id": 3790925372131,
+                          "assigned_at": 1773890012,
+                          "acknowledged_at": 1773890100
+                        }
+                      ]
+                    },
+                    "content": {
+                      "content": ""
+                    },
+                    "follow_ups": "",
+                    "has_active_incident": false
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -42654,6 +44069,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -42661,89 +44079,92 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "初始化故障复盘",
-        "tags": [
-          "On-call/故障管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障管理**（`on-call`） |\n\n## 使用说明\n\n- 最多可将 10 个故障关联到同一份复盘报告。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
-          "href": "/zh/api-reference/on-call/incidents/postmortem-write-init",
-          "metadata": {
-            "sidebarTitle": "初始化故障复盘"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/InitPostMortemRequest"
+              },
+              "example": {
+                "incident_ids": [
+                  "69bb9233331067560c718ecd"
+                ],
+                "template_id": "post_mortem_default_tmpl_en-us"
+              }
+            }
           }
         }
       }
     },
     "/incident/post-mortem/list": {
       "post": {
-        "description": "分页查询复盘报告列表，支持过滤条件。",
         "operationId": "incidentPostMortemList",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "limit": 20,
-                "p": 1,
-                "status": "published"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ListPostMortemsRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "查询复盘报告列表",
+        "description": "查询故障复盘报告列表，可按状态、团队、协作空间和创建时间过滤。",
+        "tags": [
+          "On-call/故障管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 任意有效 `app_key` 均可调用 |\n\n## 使用说明\n\n- 账户所有者和管理员可以看到全部复盘报告；其他成员可以看到公开报告以及自己所在团队的私有报告。\n- 结果按 `order_by` 排序（默认 `created_at_seconds`），默认降序，`asc` 为 `true` 时升序。\n- 列表只返回元数据；完整内容请通过 `GET /incident/post-mortem/info` 获取。",
+          "href": "/zh/api-reference/on-call/incidents/incident-post-mortem-list",
+          "metadata": {
+            "sidebarTitle": "查询复盘报告列表"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/ListPostMortemsResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
+                    "total": 3,
                     "has_next_page": false,
                     "items": [
                       {
                         "account_id": 2451002751131,
+                        "title": "Postmortem1",
+                        "status": "published",
+                        "post_mortem_id": "8104935102bf89dc01ac638a5261fe7e",
+                        "template_id": "post_mortem_default_tmpl_en-us",
+                        "incident_ids": [
+                          "69bb9233331067560c718ecd"
+                        ],
+                        "media_count": 0,
                         "author_ids": [
                           2477273692131
                         ],
+                        "team_id": 2477033058131,
                         "channel_id": 3047621227131,
+                        "is_private": false,
+                        "generation": 0,
+                        "revision": 12,
                         "channel_name": "Ops Channel",
                         "created_at_seconds": 1773900354,
-                        "incident_ids": [
-                          "69bb9233331067560c718ecd"
-                        ],
-                        "is_private": false,
-                        "media_count": 0,
-                        "post_mortem_id": "8104935102bf89dc01ac638a5261fe7e",
-                        "status": "published",
-                        "team_id": 2477033058131,
-                        "template_id": "post_mortem_default_tmpl_en-us",
-                        "title": "Postmortem1",
                         "updated_at_seconds": 1773909012
                       }
-                    ],
-                    "total": 3
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/ListPostMortemsResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                    ]
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -42751,6 +44172,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -42758,63 +44182,63 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "查询复盘报告列表",
-        "tags": [
-          "On-call/故障管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障查看**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/incidents/incident-post-mortem-list",
-          "metadata": {
-            "sidebarTitle": "查询复盘报告列表"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ListPostMortemsRequest"
+              },
+              "example": {
+                "status": "published",
+                "p": 1,
+                "limit": 20
+              }
+            }
           }
         }
       }
     },
     "/incident/post-mortem/status/reset": {
       "post": {
-        "description": "将复盘报告设置为草稿或已发布。",
         "operationId": "postmortem-write-reset-status",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "post_mortem_id": "8104935102bf89dc01ac638a5261fe7e",
-                "status": "published"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ResetPostMortemStatusRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "更新故障复盘状态",
+        "description": "将复盘报告设置为草稿或已发布。",
+        "tags": [
+          "On-call/故障管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 需要 On-call Pro 许可。\n- 调用方须为账户所有者或管理员，或是该报告所属团队的成员，否则返回 `AccessDenied`。\n- 状态可双向切换。只有 `drafting` 状态的报告可以调用 `POST /incident/post-mortem/content/reset`。\n- 发布时会删除报告正文中已不再引用的已上传媒体文件。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "href": "/zh/api-reference/on-call/incidents/postmortem-write-reset-status",
+          "metadata": {
+            "sidebarTitle": "更新故障复盘状态"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -42822,6 +44246,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -42829,62 +44256,62 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "更新故障复盘状态",
-        "tags": [
-          "On-call/故障管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障管理**（`on-call`） |\n\n## 使用说明\n\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
-          "href": "/zh/api-reference/on-call/incidents/postmortem-write-reset-status",
-          "metadata": {
-            "sidebarTitle": "更新故障复盘状态"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ResetPostMortemStatusRequest"
+              },
+              "example": {
+                "post_mortem_id": "d3c9a7f2e5b14c8a9f0e6b2d4a1c7e35",
+                "status": "published"
+              }
+            }
           }
         }
       }
     },
     "/incident/post-mortem/template/delete": {
       "post": {
-        "description": "删除自定义复盘模板。",
         "operationId": "postmortem-write-delete-template",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "template_id": "post_mortem_custom_tmpl_01"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/DeletePostMortemTemplateRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "删除故障复盘模板",
+        "description": "删除自定义复盘模板。",
+        "tags": [
+          "On-call/故障管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 需要 On-call Pro 许可。\n- 内置模板（`post_mortem_default_tmpl_*`）不可删除；ID 不存在时返回 `ResourceNotFound`。\n- 需为账户所有者或管理员，或是模板所属团队的成员。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "href": "/zh/api-reference/on-call/incidents/postmortem-write-delete-template",
+          "metadata": {
+            "sidebarTitle": "删除故障复盘模板"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -42892,6 +44319,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -42899,70 +44329,72 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "删除故障复盘模板",
-        "tags": [
-          "On-call/故障管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障管理**（`on-call`） |\n\n## 使用说明\n\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
-          "href": "/zh/api-reference/on-call/incidents/postmortem-write-delete-template",
-          "metadata": {
-            "sidebarTitle": "删除故障复盘模板"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/DeletePostMortemTemplateRequest"
+              },
+              "example": {
+                "template_id": "kQ3vXn8pR2mT7wYbZc4dEf"
+              }
+            }
           }
         }
       }
     },
     "/incident/post-mortem/template/info": {
       "get": {
-        "description": "按 ID 返回单个故障复盘模板。",
         "operationId": "postmortem-read-template-info",
-        "parameters": [
-          {
-            "description": "Template ID.",
-            "in": "query",
-            "name": "template_id",
-            "required": true,
-            "schema": {
-              "type": "string"
-            }
-          }
+        "summary": "查看故障复盘模板详情",
+        "description": "按 ID 返回单个故障复盘模板。",
+        "tags": [
+          "On-call/故障管理"
         ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 需要 On-call Pro 许可。\n- 内置 ID `post_mortem_default_tmpl_zh-cn` 和 `post_mortem_default_tmpl_en-us` 不受请求语言限制均可查询；ID 不存在时返回 `ResourceNotFound`。",
+          "href": "/zh/api-reference/on-call/incidents/postmortem-read-template-info",
+          "metadata": {
+            "sidebarTitle": "查看故障复盘模板详情"
+          }
+        },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "account_id": 2451002751131,
-                    "content": "[{\"type\":\"heading\",\"content\":\"Summary\"}]",
-                    "content_markdown": "## Summary\nDescribe what happened.",
-                    "created_at_seconds": 1773900000,
-                    "description": "Default sections for post-mortem reports.",
-                    "name": "Default post-mortem report",
-                    "team_id": 2477033058131,
-                    "template_id": "post_mortem_default_tmpl_en-us",
-                    "updated_at_seconds": 1773903600
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/PostMortemTemplate"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "account_id": 0,
+                    "template_id": "post_mortem_default_tmpl_en-us",
+                    "name": "Default Post Mortem Report Template",
+                    "description": "Standard post-mortem template with common sections",
+                    "content": "[{\"type\":\"heading\",\"props\":{\"level\":2},\"content\":\"Summary\"}]",
+                    "content_markdown": "## Summary\n> Provide a high-level description of the incident.",
+                    "team_id": 0,
+                    "created_at_seconds": 0,
+                    "updated_at_seconds": 0
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -42970,6 +44402,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -42977,81 +44412,87 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "查看故障复盘模板详情",
-        "tags": [
-          "On-call/故障管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障查看**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/incidents/postmortem-read-template-info",
-          "metadata": {
-            "sidebarTitle": "查看故障复盘模板详情"
+        "parameters": [
+          {
+            "name": "template_id",
+            "in": "query",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "模板 ID：内置 ID（如 `post_mortem_default_tmpl_en-us`）或从 `POST /incident/post-mortem/template/list` 获取的自定义模板 ID。"
           }
-        }
+        ]
       }
     },
     "/incident/post-mortem/template/list": {
       "post": {
-        "description": "返回账号下的内置和自定义故障复盘模板。",
         "operationId": "postmortem-read-list-templates",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "asc": false,
-                "limit": 20,
-                "order_by": "created_at_seconds",
-                "p": 1
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ListPostMortemTemplatesRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "查询故障复盘模板列表",
+        "description": "返回内置复盘模板，以及账户的自定义模板。",
+        "tags": [
+          "On-call/故障管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 需要 On-call Pro 许可。\n- 内置模板总是排在最前，并与请求语言对应：中文返回 `post_mortem_default_tmpl_zh-cn`，其他语言返回 `post_mortem_default_tmpl_en-us`。`total` 包含该内置模板。\n- 自定义模板按 `created_at_seconds` 排序，默认最新在前，`asc` 为 true 时升序。\n- 使用 `p` 和 `limit` 分页；`p` × `limit` 不得超过 10,000。\n- 内置模板的 `account_id`、`team_id` 及两个时间戳均为 0。",
+          "href": "/zh/api-reference/on-call/incidents/postmortem-read-list-templates",
+          "metadata": {
+            "sidebarTitle": "查询故障复盘模板列表"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "has_next_page": false,
-                    "items": [
-                      {
-                        "account_id": 2451002751131,
-                        "content": "[{\"type\":\"heading\",\"content\":\"Summary\"}]",
-                        "content_markdown": "## Summary\nDescribe what happened.",
-                        "created_at_seconds": 1773900000,
-                        "description": "Default sections for post-mortem reports.",
-                        "name": "Default post-mortem report",
-                        "team_id": 2477033058131,
-                        "template_id": "post_mortem_default_tmpl_en-us",
-                        "updated_at_seconds": 1773903600
-                      }
-                    ],
-                    "total": 2
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/ListPostMortemTemplatesResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "total": 2,
+                    "has_next_page": false,
+                    "items": [
+                      {
+                        "account_id": 0,
+                        "template_id": "post_mortem_default_tmpl_en-us",
+                        "name": "Default Post Mortem Report Template",
+                        "description": "Standard post-mortem template with common sections",
+                        "content": "[{\"type\":\"heading\",\"props\":{\"level\":2},\"content\":\"Summary\"}]",
+                        "content_markdown": "## Summary\n> Provide a high-level description of the incident.",
+                        "team_id": 0,
+                        "created_at_seconds": 0,
+                        "updated_at_seconds": 0
+                      },
+                      {
+                        "account_id": 2451002751131,
+                        "template_id": "kQ3vXn8pR2mT7wYbZc4dEf",
+                        "name": "Production incident template",
+                        "description": "Template for production incident reviews.",
+                        "content": "[{\"type\":\"heading\",\"props\":{\"level\":2},\"content\":\"Summary\"}]",
+                        "content_markdown": "## Summary\nDescribe what happened.",
+                        "team_id": 2477033058131,
+                        "created_at_seconds": 1773900000,
+                        "updated_at_seconds": 1773903600
+                      }
+                    ]
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -43059,6 +44500,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -43066,76 +44510,151 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "查询故障复盘模板列表",
-        "tags": [
-          "On-call/故障管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障查看**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/incidents/postmortem-read-list-templates",
-          "metadata": {
-            "sidebarTitle": "查询故障复盘模板列表"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ListPostMortemTemplatesRequest"
+              },
+              "example": {
+                "p": 1,
+                "limit": 20,
+                "order_by": "created_at_seconds",
+                "asc": false
+              }
+            }
           }
         }
       }
     },
     "/incident/post-mortem/template/upsert": {
       "post": {
-        "description": "创建自定义复盘模板，或更新已有模板。",
         "operationId": "postmortem-write-upsert-template",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "content": "[{\"type\":\"heading\",\"content\":\"Summary\"}]",
-                "content_markdown": "## Summary\nDescribe what happened.",
-                "description": "Template for production incident reviews.",
-                "name": "Production incident template",
-                "team_id": 2477033058131
-              },
-              "schema": {
-                "$ref": "#/components/schemas/UpsertPostMortemTemplateRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "创建或更新故障复盘模板",
+        "description": "创建自定义复盘模板，或按 `template_id` 替换已有模板。",
+        "tags": [
+          "On-call/故障管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 需要 On-call Pro 许可。\n- 省略 `template_id` 表示创建：`team_id` 必须是已存在的团队，模板 ID 由服务端生成。\n- 传 `template_id` 表示替换已有自定义模板；ID 不存在时返回 `ResourceNotFound`。更新需为账户所有者或管理员，或是模板所属团队的成员。\n- 所有文本字段整体替换：省略的 `description` 或 `content_markdown` 会变为空。更新时传 `team_id` 会把模板移到该团队；省略或传 0 则保持当前团队。\n- 内置模板（`post_mortem_default_tmpl_*`）不可修改。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "href": "/zh/api-reference/on-call/incidents/postmortem-write-upsert-template",
+          "metadata": {
+            "sidebarTitle": "创建或更新故障复盘模板"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/PostMortemTemplate"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "account_id": 2451002751131,
-                    "content": "[{\"type\":\"heading\",\"content\":\"Summary\"}]",
+                    "template_id": "kQ3vXn8pR2mT7wYbZc4dEf",
+                    "name": "Production incident template",
+                    "description": "Template for production incident reviews.",
+                    "content": "[{\"type\":\"heading\",\"props\":{\"level\":2},\"content\":\"Summary\"}]",
                     "content_markdown": "## Summary\nDescribe what happened.",
-                    "created_at_seconds": 1773900000,
-                    "description": "Default sections for post-mortem reports.",
-                    "name": "Default post-mortem report",
                     "team_id": 2477033058131,
-                    "template_id": "post_mortem_default_tmpl_en-us",
+                    "created_at_seconds": 1773900000,
                     "updated_at_seconds": 1773903600
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "429": {
+            "$ref": "#/components/responses/TooManyRequests"
+          },
+          "500": {
+            "$ref": "#/components/responses/ServerError"
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/UpsertPostMortemTemplateRequest"
+              },
+              "example": {
+                "team_id": 2477033058131,
+                "name": "Production incident template",
+                "description": "Template for production incident reviews.",
+                "content": "[{\"type\":\"heading\",\"props\":{\"level\":2},\"content\":\"Summary\"}]",
+                "content_markdown": "## Summary\nDescribe what happened."
+              }
+            }
+          }
+        }
+      }
+    },
+    "/incident/post-mortem/title/reset": {
+      "post": {
+        "operationId": "postmortem-write-reset-title",
+        "summary": "更新故障复盘标题",
+        "description": "替换复盘报告标题。",
+        "tags": [
+          "On-call/故障管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 需要 On-call Pro 许可。\n- 调用方须为账户所有者或管理员，或是该报告所属团队的成员，否则返回 `AccessDenied`。\n- 调用方会被加入报告的 `author_ids`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "href": "/zh/api-reference/on-call/incidents/postmortem-write-reset-title",
+          "metadata": {
+            "sidebarTitle": "更新故障复盘标题"
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "成功",
+            "content": {
+              "application/json": {
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/PostMortemTemplate"
+                          "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -43143,6 +44662,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -43150,63 +44672,63 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "创建或更新故障复盘模板",
-        "tags": [
-          "On-call/故障管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障管理**（`on-call`） |\n\n## 使用说明\n\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
-          "href": "/zh/api-reference/on-call/incidents/postmortem-write-upsert-template",
-          "metadata": {
-            "sidebarTitle": "创建或更新故障复盘模板"
-          }
-        }
-      }
-    },
-    "/incident/post-mortem/title/reset": {
-      "post": {
-        "description": "替换复盘报告标题。",
-        "operationId": "postmortem-write-reset-title",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {
-                "post_mortem_id": "8104935102bf89dc01ac638a5261fe7e",
-                "title": "Production API latency incident"
-              },
               "schema": {
                 "$ref": "#/components/schemas/ResetPostMortemTitleRequest"
+              },
+              "example": {
+                "post_mortem_id": "d3c9a7f2e5b14c8a9f0e6b2d4a1c7e35",
+                "title": "Production API latency incident"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/incident/remove": {
+      "post": {
+        "operationId": "incidentRemove",
+        "summary": "删除故障",
+        "description": "永久删除故障及其告警、原始事件和时间线。",
+        "tags": [
+          "On-call/故障管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **故障管理**或**协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 删除不可恢复。被删除故障的分析统计数据会在后台清除。\n- 任一故障属于调用者无权访问的协作空间时返回 `InvalidParameter`。\n- 不存在的故障 ID 会被忽略。\n- 同一账户内有其他关闭、重开、合并、评论或删除操作正在执行时返回 `RequestTooFrequently`，稍后重试即可。",
+          "href": "/zh/api-reference/on-call/incidents/incident-remove",
+          "metadata": {
+            "sidebarTitle": "删除故障"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -43214,6 +44736,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -43221,64 +44746,64 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "更新故障复盘标题",
-        "tags": [
-          "On-call/故障管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障管理**（`on-call`） |\n\n## 使用说明\n\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
-          "href": "/zh/api-reference/on-call/incidents/postmortem-write-reset-title",
-          "metadata": {
-            "sidebarTitle": "更新故障复盘标题"
-          }
-        }
-      }
-    },
-    "/incident/remove": {
-      "post": {
-        "description": "永久删除一个故障及其关联数据。",
-        "operationId": "incidentRemove",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/RemoveIncidentRequest"
+              },
               "example": {
                 "incident_ids": [
                   "69da451ef77b1b51f40e83ee"
                 ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/RemoveIncidentRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/incident/reopen": {
+      "post": {
+        "operationId": "incidentReopen",
+        "summary": "重开故障",
+        "description": "重新打开已关闭的故障，并从第一级重新分派。",
+        "tags": [
+          "On-call/故障管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **故障管理**或**协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 所有故障都必须处于 `Closed`，否则整个请求返回 `InvalidParameter`。\n- 重开后故障回到 `Triggered`，`ack_time`、`close_time`、`closer_id` 以及所有处理人的认领状态都会被重置。\n- 每个故障按原分派对象从第一级重新分派，`assigned_to.type` 置为 `reopen`。\n- 同一账户内有其他关闭、重开、合并、评论或删除操作正在执行时返回 `RequestTooFrequently`，稍后重试即可。",
+          "href": "/zh/api-reference/on-call/incidents/incident-reopen",
+          "metadata": {
+            "sidebarTitle": "重开故障"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -43286,6 +44811,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -43293,65 +44821,65 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "删除故障",
-        "tags": [
-          "On-call/故障管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障管理**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/incidents/incident-remove",
-          "metadata": {
-            "sidebarTitle": "删除故障"
-          }
-        }
-      }
-    },
-    "/incident/reopen": {
-      "post": {
-        "description": "重新打开一个已恢复的故障。",
-        "operationId": "incidentReopen",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ReopenIncidentRequest"
+              },
               "example": {
                 "incident_ids": [
                   "69da451ef77b1b51f40e83ee"
                 ],
                 "reason": "Monitoring detected the issue recurred after the initial fix."
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ReopenIncidentRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/incident/reset": {
+      "post": {
+        "operationId": "incidentReset",
+        "summary": "更新故障信息",
+        "description": "在一次调用中更新故障的标题、描述、影响、根因、解决方案或严重程度。",
+        "tags": [
+          "On-call/故障管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **故障管理**或**协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 至少要传一个字段。未传的字段和空字符串都保持原值，因此本接口无法清空字段。\n- 与当前值相同的字段会被跳过。每个发生变化的字段各写一条时间线记录（`i_r_title`、`i_r_desc`、`i_r_impact`、`i_r_rc`、`i_r_rsltn` 或 `i_r_severity`）。\n- 修改 `title`、`description` 或 `incident_severity` 会把该字段加入 `manual_overrides`，此后合并进来的告警不再覆盖它。\n- 已关闭的故障同样可以更新。",
+          "href": "/zh/api-reference/on-call/incidents/incident-reset",
+          "metadata": {
+            "sidebarTitle": "更新故障信息"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -43359,6 +44887,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -43366,64 +44897,64 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "重开故障",
-        "tags": [
-          "On-call/故障管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障管理**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/incidents/incident-reopen",
-          "metadata": {
-            "sidebarTitle": "重开故障"
-          }
-        }
-      }
-    },
-    "/incident/reset": {
-      "post": {
-        "description": "一次调用更新故障的多个可编辑字段，包括标题、描述、影响范围、根因、恢复方案和严重程度。至少需要提供一个字段。",
-        "operationId": "incidentReset",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {
-                "incident_id": "69da451ef77b1b51f40e83ee",
-                "incident_severity": "Critical",
-                "title": "Database connection timeout - prod-db-01 primary"
-              },
               "schema": {
                 "$ref": "#/components/schemas/UpdateIncidentFieldsRequest"
+              },
+              "example": {
+                "incident_id": "69da451ef77b1b51f40e83ee",
+                "title": "Database connection timeout - prod-db-01 primary",
+                "incident_severity": "Critical"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/incident/resolve": {
+      "post": {
+        "operationId": "incidentResolve",
+        "summary": "恢复故障",
+        "description": "关闭一个或多个故障，可同时记录根因、解决方案和关闭表单的填写内容。",
+        "tags": [
+          "On-call/故障管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **故障管理**或**协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 关闭表单生效时，`custom_fields`、`summary` 和 `images` 必须符合其中可见元素及必填规则。\n- 批量操作只有在全部选中的故障解析到同一张表单时才接受表单值；否则请逐条关闭。\n- 旧字段 `values` 和 `custom_values` 会被拒绝，请使用 `custom_fields`。\n- 已关闭的故障会被跳过，不报错；存在不认识的故障 ID 时整个请求返回 `InvalidParameter`。\n- 关闭处于 `Triggered` 的故障时，会先以调用者身份自动认领。\n- 关闭后，故障下未完成的行动项会转为后续行动，之后到达的事件也不再合并进该故障已有的告警。\n- 同一账户内有其他关闭、重开、合并、评论或删除操作正在执行时返回 `RequestTooFrequently`，稍后重试即可。",
+          "href": "/zh/api-reference/on-call/incidents/incident-resolve",
+          "metadata": {
+            "sidebarTitle": "恢复故障"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -43431,6 +44962,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -43438,66 +44972,66 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "更新故障信息",
-        "tags": [
-          "On-call/故障管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障管理**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/incidents/incident-reset",
-          "metadata": {
-            "sidebarTitle": "更新故障信息"
-          }
-        }
-      }
-    },
-    "/incident/resolve": {
-      "post": {
-        "description": "将故障标记为已恢复。",
-        "operationId": "incidentResolve",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ResolveIncidentRequest"
+              },
               "example": {
                 "incident_ids": [
                   "69da451ef77b1b51f40e83ee"
                 ],
-                "resolution": "Deployed hotfix v2.3.1 and restarted the affected service.",
-                "root_cause": "Memory leak in the connection pool caused by a missing cleanup call."
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ResolveIncidentRequest"
+                "root_cause": "Memory leak in the connection pool caused by a missing cleanup call.",
+                "resolution": "Deployed hotfix v2.3.1 and restarted the affected service."
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/incident/responder/add": {
+      "post": {
+        "operationId": "incidentResponderAdd",
+        "summary": "添加故障处理人员",
+        "description": "为未关闭的故障添加处理人，并通知新加入的处理人。",
+        "tags": [
+          "On-call/故障管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **故障管理**或**协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 已有处理人保持不变，已经是处理人的 ID 会被跳过。如需替换整组处理人，请使用 `POST /incident/assign`。\n- 已关闭的故障返回 `InvalidParameter`。\n- 账户中不存在的成员 ID 会被忽略。\n- 新处理人按 `notify` 设置接收通知；默认按各自的个人通知偏好发送。",
+          "href": "/zh/api-reference/on-call/incidents/incident-responder-add",
+          "metadata": {
+            "sidebarTitle": "添加故障处理人员"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -43505,6 +45039,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -43512,159 +45049,83 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "恢复故障",
-        "tags": [
-          "On-call/故障管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障管理**（`on-call`） |\n\n## 使用说明\n\n- 解决表单生效时，`custom_fields`、`summary` 和 `images` 必须符合其中可见元素及必填规则。\n- 批量操作只有在全部选中的故障解析到同一张表单时才接受表单值；否则请逐条解决。\n- 旧字段 `values` 和 `custom_values` 会被拒绝，请使用 `custom_fields`。\n- 已审计 —— 变更会记录到审计日志。",
-          "href": "/zh/api-reference/on-call/incidents/incident-resolve",
-          "metadata": {
-            "sidebarTitle": "恢复故障"
-          }
-        }
-      }
-    },
-    "/incident/responder/add": {
-      "post": {
-        "description": "向已有故障添加处理人员。",
-        "operationId": "incidentResponderAdd",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/AddIncidentResponderRequest"
+              },
               "example": {
                 "incident_id": "69da451ef77b1b51f40e83ee",
                 "person_ids": [
                   2476444212131,
                   2476444212132
                 ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/AddIncidentResponderRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/incident/sdp/request/list": {
+      "post": {
+        "operationId": "incident-service-desk-plus-request-read-list",
+        "summary": "获取 ServiceDeskPlus 关联故障",
+        "description": "分页查询 ServiceDeskPlus 请求与 Flashduty 故障的同步映射记录。",
+        "tags": [
+          "On-call/故障管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障查看**或**故障管理**或**协作空间查看**或**协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 查询 ServiceDeskPlus 请求与 Flashduty 故障之间的同步映射记录，用于排查 ITSM 同步状态或定位外部请求链接。\n- 不按 `incident_id` 查询时，`start_time` 和 `end_time` 必填，均为 Unix 秒时间戳；时间范围不能超过 30 天。\n- `status` 仅支持 `success` 和 `failed`，分别表示同步成功和同步失败。\n- 响应按内部记录 ID 排序；`asc` 为 `true` 时升序，否则降序。\n- 只能通过 `search_after_ctx` 翻页：传入上次响应返回的值；`p` 会被忽略。",
+          "href": "/zh/api-reference/on-call/incidents/incident-service-desk-plus-request-read-list",
+          "metadata": {
+            "sidebarTitle": "获取 ServiceDeskPlus 关联故障"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/EmptyResponse"
+                          "$ref": "#/components/schemas/ServiceDeskPlusRequestListResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
-                }
-              }
-            },
-            "description": "成功"
-          },
-          "400": {
-            "$ref": "#/components/responses/BadRequest"
-          },
-          "401": {
-            "$ref": "#/components/responses/Unauthorized"
-          },
-          "429": {
-            "$ref": "#/components/responses/TooManyRequests"
-          },
-          "500": {
-            "$ref": "#/components/responses/ServerError"
-          }
-        },
-        "summary": "添加故障处理人员",
-        "tags": [
-          "On-call/故障管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障管理**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/incidents/incident-responder-add",
-          "metadata": {
-            "sidebarTitle": "添加故障处理人员"
-          }
-        }
-      }
-    },
-    "/incident/sdp/request/list": {
-      "post": {
-        "description": "分页查询 ServiceDeskPlus 请求与 Flashduty 故障的同步映射记录。",
-        "operationId": "incident-service-desk-plus-request-read-list",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "channel_ids": [
-                  12345
-                ],
-                "end_time": 1779600000,
-                "limit": 20,
-                "start_time": 1779513600,
-                "status": "success"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ServiceDeskPlusRequestListRequest"
-              }
-            }
-          },
-          "required": true
-        },
-        "responses": {
-          "200": {
-            "content": {
-              "application/json": {
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
-                    "has_next_page": false,
                     "items": [
                       {
-                        "channel_id": 12345,
-                        "channel_name": "Payments",
                         "created_at": 1779514631,
-                        "incident_id": "685d7f4e51b9a9a6d4d0c123",
-                        "incident_title": "Checkout API 5xx rate increased",
-                        "integration_id": 98765,
+                        "status": "success",
                         "request_id": "100000000001",
                         "request_link": "https://servicedesk.example.com/app/itdesk/ui/requests/100000000001/details",
-                        "status": "success"
+                        "integration_id": 98765,
+                        "incident_id": "685d7f4e51b9a9a6d4d0c123",
+                        "incident_title": "Checkout API 5xx rate increased",
+                        "channel_id": 12345,
+                        "channel_name": "Payments"
                       }
                     ],
-                    "search_after_ctx": "",
-                    "total": 1
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/ServiceDeskPlusRequestListResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                    "total": 1,
+                    "has_next_page": false,
+                    "search_after_ctx": ""
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -43672,6 +45133,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -43679,65 +45143,68 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "获取 ServiceDeskPlus 关联故障",
-        "tags": [
-          "On-call/故障管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障查看**（`on-call`） |\n\n## 使用说明\n\n- 查询 ServiceDeskPlus 请求与 Flashduty 故障之间的同步映射记录，用于排查 ITSM 同步状态或定位外部请求链接。\n- 不按 `incident_id` 查询时，`start_time` 和 `end_time` 必填，均为 Unix 秒时间戳；时间范围不能超过 30 天。\n- `status` 仅支持 `success` 和 `failed`，分别表示同步成功和同步失败。\n- 响应按内部记录 ID 排序；`asc` 为 `true` 时升序，否则降序。继续翻页时传入上次响应的 `search_after_ctx`。",
-          "href": "/zh/api-reference/on-call/incidents/incident-service-desk-plus-request-read-list",
-          "metadata": {
-            "sidebarTitle": "获取 ServiceDeskPlus 关联故障"
-          }
-        }
-      }
-    },
-    "/incident/snooze": {
-      "post": {
-        "description": "暂时屏蔽故障通知直到指定时间。",
-        "operationId": "incidentSnooze",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ServiceDeskPlusRequestListRequest"
+              },
               "example": {
-                "incident_ids": [
-                  "69da451ef77b1b51f40e83ee"
+                "start_time": 1779513600,
+                "end_time": 1779600000,
+                "status": "success",
+                "channel_ids": [
+                  12345
                 ],
-                "minutes": 60
-              },
-              "schema": {
-                "$ref": "#/components/schemas/SnoozeIncidentRequest"
+                "limit": 20
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/incident/snooze": {
+      "post": {
+        "operationId": "incidentSnooze",
+        "summary": "暂停故障通知",
+        "description": "在指定分钟数内暂停已认领故障的通知。",
+        "tags": [
+          "On-call/故障管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **故障管理**或**协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 只有处理进度为 `Processing` 的故障可以暂停；任一故障处于其他进度时整个请求返回 `InvalidParameter`。\n- 经过 `minutes` 分钟后自动恢复通知，也可以提前调用 `POST /incident/wake` 恢复。暂停结束时间记录在故障的 `snoozed_before` 字段（Unix 秒）。\n- 故障被重新分派或回到 `Triggered` 时，暂停也会被清除。",
+          "href": "/zh/api-reference/on-call/incidents/incident-snooze",
+          "metadata": {
+            "sidebarTitle": "暂停故障通知"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -43745,6 +45212,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -43752,64 +45222,65 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "暂停故障通知",
-        "tags": [
-          "On-call/故障管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障管理**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/incidents/incident-snooze",
-          "metadata": {
-            "sidebarTitle": "暂停故障通知"
-          }
-        }
-      }
-    },
-    "/incident/unack": {
-      "post": {
-        "description": "取消故障的认领状态。",
-        "operationId": "incidentUnack",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/SnoozeIncidentRequest"
+              },
               "example": {
                 "incident_ids": [
                   "69da451ef77b1b51f40e83ee"
-                ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/UnackIncidentRequest"
+                ],
+                "minutes": 60
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/incident/unack": {
+      "post": {
+        "operationId": "incidentUnack",
+        "summary": "取消认领故障",
+        "description": "撤销调用成员对一个或多个故障的认领。",
+        "tags": [
+          "On-call/故障管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **故障管理**或**协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 只撤销调用成员自己的认领。只有当没有其他处理人仍处于已认领状态时，故障才会回到 `Triggered` 并清除暂停。\n- 所有故障都必须处于 `Processing`；任一故障为 `Triggered` 或 `Closed` 时整个请求返回 `InvalidParameter`。",
+          "href": "/zh/api-reference/on-call/incidents/incident-unack",
+          "metadata": {
+            "sidebarTitle": "取消认领故障"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -43817,6 +45288,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -43824,64 +45298,64 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "取消认领故障",
-        "tags": [
-          "On-call/故障管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障管理**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/incidents/incident-unack",
-          "metadata": {
-            "sidebarTitle": "取消认领故障"
-          }
-        }
-      }
-    },
-    "/incident/wake": {
-      "post": {
-        "description": "取消故障的暂停状态，恢复通知。",
-        "operationId": "incidentWake",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/UnackIncidentRequest"
+              },
               "example": {
                 "incident_ids": [
                   "69da451ef77b1b51f40e83ee"
                 ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/WakeIncidentRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/incident/wake": {
+      "post": {
+        "operationId": "incidentWake",
+        "summary": "恢复故障通知",
+        "description": "结束故障的暂停状态，立即恢复通知。",
+        "tags": [
+          "On-call/故障管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **故障管理**或**协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 暂停已经结束的故障会被跳过；任一故障已关闭时整个请求返回 `InvalidParameter`。",
+          "href": "/zh/api-reference/on-call/incidents/incident-wake",
+          "metadata": {
+            "sidebarTitle": "恢复故障通知"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -43889,6 +45363,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -43896,68 +45373,65 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "恢复故障通知",
-        "tags": [
-          "On-call/故障管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障管理**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/incidents/incident-wake",
-          "metadata": {
-            "sidebarTitle": "恢复故障通知"
-          }
-        }
-      }
-    },
-    "/incident/war-room/add-member": {
-      "post": {
-        "description": "向与故障集成绑定的 IM 作战室添加一名或多名成员。",
-        "operationId": "incident-write-add-war-room-member",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/WakeIncidentRequest"
+              },
               "example": {
-                "chat_id": "oc_5ce6d572455d361153b7cb51da133945",
-                "integration_id": 362,
-                "member_ids": [
-                  20001,
-                  20002
+                "incident_ids": [
+                  "69da451ef77b1b51f40e83ee"
                 ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/AddWarRoomMemberRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/incident/war-room/add-member": {
+      "post": {
+        "operationId": "incident-write-add-war-room-member",
+        "summary": "添加作战室成员",
+        "description": "向飞书、钉钉、企业微信或 Slack 上已有的故障作战室添加成员。",
+        "tags": [
+          "On-call/故障管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **故障管理**（`on-call`）或 **协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 需要 On-call Pro 许可。\n- `chat_id` 必须对应通过 Flashduty 在集成 `integration_id` 上创建的作战室，否则返回 `ResourceNotFound`。\n- 仅飞书、钉钉、企业微信和 Slack 集成支持作战室；其他集成返回 `InvalidParameter`。\n- `member_ids` 中的每个 ID 都必须是本账户的人员；任一 ID 无效则整个请求失败。\n- 成功时 `data` 为字符串 `ok`。",
+          "href": "/zh/api-reference/on-call/incidents/incident-write-add-war-room-member",
+          "metadata": {
+            "sidebarTitle": "添加作战室成员"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": "ok",
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "description": "成功时返回字面量 \"ok\"。",
-                          "type": "string"
+                          "type": "string",
+                          "description": "成功时返回字面量 \"ok\"。"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": "ok"
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -43965,6 +45439,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -43972,68 +45449,71 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "添加作战室成员",
-        "tags": [
-          "On-call/故障管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n",
-          "href": "/zh/api-reference/on-call/incidents/incident-write-add-war-room-member",
-          "metadata": {
-            "sidebarTitle": "添加作战室成员"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/AddWarRoomMemberRequest"
+              },
+              "example": {
+                "integration_id": 2551105804131,
+                "chat_id": "oc_5ce6d572455d361153b7cb51da133945",
+                "member_ids": [
+                  3790925372131,
+                  5068740052131
+                ]
+              }
+            }
           }
         }
       }
     },
     "/incident/war-room/create": {
       "post": {
-        "description": "为故障协同响应创建战情室频道。",
         "operationId": "incidentWarRoomCreate",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "add_observers": true,
-                "incident_id": "69da451ef77b1b51f40e83ee",
-                "integration_id": 2490562293131
-              },
-              "schema": {
-                "$ref": "#/components/schemas/CreateWarRoomRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "创建战情室",
+        "description": "为故障创建 IM 群聊作为作战室，并邀请成员加入。",
+        "tags": [
+          "On-call/故障管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **故障管理**或**协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 需要专业版及以上版本，否则返回 `NoLicense`。\n- IM 集成必须处于启用状态并开启作战室功能。支持飞书、钉钉、企业微信（仅自建应用）和 Slack。\n- 每个故障只能有一个作战室。使用相同 `integration_id` 再次调用会返回已有群组（`share_link` 为空）；使用不同的 `integration_id` 返回 `InvalidParameter`。\n- 同一故障并发创建时返回 `RequestTooFrequently`。\n- 创建成功后会写入一条 `i_wr_create` 时间线记录。",
+          "href": "/zh/api-reference/on-call/incidents/incident-war-room-create",
+          "metadata": {
+            "sidebarTitle": "创建战情室"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "chat_id": "oc_a0553eda9014c2de1b3a8f75b4e0c000",
-                    "chat_name": "Incident #0E83EE war room",
-                    "share_link": ""
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/WarRoom"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "chat_id": "oc_a0553eda9014c2de1b3a8f75b4e0c000",
+                    "chat_name": "Incident #0E83EE war room",
+                    "share_link": ""
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -44041,6 +45521,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -44048,77 +45531,78 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "创建战情室",
-        "tags": [
-          "On-call/故障管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障管理**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/incidents/incident-war-room-create",
-          "metadata": {
-            "sidebarTitle": "创建战情室"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CreateWarRoomRequest"
+              },
+              "example": {
+                "incident_id": "69da451ef77b1b51f40e83ee",
+                "integration_id": 2490562293131,
+                "add_observers": true
+              }
+            }
           }
         }
       }
     },
     "/incident/war-room/default-observers": {
       "post": {
-        "description": "返回开启作战室时建议作为默认观察者的历史响应人。",
         "operationId": "incident-read-get-war-room-default-observers",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "incident_id": "664a1b2c3d4e5f6a7b8c9d0e"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/GetWarRoomDefaultObserversRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "查看作战室默认观察者",
+        "description": "返回曾被分派到故障、但当前已不是处理人员的人，作为作战室的建议观察者。",
+        "tags": [
+          "On-call/故障管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 需要 On-call Pro 许可。\n- 观察者为在故障时间线中曾被分派或被添加为处理人员、但当前不在处理人员中的人。\n- `observers` 为空数组表示没有符合条件的人。\n- 故障不存在时返回 `ResourceNotFound`。",
+          "href": "/zh/api-reference/on-call/incidents/incident-read-get-war-room-default-observers",
+          "metadata": {
+            "sidebarTitle": "查看作战室默认观察者"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "observers": [
-                      {
-                        "account_id": 10001,
-                        "as": "responder",
-                        "avatar": "https://cdn.flashcat.cloud/avatar/20001.png",
-                        "email": "alice@acme.com",
-                        "locale": "zh-CN",
-                        "person_id": 20001,
-                        "person_name": "Alice Chen",
-                        "phone": "+8613800000000",
-                        "status": "active",
-                        "time_zone": "Asia/Shanghai"
-                      }
-                    ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/GetWarRoomDefaultObserversResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "observers": [
+                      {
+                        "account_id": 2451002751131,
+                        "person_id": 3790925372131,
+                        "person_name": "Alice Chen",
+                        "avatar": "https://example.com/avatars/3790925372131.png",
+                        "email": "alice@example.com",
+                        "locale": "zh-CN",
+                        "time_zone": "Asia/Shanghai",
+                        "as": "member",
+                        "status": "enabled"
+                      }
+                    ]
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -44126,6 +45610,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -44133,63 +45620,61 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "查看作战室默认观察者",
-        "tags": [
-          "On-call/故障管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n",
-          "href": "/zh/api-reference/on-call/incidents/incident-read-get-war-room-default-observers",
-          "metadata": {
-            "sidebarTitle": "查看作战室默认观察者"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/GetWarRoomDefaultObserversRequest"
+              },
+              "example": {
+                "incident_id": "69bb9233331067560c718ecd"
+              }
+            }
           }
         }
       }
     },
     "/incident/war-room/delete": {
       "post": {
-        "description": "删除指定的故障战情室。",
         "operationId": "incidentWarRoomDelete",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "incident_id": "69da451ef77b1b51f40e83ee",
-                "integration_id": 2490562293131
-              },
-              "schema": {
-                "$ref": "#/components/schemas/DeleteWarRoomRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "删除战情室",
+        "description": "在 IM 平台解散故障的作战室群组，并解除与故障的关联。",
+        "tags": [
+          "On-call/故障管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **故障管理**或**协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 先删除作战室记录；IM 侧解散群组失败（例如群组已被解散）会被忽略。\n- 故障在该集成上没有作战室时直接返回成功，不做任何变更。\n- 如果只想解除关联（适用于 IM 集成已禁用或已删除的情况），设置 `unlink_only: true` 并传入该作战室的 `chat_id`。此模式仅限账户所有者和管理员使用，集成仍处于启用状态时返回 `InvalidParameter`，且不会解散群组。\n- 成功时响应不含 `data` 字段。",
+          "href": "/zh/api-reference/on-call/incidents/incident-war-room-delete",
+          "metadata": {
+            "sidebarTitle": "删除战情室"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -44197,6 +45682,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -44204,67 +45692,67 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "删除战情室",
-        "tags": [
-          "On-call/故障管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障管理**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/incidents/incident-war-room-delete",
-          "metadata": {
-            "sidebarTitle": "删除战情室"
-          }
-        }
-      }
-    },
-    "/incident/war-room/detail": {
-      "post": {
-        "description": "获取故障的战情室配置和成员信息。",
-        "operationId": "incidentWarRoomDetail",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/DeleteWarRoomRequest"
+              },
               "example": {
-                "chat_id": "oc_a0553eda9014c2de1b3a8f75b4e0c000",
+                "incident_id": "69da451ef77b1b51f40e83ee",
                 "integration_id": 2490562293131
-              },
-              "schema": {
-                "$ref": "#/components/schemas/GetWarRoomDetailRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/incident/war-room/detail": {
+      "post": {
+        "operationId": "incidentWarRoomDetail",
+        "summary": "获取战情室详情",
+        "description": "从 IM 平台读取作战室群组当前的名称和加入链接。",
+        "tags": [
+          "On-call/故障管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障查看**或**故障管理**或**协作空间查看**（`on-call`） |\n\n## 使用说明\n\n- 支持飞书、钉钉、企业微信和 Slack IM 集成；其他集成返回 `InvalidParameter`。\n- 如果 IM 平台查询失败（例如群组已在 Flashduty 之外解散），请求仍然成功，所有字段均为空字符串。",
+          "href": "/zh/api-reference/on-call/incidents/incident-war-room-detail",
+          "metadata": {
+            "sidebarTitle": "获取战情室详情"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "chat_id": "oc_a0553eda9014c2de1b3a8f75b4e0c000",
-                    "chat_name": "Incident #0E83EE war room",
-                    "share_link": ""
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/WarRoom"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "chat_id": "oc_a0553eda9014c2de1b3a8f75b4e0c000",
+                    "chat_name": "Incident #0E83EE war room",
+                    "share_link": ""
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -44272,6 +45760,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -44279,64 +45770,77 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "获取战情室详情",
-        "tags": [
-          "On-call/故障管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障查看**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/incidents/incident-war-room-detail",
-          "metadata": {
-            "sidebarTitle": "获取战情室详情"
-          }
-        }
-      }
-    },
-    "/incident/war-room/list": {
-      "post": {
-        "description": "查询故障关联的所有战情室。",
-        "operationId": "incidentWarRoomList",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {
-                "incident_id": "69da451ef77b1b51f40e83ee"
-              },
               "schema": {
-                "$ref": "#/components/schemas/ListWarRoomsRequest"
+                "$ref": "#/components/schemas/GetWarRoomDetailRequest"
+              },
+              "example": {
+                "integration_id": 2490562293131,
+                "chat_id": "oc_a0553eda9014c2de1b3a8f75b4e0c000"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/incident/war-room/list": {
+      "post": {
+        "operationId": "incidentWarRoomList",
+        "summary": "查询战情室列表",
+        "description": "查询故障关联的 IM 作战室群组。",
+        "tags": [
+          "On-call/故障管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障查看**或**故障管理**或**协作空间查看**或**协作空间管理**（`on-call`） |\n\n## 使用说明\n\n- 所属 IM 集成已禁用或已删除的作战室仍会返回，并将 `integration_unavailable` 置为 `true`。\n- 可将 `chat_id` 和 `integration_id` 传给 `POST /incident/war-room/detail`，读取群组当前名称和加入链接。",
+          "href": "/zh/api-reference/on-call/incidents/incident-war-room-list",
+          "metadata": {
+            "sidebarTitle": "查询战情室列表"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "items": []
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/ListWarRoomsResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "items": [
+                      {
+                        "account_id": 2451002751131,
+                        "integration_id": 2490562293131,
+                        "created_by": 2476444212131,
+                        "chat_id": "oc_a0553eda9014c2de1b3a8f75b4e0c000",
+                        "incident_id": "69da451ef77b1b51f40e83ee",
+                        "status": "enabled",
+                        "created_at": 1775972300,
+                        "plugin_type": "feishu_app",
+                        "chat_name": "Incident #0E83EE war room"
+                      }
+                    ]
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -44344,6 +45848,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -44351,107 +45858,95 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "查询战情室列表",
-        "tags": [
-          "On-call/故障管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障查看**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/incidents/incident-war-room-list",
-          "metadata": {
-            "sidebarTitle": "查询战情室列表"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ListWarRoomsRequest"
+              },
+              "example": {
+                "incident_id": "69da451ef77b1b51f40e83ee"
+              }
+            }
           }
         }
       }
     },
     "/incident/work-item/assignees/reset": {
       "post": {
-        "description": "整体替换跟进事项的负责人集合。",
         "operationId": "incidentWorkItemResetAssignees",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "assignee_ids": [
-                  3790925372131,
-                  5068740052131
-                ],
-                "version": 2,
-                "work_item_id": "wi_9fK2mNqRtVwXyZaBcDeFgH"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ResetWorkItemAssigneesRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "重置跟进事项负责人",
+        "description": "整体替换跟进事项的负责人集合。",
+        "tags": [
+          "On-call/故障管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 需要 On-call Pro 许可。\n- 整体替换负责人集合。传 `assignees` 或旧版 `assignee_ids`（二选一）；两者都不传会报错，传 `[]` 或 `null` 会清空所有负责人。\n- 人员负责人须为已能查看该故障或复盘的活跃成员 —— 指派不会授予访问权限。\n- 仅新添加的人员负责人会收到通知，移除不会通知。新指派 `ai_sre` 会为该事项启动一个 AI SRE 会话。\n- 负责人集合未发生变化时，`version` 不会递增。\n- 乐观锁 —— `version` 必须等于事项当前版本；不一致时返回 `RequestLocked`（HTTP 423），请重新读取事项后重试。\n- 调用方须拥有事项锚点的编辑权限：已绑定复盘时为该复盘，否则为故障。\n- `follow_up` 事项仅在其故障已关闭时可修改。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "href": "/zh/api-reference/on-call/incidents/incident-work-item-reset-assignees",
+          "metadata": {
+            "sidebarTitle": "重置跟进事项负责人"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/WorkItemMutationResult"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01J8XQ3E5Z7JM2NTFQ5YJ8P9R4",
                   "data": {
-                    "added_assignee_ids": [
-                      5068740052131
-                    ],
                     "item": {
+                      "work_item_id": "wi_9fK2mNqRtVwXyZaBcDeFgH",
+                      "item_type": "action",
+                      "incident_id": "6a5f1e28807515413b384bce",
+                      "title": "Roll back the v2.14 deployment on web-server-01 and web-server-02",
+                      "description": "CPU saturation started right after the v2.14 rollout; roll back and watch the error rate.",
+                      "status": "in_progress",
+                      "priority": "high",
+                      "source_kind": "native",
+                      "version": 3,
                       "assignee_ids": [
                         3790925372131,
-                        4756301322131,
                         5068740052131
                       ],
                       "assignees": [
                         {
-                          "id": 3790925372131,
-                          "type": "person"
-                        },
-                        {
-                          "id": 4756301322131,
-                          "type": "person"
+                          "type": "person",
+                          "id": 3790925372131
                         },
                         {
-                          "id": 5068740052131,
-                          "type": "person"
+                          "type": "person",
+                          "id": 5068740052131
                         }
                       ],
-                      "created_at_seconds": 1785495329,
-                      "created_by": 5329873302131,
-                      "incident_id": "6a5f1e28807515413b384bce",
-                      "item_type": "follow_up",
-                      "post_mortem_id": "51d65cd9525c369379ba471b5512df63",
-                      "source_kind": "native",
-                      "status": "done",
-                      "title": "Follow-ups assigned to Bowen and Weili",
-                      "updated_at_seconds": 1785496384,
+                      "created_by": 3790925372131,
                       "updated_by": 3790925372131,
-                      "version": 2,
-                      "work_item_id": "wi_68MHnkWBiyjrh6uhkxUyiZ"
+                      "created_at_seconds": 1785496400,
+                      "updated_at_seconds": 1785497000
                     },
-                    "removed_assignee_ids": [
-                      4756301322131
+                    "added_assignee_ids": [
+                      5068740052131
                     ]
-                  },
-                  "request_id": "01J8XQ3E5Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/WorkItemMutationResult"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -44459,6 +45954,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -44466,99 +45964,92 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "重置跟进事项负责人",
-        "tags": [
-          "On-call/故障管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障管理**（`on-call`） |\n\n## 使用说明\n\n- 需要 On-call Pro 许可。\n- 整体替换负责人集合 —— 空数组表示清空所有负责人。\n- 使用 `assignees` 或旧版 `assignee_ids`。两者同时出现会报错。`ai_sre` 条目不带 `id`。\n- 仅新添加的负责人会收到通知；移除不通知。\n- 已审计 —— 变更会记录到审计日志。",
-          "href": "/zh/api-reference/on-call/incidents/incident-work-item-reset-assignees",
-          "metadata": {
-            "sidebarTitle": "重置跟进事项负责人"
-          }
-        }
-      }
-    },
-    "/incident/work-item/complete": {
-      "post": {
-        "description": "通过设置客户端自定义的目标状态，将跟进事项标记为完成。",
-        "operationId": "incidentWorkItemComplete",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ResetWorkItemAssigneesRequest"
+              },
               "example": {
-                "idempotency_key": "complete-wi-20260731-0001",
-                "target_status": "done",
+                "work_item_id": "wi_9fK2mNqRtVwXyZaBcDeFgH",
                 "version": 2,
-                "work_item_id": "wi_9fK2mNqRtVwXyZaBcDeFgH"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/CompleteWorkItemRequest"
+                "assignee_ids": [
+                  3790925372131,
+                  5068740052131
+                ]
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/incident/work-item/complete": {
+      "post": {
+        "operationId": "incidentWorkItemComplete",
+        "summary": "完成跟进事项",
+        "description": "将跟进事项标记为已完成；仅当前负责人可以操作。",
+        "tags": [
+          "On-call/故障管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 需要 On-call Pro 许可。\n- `target_status` 必须为 `done`。\n- 仅当前人员负责人可以完成事项（账户所有者和管理员不会被视为负责人）；指派给 AI SRE 的事项也可由处理它的 AI SRE 会话完成。调用方还须有该故障或复盘的查看权限。\n- `follow_up` 事项仅在其故障已关闭时可修改。\n- 用相同的 `idempotency_key` 重复调用会返回该事项并标记 `idempotent_replay: true`。\n- 乐观锁 —— `version` 必须等于事项当前版本；不一致时返回 `RequestLocked`（HTTP 423），请重新读取事项后重试。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "href": "/zh/api-reference/on-call/incidents/incident-work-item-complete",
+          "metadata": {
+            "sidebarTitle": "完成跟进事项"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "item": {
-                      "assignee_ids": [
-                        3790925372131,
-                        4756301322131,
-                        5068740052131
-                      ],
-                      "assignees": [
-                        {
-                          "id": 3790925372131,
-                          "type": "person"
-                        },
-                        {
-                          "id": 4756301322131,
-                          "type": "person"
-                        },
-                        {
-                          "id": 5068740052131,
-                          "type": "person"
-                        }
-                      ],
-                      "created_at_seconds": 1785495329,
-                      "created_by": 5329873302131,
-                      "incident_id": "6a5f1e28807515413b384bce",
-                      "item_type": "follow_up",
-                      "post_mortem_id": "51d65cd9525c369379ba471b5512df63",
-                      "source_kind": "native",
-                      "status": "done",
-                      "title": "Follow-ups assigned to Bowen and Weili",
-                      "updated_at_seconds": 1785496384,
-                      "updated_by": 3790925372131,
-                      "version": 2,
-                      "work_item_id": "wi_68MHnkWBiyjrh6uhkxUyiZ"
-                    }
-                  },
-                  "request_id": "01J8XQ3E5Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/WorkItemMutationResult"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01J8XQ3E5Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "item": {
+                      "work_item_id": "wi_9fK2mNqRtVwXyZaBcDeFgH",
+                      "item_type": "action",
+                      "incident_id": "6a5f1e28807515413b384bce",
+                      "title": "Roll back the v2.14 deployment on web-server-01 and web-server-02",
+                      "description": "CPU saturation started right after the v2.14 rollout; roll back and watch the error rate.",
+                      "status": "done",
+                      "priority": "high",
+                      "source_kind": "native",
+                      "version": 3,
+                      "assignee_ids": [
+                        3790925372131
+                      ],
+                      "assignees": [
+                        {
+                          "type": "person",
+                          "id": 3790925372131
+                        }
+                      ],
+                      "created_by": 3790925372131,
+                      "updated_by": 3790925372131,
+                      "created_at_seconds": 1785496400,
+                      "updated_at_seconds": 1785497600
+                    }
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -44566,6 +46057,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -44573,99 +46067,93 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "完成跟进事项",
-        "tags": [
-          "On-call/故障管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障管理**（`on-call`） |\n\n## 使用说明\n\n- 需要 On-call Pro 许可。\n- 仅当前负责人可以完成跟进事项。\n- `target_status` 为客户端自定义字符串 —— 没有固定状态机。\n- 相同 `idempotency_key` 搭配相同 `target_status` 会幂等重放；相同键搭配不同 `target_status` 将返回错误。\n- 已审计 —— 变更会记录到审计日志。",
-          "href": "/zh/api-reference/on-call/incidents/incident-work-item-complete",
-          "metadata": {
-            "sidebarTitle": "完成跟进事项"
-          }
-        }
-      }
-    },
-    "/incident/work-item/convert": {
-      "post": {
-        "description": "将故障行动项原地转化为故障复盘后续行动。",
-        "operationId": "incidentWorkItemConvert",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CompleteWorkItemRequest"
+              },
               "example": {
-                "idempotency_key": "convert-wi-20260731-0001",
-                "target_status": "open",
+                "work_item_id": "wi_9fK2mNqRtVwXyZaBcDeFgH",
                 "version": 2,
-                "work_item_id": "wi_9fK2mNqRtVwXyZaBcDeFgH"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ConvertWorkItemRequest"
+                "target_status": "done",
+                "idempotency_key": "complete-wi-20260731-0001"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/incident/work-item/convert": {
+      "post": {
+        "operationId": "incidentWorkItemConvert",
+        "summary": "转化跟进事项为复盘后续行动",
+        "description": "将故障行动项原地转化为故障复盘后续行动。",
+        "tags": [
+          "On-call/故障管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 需要 On-call Pro 许可。\n- 将 `action` 就地转为复盘 `follow_up` —— `work_item_id` 不变。\n- 对已是 `follow_up` 的事项调用不会做任何修改，并返回 `idempotent_replay: true`。\n- 若故障已有复盘，事项会绑定到该复盘，此时需要该复盘的编辑权限；否则可稍后通过 `POST /incident/work-item/post-mortem/bind` 绑定。\n- 调用方须拥有事项锚点的编辑权限：已绑定复盘时为该复盘，否则为故障。\n- 乐观锁 —— `version` 必须等于事项当前版本；不一致时返回 `RequestLocked`（HTTP 423），请重新读取事项后重试。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "href": "/zh/api-reference/on-call/incidents/incident-work-item-convert",
+          "metadata": {
+            "sidebarTitle": "转化跟进事项为复盘后续行动"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "item": {
-                      "assignee_ids": [
-                        3790925372131,
-                        4756301322131,
-                        5068740052131
-                      ],
-                      "assignees": [
-                        {
-                          "id": 3790925372131,
-                          "type": "person"
-                        },
-                        {
-                          "id": 4756301322131,
-                          "type": "person"
-                        },
-                        {
-                          "id": 5068740052131,
-                          "type": "person"
-                        }
-                      ],
-                      "created_at_seconds": 1785495329,
-                      "created_by": 5329873302131,
-                      "incident_id": "6a5f1e28807515413b384bce",
-                      "item_type": "follow_up",
-                      "post_mortem_id": "51d65cd9525c369379ba471b5512df63",
-                      "source_kind": "native",
-                      "status": "done",
-                      "title": "Follow-ups assigned to Bowen and Weili",
-                      "updated_at_seconds": 1785496384,
-                      "updated_by": 3790925372131,
-                      "version": 2,
-                      "work_item_id": "wi_68MHnkWBiyjrh6uhkxUyiZ"
-                    }
-                  },
-                  "request_id": "01J8XQ3E5Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/WorkItemMutationResult"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01J8XQ3E5Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "item": {
+                      "work_item_id": "wi_9fK2mNqRtVwXyZaBcDeFgH",
+                      "item_type": "follow_up",
+                      "incident_id": "6a5f1e28807515413b384bce",
+                      "post_mortem_id": "51d65cd9525c369379ba471b5512df63",
+                      "title": "Roll back the v2.14 deployment on web-server-01 and web-server-02",
+                      "description": "CPU saturation started right after the v2.14 rollout; roll back and watch the error rate.",
+                      "status": "open",
+                      "priority": "high",
+                      "source_kind": "native",
+                      "version": 3,
+                      "assignee_ids": [
+                        3790925372131
+                      ],
+                      "assignees": [
+                        {
+                          "type": "person",
+                          "id": 3790925372131
+                        }
+                      ],
+                      "created_by": 3790925372131,
+                      "updated_by": 3790925372131,
+                      "converted_by": 3790925372131,
+                      "converted_at_seconds": 1785497600,
+                      "created_at_seconds": 1785496400,
+                      "updated_at_seconds": 1785497600
+                    }
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -44673,6 +46161,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -44680,97 +46171,93 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "转化跟进事项为复盘后续行动",
-        "tags": [
-          "On-call/故障管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障管理**（`on-call`） |\n\n## 使用说明\n\n- 需要 On-call Pro 许可。\n- 将 `action` 事项原地转化为复盘 `follow_up` —— `work_item_id` 不变。\n- 转化已是 `follow_up` 的事项时返回 `idempotent_replay: true`。\n- 如果故障已存在复盘，转化后的事项会自动绑定到该复盘。\n- 已审计 —— 变更会记录到审计日志。",
-          "href": "/zh/api-reference/on-call/incidents/incident-work-item-convert",
-          "metadata": {
-            "sidebarTitle": "转化跟进事项为复盘后续行动"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ConvertWorkItemRequest"
+              },
+              "example": {
+                "work_item_id": "wi_9fK2mNqRtVwXyZaBcDeFgH",
+                "version": 2,
+                "target_status": "open",
+                "idempotency_key": "convert-wi-20260731-0001"
+              }
+            }
           }
         }
       }
     },
     "/incident/work-item/create": {
       "post": {
-        "description": "在活动故障上创建行动项，或在其故障复盘上创建后续行动。",
         "operationId": "incidentWorkItemCreate",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "assignee_ids": [
-                  3790925372131
-                ],
-                "description": "CPU saturation started right after the v2.14 rollout; roll back and watch the error rate.",
-                "idempotency_key": "create-wi-20260731-0001",
-                "incident_id": "6a5f1e28807515413b384bce",
-                "item_type": "action",
-                "priority": "high",
-                "status": "open",
-                "title": "Roll back the v2.14 deployment on web-server-01"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/CreateWorkItemRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "创建跟进事项",
+        "description": "在未关闭的故障上创建行动项，或在已关闭的故障上创建后续行动。",
+        "tags": [
+          "On-call/故障管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 需要 On-call Pro 许可。\n- `action`：故障不能已关闭，调用方须有该故障的编辑权限，且不得设置 `post_mortem_id`。\n- `follow_up`：故障必须已关闭。传 `post_mortem_id` 时，调用方须有该复盘的编辑权限，且故障须已关联到该复盘；不传时，调用方须有故障的编辑权限，若故障已有复盘则服务端自动绑定，否则事项保持未绑定，直到创建复盘。\n- `assignees`（每项为 `{type, id?}`，`type` 取 `person` 或 `ai_sre`，`ai_sre` 不带 `id`）与旧版 `assignee_ids`（全部为 `person`）二选一，同时传入会报错。\n- 人员负责人须为已能查看该故障或复盘的活跃成员 —— 指派不会授予访问权限。\n- 新添加的人员负责人会收到通知；指派 `ai_sre` 会启动一个 AI SRE 会话来处理该事项。\n- 同一调用方用相同 `idempotency_key` 重试时，返回原事项并标记 `idempotent_replay: true`；若原事项已被删除，返回 `RequestLocked`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "href": "/zh/api-reference/on-call/incidents/incident-work-item-create",
+          "metadata": {
+            "sidebarTitle": "创建跟进事项"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/WorkItemCreateResult"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01J8XQ3E5Z7JM2NTFQ5YJ8P9R4",
                   "data": {
-                    "added_assignee_ids": [
-                      3790925372131
-                    ],
                     "item": {
+                      "work_item_id": "wi_9fK2mNqRtVwXyZaBcDeFgH",
+                      "item_type": "action",
+                      "incident_id": "6a5f1e28807515413b384bce",
+                      "title": "Roll back the v2.14 deployment on web-server-01",
+                      "description": "CPU saturation started right after the v2.14 rollout; roll back and watch the error rate.",
+                      "status": "open",
+                      "priority": "high",
+                      "source_kind": "native",
+                      "version": 1,
                       "assignee_ids": [
                         3790925372131
                       ],
                       "assignees": [
                         {
-                          "id": 3790925372131,
-                          "type": "person"
+                          "type": "person",
+                          "id": 3790925372131
                         }
                       ],
-                      "created_at_seconds": 1785496400,
                       "created_by": 3790925372131,
-                      "incident_id": "6a5f1e28807515413b384bce",
-                      "item_type": "action",
-                      "source_kind": "native",
-                      "status": "open",
-                      "title": "Roll back the v2.14 deployment on web-server-01",
-                      "updated_at_seconds": 1785496400,
                       "updated_by": 3790925372131,
-                      "version": 1,
-                      "work_item_id": "wi_9fK2mNqRtVwXyZaBcDeFgH"
-                    }
-                  },
-                  "request_id": "01J8XQ3E5Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
+                      "created_at_seconds": 1785496400,
+                      "updated_at_seconds": 1785496400
                     },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/WorkItemCreateResult"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                    "added_assignee_ids": [
+                      3790925372131
+                    ]
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -44778,6 +46265,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -44785,63 +46275,71 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "创建跟进事项",
-        "tags": [
-          "On-call/故障管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障管理**（`on-call`） |\n\n## 使用说明\n\n- 需要 On-call Pro 许可。\n- `action` 锚定活动故障，且不得设置 `post_mortem_id`；`follow_up` 必须设置为关联到 `incident_id` 的故障复盘 ID。\n- 使用 `assignees`（`person` 带 `id`，或 `ai_sre` 不带 `id`），或使用旧版 `assignee_ids`（全部为 `person`）。两者同时出现会报错。\n- 人员负责人须为已能查看锚定故障或复盘的活跃成员 —— 指派不会授予访问权限。\n- 新添加的负责人会收到通知。\n- 以相同的（`creator`、`idempotency_key`）重试时，返回原事项并标记 `idempotent_replay: true`，不会创建重复事项。\n- 已审计 —— 变更会记录到审计日志。",
-          "href": "/zh/api-reference/on-call/incidents/incident-work-item-create",
-          "metadata": {
-            "sidebarTitle": "创建跟进事项"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CreateWorkItemRequest"
+              },
+              "example": {
+                "item_type": "action",
+                "title": "Roll back the v2.14 deployment on web-server-01",
+                "description": "CPU saturation started right after the v2.14 rollout; roll back and watch the error rate.",
+                "status": "open",
+                "priority": "high",
+                "incident_id": "6a5f1e28807515413b384bce",
+                "assignee_ids": [
+                  3790925372131
+                ],
+                "idempotency_key": "create-wi-20260731-0001"
+              }
+            }
           }
         }
       }
     },
     "/incident/work-item/delete": {
       "post": {
-        "description": "软删除跟进事项。",
         "operationId": "incidentWorkItemDelete",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "version": 2,
-                "work_item_id": "wi_9fK2mNqRtVwXyZaBcDeFgH"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/DeleteWorkItemRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "删除跟进事项",
+        "description": "软删除跟进事项，使其不再出现在事项列表中。",
+        "tags": [
+          "On-call/故障管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 需要 On-call Pro 许可。\n- 软删除 —— 事项不再出现在列表中，但数据会保留；其创建时使用的 `idempotency_key` 不能再复用。\n- 乐观锁 —— `version` 必须等于事项当前版本；不一致时返回 `RequestLocked`（HTTP 423），请重新读取事项后重试。\n- 调用方须拥有事项锚点的编辑权限：已绑定复盘时为该复盘，否则为故障。\n- `follow_up` 事项仅在其故障已关闭时可修改。\n- 成功时 `data` 为空对象。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "href": "/zh/api-reference/on-call/incidents/incident-work-item-delete",
+          "metadata": {
+            "sidebarTitle": "删除跟进事项"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01J8XQ3E5Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/WorkItemMutationResult"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01J8XQ3E5Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -44849,6 +46347,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -44856,124 +46357,125 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "删除跟进事项",
-        "tags": [
-          "On-call/故障管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障管理**（`on-call`） |\n\n## 使用说明\n\n- 需要 On-call Pro 许可。\n- 软删除 —— 事项不再出现在列表中，但数据仍保留。\n- 乐观锁 —— `version` 必须与事项当前版本一致；不一致返回冲突错误。\n- 已审计 —— 变更会记录到审计日志。",
-          "href": "/zh/api-reference/on-call/incidents/incident-work-item-delete",
-          "metadata": {
-            "sidebarTitle": "删除跟进事项"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/DeleteWorkItemRequest"
+              },
+              "example": {
+                "work_item_id": "wi_9fK2mNqRtVwXyZaBcDeFgH",
+                "version": 3
+              }
+            }
           }
         }
       }
     },
     "/incident/work-item/list": {
       "post": {
-        "description": "查询故障跟进事项（行动项与复盘后续行动），使用游标分页。",
         "operationId": "incidentWorkItemList",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "incident_id": "6a5f1e28807515413b384bce",
-                "limit": 50
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ListWorkItemRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "查询跟进事项列表",
+        "description": "以游标分页列出故障的跟进事项（行动项和复盘后续行动）。",
+        "tags": [
+          "On-call/故障管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- `incident_id`、`post_mortem_id`、`assignee_id` 或 `assignee_type` = `ai_sre` 至少提供一个。\n- 按 `incident_id` 或 `post_mortem_id` 过滤时，须有该故障或复盘的查看权限；按 `incident_id` 查询时，若调用方可查看该故障的复盘，也会返回绑定到该复盘的后续行动。\n- 仅按 `assignee_id` 查询时，调用方须为该成员本人，或账户所有者、管理员。未指定 `incident_id` 和 `post_mortem_id` 时，非所有者或管理员只能看到其有权查看的故障或复盘下的事项。\n- 按 `updated_at_seconds` 降序排列。将上一次响应中的 `next_cursor` 作为 `cursor` 传入，直到 `has_more` 为 false。",
+          "href": "/zh/api-reference/on-call/incidents/incident-work-item-list",
+          "metadata": {
+            "sidebarTitle": "查询跟进事项列表"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/WorkItemListResult"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01J8XQ3E5Z7JM2NTFQ5YJ8P9R4",
                   "data": {
-                    "has_more": true,
                     "items": [
                       {
+                        "work_item_id": "wi_68MHnkWBiyjrh6uhkxUyiZ",
+                        "item_type": "follow_up",
+                        "incident_id": "6a5f1e28807515413b384bce",
+                        "post_mortem_id": "51d65cd9525c369379ba471b5512df63",
+                        "title": "Add a saturation alert for the orders database pool",
+                        "status": "done",
+                        "priority": "medium",
+                        "source_kind": "native",
+                        "version": 3,
                         "assignee_ids": [
                           3790925372131,
-                          4756301322131,
                           5068740052131
                         ],
                         "assignees": [
                           {
-                            "id": 3790925372131,
-                            "type": "person"
-                          },
-                          {
-                            "id": 4756301322131,
-                            "type": "person"
+                            "type": "person",
+                            "id": 3790925372131
                           },
                           {
-                            "id": 5068740052131,
-                            "type": "person"
+                            "type": "person",
+                            "id": 5068740052131
                           }
                         ],
+                        "created_by": 4756301322131,
+                        "updated_by": 3790925372131,
+                        "converted_by": 4756301322131,
+                        "converted_at_seconds": 1785495900,
                         "created_at_seconds": 1785495329,
-                        "created_by": 5329873302131,
-                        "incident_id": "6a5f1e28807515413b384bce",
+                        "updated_at_seconds": 1785496384
+                      },
+                      {
+                        "work_item_id": "wi_dMRYTeZHivE5vf87PQEeFX",
                         "item_type": "follow_up",
+                        "incident_id": "6a5f1e28807515413b384bce",
                         "post_mortem_id": "51d65cd9525c369379ba471b5512df63",
+                        "title": "Document the cache TTL rollback procedure",
+                        "status": "open",
+                        "priority": "low",
                         "source_kind": "native",
-                        "status": "done",
-                        "title": "Follow-ups assigned to Bowen and Weili",
-                        "updated_at_seconds": 1785496384,
-                        "updated_by": 3790925372131,
                         "version": 2,
-                        "work_item_id": "wi_68MHnkWBiyjrh6uhkxUyiZ"
-                      },
-                      {
                         "assignee_ids": [
                           5068740052131
                         ],
                         "assignees": [
                           {
-                            "id": 5068740052131,
-                            "type": "person"
+                            "type": "person",
+                            "id": 5068740052131
                           }
                         ],
-                        "created_at_seconds": 1785495164,
                         "created_by": 3790925372131,
-                        "incident_id": "6a5f1e28807515413b384bce",
-                        "item_type": "follow_up",
-                        "post_mortem_id": "51d65cd9525c369379ba471b5512df63",
-                        "source_kind": "native",
-                        "status": "open",
-                        "title": "Check whether this to-do notifies Bowen",
-                        "updated_at_seconds": 1785495164,
                         "updated_by": 3790925372131,
-                        "version": 1,
-                        "work_item_id": "wi_dMRYTeZHivE5vf87PQEeFX"
+                        "converted_by": 3790925372131,
+                        "converted_at_seconds": 1785495200,
+                        "created_at_seconds": 1785495164,
+                        "updated_at_seconds": 1785495200
                       }
                     ],
-                    "next_cursor": "MTc4NTQ5NTE2NHx3aV9kTVJZVGVaSGl2RTV2Zjg3UFFFZUZY"
-                  },
-                  "request_id": "01J8XQ3E5Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/WorkItemListResult"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                    "next_cursor": "MTc4NTQ5NTIwMHx3aV9kTVJZVGVaSGl2RTV2Zjg3UFFFZUZY",
+                    "has_more": true
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -44981,6 +46483,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -44988,124 +46493,124 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "查询跟进事项列表",
-        "tags": [
-          "On-call/故障管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障查看**（`on-call`） |\n\n## 使用说明\n\n- `incident_id`、`post_mortem_id`、`assignee_id`，或 `assignee_type` 为 `ai_sre`，至少满足一个。\n- `assignee_type` 为 `ai_sre` 时返回指派给 AI SRE 的事项，可单独作为查询条件。\n- 按 `updated_at_seconds` 倒序的游标分页 —— 将上一次响应的 `next_cursor` 作为 `cursor` 传入，直到 `has_more` 为 false。\n- 按 `incident_id` 查询时，同时包含锚定在该故障复盘上的后续行动。\n- 仅按 `assignee_id` 查询时，须为本人或账户管理员。",
-          "href": "/zh/api-reference/on-call/incidents/incident-work-item-list",
-          "metadata": {
-            "sidebarTitle": "查询跟进事项列表"
-          }
-        }
-      }
-    },
-    "/incident/work-item/post-mortem/bind": {
-      "post": {
-        "description": "将故障下已转化但未绑定的后续行动批量绑定到故障复盘。",
-        "operationId": "incidentWorkItemBindPostMortem",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ListWorkItemRequest"
+              },
               "example": {
-                "idempotency_key": "bind-wi-20260731-0001",
                 "incident_id": "6a5f1e28807515413b384bce",
-                "post_mortem_id": "51d65cd9525c369379ba471b5512df63"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/BindWorkItemPostMortemRequest"
+                "limit": 2
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/incident/work-item/post-mortem/bind": {
+      "post": {
+        "operationId": "incidentWorkItemBindPostMortem",
+        "summary": "绑定跟进事项到复盘",
+        "description": "将故障下已转化但未绑定的后续行动批量绑定到故障复盘。",
+        "tags": [
+          "On-call/故障管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 需要 On-call Pro 许可。\n- 绑定该故障中所有由行动项转换而来、且尚未绑定任何复盘的事项。\n- 调用方须有该复盘的编辑权限，且 `incident_id` 必须已关联到该复盘。\n- `items` 为本次绑定的事项，可能为空；`next_cursor` 不返回，`has_more` 为 false。\n- 用相同的 `idempotency_key` 重试时，返回之前绑定的事项并标记 `idempotent_replay: true`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "href": "/zh/api-reference/on-call/incidents/incident-work-item-bind-post-mortem",
+          "metadata": {
+            "sidebarTitle": "绑定跟进事项到复盘"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/WorkItemListResult"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01J8XQ3E5Z7JM2NTFQ5YJ8P9R4",
                   "data": {
-                    "has_more": false,
                     "items": [
                       {
+                        "work_item_id": "wi_68MHnkWBiyjrh6uhkxUyiZ",
+                        "item_type": "follow_up",
+                        "incident_id": "6a5f1e28807515413b384bce",
+                        "post_mortem_id": "51d65cd9525c369379ba471b5512df63",
+                        "title": "Add a saturation alert for the orders database pool",
+                        "status": "done",
+                        "priority": "medium",
+                        "source_kind": "native",
+                        "version": 3,
                         "assignee_ids": [
                           3790925372131,
-                          4756301322131,
                           5068740052131
                         ],
                         "assignees": [
                           {
-                            "id": 3790925372131,
-                            "type": "person"
+                            "type": "person",
+                            "id": 3790925372131
                           },
                           {
-                            "id": 4756301322131,
-                            "type": "person"
-                          },
-                          {
-                            "id": 5068740052131,
-                            "type": "person"
+                            "type": "person",
+                            "id": 5068740052131
                           }
                         ],
+                        "created_by": 4756301322131,
+                        "updated_by": 3790925372131,
+                        "converted_by": 4756301322131,
+                        "converted_at_seconds": 1785495900,
                         "created_at_seconds": 1785495329,
-                        "created_by": 5329873302131,
-                        "incident_id": "6a5f1e28807515413b384bce",
+                        "updated_at_seconds": 1785496384
+                      },
+                      {
+                        "work_item_id": "wi_dMRYTeZHivE5vf87PQEeFX",
                         "item_type": "follow_up",
+                        "incident_id": "6a5f1e28807515413b384bce",
                         "post_mortem_id": "51d65cd9525c369379ba471b5512df63",
+                        "title": "Document the cache TTL rollback procedure",
+                        "status": "open",
+                        "priority": "low",
                         "source_kind": "native",
-                        "status": "done",
-                        "title": "Follow-ups assigned to Bowen and Weili",
-                        "updated_at_seconds": 1785496384,
-                        "updated_by": 3790925372131,
                         "version": 2,
-                        "work_item_id": "wi_68MHnkWBiyjrh6uhkxUyiZ"
-                      },
-                      {
                         "assignee_ids": [
                           5068740052131
                         ],
                         "assignees": [
                           {
-                            "id": 5068740052131,
-                            "type": "person"
+                            "type": "person",
+                            "id": 5068740052131
                           }
                         ],
-                        "created_at_seconds": 1785495164,
                         "created_by": 3790925372131,
-                        "incident_id": "6a5f1e28807515413b384bce",
-                        "item_type": "follow_up",
-                        "post_mortem_id": "51d65cd9525c369379ba471b5512df63",
-                        "source_kind": "native",
-                        "status": "open",
-                        "title": "Check whether this to-do notifies Bowen",
-                        "updated_at_seconds": 1785495164,
                         "updated_by": 3790925372131,
-                        "version": 1,
-                        "work_item_id": "wi_dMRYTeZHivE5vf87PQEeFX"
+                        "converted_by": 3790925372131,
+                        "converted_at_seconds": 1785495200,
+                        "created_at_seconds": 1785495164,
+                        "updated_at_seconds": 1785495200
                       }
-                    ]
-                  },
-                  "request_id": "01J8XQ3E5Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/WorkItemListResult"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                    ],
+                    "has_more": false
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -45113,6 +46618,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -45120,99 +46628,89 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "绑定跟进事项到复盘",
-        "tags": [
-          "On-call/故障管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障管理**（`on-call`） |\n\n## 使用说明\n\n- 需要 On-call Pro 许可。\n- 一次调用将该故障全部已转化但未绑定的后续行动绑定到指定复盘。\n- `items` 为本次新绑定的批次；不设置 `next_cursor` 和 `has_more`。\n- 通过 `idempotency_key` 幂等 —— 以相同键重试时重放原始结果。\n- 已审计 —— 变更会记录到审计日志。",
-          "href": "/zh/api-reference/on-call/incidents/incident-work-item-bind-post-mortem",
-          "metadata": {
-            "sidebarTitle": "绑定跟进事项到复盘"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/BindWorkItemPostMortemRequest"
+              },
+              "example": {
+                "post_mortem_id": "51d65cd9525c369379ba471b5512df63",
+                "incident_id": "6a5f1e28807515413b384bce",
+                "idempotency_key": "bind-wi-20260731-0001"
+              }
+            }
           }
         }
       }
     },
     "/incident/work-item/update": {
       "post": {
-        "description": "部分更新跟进事项的标题、描述、状态或优先级。",
         "operationId": "incidentWorkItemUpdate",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "status": "in_progress",
-                "title": "Roll back the v2.14 deployment on web-server-01 and web-server-02",
-                "version": 1,
-                "work_item_id": "wi_9fK2mNqRtVwXyZaBcDeFgH"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/UpdateWorkItemRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "更新跟进事项",
+        "description": "部分更新跟进事项的标题、描述、状态或优先级。",
+        "tags": [
+          "On-call/故障管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 需要 On-call Pro 许可。\n- 部分更新：未提供的字段以及传 `null` 的字段均保持不变。传 `\"\"` 可清空 `description` 或 `priority`；`title` 和 `status` 不能为空。\n- 乐观锁 —— `version` 必须等于事项当前版本；不一致时返回 `RequestLocked`（HTTP 423），请重新读取事项后重试。\n- 若没有任何字段发生变化，则直接返回当前事项，不校验也不递增 `version`。\n- 调用方须拥有事项锚点的编辑权限：已绑定复盘时为该复盘，否则为故障。\n- `follow_up` 事项仅在其故障已关闭时可修改。\n- 负责人、`item_type` 以及故障/复盘锚点不能在此修改 —— 请使用专用接口。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "href": "/zh/api-reference/on-call/incidents/incident-work-item-update",
+          "metadata": {
+            "sidebarTitle": "更新跟进事项"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "item": {
-                      "assignee_ids": [
-                        3790925372131,
-                        4756301322131,
-                        5068740052131
-                      ],
-                      "assignees": [
-                        {
-                          "id": 3790925372131,
-                          "type": "person"
-                        },
-                        {
-                          "id": 4756301322131,
-                          "type": "person"
-                        },
-                        {
-                          "id": 5068740052131,
-                          "type": "person"
-                        }
-                      ],
-                      "created_at_seconds": 1785495329,
-                      "created_by": 5329873302131,
-                      "incident_id": "6a5f1e28807515413b384bce",
-                      "item_type": "follow_up",
-                      "post_mortem_id": "51d65cd9525c369379ba471b5512df63",
-                      "source_kind": "native",
-                      "status": "done",
-                      "title": "Follow-ups assigned to Bowen and Weili",
-                      "updated_at_seconds": 1785496384,
-                      "updated_by": 3790925372131,
-                      "version": 2,
-                      "work_item_id": "wi_68MHnkWBiyjrh6uhkxUyiZ"
-                    }
-                  },
-                  "request_id": "01J8XQ3E5Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/WorkItemMutationResult"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01J8XQ3E5Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "item": {
+                      "work_item_id": "wi_9fK2mNqRtVwXyZaBcDeFgH",
+                      "item_type": "action",
+                      "incident_id": "6a5f1e28807515413b384bce",
+                      "title": "Roll back the v2.14 deployment on web-server-01 and web-server-02",
+                      "description": "CPU saturation started right after the v2.14 rollout; roll back and watch the error rate.",
+                      "status": "in_progress",
+                      "priority": "high",
+                      "source_kind": "native",
+                      "version": 2,
+                      "assignee_ids": [
+                        3790925372131
+                      ],
+                      "assignees": [
+                        {
+                          "type": "person",
+                          "id": 3790925372131
+                        }
+                      ],
+                      "created_by": 3790925372131,
+                      "updated_by": 3790925372131,
+                      "created_at_seconds": 1785496400,
+                      "updated_at_seconds": 1785496700
+                    }
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -45220,6 +46718,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -45227,95 +46728,92 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "更新跟进事项",
-        "tags": [
-          "On-call/故障管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障管理**（`on-call`） |\n\n## 使用说明\n\n- 需要 On-call Pro 许可。\n- 部分更新：未提供的字段保持不变；显式传 `null` 则清空该字段。\n- 乐观锁 —— `version` 必须与事项当前版本一致；不一致返回冲突错误。\n- 负责人、`item_type` 以及故障/复盘锚点不能在此修改 —— 请使用专用接口。\n- 已审计 —— 变更会记录到审计日志。",
-          "href": "/zh/api-reference/on-call/incidents/incident-work-item-update",
-          "metadata": {
-            "sidebarTitle": "更新跟进事项"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/UpdateWorkItemRequest"
+              },
+              "example": {
+                "work_item_id": "wi_9fK2mNqRtVwXyZaBcDeFgH",
+                "version": 1,
+                "title": "Roll back the v2.14 deployment on web-server-01 and web-server-02",
+                "status": "in_progress"
+              }
+            }
           }
         }
       }
     },
     "/insight/account": {
       "post": {
-        "description": "返回整个账户的聚合故障洞察指标。",
         "operationId": "insightByAccount",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "aggregate_unit": "day",
-                "end_time": 1712604800,
-                "severities": [
-                  "Critical",
-                  "Warning"
-                ],
-                "start_time": 1712000000
-              },
-              "schema": {
-                "$ref": "#/components/schemas/InsightQueryRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "查看账户级别洞察",
+        "description": "按时间桶返回整个账户的故障与告警指标汇总。",
+        "tags": [
+          "On-call/分析看板"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **分析看板查看**（`on-call`） |\n\n## 使用说明\n\n- 每个时间桶返回一行整个账户的汇总。`responder_ids` 和 `incident_ids` 不生效；如需按人员或按故障查看，请使用 `/insight/responder` 或 `/insight/incident/list`。\n- 故障按创建时间归入时间桶。结果按 `ts` 从新到旧排列；没有故障的时间桶（或维度取值）不会出现在结果中，缺行即为 0。`split_hours` 为 true 时，每个时间桶最多返回 3 行，每个 `hours` 取值一行。\n- `total_alert_cnt`、`total_alert_event_cnt` 和 `noise_reduction_pct` 只受时间范围、团队、协作空间和严重程度过滤影响；`query`、`labels`、`fields` 以及时长过滤只作用于故障指标。\n- 非账户所有者、非管理员的成员只能看到自己有权访问的协作空间的数据，其他协作空间会被静默排除。\n- `is_my_team` 为 true 时，`team_ids` 收窄为调用者所在的团队；调用者不属于任何团队时返回空结果。",
+          "href": "/zh/api-reference/on-call/analytics/insight-by-account",
+          "metadata": {
+            "sidebarTitle": "查看账户级别洞察"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/DimensionInsightResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "items": [
                       {
-                        "acknowledgement_pct": 100,
-                        "mean_seconds_to_ack": 1658854.5,
-                        "mean_seconds_to_close": 1874757,
-                        "noise_reduction_pct": 0,
-                        "total_alert_cnt": 0,
-                        "total_alert_event_cnt": 0,
-                        "total_engaged_seconds": 3317709,
+                        "ts": 1740844800,
                         "total_incident_cnt": 2,
                         "total_incidents_acknowledged": 2,
-                        "total_incidents_auto_closed": 0,
                         "total_incidents_closed": 2,
-                        "total_incidents_escalated": 0,
+                        "total_incidents_auto_closed": 0,
                         "total_incidents_manually_closed": 2,
-                        "total_incidents_manually_escalated": 0,
-                        "total_incidents_reassigned": 2,
                         "total_incidents_timeout_closed": 0,
+                        "total_incidents_escalated": 0,
+                        "total_incidents_manually_escalated": 0,
                         "total_incidents_timeout_escalated": 0,
+                        "total_incidents_reassigned": 2,
                         "total_interruptions": 3,
                         "total_notifications": 6,
+                        "total_engaged_seconds": 3317709,
                         "total_seconds_to_ack": 3317709,
                         "total_seconds_to_close": 3749514,
-                        "ts": 1740844800
+                        "mean_seconds_to_ack": 1658854.5,
+                        "mean_seconds_to_close": 1874757,
+                        "noise_reduction_pct": 0,
+                        "acknowledgement_pct": 100,
+                        "total_alert_cnt": 0,
+                        "total_alert_event_cnt": 0
                       }
                     ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/DimensionInsightResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -45323,6 +46821,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -45330,84 +46831,86 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "查看账户级别洞察",
-        "tags": [
-          "On-call/分析看板"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **分析看板查看**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/analytics/insight-by-account",
-          "metadata": {
-            "sidebarTitle": "查看账户级别洞察"
-          }
-        }
-      }
-    },
-    "/insight/alert/topk-by-label": {
-      "post": {
-        "description": "返回指定时间范围内按 `check` 或 `resource` 聚合的 Top-K 告警组。",
-        "operationId": "insightTopkAlertsByLabel",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/InsightQueryRequest"
+              },
               "example": {
+                "start_time": 1712000000,
                 "end_time": 1712604800,
-                "k": 10,
-                "label": "check",
-                "orderby": "total_alert_cnt",
-                "start_time": 1712000000
-              },
-              "schema": {
-                "$ref": "#/components/schemas/InsightTopkAlertByLabelRequest"
+                "aggregate_unit": "day",
+                "severities": [
+                  "Critical",
+                  "Warning"
+                ]
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/insight/alert/topk-by-label": {
+      "post": {
+        "operationId": "insightTopkAlertsByLabel",
+        "summary": "查看按 check/resource 聚合的 Top-K 告警",
+        "description": "返回指定时间范围内按 `check` 或 `resource` 聚合的 Top-K 告警组。",
+        "tags": [
+          "On-call/分析看板"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **分析看板查看**（`on-call`） |\n\n## 使用说明\n\n- 只有时间范围、`team_ids`、`channel_ids`、`severities`、`is_my_team` 和 `split_hours` 会影响结果；其他过滤字段以及 `aggregate_unit` 不生效。\n- 告警按小时粒度统计，实际时间范围按整点对齐。\n- `split_hours` 为 true 时，会分别对 `work`、`sleep`、`off` 各取前 `k` 条，最多返回 3 × `k` 行。\n- 非账户所有者、非管理员的成员只能看到自己有权访问的协作空间的数据，其他协作空间会被静默排除。",
+          "href": "/zh/api-reference/on-call/analytics/insight-topk-alerts-by-label",
+          "metadata": {
+            "sidebarTitle": "查看按 check/resource 聚合的 Top-K 告警"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "items": [
-                      {
-                        "label": "cpu-high",
-                        "total_alert_cnt": 312,
-                        "total_alert_event_cnt": 987
-                      },
-                      {
-                        "label": "disk-full",
-                        "total_alert_cnt": 178,
-                        "total_alert_event_cnt": 452
-                      },
-                      {
-                        "label": "memory-oom",
-                        "total_alert_cnt": 94,
-                        "total_alert_event_cnt": 231
-                      }
-                    ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/InsightAlertByLabelResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "items": [
+                      {
+                        "label": "cpu-high",
+                        "total_alert_cnt": 312,
+                        "total_alert_event_cnt": 987
+                      },
+                      {
+                        "label": "disk-full",
+                        "total_alert_cnt": 178,
+                        "total_alert_event_cnt": 452
+                      },
+                      {
+                        "label": "memory-oom",
+                        "total_alert_cnt": 94,
+                        "total_alert_event_cnt": 231
+                      }
+                    ]
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -45415,6 +46918,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -45422,96 +46928,95 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "查看按 check/resource 聚合的 Top-K 告警",
-        "tags": [
-          "On-call/分析看板"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **分析看板查看**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/analytics/insight-topk-alerts-by-label",
-          "metadata": {
-            "sidebarTitle": "查看按 check/resource 聚合的 Top-K 告警"
-          }
-        }
-      }
-    },
-    "/insight/channel": {
-      "post": {
-        "description": "返回按协作空间聚合的洞察指标。",
-        "operationId": "insightByChannel",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/InsightTopkAlertByLabelRequest"
+              },
               "example": {
-                "aggregate_unit": "day",
-                "channel_ids": [
-                  4321322010131
-                ],
+                "start_time": 1712000000,
                 "end_time": 1712604800,
-                "start_time": 1712000000
-              },
-              "schema": {
-                "$ref": "#/components/schemas/InsightQueryRequest"
+                "label": "check",
+                "k": 10,
+                "orderby": "total_alert_cnt"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/insight/channel": {
+      "post": {
+        "operationId": "insightByChannel",
+        "summary": "查看协作空间洞察",
+        "description": "按协作空间分组返回故障与告警指标，每个协作空间、每个时间桶一行。",
+        "tags": [
+          "On-call/分析看板"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **分析看板查看**（`on-call`） |\n\n## 使用说明\n\n- 每个协作空间、每个时间桶返回一行。`responder_ids` 和 `incident_ids` 不生效。\n- 故障按创建时间归入时间桶。结果按 `ts` 从新到旧排列；没有故障的时间桶（或维度取值）不会出现在结果中，缺行即为 0。`split_hours` 为 true 时，每个时间桶最多返回 3 行，每个 `hours` 取值一行。\n- `total_alert_cnt`、`total_alert_event_cnt` 和 `noise_reduction_pct` 只受时间范围、团队、协作空间和严重程度过滤影响；`query`、`labels`、`fields` 以及时长过滤只作用于故障指标。\n- 非账户所有者、非管理员的成员只能看到自己有权访问的协作空间的数据，其他协作空间会被静默排除。\n- `is_my_team` 为 true 时，`team_ids` 收窄为调用者所在的团队；调用者不属于任何团队时返回空结果。",
+          "href": "/zh/api-reference/on-call/analytics/insight-by-channel",
+          "metadata": {
+            "sidebarTitle": "查看协作空间洞察"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/DimensionInsightResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "items": [
                       {
-                        "acknowledgement_pct": 100,
+                        "ts": 1740844800,
                         "channel_id": 4321322010131,
                         "channel_name": "Production Alerts",
-                        "mean_seconds_to_ack": 1658854.5,
-                        "mean_seconds_to_close": 1874757,
-                        "noise_reduction_pct": 0,
-                        "total_alert_cnt": 0,
-                        "total_alert_event_cnt": 0,
-                        "total_engaged_seconds": 3317709,
                         "total_incident_cnt": 2,
                         "total_incidents_acknowledged": 2,
-                        "total_incidents_auto_closed": 0,
                         "total_incidents_closed": 2,
-                        "total_incidents_escalated": 0,
+                        "total_incidents_auto_closed": 0,
                         "total_incidents_manually_closed": 2,
-                        "total_incidents_manually_escalated": 0,
-                        "total_incidents_reassigned": 2,
                         "total_incidents_timeout_closed": 0,
+                        "total_incidents_escalated": 0,
+                        "total_incidents_manually_escalated": 0,
                         "total_incidents_timeout_escalated": 0,
+                        "total_incidents_reassigned": 2,
                         "total_interruptions": 3,
                         "total_notifications": 6,
+                        "total_engaged_seconds": 3317709,
                         "total_seconds_to_ack": 3317709,
                         "total_seconds_to_close": 3749514,
-                        "ts": 1740844800
+                        "mean_seconds_to_ack": 1658854.5,
+                        "mean_seconds_to_close": 1874757,
+                        "noise_reduction_pct": 0,
+                        "acknowledgement_pct": 100,
+                        "total_alert_cnt": 0,
+                        "total_alert_event_cnt": 0
                       }
                     ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/DimensionInsightResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -45519,6 +47024,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -45526,57 +47034,54 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "查看协作空间洞察",
-        "tags": [
-          "On-call/分析看板"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **分析看板查看**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/analytics/insight-by-channel",
-          "metadata": {
-            "sidebarTitle": "查看协作空间洞察"
-          }
-        }
-      }
-    },
-    "/insight/channel/export": {
-      "post": {
-        "description": "将协作空间维度洞察指标导出为 CSV 文件——每行一个协作空间（使用 `aggregate_unit`/`split_hours` 时按时间桶/小时桶拆分）。响应为 CSV 字节流（`Content-Disposition: attachment`），不是 JSON 响应包。`time_zone` 缺省为 UTC。无有效协作空间 ID 的行会被跳过。可用的 `export_fields` key：channel_id, channel_name, total_incident_cnt, total_incidents_acknowledged, total_incidents_closed, total_incidents_auto_closed, total_incidents_manually_closed, total_incidents_timeout_closed, total_incidents_escalated, total_incidents_manually_escalated, total_incidents_timeout_escalated, total_incidents_reassigned, total_interruptions, total_notifications, total_engaged_seconds, mean_seconds_to_ack, mean_seconds_to_close, noise_reduction_pct, acknowledgement_pct, total_alert_cnt, total_alert_event_cnt, hours。`hours` 列仅在 `split_hours` 为 true 时默认包含。为兼容起见，故障导出列的 key 也可传入，但导出为空列。",
-        "operationId": "insightChannelExport",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/InsightQueryRequest"
+              },
               "example": {
+                "start_time": 1712000000,
+                "end_time": 1712604800,
                 "channel_ids": [
                   4321322010131
                 ],
-                "end_time": 1712604800,
-                "severities": [
-                  "Critical",
-                  "Warning"
-                ],
-                "start_time": 1712000000
-              },
-              "schema": {
-                "$ref": "#/components/schemas/InsightQueryRequest"
+                "aggregate_unit": "day"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/insight/channel/export": {
+      "post": {
+        "operationId": "insightChannelExport",
+        "summary": "导出协作空间洞察",
+        "description": "将协作空间维度洞察指标导出为 CSV 文件，行与 `/insight/channel` 的返回一致。",
+        "tags": [
+          "On-call/分析看板"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **100 次/天**；**20 次/分钟**；**10 次/秒** |\n| 权限要求 | **分析看板查看**（`on-call`） |\n\n## 使用说明\n\n- 响应是 CSV 文件（`Content-Type: application/octet-stream`），不是 JSON 响应包。参数校验失败时，在写出任何 CSV 内容之前返回 JSON 错误。\n- 过滤参数与 `/insight/channel` 相同。没有协作空间 ID 的行的行会被跳过。文件中没有时间桶列，使用 `aggregate_unit` 时不同时间桶的行无法区分；如需按时间拆分，请每个时间桶单独导出一次。\n- `export_fields` 决定导出哪些列及其顺序：channel_id, channel_name, total_incident_cnt, total_incidents_acknowledged, total_incidents_closed, total_incidents_auto_closed, total_incidents_manually_closed, total_incidents_timeout_closed, total_incidents_escalated, total_incidents_manually_escalated, total_incidents_timeout_escalated, total_incidents_reassigned, total_interruptions, total_notifications, total_engaged_seconds, mean_seconds_to_ack, mean_seconds_to_close, noise_reduction_pct, acknowledgement_pct, total_alert_cnt, total_alert_event_cnt, hours。未知或重复的 key 会被拒绝。不传时导出全部列，其中 `hours` 列仅在 `split_hours` 为 true 时包含。\n- 为兼容起见，也接受故障快照类 key（progress, assigned_to, raw_assigned_to, escalate_rule_name, responders, raw_responders, ackers, owner_id, owner_name, creator_id, creator_name, closer_id, closer_name, snooze_status, snoozed_before, ever_muted, frequency, is_rare, alert_cnt, active_alert_cnt, alert_event_cnt, description, labels, fields），这些列导出为空。\n- 列名按语言本地化（依次取请求语言、成员语言、账户语言）。时间桶按 `time_zone` 切分（不传为 UTC）。",
+          "href": "/zh/api-reference/on-call/analytics/insight-channel-export",
+          "metadata": {
+            "sidebarTitle": "导出协作空间洞察"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/octet-stream": {
-                "example": "channel_id,channel_name,total_incident_cnt,total_incidents_closed\n4321322010131,Production Alerts,12,10\n",
                 "schema": {
-                  "description": "CSV 字节流（`Content-Type: application/octet-stream`，`Content-Disposition: attachment; filename=channel_export_yyyyMMdd_HHmmss.csv`）。首行为本地化列名。列默认为完整字段集，或由 `export_fields` 指定。",
+                  "type": "string",
                   "format": "binary",
-                  "type": "string"
-                }
+                  "description": "CSV 文件（`Content-Type: application/octet-stream`，`Content-Disposition: attachment; filename*=UTF-8''channel_export_yyyyMMdd_HHmmss.csv`）。第一行为本地化的列名。"
+                },
+                "example": "channel_id,channel_name,total_incident_cnt,total_incidents_closed\n4321322010131,Production Alerts,12,10\n"
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -45584,6 +47089,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -45591,62 +47099,57 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "导出协作空间洞察",
-        "tags": [
-          "On-call/分析看板"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **100 次/天**；**20 次/分钟**；**10 次/秒** |\n| 权限要求 | **分析看板查看**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/analytics/insight-channel-export",
-          "metadata": {
-            "sidebarTitle": "导出协作空间洞察"
-          }
-        }
-      }
-    },
-    "/insight/incident/export": {
-      "post": {
-        "description": "将过滤后的故障分析明细导出为 CSV 文件。响应为 CSV 字节流（`Content-Disposition: attachment`），不是 JSON 响应包。CSV 列名和格式化值优先使用请求语言，其次成员语言、账户语言。`time_zone` 缺省时依次回退到账户时区、`Asia/Shanghai`。最多导出 100,000 行。可用的 `export_fields` key：incident_id, title, severity, progress, channel_id, channel_name, team_id, team_name, created_at, alert_cnt, active_alert_cnt, alert_event_cnt, seconds_to_ack, seconds_to_close, closed_by, owner_id, owner_name, creator_id, creator_name, closer_id, closer_name, engaged_seconds, hours, notifications, interruptions, acknowledgements, ackers, assignments, reassignments, escalations, manual_escalations, timeout_escalations, assigned_to, raw_assigned_to, escalate_rule_name, responders, raw_responders, snooze_status, snoozed_before, ever_muted, frequency, is_rare, description, labels, fields。不传 `export_fields` 时导出全部列。",
-        "operationId": "insightIncidentExport",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/InsightQueryRequest"
+              },
               "example": {
-                "description_html_to_text": true,
+                "start_time": 1712000000,
                 "end_time": 1712604800,
-                "export_fields": [
-                  "incident_id",
-                  "title",
-                  "severity",
-                  "created_at",
-                  "seconds_to_close"
+                "channel_ids": [
+                  4321322010131
                 ],
                 "severities": [
                   "Critical",
                   "Warning"
-                ],
-                "start_time": 1712000000
-              },
-              "schema": {
-                "$ref": "#/components/schemas/InsightIncidentExportRequest"
+                ]
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/insight/incident/export": {
+      "post": {
+        "operationId": "insightIncidentExport",
+        "summary": "导出洞察故障",
+        "description": "将分析过滤条件命中的故障导出为 CSV 文件，每条故障一行。",
+        "tags": [
+          "On-call/分析看板"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **100 次/天**；**20 次/分钟**；**10 次/秒** |\n| 权限要求 | **分析看板查看**（`on-call`） |\n\n## 使用说明\n\n- 响应是 CSV 文件（`Content-Type: application/octet-stream`），不是 JSON 响应包。参数校验失败时，在写出任何 CSV 内容之前返回 JSON 错误。\n- 过滤条件与排序方式与 `/insight/incident/list` 相同。写出的行数超过 100,000 后停止导出。\n- `start_time` 会被推后到账户数据保留期内最早的日期；整个时间范围都早于该日期时请求会被拒绝。\n- `export_fields` 决定导出哪些列及其顺序：incident_id, title, severity, progress, channel_id, channel_name, team_id, team_name, created_at, alert_cnt, active_alert_cnt, alert_event_cnt, seconds_to_ack, seconds_to_close, closed_by, owner_id, owner_name, creator_id, creator_name, closer_id, closer_name, engaged_seconds, hours, notifications, interruptions, acknowledgements, ackers, assignments, reassignments, escalations, manual_escalations, timeout_escalations, assigned_to, raw_assigned_to, escalate_rule_name, responders, raw_responders, snooze_status, snoozed_before, ever_muted, frequency, is_rare, description, labels, fields。未知或重复的 key 会被拒绝；不传时导出除别名 `owner_id`、`creator_id`、`closer_id`、`snoozed_before`、`is_rare` 以外的全部列。\n- `description_html_to_text` 为 true 时去掉 `description` 列中的 HTML 标记。\n- 列名和格式化值依次使用请求语言、成员语言、账户语言。时间按 `time_zone` 渲染，未传时依次回退到账户时区、`Asia/Shanghai`。",
+          "href": "/zh/api-reference/on-call/analytics/insight-incident-export",
+          "metadata": {
+            "sidebarTitle": "导出洞察故障"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/octet-stream": {
-                "example": "incident_id,title,severity,created_at\n6a86b5d6f72de50ae1ce2ffb,CPU usage above 90%,Critical,2026-01-01 10:00:00 +0800 CST\n",
                 "schema": {
-                  "description": "CSV 字节流（`Content-Type: application/octet-stream`，`Content-Disposition: attachment; filename=incident_export_yyyyMMdd_HHmmss.csv`）。首行为本地化列名。列默认为完整故障字段集，或由 `export_fields` 指定。",
+                  "type": "string",
                   "format": "binary",
-                  "type": "string"
-                }
+                  "description": "CSV 文件（`Content-Type: application/octet-stream`，`Content-Disposition: attachment; filename*=UTF-8''incident_export_yyyyMMdd_HHmmss.csv`）。第一行为本地化的列名。"
+                },
+                "example": "incident_id,title,severity,created_at\n6a86b5d6f72de50ae1ce2ffb,CPU usage above 90%,Critical,2026-01-01 10:00:00 +0800 CST\n"
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -45654,6 +47157,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -45661,123 +47167,130 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "导出洞察故障",
-        "tags": [
-          "On-call/分析看板"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **100 次/天**；**20 次/分钟**；**10 次/秒** |\n| 权限要求 | **分析看板查看**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/analytics/insight-incident-export",
-          "metadata": {
-            "sidebarTitle": "导出洞察故障"
-          }
-        }
-      }
-    },
-    "/insight/incident/list": {
-      "post": {
-        "description": "返回用于分析看板的故障分页列表，包含每条故障的处理效能指标。",
-        "operationId": "insightIncidentList",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/InsightIncidentExportRequest"
+              },
               "example": {
+                "start_time": 1712000000,
                 "end_time": 1712604800,
-                "limit": 20,
-                "p": 1,
                 "severities": [
-                  "Critical"
+                  "Critical",
+                  "Warning"
                 ],
-                "start_time": 1712000000
-              },
-              "schema": {
-                "$ref": "#/components/schemas/InsightIncidentListRequest"
+                "export_fields": [
+                  "incident_id",
+                  "title",
+                  "severity",
+                  "created_at",
+                  "seconds_to_close"
+                ],
+                "description_html_to_text": true
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/insight/incident/list": {
+      "post": {
+        "operationId": "insightIncidentList",
+        "summary": "查询洞察故障列表",
+        "description": "返回用于分析看板的故障分页列表，包含每条故障的处理效能指标。",
+        "tags": [
+          "On-call/分析看板"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **分析看板查看**（`on-call`） |\n\n## 使用说明\n\n- 默认按故障创建时间从新到旧排序（`asc: true` 为从旧到新）。\n- 可用 `p` + `limit` 翻页（最多可取到第 10,000 条），更深的翻页请把上一页返回的 `search_after_ctx` 传回。传入 `search_after_ctx` 时，`total` 只统计游标之后的故障数。\n- `responder_ids` 保留任一指定成员参与响应的故障。\n- 非账户所有者、非管理员的成员只能看到自己有权访问的协作空间的数据，其他协作空间会被静默排除。\n- `is_my_team` 为 true 时，`team_ids` 收窄为调用者所在的团队；调用者不属于任何团队时返回空结果。",
+          "href": "/zh/api-reference/on-call/analytics/insight-incident-list",
+          "metadata": {
+            "sidebarTitle": "查询洞察故障列表"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/InsightIncidentListResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
+                    "total": 2363,
                     "has_next_page": true,
+                    "search_after_ctx": "6a86b5d6f72de50ae1ce2ffb",
                     "items": [
                       {
-                        "acknowledgements": 1,
-                        "active_alert_cnt": 0,
-                        "alert_cnt": 3,
-                        "alert_event_cnt": 5,
-                        "assigned_to": {
-                          "assigned_at": 1787213270,
-                          "escalate_rule_id": "66138789904a9027583dbc4e",
-                          "escalate_rule_name": "On-call Policy",
-                          "id": "b8tyUoRvCv4wsPndFRpmNL",
-                          "layer_idx": 0,
-                          "type": "assign"
-                        },
-                        "assignments": 1,
+                        "incident_id": "6a86b5d6f72de50ae1ce2ffb",
+                        "title": "CPU usage above 90% on prod-web-01",
+                        "description": "CPU usage stayed above the threshold for 5 minutes",
+                        "team_id": 2477033058131,
+                        "team_name": "SRE Team",
                         "channel_id": 3047621227131,
                         "channel_name": "Production Alerts",
-                        "closed_by": "manually",
-                        "closer_id": 2477273692131,
-                        "closer_name": "alice",
+                        "progress": "Closed",
+                        "severity": "Critical",
                         "created_at": 1787213270,
+                        "alert_cnt": 3,
+                        "active_alert_cnt": 0,
+                        "alert_event_cnt": 5,
+                        "closed_by": "manually",
                         "creator_id": 2477273692131,
                         "creator_name": "alice",
-                        "description": "CPU usage stayed above the threshold for 5 minutes",
+                        "closer_id": 2477273692131,
+                        "closer_name": "alice",
+                        "seconds_to_ack": 14,
+                        "seconds_to_close": 1830,
                         "engaged_seconds": 1816,
-                        "escalations": 0,
                         "hours": "work",
-                        "incident_id": "6a86b5d6f72de50ae1ce2ffb",
-                        "interruptions": 1,
-                        "manual_escalations": 0,
-                        "notifications": 2,
-                        "progress": "Closed",
-                        "reassignments": 0,
                         "responders": [
                           {
-                            "acknowledged_at": 1787213284,
-                            "assigned_at": 1787213270,
-                            "email": "alice@example.com",
                             "person_id": 2477273692131,
-                            "person_name": "alice"
+                            "assigned_at": 1787213270,
+                            "acknowledged_at": 1787213284,
+                            "person_name": "alice",
+                            "email": "alice@example.com"
                           }
                         ],
-                        "seconds_to_ack": 14,
-                        "seconds_to_close": 1830,
-                        "severity": "Critical",
-                        "team_id": 2477033058131,
-                        "team_name": "SRE Team",
+                        "assigned_to": {
+                          "escalate_rule_id": "66138789904a9027583dbc4e",
+                          "layer_idx": 0,
+                          "type": "assign",
+                          "assigned_at": 1787213270,
+                          "id": "b8tyUoRvCv4wsPndFRpmNL",
+                          "escalate_rule_name": "On-call Policy"
+                        },
+                        "notifications": 2,
+                        "interruptions": 1,
+                        "assignments": 1,
+                        "reassignments": 0,
+                        "acknowledgements": 1,
+                        "escalations": 0,
                         "timeout_escalations": 0,
-                        "title": "CPU usage above 90% on prod-web-01"
+                        "manual_escalations": 0
                       }
-                    ],
-                    "search_after_ctx": "6a86b5d6f72de50ae1ce2ffb",
-                    "total": 2363
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/InsightIncidentListResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                    ]
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -45785,6 +47298,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -45792,87 +47308,88 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "查询洞察故障列表",
-        "tags": [
-          "On-call/分析看板"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **分析看板查看**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/analytics/insight-incident-list",
-          "metadata": {
-            "sidebarTitle": "查询洞察故障列表"
-          }
-        }
-      }
-    },
-    "/insight/responder": {
-      "post": {
-        "description": "返回按处理人员聚合的洞察指标。",
-        "operationId": "insightByResponder",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/InsightIncidentListRequest"
+              },
               "example": {
-                "aggregate_unit": "day",
+                "start_time": 1712000000,
                 "end_time": 1712604800,
-                "responder_ids": [
-                  3790925372131
-                ],
-                "start_time": 1712000000
-              },
-              "schema": {
-                "$ref": "#/components/schemas/InsightQueryRequest"
+                "p": 1,
+                "limit": 20,
+                "severities": [
+                  "Critical"
+                ]
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/insight/responder": {
+      "post": {
+        "operationId": "insightByResponder",
+        "summary": "查看处理人员洞察",
+        "description": "按响应人返回故障处理指标，每个响应人、每个时间桶一行。",
+        "tags": [
+          "On-call/分析看板"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **分析看板查看**（`on-call`） |\n\n## 使用说明\n\n- 每个响应人、每个时间桶返回一行；`responder_ids` 用于限定返回哪些响应人。`seconds_to_close_from`/`seconds_to_close_to` 和 `incident_ids` 不生效。\n- 故障按创建时间归入时间桶。结果按 `ts` 从新到旧排列；没有故障的时间桶（或维度取值）不会出现在结果中，缺行即为 0。`split_hours` 为 true 时，每个时间桶最多返回 3 行，每个 `hours` 取值一行。\n- 非账户所有者、非管理员的成员只能看到自己有权访问的协作空间的数据，其他协作空间会被静默排除。\n- `is_my_team` 为 true 时，`team_ids` 收窄为调用者所在的团队；调用者不属于任何团队时返回空结果。",
+          "href": "/zh/api-reference/on-call/analytics/insight-by-responder",
+          "metadata": {
+            "sidebarTitle": "查看处理人员洞察"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/ResponderInsightResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "items": [
                       {
-                        "acknowledgement_pct": 100,
-                        "mean_seconds_to_ack": 2265624,
+                        "ts": 1740844800,
                         "responder_id": 3790925372131,
                         "responder_name": "alice",
-                        "total_engaged_seconds": 10,
                         "total_incident_cnt": 1,
                         "total_incidents_acknowledged": 1,
-                        "total_incidents_escalated": 0,
-                        "total_incidents_manually_escalated": 0,
                         "total_incidents_reassigned": 0,
+                        "total_incidents_escalated": 0,
                         "total_incidents_timeout_escalated": 0,
+                        "total_incidents_manually_escalated": 0,
                         "total_interruptions": 1,
                         "total_notifications": 2,
+                        "total_engaged_seconds": 10,
                         "total_seconds_to_ack": 2265624,
-                        "ts": 1740844800
+                        "mean_seconds_to_ack": 2265624,
+                        "acknowledgement_pct": 100
                       }
                     ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/ResponderInsightResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -45880,64 +47397,64 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
-          },
-          "500": {
-            "$ref": "#/components/responses/ServerError"
-          }
-        },
-        "summary": "查看处理人员洞察",
-        "tags": [
-          "On-call/分析看板"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **分析看板查看**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/analytics/insight-by-responder",
-          "metadata": {
-            "sidebarTitle": "查看处理人员洞察"
+          },
+          "500": {
+            "$ref": "#/components/responses/ServerError"
           }
-        }
-      }
-    },
-    "/insight/responder/export": {
-      "post": {
-        "description": "将响应人维度洞察指标导出为 CSV 文件——每行一个响应人（使用 `aggregate_unit`/`split_hours` 时按时间桶/小时桶拆分）。响应为 CSV 字节流（`Content-Disposition: attachment`），不是 JSON 响应包。`time_zone` 缺省为 UTC。无有效响应人 ID 的行会被跳过。可用的 `export_fields` key：responder_id, responder_name, total_incident_cnt, total_incidents_acknowledged, total_incidents_reassigned, total_incidents_escalated, total_incidents_manually_escalated, total_incidents_timeout_escalated, total_interruptions, total_notifications, total_engaged_seconds, mean_seconds_to_ack, acknowledgement_pct, hours。`hours` 列仅在 `split_hours` 为 true 时默认包含。为兼容起见，故障导出列的 key 也可传入，但导出为空列。",
-        "operationId": "insightResponderExport",
+        },
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/InsightQueryRequest"
+              },
               "example": {
+                "start_time": 1712000000,
                 "end_time": 1712604800,
                 "responder_ids": [
                   3790925372131
                 ],
-                "severities": [
-                  "Critical",
-                  "Warning"
-                ],
-                "start_time": 1712000000
-              },
-              "schema": {
-                "$ref": "#/components/schemas/InsightQueryRequest"
+                "aggregate_unit": "day"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/insight/responder/export": {
+      "post": {
+        "operationId": "insightResponderExport",
+        "summary": "导出处理人员洞察",
+        "description": "将响应人维度洞察指标导出为 CSV 文件，行与 `/insight/responder` 的返回一致。",
+        "tags": [
+          "On-call/分析看板"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **100 次/天**；**20 次/分钟**；**10 次/秒** |\n| 权限要求 | **分析看板查看**（`on-call`） |\n\n## 使用说明\n\n- 响应是 CSV 文件（`Content-Type: application/octet-stream`），不是 JSON 响应包。参数校验失败时，在写出任何 CSV 内容之前返回 JSON 错误。\n- 过滤参数与 `/insight/responder` 相同。没有响应人 ID 的行的行会被跳过。文件中没有时间桶列，使用 `aggregate_unit` 时不同时间桶的行无法区分；如需按时间拆分，请每个时间桶单独导出一次。\n- `export_fields` 决定导出哪些列及其顺序：responder_id, responder_name, total_incident_cnt, total_incidents_acknowledged, total_incidents_reassigned, total_incidents_escalated, total_incidents_manually_escalated, total_incidents_timeout_escalated, total_interruptions, total_notifications, total_engaged_seconds, mean_seconds_to_ack, acknowledgement_pct, hours。未知或重复的 key 会被拒绝。不传时导出全部列，其中 `hours` 列仅在 `split_hours` 为 true 时包含。\n- 为兼容起见，也接受故障快照类 key（progress, assigned_to, raw_assigned_to, escalate_rule_name, responders, raw_responders, ackers, owner_id, owner_name, creator_id, creator_name, closer_id, closer_name, snooze_status, snoozed_before, ever_muted, frequency, is_rare, alert_cnt, active_alert_cnt, alert_event_cnt, description, labels, fields），这些列导出为空。\n- 列名按语言本地化（依次取请求语言、成员语言、账户语言）。时间桶按 `time_zone` 切分（不传为 UTC）。",
+          "href": "/zh/api-reference/on-call/analytics/insight-responder-export",
+          "metadata": {
+            "sidebarTitle": "导出处理人员洞察"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/octet-stream": {
-                "example": "responder_id,responder_name,total_incident_cnt,total_incidents_acknowledged\n3790925372131,alice,5,4\n",
                 "schema": {
-                  "description": "CSV 字节流（`Content-Type: application/octet-stream`，`Content-Disposition: attachment; filename=responder_export_yyyyMMdd_HHmmss.csv`）。首行为本地化列名。列默认为完整字段集，或由 `export_fields` 指定。",
+                  "type": "string",
                   "format": "binary",
-                  "type": "string"
-                }
+                  "description": "CSV 文件（`Content-Type: application/octet-stream`，`Content-Disposition: attachment; filename*=UTF-8''responder_export_yyyyMMdd_HHmmss.csv`）。第一行为本地化的列名。"
+                },
+                "example": "responder_id,responder_name,total_incident_cnt,total_incidents_acknowledged\n3790925372131,alice,5,4\n"
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -45945,6 +47462,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -45952,96 +47472,99 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "导出处理人员洞察",
-        "tags": [
-          "On-call/分析看板"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **100 次/天**；**20 次/分钟**；**10 次/秒** |\n| 权限要求 | **分析看板查看**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/analytics/insight-responder-export",
-          "metadata": {
-            "sidebarTitle": "导出处理人员洞察"
-          }
-        }
-      }
-    },
-    "/insight/team": {
-      "post": {
-        "description": "返回按团队聚合的洞察指标。",
-        "operationId": "insightByTeam",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/InsightQueryRequest"
+              },
               "example": {
-                "aggregate_unit": "day",
-                "end_time": 1712604800,
                 "start_time": 1712000000,
-                "team_ids": [
-                  4295771902131
+                "end_time": 1712604800,
+                "responder_ids": [
+                  3790925372131
+                ],
+                "severities": [
+                  "Critical",
+                  "Warning"
                 ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/InsightQueryRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/insight/team": {
+      "post": {
+        "operationId": "insightByTeam",
+        "summary": "查看团队洞察",
+        "description": "按团队分组返回故障与告警指标，每个团队、每个时间桶一行。",
+        "tags": [
+          "On-call/分析看板"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **分析看板查看**（`on-call`） |\n\n## 使用说明\n\n- 每个团队、每个时间桶返回一行。未归属团队的故障汇总为一行，该行没有 `team_id`。`responder_ids` 和 `incident_ids` 不生效。\n- 故障按创建时间归入时间桶。结果按 `ts` 从新到旧排列；没有故障的时间桶（或维度取值）不会出现在结果中，缺行即为 0。`split_hours` 为 true 时，每个时间桶最多返回 3 行，每个 `hours` 取值一行。\n- `total_alert_cnt`、`total_alert_event_cnt` 和 `noise_reduction_pct` 只受时间范围、团队、协作空间和严重程度过滤影响；`query`、`labels`、`fields` 以及时长过滤只作用于故障指标。\n- 非账户所有者、非管理员的成员只能看到自己有权访问的协作空间的数据，其他协作空间会被静默排除。\n- `is_my_team` 为 true 时，`team_ids` 收窄为调用者所在的团队；调用者不属于任何团队时返回空结果。",
+          "href": "/zh/api-reference/on-call/analytics/insight-by-team",
+          "metadata": {
+            "sidebarTitle": "查看团队洞察"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/DimensionInsightResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "items": [
                       {
-                        "acknowledgement_pct": 100,
-                        "mean_seconds_to_ack": 1658854.5,
-                        "mean_seconds_to_close": 1874757,
-                        "noise_reduction_pct": 0,
+                        "ts": 1740844800,
                         "team_id": 4295771902131,
                         "team_name": "SRE Team",
-                        "total_alert_cnt": 0,
-                        "total_alert_event_cnt": 0,
-                        "total_engaged_seconds": 3317709,
                         "total_incident_cnt": 2,
                         "total_incidents_acknowledged": 2,
-                        "total_incidents_auto_closed": 0,
                         "total_incidents_closed": 2,
-                        "total_incidents_escalated": 0,
+                        "total_incidents_auto_closed": 0,
                         "total_incidents_manually_closed": 2,
-                        "total_incidents_manually_escalated": 0,
-                        "total_incidents_reassigned": 2,
                         "total_incidents_timeout_closed": 0,
+                        "total_incidents_escalated": 0,
+                        "total_incidents_manually_escalated": 0,
                         "total_incidents_timeout_escalated": 0,
+                        "total_incidents_reassigned": 2,
                         "total_interruptions": 3,
                         "total_notifications": 6,
+                        "total_engaged_seconds": 3317709,
                         "total_seconds_to_ack": 3317709,
                         "total_seconds_to_close": 3749514,
-                        "ts": 1740844800
+                        "mean_seconds_to_ack": 1658854.5,
+                        "mean_seconds_to_close": 1874757,
+                        "noise_reduction_pct": 0,
+                        "acknowledgement_pct": 100,
+                        "total_alert_cnt": 0,
+                        "total_alert_event_cnt": 0
                       }
                     ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/DimensionInsightResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -46049,6 +47572,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -46056,57 +47582,54 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "查看团队洞察",
-        "tags": [
-          "On-call/分析看板"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **分析看板查看**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/analytics/insight-by-team",
-          "metadata": {
-            "sidebarTitle": "查看团队洞察"
-          }
-        }
-      }
-    },
-    "/insight/team/export": {
-      "post": {
-        "description": "将团队维度洞察指标导出为 CSV 文件——每行一个团队（使用 `aggregate_unit`/`split_hours` 时按时间桶/小时桶拆分）。响应为 CSV 字节流（`Content-Disposition: attachment`），不是 JSON 响应包。`time_zone` 缺省为 UTC。无有效团队 ID 的行会被跳过。可用的 `export_fields` key：team_id, team_name, total_incident_cnt, total_incidents_acknowledged, total_incidents_closed, total_incidents_auto_closed, total_incidents_manually_closed, total_incidents_timeout_closed, total_incidents_escalated, total_incidents_manually_escalated, total_incidents_timeout_escalated, total_incidents_reassigned, total_interruptions, total_notifications, total_engaged_seconds, mean_seconds_to_ack, mean_seconds_to_close, noise_reduction_pct, acknowledgement_pct, total_alert_cnt, total_alert_event_cnt, hours。`hours` 列仅在 `split_hours` 为 true 时默认包含。为兼容起见，故障导出列的 key 也可传入，但导出为空列。",
-        "operationId": "insightTeamExport",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/InsightQueryRequest"
+              },
               "example": {
-                "end_time": 1712604800,
-                "severities": [
-                  "Critical",
-                  "Warning"
-                ],
                 "start_time": 1712000000,
+                "end_time": 1712604800,
                 "team_ids": [
                   4295771902131
-                ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/InsightQueryRequest"
+                ],
+                "aggregate_unit": "day"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/insight/team/export": {
+      "post": {
+        "operationId": "insightTeamExport",
+        "summary": "导出团队洞察",
+        "description": "将团队维度洞察指标导出为 CSV 文件，行与 `/insight/team` 的返回一致。",
+        "tags": [
+          "On-call/分析看板"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **100 次/天**；**20 次/分钟**；**10 次/秒** |\n| 权限要求 | **分析看板查看**（`on-call`） |\n\n## 使用说明\n\n- 响应是 CSV 文件（`Content-Type: application/octet-stream`），不是 JSON 响应包。参数校验失败时，在写出任何 CSV 内容之前返回 JSON 错误。\n- 过滤参数与 `/insight/team` 相同。没有团队 ID 的行（未归属团队的故障）的行会被跳过。文件中没有时间桶列，使用 `aggregate_unit` 时不同时间桶的行无法区分；如需按时间拆分，请每个时间桶单独导出一次。\n- `export_fields` 决定导出哪些列及其顺序：team_id, team_name, total_incident_cnt, total_incidents_acknowledged, total_incidents_closed, total_incidents_auto_closed, total_incidents_manually_closed, total_incidents_timeout_closed, total_incidents_escalated, total_incidents_manually_escalated, total_incidents_timeout_escalated, total_incidents_reassigned, total_interruptions, total_notifications, total_engaged_seconds, mean_seconds_to_ack, mean_seconds_to_close, noise_reduction_pct, acknowledgement_pct, total_alert_cnt, total_alert_event_cnt, hours。未知或重复的 key 会被拒绝。不传时导出全部列，其中 `hours` 列仅在 `split_hours` 为 true 时包含。\n- 为兼容起见，也接受故障快照类 key（progress, assigned_to, raw_assigned_to, escalate_rule_name, responders, raw_responders, ackers, owner_id, owner_name, creator_id, creator_name, closer_id, closer_name, snooze_status, snoozed_before, ever_muted, frequency, is_rare, alert_cnt, active_alert_cnt, alert_event_cnt, description, labels, fields），这些列导出为空。\n- 列名按语言本地化（依次取请求语言、成员语言、账户语言）。时间桶按 `time_zone` 切分（不传为 UTC）。",
+          "href": "/zh/api-reference/on-call/analytics/insight-team-export",
+          "metadata": {
+            "sidebarTitle": "导出团队洞察"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/octet-stream": {
-                "example": "team_id,team_name,total_incident_cnt,total_incidents_closed\n4295771902131,SRE Team,12,10\n",
                 "schema": {
-                  "description": "CSV 字节流（`Content-Type: application/octet-stream`，`Content-Disposition: attachment; filename=team_export_yyyyMMdd_HHmmss.csv`）。首行为本地化列名。列默认为完整字段集，或由 `export_fields` 指定。",
+                  "type": "string",
                   "format": "binary",
-                  "type": "string"
-                }
+                  "description": "CSV 文件（`Content-Type: application/octet-stream`，`Content-Disposition: attachment; filename*=UTF-8''team_export_yyyyMMdd_HHmmss.csv`）。第一行为本地化的列名。"
+                },
+                "example": "team_id,team_name,total_incident_cnt,total_incidents_closed\n4295771902131,SRE Team,12,10\n"
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -46114,6 +47637,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -46121,62 +47647,70 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "导出团队洞察",
-        "tags": [
-          "On-call/分析看板"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **100 次/天**；**20 次/分钟**；**10 次/秒** |\n| 权限要求 | **分析看板查看**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/analytics/insight-team-export",
-          "metadata": {
-            "sidebarTitle": "导出团队洞察"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/InsightQueryRequest"
+              },
+              "example": {
+                "start_time": 1712000000,
+                "end_time": 1712604800,
+                "team_ids": [
+                  4295771902131
+                ],
+                "severities": [
+                  "Critical",
+                  "Warning"
+                ]
+              }
+            }
           }
         }
       }
     },
     "/member/delete": {
       "post": {
-        "description": "通过 ID、邮箱、手机号或名称从组织中移除成员。",
         "operationId": "memberDelete",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "member_id": 5068740052131
-              },
-              "schema": {
-                "$ref": "#/components/schemas/MemberDeleteRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "删除成员",
+        "description": "通过 ID、邮箱、手机号或名称从组织中移除成员。",
+        "tags": [
+          "平台/成员管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **成员管理**（`organization`） |\n\n## 使用说明\n\n- 使用任一查找字段定位成员；同时传多个时，按 `member_id`、`member_name`、`email`、`phone`、`ref_id` 的顺序取第一个非空字段。\n- 除非 `is_force` 为 true，成员仍属于某个团队、被分派策略直接指定或在值班表中时，调用返回 `400 ReferenceExist`，`data.refs` 列出每条引用。强制删除会跳过检查，且不会清理这些引用。\n- 删除为软删除：成员状态变为 `deleted`，释放其占用的 License 席位，并移除其单点登录身份关联。之后仍可通过 `POST /person/infos` 解析该成员。\n- 通过单点登录同步的成员，在单点登录配置将其设为不可编辑时无法删除，调用返回 `400`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "href": "/zh/api-reference/platform/members/member-delete",
+          "metadata": {
+            "sidebarTitle": "删除成员"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/MemberEmptyObject"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -46184,6 +47718,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -46191,39 +47728,58 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "删除成员",
-        "tags": [
-          "平台/成员管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **成员管理**（`organization`） |\n\n## 使用说明\n\n- 默认情况下（`is_force=false`），系统会检查该成员是否被其他资源引用（如分派策略、值班表等）。如果存在引用，接口将返回错误码 `ReferenceExist` 并在 `data.refs` 中返回引用列表。设置 `is_force=true` 可跳过引用检查，直接强制删除。\n- 通过 SSO 同步且 SSO 配置了成员不可编辑（`sso_user_non_editable=true`）的成员，无法通过此接口删除。需要先在 SSO 配置中关闭该限制。\n- 此操作会记录审计日志。",
-          "href": "/zh/api-reference/platform/members/member-delete",
-          "metadata": {
-            "sidebarTitle": "删除成员"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/MemberDeleteRequest"
+              },
+              "example": {
+                "member_id": 5068740052131
+              }
+            }
           }
         }
       }
     },
     "/member/info": {
       "post": {
-        "description": "返回当前凭据所属成员的完整资料。需要成员级凭据——以账户主体身份（如账户级 App Key）调用会被拒绝并返回 400。",
         "operationId": "memberInfo",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {},
-              "schema": {
-                "$ref": "#/components/schemas/MemberInfoRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "获取当前成员信息",
+        "description": "返回当前凭据所属成员的资料及其所在账户信息。",
+        "tags": [
+          "平台/成员管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 但对调用凭据有要求，见使用说明 |\n\n## 使用说明\n\n- 需要成员凭据；使用账户主体凭据调用会返回 `400 BadRequest`。账户主体请使用 `POST /account/info`。\n- `time_zone` 是成员自己的设置（空字符串表示跟随账户），`account_time_zone` 是账户的设置，`resolved_time_zone` 是实际用于展示时间的时区。",
+          "href": "/zh/api-reference/platform/members/member-info",
+          "metadata": {
+            "sidebarTitle": "获取当前成员信息"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/MemberInfoResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "account_avatar": "",
                     "account_email": "alice@example.com",
@@ -46246,28 +47802,12 @@
                     "member_name": "Alice",
                     "phone": "+86185****0300",
                     "phone_verified": true,
-                    "time_zone": "Asia/Shanghai"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/MemberInfoResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                    "time_zone": "Asia/Shanghai",
+                    "resolved_time_zone": "Asia/Shanghai"
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -46275,6 +47815,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -46282,67 +47825,60 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "获取当前成员信息",
-        "tags": [
-          "平台/成员管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 但凭据必须属于某个成员；以账户主体身份（如账户级 App Key）调用会被拒绝并返回 400 |",
-          "href": "/zh/api-reference/platform/members/member-info",
-          "metadata": {
-            "sidebarTitle": "获取当前成员信息"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/MemberInfoRequest"
+              },
+              "example": {}
+            }
           }
         }
       }
     },
     "/member/info/reset": {
       "post": {
-        "description": "通过成员标识定位成员，并重置指定资料字段。",
         "operationId": "memberResetInfo",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "member_id": 2476444212131,
-                "updates": {
-                  "locale": "zh-CN",
-                  "member_name": "Alice Chen",
-                  "time_zone": "Asia/Shanghai"
-                }
-              },
-              "schema": {
-                "$ref": "#/components/schemas/MemberResetInfoRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "重置成员信息",
+        "description": "通过成员标识定位成员，并重置指定资料字段。",
+        "tags": [
+          "平台/成员管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 使用 `member_id`、`member_name`、`email`、`phone` 或 `ref_id` 中任一字段定位成员；如果同时传多个字段，服务端按上述顺序匹配。\n- 调用者必须是账户主体、该成员本人或拥有 Admin 角色，否则返回 `403 AccessDenied`。\n- `updates` 承载要写入的新资料，支持 `member_name`、`password`、`phone`、`country_code`、`email`、`avatar`、`locale`、`time_zone`、`ref_id`。省略或为 `null` 的字段保持原值；`updates` 至少要带一个字段。\n- 新的 `member_name`、`email`、`phone` 不能已属于本账户其他成员，冲突时返回 `400`。修改后的 `email` 或 `phone` 会被标记为未验证，除非 `from` 为 `api` 且账户关闭了成员邀请。\n- `updates.time_zone` 传空字符串会清除成员自己的时区，使其跟随账户时区。\n- `updates.country_code` 为 ISO 3166-1 alpha-2 地区代码（如 \"CN\"、\"US\"）。它是独立可更新字段：无需同时传 `updates.phone`，即使手机号不变也会写入新的地区代码；显式传空字符串会被拒绝（400）。\n- 当 `updates.phone` 不带 \"+\" 前缀时，按 `updates.country_code` 作为地区提示解析；未传时依次回退到成员已存的地区代码、默认值 \"CN\"。\"86\" 等数字电话区号仅在解析场景兼容，存储值一律为 ISO 地区代码。\n- 顶层的 `country_code` 仅作为定位用 `phone` 的解析提示，不会被存储。\n- 各字段逐个写入；若后面的字段校验失败，同一次调用中已写入的字段不会回滚。\n- 通过单点登录同步的成员，在单点登录配置将其设为不可编辑时无法修改。\n- 同一账户内并发的资料更新或成员邀请可能返回 `429 RequestTooFrequently`，请稍后重试。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "href": "/zh/api-reference/platform/members/member-reset-info",
+          "metadata": {
+            "sidebarTitle": "重置成员信息"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/MemberEmptyObject"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -46350,6 +47886,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -46357,90 +47896,78 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "重置成员信息",
-        "tags": [
-          "平台/成员管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 使用 `member_id`、`member_name`、`email`、`phone` 或 `ref_id` 中任一字段定位成员；如果同时传多个字段，服务端按上述顺序匹配。\n- `updates.country_code` 为 ISO 3166-1 alpha-2 地区代码（如 \"CN\"、\"US\"）。它是独立可更新字段：无需同时传 `updates.phone`，即使手机号不变也会写入新的地区代码；显式传空字符串会被拒绝（400）。\n- 当 `updates.phone` 不带 \"+\" 前缀时，按 `updates.country_code` 作为地区提示解析；未传时依次回退到成员已存的地区代码、默认值 \"CN\"。\"86\" 等数字电话区号仅在解析场景兼容，存储值一律为 ISO 地区代码。\n- 顶层的 `country_code` 仅作为定位用 `phone` 的解析提示，不会被存储。\n- `updates` 承载要写入的新资料，支持 `member_name`、`password`、`phone`、`country_code`、`email`、`avatar`、`locale`、`time_zone`、`ref_id`。\n- 由 SSO 托管且不可编辑的成员不能通过此接口修改。\n- `updates` 至少要带一个字段；所有字段都不传的空对象会被拒绝。",
-          "href": "/zh/api-reference/platform/members/member-reset-info",
-          "metadata": {
-            "sidebarTitle": "重置成员信息"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/MemberResetInfoRequest"
+              },
+              "example": {
+                "member_id": 2476444212131,
+                "updates": {
+                  "member_name": "Alice Chen",
+                  "locale": "zh-CN",
+                  "time_zone": "Asia/Shanghai"
+                }
+              }
+            }
           }
         }
       }
     },
     "/member/invite": {
       "post": {
-        "description": "通过邮箱或手机号批量邀请新成员加入组织。",
         "operationId": "memberInvite",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "members": [
-                  {
-                    "email": "charlie@example.com",
-                    "locale": "en-US",
-                    "member_name": "Charlie",
-                    "role_ids": [
-                      6
-                    ],
-                    "time_zone": "Asia/Shanghai"
-                  },
-                  {
-                    "country_code": "CN",
-                    "locale": "zh-CN",
-                    "member_name": "Dave",
-                    "phone": "13800138000",
-                    "time_zone": "Asia/Shanghai"
-                  }
-                ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/MemberInviteRequest"
-              }
-            }
-          },
-          "required": true
-        },
-        "responses": {
-          "200": {
-            "content": {
-              "application/json": {
-                "example": {
-                  "data": {
-                    "items": [
-                      {
-                        "member_id": 5068740052131,
-                        "member_name": "Charlie"
-                      },
-                      {
-                        "member_id": 5068740052132,
-                        "member_name": "Dave"
-                      }
-                    ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
+        "summary": "邀请成员",
+        "description": "通过邮箱或手机号批量邀请新成员加入组织。",
+        "tags": [
+          "平台/成员管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **成员管理**（`organization`） |\n\n## 使用说明\n\n- 每个条目需要提供 `email`，或同时提供 `member_name` 和 `phone`。\n- 邮箱或手机号已属于本账户成员的条目会被静默跳过；`items` 只列出本次新建的成员，一个都没有创建时为 `null`。\n- 新成员以 `pending` 状态创建，并通过邮件或短信收到邀请。\n- 邮箱以小写存储。账户限制了成员邮箱域名时，不在白名单内的地址返回 `400`；同一请求内邮箱或手机号重复也返回 `400`。\n- `country_code` 必须是 ISO 3166-1 alpha-2 地区代码（如 \"CN\"）；写入前校验并统一转为大写，非法值返回 400。\n- 当成员的 `phone` 不带 \"+\" 前缀时，按该成员的 `country_code` 作为地区提示解析（未传时默认 \"CN\"）。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "href": "/zh/api-reference/platform/members/member-invite",
+          "metadata": {
+            "sidebarTitle": "邀请成员"
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "成功",
+            "content": {
+              "application/json": {
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/MemberInviteResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "items": [
+                      {
+                        "member_id": 5068740052131,
+                        "member_name": "Charlie"
+                      },
+                      {
+                        "member_id": 5068740052132,
+                        "member_name": "Dave"
+                      }
+                    ]
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -46448,6 +47975,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -46455,108 +47985,124 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "邀请成员",
-        "tags": [
-          "平台/成员管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **成员管理**（`organization`） |\n\n## 使用说明\n\n- `country_code` 必须是 ISO 3166-1 alpha-2 地区代码（如 \"CN\"）；写入前校验并统一转为大写，非法值返回 400。\n- 当成员的 `phone` 不带 \"+\" 前缀时，按该成员的 `country_code` 作为地区提示解析（未传时默认 \"CN\"）。",
-          "href": "/zh/api-reference/platform/members/member-invite",
-          "metadata": {
-            "sidebarTitle": "邀请成员"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/MemberInviteRequest"
+              },
+              "example": {
+                "members": [
+                  {
+                    "member_name": "Charlie",
+                    "email": "charlie@example.com",
+                    "locale": "en-US",
+                    "time_zone": "Asia/Shanghai",
+                    "role_ids": [
+                      6
+                    ]
+                  },
+                  {
+                    "member_name": "Dave",
+                    "phone": "13800138000",
+                    "country_code": "CN",
+                    "locale": "zh-CN",
+                    "time_zone": "Asia/Shanghai"
+                  }
+                ]
+              }
+            }
           }
         }
       }
     },
     "/member/list": {
       "post": {
-        "description": "返回组织成员的分页列表。",
         "operationId": "memberList",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "limit": 5,
-                "p": 1
-              },
-              "schema": {
-                "$ref": "#/components/schemas/MemberListRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "查询成员列表",
+        "description": "返回组织成员的分页列表。",
+        "tags": [
+          "平台/成员管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 返回 `enabled` 或 `pending` 状态的成员。已删除的成员和账户主体不会出现在列表中，可用 `POST /person/infos` 解析其 ID。\n- `role_id` 返回持有该角色的成员；`member_id` 最多返回该成员一人。",
+          "href": "/zh/api-reference/platform/members/member-list",
+          "metadata": {
+            "sidebarTitle": "查询成员列表"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/MemberListResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
+                    "p": 1,
+                    "limit": 5,
+                    "total": 148,
                     "items": [
                       {
                         "account_id": 2451002751131,
+                        "member_id": 5068740052131,
+                        "member_name": "Bob",
+                        "country_code": "",
+                        "phone": "+86151****6519",
+                        "email": "bob@example.com",
+                        "phone_verified": true,
+                        "email_verified": true,
+                        "avatar": "",
+                        "status": "enabled",
                         "account_role_ids": [
                           2,
                           6
                         ],
-                        "avatar": "",
-                        "country_code": "",
                         "created_at": 1752030749,
-                        "email": "bob@example.com",
-                        "email_verified": true,
-                        "is_external": false,
-                        "member_id": 5068740052131,
-                        "member_name": "Bob",
-                        "phone": "+86151****6519",
-                        "phone_verified": true,
+                        "updated_at": 1775962064,
                         "ref_id": "",
-                        "status": "enabled",
-                        "updated_at": 1775962064
+                        "is_external": false
                       },
                       {
                         "account_id": 2451002751131,
-                        "account_role_ids": [
-                          6
-                        ],
-                        "avatar": "/image/avatar1.png",
-                        "country_code": "CN",
-                        "created_at": 1701399971,
-                        "email": "alice@example.com",
-                        "email_verified": true,
-                        "is_external": false,
                         "member_id": 2476444212131,
                         "member_name": "Alice",
+                        "country_code": "CN",
                         "phone": "+86185****0300",
+                        "email": "alice@example.com",
                         "phone_verified": true,
-                        "ref_id": "",
+                        "email_verified": true,
+                        "avatar": "/image/avatar1.png",
                         "status": "enabled",
-                        "updated_at": 1775809507
+                        "account_role_ids": [
+                          6
+                        ],
+                        "created_at": 1701399971,
+                        "updated_at": 1775809507,
+                        "ref_id": "",
+                        "is_external": false
                       }
-                    ],
-                    "limit": 5,
-                    "p": 1,
-                    "total": 148
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/MemberListResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                    ]
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -46564,6 +48110,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -46571,65 +48120,63 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "查询成员列表",
-        "tags": [
-          "平台/成员管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |",
-          "href": "/zh/api-reference/platform/members/member-list",
-          "metadata": {
-            "sidebarTitle": "查询成员列表"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/MemberListRequest"
+              },
+              "example": {
+                "p": 1,
+                "limit": 5
+              }
+            }
           }
         }
       }
     },
     "/member/role/grant": {
       "post": {
-        "description": "为成员追加角色授权。不存在的角色 ID 会被静默忽略；若全部无法解析，则调用成功但不产生任何变更。",
         "operationId": "memberGrantRole",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "member_id": 5068740052131,
-                "role_ids": [
-                  6
-                ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/MemberRoleGrantRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "授予成员角色",
+        "description": "为成员在现有角色之外追加一个或多个角色。",
+        "tags": [
+          "平台/成员管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **成员管理**（`organization`） |\n\n## 使用说明\n\n- 不存在的角色 ID 会被忽略；全部不存在时调用成功但不做任何修改。\n- 成员已持有的角色只保留一份，不会重复添加。\n- 通过单点登录同步的成员，在单点登录配置将其设为不可编辑时无法修改，调用返回 `400`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "href": "/zh/api-reference/platform/members/member-grant-role",
+          "metadata": {
+            "sidebarTitle": "授予成员角色"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/MemberEmptyObject"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -46637,6 +48184,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -46644,65 +48194,65 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "授予成员角色",
-        "tags": [
-          "平台/成员管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **成员管理**（`organization`） |",
-          "href": "/zh/api-reference/platform/members/member-grant-role",
-          "metadata": {
-            "sidebarTitle": "授予成员角色"
-          }
-        }
-      }
-    },
-    "/member/role/revoke": {
-      "post": {
-        "description": "解除成员的角色授权。不存在的角色 ID 会被静默忽略；若全部无法解析，则调用成功但不产生任何变更。",
-        "operationId": "memberRevokeRole",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/MemberRoleGrantRequest"
+              },
               "example": {
                 "member_id": 5068740052131,
                 "role_ids": [
                   6
                 ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/MemberRoleRevokeRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/member/role/revoke": {
+      "post": {
+        "operationId": "memberRevokeRole",
+        "summary": "解除成员角色",
+        "description": "从成员的角色中移除一个或多个角色。",
+        "tags": [
+          "平台/成员管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **成员管理**（`organization`） |\n\n## 使用说明\n\n- 不存在的角色 ID 会被忽略；全部不存在时调用成功但不做任何修改。\n- 解除全部角色后成员将没有任何角色，不会回退为 Viewer。\n- 通过单点登录同步的成员，在单点登录配置将其设为不可编辑时无法修改，调用返回 `400`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "href": "/zh/api-reference/platform/members/member-revoke-role",
+          "metadata": {
+            "sidebarTitle": "解除成员角色"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/MemberEmptyObject"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -46710,6 +48260,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -46717,66 +48270,65 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "解除成员角色",
-        "tags": [
-          "平台/成员管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **成员管理**（`organization`） |",
-          "href": "/zh/api-reference/platform/members/member-revoke-role",
-          "metadata": {
-            "sidebarTitle": "解除成员角色"
-          }
-        }
-      }
-    },
-    "/member/role/update": {
-      "post": {
-        "description": "一次性整体替换成员的角色。不存在的角色 ID 会被静默丢弃；`role_ids` 为空时重置为内置 Viewer 角色（ID 8）。",
-        "operationId": "memberUpdateRole",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/MemberRoleRevokeRequest"
+              },
               "example": {
                 "member_id": 5068740052131,
                 "role_ids": [
-                  2,
                   6
                 ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/MemberRoleUpdateRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/member/role/update": {
+      "post": {
+        "operationId": "memberUpdateRole",
+        "summary": "更新成员角色",
+        "description": "用给定的角色集合整体替换成员的角色。",
+        "tags": [
+          "平台/成员管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **成员管理**（`organization`） |\n\n## 使用说明\n\n- `role_ids` 为空或不传时，分配内置的 Viewer 角色（`8`）。\n- 不存在的角色 ID 会被丢弃；若给定的 ID 全部不存在，成员最终将没有任何角色。\n- 通过单点登录同步的成员，在单点登录配置将其设为不可编辑时无法修改，调用返回 `400`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "href": "/zh/api-reference/platform/members/member-update-role",
+          "metadata": {
+            "sidebarTitle": "更新成员角色"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/MemberEmptyObject"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -46784,6 +48336,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -46791,79 +48346,88 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "更新成员角色",
-        "tags": [
-          "平台/成员管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **成员管理**（`organization`） |",
-          "href": "/zh/api-reference/platform/members/member-update-role",
-          "metadata": {
-            "sidebarTitle": "更新成员角色"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/MemberRoleUpdateRequest"
+              },
+              "example": {
+                "member_id": 5068740052131,
+                "role_ids": [
+                  2,
+                  6
+                ]
+              }
+            }
           }
         }
       }
     },
     "/monit/datasource/create": {
       "post": {
-        "description": "创建新的监控数据源，`payload` 中须包含对应类型的配置块。 支持诊断类型 redis_node、redis_sentinel、mongodb_mongod、mongodb_mongos 和 kafka；enabled 与 alerting_enabled 相互独立。",
         "operationId": "monit-datasource-write-create",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "address": "http://prometheus.example.com:9090",
-                "edge_cluster_name": "default",
-                "name": "Prometheus Prod",
-                "note": "Production Prometheus",
-                "payload": {
-                  "prometheus": {
-                    "basic_auth_enabled": false
-                  }
-                },
-                "type_ident": "prometheus"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/DataSourceUpsertRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "创建数据源",
+        "description": "创建一个监控数据源（支持 15 种类型），并将其绑定到某个 Monitors edge 集群。",
+        "tags": [
+          "Monitors/告警数据源"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **数据源管理**（`monit`） |\n\n## 使用说明\n\n- `type_ident` 必须为以下之一：`prometheus`, `loki`, `mysql`, `oracle`, `postgres`, `clickhouse`, `elasticsearch`, `sls`, `tencent_cls`, `victorialogs`, `redis_node`, `redis_sentinel`, `mongodb_mongod`, `mongodb_mongos`, `kafka`。后五种（`redis_node`、`redis_sentinel`、`mongodb_mongod`、`mongodb_mongos`、`kafka`）仅用于诊断，不能评估告警，因此 `alerting_enabled` 不能为 `true`。\n- `name` 在账户内唯一（不区分类型），重名时返回 `InvalidParameter`。\n- `edge_cluster_name` 必须是账户下已存在的 Monitors edge 集群；该集群负责评估规则并执行该数据源的查询。\n- 类型专属配置放在 `payload.<type_ident>` 中。`elasticsearch` 必须设置 `payload.elasticsearch.deployment`（`cloud` 或 `self-managed`）。`tencent_cls` 要求集群内所有 edge 实例均为 Monitors edge v0.66.0 或更高版本。\n- 省略 `enabled` 时默认为 `true`；省略 `alerting_enabled` 时，告警类默认 `true`，仅诊断类默认 `false`。两者显式传 `null` 都会被拒绝。\n- `manage_team_id` 和 `readonly_team_ids` 用于限制谁能管理或查询该数据源；两者都省略则对所有成员开放。\n- 响应会原样返回非诊断类型的凭据（例如 Prometheus 的 Basic Auth 密码）；诊断类型的密码和 Kafka 私钥仅在它们是 `${env:NAME}` 引用时才返回。请将响应视为敏感信息。\n- 每次调用都会记录到账户审计日志。",
+          "href": "/zh/api-reference/monitors/data-sources/monit-datasource-write-create",
+          "metadata": {
+            "sidebarTitle": "创建数据源"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "alerting_enabled": true,
-                    "edge_cluster_name": "default",
-                    "enabled": true,
-                    "id": 10,
-                    "name": "Prometheus Prod",
-                    "type_ident": "prometheus",
-                    "updated_at": 1712000000
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/DataSourceItem"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "id": 10,
+                    "account_id": 10023,
+                    "type_ident": "prometheus",
+                    "name": "Prometheus Prod",
+                    "enabled": true,
+                    "note": "Production Prometheus",
+                    "address": "http://prometheus.example.com:9090",
+                    "payload": {
+                      "prometheus": {
+                        "basic_auth_enabled": false,
+                        "basic_auth_username": "",
+                        "basic_auth_password": "",
+                        "tls_skip_verify": false
+                      }
+                    },
+                    "edge_cluster_name": "default",
+                    "updated_at": 1712000000,
+                    "alerting_enabled": true,
+                    "manage_team_id": null,
+                    "readonly_team_ids": null,
+                    "creator_id": 20001
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -46871,6 +48435,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -46878,62 +48445,71 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "创建数据源",
-        "tags": [
-          "Monitors/告警数据源"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **数据源管理**（`monit`） |\n\n## 使用说明\n\n- `type_ident` 必须为以下之一：`prometheus`、`loki`、`mysql`、`oracle`、`postgres`、`clickhouse`、`elasticsearch`、`sls`、`tencent_cls`、`victorialogs`、`redis_node`、`redis_sentinel`、`mongodb_mongod`、`mongodb_mongos`、`kafka`。\n- `edge_cluster_name` 指定使用该数据源进行规则评估的 Monitors Edge 集群。\n- 对于 `elasticsearch`，`payload.elasticsearch.deployment` 须设为 `cloud` 或 `self-managed`。\n- 每次调用都会记录到账户审计日志，仅通过凭据字段配置连接凭据。\n\n完整支持类型与凭据行为见请求/响应 Schema。仅诊断类型不能启用告警。创建时省略 enabled 默认为 true，更新时省略保留当前值；enabled 或 alerting_enabled 的显式 null 非法。诊断密码及 Kafka 私钥在响应中省略，环境变量引用除外；更新时省略秘密字段保留原值，空字符串清除。其他数据源凭据可能返回，应作为敏感数据处理。",
-          "href": "/zh/api-reference/monitors/data-sources/monit-datasource-write-create",
-          "metadata": {
-            "sidebarTitle": "创建数据源"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/DataSourceUpsertRequest"
+              },
+              "example": {
+                "type_ident": "prometheus",
+                "name": "Prometheus Prod",
+                "note": "Production Prometheus",
+                "address": "http://prometheus.example.com:9090",
+                "edge_cluster_name": "default",
+                "payload": {
+                  "prometheus": {
+                    "basic_auth_enabled": false
+                  }
+                }
+              }
+            }
           }
         }
       }
     },
     "/monit/datasource/delete": {
       "post": {
-        "description": "通过 ID 删除数据源。引用该数据源的告警规则不会被阻塞：该数据源会从规则的监控范围中移除，规则上相关的未恢复告警会自动关闭。",
         "operationId": "monit-datasource-write-delete",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "id": 10
-              },
-              "schema": {
-                "$ref": "#/components/schemas/IDRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "删除数据源",
+        "description": "按 ID 删除数据源；引用它的告警规则不会被阻止。",
+        "tags": [
+          "Monitors/告警数据源"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **数据源管理**（`monit`） |\n\n## 使用说明\n\n- 引用该数据源的告警规则不会被阻止，也不会被修改；规则上该数据源的未恢复告警会自动关闭。\n- 删除不存在的 ID 会直接成功（无任何操作）；属于其他账户的 ID 返回 `ResourceNotFound`。\n- 只有账户所有者、管理员、创建者和负责团队成员可以删除数据源（未设置负责团队时，拥有该权限的调用方均可）；其他人返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志。",
+          "href": "/zh/api-reference/monitors/data-sources/monit-datasource-write-delete",
+          "metadata": {
+            "sidebarTitle": "删除数据源"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -46941,6 +48517,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -46948,81 +48527,84 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "删除数据源",
-        "tags": [
-          "Monitors/告警数据源"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **数据源管理**（`monit`） |\n\n## 使用说明\n\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
-          "href": "/zh/api-reference/monitors/data-sources/monit-datasource-write-delete",
-          "metadata": {
-            "sidebarTitle": "删除数据源"
-          }
-        }
-      }
-    },
-    "/monit/datasource/info": {
-      "post": {
-        "description": "通过 ID 获取单个数据源的完整信息，包括 `payload` 配置及其中配置的连接与鉴权信息；请将该响应视为敏感信息，避免记录或转发。 支持诊断类型 redis_node、redis_sentinel、mongodb_mongod、mongodb_mongos 和 kafka；enabled 与 alerting_enabled 相互独立。",
-        "operationId": "monit-datasource-read-info",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {
-                "id": 10
-              },
               "schema": {
                 "$ref": "#/components/schemas/IDRequest"
+              },
+              "example": {
+                "id": 10
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/monit/datasource/info": {
+      "post": {
+        "operationId": "monit-datasource-read-info",
+        "summary": "查看数据源详情",
+        "description": "按 ID 返回单个数据源，包含完整的 `payload` 配置。",
+        "tags": [
+          "Monitors/告警数据源"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **数据源查看**（`monit`） |\n\n## 使用说明\n\n- 需要该数据源的管理权限（见 `manage_team_id`）；只有查询权限的成员返回 `AccessDenied`。需要查看自己可查询的数据源时请使用 `/monit/datasource/list`。\n- 响应属于敏感信息：`payload` 包含连接配置，非诊断类型的凭据会原样返回；诊断类型的密码和 Kafka 私钥仅在是 `${env:NAME}` 引用时才返回；`tencent_cls` 的 `secret_key` 返回空字符串，除非它是 `${env:NAME}` 引用。\n- ID 不存在或属于其他账户时返回 `ResourceNotFound`。",
+          "href": "/zh/api-reference/monitors/data-sources/monit-datasource-read-info",
+          "metadata": {
+            "sidebarTitle": "查看数据源详情"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "account_id": 10023,
-                    "address": "http://prometheus.example.com:9090",
-                    "alerting_enabled": true,
-                    "edge_cluster_name": "default",
-                    "enabled": true,
-                    "id": 10,
-                    "name": "Prometheus Prod",
-                    "note": "Production Prometheus",
-                    "payload": {
-                      "prometheus": {
-                        "basic_auth_enabled": false,
-                        "basic_auth_password": "",
-                        "basic_auth_username": "",
-                        "tls_skip_verify": false
-                      }
-                    },
-                    "type_ident": "prometheus",
-                    "updated_at": 1712000000
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/DataSourceItem"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "id": 10,
+                    "account_id": 10023,
+                    "type_ident": "prometheus",
+                    "name": "Prometheus Prod",
+                    "enabled": true,
+                    "note": "Production Prometheus",
+                    "address": "http://prometheus.example.com:9090",
+                    "payload": {
+                      "prometheus": {
+                        "basic_auth_enabled": false,
+                        "basic_auth_username": "",
+                        "basic_auth_password": "",
+                        "tls_skip_verify": false
+                      }
+                    },
+                    "edge_cluster_name": "default",
+                    "updated_at": 1712000000,
+                    "alerting_enabled": true,
+                    "manage_team_id": null,
+                    "readonly_team_ids": null,
+                    "creator_id": 20001
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -47030,6 +48612,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -47037,76 +48622,80 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "查看数据源详情",
-        "tags": [
-          "Monitors/告警数据源"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **数据源查看**（`monit`） |\n\n完整支持类型与凭据行为见请求/响应 Schema。仅诊断类型不能启用告警。创建时省略 enabled 默认为 true，更新时省略保留当前值；enabled 或 alerting_enabled 的显式 null 非法。诊断密码及 Kafka 私钥在响应中省略，环境变量引用除外；更新时省略秘密字段保留原值，空字符串清除。其他数据源凭据可能返回，应作为敏感数据处理。",
-          "href": "/zh/api-reference/monitors/data-sources/monit-datasource-read-info",
-          "metadata": {
-            "sidebarTitle": "查看数据源详情"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/IDRequest"
+              },
+              "example": {
+                "id": 10
+              }
+            }
           }
         }
       }
     },
     "/monit/datasource/list": {
       "post": {
-        "description": "返回当前账户下的所有数据源，可通过 `type_ident` 过滤类型。 支持诊断类型 redis_node、redis_sentinel、mongodb_mongod、mongodb_mongos 和 kafka；enabled 与 alerting_enabled 相互独立。",
         "operationId": "monit-datasource-read-list",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "type": "prometheus"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/DataSourceListRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "查询数据源列表",
+        "description": "列出账户下调用方有权查询的数据源，可按类型或名称精确过滤。",
+        "tags": [
+          "Monitors/告警数据源"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **数据源查看**（`monit`） |\n\n## 使用说明\n\n- 省略 `type` 和 `name` 时返回你有权查询的所有数据源；`type`、`name` 均为精确匹配。无法识别的 `type` 返回空数组。结果不分页。\n- 只返回调用方有权查询的数据源（见 `readonly_team_ids`）；每项带有 `my_perm`（`manage` 或 `readonly`）。\n- 列表项中的 `payload` 恒为 `null`。如需读取自己可管理的数据源的配置，请使用 `/monit/datasource/info`。",
+          "href": "/zh/api-reference/monitors/data-sources/monit-datasource-read-list",
+          "metadata": {
+            "sidebarTitle": "查询数据源列表"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": [
-                    {
-                      "account_id": 10023,
-                      "address": "http://prometheus.example.com:9090",
-                      "alerting_enabled": true,
-                      "edge_cluster_name": "default",
-                      "enabled": true,
-                      "id": 10,
-                      "name": "Prometheus Prod",
-                      "note": "Production Prometheus",
-                      "payload": null,
-                      "type_ident": "prometheus",
-                      "updated_at": 1712000000
-                    }
-                  ],
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/DataSourceListResponse"
                         }
-                      },
-                      "type": "object"
+                      }
+                    }
+                  ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": [
+                    {
+                      "id": 10,
+                      "account_id": 10023,
+                      "type_ident": "prometheus",
+                      "name": "Prometheus Prod",
+                      "enabled": true,
+                      "note": "Production Prometheus",
+                      "address": "http://prometheus.example.com:9090",
+                      "payload": null,
+                      "edge_cluster_name": "default",
+                      "updated_at": 1712000000,
+                      "alerting_enabled": true,
+                      "manage_team_id": null,
+                      "readonly_team_ids": null,
+                      "creator_id": 20001,
+                      "my_perm": "manage"
                     }
                   ]
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -47114,6 +48703,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -47121,68 +48713,65 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "查询数据源列表",
-        "tags": [
-          "Monitors/告警数据源"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **数据源查看**（`monit`） |\n\n## 使用说明\n\n- 省略 `type_ident` 可返回所有类型的数据源。\n- 列表响应中不返回敏感凭证字段（密码、密钥）。\n\n完整支持类型与凭据行为见请求/响应 Schema。仅诊断类型不能启用告警。创建时省略 enabled 默认为 true，更新时省略保留当前值；enabled 或 alerting_enabled 的显式 null 非法。诊断密码及 Kafka 私钥在响应中省略，环境变量引用除外；更新时省略秘密字段保留原值，空字符串清除。其他数据源凭据可能返回，应作为敏感数据处理。",
-          "href": "/zh/api-reference/monitors/data-sources/monit-datasource-read-list",
-          "metadata": {
-            "sidebarTitle": "查询数据源列表"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/DataSourceListRequest"
+              },
+              "example": {
+                "type": "prometheus"
+              }
+            }
           }
         }
       }
     },
     "/monit/datasource/sls/logstores": {
       "post": {
-        "description": "列出指定 SLS 数据源中某个项目下的日志库。",
         "operationId": "monit-datasource-read-sls-logstores",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "id": 10,
-                "offset": 0,
-                "project": "project-a",
-                "size": 50
-              },
-              "schema": {
-                "$ref": "#/components/schemas/SLSLogstoresRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "查询 SLS 日志库列表",
+        "description": "列出指定 SLS 数据源中某个项目下的日志库。",
+        "tags": [
+          "Monitors/告警数据源"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **数据源查看**（`monit`） |\n\n## 使用说明\n\n- `id` 指定的数据源类型必须为 `sls`，其他类型返回 `InvalidParameter`。\n- 通过 `project` 指定要列出日志库的 SLS 项目；使用 `offset` 和 `size` 分页。响应是日志库名称组成的数组。\n- 请求会转发给该数据源所属的 Monitors edge 集群，由 edge 使用已保存的凭据调用阿里云，30 秒超时。该集群没有在线的 edge 实例时返回 `InvalidParameter`；edge 版本不支持元数据发现时返回 HTTP 503 `ServiceUnavailable`。",
+          "href": "/zh/api-reference/monitors/data-sources/monit-datasource-read-sls-logstores",
+          "metadata": {
+            "sidebarTitle": "查询 SLS 日志库列表"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": [
-                    "logstore-1",
-                    "logstore-2"
-                  ],
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/SLSLogstoresResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": [
+                    "logstore-1",
+                    "logstore-2"
+                  ]
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -47190,6 +48779,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -47197,88 +48789,88 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "查询 SLS 日志库列表",
-        "tags": [
-          "Monitors/告警数据源"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **数据源查看**（`monit`） |\n\n## 使用说明\n\n- `id` 指定的数据源类型必须为 `sls`。\n- 通过 `project` 指定要列出日志库的 SLS 项目。",
-          "href": "/zh/api-reference/monitors/data-sources/monit-datasource-read-sls-logstores",
-          "metadata": {
-            "sidebarTitle": "查询 SLS 日志库列表"
-          }
-        }
-      }
-    },
-    "/monit/datasource/sls/projects": {
-      "post": {
-        "description": "列出指定 SLS 数据源中可用的阿里云日志服务（SLS）项目。",
-        "operationId": "monit-datasource-read-sls-projects",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/SLSLogstoresRequest"
+              },
               "example": {
                 "id": 10,
+                "project": "project-a",
                 "offset": 0,
-                "query": "",
                 "size": 50
-              },
-              "schema": {
-                "$ref": "#/components/schemas/SLSProjectsRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/monit/datasource/sls/projects": {
+      "post": {
+        "operationId": "monit-datasource-read-sls-projects",
+        "summary": "查询 SLS 项目列表",
+        "description": "列出指定 SLS 数据源中可用的阿里云日志服务（SLS）项目。",
+        "tags": [
+          "Monitors/告警数据源"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **数据源查看**（`monit`） |\n\n## 使用说明\n\n- `id` 指定的数据源类型必须为 `sls`，其他类型返回 `InvalidParameter`。\n- 使用 `query` 过滤项目列表，使用 `offset` 和 `size` 分页；`count` 为当前页项目数，`total` 为满足过滤条件的项目总数。\n- 请求会转发给该数据源所属的 Monitors edge 集群，由 edge 使用已保存的凭据调用阿里云，30 秒超时。该集群没有在线的 edge 实例时返回 `InvalidParameter`；edge 版本不支持元数据发现时返回 HTTP 503 `ServiceUnavailable`。",
+          "href": "/zh/api-reference/monitors/data-sources/monit-datasource-read-sls-projects",
+          "metadata": {
+            "sidebarTitle": "查询 SLS 项目列表"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/SLSProjectsResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
-                    "count": 2,
                     "projects": [
                       {
-                        "createTime": "1710000000",
+                        "projectName": "project-a",
                         "description": "Production logs",
-                        "lastModifyTime": "1712000000",
+                        "status": "Normal",
                         "owner": "",
-                        "projectName": "project-a",
                         "region": "cn-shanghai",
-                        "status": "Normal"
+                        "createTime": "1710000000",
+                        "lastModifyTime": "1712000000"
                       },
                       {
-                        "createTime": "1710000000",
+                        "projectName": "project-b",
                         "description": "Staging logs",
-                        "lastModifyTime": "1712000000",
+                        "status": "Normal",
                         "owner": "",
-                        "projectName": "project-b",
                         "region": "cn-shanghai",
-                        "status": "Normal"
+                        "createTime": "1710000000",
+                        "lastModifyTime": "1712000000"
                       }
                     ],
+                    "count": 2,
                     "total": 2
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/SLSProjectsResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -47286,6 +48878,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -47293,15 +48888,20 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "查询 SLS 项目列表",
-        "tags": [
-          "Monitors/告警数据源"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **数据源查看**（`monit`） |\n\n## 使用说明\n\n- `id` 指定的数据源类型必须为 `sls`。\n- 使用 `query` 按名称前缀过滤项目，使用 `offset` 和 `size` 分页。",
-          "href": "/zh/api-reference/monitors/data-sources/monit-datasource-read-sls-projects",
-          "metadata": {
-            "sidebarTitle": "查询 SLS 项目列表"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/SLSProjectsRequest"
+              },
+              "example": {
+                "id": 10,
+                "query": "",
+                "offset": 0,
+                "size": 50
+              }
+            }
           }
         }
       }
@@ -47389,7 +48989,7 @@
                               {
                                 "labels": {
                                   "__name__": "up",
-                                  "instance": "10.101.214.50:7070"
+                                  "instance": "203.0.113.10:9090"
                                 },
                                 "value": 1
                               }
@@ -47513,7 +49113,7 @@
           "Monitors/告警数据源"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **2,000 次/分钟**；**32 次/秒** |\n| 权限要求 | **数据源查看**（`monit`） |\n\n通过 `/monit/datasource/list` 获取数据源 ID。停用数据源返回 `datasource_disabled`，`alerting_enabled=false` 不阻断工具。错误使用非 2xx HTTP 状态和 `error.code`、`error.message`、`error.reason`。`tool_not_supported` 表示选中的执行端未提供该工具，不表示厂商权限不足。禁止自动切换 Edge 或回退旧 diagnose 重试。\n\n## 使用说明\n\n- 本入口共用两类工具：由执行端 Edge 定义的诊断工具（如 `mysql.overview`、`prometheus.metric_trends`）和命名为 `<type>.query` 的查询工具。工具前缀必须与数据源类型一致。\n- 查询工具要求 Edge 集群支持 Explore 查询（协议里程碑 v0.68.0）；诊断工具要求 v0.71.0 基础 invoke 协议。不支持的集群返回 `edge_upgrade_required`、`mixed_edge_versions` 或 `edge_version_unknown`；禁止自动回退 `/monit/query/data` 或其他接口。\n- 查询工具的 `params` 遵循 `tool` 字段描述中按数据源列出的专属 Schema。`expr` 和 `execution` 必填。`limit`/`direction` 只约束原始日志条数与检索方向，不代表 SQL 行数或扫描量。未知扩展字段被容忍，但不参与执行也不透传。\n- 查询结果的 `data` 是完整 Explore 结果：`format` 为 `explore_result.v1`，`result.kind` 为 `samples`、`frames` 或 `logs`；日志结果保留 `applied_limit` 和 `has_more`。查询结果不合成 `summary` 或 `truncated`。\n- 请求体上限 128 KiB；两类工具的完整成功响应上限均为 10 MiB；诊断工具超时最多 25 秒。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **2,000 次/分钟**；**32 次/秒** |\n| 权限要求 | **数据源查看**（`monit`） |\n\n通过 `/monit/datasource/list` 获取数据源 ID。停用数据源返回 `datasource_disabled`，`alerting_enabled=false` 不阻断工具。错误使用非 2xx HTTP 状态和 `error.code`、`error.message`、`error.reason`。`tool_not_supported` 表示选中的执行端未提供该工具，不表示厂商权限不足。禁止自动切换 Edge 或回退旧 diagnose 重试。\n\n## 使用说明\n\n- 调用方需要拥有该数据源的查询权限（见数据源的 `readonly_team_ids`），否则返回 403 `access_denied`；其他账户的数据源返回 404 `datasource_not_found`。\n- 诊断工具仅支持数据源类型 `mysql`、`postgres`、`redis_node`、`redis_sentinel`、`mongodb_mongod`、`mongodb_mongos`、`kafka`、`elasticsearch`、`prometheus`、`loki` 和 `victorialogs`；`oracle`、`clickhouse`、`sls`、`tencent_cls` 只支持各自的 `<type>.query` 工具。其他组合返回 `invalid_request`。\n- 本入口共用两类工具：由执行端 Edge 定义的诊断工具（如 `mysql.overview`、`prometheus.metric_trends`）和命名为 `<type>.query` 的查询工具。工具前缀必须与数据源类型一致。\n- 查询工具要求 Edge 集群支持 Explore 查询（协议里程碑 v0.68.0）；诊断工具要求 v0.71.0 基础 invoke 协议。不支持的集群返回 `edge_upgrade_required`、`mixed_edge_versions` 或 `edge_version_unknown`；禁止自动回退 `/monit/query/data` 或其他接口。\n- 查询工具的 `params` 遵循 `tool` 字段描述中按数据源列出的专属 Schema。`expr` 和 `execution` 必填。`limit`/`direction` 只约束原始日志条数与检索方向，不代表 SQL 行数或扫描量。未知扩展字段被容忍，但不参与执行也不透传。\n- 查询结果的 `data` 是完整 Explore 结果：`format` 为 `explore_result.v1`，`result.kind` 为 `samples`、`frames` 或 `logs`；日志结果保留 `applied_limit` 和 `has_more`。查询结果不合成 `summary` 或 `truncated`。\n- 请求体上限 128 KiB；两类工具的完整成功响应上限均为 10 MiB；诊断工具超时最多 25 秒。",
           "href": "/zh/api-reference/monitors/data-sources/monit-datasource-tools-invoke",
           "metadata": {
             "sidebarTitle": "调用数据源工具"
@@ -47523,65 +49123,67 @@
     },
     "/monit/datasource/update": {
       "post": {
-        "description": "更新已有数据源，需提供 `id` 及待修改的字段。 支持诊断类型 redis_node、redis_sentinel、mongodb_mongod、mongodb_mongos 和 kafka；enabled 与 alerting_enabled 相互独立。",
         "operationId": "monit-datasource-write-update",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "address": "http://prometheus-v2.example.com:9090",
-                "edge_cluster_name": "default",
-                "id": 10,
-                "name": "Prometheus Prod v2",
-                "note": "Updated",
-                "payload": {
-                  "prometheus": {
-                    "basic_auth_enabled": false
-                  }
-                },
-                "type_ident": "prometheus"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/DataSourceUpsertRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "更新数据源",
+        "description": "按 ID 更新数据源，整体替换其名称、备注、地址、payload 和 edge 集群。",
+        "tags": [
+          "Monitors/告警数据源"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **数据源管理**（`monit`） |\n\n## 使用说明\n\n- 这是整体替换而非局部更新：每次调用都要发送 `type_ident`、`name`、`edge_cluster_name`、`payload`，以及 `address`（`cloud` 部署的 Elasticsearch 除外）。`note`、`address`、`payload` 会覆盖已保存的值，因此省略 `note` 会将其清空。\n- 省略 `enabled`、`alerting_enabled`、`manage_team_id`、`readonly_team_ids` 时保持原值。`enabled` 或 `alerting_enabled` 传 `null` 会被拒绝；两个团队字段传 `null` 表示清除。\n- 密钥：诊断类型省略密码（以及 Kafka 的 `tls_key`）表示保留已保存的值，传空字符串表示清除；`tencent_cls` 省略或传空的 `secret_key` 表示保留已保存的密钥；其他类型需要重新发送凭据。\n- 将 `enabled` 或 `alerting_enabled` 设为 `false`，或修改 `type_ident`、`edge_cluster_name`，会关闭使用该数据源的规则上的未恢复告警；重命名时，会关闭 `ds_list` 名称模式不再匹配新名称的规则上的未恢复告警。\n- 只要仍有已启用的告警规则选中该数据源，关闭 `alerting_enabled` 会返回 HTTP 409 `UndonedOrderExist`。\n- 只有账户所有者、管理员、创建者和负责团队成员可以更新数据源（未设置负责团队时，拥有该权限的调用方均可）；其他人返回 `AccessDenied`。ID 不存在或属于其他账户时返回 `ResourceNotFound`。\n- 每次调用都会记录到账户审计日志。",
+          "href": "/zh/api-reference/monitors/data-sources/monit-datasource-write-update",
+          "metadata": {
+            "sidebarTitle": "更新数据源"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "alerting_enabled": true,
-                    "edge_cluster_name": "default",
-                    "enabled": true,
-                    "id": 10,
-                    "name": "Prometheus Prod v2",
-                    "type_ident": "prometheus",
-                    "updated_at": 1712100000
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/DataSourceItem"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "id": 10,
+                    "account_id": 10023,
+                    "type_ident": "prometheus",
+                    "name": "Prometheus Prod v2",
+                    "enabled": true,
+                    "note": "Updated",
+                    "address": "http://prometheus-v2.example.com:9090",
+                    "payload": {
+                      "prometheus": {
+                        "basic_auth_enabled": false,
+                        "basic_auth_username": "",
+                        "basic_auth_password": "",
+                        "tls_skip_verify": false
+                      }
+                    },
+                    "edge_cluster_name": "default",
+                    "updated_at": 1712100000,
+                    "alerting_enabled": true,
+                    "manage_team_id": null,
+                    "readonly_team_ids": null,
+                    "creator_id": 20001
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -47589,6 +49191,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -47596,15 +49201,27 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "更新数据源",
-        "tags": [
-          "Monitors/告警数据源"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **数据源管理**（`monit`） |\n\n## 使用说明\n\n- 每次调用都会记录到账户审计日志，仅通过凭据字段配置连接凭据。\n\n完整支持类型与凭据行为见请求/响应 Schema。仅诊断类型不能启用告警。创建时省略 enabled 默认为 true，更新时省略保留当前值；enabled 或 alerting_enabled 的显式 null 非法。诊断密码及 Kafka 私钥在响应中省略，环境变量引用除外；更新时省略秘密字段保留原值，空字符串清除。其他数据源凭据可能返回，应作为敏感数据处理。",
-          "href": "/zh/api-reference/monitors/data-sources/monit-datasource-write-update",
-          "metadata": {
-            "sidebarTitle": "更新数据源"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/DataSourceUpsertRequest"
+              },
+              "example": {
+                "id": 10,
+                "type_ident": "prometheus",
+                "name": "Prometheus Prod v2",
+                "note": "Updated",
+                "address": "http://prometheus-v2.example.com:9090",
+                "edge_cluster_name": "default",
+                "payload": {
+                  "prometheus": {
+                    "basic_auth_enabled": false
+                  }
+                }
+              }
+            }
           }
         }
       }
@@ -47615,75 +49232,71 @@
         "operationId": "monit-prometheus-read-label-values",
         "parameters": [
           {
-            "description": "要枚举取值的标签名，例如 `job`。",
-            "in": "path",
             "name": "label_name",
+            "in": "path",
             "required": true,
             "schema": {
               "type": "string"
-            }
+            },
+            "description": "要枚举取值的标签名，例如 `job`。"
           },
           {
-            "description": "要查询的数据源 ID，必须是当前账户下 Prometheus 兼容类型的数据源。",
-            "in": "header",
             "name": "X-DSID",
-            "required": true,
+            "in": "header",
+            "required": false,
             "schema": {
               "type": "string"
-            }
+            },
+            "description": "要查询的数据源 ID，十进制字符串。必须是当前账户下的 Prometheus 类型数据源。省略时由平台自有的 Prometheus 响应，而不是您的数据源。"
           }
         ],
         "responses": {
           "200": {
+            "description": "数据源返回的原生 Prometheus 标签值响应。",
             "content": {
               "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PrometheusLabelValuesResponse"
+                },
                 "example": {
+                  "status": "success",
                   "data": [
                     "api",
                     "db",
                     "worker"
-                  ],
-                  "status": "success"
-                },
-                "schema": {
-                  "$ref": "#/components/schemas/PrometheusLabelValuesResponse"
+                  ]
                 }
               }
-            },
-            "description": "数据源返回的原生 Prometheus 标签值响应。"
+            }
           },
           "400": {
+            "description": "`X-DSID` 请求头不是数字、数据源不是 Prometheus 类型，或数据源所在集群没有已注册的 monit-edge。以 `text/plain` 返回。",
             "content": {
               "text/plain": {
                 "schema": {
                   "type": "string"
                 }
               }
-            },
-            "description": "`X-DSID` 请求头缺失或非法、数据源不存在，或该数据源不是 Prometheus 类型。以 `text/plain` 返回。"
+            }
           },
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
-          "500": {
-            "content": {
-              "text/plain": {
-                "schema": {
-                  "type": "string"
-                }
-              }
-            },
-            "description": "数据源查询或代理请求失败。以 `text/plain` 返回。"
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
           },
-          "503": {
+          "429": {
+            "$ref": "#/components/responses/TooManyRequests"
+          },
+          "500": {
+            "description": "数据源不存在或属于其他账户（消息为 `data source not found`），或数据源查询、代理请求失败。以 `text/plain` 返回。",
             "content": {
               "text/plain": {
                 "schema": {
                   "type": "string"
                 }
               }
-            },
-            "description": "数据源所在集群中没有支持数据源资源代理的 monit-edge。以 `text/plain` 返回，请升级 monit-edge。"
+            }
           }
         },
         "summary": "查询 Prometheus 标签值列表",
@@ -47691,7 +49304,7 @@
           "Monitors/告警数据源"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 任意有效的 `app_key`（只读，不受特定权限分类限制） |\n| Edge 版本要求 | 受支持的部署要求 **monit-edge v0.35.0 或更高版本** |\n\n## 使用说明\n\n- 通过 `X-DSID` 请求头指定目标数据源，必须是当前账户下 Prometheus 兼容类型的数据源；可用 `/monit/datasource/list` 获取 ID。\n- 200 响应体是数据源原生的 Prometheus HTTP API 结构，**不是**统一的 `{ request_id, data }` envelope。未到达数据源前发生的失败以 `text/plain` 返回，并携带对应的 4xx/5xx 状态码。\n- 省略 `X-DSID` 时会回退到平台自有的 Prometheus 代理；需要查询指定数据源时必须携带该请求头。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 任意有效的 `app_key`（只读，不受特定权限分类限制） |\n| Edge 版本要求 | 查询指定数据源要求 **monit-edge v0.35.0 或更高版本** |\n\n## 使用说明\n\n- 通过 `X-DSID` 请求头传入目标数据源 ID。数据源必须属于当前账户且为 Prometheus 类型；可用 `/monit/datasource/list` 获取 ID。\n- 200 响应体是数据源原生的 Prometheus HTTP API 结构，**不是**统一的 `{ request_id, data }` envelope。查询字符串参数会原样转发，因此 Prometheus 自身的 `match[]`、`start`、`end` 等参数都可使用。\n- 省略 `X-DSID`，或数据源所在集群中有任意 monit-edge 低于 v0.35.0 时，请求会由平台自有的 Prometheus 响应，而不是您的数据源。请携带该请求头并保持 monit-edge 为较新版本，才能获得数据源自身的取值。\n- 到达数据源之前发生的失败以 `text/plain` 返回，并携带对应的 4xx/5xx 状态码。数据源自身返回的 400 及以上状态码会连同其响应体一并透传。",
           "href": "/zh/api-reference/monitors/data-sources/monit-prometheus-read-label-values",
           "metadata": {
             "sidebarTitle": "查询 Prometheus 标签值列表"
@@ -47704,41 +49317,56 @@
         "description": "对已配置的数据源执行探索查询，返回 frames、samples 或 logs 形态的结果。",
         "operationId": "monit-read-query-explore",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/QueryExploreRequest"
+              },
               "example": {
-                "args": {},
                 "datasource_id": 101,
+                "expr": "rate(http_requests_total[5m])",
+                "args": {},
                 "execution": {
-                  "from_ms": 1787187600000,
                   "kind": "range",
+                  "from_ms": 1787187600000,
+                  "to_ms": 1787191200000,
                   "max_data_points": 1200,
-                  "min_step_seconds": 15,
-                  "to_ms": 1787191200000
-                },
-                "expr": "rate(http_requests_total[5m])"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/QueryExploreRequest"
+                  "min_step_seconds": 15
+                }
               }
             }
-          },
-          "required": true
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/ExploreData"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
-                    "execution": {
-                      "effective_step_seconds": 60,
-                      "kind": "range"
-                    },
                     "format": "explore_result.v1",
                     "result": {
+                      "kind": "frames",
                       "frames": [
                         {
+                          "kind": "time_series",
                           "fields": [
                             {
                               "name": "time",
@@ -47749,136 +49377,111 @@
                               ]
                             },
                             {
+                              "name": "value",
+                              "type": "float",
                               "labels": {
                                 "job": "api"
                               },
-                              "name": "value",
-                              "type": "float",
                               "values": [
                                 1.25,
                                 null
                               ]
                             }
-                          ],
-                          "kind": "time_series"
+                          ]
                         }
-                      ],
-                      "kind": "frames"
-                    }
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
+                      ]
                     },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/ExploreData"
-                        }
-                      },
-                      "type": "object"
+                    "execution": {
+                      "kind": "range",
+                      "effective_step_seconds": 60
                     }
-                  ]
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
+            "description": "标准 HTTP 错误。参数格式错误或超出范围、数据源已禁用、数据源类型不受支持或数据源未绑定 Edge 集群时，`error.reason` 为 `invalid_request`。数据源 ID 不存在时返回错误码 `ResourceNotFound`，且不带 `reason`。",
             "content": {
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ErrorResponse"
                 }
               }
-            },
-            "description": "标准 HTTP 错误；error.reason：invalid_request。"
+            }
           },
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
           "403": {
+            "description": "调用方无权查询该数据源。`error.code` 为 `AccessDenied`，不带 `error.reason`。",
             "content": {
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ErrorResponse"
                 }
               }
-            },
-            "description": "标准 HTTP 错误；error.reason：access_denied。"
-          },
-          "404": {
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/ErrorResponse"
-                }
-              }
-            },
-            "description": "标准 HTTP 错误；error.reason：datasource_not_found。"
+            }
           },
           "413": {
+            "description": "标准 HTTP 错误。`error.reason`：`too_many_rows`、`source_too_large` 或 `result_too_large`。请求体超过 256 KiB 时同样返回 413，不带 `reason`。",
             "content": {
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ErrorResponse"
                 }
               }
-            },
-            "description": "标准 HTTP 错误；error.reason：source_too_large、result_too_large。"
+            }
           },
           "429": {
+            "description": "标准 HTTP 错误；error.reason：overloaded。",
             "content": {
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ErrorResponse"
                 }
               }
-            },
-            "description": "标准 HTTP 错误；error.reason：overloaded。"
+            }
           },
           "499": {
+            "description": "标准 HTTP 错误；error.reason：canceled。",
             "content": {
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ErrorResponse"
                 }
               }
-            },
-            "description": "标准 HTTP 错误；error.reason：canceled。"
+            }
           },
           "500": {
+            "description": "标准 HTTP 错误；error.reason：internal。",
             "content": {
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ErrorResponse"
                 }
               }
-            },
-            "description": "标准 HTTP 错误；error.reason：internal。"
+            }
           },
           "503": {
+            "description": "标准 HTTP 错误。`error.reason`：`no_active_edge`、`edge_version_unknown`、`edge_upgrade_required`、`mixed_edge_versions` 或 `edge_unavailable`。",
             "content": {
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ErrorResponse"
                 }
               }
-            },
-            "description": "标准 HTTP 错误；error.reason：no_active_edge、edge_upgrade_required、mixed_edge_versions、edge_unavailable。"
+            }
           },
           "504": {
+            "description": "标准 HTTP 错误；error.reason：timeout。",
             "content": {
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ErrorResponse"
                 }
               }
-            },
-            "description": "标准 HTTP 错误；error.reason：timeout。"
+            }
           }
         },
         "summary": "执行探索查询",
@@ -47886,7 +49489,7 @@
           "Monitors/诊断分析"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **100 次/分钟**；**16 次/秒** |\n| 权限要求 | **数据源查看**（`monit`） |\n| Edge 版本要求 | 受支持的部署要求 **monit-edge v0.68.0 或更高版本** |\n\n## 使用说明\n\n- 需要数据源原生结果形态时使用本接口；`/monit/query/data` 返回稳定的 `query_result.v1` 契约。本接口根据 `data.result.kind`（`frames`、`samples` 或 `logs`）分发结果。\n- `execution.kind` 决定可接受的配套字段：`instant` 只需 `to_ms`，`range` 需要 `from_ms`、`to_ms` 和 `max_data_points`，`window` 需要 `from_ms` 和 `to_ms`。不接受 `step_seconds`，步长由 `max_data_points` 与 `min_step_seconds` 推导。\n- `args` 用于宏替换（例如 Grafana 风格变量），取值均为字符串。\n- `logs` 结果最多返回 1,000 条，并通过 `applied_limit` 与 `has_more` 说明截断情况。时序与采样结果各最多 1,000 条，成功响应整体上限 8 MiB。\n- WebAPI 跨实例转发与 Edge 执行合计可能耗时 35 秒，客户端超时建议至少 40 秒。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **100 次/分钟**；**16 次/秒** |\n| 权限要求 | **数据源查看**（`monit`） |\n| Edge 版本要求 | 受支持的部署要求 **monit-edge v0.68.0 或更高版本** |\n\n## 使用说明\n\n- 需要数据源原生结果形态时使用本接口；`/monit/query/data` 返回稳定的 `query_result.v1` 契约。本接口根据 `data.result.kind`（`frames`、`samples` 或 `logs`）分发结果。\n- 数据源由 `datasource_id` 指定。数据源必须属于当前账户、已启用、已绑定 Edge 集群，且类型为 `prometheus`、`elasticsearch`、`loki`、`clickhouse`、`mysql`、`oracle`、`postgres`、`sls`、`victorialogs` 或 `tencent_cls` 之一。若数据源限制了可查询的团队，只有这些团队的成员、其管理团队以及账户所有者或管理员可以查询。\n- `execution.kind` 决定可接受的配套字段：`instant` 需要 `to_ms`（`from_ms` 可选），`range` 需要 `from_ms`、`to_ms` 和 `max_data_points`，`window` 需要 `from_ms` 和 `to_ms`。同时给出两个时间时，`from_ms` 必须小于 `to_ms`。不接受 `step_seconds`，步长由 `max_data_points` 与 `min_step_seconds` 推导。\n- `args` 为必填（无参数时传 `{}`），用于宏替换（例如 Grafana 风格变量），取值均为字符串。未知或重复的 JSON 键会被拒绝。\n- `logs` 结果最多返回 1,000 条（`sls` 为 100 条），并通过 `applied_limit` 与 `has_more` 说明截断情况。`frames` 结果最多 1,000 个 frame，表格行合计最多 1,000 行，值合计最多 100,000 个；`samples` 结果最多 1,000 条。请求体上限 256 KiB，成功响应整体上限 10 MiB。\n- 失败使用标准错误 envelope。`error.reason` 是稳定的机器可读取值；数据源 ID 不存在时返回 HTTP 400，错误码为 `ResourceNotFound`，且不带 `reason`。\n- WebAPI 跨实例转发与 Edge 执行合计可能耗时 35 秒，客户端超时建议至少 40 秒。",
           "href": "/zh/api-reference/monitors/diagnostics/monit-read-query-explore",
           "metadata": {
             "sidebarTitle": "执行探索查询"
@@ -47896,30 +49499,58 @@
     },
     "/monit/query/data": {
       "post": {
-        "description": "对已配置的数据源执行同步即席查询，并返回稳定的 `query_result.v1` 结果；结果会按自然语义呈现为 frames、records 或 samples。此公开接口要求 monit-edge v0.65.0 或更高版本。",
         "operationId": "monit-read-query-data",
+        "summary": "查询结构化数据",
+        "description": "对数据源执行同步即席查询，返回 `query_result.v1` 结果，形态为 frames、records 或 samples。",
+        "tags": [
+          "Monitors/诊断分析"
+        ],
+        "x-mint": {
+          "content": "## 调用限制\n\n| 项 | 值 |\n| ------ | ----- |\n| 速率限制 | 每账户 **100 次/分钟**、**5 次/秒** |\n| 权限 | 任意有效的 `app_key`（只读，不受特定权限分类限制） |\n| Edge 版本要求 | 受支持的部署要求 **monit-edge v0.65.0 或更高版本** |\n\n## 使用说明\n\n- 数据源由 `ds_type` 加 `ds_name` 指定，而不是数据源 ID。数据源必须属于当前账户且已启用。若数据源限制了可查询的团队，只有这些团队的成员、其管理团队以及账户所有者或管理员可以查询，其他人会收到 `AccessDenied`。\n- 此公开接口以 **monit-edge v0.65.0** 为最低受支持版本。迁移期间，WebAPI 仍保留旧版 Edge 适配器：query.v2 结果仍可能保留 frames、records 或 samples，而 legacy rows 只能提供其已保留的信息。这些适配器不会改变最低支持版本；旧协议缺少 query.v3 的取消和错误生命周期语义，legacy rows 已丢失的数据也无法恢复。\n- 公开响应格式固定为 `query_result.v1`，与 Edge 内部查询协议版本无关。必须根据 `result.kind`（`frames`、`records` 或 `samples`）分发结果，不要根据 `ds_type` 或 Edge 版本猜测结果形态。\n- `frames` 结果可以包含多个表格或时序 Frame。字段值按列组织，同一 Frame 中所有字段的值数量一致。\n- `records` 结果可以包含嵌套 JSON 和 null record。超出 JavaScript 安全整数范围的整数字面量会以十进制字符串返回。\n- `samples` 结果包含标签集合和瞬时值。值可以是数字，也可以是字符串 `NaN`、`+Inf` 或 `-Inf`。\n- Prometheus 表达式在下发查询前会做语法检查，表达式非法时返回 HTTP 400。\n- 请求体上限为 256 KiB，完整成功响应上限为 10 MiB，超限均返回 HTTP 413。结果超过 1,000 行时返回 HTTP 400。请缩短时间范围、减少字段或在数据源侧聚合。\n- 查询失败使用非 2xx HTTP 状态码和标准错误 envelope。\n- WebAPI 跨实例转发和 Edge 执行合计可能耗时 35 秒。客户端超时建议至少设为 40 秒，并在调用方放弃查询时向下传播取消信号。",
+          "href": "/zh/api-reference/monitors/diagnostics/monit-read-query-data",
+          "metadata": {
+            "sidebarTitle": "查询结构化数据"
+          }
+        },
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {
-                "args": {},
-                "delay_seconds": 0,
-                "ds_name": "prod-prom",
-                "ds_type": "prometheus",
-                "expr": "sum by (job) (rate(http_requests_total[5m]))"
-              },
               "schema": {
                 "$ref": "#/components/schemas/QueryDataRequest"
+              },
+              "example": {
+                "ds_type": "prometheus",
+                "ds_name": "prod-prom",
+                "expr": "sum by (job) (rate(http_requests_total[5m]))",
+                "delay_seconds": 0,
+                "args": {}
               }
             }
-          },
-          "required": true
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/QueryDataResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "format": "query_result.v1",
                     "result": {
@@ -47933,27 +49564,10 @@
                         }
                       ]
                     }
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/QueryDataResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -47965,27 +49579,27 @@
             "$ref": "#/components/responses/Forbidden"
           },
           "413": {
+            "description": "请求或最终响应超过大小限制。",
             "content": {
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ErrorResponse"
                 }
               }
-            },
-            "description": "请求或最终响应超过大小限制。"
+            }
           },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
           "499": {
+            "description": "客户端已取消查询。",
             "content": {
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ErrorResponse"
                 }
               }
-            },
-            "description": "客户端已取消查询。"
+            }
           },
           "500": {
             "$ref": "#/components/responses/ServerError"
@@ -47994,81 +49608,68 @@
             "$ref": "#/components/responses/ServiceUnavailable"
           },
           "504": {
+            "description": "查询超时。",
             "content": {
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ErrorResponse"
                 }
               }
-            },
-            "description": "查询超时。"
-          }
-        },
-        "summary": "查询结构化数据",
-        "tags": [
-          "Monitors/诊断分析"
-        ],
-        "x-mint": {
-          "content": "## 调用限制\n\n| 项 | 值 |\n| ------ | ----- |\n| 速率限制 | 每账户 **100 次/分钟**、**5 次/秒** |\n| 权限 | 任意有效的 `app_key`（只读，不受特定权限分类限制） |\n| Edge 版本要求 | 受支持的部署要求 **monit-edge v0.65.0 或更高版本** |\n\n## 使用说明\n\n- 此公开接口以 **monit-edge v0.65.0** 为最低受支持版本。迁移期间，WebAPI 仍保留旧版 Edge 适配器：query.v2 结果仍可能保留 frames、records 或 samples，而 legacy rows 只能提供其已保留的信息。这些适配器不会改变最低支持版本；旧协议缺少 query.v3 的取消和错误生命周期语义，legacy rows 已丢失的数据也无法恢复。\n- 公开响应格式固定为 `query_result.v1`，与 Edge 内部查询协议版本无关。必须根据 `result.kind`（`frames`、`records` 或 `samples`）分发结果，不要根据 `ds_type` 或 Edge 版本猜测结果形态。\n- `frames` 结果可以包含多个表格或时序 Frame。字段值按列组织，同一 Frame 中所有字段的值数量一致。\n- `records` 结果可以包含嵌套 JSON 和 null record。超出 JavaScript 安全整数范围的整数字面量会以十进制字符串返回。\n- `samples` 结果包含标签集合和瞬时值。值可以是数字，也可以是字符串 `NaN`、`+Inf` 或 `-Inf`。\n- 最终成功响应上限为 8 MiB，查询结果上限为 1,000 行。超限时请缩短时间范围、减少字段或在数据源侧聚合。\n- 查询失败使用非 2xx HTTP 状态码和标准错误 envelope。不要透明回退到已弃用的 `/monit/query/rows` 接口。\n- WebAPI 跨实例转发和 Edge 执行合计可能耗时 35 秒。客户端超时建议至少设为 40 秒，并在调用方放弃查询时向下传播取消信号。",
-          "href": "/zh/api-reference/monitors/diagnostics/monit-read-query-data",
-          "metadata": {
-            "sidebarTitle": "查询结构化数据"
+            }
           }
         }
       }
     },
     "/monit/rule/audit/detail": {
       "post": {
-        "description": "返回审计记录（包含 `content` 字段，即该时间点规则配置的 JSON 字符串快照）。",
         "operationId": "monit-rule-read-audit-detail",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "id": 9001
-              },
-              "schema": {
-                "$ref": "#/components/schemas/AuditRecordIDRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "查看规则审计快照",
+        "description": "返回告警规则的一条审计记录，包含保存在 `content` 中的规则快照。",
+        "tags": [
+          "Monitors/告警规则"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 任意有效 `app_key` 均可调用 |\n\n## 使用说明\n\n- 传入来自 `POST /monit/rule/audits` 的审计记录 `id`（非规则 `id`）。ID 不存在时返回 `InvalidParameter`（`alert rule audit not found`）。\n- `content` 为 JSON 字符串，解析后可获得规则快照；其结构取决于写入该记录的操作（见下方 `content` 字段说明）。\n- 调用者须对规则所在文件夹有管理权限（账户所有者或管理员、该文件夹或其上级文件夹的创建者，或绑定到该文件夹或其上级文件夹的团队成员），否则返回 `AccessDenied`。规则被删除后其审计记录无法再读取，调用返回 `InvalidParameter`（`alert rule not found`）。",
+          "href": "/zh/api-reference/monitors/alert-rules/monit-rule-read-audit-detail",
+          "metadata": {
+            "sidebarTitle": "查看规则审计快照"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "account_id": 10023,
-                    "action": "update",
-                    "alert_rule_id": 50001,
-                    "content": "{\"id\":50001,\"name\":\"CPU High\"}",
-                    "created_at": 1712000000,
-                    "creator_id": 80011,
-                    "creator_name": "Alice",
-                    "id": 9001
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/AlertRuleAudit"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "id": 9001,
+                    "account_id": 888,
+                    "alert_rule_id": 50001,
+                    "action": "update",
+                    "content": "{\"id\":50001,\"account_id\":888,\"folder_id\":100,\"name\":\"CPU High\",\"enabled\":true,\"updated_at\":1712003600}",
+                    "creator_id": 66,
+                    "creator_name": "zhangsan",
+                    "created_at": 1712003600
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -48076,6 +49677,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -48083,72 +49687,81 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "查看规则审计快照",
-        "tags": [
-          "Monitors/告警规则"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **告警规则查看**（`monit`） |\n\n## 使用说明\n\n- 传入来自 `POST /monit/rule/audits` 的审计记录 `id`（非规则 `id`）。\n- `content` 为 JSON 字符串，解析后可获得完整的规则快照。",
-          "href": "/zh/api-reference/monitors/alert-rules/monit-rule-read-audit-detail",
-          "metadata": {
-            "sidebarTitle": "查看规则审计快照"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/AuditRecordIDRequest"
+              },
+              "example": {
+                "id": 9001
+              }
+            }
           }
         }
       }
     },
     "/monit/rule/audits": {
       "post": {
-        "description": "返回告警规则的变更历史（审计记录）。",
         "operationId": "monit-rule-read-audits",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "id": 50001
-              },
-              "schema": {
-                "$ref": "#/components/schemas/RuleIDRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "查询规则变更历史",
+        "description": "返回告警规则的变更历史（审计记录）。",
+        "tags": [
+          "Monitors/告警规则"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 任意有效 `app_key` 均可调用 |\n\n## 使用说明\n\n- 记录按时间倒序排列，不含 `content`；如需查看快照，请调用 `POST /monit/rule/audit/detail`。\n- 每次创建、整体更新、字段批量更新和移动都会写入一条记录。删除规则不会写入记录，且规则删除后无法再列出其历史，调用返回 `InvalidParameter`（`alert rule not found`）。\n- 调用者须对规则所在文件夹有管理权限（账户所有者或管理员、该文件夹或其上级文件夹的创建者，或绑定到该文件夹或其上级文件夹的团队成员），否则返回 `AccessDenied`。",
+          "href": "/zh/api-reference/monitors/alert-rules/monit-rule-read-audits",
+          "metadata": {
+            "sidebarTitle": "查询规则变更历史"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": [
-                    {
-                      "account_id": 10023,
-                      "action": "update",
-                      "alert_rule_id": 50001,
-                      "created_at": 1712000000,
-                      "creator_id": 80011,
-                      "creator_name": "Alice",
-                      "id": 9001
-                    }
-                  ],
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/RuleAuditListResponse"
                         }
-                      },
-                      "type": "object"
+                      }
+                    }
+                  ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": [
+                    {
+                      "id": 9001,
+                      "account_id": 888,
+                      "alert_rule_id": 50001,
+                      "action": "update",
+                      "creator_id": 66,
+                      "creator_name": "zhangsan",
+                      "created_at": 1712003600
+                    },
+                    {
+                      "id": 8990,
+                      "account_id": 888,
+                      "alert_rule_id": 50001,
+                      "action": "create",
+                      "creator_id": 66,
+                      "creator_name": "zhangsan",
+                      "created_at": 1712000000
                     }
                   ]
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -48156,6 +49769,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -48163,62 +49779,64 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "查询规则变更历史",
-        "tags": [
-          "Monitors/告警规则"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **告警规则查看**（`monit`） |",
-          "href": "/zh/api-reference/monitors/alert-rules/monit-rule-read-audits",
-          "metadata": {
-            "sidebarTitle": "查询规则变更历史"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/RuleIDRequest"
+              },
+              "example": {
+                "id": 50001
+              }
+            }
           }
         }
       }
     },
     "/monit/rule/counter/channel": {
       "post": {
-        "description": "返回一个对象，key 为协作空间名称，value 为将告警路由到该协作空间的规则数量。若协作空间名称无法解析，则以协作空间 ID（字符串形式）作为 key。",
         "operationId": "monit-rule-read-counter-channel",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {},
-              "schema": {
-                "$ref": "#/components/schemas/RuleEmptyRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "按协作空间查询规则统计",
+        "description": "按协作空间名称返回将告警路由到各协作空间的告警规则数量。",
+        "tags": [
+          "Monitors/告警规则"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **概览查看**（`monit`） |\n\n## 使用说明\n\n- 仅统计 `channel_ids` 非空的规则；一条规则路由到多个协作空间时，会在每个协作空间下各计一次。\n- 协作空间 ID 无法解析为名称时，以该 ID 的字符串形式作为 key；同名的协作空间会合并到同一个 key。\n- 没有任何规则路由到协作空间时返回空对象 `{}`。",
+          "href": "/zh/api-reference/monitors/alert-rules/monit-rule-read-counter-channel",
+          "metadata": {
+            "sidebarTitle": "按协作空间查询规则统计"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "Production": 8
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/RuleCounterChannelResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "Production": 8
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -48226,6 +49844,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -48233,67 +49854,73 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "按协作空间查询规则统计",
-        "tags": [
-          "Monitors/告警规则"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **告警规则查看**（`monit`） |",
-          "href": "/zh/api-reference/monitors/alert-rules/monit-rule-read-counter-channel",
-          "metadata": {
-            "sidebarTitle": "按协作空间查询规则统计"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/RuleEmptyRequest"
+              },
+              "example": {}
+            }
           }
         }
       }
     },
     "/monit/rule/counter/total": {
       "post": {
-        "description": "返回当前账户下规则总数的历史时序数据，每个 `clock` 时间戳对应一个采样。",
         "operationId": "monit-rule-read-counter-total",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {},
-              "schema": {
-                "$ref": "#/components/schemas/RuleEmptyRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "查看规则数量时序",
+        "description": "返回当前账户下规则总数的历史时序数据，每个 `clock` 时间戳对应一个采样。",
+        "tags": [
+          "Monitors/告警规则"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **概览查看**（`monit`） |\n\n## 使用说明\n\n- 每一项为一次历史快照：`num` 为 `clock`（Unix 时间戳，秒）时刻账户下告警规则的总数（含启用与禁用的规则）。\n- 大约每 12 小时记录一次快照（每小时运行的任务在最近 12 小时内没有快照时补记一条）。返回全部快照，按时间从早到晚排列；尚未记录任何快照时返回空数组。",
+          "href": "/zh/api-reference/monitors/alert-rules/monit-rule-read-counter-total",
+          "metadata": {
+            "sidebarTitle": "查看规则数量时序"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": [
-                    {
-                      "account_id": 10023,
-                      "clock": 1712000000,
-                      "id": 1,
-                      "num": 50
-                    }
-                  ],
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/RuleCounterTotalResponse"
                         }
-                      },
-                      "type": "object"
+                      }
+                    }
+                  ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": [
+                    {
+                      "id": 1,
+                      "account_id": 888,
+                      "num": 48,
+                      "clock": 1711956000
+                    },
+                    {
+                      "id": 2,
+                      "account_id": 888,
+                      "num": 50,
+                      "clock": 1712000000
                     }
                   ]
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -48301,6 +49928,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -48308,62 +49938,60 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "查看规则数量时序",
-        "tags": [
-          "Monitors/告警规则"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **告警规则查看**（`monit`） |\n\n## 使用说明\n\n- 每一项为一次历史快照：`num` 为 `clock`（Unix 时间戳，秒）时刻的规则总数。",
-          "href": "/zh/api-reference/monitors/alert-rules/monit-rule-read-counter-total",
-          "metadata": {
-            "sidebarTitle": "查看规则数量时序"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/RuleEmptyRequest"
+              },
+              "example": {}
+            }
           }
         }
       }
     },
     "/monit/rule/delete": {
       "post": {
-        "description": "通过 ID 删除单条告警规则。",
         "operationId": "monit-rule-write-delete",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "id": 50001
-              },
-              "schema": {
-                "$ref": "#/components/schemas/RuleIDRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "删除告警规则",
+        "description": "通过 ID 删除单条告警规则。",
+        "tags": [
+          "Monitors/告警规则"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **告警规则管理**（`monit`） |\n\n## 使用说明\n\n- 删除规则时会同时清理该规则的活跃告警。\n- 删除不存在的 ID 也会成功并返回空 `data`，因此可以安全重试。\n- 调用者须对规则所在文件夹有管理权限（账户所有者或管理员、该文件夹或其上级文件夹的创建者，或绑定到该文件夹或其上级文件夹的团队成员），否则返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "href": "/zh/api-reference/monitors/alert-rules/monit-rule-write-delete",
+          "metadata": {
+            "sidebarTitle": "删除告警规则"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/RuleEmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -48371,6 +49999,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -48378,65 +50009,62 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "删除告警规则",
-        "tags": [
-          "Monitors/告警规则"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **告警规则管理**（`monit`） |\n\n## 使用说明\n\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
-          "href": "/zh/api-reference/monitors/alert-rules/monit-rule-write-delete",
-          "metadata": {
-            "sidebarTitle": "删除告警规则"
-          }
-        }
-      }
-    },
-    "/monit/rule/delete/batch": {
-      "post": {
-        "description": "在单次请求中删除多条告警规则。",
-        "operationId": "monit-rule-write-delete-batch",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {
-                "ids": [
-                  50001,
-                  50002
-                ]
+              "schema": {
+                "$ref": "#/components/schemas/RuleIDRequest"
               },
-              "schema": {
-                "$ref": "#/components/schemas/RuleIDsRequest"
+              "example": {
+                "id": 50001
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/monit/rule/delete/batch": {
+      "post": {
+        "operationId": "monit-rule-write-delete-batch",
+        "summary": "批量删除告警规则",
+        "description": "在单次请求中删除多条告警规则。",
+        "tags": [
+          "Monitors/告警规则"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **100 次/分钟**；**5 次/秒** |\n| 权限要求 | **告警规则管理**（`monit`） |\n\n## 使用说明\n\n- 按顺序逐个处理 ID，遇到第一个错误即停止；错误前已删除的规则不会恢复，请排除原因后重新提交剩余 ID。\n- 不存在的 ID 会被跳过，不报错。每条被删除规则的活跃告警会被清理。\n- `ids` 至少包含一个 ID。调用者须对每条规则所在的文件夹有管理权限（账户所有者或管理员、该文件夹或其上级文件夹的创建者，或绑定到该文件夹或其上级文件夹的团队成员），否则返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "href": "/zh/api-reference/monitors/alert-rules/monit-rule-write-delete-batch",
+          "metadata": {
+            "sidebarTitle": "批量删除告警规则"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/RuleEmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -48444,6 +50072,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -48451,74 +50082,90 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "批量删除告警规则",
-        "tags": [
-          "Monitors/告警规则"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **30 次/分钟**；**5 次/秒** |\n| 权限要求 | **告警规则管理**（`monit`） |\n\n## 使用说明\n\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
-          "href": "/zh/api-reference/monitors/alert-rules/monit-rule-write-delete-batch",
-          "metadata": {
-            "sidebarTitle": "批量删除告警规则"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/RuleIDsRequest"
+              },
+              "example": {
+                "ids": [
+                  50001,
+                  50002
+                ]
+              }
+            }
           }
         }
       }
     },
     "/monit/rule/list/basic": {
       "post": {
-        "description": "返回指定文件夹下所有告警规则的基础信息。如需完整规则详情，请调用 `POST /monit/rule/v2/info`。",
         "operationId": "monit-rule-read-list",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "folder_id": 100
-              },
-              "schema": {
-                "$ref": "#/components/schemas/RuleListRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "查询告警规则列表",
+        "description": "返回指定文件夹下告警规则的基础信息；如需完整配置，请调用 `POST /monit/rule/v2/info`。",
+        "tags": [
+          "Monitors/告警规则"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **告警规则查看**或**告警规则管理**（`monit`） |\n\n## 使用说明\n\n- `folder_id` 必须是已存在的文件夹：传 `0` 或不存在的 ID 返回 `InvalidParameter`；调用者对该文件夹无管理权限（账户所有者或管理员、该文件夹或其上级文件夹的创建者，或绑定到该文件夹或其上级文件夹的团队成员）时返回 `AccessDenied`。不支持跨文件夹列出整个账户的规则。\n- 默认只返回直接位于该文件夹下的规则，按名称排序，并填充 `active_alert_count` 与 `runtime_state`。\n- `include_descendants` 为 `true` 时会搜索该文件夹及其所有子孙文件夹，按名称排序最多返回 `limit` 条；此时只填充 `id`、`folder_id`、`name`，其余字段为零值（`labels` 为 `null`，不返回 `runtime_state`）。\n- 当且仅当 `active_alert_count > 0` 时 `triggered` 为 `true`。",
+          "href": "/zh/api-reference/monitors/alert-rules/monit-rule-read-list",
+          "metadata": {
+            "sidebarTitle": "查询告警规则列表"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": [
-                    {
-                      "active_alert_count": 2,
-                      "created_at": 1710000000,
-                      "ds_type": "prometheus",
-                      "enabled": true,
-                      "folder_id": 100,
-                      "id": 50001,
-                      "name": "CPU High",
-                      "runtime_state": "normal",
-                      "triggered": true
-                    }
-                  ],
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/RuleBasicListResponse"
                         }
+                      }
+                    }
+                  ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": [
+                    {
+                      "id": 50001,
+                      "account_id": 888,
+                      "folder_id": 100,
+                      "name": "CPU High",
+                      "labels": {
+                        "team": "sre"
                       },
-                      "type": "object"
+                      "ds_type": "prometheus",
+                      "enabled": true,
+                      "debug_log_enabled": false,
+                      "cron_pattern": "0 * * * * *",
+                      "timezone": "Asia/Shanghai",
+                      "delay_seconds": 0,
+                      "creator_id": 66,
+                      "creator_name": "zhangsan",
+                      "updater_id": 66,
+                      "updater_name": "zhangsan",
+                      "created_at": 1710000000,
+                      "updated_at": 1712000000,
+                      "triggered": true,
+                      "active_alert_count": 2,
+                      "runtime_state": "normal"
                     }
                   ]
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -48526,6 +50173,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -48533,71 +50183,71 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "查询告警规则列表",
-        "tags": [
-          "Monitors/告警规则"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **告警规则查看**（`monit`） |\n\n## 使用说明\n\n- 将 `folder_id` 设为 `0` 可列出当前用户有权查看的所有文件夹下的规则。\n- `triggered` 字段表示该规则当前是否有活跃告警。",
-          "href": "/zh/api-reference/monitors/alert-rules/monit-rule-read-list",
-          "metadata": {
-            "sidebarTitle": "查询告警规则列表"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/RuleListRequest"
+              },
+              "example": {
+                "folder_id": 100
+              }
+            }
           }
         }
       }
     },
     "/monit/rule/move": {
       "post": {
-        "description": "将一条或多条告警规则移动到其他文件夹。",
         "operationId": "monit-rule-write-move",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "dest_folder_id": 200,
-                "ids": [
-                  50001,
-                  50002
-                ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/RuleMoveRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "移动告警规则到文件夹",
+        "description": "将一条或多条告警规则移动到其他文件夹。",
+        "tags": [
+          "Monitors/告警规则"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **告警规则管理**（`monit`） |\n\n## 使用说明\n\n- `dest_folder_id` 必须是已存在的文件夹，且调用者须对该文件夹有管理权限（账户所有者或管理员、该文件夹或其上级文件夹的创建者，或绑定到该文件夹或其上级文件夹的团队成员）；否则整个调用返回 `AccessDenied`，不会移动任何规则。\n- 结果按请求顺序为每个 ID 返回一项。移动成功的规则 `message` 为本地化的成功文案（`Move successfully` / `移动成功`）；未移动的规则保留在原文件夹，`message` 为错误信息。\n- 目标文件夹已有同名规则、调用者对规则当前所在文件夹无管理权限，或 ID 不存在（此时 `name` 为 `id: <id>`）时，该规则不会被移动。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "href": "/zh/api-reference/monitors/alert-rules/monit-rule-write-move",
+          "metadata": {
+            "sidebarTitle": "移动告警规则到文件夹"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": [
-                    {
-                      "message": "",
-                      "name": "CPU High"
-                    }
-                  ],
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/RuleNameMessageListResponse"
                         }
-                      },
-                      "type": "object"
+                      }
+                    }
+                  ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": [
+                    {
+                      "name": "CPU High",
+                      "message": "移动成功"
+                    },
+                    {
+                      "name": "Disk High",
+                      "message": "alert rule name already exists in this folder"
                     }
                   ]
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -48605,6 +50255,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -48612,78 +50265,75 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "移动告警规则到文件夹",
-        "tags": [
-          "Monitors/告警规则"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **告警规则管理**（`monit`） |\n\n## 使用说明\n\n- 如果目标文件夹中已存在同名规则，该规则会被跳过；请检查每条结果的 `message` 以识别冲突。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
-          "href": "/zh/api-reference/monitors/alert-rules/monit-rule-write-move",
-          "metadata": {
-            "sidebarTitle": "移动告警规则到文件夹"
-          }
-        }
-      }
-    },
-    "/monit/rule/update/fields": {
-      "post": {
-        "description": "一次性更新多条告警规则的特定字段，仅应用 `fields` 列表中指定的字段。",
-        "operationId": "monit-rule-write-fields-update",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/RuleMoveRequest"
+              },
               "example": {
-                "enabled": false,
-                "fields": [
-                  "enabled"
-                ],
                 "ids": [
                   50001,
                   50002
-                ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/RuleFieldsUpdateRequest"
+                ],
+                "dest_folder_id": 200
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/monit/rule/update/fields": {
+      "post": {
+        "operationId": "monit-rule-write-fields-update",
+        "summary": "批量更新规则字段",
+        "description": "在一次调用中为多条告警规则更新 `fields` 中列出的字段。",
+        "tags": [
+          "Monitors/告警规则"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **告警规则管理**（`monit`） |\n\n## 使用说明\n\n- 每个列出的字段取同名请求字段的值；列出但未传值的字段会被设为零值（例如 `fields` 包含 `labels` 却既不传 `labels` 也不传 `labels_patch`，会清空全部标签）。未列出的字段保持原值。\n- `fields` 中出现未知字段名、传入 `labels_patch` / `annotations_patch` 但 `fields` 未包含对应字段，或同时传入 `labels` 与 `labels_patch`（`annotations` 与 `annotations_patch` 同理）时，整个调用返回 `InvalidParameter`。\n- 规则逐条更新，结果为每个 ID 返回一项：成功时 `message` 为空，否则为该规则的错误信息（校验失败、对其所在文件夹无权限，或 ID 不存在，此时 `name` 为 `id: <id>`）。\n- 将 `enabled` 设为 `false` 会清理这些规则的活跃告警。除非本次调用只是停用规则（`fields` 恰好为 `[\"enabled\"]` 且 `enabled: false`），否则账户规则数超出告警规则 License 上限时返回 `AccessDenied`，且非管理员调用者须对每条规则选中的所有数据源具备只读权限。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "href": "/zh/api-reference/monitors/alert-rules/monit-rule-write-fields-update",
+          "metadata": {
+            "sidebarTitle": "批量更新规则字段"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": [
-                    {
-                      "message": "",
-                      "name": "CPU High"
-                    },
-                    {
-                      "message": "",
-                      "name": "Disk High"
-                    }
-                  ],
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/RuleNameMessageListResponse"
                         }
-                      },
-                      "type": "object"
+                      }
+                    }
+                  ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": [
+                    {
+                      "name": "CPU High",
+                      "message": ""
+                    },
+                    {
+                      "name": "Disk High",
+                      "message": ""
                     }
                   ]
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -48691,6 +50341,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -48698,15 +50351,24 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "批量更新规则字段",
-        "tags": [
-          "Monitors/告警规则"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **告警规则管理**（`monit`） |\n\n## 使用说明\n\n- 在 `fields` 数组中指定要更新的字段名，如 `[\"enabled\", \"channel_ids\"]`。\n- 仅更新指定字段，其他字段保持不变。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
-          "href": "/zh/api-reference/monitors/alert-rules/monit-rule-write-fields-update",
-          "metadata": {
-            "sidebarTitle": "批量更新规则字段"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/RuleFieldsUpdateRequest"
+              },
+              "example": {
+                "ids": [
+                  50001,
+                  50002
+                ],
+                "fields": [
+                  "enabled"
+                ],
+                "enabled": false
+              }
+            }
           }
         }
       }
@@ -48720,7 +50382,7 @@
           "Monitors/告警规则"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **告警规则查看**（`monit`） |\n\n## 使用说明\n\n- `id` 必填且不能为 `0`，否则返回 `InvalidParameter`。\n- 规则不存在时返回 `InvalidParameter`（`alert rule not found`）。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **告警规则查看**或**告警规则管理**（`monit`） |\n\n## 使用说明\n\n- `id` 必填且不能为 `0`，否则返回 `InvalidParameter`。\n- 规则不存在或属于其他账户时返回 `InvalidParameter`（`alert rule not found`）。\n- 不做文件夹级权限校验：具备上述权限的调用者可读取账户内的任意规则。",
           "href": "/zh/api-reference/monitors/alert-rules/monit-rule-read-info-v2",
           "metadata": {
             "sidebarTitle": "获取告警规则详情 V2"
@@ -48762,6 +50424,7 @@
                     "enabled": true,
                     "debug_log_enabled": false,
                     "rule_configs": {
+                      "relate_queries": [],
                       "queries": [
                         {
                           "name": "A",
@@ -48822,6 +50485,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -48853,7 +50519,7 @@
           "Monitors/告警规则"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **告警规则管理**（`monit`） |\n\n## 使用说明\n\n- `name`、`ds_type`、`enabled`、`cron_pattern` 和 `rule_configs.queries` 为必填项；`ds_list`（支持通配符）或 `ds_ids` 必须有一个非空。\n- `enabled` 必须显式传入（包括 `false`），缺失时返回 `InvalidParameter`。\n- `id`、`account_id`、`creator_*`、`updater_*`、`created_at`、`updated_at` 由服务端赋值，客户端传入将被忽略。\n- `name` 在 `folder_id` 内必须唯一；重名会返回 `InvalidParameter`。\n- `channel_ids` 可为空，告警将通过全局集成路由。\n- 请求体容忍额外的未知字段（向前兼容），未知字段会被忽略。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **告警规则管理**（`monit`） |\n\n## 使用说明\n\n- `folder_id`、`name`、`ds_type`、`enabled`、`cron_pattern` 和 `rule_configs.queries` 为必填项；`ds_list`（支持通配符）与 `ds_ids` 至少一个非空。\n- `enabled` 必须显式传入（包括 `false`），缺失时返回 `InvalidParameter`。\n- `folder_id` 必须是已存在的文件夹（否则返回 `InvalidParameter`），且调用者须对该文件夹有管理权限（账户所有者或管理员、该文件夹或其上级文件夹的创建者，或绑定到该文件夹或其上级文件夹的团队成员）（否则返回 `AccessDenied`）。\n- `name` 在 `folder_id` 内必须唯一；重名会返回 `InvalidParameter`。\n- `enabled` 为 `true` 时，`ds_type` 必须是支持告警的数据源类型，且 `ds_ids` 中的每个 ID 都必须是已启用并开启告警的数据源，否则返回 `InvalidParameter`。\n- 账户所有者和管理员以外的调用者，须对 `ds_ids` 中列出的、以及 `ds_list` 当前匹配到的每个数据源具备只读权限，否则返回 `AccessDenied`（`no permission to reference datasource \"<name>\"`）。\n- 创建后若超出账户的告警规则 License 上限，调用返回 `AccessDenied`。\n- `id`、`account_id`、`creator_*`、`updater_*`、`created_at`、`updated_at` 由服务端赋值，客户端传入将被忽略。\n- `channel_ids` 可为空，告警将通过全局集成路由。\n- 请求体不得超过 1 MiB，超出时返回 HTTP 413（`EntityTooLarge`）。请求体中额外的未知字段会被忽略（向前兼容）。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/monitors/alert-rules/monit-rule-write-create-v2",
           "metadata": {
             "sidebarTitle": "创建告警规则 V2"
@@ -48895,6 +50561,7 @@
                     "enabled": true,
                     "debug_log_enabled": false,
                     "rule_configs": {
+                      "relate_queries": [],
                       "queries": [
                         {
                           "name": "A",
@@ -48955,6 +50622,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -49013,7 +50683,7 @@
           "Monitors/告警规则"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **告警规则管理**（`monit`） |\n\n## 使用说明\n\n- `id` 必填且对应规则必须已存在，否则返回 `InvalidParameter`。\n- 本接口为全量字段替换语义：除下列例外外，未传入的字段按零值保存，建议先调用 `/monit/rule/v2/info` 获取完整配置后再修改。\n- `enabled` 必须显式传入（包括 `false`），缺失时返回 `InvalidParameter`；更新为 `false` 时服务端会清理该规则的活跃告警。\n- `investigation_targets` 为例外：省略时保留原配置，传 `[]` 清空，传值则整体替换。\n- `folder_id` 不可通过本接口修改，调整文件夹请使用 `/monit/rule/move`。\n- `account_id`、`creator_*`、`updater_*`、`created_at`、`updated_at` 由服务端维护，传入将被忽略。\n- `name` 在 `folder_id` 内必须唯一；重名会返回 `InvalidParameter`。\n- 请求体容忍额外的未知字段（向前兼容），未知字段会被忽略。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **告警规则管理**（`monit`） |\n\n## 使用说明\n\n- `id` 必填且对应规则必须已存在，否则返回 `InvalidParameter`。\n- 本接口为全量字段替换语义：除下列例外外，未传入的字段按零值保存（随后按默认规则归一，例如 `repeat_interval` 变为 3600），建议先调用 `/monit/rule/v2/info` 获取完整配置后再修改。\n- `enabled` 必须显式传入（包括 `false`），缺失时返回 `InvalidParameter`；更新为 `false` 时服务端会清理该规则的活跃告警。\n- `investigation_targets` 为例外：省略时保留原配置，传 `[]` 清空，传值则整体替换。\n- `folder_id` 不可通过本接口修改，调整文件夹请使用 `/monit/rule/move`。\n- 调用者须对规则所在文件夹有管理权限（账户所有者或管理员、该文件夹或其上级文件夹的创建者，或绑定到该文件夹或其上级文件夹的团队成员），否则返回 `AccessDenied`。\n- `name` 在规则所在文件夹内必须唯一；重名会返回 `InvalidParameter`。\n- `enabled` 为 `true` 时，`ds_type` 必须是支持告警的数据源类型，且 `ds_ids` 中的每个 ID 都必须是已启用并开启告警的数据源，否则返回 `InvalidParameter`。\n- 账户所有者和管理员以外的调用者，须对 `ds_ids` 中列出的、以及 `ds_list` 当前匹配到的每个数据源具备只读权限，否则返回 `AccessDenied`（`no permission to reference datasource \"<name>\"`）。\n- 账户规则数已超出告警规则 License 上限时，调用返回 `AccessDenied`。\n- 处理期间规则被其他请求修改时，返回 HTTP 409（`UndonedOrderExist`，`alert rule was modified; reload and retry`），请重新获取规则后重试。\n- `account_id`、`creator_*`、`updater_*`、`created_at`、`updated_at` 由服务端维护，传入将被忽略。\n- 请求体不得超过 1 MiB，超出时返回 HTTP 413（`EntityTooLarge`）。请求体中额外的未知字段会被忽略（向前兼容）。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/monitors/alert-rules/monit-rule-write-update-v2",
           "metadata": {
             "sidebarTitle": "更新告警规则 V2"
@@ -49055,6 +50725,7 @@
                     "enabled": true,
                     "debug_log_enabled": false,
                     "rule_configs": {
+                      "relate_queries": [],
                       "queries": [
                         {
                           "name": "A",
@@ -49115,6 +50786,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -49167,66 +50841,66 @@
     },
     "/oncall/license/list": {
       "post": {
-        "description": "查询当前账户中正在使用固定或临时 On-call 许可的人员。",
         "operationId": "oncall-license-read-license-list",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {},
-              "schema": {
-                "$ref": "#/components/schemas/EmptyRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "查询 On-call 许可列表",
+        "description": "查询当前账户中正在使用固定或临时 On-call 许可的人员。",
+        "tags": [
+          "On-call/许可管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无——任意有效的 `app_key` 都可以调用此接口 |\n\n## 使用说明\n\n- `items` 仅包含持有固定或临时 On-call 许可的人员。\n- 对临时许可，`updated_by`、`created_at` 和 `updated_at` 均为 `0`。",
+          "href": "/zh/api-reference/on-call/licenses/oncall-license-read-license-list",
+          "metadata": {
+            "sidebarTitle": "查询 On-call 许可列表"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/LicenseListResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01J0D5Y31GY2TWAHRP3Q8K4M6N",
                   "data": {
+                    "total": 2,
                     "items": [
                       {
-                        "created_at": 1719792000,
                         "person_id": 80011,
                         "person_name": "Yuki Zhang",
                         "type": "fixed",
-                        "updated_at": 1719878400,
-                        "updated_by": 80001
+                        "updated_by": 80001,
+                        "created_at": 1719792000,
+                        "updated_at": 1719878400
                       },
                       {
-                        "created_at": 0,
                         "person_id": 80012,
                         "person_name": "Alex Chen",
                         "type": "temporary",
-                        "updated_at": 0,
-                        "updated_by": 0
+                        "updated_by": 0,
+                        "created_at": 0,
+                        "updated_at": 0
                       }
                     ],
-                    "release_limited": false,
-                    "total": 2
-                  },
-                  "request_id": "01J0D5Y31GY2TWAHRP3Q8K4M6N"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/LicenseListResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                    "release_limited": false
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -49234,6 +50908,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -49241,91 +50918,86 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "查询 On-call 许可列表",
-        "tags": [
-          "On-call/许可管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无——任意有效的 `app_key` 都可以调用此接口 |\n\n## 使用说明\n\n- `items` 仅包含持有固定或临时 On-call 许可的人员。\n- 对临时许可，`updated_by`、`created_at` 和 `updated_at` 均为 `0`。",
-          "href": "/zh/api-reference/on-call/licenses/oncall-license-read-license-list",
-          "metadata": {
-            "sidebarTitle": "查询 On-call 许可列表"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/EmptyRequest"
+              },
+              "example": {}
+            }
           }
         }
       }
     },
     "/person/infos": {
       "post": {
-        "description": "根据 ID 批量返回成员或账户的资料信息。",
         "operationId": "personInfos",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "person_ids": [
-                  2476444212131,
-                  3790925372131
-                ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/PersonInfosRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "批量获取人员信息",
+        "description": "根据 ID 批量返回成员或账户的资料信息。",
+        "tags": [
+          "平台/成员管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 传入账户 ID 会返回账户主体，`as` 为 `account`。其他 ID 在本账户成员中查找，包括已删除的成员（`status` 为 `deleted`），因此历史记录里保存的 ID 依然能解析。\n- 重复的 ID 会去重；两者都匹配不上的 ID 会被省略。",
+          "href": "/zh/api-reference/platform/members/person-infos",
+          "metadata": {
+            "sidebarTitle": "批量获取人员信息"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/PersonInfosResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "items": [
                       {
                         "account_id": 2451002751131,
-                        "as": "member",
-                        "avatar": "/image/avatar1.png",
-                        "email": "alice@example.com",
-                        "email_verified": true,
-                        "locale": "zh-CN",
                         "person_id": 2476444212131,
                         "person_name": "Alice",
+                        "avatar": "/image/avatar1.png",
+                        "locale": "zh-CN",
+                        "time_zone": "Asia/Shanghai",
+                        "email": "alice@example.com",
                         "phone_verified": false,
-                        "status": "enabled",
-                        "time_zone": "Asia/Shanghai"
+                        "email_verified": true,
+                        "as": "member",
+                        "status": "enabled"
                       },
                       {
                         "account_id": 2451002751131,
-                        "as": "member",
-                        "email": "bob@example.com",
-                        "email_verified": true,
                         "person_id": 3790925372131,
                         "person_name": "Bob",
+                        "email": "bob@example.com",
                         "phone_verified": false,
+                        "email_verified": true,
+                        "as": "member",
                         "status": "enabled"
                       }
                     ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/PersonInfosResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -49333,6 +51005,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -49340,62 +51015,65 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "批量获取人员信息",
-        "tags": [
-          "平台/成员管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |",
-          "href": "/zh/api-reference/platform/members/person-infos",
-          "metadata": {
-            "sidebarTitle": "批量获取人员信息"
-          }
-        }
-      }
-    },
-    "/role/delete": {
-      "post": {
-        "description": "删除一个自定义角色。当仍有成员持有该角色时，除非 `is_force` 为 true，否则调用失败并返回 `ReferenceExist`。",
-        "operationId": "role-write-delete",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {
-                "role_id": 150
-              },
               "schema": {
-                "$ref": "#/components/schemas/RoleDeleteRequest"
+                "$ref": "#/components/schemas/PersonInfosRequest"
+              },
+              "example": {
+                "person_ids": [
+                  2476444212131,
+                  3790925372131
+                ]
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/role/delete": {
+      "post": {
+        "operationId": "role-write-delete",
+        "summary": "删除角色",
+        "description": "删除自定义角色，可选择先从所有仍持有它的成员身上解除。",
+        "tags": [
+          "平台/角色与权限"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **角色管理**（`organization`） |\n\n## 使用说明\n\n- 仍有成员持有该角色时，调用返回 `400 ReferenceExist`，并在 `data.refs` 中列出这些成员（`kind` 为 `member`）；设置 `is_force` 为 `true` 会先从所有持有成员解除该角色再删除。\n- 被单点登录配置选为默认角色的角色无法删除，即使设置 `is_force` 也一样；在单点登录配置中取消选择前，调用会返回 `400 ReferenceExist`。\n- 角色 ID 不存在或已删除时不做任何操作，调用仍返回成功。\n- 不要传内置角色 ID（`2`、`6`、`8`）：内置角色本身不会被删除，但设置 `is_force: true` 时会把它从所有持有成员身上解除。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "href": "/zh/api-reference/platform/roles-permissions/role-write-delete",
+          "metadata": {
+            "sidebarTitle": "删除角色"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/PlatformEmptyObject"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -49413,62 +51091,62 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "删除角色",
-        "tags": [
-          "平台/角色与权限"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **角色管理**（`organization`） |\n\n## 使用说明\n\n- 内置角色是虚拟数据，永远不会被删除；对内置角色调用等同空操作。\n- 默认（`is_force=false`）情况下，只要还有成员持有该角色，调用就会失败并返回 `ReferenceExist` 错误码，持有成员列在 `data.refs` 中。设置 `is_force=true` 可先从所有持有成员解除该角色再删除。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
-          "href": "/zh/api-reference/platform/roles-permissions/role-write-delete",
-          "metadata": {
-            "sidebarTitle": "删除角色"
-          }
-        }
-      }
-    },
-    "/role/disable": {
-      "post": {
-        "description": "禁用自定义角色，使其停止授予权限。",
-        "operationId": "role-write-disable",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/RoleDeleteRequest"
+              },
               "example": {
                 "role_id": 150
-              },
-              "schema": {
-                "$ref": "#/components/schemas/RoleIDRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/role/disable": {
+      "post": {
+        "operationId": "role-write-disable",
+        "summary": "禁用角色",
+        "description": "将自定义角色置为禁用状态，但不删除它。",
+        "tags": [
+          "平台/角色与权限"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **角色管理**（`organization`） |\n\n## 使用说明\n\n- 只有 `enabled` 状态的角色可以禁用；对已禁用的角色调用会返回 `400 InvalidParameter`。\n- 内置角色（`2`、`6`、`8`）无法禁用：调用返回成功，但不做任何修改。\n- 角色 ID 不存在或已删除时不做任何操作，调用仍返回成功。\n- 禁用角色不会把它从持有该角色的成员身上解除。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "href": "/zh/api-reference/platform/roles-permissions/role-write-disable",
+          "metadata": {
+            "sidebarTitle": "禁用角色"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/PlatformEmptyObject"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -49486,62 +51164,62 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "禁用角色",
-        "tags": [
-          "平台/角色与权限"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **角色管理**（`organization`） |\n\n## 使用说明\n\n- 持有该角色的成员将立即失去其权限。\n- 内置角色始终保持启用状态；对其启用/禁用为静默空操作。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
-          "href": "/zh/api-reference/platform/roles-permissions/role-write-disable",
-          "metadata": {
-            "sidebarTitle": "禁用角色"
-          }
-        }
-      }
-    },
-    "/role/enable": {
-      "post": {
-        "description": "重新启用已被禁用的自定义角色。",
-        "operationId": "role-write-enable",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {
-                "role_id": 150
-              },
               "schema": {
                 "$ref": "#/components/schemas/RoleIDRequest"
+              },
+              "example": {
+                "role_id": 150
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/role/enable": {
+      "post": {
+        "operationId": "role-write-enable",
+        "summary": "启用角色",
+        "description": "重新启用已被禁用的自定义角色。",
+        "tags": [
+          "平台/角色与权限"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **角色管理**（`organization`） |\n\n## 使用说明\n\n- 只有 `disabled` 状态的角色可以启用；对已启用的角色（包括内置角色）调用会返回 `400 InvalidParameter`。\n- 角色 ID 不存在或已删除时不做任何操作，调用仍返回成功。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "href": "/zh/api-reference/platform/roles-permissions/role-write-enable",
+          "metadata": {
+            "sidebarTitle": "启用角色"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/PlatformEmptyObject"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -49559,75 +51237,76 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "启用角色",
-        "tags": [
-          "平台/角色与权限"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **角色管理**（`organization`） |\n\n## 使用说明\n\n- 内置角色始终保持启用状态；对其启用/禁用为静默空操作。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
-          "href": "/zh/api-reference/platform/roles-permissions/role-write-enable",
-          "metadata": {
-            "sidebarTitle": "启用角色"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/RoleIDRequest"
+              },
+              "example": {
+                "role_id": 150
+              }
+            }
           }
         }
       }
     },
     "/role/info": {
       "post": {
-        "description": "按角色 ID 返回单个角色的详细信息。",
         "operationId": "role-read-info",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "role_id": 2
-              },
-              "schema": {
-                "$ref": "#/components/schemas/RoleInfoRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "查看角色详情",
+        "description": "按角色 ID 返回单个角色的详细信息。",
+        "tags": [
+          "平台/角色与权限"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- ID `2`、`6`、`8` 返回内置的 Admin、Responder、Viewer 角色，其 `description` 随请求语言变化。\n- 角色 ID 不存在或已删除时返回 `400 InvalidParameter`。",
+          "href": "/zh/api-reference/platform/roles-permissions/role-read-info",
+          "metadata": {
+            "sidebarTitle": "查看角色详情"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "created_at": 1700000000,
-                    "description": "Account admin with all permissions.",
-                    "editable": false,
-                    "permission_ids": [
-                      101,
-                      102,
-                      201
-                    ],
-                    "role_id": 2,
-                    "role_name": "Account Admin",
-                    "status": "enabled",
-                    "updated_at": 1700000000
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/RoleItem"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "role_id": 2,
+                    "role_name": "Admin",
+                    "description": "Account Administrator, has all account permissions and can assist the main account in managing all affairs.",
+                    "status": "enabled",
+                    "permission_ids": [
+                      101,
+                      102,
+                      201,
+                      701
+                    ],
+                    "editable": false,
+                    "created_at": 1653530940,
+                    "updated_at": 1653530940
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -49635,6 +51314,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -49642,77 +51324,119 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "查看角色详情",
-        "tags": [
-          "平台/角色与权限"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |",
-          "href": "/zh/api-reference/platform/roles-permissions/role-read-info",
-          "metadata": {
-            "sidebarTitle": "查看角色详情"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/RoleInfoRequest"
+              },
+              "example": {
+                "role_id": 2
+              }
+            }
           }
         }
       }
     },
     "/role/list": {
       "post": {
-        "description": "返回当前账户下所有自定义及内置角色。",
         "operationId": "role-read-list",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "asc": false,
-                "orderby": "created_at"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/RoleListRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "查看角色列表",
+        "description": "返回当前账户下所有自定义及内置角色。",
+        "tags": [
+          "平台/角色与权限"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 自定义角色（含启用和禁用）排在前面，按 `orderby`/`asc` 排序；三个内置角色——`2` Admin、`6` Responder、`8` Viewer——追加在末尾（`no_global` 为 true 时不返回），并计入 `total`。\n- 内置角色的 `editable` 为 false，其 `description` 随请求语言变化（`Accept-Language` 请求头，或 `locale`/`lang` 查询参数）。",
+          "href": "/zh/api-reference/platform/roles-permissions/role-read-list",
+          "metadata": {
+            "sidebarTitle": "查看角色列表"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "items": [
-                      {
-                        "created_at": 1700000000,
-                        "description": "",
-                        "editable": false,
-                        "permission_ids": [],
-                        "role_id": 2,
-                        "role_name": "Account Admin",
-                        "status": "enabled",
-                        "updated_at": 1700000000
-                      }
-                    ],
-                    "total": 3
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/RoleListResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "total": 4,
+                    "items": [
+                      {
+                        "role_id": 150,
+                        "role_name": "On-call Manager",
+                        "description": "Manage on-call rotations and incidents.",
+                        "status": "enabled",
+                        "permission_ids": [
+                          501,
+                          502
+                        ],
+                        "editable": true,
+                        "created_at": 1710000000,
+                        "updated_at": 1712000000
+                      },
+                      {
+                        "role_id": 2,
+                        "role_name": "Admin",
+                        "description": "Account Administrator, has all account permissions and can assist the main account in managing all affairs.",
+                        "status": "enabled",
+                        "permission_ids": [
+                          101,
+                          102,
+                          201,
+                          701
+                        ],
+                        "editable": false,
+                        "created_at": 1653530940,
+                        "updated_at": 1653530940
+                      },
+                      {
+                        "role_id": 6,
+                        "role_name": "Responder",
+                        "description": "Responder, has standard permissions except billing center, member management, role management and single sign-on management, suitable for members handling daily operations.",
+                        "status": "enabled",
+                        "permission_ids": [
+                          201,
+                          701
+                        ],
+                        "editable": false,
+                        "created_at": 1653530940,
+                        "updated_at": 1653530940
+                      },
+                      {
+                        "role_id": 8,
+                        "role_name": "Viewer",
+                        "description": "Viewer, has most read-only permissions except audit and onboarding, suitable for members who only need to view data.",
+                        "status": "enabled",
+                        "permission_ids": [
+                          103
+                        ],
+                        "editable": false,
+                        "created_at": 1653530940,
+                        "updated_at": 1653530940
+                      }
+                    ]
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -49720,6 +51444,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -49727,66 +51454,63 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "查看角色列表",
-        "tags": [
-          "平台/角色与权限"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 内置角色（`editable: false`）不可修改或删除。",
-          "href": "/zh/api-reference/platform/roles-permissions/role-read-list",
-          "metadata": {
-            "sidebarTitle": "查看角色列表"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/RoleListRequest"
+              },
+              "example": {
+                "orderby": "created_at",
+                "asc": false
+              }
+            }
           }
         }
       }
     },
     "/role/member/grant": {
       "post": {
-        "description": "将角色授予一个或多个成员，赋予其该角色包含的权限。",
         "operationId": "role-write-grant-role",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "member_ids": [
-                  80011,
-                  80012
-                ],
-                "role_id": 150
-              },
-              "schema": {
-                "$ref": "#/components/schemas/RoleGrantRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "授予成员账户权限",
+        "description": "将角色授予一个或多个成员，赋予其该角色包含的权限。",
+        "tags": [
+          "平台/角色与权限"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **角色管理**（`organization`） |\n\n## 使用说明\n\n- `member_ids` 中的每个 ID 都必须是本账户成员且不能重复，否则返回 `400`，不修改任何人。\n- `role_id` 必须是内置角色或未删除的自定义角色（已禁用的角色也可以），否则返回 `400`。\n- 通过单点登录同步的成员，在单点登录配置将其设为不可编辑时无法修改，调用返回 `400`。\n- 已持有该角色的成员保持不变。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "href": "/zh/api-reference/platform/roles-permissions/role-write-grant-role",
+          "metadata": {
+            "sidebarTitle": "授予成员账户权限"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/PlatformEmptyObject"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -49804,65 +51528,66 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "授予成员账户权限",
-        "tags": [
-          "平台/角色与权限"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **角色管理**（`organization`） |\n\n## 使用说明\n\n- 已持有该角色的成员会被静默跳过。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
-          "href": "/zh/api-reference/platform/roles-permissions/role-write-grant-role",
-          "metadata": {
-            "sidebarTitle": "授予成员账户权限"
-          }
-        }
-      }
-    },
-    "/role/member/revoke": {
-      "post": {
-        "description": "从一个或多个成员处撤销角色授权。",
-        "operationId": "role-write-revoke-role",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/RoleGrantRequest"
+              },
               "example": {
                 "member_ids": [
-                  80011
+                  80011,
+                  80012
                 ],
                 "role_id": 150
-              },
-              "schema": {
-                "$ref": "#/components/schemas/RoleGrantRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/role/member/revoke": {
+      "post": {
+        "operationId": "role-write-revoke-role",
+        "summary": "解除成员账户权限",
+        "description": "从一个或多个成员处撤销角色授权。",
+        "tags": [
+          "平台/角色与权限"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **角色管理**（`organization`） |\n\n## 使用说明\n\n- `member_ids` 中的每个 ID 都必须是本账户成员且不能重复，否则返回 `400`，不修改任何人。\n- `role_id` 必须是内置角色或未删除的自定义角色（已禁用的角色也可以），否则返回 `400`。\n- 通过单点登录同步的成员，在单点登录配置将其设为不可编辑时无法修改，调用返回 `400`。\n- 未持有该角色的成员保持不变；解除成员的最后一个角色后，该成员将没有任何角色。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "href": "/zh/api-reference/platform/roles-permissions/role-write-revoke-role",
+          "metadata": {
+            "sidebarTitle": "解除成员账户权限"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/PlatformEmptyObject"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -49880,70 +51605,71 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "解除成员账户权限",
-        "tags": [
-          "平台/角色与权限"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **角色管理**（`organization`） |\n\n## 使用说明\n\n- 未持有该角色的成员会被静默跳过。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
-          "href": "/zh/api-reference/platform/roles-permissions/role-write-revoke-role",
-          "metadata": {
-            "sidebarTitle": "解除成员账户权限"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/RoleGrantRequest"
+              },
+              "example": {
+                "member_ids": [
+                  80011
+                ],
+                "role_id": 150
+              }
+            }
           }
         }
       }
     },
     "/role/permission/factor/list": {
       "post": {
-        "description": "返回当前成员拥有的权限因子（API、按钮、菜单、URL、页面访问），可按类型过滤。需要成员级凭据——以账户主体身份（如账户级 App Key）调用会被拒绝并返回 400，因为账户主体天然拥有全部权限。",
         "operationId": "role-read-list-permission-factor",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "factor_types": [
-                  "api"
-                ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/PermissionFactorListRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "查看权限因子集合",
+        "description": "列出调用成员通过其角色获得的权限因子。",
+        "tags": [
+          "平台/角色与权限"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 但对调用凭据有要求，见使用说明 |\n\n## 使用说明\n\n- 需要成员凭据：使用账户主体凭据调用会返回 `400 InvalidParameter`，因为账户主体天然拥有全部权限。\n- 权限因子来自调用成员持有的所有角色，并已去重；返回顺序不固定。没有角色的成员得到空数组。\n- `factor_types` 按类型过滤（`api`、`button`、`visit`、`menu`、`url`）；不传则返回全部类型。传入不支持的类型返回 `400`。",
+          "href": "/zh/api-reference/platform/roles-permissions/role-read-list-permission-factor",
+          "metadata": {
+            "sidebarTitle": "查看权限因子集合"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": [
-                    {
-                      "factor_name": "template:read:info",
-                      "factor_type": "api",
-                      "source": "system"
-                    }
-                  ],
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/PermissionFactorListResponse"
                         }
-                      },
-                      "type": "object"
+                      }
+                    }
+                  ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": [
+                    {
+                      "factor_name": "template:read:info",
+                      "factor_type": "api",
+                      "source": "system"
                     }
                   ]
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -49951,6 +51677,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -49958,79 +51687,78 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "查看权限因子集合",
-        "tags": [
-          "平台/角色与权限"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 但凭据必须属于某个成员；以账户主体身份（如账户级 App Key）调用会被拒绝并返回 400 |\n\n## 使用说明\n\n- 权限因子是每个权限的细粒度控制项。\n- `factor_types` 可选值：`api`、`button`、`visit`、`menu`、`url`。",
-          "href": "/zh/api-reference/platform/roles-permissions/role-read-list-permission-factor",
-          "metadata": {
-            "sidebarTitle": "查看权限因子集合"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PermissionFactorListRequest"
+              },
+              "example": {
+                "factor_types": [
+                  "api"
+                ]
+              }
+            }
           }
         }
       }
     },
     "/role/permission/list": {
       "post": {
-        "description": "返回所有可用权限，可按角色 ID 过滤仅返回指定角色已授予的权限。",
         "operationId": "role-read-list-permission",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "role_ids": [
-                  150
-                ],
-                "with_all": true
-              },
-              "schema": {
-                "$ref": "#/components/schemas/RolePermissionListRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "查看角色权限集合",
+        "description": "列出权限项，并标记其中哪些由指定角色授予。",
+        "tags": [
+          "平台/角色与权限"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- `with_all: true` 时返回全部权限，`is_granted` 标记 `role_ids` 中任一角色授予的权限。\n- `with_all` 为 false（默认）时只返回 `role_ids` 授予的权限——不传 `role_ids` 会得到空列表。\n- `permission_name`、`description`、`class` 随请求语言变化（`Accept-Language` 请求头，或 `locale`/`lang` 查询参数）。",
+          "href": "/zh/api-reference/platform/roles-permissions/role-read-list-permission",
+          "metadata": {
+            "sidebarTitle": "查看角色权限集合"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "items": [
-                      {
-                        "class": "On-call",
-                        "description": "View notification templates",
-                        "id": 501,
-                        "is_granted": true,
-                        "permission_name": "Templates Read",
-                        "permission_type": "read",
-                        "scope": "on-call",
-                        "source": "system",
-                        "status": "enabled"
-                      }
-                    ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/RolePermissionListResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "items": [
+                      {
+                        "id": 501,
+                        "permission_name": "Templates Read",
+                        "permission_type": "read",
+                        "description": "View notification templates",
+                        "class": "On-call",
+                        "scope": "on-call",
+                        "status": "enabled",
+                        "is_granted": true,
+                        "source": "system"
+                      }
+                    ]
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -50038,6 +51766,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -50045,70 +51776,68 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "查看角色权限集合",
-        "tags": [
-          "平台/角色与权限"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 传入 `role_ids` 可过滤只返回指定角色已授予的权限。\n- 传入 `with_all: true` 可返回全部权限，并在每项中通过 `is_granted` 标记是否已授予。",
-          "href": "/zh/api-reference/platform/roles-permissions/role-read-list-permission",
-          "metadata": {
-            "sidebarTitle": "查看角色权限集合"
-          }
-        }
-      }
-    },
-    "/role/upsert": {
-      "post": {
-        "description": "创建新的自定义角色或更新已有角色，更新时传入 `role_id`。",
-        "operationId": "role-write-upsert",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/RolePermissionListRequest"
+              },
               "example": {
-                "description": "Manage on-call rotations and incidents.",
-                "permission_ids": [
-                  501,
-                  502
+                "role_ids": [
+                  150
                 ],
-                "role_name": "On-call Manager"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/RoleUpsertRequest"
+                "with_all": true
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/role/upsert": {
+      "post": {
+        "operationId": "role-write-upsert",
+        "summary": "创建或更新角色",
+        "description": "创建新的自定义角色或更新已有角色，更新时传入 `role_id`。",
+        "tags": [
+          "平台/角色与权限"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **角色管理**（`organization`） |\n\n## 使用说明\n\n- 省略 `role_id`（或置为 0）表示创建角色；传入自定义角色的 ID 表示更新。\n- `role_name` 在账户内必须唯一，也不能与内置名称 `Admin`、`Responder`、`Viewer` 重复；冲突时返回 `400`。\n- 更新会同时覆盖 `role_name`、`description`、`permission_ids`：不传 `description` 会清空描述，不传 `permission_ids` 会移除该角色的全部权限。\n- 更新一个已禁用的角色会使其重新启用。\n- `permission_ids` 中的每个 ID 都必须是 `POST /role/permission/list`（`with_all: true`）返回的权限，否则返回 `400`，不做任何修改。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "href": "/zh/api-reference/platform/roles-permissions/role-write-upsert",
+          "metadata": {
+            "sidebarTitle": "创建或更新角色"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "role_id": 150,
-                    "role_name": "On-call Manager"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/RoleUpsertResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "role_id": 150,
+                    "role_name": "On-call Manager"
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -50126,48 +51855,67 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "创建或更新角色",
-        "tags": [
-          "平台/角色与权限"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **角色管理**（`organization`） |\n\n## 使用说明\n\n- 省略 `role_id`（或置为 0）表示创建；传入已有 ID 表示更新。\n- `role_name` 须为 1–39 个字符且在账户内唯一。\n- `permission_ids` 会完整替换角色的权限集合。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
-          "href": "/zh/api-reference/platform/roles-permissions/role-write-upsert",
-          "metadata": {
-            "sidebarTitle": "创建或更新角色"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/RoleUpsertRequest"
+              },
+              "example": {
+                "role_name": "On-call Manager",
+                "description": "Manage on-call rotations and incidents.",
+                "permission_ids": [
+                  501,
+                  502
+                ]
+              }
+            }
           }
         }
       }
     },
     "/route/info": {
       "post": {
-        "description": "获取指定集成的路由规则配置。当集成尚未配置路由规则时返回 null。",
         "operationId": "routeInfo",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "integration_id": 6113996590131
-              },
-              "schema": {
-                "$ref": "#/components/schemas/RouteInfoRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "获取路由规则详情",
+        "description": "返回单个共享集成的路由规则。",
+        "tags": [
+          "On-call/协作空间"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **集成中心查看**（`on-call`） 或 **集成中心管理**（`on-call`） |\n\n## 使用说明\n\n- 集成未配置路由规则时，响应只包含 `request_id`，没有 `data` 字段。\n- `integration_id` 为协作空间专属集成或不存在时返回 `InvalidParameter`。",
+          "href": "/zh/api-reference/on-call/channels/route-info",
+          "metadata": {
+            "sidebarTitle": "获取路由规则详情"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/RouteItem"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
+                    "integration_id": 6113996590131,
                     "cases": [
                       {
-                        "channel_ids": [
-                          2533748993131
-                        ],
-                        "fallthrough": false,
                         "if": [
                           {
                             "key": "labels.check",
@@ -50177,11 +51925,13 @@
                             ]
                           }
                         ],
+                        "channel_ids": [
+                          2533748993131
+                        ],
+                        "fallthrough": false,
                         "routing_mode": "standard"
                       },
                       {
-                        "channel_ids": null,
-                        "fallthrough": false,
                         "if": [
                           {
                             "key": "severity",
@@ -50191,43 +51941,27 @@
                             ]
                           }
                         ],
-                        "name_mapping_label": "labels.service",
-                        "routing_mode": "name_mapping"
+                        "channel_ids": null,
+                        "fallthrough": false,
+                        "routing_mode": "name_mapping",
+                        "name_mapping_label": "labels.service"
                       }
                     ],
-                    "created_at": 1774606136,
-                    "creator_id": 3790925372131,
                     "default": {
                       "channel_ids": [
                         3521074710131
                       ]
                     },
-                    "integration_id": 6113996590131,
                     "status": "enabled",
-                    "updated_at": 1774606136,
+                    "version": 6,
                     "updated_by": 3790925372131,
-                    "version": 6
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/RouteItem"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                    "creator_id": 3790925372131,
+                    "created_at": 1774606136,
+                    "updated_at": 1774606136
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -50235,6 +51969,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -50242,53 +51979,64 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "获取路由规则详情",
-        "tags": [
-          "On-call/协作空间"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **集成中心查看**（`on-call`） 或 **集成中心管理**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/channels/route-info",
-          "metadata": {
-            "sidebarTitle": "获取路由规则详情"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/RouteInfoRequest"
+              },
+              "example": {
+                "integration_id": 6113996590131
+              }
+            }
           }
         }
       }
     },
     "/route/list": {
       "post": {
-        "description": "返回指定集成的路由规则列表。未配置路由规则的集成将不出现在响应中。",
         "operationId": "routeList",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "integration_ids": [
-                  6113996590131,
-                  6113996590132
-                ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ListRoutesRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "查询路由规则列表",
+        "description": "一次返回多个共享集成的路由规则。",
+        "tags": [
+          "On-call/协作空间"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **集成中心查看**（`on-call`） 或 **集成中心管理**（`on-call`） |\n\n## 使用说明\n\n- 未配置路由规则的集成不会出现在 `items` 中。\n- 每个 ID 都必须是存在的共享集成；只要有一个不存在或属于协作空间专属集成，整个请求返回 `InvalidParameter`。",
+          "href": "/zh/api-reference/on-call/channels/route-list",
+          "metadata": {
+            "sidebarTitle": "查询路由规则列表"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/ListRoutesResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "items": [
                       {
+                        "integration_id": 6113996590131,
                         "cases": [
                           {
-                            "channel_ids": [
-                              2533748993131
-                            ],
-                            "fallthrough": false,
                             "if": [
                               {
                                 "key": "labels.check",
@@ -50298,44 +52046,30 @@
                                 ]
                               }
                             ],
+                            "channel_ids": [
+                              2533748993131
+                            ],
+                            "fallthrough": false,
                             "routing_mode": "standard"
                           }
                         ],
-                        "created_at": 1774606136,
-                        "creator_id": 3790925372131,
                         "default": {
                           "channel_ids": [
                             3521074710131
                           ]
                         },
-                        "integration_id": 6113996590131,
                         "status": "enabled",
-                        "updated_at": 1774606136,
+                        "version": 6,
                         "updated_by": 3790925372131,
-                        "version": 6
+                        "creator_id": 3790925372131,
+                        "created_at": 1774606136,
+                        "updated_at": 1774606136
                       }
                     ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/ListRoutesResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -50343,6 +52077,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -50350,85 +52087,64 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "查询路由规则列表",
-        "tags": [
-          "On-call/协作空间"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **集成中心查看**（`on-call`） 或 **集成中心管理**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/channels/route-list",
-          "metadata": {
-            "sidebarTitle": "查询路由规则列表"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ListRoutesRequest"
+              },
+              "example": {
+                "integration_ids": [
+                  6113996590131,
+                  6113996590132
+                ]
+              }
+            }
           }
         }
       }
     },
     "/route/upsert": {
       "post": {
-        "description": "创建或更新集成的路由规则，将告警导向特定协作空间。`cases` 与 `default` 至少需要提供其一。",
         "operationId": "routeUpsert",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "cases": [
-                  {
-                    "channel_ids": [
-                      3521074710131
-                    ],
-                    "fallthrough": false,
-                    "if": [
-                      {
-                        "key": "severity",
-                        "oper": "IN",
-                        "vals": [
-                          "Critical"
-                        ]
-                      }
-                    ],
-                    "routing_mode": "standard"
-                  }
-                ],
-                "default": {
-                  "channel_ids": [
-                    3521074710131
-                  ]
-                },
-                "integration_id": 6113996590131
-              },
-              "schema": {
-                "$ref": "#/components/schemas/UpsertRouteRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "创建或更新路由规则",
+        "description": "创建或整体替换共享集成的路由规则，决定其告警进入哪些协作空间。",
+        "tags": [
+          "On-call/协作空间"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **集成中心管理**（`on-call`） |\n\n## 使用说明\n\n- 整体替换：请求中未出现的 `cases`、`sections`、`default` 会被删除。每次调用 `version` 递增，旧版本保留在路由历史中。\n- `cases` 与 `default` 至少提供其一；`channel_ids` 为空的 `default` 视为未提供。\n- 只有共享集成才有路由规则：`integration_id` 为协作空间专属集成或不存在，或任一协作空间 ID 不存在时，返回 `InvalidParameter`。\n- 集成归属某个团队时，调用者必须是账户所有者或管理员、集成创建者或该团队成员，否则返回 `AccessDenied`。\n- 成功响应只包含 `request_id`，没有 `data` 字段。\n- 每次调用都会记录到账户审计日志。",
+          "href": "/zh/api-reference/on-call/channels/route-upsert",
+          "metadata": {
+            "sidebarTitle": "创建或更新路由规则"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -50436,6 +52152,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -50443,15 +52162,40 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "创建或更新路由规则",
-        "tags": [
-          "On-call/协作空间"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **集成中心管理**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/channels/route-upsert",
-          "metadata": {
-            "sidebarTitle": "创建或更新路由规则"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/UpsertRouteRequest"
+              },
+              "example": {
+                "integration_id": 6113996590131,
+                "cases": [
+                  {
+                    "if": [
+                      {
+                        "key": "severity",
+                        "oper": "IN",
+                        "vals": [
+                          "Critical"
+                        ]
+                      }
+                    ],
+                    "channel_ids": [
+                      3521074710131
+                    ],
+                    "fallthrough": false,
+                    "routing_mode": "standard"
+                  }
+                ],
+                "default": {
+                  "channel_ids": [
+                    3521074710131
+                  ]
+                }
+              }
+            }
           }
         }
       }
@@ -50530,6 +52274,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -50542,7 +52289,7 @@
           "RUM/应用管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **应用管理**（`rum`） |\n\n## 使用说明\n\n- `type` 须为以下之一：`browser`、`ios`、`android`、`react-native`、`flutter`、`kotlin-multiplatform`、`roku`、`unity`、`miniprogram`、`harmony`、`electron`。\n- `links.systems[].url` 必须以 `http` 或 `https` 开头；`${var}` 变量会根据 RUM 事件上下文解析。\n- `links.systems[].event_types` 支持：`crash`、`error`、`view`、`action`、`resource`、`session`、`all`。\n- `client_token` 自动生成，用于初始化 RUM SDK。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **应用管理**（`rum`） |\n\n## 使用说明\n\n- `type` 须为以下之一：`browser`、`ios`、`android`、`react-native`、`flutter`、`kotlin-multiplatform`、`roku`、`unity`、`miniprogram`、`harmony`、`electron`。\n- `client_token` 由服务端生成，用于初始化 RUM SDK；之后也可通过 `POST /rum/application/info` 再次获取。\n- 传入 `tracing` 时，即使 `enabled` 为 `false`，也必须提供 `open_type`（`popup` 或 `tab`）和以 `http`/`https` 开头的 `endpoint`。\n- `links.systems[].url` 必须以 `http` 或 `https` 开头；每个系统都需要 `name` 和至少一个 `event_types`。\n- `alerting.delivery_mode` 为 `oncall`（Flashduty 云端默认值）时，服务端会创建或复用账户的 RUM 告警集成，并在 `alerting.integration_id` 中返回其 ID。\n- 服务端不校验 `team_id` 是否为调用者所在的团队。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/rum/applications/rum-application-write-create",
           "metadata": {
             "sidebarTitle": "创建应用"
@@ -50600,6 +52347,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -50612,7 +52362,7 @@
           "RUM/应用管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **应用管理**（`rum`） |\n\n## 使用说明\n\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **应用管理**（`rum`） |\n\n## 使用说明\n\n- 删除为软删除：应用会从列表、详情和批量详情中消失，之后使用该 ID 的调用会失败（返回 `InvalidParameter`，远程配置相关接口返回 `ResourceNotFound`）。没有恢复接口。\n- 应用的 `client_token` 会在约 5 分钟内被数据接入端拒绝；已采集的数据不会被删除。\n- 调用者须对该应用有编辑权：账户所有者、账户管理员、应用创建者或所属团队成员，否则返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/rum/applications/rum-application-write-delete",
           "metadata": {
             "sidebarTitle": "删除应用"
@@ -50649,7 +52399,8 @@
                         2490121812131
                       ],
                       "enabled": true,
-                      "integration_id": 4759595678131
+                      "integration_id": 4759595678131,
+                      "delivery_mode": "oncall"
                     },
                     "application_id": "WoyQQ3BohkdtPivubEvE8o",
                     "application_name": "flashcat-rum",
@@ -50685,7 +52436,13 @@
                     },
                     "type": "browser",
                     "updated_at": 1773398630657,
-                    "updated_by": 3790925372131
+                    "updated_by": 3790925372131,
+                    "repositories": [
+                      {
+                        "repo": "acme/web-app",
+                        "subdir": "apps/web"
+                      }
+                    ]
                   },
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 },
@@ -50714,6 +52471,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -50726,7 +52486,7 @@
           "RUM/应用管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- `application_id` 不存在或已删除时返回 `InvalidParameter`。\n- 私有应用（`is_private: true`）仅账户所有者、账户管理员、应用创建者和所属团队成员可读，其他人返回 `AccessDenied`。",
           "href": "/zh/api-reference/rum/applications/rum-application-read-info",
           "metadata": {
             "sidebarTitle": "查看应用详情"
@@ -50769,7 +52529,8 @@
                             5967875767131
                           ],
                           "enabled": true,
-                          "integration_id": 4759595678131
+                          "integration_id": 4759595678131,
+                          "delivery_mode": "oncall"
                         },
                         "application_id": "eWbr4xk3ZRnLabRa6unqwD",
                         "application_name": "Flashduty DEV",
@@ -50792,7 +52553,8 @@
                         },
                         "type": "browser",
                         "updated_at": 1772096392711,
-                        "updated_by": 3122470302131
+                        "updated_by": 3122470302131,
+                        "repositories": []
                       },
                       {
                         "account_id": 2451002751131,
@@ -50801,7 +52563,8 @@
                             2490121812131
                           ],
                           "enabled": true,
-                          "integration_id": 4759595678131
+                          "integration_id": 4759595678131,
+                          "delivery_mode": "oncall"
                         },
                         "application_id": "WoyQQ3BohkdtPivubEvE8o",
                         "application_name": "flashcat-rum",
@@ -50837,7 +52600,8 @@
                         },
                         "type": "browser",
                         "updated_at": 1773398630657,
-                        "updated_by": 3790925372131
+                        "updated_by": 3790925372131,
+                        "repositories": []
                       }
                     ]
                   },
@@ -50868,6 +52632,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -50880,7 +52647,7 @@
           "RUM/应用管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 每次请求最多传入 200 个 ID。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 重复的 ID 会被去重；不存在或已删除的 ID 会被直接跳过而不报错，因此 `items` 可能比 `application_ids` 短。\n- `items` 的顺序不保证与 `application_ids` 一致。",
           "href": "/zh/api-reference/rum/applications/rum-application-read-infos",
           "metadata": {
             "sidebarTitle": "批量查询应用详情"
@@ -50923,7 +52690,8 @@
                             2490121812131
                           ],
                           "enabled": true,
-                          "integration_id": 4759595678131
+                          "integration_id": 4759595678131,
+                          "delivery_mode": "oncall"
                         },
                         "application_id": "WoyQQ3BohkdtPivubEvE8o",
                         "application_name": "flashcat-rum",
@@ -50959,7 +52727,8 @@
                         },
                         "type": "browser",
                         "updated_at": 1773398630657,
-                        "updated_by": 3790925372131
+                        "updated_by": 3790925372131,
+                        "repositories": []
                       },
                       {
                         "account_id": 2451002751131,
@@ -50969,7 +52738,8 @@
                             5967875767131
                           ],
                           "enabled": true,
-                          "integration_id": 4759595678131
+                          "integration_id": 4759595678131,
+                          "delivery_mode": "oncall"
                         },
                         "application_id": "eWbr4xk3ZRnLabRa6unqwD",
                         "application_name": "Flashduty DEV",
@@ -50992,7 +52762,8 @@
                         },
                         "type": "browser",
                         "updated_at": 1772096392711,
-                        "updated_by": 3122470302131
+                        "updated_by": 3122470302131,
+                        "repositories": []
                       }
                     ],
                     "total": 7
@@ -51024,6 +52795,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -51036,7 +52810,7 @@
           "RUM/应用管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 使用 `is_my_team` 可过滤当前用户所在团队的应用。\n- 默认每页 20 条，最大 100 条。\n- `orderby` 支持 `created_at` 或 `updated_at`。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 调用者无权访问的私有应用不会出现在结果中；账户所有者和账户管理员可以看到全部应用。\n- `is_my_team: true` 只保留调用者所在团队拥有的应用；调用者不属于任何团队时，该过滤不生效。\n- `team_id`、`query`、`is_my_team` 之间是“与”关系。\n- 默认按 `updated_at` 倒序排列，可用 `orderby`/`asc` 调整。",
           "href": "/zh/api-reference/rum/applications/rum-application-read-list",
           "metadata": {
             "sidebarTitle": "查询应用列表"
@@ -51125,6 +52899,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -51137,7 +52914,7 @@
           "RUM/应用管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- `version` 为 `0` 表示该应用从未配置过远程配置，SDK 完全沿用初始化值。\n- 变更在客户端下一次会话开始时生效（`activation` 为 `immediate` 时立即生效）。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 首次发布前，`version` 和 `updated_at` 为 `0`，`config` 为 `null`；此时 SDK 完全使用初始化参数。\n- 除非 `activation` 为 `immediate`，变更在客户端下一个会话开始时生效。\n- `application_id` 不存在或已删除时返回 `ResourceNotFound`。私有应用（`is_private: true`）仅账户所有者、账户管理员、应用创建者和所属团队成员可读，其他人返回 `AccessDenied`。",
           "href": "/zh/api-reference/rum/applications/rum-application-remote-config-read-get",
           "metadata": {
             "sidebarTitle": "查看远程配置详情"
@@ -51203,12 +52980,13 @@
                             }
                           ]
                         },
-                        "content_hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
-                        "reason": "Tighten replay sampling for the Q4 launch",
+                        "content_hash": "9f86d081884c7d65",
+                        "reason": "Re-apply the v7 sampling after the test",
                         "updated_at": 1773398630657,
                         "updated_by": 4441703362131,
                         "updated_by_name": "Alice Zhang",
-                        "version": 8
+                        "version": 8,
+                        "equivalent_to": 7
                       },
                       {
                         "config": {
@@ -51239,7 +53017,7 @@
                             }
                           ]
                         },
-                        "content_hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
+                        "content_hash": "9f86d081884c7d65",
                         "reason": "",
                         "updated_at": 1772398630657,
                         "updated_by": 4441703362131,
@@ -51276,6 +53054,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -51288,7 +53069,7 @@
           "RUM/应用管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 默认按更新时间倒序（`orderby=updated_at`，`asc=false`）。\n- 内容相同的版本通过 `content_hash` 与 `equivalent_to` 标识，控制台据此提示\"这是某历史版本的相同内容\"。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 仅保留最近 50 个版本；发布新版本时更早的版本会被删除，之后无法再列出或回滚到这些版本。\n- 默认按最新在前排序（`orderby=updated_at`、`asc=false`）。无法识别的 `orderby` 会回退为 `updated_at`；时间相同则按 `version` 排序。\n- `content_hash` 和 `equivalent_to` 用于识别内容相同的版本，例如回滚后恢复的早期版本。",
           "href": "/zh/api-reference/rum/applications/rum-application-remote-config-read-history-list",
           "metadata": {
             "sidebarTitle": "查询远程配置历史列表"
@@ -51350,6 +53131,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -51362,7 +53146,7 @@
           "RUM/应用管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **应用管理**（`rum`） |\n\n## 使用说明\n\n- 回滚不会重写历史：旧版本内容会以新的版本号发布。\n- `reason` 留空时控制台会自动填入\"rolled back to vN\"。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **应用管理**（`rum`） |\n\n## 使用说明\n\n- 历史记录不会被改写：回滚会把早期版本的内容以新的版本号重新发布，并返回该版本号。\n- `version` 必须仍在保留的历史中（最近 50 个版本），否则返回 `InvalidParameter`（`version not found`）。\n- 恢复的内容会按当前规则重新校验，不再通过时返回 `InvalidParameter`。\n- 服务端不会自动生成 `reason`；未传时保存为空字符串。\n- 调用者须对该应用有编辑权：账户所有者、账户管理员、应用创建者或所属团队成员，否则返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/rum/applications/rum-application-remote-config-write-history-revert",
           "metadata": {
             "sidebarTitle": "回滚远程配置版本"
@@ -51430,6 +53214,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -51442,7 +53229,7 @@
           "RUM/应用管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 使用与引擎完全相同的匹配逻辑，结果与生产客户端实际获取一致。\n- 省略 `config` 时预览当前生效配置。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 使用与 SDK 配置下发端相同的规则匹配逻辑，不会发布任何内容。\n- 不传 `config` 则预览线上配置；传入的 `config` 会按更新接口的规则校验，不合法时返回 `InvalidParameter`。\n- 规则条件按字符串精确比较；请求中省略 `env`、`app_version` 或 `sdk` 时，依赖该字段的规则一定不命中。\n- 配置已关闭（`enabled: false`）或从未发布时，`values` 为空，`hit_rule_index` 为 `-1`。",
           "href": "/zh/api-reference/rum/applications/rum-application-remote-config-read-preview",
           "metadata": {
             "sidebarTitle": "预览远程配置"
@@ -51531,6 +53318,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -51543,7 +53333,7 @@
           "RUM/应用管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **应用管理**（`rum`） |\n\n## 使用说明\n\n- 必须提交完整配置对象而非增量补丁——规则顺序即优先级，部分更新没有无歧义的解释。\n- 每次调用都会分配新版本号，并在同一事务中写入历史记录。\n- 发布前可先调用 `POST /rum/application/remote-config/preview` 验证客户端将拿到的值。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **应用管理**（`rum`） |\n\n## 使用说明\n\n- 需提交完整配置而非增量补丁：规则顺序即优先级，部分更新没有明确含义。\n- 每次调用都会发布一个新版本，即使内容未变或 `enabled` 为 `false`；仅保留最近 50 个版本。\n- 发布前可先调用 `POST /rum/application/remote-config/preview` 检查客户端会拿到的值。\n- 调用者须对该应用有编辑权：账户所有者、账户管理员、应用创建者或所属团队成员，否则返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/rum/applications/rum-application-remote-config-write-update",
           "metadata": {
             "sidebarTitle": "更新远程配置"
@@ -51553,7 +53343,7 @@
     },
     "/rum/application/update": {
       "post": {
-        "description": "更新已有 RUM 应用，除 `application_id` 外均为可选，仅更新提供的字段。",
+        "description": "更新 RUM 应用的指定字段；请求中未出现的字段保持原值。",
         "operationId": "rum-application-write-update",
         "requestBody": {
           "content": {
@@ -51625,6 +53415,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -51637,7 +53430,7 @@
           "RUM/应用管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **应用管理**（`rum`） |\n\n## 使用说明\n\n- `links.systems[].url` 必须以 `http` 或 `https` 开头；`${var}` 变量会根据 RUM 事件上下文解析。\n- `links.systems[].event_types` 支持：`crash`、`error`、`view`、`action`、`resource`、`session`、`all`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **应用管理**（`rum`） |\n\n## 使用说明\n\n- 只修改请求中出现的字段。传入 `alerting`、`tracing`、`links` 时会整体替换已保存的对象；`repositories` 会整体替换列表。\n- 传入 `tracing` 时，即使 `enabled` 为 `false`，也必须提供 `open_type`（`popup` 或 `tab`）和以 `http`/`https` 开头的 `endpoint`。\n- `links.systems[].url` 必须以 `http` 或 `https` 开头；每个系统都需要 `name` 和至少一个 `event_types`。\n- 传入 `alerting` 且 `delivery_mode` 为 `oncall` 时，沿用已有的 `integration_id`（没有则分配一个），客户端传入的 `integration_id` 会被忽略。\n- `application_id` 不存在或已删除时返回 `InvalidParameter`。调用者须对该应用有编辑权：账户所有者、账户管理员、应用创建者或所属团队成员，否则返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/rum/applications/rum-application-write-update",
           "metadata": {
             "sidebarTitle": "更新应用"
@@ -51653,7 +53446,7 @@
           "content": {
             "application/json": {
               "example": {
-                "application_id": "rum-app-prod",
+                "application_id": "WoyQQ3BohkdtPivubEvE8o",
                 "webhook_url": "https://hooks.example.com/rum-alerts"
               },
               "schema": {
@@ -51715,7 +53508,7 @@
           "RUM/应用管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **应用管理**（`rum`） |\n\n## 使用说明\n\n- 接口会先校验 URL，再发送样例事件。\n- 投递失败时仍返回 HTTP 200，但 `ok=false`，错误原因在 `message` 中。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- URL 必须使用 `http` 或 `https`；在 Flashduty 云端，解析到私有、回环、链路本地或保留地址的主机会被拒绝并返回 `InvalidParameter`。\n- 样例请求体与真实告警事件结构相同：`account_id`、`data_source_type`（`rum.alert`）、`title`、`event_severity`、`event_status`、`description`、`alert_key`、`labels` 以及 `event_time`（Unix 秒）。\n- 每次尝试 10 秒超时；传输错误、5xx 和 429 响应最多重试 2 次。\n- 投递失败时仍返回 HTTP 200，`ok` 为 `false`，原因在 `message` 中。\n- 调用者须对该应用有编辑权：账户所有者、账户管理员、应用创建者或所属团队成员，否则返回 `AccessDenied`。",
           "href": "/zh/api-reference/rum/applications/rum-application-webhook-test",
           "metadata": {
             "sidebarTitle": "测试应用 Webhook"
@@ -51736,8 +53529,7 @@
                   {
                     "format": "table",
                     "id": "errors_by_type",
-                    "sql": "SELECT error.type, count(*) AS errors FROM error GROUP BY error.type ORDER BY errors DESC LIMIT 10",
-                    "time_zone": "Asia/Shanghai"
+                    "sql": "SELECT error_type, count(*) AS errors FROM errors GROUP BY error_type ORDER BY errors DESC LIMIT 10"
                   }
                 ],
                 "start_time": 1712620800000
@@ -51759,23 +53551,23 @@
                       "data": {
                         "fields": [
                           {
-                            "name": "error.type",
-                            "nullable": false,
-                            "type": "String"
+                            "name": "error_type",
+                            "nullable": true,
+                            "type": "VARCHAR"
                           },
                           {
                             "name": "errors",
                             "nullable": false,
-                            "type": "UInt64"
+                            "type": "BIGINT"
                           }
                         ],
                         "values": [
                           [
                             "TypeError",
-                            1523
+                            "ReferenceError"
                           ],
                           [
-                            "ReferenceError",
+                            1523,
                             342
                           ]
                         ]
@@ -51809,6 +53601,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -51821,7 +53616,7 @@
           "RUM/RUM 数据查询"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 单次请求可提交 1 到 10 个查询；每个查询的 `id` 会成为响应对象中的 key。\n- `start_time` 和 `end_time` 必填，均为 Unix 毫秒时间戳；最大时间范围为 31 天。\n- 使用 `format: table` 返回表格结果，使用 `format: time_series` 返回按时间桶聚合的时序结果。\n- 当 `format: time_series` 时，省略 `interval` 会默认使用 3600 秒，省略 `max_points` 会默认使用 1226。\n- 分页表格查询会返回 `search_after_ctx`，继续扫描时可原样传回。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 单次请求可提交 1 到 10 个查询；每个查询的 `id` 会成为响应对象中的 key。\n- `start_time`、`end_time` 为 Unix 毫秒时间戳，跨度不超过 31 天。服务端会自动追加时间范围与账户过滤条件，`sql` 中无需再写。\n- `FROM` 填写 RUM 数据表名：`sessions`、`views`、`actions`、`errors`、`resources`、`long_tasks`、`vitals`、`issues` 或 `sourcemaps`（也接受单数形式）。列名即 `POST /rum/field/list` 返回的 `field_key`。\n- 若查询在顶层 `AND` 条件中用 `=` 或 `IN` 限定了 `application_id`，调用者必须能读取这些应用：所属团队不包含调用者的私有应用会让整个请求返回 `AccessDenied`，不存在的应用返回 `ResourceNotFound`，单次请求最多涉及 50 个不同应用。未限定应用的查询会自动跳过调用者无权读取的私有应用。\n- SQL 语法错误、`time_zone` 无效或时间范围不合法时，整个请求返回 `InvalidParameter`。之后阶段才失败的查询（表或列不存在、`dql` 无效、`search_after_ctx` 无效、数据库报错）只在该查询自己的结果中返回 `error`，错误码为 `InternalError`，其他查询仍正常返回 `data`。\n- `values` 按列组织：`values[i]` 是列 `fields[i]` 在所有行上的取值。\n- `table` 查询最多返回 1,000 行；未写 `LIMIT` 或超过 1,000 时按 1,000 处理。不含聚合、带 `ORDER BY` 且没有 `OFFSET` 的查询在本页取满时会返回 `search_after_ctx`，用相同的 `sql` 带上它即可取下一页。\n- `time_series` 查询会在最前面插入 `ts` 列（时间桶起点，Unix 毫秒），并按它分组、排序。桶宽以毫秒在 `interval` 中返回，取值为固定档位（1、2、5、10、20、50、100、200、500 毫秒；1、2、5、10、15、30 秒；1、2、5、10、15、30 分钟；1、2、3、6、12 小时；1、2、3、7 天；30、60、90、180 天）中同时不小于 `interval` 和「时间跨度 ÷ `max_points`」的最小一档。\n- 时间跨度较大时，聚合查询可能基于抽样数据执行；此时响应带有 `sampling`，且 `COUNT`、`SUM`、`COUNT(DISTINCT)` 列已乘以 `scale_factor`。设置 `disable_sampling: true` 可始终查询全量数据。",
           "href": "/zh/api-reference/rum/data-query/rum-read-data-query",
           "metadata": {
             "sidebarTitle": "查询 RUM 数据"
@@ -51831,43 +53626,36 @@
     },
     "/rum/error-ingestion/rules/create": {
       "post": {
-        "description": "创建一条新的错误采集规则，用于过滤要存储的错误。",
+        "description": "创建一条错误采集规则：命中的错误不再归入任何问题（Issue），但仍会照常入库。",
         "operationId": "rum-error-ingestion-rules-create",
         "requestBody": {
           "content": {
             "application/json": {
               "example": {
                 "application_id": "WoyQQ3BohkdtPivubEvE8o",
-                "description": "Only ingest TypeError/ReferenceError from production, excluding Safari.",
+                "description": "Keep cross-origin script errors, ResizeObserver warnings, and debug pages out of issues.",
                 "filters": [
                   [
                     {
-                      "key": "error.env",
-                      "oper": "IN",
-                      "vals": [
-                        "production"
-                      ]
-                    },
-                    {
-                      "key": "error.error_type",
+                      "key": "error.error_message",
                       "oper": "IN",
                       "vals": [
-                        "TypeError",
-                        "ReferenceError"
+                        "Script error.",
+                        "ResizeObserver loop*"
                       ]
                     }
                   ],
                   [
                     {
-                      "key": "error.browser_name",
-                      "oper": "NOTIN",
+                      "key": "error.view_url",
+                      "oper": "IN",
                       "vals": [
-                        "Safari"
+                        "https://example.com/debug/*"
                       ]
                     }
                   ]
                 ],
-                "rule_name": "Production console errors"
+                "rule_name": "Ignore browser noise"
               },
               "schema": {
                 "$ref": "#/components/schemas/RumErrorIngestionCreateRequest"
@@ -51883,7 +53671,7 @@
                 "example": {
                   "data": {
                     "rule_id": "9spXEVoMeZWujjz25yrgTe",
-                    "rule_name": "Production console errors"
+                    "rule_name": "Ignore browser noise"
                   },
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 },
@@ -51912,6 +53700,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -51924,7 +53715,7 @@
           "RUM/错误采集规则"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 创建、更新、启用、禁用、删除都会先把应用当前的全部规则快照进历史记录，因此 `history/list` 会反映每一次变更。\n- `filters` 中的每个条件 key 必须是受支持的 `error.*` 字段或 `context.*` 路径，不支持的 key 会返回 `InvalidParameter`。\n- 新建规则的初始状态为 `enabled`；如需创建后即处于停用状态，需再调用一次 `disable`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 命中的错误仍会入库、可正常查询，只是不会被归入任何问题，且其 `issue_grouping_excluded` 字段为 `true`。\n- 规则匹配的是 SDK 上报的原始错误类型和错误信息，发生在服务端解析堆栈之前。\n- `filters` 中每个条件的 key 必须是受支持的 `error.*` 字段或 `context.*` 路径；key 不受支持、操作符无效、`vals` 为空，或正则/CIDR/数值模式无效时，返回 `InvalidParameter`。\n- 新建规则的初始状态为 `enabled`；如需创建后即处于停用状态，需再调用一次 `disable`。\n- 每次写操作都会先把应用变更前的完整规则集合保存为一个新的历史版本。\n- 采集端按应用缓存已启用的规则，缓存有效期 5 秒，因此变更最多约 5 秒后对新上报的错误生效。\n- 需要对该应用有编辑权限（账户所有者或管理员、应用创建者、应用所属团队的成员），否则返回 `AccessDenied`；`application_id` 不存在时返回 `ResourceNotFound`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/rum/error-ingestion-rules/rum-error-ingestion-rules-create",
           "metadata": {
             "sidebarTitle": "创建错误采集规则"
@@ -51983,6 +53774,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -51995,7 +53789,7 @@
           "RUM/错误采集规则"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 删除后规则会立即从 `list` 结果中消失；但用于过滤判定的启用规则集有最多 5 秒缓存，因此删除后数秒内上报的错误仍可能被该规则匹配。\n- 若 `rule_id` 在该 `application_id` 下不存在，返回 `ResourceNotFound`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 删除后规则会立即从 `list` 结果中消失，且无法再启用或更新；如需恢复，可回滚到仍包含该规则的历史版本。\n- 若 `rule_id` 在该 `application_id` 下不存在（或已删除），返回 `ResourceNotFound`。\n- 每次写操作都会先把应用变更前的完整规则集合保存为一个新的历史版本。\n- 采集端按应用缓存已启用的规则，缓存有效期 5 秒，因此变更最多约 5 秒后对新上报的错误生效。\n- 需要对该应用有编辑权限（账户所有者或管理员、应用创建者、应用所属团队的成员），否则返回 `AccessDenied`；`application_id` 不存在时返回 `ResourceNotFound`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/rum/error-ingestion-rules/rum-error-ingestion-rules-delete",
           "metadata": {
             "sidebarTitle": "删除错误采集规则"
@@ -52054,6 +53848,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -52066,7 +53863,7 @@
           "RUM/错误采集规则"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 禁用的规则会保留并仍出现在 `list` 结果中，但不再参与错误匹配。\n- 若 `rule_id` 在该 `application_id` 下不存在，返回 `ResourceNotFound`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 禁用的规则会保留并仍出现在 `list` 结果中，但不再参与错误匹配。\n- 若 `rule_id` 在该 `application_id` 下不存在（或已删除），返回 `ResourceNotFound`。\n- 每次写操作都会先把应用变更前的完整规则集合保存为一个新的历史版本。\n- 采集端按应用缓存已启用的规则，缓存有效期 5 秒，因此变更最多约 5 秒后对新上报的错误生效。\n- 需要对该应用有编辑权限（账户所有者或管理员、应用创建者、应用所属团队的成员），否则返回 `AccessDenied`；`application_id` 不存在时返回 `ResourceNotFound`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/rum/error-ingestion-rules/rum-error-ingestion-rules-disable",
           "metadata": {
             "sidebarTitle": "禁用错误采集规则"
@@ -52125,6 +53922,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -52137,7 +53937,7 @@
           "RUM/错误采集规则"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 若 `rule_id` 在该 `application_id` 下不存在，返回 `ResourceNotFound`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 对已启用的规则再次启用也会成功，并同样生成一个历史版本。\n- 若 `rule_id` 在该 `application_id` 下不存在（或已删除），返回 `ResourceNotFound`。\n- 每次写操作都会先把应用变更前的完整规则集合保存为一个新的历史版本。\n- 采集端按应用缓存已启用的规则，缓存有效期 5 秒，因此变更最多约 5 秒后对新上报的错误生效。\n- 需要对该应用有编辑权限（账户所有者或管理员、应用创建者、应用所属团队的成员），否则返回 `AccessDenied`；`application_id` 不存在时返回 `ResourceNotFound`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/rum/error-ingestion-rules/rum-error-ingestion-rules-enable",
           "metadata": {
             "sidebarTitle": "启用错误采集规则"
@@ -52182,38 +53982,31 @@
                             "created_at": 1786000000000,
                             "created_by": 1001,
                             "deleted_at": 0,
-                            "description": "Only ingest TypeError/ReferenceError from production, excluding Safari.",
+                            "description": "Keep cross-origin script errors, ResizeObserver warnings, and debug pages out of issues.",
                             "filters": [
                               [
                                 {
-                                  "key": "error.env",
-                                  "oper": "IN",
-                                  "vals": [
-                                    "production"
-                                  ]
-                                },
-                                {
-                                  "key": "error.error_type",
+                                  "key": "error.error_message",
                                   "oper": "IN",
                                   "vals": [
-                                    "TypeError",
-                                    "ReferenceError"
+                                    "Script error.",
+                                    "ResizeObserver loop*"
                                   ]
                                 }
                               ],
                               [
                                 {
-                                  "key": "error.browser_name",
-                                  "oper": "NOTIN",
+                                  "key": "error.view_url",
+                                  "oper": "IN",
                                   "vals": [
-                                    "Safari"
+                                    "https://example.com/debug/*"
                                   ]
                                 }
                               ]
                             ],
                             "id": 1044,
                             "rule_id": "9spXEVoMeZWujjz25yrgTe",
-                            "rule_name": "Production console errors",
+                            "rule_name": "Ignore browser noise",
                             "status": "enabled",
                             "updated_at": 1786000000000,
                             "updated_by": 1001
@@ -52261,6 +54054,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -52273,7 +54069,7 @@
           "RUM/错误采集规则"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 每条历史记录都是该应用在某一时刻全部规则的完整快照，而不是单条规则的差异。\n- `p` 是从 0 开始的页码，不是字节偏移量——服务端内部按 `offset = p * limit` 计算。\n- `orderby` 仅支持 `updated_at` 或 `version`；传入其他值会被静默回退为 `updated_at`。\n- `limit` 默认 20，服务端上限 100；超过 100 会被静默截断，小于等于 0 时回退为默认值。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 每次写操作都会先保存变更前的规则集合，因此版本 N 记录的是第 N 次变更之前的规则，其 `updated_by`/`updated_at` 对应的就是这第 N 次变更。当前生效的规则集合请用 `list` 查询，不在此返回。\n- 每条历史记录都是该应用全部未删除规则的完整快照，而不是单条规则的差异。\n- `p` 是从 0 开始的页码：服务端跳过 `p * limit` 条记录。\n- `limit` 默认 20，上限 100；超过 100 会被截断为 100，小于等于 0 时回退为默认值。\n- 公开应用任何成员都可读取；私有应用需要编辑权限（账户所有者或管理员、应用创建者、应用所属团队的成员），否则返回 `AccessDenied`；`application_id` 不存在时返回 `ResourceNotFound`。",
           "href": "/zh/api-reference/rum/error-ingestion-rules/rum-error-ingestion-rules-history-list",
           "metadata": {
             "sidebarTitle": "查询错误采集规则历史"
@@ -52332,6 +54128,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -52344,7 +54143,7 @@
           "RUM/错误采集规则"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 回滚会替换该应用的整个规则集合——目标版本之后新建的规则会被移除，而不是合并保留。\n- 回滚前会先把当前状态快照进历史记录，因此回滚操作本身也可以通过再次回滚来撤销。\n- 若 `version` 在该应用下不存在，返回的是 `InvalidParameter` 而不是 `ResourceNotFound`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 版本 N 记录的是第 N 次变更之前的规则，因此回滚到版本 N 会撤销第 N 次及之后的所有变更。\n- 回滚会替换该应用的整个规则集合：目标版本中没有的规则会被移除，而不是合并保留。\n- 恢复的规则保留原来的 `rule_id`、名称、描述、过滤条件和状态，`created_at` 与 `updated_at` 重置为回滚时间。\n- 回滚前会先把当前状态保存为一个新的历史版本，因此回滚操作本身也可以通过再次回滚来撤销。\n- 若 `version` 在该应用下不存在，返回的是 `InvalidParameter` 而不是 `ResourceNotFound`。\n- 采集端按应用缓存已启用的规则，缓存有效期 5 秒，因此变更最多约 5 秒后对新上报的错误生效。\n- 需要对该应用有编辑权限（账户所有者或管理员、应用创建者、应用所属团队的成员），否则返回 `AccessDenied`；`application_id` 不存在时返回 `ResourceNotFound`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/rum/error-ingestion-rules/rum-error-ingestion-rules-history-revert",
           "metadata": {
             "sidebarTitle": "回滚错误采集规则到历史版本"
@@ -52378,37 +54177,30 @@
                     "items": [
                       {
                         "created_at": 1786000000000,
-                        "description": "Only ingest TypeError/ReferenceError from production, excluding Safari.",
+                        "description": "Known browser noise and errors from internal debug pages.",
                         "filters": [
                           [
                             {
-                              "key": "error.env",
-                              "oper": "IN",
-                              "vals": [
-                                "production"
-                              ]
-                            },
-                            {
-                              "key": "error.error_type",
+                              "key": "error.error_message",
                               "oper": "IN",
                               "vals": [
-                                "TypeError",
-                                "ReferenceError"
+                                "Script error.",
+                                "ResizeObserver loop*"
                               ]
                             }
                           ],
                           [
                             {
-                              "key": "error.browser_name",
-                              "oper": "NOTIN",
+                              "key": "error.view_url",
+                              "oper": "IN",
                               "vals": [
-                                "Safari"
+                                "https://example.com/debug/*"
                               ]
                             }
                           ]
                         ],
                         "rule_id": "9spXEVoMeZWujjz25yrgTe",
-                        "rule_name": "Production console errors",
+                        "rule_name": "Ignore browser noise",
                         "status": "enabled",
                         "updated_at": 1786003600000
                       }
@@ -52441,6 +54233,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -52453,7 +54248,7 @@
           "RUM/错误采集规则"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 已删除的规则不会出现在结果中，仅返回状态为 `enabled` 或 `disabled` 的规则。\n- 结果按创建时间倒序排列。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 已删除的规则不会出现在结果中，仅返回状态为 `enabled` 或 `disabled` 的规则。\n- 结果按创建时间倒序排列，不分页。\n- 公开应用任何成员都可读取；私有应用需要编辑权限（账户所有者或管理员、应用创建者、应用所属团队的成员），否则返回 `AccessDenied`；`application_id` 不存在时返回 `ResourceNotFound`。",
           "href": "/zh/api-reference/rum/error-ingestion-rules/rum-error-ingestion-rules-list",
           "metadata": {
             "sidebarTitle": "查询错误采集规则列表"
@@ -52470,7 +54265,7 @@
             "application/json": {
               "example": {
                 "application_id": "WoyQQ3BohkdtPivubEvE8o",
-                "description": "Now also excludes staging traffic.",
+                "description": "Known browser noise and errors from internal debug pages.",
                 "rule_id": "9spXEVoMeZWujjz25yrgTe"
               },
               "schema": {
@@ -52513,6 +54308,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -52525,7 +54323,7 @@
           "RUM/错误采集规则"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 仅更新请求中出现的字段，未传入的字段保持原值不变。\n- 不传任何可更新字段时视为空操作，仍会返回成功。\n- 若 `rule_id` 在该 `application_id` 下不存在，返回 `ResourceNotFound`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 仅更新请求中出现的字段，未传入或传 `null` 的字段保持原值不变。\n- 不传任何可更新字段时不做任何修改、也不生成历史版本，但仍返回成功。\n- 新的 `filters` 与 `create` 采用同样的校验规则，无效时返回 `InvalidParameter`。\n- 若 `rule_id` 在该 `application_id` 下不存在（或已删除），返回 `ResourceNotFound`。\n- 每次写操作都会先把应用变更前的完整规则集合保存为一个新的历史版本。\n- 采集端按应用缓存已启用的规则，缓存有效期 5 秒，因此变更最多约 5 秒后对新上报的错误生效。\n- 需要对该应用有编辑权限（账户所有者或管理员、应用创建者、应用所属团队的成员），否则返回 `AccessDenied`；`application_id` 不存在时返回 `ResourceNotFound`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/rum/error-ingestion-rules/rum-error-ingestion-rules-update",
           "metadata": {
             "sidebarTitle": "更新错误采集规则"
@@ -52542,7 +54340,7 @@
             "application/json": {
               "example": {
                 "end_time": 1712707200000,
-                "facet_key": "error.type",
+                "facet_key": "error_type",
                 "limit": 10,
                 "scope": "error",
                 "start_time": 1712620800000
@@ -52602,6 +54400,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -52614,7 +54415,7 @@
           "RUM/RUM 自定义字段"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**100 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 使用 `POST /rum/field/list`（传 `is_facet: true`）发现每个 scope 下可用的 `facet_key` 值。\n- `scope` 必须是以下之一：`session`、`view`、`action`、`error`、`resource`、`long_task`、`vital`、`issue`、`sourcemap`。\n- 传入 `dql` 可在统计前进一步过滤事件，DQL 语法遵循 RUM 查询语言。\n- 传入 `sql` 可使用仅含 WHERE 子句（无 SELECT）的 SQL 风格过滤。\n- 默认 limit 为 100，最大 100。\n- 时间范围必填（`start_time` / `end_time` 为 Unix 毫秒时间戳），最大跨度 31 天。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**100 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 使用 `POST /rum/field/list`（传 `is_facet: true`）发现每个 scope 下可用的 `facet_key`。\n- `facet_key` 必须是所请求 `scope` 下的分面字段（`is_facet: true`），且 `show_type` 为 `list`、`value_type` 不是数组类型，否则返回 `InvalidParameter`。\n- `facet_key` 为 `null` 的事件不参与统计。传入 `facet_value` 时只统计取值等于它的事件，其 JSON 类型须与字段的 `value_type` 一致。\n- 传入 `dql` 可在统计前过滤事件。`sql` 只填 `WHERE` 条件本身；其中任意位置出现 `SELECT`（不区分大小写）都会被拒绝。\n- `limit` 默认 100，最大 100。\n- `start_time` / `end_time` 必填，为 Unix **毫秒**时间戳，跨度不超过 31 天。\n- `scope` 为 `sourcemap` 时，用 `type` 和 `kind` 选择统计哪个符号文件库。",
           "href": "/zh/api-reference/rum/facets/rum-read-facet-count",
           "metadata": {
             "sidebarTitle": "查询分值分布"
@@ -52651,19 +54452,20 @@
                     "items": [
                       {
                         "account_id": 0,
-                        "description": "The type of the error.",
+                        "description": "Error type or class depending on the language. Examples: `TypeError`, `NotFoundError`.",
                         "edit_able": false,
                         "enum_values": [],
-                        "field_key": "error.type",
-                        "field_name": "Error type",
-                        "group": "Error",
+                        "field_key": "error_type",
+                        "field_name": "Error Type",
+                        "group": "error",
                         "is_facet": true,
                         "queryable": true,
                         "scopes": [
-                          "error"
+                          "error",
+                          "issue"
                         ],
                         "show_type": "list",
-                        "status": "active",
+                        "status": "enabled",
                         "unit_family": "",
                         "unit_name": "",
                         "value_type": "string"
@@ -52697,6 +54499,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -52719,7 +54524,7 @@
     },
     "/rum/issue/export": {
       "post": {
-        "description": "将符合过滤条件的 RUM 异常追踪 Issue 导出为 CSV 文件。响应为 `text/csv` 流，通过 `Content-Disposition: attachment` 交付——不是 JSON 信封；非控制台调用方可通过 `X-Export-Total` 与 `X-Export-Truncated` 响应头获知匹配总数与截断情况。",
+        "description": "按 `POST /rum/issue/list` 的过滤条件导出 Issue，生成最多 100 行的 CSV 文件。",
         "operationId": "rum-issue-read-export",
         "requestBody": {
           "content": {
@@ -52787,6 +54592,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -52799,7 +54607,7 @@
           "RUM/RUM 问题跟踪"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **200 次/天**；**100 次/分钟**；**10 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 响应为 `text/csv` 流，通过 `Content-Disposition: attachment` 交付——不使用标准信封。文件名为 `rum-issues-<时间戳>.csv`，按请求的 `time_zone` 打时间戳。请通过 `X-Export-Total` 与 `X-Export-Truncated` 响应头获取总数与截断情况。\n- 导出读取前 100 条匹配记录（`ExportMaxRows`）；匹配数超过上限时 `X-Export-Truncated` 为 `true`。`p` 和 `limit` 被忽略。\n- 请求过滤条件与 `POST /rum/issue/list` 完全一致——导出就是“我正在看的列表，输出成文件”。\n- `export_fields` 按顺序指定 CSV 列；未知键会被拒绝；空数组使用默认列集。\n- `time_zone` 必须是合法的 IANA 时区名（如 `Asia/Shanghai`、`UTC`）；时间戳按该时区渲染，时间列表头携带时区。非法时区名会被拒绝。\n- `console_origin` 用于拼接 `issue_url` 列；服务无法自行推断（SaaS、私有化与 dev 环境地址不同）。\n- 每次调用都会记录到账户审计日志，包含调用者成员 ID、请求负载与最终错误（如有）。请勿在请求字段中放置敏感信息。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **200 次/天**；**100 次/分钟**；**10 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 成功时响应体是 `text/csv` 附件，文件名为 `rum-issues-<yyyyMMdd-HHmmss>.csv`（按 `time_zone` 取时间），不使用 JSON 信封；参数校验失败等错误仍返回 JSON 错误信封。\n- `X-Export-Total` 为匹配的 Issue 总数；匹配数超过 100 时 `X-Export-Truncated` 为 `true`，文件只包含按 `orderby` 排序后的前 100 条。`p` 和 `limit` 会被忽略。\n- 过滤条件与 `POST /rum/issue/list` 完全一致，同样会排除调用方无权访问的私有应用。\n- `export_fields` 按输出顺序列出列；未知键会被拒绝，重复键会被去掉，传空数组或不传时导出除 `sample_first_*` 外的全部列。\n- `sample_*` 列取该 Issue 在 `[start_time, end_time]` 内最近的一条错误事件，`sample_first_*` 列取最早的一条；时间窗内没有事件时这些列为空。\n- 表头默认英文，请求语言为中文时（`Accept-Language` 请求头，或 `locale` / `lang` 查询参数）输出中文表头。时间列按 `time_zone` 渲染为 `yyyy-MM-dd HH:mm:ss`，表头附带时区，时间未设置时为空。\n- 以 `=`、`+`、`-`、`@`、制表符或回车开头的单元格会加上前缀 `'`，防止表格软件把它当作公式执行。\n- 每次调用都会记录到账户审计日志，包含调用者成员 ID、请求负载与最终错误（如有）。请勿在请求字段中放置敏感信息。",
           "href": "/zh/api-reference/rum/issues/rum-issue-read-export",
           "metadata": {
             "sidebarTitle": "导出 Issue 列表"
@@ -52851,6 +54659,7 @@
                     },
                     "resolved_at": 0,
                     "resolved_by": 0,
+                    "resolve_mode": "version",
                     "service": "fd-console",
                     "session_count": 381,
                     "severity": "Info",
@@ -52894,6 +54703,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -52906,7 +54718,7 @@
           "RUM/RUM 问题跟踪"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- `team_id` 为所属应用**当前**的团队；`POST /rum/issue/list` 与 `POST /rum/issue/export` 返回 Issue 首次出现时记录的团队，应用转移到其他团队后两者不同。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- `team_id` 为所属应用**当前**的团队；`POST /rum/issue/list` 与 `POST /rum/issue/export` 返回 Issue 首次出现时记录的团队，应用转移到其他团队后两者不同。\n- `issue_id` 不存在或已删除时返回 `InvalidParameter`（\"The specified issue does not exist\"），而不是 `ResourceNotFound`。",
           "href": "/zh/api-reference/rum/issues/rum-issue-read-info",
           "metadata": {
             "sidebarTitle": "查看 Issue 详情"
@@ -52971,6 +54783,7 @@
                         },
                         "resolved_at": 0,
                         "resolved_by": 0,
+                        "resolve_mode": "version",
                         "service": "fd-console",
                         "session_count": 381,
                         "severity": "Info",
@@ -53009,6 +54822,7 @@
                         },
                         "resolved_at": 0,
                         "resolved_by": 0,
+                        "resolve_mode": "version",
                         "service": "fd-console",
                         "session_count": 1,
                         "severity": "Info",
@@ -53055,6 +54869,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -53067,7 +54884,7 @@
           "RUM/RUM 问题跟踪"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- `start_time` 和 `end_time` 为毫秒时间戳，最大范围 183 天。\n- `statuses` 按状态过滤，可选值：`for_review`、`reviewed`、`ignored`、`resolved`。\n- `orderby` 支持：`created_at`、`updated_at`、`session_count`、`error_count`。\n- 使用 `dql` 或 `sql` 进行高级过滤，两者不可同时使用。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- `start_time` 和 `end_time` 为毫秒时间戳，最大范围 183 天。\n- 默认只匹配在时间窗内创建的 Issue；`by_intersection=true` 时，只要 Issue 在 `end_time` 之前创建且最近出现时间不早于 `start_time` 即匹配。\n- 私有应用的 Issue 会被排除，除非调用方是账户所有者或管理员、应用创建者，或应用所属团队的成员。\n- `statuses` 按状态过滤，可选值：`for_review`、`reviewed`、`ignored`、`resolved`。\n- `orderby` 支持：`created_at`、`updated_at`（默认）、`session_count`、`error_count`、`severity`。按 `severity` 排序时，没有严重性的 Issue 总是排在最后。\n- 使用 `dql` 或 `sql` 进行高级过滤，两者不可同时使用。",
           "href": "/zh/api-reference/rum/issues/rum-issue-read-list",
           "metadata": {
             "sidebarTitle": "查询 Issue 列表"
@@ -53150,6 +54967,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -53162,7 +54982,7 @@
           "RUM/Issue 预设严重性规则"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- `filters.*.key` 仅支持固定的一组 Error 级别属性，传入其他键将返回 `InvalidParameter`。\n- 请至少传入一组条件：`filters` 传空数组虽然会被接受，但该规则永远不会命中。\n- 新规则创建后默认启用，并以最低优先级追加到末尾（`priority` = 当前最大值 + 1）；如需提前评估顺序，请调用 `reorder`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- `filters.*.key` 仅支持固定的一组 Error 级别属性，传入其他键将返回 `InvalidParameter`。\n- 请至少传入一组条件：`filters` 传空数组虽然会被接受，但该规则永远不会命中。\n- 新规则创建后默认启用，并以最低优先级追加到末尾（`priority` = 当前最大值 + 1）；如需提前评估顺序，请调用 `reorder`。\n- 需要对该应用有编辑权限（账户所有者或管理员、应用创建者，或应用所属团队的成员），否则返回 `AccessDenied`；`application_id` 不存在时返回 `ResourceNotFound`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/rum/issue-preset-severity-rules/rum-issue-preset-severity-rules-create",
           "metadata": {
             "sidebarTitle": "创建预设严重性规则"
@@ -53193,7 +55013,6 @@
             "content": {
               "application/json": {
                 "example": {
-                  "data": {},
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 },
                 "schema": {
@@ -53221,6 +55040,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -53233,7 +55055,7 @@
           "RUM/Issue 预设严重性规则"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 若 `rule_id` 在该应用下不存在，返回 `ResourceNotFound`。\n- 删除为软删除：规则会立即从列表中消失，但启用规则集有最多 5 秒缓存，因此删除后数秒内上报的错误仍可能被其评估。删除前的状态仍可通过历史接口查看。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 若 `rule_id` 在该应用下不存在，返回 `ResourceNotFound`。\n- 删除为软删除：规则会立即从列表中消失，但启用规则集有最多 5 秒缓存，因此删除后数秒内上报的错误仍可能被其评估。删除前的状态仍可通过历史接口查看。\n- 需要对该应用有编辑权限（账户所有者或管理员、应用创建者，或应用所属团队的成员），否则返回 `AccessDenied`；`application_id` 不存在时返回 `ResourceNotFound`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/rum/issue-preset-severity-rules/rum-issue-preset-severity-rules-delete",
           "metadata": {
             "sidebarTitle": "删除预设严重性规则"
@@ -53264,7 +55086,6 @@
             "content": {
               "application/json": {
                 "example": {
-                  "data": {},
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 },
                 "schema": {
@@ -53292,6 +55113,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -53304,7 +55128,7 @@
           "RUM/Issue 预设严重性规则"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 若 `rule_id` 在该应用下不存在，返回 `ResourceNotFound`。\n- 禁用的规则在评估时会被跳过，但仍保留其 `priority` 位置；缓存生效最多有 5 秒延迟。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 若 `rule_id` 在该应用下不存在，返回 `ResourceNotFound`。\n- 禁用的规则在评估时会被跳过，但仍保留其 `priority` 位置；缓存生效最多有 5 秒延迟。\n- 需要对该应用有编辑权限（账户所有者或管理员、应用创建者，或应用所属团队的成员），否则返回 `AccessDenied`；`application_id` 不存在时返回 `ResourceNotFound`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/rum/issue-preset-severity-rules/rum-issue-preset-severity-rules-disable",
           "metadata": {
             "sidebarTitle": "禁用预设严重性规则"
@@ -53335,7 +55159,6 @@
             "content": {
               "application/json": {
                 "example": {
-                  "data": {},
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 },
                 "schema": {
@@ -53363,6 +55186,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -53375,7 +55201,7 @@
           "RUM/Issue 预设严重性规则"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 若 `rule_id` 在该应用下不存在，返回 `ResourceNotFound`。\n- 已启用规则会被缓存最多 5 秒，因此对新采集错误生效可能有数秒延迟。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 若 `rule_id` 在该应用下不存在，返回 `ResourceNotFound`。\n- 已启用规则会被缓存最多 5 秒，因此对新采集错误生效可能有数秒延迟。\n- 需要对该应用有编辑权限（账户所有者或管理员、应用创建者，或应用所属团队的成员），否则返回 `AccessDenied`；`application_id` 不存在时返回 `ResourceNotFound`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/rum/issue-preset-severity-rules/rum-issue-preset-severity-rules-enable",
           "metadata": {
             "sidebarTitle": "启用预设严重性规则"
@@ -53551,6 +55377,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -53563,7 +55392,7 @@
           "RUM/Issue 预设严重性规则"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 每条记录是该应用下所有规则在触发本次变更**之前**那一刻的整体快照，而非增量差异。每次真正产生变更的 create/update/enable/disable/delete/reorder/revert 调用前都会写入一条新快照（若 `update` 请求未携带任何可改字段，会直接返回成功且不写快照），因此 `version=1` 通常是首次创建规则之前捕获到的空规则集。\n- `rules` 中的每一项都是完整的内部行结构（包含 `account_id`、`created_by`、`id`、`deleted_at`），比 `rules/list` 返回的结构更宽。\n- `limit` 默认 20，超过 100 会被静默截断为 100，而不会报错。\n- `orderby` 仅支持 `updated_at` 或 `version`，传入其他值（含缺省）会回退为 `updated_at`，不会报错。\n- 结果默认按降序排列，传入 `asc=true` 可改为升序。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 每条记录是该应用下所有规则在触发本次变更**之前**那一刻的整体快照，而非增量差异。每次成功的 create/update/enable/disable/delete/reorder/revert 调用前都会写入一条快照，即使规则实际没有变化（例如启用一条已启用的规则）；只有未携带任何可改字段的 `update` 请求不写快照。因此 `version=1` 通常是首次创建规则之前捕获到的空规则集。\n- `rules` 中的每一项都是完整的内部行结构（包含 `account_id`、`created_by`、`id`、`deleted_at`），比 `rules/list` 返回的结构更宽。\n- `limit` 默认 20，超过 100 会被静默截断为 100，而不会报错。\n- `orderby` 仅支持 `updated_at` 或 `version`，传入其他值（含缺省）会回退为 `updated_at`，不会报错。\n- 结果默认按降序排列，传入 `asc=true` 可改为升序。\n- 私有应用的规则仅对有编辑权限的调用方可见（账户所有者或管理员、应用创建者，或应用所属团队的成员），其他调用方返回 `AccessDenied`；`application_id` 不存在时返回 `ResourceNotFound`。",
           "href": "/zh/api-reference/rum/issue-preset-severity-rules/rum-issue-preset-severity-rules-history-list",
           "metadata": {
             "sidebarTitle": "查询预设严重性规则历史列表"
@@ -53594,7 +55423,6 @@
             "content": {
               "application/json": {
                 "example": {
-                  "data": {},
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 },
                 "schema": {
@@ -53622,6 +55450,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -53634,7 +55465,7 @@
           "RUM/Issue 预设严重性规则"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 会用该快照的行整体替换当前规则集：`rule_id`、`priority`、`filters`、`severity`、`status`、`created_by` 沿用快照中的值，但 `created_at`/`updated_at` 会重置为回滚发生的时间，`updated_by` 会设为执行回滚的用户。\n- 当 `version` 在该应用下不存在对应历史快照时，返回 `InvalidParameter`（而非 `ResourceNotFound`）。\n- 回滚操作本身也会先生成一条新的历史快照再执行，因此回滚也可以被再次回滚。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 会用该快照的行整体替换当前规则集：`rule_id`、`priority`、`filters`、`severity`、`status`、`created_by` 沿用快照中的值，但 `created_at`/`updated_at` 会重置为回滚发生的时间，`updated_by` 会设为执行回滚的用户。\n- 当 `version` 在该应用下不存在对应历史快照时，返回 `InvalidParameter`（而非 `ResourceNotFound`）。\n- 回滚操作本身也会先生成一条新的历史快照再执行，因此回滚也可以被再次回滚。\n- 需要对该应用有编辑权限（账户所有者或管理员、应用创建者，或应用所属团队的成员），否则返回 `AccessDenied`；`application_id` 不存在时返回 `ResourceNotFound`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/rum/issue-preset-severity-rules/rum-issue-preset-severity-rules-history-revert",
           "metadata": {
             "sidebarTitle": "回滚预设严重性规则到历史版本"
@@ -53744,6 +55575,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -53756,7 +55590,7 @@
           "RUM/Issue 预设严重性规则"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 返回结果按 `priority` 升序、`created_at` 升序排列，与实际评估顺序一致。\n- 仅已启用的规则参与对新错误的评估；按优先级顺序第一条过滤条件匹配的已启用规则生效并赋予其 `severity`。未命中任何已启用规则的错误保持默认严重级别。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 返回结果按 `priority` 升序、`created_at` 升序排列，与实际评估顺序一致。\n- 仅已启用的规则参与对新错误的评估；按优先级顺序第一条过滤条件匹配的已启用规则生效并赋予其 `severity`。未命中任何已启用规则的错误使用内置严重性：崩溃为 `Critical`，其他错误按环境与错误信息关键词打分。\n- 严重性只在错误创建新 Issue 时确定一次；规则变更只影响之后接收的错误（已启用规则最多缓存 5 秒），不会重新评定已有 Issue。\n- 私有应用的规则仅对有编辑权限的调用方可见（账户所有者或管理员、应用创建者，或应用所属团队的成员），其他调用方返回 `AccessDenied`；`application_id` 不存在时返回 `ResourceNotFound`。",
           "href": "/zh/api-reference/rum/issue-preset-severity-rules/rum-issue-preset-severity-rules-list",
           "metadata": {
             "sidebarTitle": "查询预设严重性规则列表"
@@ -53788,7 +55622,6 @@
             "content": {
               "application/json": {
                 "example": {
-                  "data": {},
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 },
                 "schema": {
@@ -53816,6 +55649,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -53828,7 +55664,7 @@
           "RUM/Issue 预设严重性规则"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 本接口每次只移动一条规则，而非整体重排：`drag_rule_id` 的 `priority` 被设为 `target_rule_id` 当前的 `priority`，两者原位置之间的规则（含 `target_rule_id` 自身）整体平移一位以填补空缺。\n- `priority` 数值越小越先评估；拖动到编号更小的目标会使该规则评估顺序提前，拖动到编号更大的目标则顺延。\n- 若 `drag_rule_id` 或 `target_rule_id` 任一在该应用下不存在，返回 `ResourceNotFound`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 本接口每次只移动一条规则，而非整体重排：`drag_rule_id` 的 `priority` 被设为 `target_rule_id` 当前的 `priority`，两者原位置之间的规则（含 `target_rule_id` 自身）整体平移一位以填补空缺。\n- `priority` 数值越小越先评估；拖动到编号更小的目标会使该规则评估顺序提前，拖动到编号更大的目标则顺延。\n- 若 `drag_rule_id` 或 `target_rule_id` 任一在该应用下不存在，返回 `ResourceNotFound`。\n- 需要对该应用有编辑权限（账户所有者或管理员、应用创建者，或应用所属团队的成员），否则返回 `AccessDenied`；`application_id` 不存在时返回 `ResourceNotFound`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/rum/issue-preset-severity-rules/rum-issue-preset-severity-rules-reorder",
           "metadata": {
             "sidebarTitle": "调整预设严重性规则顺序"
@@ -53861,7 +55697,6 @@
             "content": {
               "application/json": {
                 "example": {
-                  "data": {},
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 },
                 "schema": {
@@ -53889,6 +55724,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -53901,7 +55739,7 @@
           "RUM/Issue 预设严重性规则"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 仅更新请求中出现的字段，未传字段保持原值不变。\n- 若 `rule_id` 在该应用下不存在，返回 `ResourceNotFound`。\n- 若传入 `filters`，将整体替换原有过滤结构，并按与 `create` 相同的允许键集合重新校验。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 仅更新请求中出现的字段，未传字段保持原值不变。\n- 若 `rule_id` 在该应用下不存在，返回 `ResourceNotFound`。\n- 若传入 `filters`，将整体替换原有过滤结构，并按与 `create` 相同的允许键集合重新校验。\n- 需要对该应用有编辑权限（账户所有者或管理员、应用创建者，或应用所属团队的成员），否则返回 `AccessDenied`；`application_id` 不存在时返回 `ResourceNotFound`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/rum/issue-preset-severity-rules/rum-issue-preset-severity-rules-update",
           "metadata": {
             "sidebarTitle": "更新预设严重性规则"
@@ -53960,6 +55798,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -53972,7 +55813,7 @@
           "RUM/RUM 问题跟踪"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- `status` 可选值：`for_review`、`reviewed`、`ignored`、`resolved`。\n- `suspected_cause` 可选值：`api.failed_request`、`network.error`、`code.exception`、`code.invalid_object_access`、`code.invalid_argument`、`unknown`。\n- 将 `status` 设为 `resolved` 会同时记录 `resolved_at` 和 `resolved_by`；从 resolved 切回其他状态则会清空这两个字段。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 只应用请求中携带的字段；`status` 与当前状态相同时不会产生任何变化。\n- 将未解决的 Issue 的 `status` 设为 `resolved` 会记录 `resolved_at` 和 `resolved_by` 并清除 `regression`；把已解决的 Issue 改为其他状态会清空 `resolved_at` 和 `resolved_by`。\n- `resolve_mode` 只在同时传 `status: resolved` 时生效，此时不传默认为 `any`；对已解决的 Issue 传 `status: resolved` 加新的 `resolve_mode` 可以只修改解决方式。\n- 应用开启告警时，将 Issue 设为已解决会立即发送其恢复告警。\n- 设置 `suspected_cause` 会把根因标记为用户指定（`suspected_cause.source` 为 `user`，`person_id` 为调用者），之后自动分析不会再覆盖它。\n- `issue_id` 不存在时返回 `InvalidParameter`（\"The specified issue does not exist\"）。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/rum/issues/rum-issue-write-update",
           "metadata": {
             "sidebarTitle": "更新 Issue"
@@ -54056,6 +55897,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -54068,7 +55912,7 @@
           "RUM/资源"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 账户尚未开通 RUM 资源，或资源状态为 `deleted`/`destroyed` 时，返回 `ResourceNotFound`。\n- `no_cache=true` 跳过的是资源记录本身（套餐版本、配额、状态）的短时缓存；`used_cnt` 系列用量来自另一份小时级缓存，不受该参数影响，无论是否传该参数都可能有延迟。\n- 已用量字段反映当前 30 天计费窗口（`window_start_time` 至 `window_end_time`）内的用量，而非历史累计总量。\n- `expired_at` 仅私有化部署会返回，取自 License 到期时间；SaaS 账户该字段不会出现在响应中。\n- 对于 `version=free` 的账户，用量超过所有应用的免费额度合计（单应用免费额度 × 应用数）时 `session_limit_reached` 为 `true`；账户尚无任何应用时始终为 `false`。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 账户尚未开通 RUM 资源，或资源状态为 `deleted`/`destroyed` 时，返回 `ResourceNotFound`。\n- `no_cache=true` 跳过的是资源记录本身（套餐版本、配额、状态）的短时缓存；`used_cnt` 系列用量来自另一份小时级缓存，不受该参数影响，无论是否传该参数都可能有延迟。\n- 已用量字段反映当前 30 天计费窗口（`window_start_time` 至 `window_end_time`）内的用量，而非历史累计总量。\n- `free_cnt` 为负数表示该额度不限量。\n- `expired_at` 仅私有化部署会返回，取自 License 到期时间；SaaS 账户该字段不会出现在响应中。\n- 对于 `version=free` 的账户，investigate 或 replay 会话用量达到「单应用免费额度 × 应用数」时 `session_limit_reached` 为 `true`（measure 会话不计入）；账户尚无任何应用时始终为 `false`。",
           "href": "/zh/api-reference/rum/resources/rum-resource-read-info",
           "metadata": {
             "sidebarTitle": "查看 RUM 资源信息"
@@ -54115,8 +55959,6 @@
                     },
                     "views": [
                       {
-                        "container_source": "",
-                        "container_view_id": "",
                         "end": 1752480600000,
                         "is_active": false,
                         "loading_type": "initial_load",
@@ -54156,6 +55998,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -54168,7 +56013,7 @@
           "RUM/RUM 会话回放"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 若会话不存在，或该会话没有录制回放数据（`session_has_replay` 为 false），返回 `InvalidParameter`。\n- 若该会话时间窗口内未查询到任何视图，返回 `InvalidParameter`。\n- 当 `session_id` 在不同时间窗口内被复用时，可传入 `ts` 加以区分。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 若会话不存在，或该会话没有录制回放数据（`session_has_replay` 为 false），返回 `InvalidParameter`。\n- 若在会话开始至其记录结束时间后 4 小时内找不到带回放数据的视图，返回 `InvalidParameter`。\n- `ts` 必须与会话开始时间（Unix 毫秒）完全相等；其他取值会导致查不到会话并返回 `InvalidParameter`。\n- 所有时间戳均为客户端时间，不做时钟偏差校正（`server_time_delta` 恒为 `0`）。",
           "href": "/zh/api-reference/rum/session-replay/rum-session-replay-read-metadata",
           "metadata": {
             "sidebarTitle": "查看会话回放元数据"
@@ -54184,7 +56029,7 @@
           "content": {
             "application/json": {
               "example": {
-                "limit": 20,
+                "limit": 2,
                 "session_id": "0a4a2e64-8a4f-4b9a-9c1e-3a2f9e6d7c81",
                 "url_mode": true
               },
@@ -54202,8 +56047,8 @@
                 "example": {
                   "data": {
                     "items": [
-                      "https://rum-replay.flashcat.cloud/short-term/2451002751131/0a4a2e64-8a4f-4b9a-9c1e-3a2f9e6d7c81/segments/1752480001234?X-Amz-Signature=example",
-                      "https://rum-replay.flashcat.cloud/short-term/2451002751131/0a4a2e64-8a4f-4b9a-9c1e-3a2f9e6d7c81/segments/1752480032456?X-Amz-Signature=example"
+                      "https://replay-storage.example.com/short-term/2451002751131/0a4a2e64-8a4f-4b9a-9c1e-3a2f9e6d7c81/segments/1752480001234?X-Amz-Signature=example",
+                      "https://replay-storage.example.com/short-term/2451002751131/0a4a2e64-8a4f-4b9a-9c1e-3a2f9e6d7c81/segments/1752480032456?X-Amz-Signature=example"
                     ],
                     "search_after_ctx": "c2hvcnQtdGVybS8yNDUxMDAyNzUxMTMxLzBhNGEyZTY0LThhNGYtNGI5YS05YzFlLTNhMmY5ZTZkN2M4MS9zZWdtZW50cy8xNzUyNDgwMDMyNDU2"
                   },
@@ -54248,6 +56093,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -54260,7 +56108,7 @@
           "RUM/RUM 会话回放"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 当 `url_mode` 为 `false`（默认）时，响应以 `application/x-ndjson` 流式返回——每行是一条解压后的回放分段 JSON 记录——且**不会**包裹在标准信封中；下一页的分页游标改由响应头 `X-Search-After-Ctx` 返回，而非响应体字段。\n- 当 `url_mode` 为 `true` 时，响应为标准 JSON 信封，内含分段的预签名下载地址（1 小时内有效），而非原始字节流。\n- 传入 `ts` 可从该时间点之前最近的一个全量快照分段开始定位，而非从会话起始处分页。\n- `limit` 取值范围 1-99；传入 100 及以上将被拒绝。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 当 `url_mode` 为 `false`（默认）时，响应以 `application/x-ndjson` 流式返回——每行是一条解压后的回放分段 JSON 记录——且**不会**包裹在标准信封中；下一页的分页游标改由响应头 `X-Search-After-Ctx` 返回，而非响应体字段。读取失败的分段会被直接跳过。\n- 当 `url_mode` 为 `true` 时，响应为标准 JSON 信封，内含分段对象（zlib 压缩）的预签名下载地址，1 小时内有效。\n- 传入 `ts`（且不传 `search_after_ctx`）时，从该时间点及之前最近的全量快照分段开始，最多向前查找 4 小时；找不到时从头开始分页。\n- 只要本页取满 `limit` 个分段就会返回游标，因此最后一页可能为空。\n- `limit` 取值范围 1-99；传入 100 及以上将被拒绝。",
           "href": "/zh/api-reference/rum/session-replay/rum-session-replay-read-segments",
           "metadata": {
             "sidebarTitle": "查询会话回放分段"
@@ -54270,57 +56118,52 @@
     },
     "/safari/a2a-agent/create": {
       "post": {
-        "description": "通过智能体卡片 URL 注册新的 A2A 远程智能体。",
         "operationId": "remote-agent-write-create",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "agent_name": "deploy-bot",
-                "auth_type": "bearer",
-                "card_url": "https://agents.example.com/deploy-bot/card",
-                "environments": [
-                  "env_8s7Hn2kLpQ3xYbVc4Wd2m"
-                ],
-                "instructions": "Inspect deployment pipelines and propose rollbacks when a canary fails health checks.",
-                "streaming": true,
-                "team_id": 0
-              },
-              "schema": {
-                "$ref": "#/components/schemas/A2AAgentCreateRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "创建 A2A 智能体",
+        "description": "通过智能体卡片 URL 注册新的 A2A 远程智能体。",
+        "tags": [
+          "AI SRE/A2A 智能体"
+        ],
+        "security": [
+          {
+            "AppKeyAuth": []
+          }
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **Agent 管理**（`ai-sre`） |\n\n## 使用说明\n\n- `instructions` 为必填：Markdown 文档，可带 `summary` frontmatter，正文不能为空，最多 51,200 字节。已弃用的 `description` 字段仍可传入，若与 `instructions` 同时传入，两者必须完全一致。\n- `agent_name` 不能包含 `@`，也不能是内置智能体保留的 `general` / `explore`，且在其作用域（账户级或单个团队）内必须唯一；违反时返回 `InvalidParameter`。\n- `card_url` 必须是带 host 的绝对 `http`/`https` URL。若该智能体有在线的执行环境，服务端会通过该环境拉取智能体卡片（`card_url` 不带路径时自动补 `/.well-known/agent-card.json`），卡片不是合法 JSON、或未声明协议绑定为 `JSONRPC` / `HTTP+JSON` 的 A2A 1.x 接口时拒绝；卡片不可达、返回非 2xx 或没有在线环境时不阻断调用。\n- `auth_type=bearer` 时以 `Authorization: Bearer <token>` 发送 `auth_config.token`；`auth_type=api_key` 时把 `auth_config.api_key` 放进 `auth_config.header` 指定名称的请求头；为 `none` 或空值时不发送共享凭据请求头。\n- `environments` 的每一项必须是 `cloud`，或某个账户级 BYOC Runner、调用者所属团队的 BYOC Runner 的环境 ID；重复项会被去除，空字符串会被拒绝。省略或为空表示所有环境。\n- 创建到团队（`team_id > 0`）要求调用者属于该团队；只有账户 owner 或管理员可以在账户级（`team_id=0`）创建。\n- 新建的智能体 `status` 为 `enabled`。\n- 每次调用都会记录到账户审计日志。\n",
+          "href": "/zh/api-reference/ai-sre/a2a-agents/remote-agent-write-create",
+          "metadata": {
+            "sidebarTitle": "创建 A2A 智能体"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "agent_id": "a2a_6mWqZ2pK9nLcR3tY8uVb4D"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/ResponseEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/A2AAgentCreateResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "agent_id": "a2a_6mWqZ2pK9nLcR3tY8uVb4D"
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -54338,68 +56181,78 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/A2AAgentCreateRequest"
+              },
+              "example": {
+                "agent_name": "deploy-bot",
+                "instructions": "Inspect deployment pipelines and propose rollbacks when a canary fails health checks.",
+                "card_url": "https://agents.example.com/deploy-bot/card",
+                "auth_type": "bearer",
+                "auth_config": {
+                  "token": "sk-agent-token-example-9f2c"
+                },
+                "streaming": true,
+                "team_id": 0,
+                "environments": [
+                  "env_8s7Hn2kLpQ3xYbVc4Wd2m"
+                ]
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/a2a-agent/delete": {
+      "post": {
+        "operationId": "remote-agent-write-delete",
+        "summary": "删除 A2A 智能体",
+        "description": "按 ID 软删除 A2A 智能体。",
+        "tags": [
+          "AI SRE/A2A 智能体"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "创建 A2A 智能体",
-        "tags": [
-          "AI SRE/A2A 智能体"
-        ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **Agent 管理**（`ai-sre`） |\n\n## 使用说明\n\n- `instructions` 为必填项；已弃用的 `description` 字段仍保留以兼容旧客户端，若两者同时传入则必须与 `instructions` 完全一致。\n- `card_url` 必须是 host 非空的绝对 `http`/`https` URL（可达性由执行环境验证，此处不检查）；`auth_type` 仅接受 `none`、`api_key` 或 `bearer`。\n- `environments` 限定智能体可运行的环境：`cloud` 和/或 BYOC Runner 的环境 ID 列表；省略或为空表示所有环境，且每个 Runner 必须对调用者可见。\n- 创建到某个团队（`team_id > 0`）需要调用者真实属于该团队；只有账户 owner/admin 可以在账户级（`team_id=0`）创建。\n- 每次调用都会记录到账户审计日志。\n",
-          "href": "/zh/api-reference/ai-sre/a2a-agents/remote-agent-write-create",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **Agent 管理**（`ai-sre`） |\n\n## 使用说明\n\n- 软删除：智能体立即从列表和详情中消失，不能再被调用，其名称在原作用域内可以重新使用。\n- 需要对智能体当前所属团队有编辑权限：账户级智能体（`team_id=0`）仅账户 owner 或管理员可改；团队智能体仅该团队成员可改（owner/管理员也必须是该团队成员）。\n- 智能体不存在或已删除时返回 `ResourceNotFound`。\n- 每次调用都会记录到账户审计日志。\n",
+          "href": "/zh/api-reference/ai-sre/a2a-agents/remote-agent-write-delete",
           "metadata": {
-            "sidebarTitle": "创建 A2A 智能体"
+            "sidebarTitle": "删除 A2A 智能体"
           }
-        }
-      }
-    },
-    "/safari/a2a-agent/delete": {
-      "post": {
-        "description": "按 ID 软删除 A2A 智能体。",
-        "operationId": "remote-agent-write-delete",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "agent_id": "a2a_6mWqZ2pK9nLcR3tY8uVb4D"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/A2AAgentIDRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": null,
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/ResponseEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "description": "成功时恒为 null。",
-                          "type": "null"
+                          "type": "null",
+                          "description": "成功时不返回该字段，响应体只有 `request_id`。"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -54417,68 +56270,67 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/A2AAgentIDRequest"
+              },
+              "example": {
+                "agent_id": "a2a_6mWqZ2pK9nLcR3tY8uVb4D"
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/a2a-agent/disable": {
+      "post": {
+        "operationId": "remote-agent-write-disable",
+        "summary": "禁用 A2A 智能体",
+        "description": "禁用已启用的 A2A 智能体。",
+        "tags": [
+          "AI SRE/A2A 智能体"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "删除 A2A 智能体",
-        "tags": [
-          "AI SRE/A2A 智能体"
-        ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **Agent 管理**（`ai-sre`） |\n\n## 使用说明\n\n- 删除为软删除；删除后该智能体不再出现在列表/详情中，也无法再被调度。\n- 需要对智能体所属团队具备编辑权限（`access.CanEdit`）。\n- 每次调用都会记录到账户审计日志。\n",
-          "href": "/zh/api-reference/ai-sre/a2a-agents/remote-agent-write-delete",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **Agent 管理**（`ai-sre`） |\n\n## 使用说明\n\n- 需要对智能体当前所属团队有编辑权限：账户级智能体（`team_id=0`）仅账户 owner 或管理员可改；团队智能体仅该团队成员可改（owner/管理员也必须是该团队成员）。\n- 智能体已处于停用状态时返回 `InvalidParameter`。\n- 停用后，该智能体不再提供给 AI SRE 会话使用，配置保留。\n- 每次调用都会记录到账户审计日志。\n",
+          "href": "/zh/api-reference/ai-sre/a2a-agents/remote-agent-write-disable",
           "metadata": {
-            "sidebarTitle": "删除 A2A 智能体"
+            "sidebarTitle": "禁用 A2A 智能体"
           }
-        }
-      }
-    },
-    "/safari/a2a-agent/disable": {
-      "post": {
-        "description": "禁用已启用的 A2A 智能体。",
-        "operationId": "remote-agent-write-disable",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "agent_id": "a2a_6mWqZ2pK9nLcR3tY8uVb4D"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/A2AAgentIDRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": null,
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/ResponseEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "description": "成功时恒为 null。",
-                          "type": "null"
+                          "type": "null",
+                          "description": "成功时不返回该字段，响应体只有 `request_id`。"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -54496,68 +56348,67 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/A2AAgentIDRequest"
+              },
+              "example": {
+                "agent_id": "a2a_6mWqZ2pK9nLcR3tY8uVb4D"
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/a2a-agent/enable": {
+      "post": {
+        "operationId": "remote-agent-write-enable",
+        "summary": "启用 A2A 智能体",
+        "description": "启用已禁用的 A2A 智能体。",
+        "tags": [
+          "AI SRE/A2A 智能体"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "禁用 A2A 智能体",
-        "tags": [
-          "AI SRE/A2A 智能体"
-        ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **Agent 管理**（`ai-sre`） |\n\n## 使用说明\n\n- 需要对智能体所属团队具备编辑权限（`access.CanEdit`）。\n- 若智能体已处于禁用状态，返回 `InvalidParameter`。\n- 每次调用都会记录到账户审计日志。\n",
-          "href": "/zh/api-reference/ai-sre/a2a-agents/remote-agent-write-disable",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **Agent 管理**（`ai-sre`） |\n\n## 使用说明\n\n- 需要对智能体当前所属团队有编辑权限：账户级智能体（`team_id=0`）仅账户 owner 或管理员可改；团队智能体仅该团队成员可改（owner/管理员也必须是该团队成员）。\n- 智能体已处于启用状态时返回 `InvalidParameter`。\n- 启用后，该智能体会重新提供给 AI SRE 会话使用。\n- 每次调用都会记录到账户审计日志。\n",
+          "href": "/zh/api-reference/ai-sre/a2a-agents/remote-agent-write-enable",
           "metadata": {
-            "sidebarTitle": "禁用 A2A 智能体"
+            "sidebarTitle": "启用 A2A 智能体"
           }
-        }
-      }
-    },
-    "/safari/a2a-agent/enable": {
-      "post": {
-        "description": "启用已禁用的 A2A 智能体。",
-        "operationId": "remote-agent-write-enable",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "agent_id": "a2a_6mWqZ2pK9nLcR3tY8uVb4D"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/A2AAgentIDRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": null,
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/ResponseEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "description": "成功时恒为 null。",
-                          "type": "null"
+                          "type": "null",
+                          "description": "成功时不返回该字段，响应体只有 `request_id`。"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -54575,92 +56426,90 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/A2AAgentIDRequest"
+              },
+              "example": {
+                "agent_id": "a2a_6mWqZ2pK9nLcR3tY8uVb4D"
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/a2a-agent/get": {
+      "post": {
+        "operationId": "remote-agent-read-get",
+        "summary": "查看 A2A 智能体详情",
+        "description": "按 ID 返回单个 A2A 智能体的配置，认证密钥已脱敏。",
+        "tags": [
+          "AI SRE/A2A 智能体"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "启用 A2A 智能体",
-        "tags": [
-          "AI SRE/A2A 智能体"
-        ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **Agent 管理**（`ai-sre`） |\n\n## 使用说明\n\n- 需要对智能体所属团队具备编辑权限（`access.CanEdit`），仅可见不足以调用。\n- 若智能体已处于启用状态，返回 `InvalidParameter`。\n- 每次调用都会记录到账户审计日志。\n",
-          "href": "/zh/api-reference/ai-sre/a2a-agents/remote-agent-write-enable",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- `auth_config` 中 `api_key`、`token`、`client_secret` 以及其他加密存储的值会脱敏：超过 8 个字符时只显示首尾各 4 个字符，中间为 `****`，否则显示 `****`。\n- `card_resolve_timeout` 与 `task_timeout` 目前恒为 `0` —— API 尚未提供设置方式。\n- 智能体不存在或已删除时返回 `ResourceNotFound`。\n",
+          "href": "/zh/api-reference/ai-sre/a2a-agents/remote-agent-read-get",
           "metadata": {
-            "sidebarTitle": "启用 A2A 智能体"
+            "sidebarTitle": "查看 A2A 智能体详情"
           }
-        }
-      }
-    },
-    "/safari/a2a-agent/get": {
-      "post": {
-        "description": "按 ID 查看单个 A2A 智能体。",
-        "operationId": "remote-agent-read-get",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "agent_id": "a2a_6mWqZ2pK9nLcR3tY8uVb4D"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/A2AAgentIDRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "account_id": 10023,
-                    "agent_card_name": "Deploy Bot",
-                    "agent_card_skills": [
-                      "rollback",
-                      "diff"
-                    ],
-                    "agent_id": "a2a_6mWqZ2pK9nLcR3tY8uVb4D",
-                    "agent_name": "deploy-bot",
-                    "auth_mode": "shared",
-                    "auth_type": "bearer",
-                    "can_edit": true,
-                    "card_resolve_timeout": 0,
-                    "card_url": "https://agents.example.com/deploy-bot/card",
-                    "created_at": 1716960000000,
-                    "created_by": 80011,
-                    "environments": [
-                      "env_8s7Hn2kLpQ3xYbVc4Wd2m"
-                    ],
-                    "instructions": "Inspect deployment pipelines and propose rollbacks when a canary fails health checks.",
-                    "status": "enabled",
-                    "streaming": true,
-                    "task_timeout": 0,
-                    "team_id": 0,
-                    "updated_at": 1717046400000
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/ResponseEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/A2AAgentItem"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "agent_id": "a2a_6mWqZ2pK9nLcR3tY8uVb4D",
+                    "account_id": 10023,
+                    "team_id": 0,
+                    "can_edit": true,
+                    "environments": [
+                      "env_8s7Hn2kLpQ3xYbVc4Wd2m"
+                    ],
+                    "agent_name": "deploy-bot",
+                    "instructions": "Inspect deployment pipelines and propose rollbacks when a canary fails health checks.",
+                    "card_url": "https://agents.example.com/deploy-bot/card",
+                    "auth_type": "bearer",
+                    "auth_config": {
+                      "token": "sk-a****9f2c"
+                    },
+                    "streaming": true,
+                    "status": "enabled",
+                    "card_resolve_timeout": 0,
+                    "task_timeout": 0,
+                    "auth_mode": "shared",
+                    "created_by": 80011,
+                    "created_at": 1716960000000,
+                    "updated_at": 1717046400000
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -54668,6 +56517,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -54675,99 +56527,95 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/A2AAgentIDRequest"
+              },
+              "example": {
+                "agent_id": "a2a_6mWqZ2pK9nLcR3tY8uVb4D"
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/a2a-agent/list": {
+      "post": {
+        "operationId": "remote-agent-read-list",
+        "summary": "查询 A2A 智能体列表",
+        "description": "分页查询调用者在账户与团队范围内可见的 A2A 智能体。",
+        "tags": [
+          "AI SRE/A2A 智能体"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "查看 A2A 智能体详情",
-        "tags": [
-          "AI SRE/A2A 智能体"
-        ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- `card_resolve_timeout` 与 `task_timeout` 目前恒为 `0` —— API 尚未提供设置方式。\n",
-          "href": "/zh/api-reference/ai-sre/a2a-agents/remote-agent-read-get",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 分页使用 `offset`/`limit`（而非 `p`/`limit`）；`limit` 小于等于 0 时按 20 处理。结果按创建时间倒序排列。\n- 可见范围对所有调用者（含 owner 和管理员）都按真实团队成员关系计算：账户级记录，加上调用者所属团队的记录；`team_ids` 中不在此范围内的团队 ID 会被忽略。\n- `scope=account` 只返回账户级记录；`scope=team` 只返回团队记录；`all`（默认）返回团队记录，并在 `include_account` 不为 `false` 时一并返回账户级记录。\n- `query` 会在智能体名称、指令、卡片 URL、智能体 ID 和卡片名称中执行不区分大小写的子串搜索。\n- 每条记录的 `can_edit` 表示调用者能否更新、启用、停用或删除该智能体。\n",
+          "href": "/zh/api-reference/ai-sre/a2a-agents/remote-agent-read-list",
           "metadata": {
-            "sidebarTitle": "查看 A2A 智能体详情"
+            "sidebarTitle": "查询 A2A 智能体列表"
           }
-        }
-      }
-    },
-    "/safari/a2a-agent/list": {
-      "post": {
-        "description": "分页查询调用者在账户与团队范围内可见的 A2A 智能体。",
-        "operationId": "remote-agent-read-list",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "include_account": true,
-                "limit": 20,
-                "offset": 0
-              },
-              "schema": {
-                "$ref": "#/components/schemas/A2AAgentListRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ResponseEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/A2AAgentListResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "items": [
                       {
-                        "account_id": 10023,
-                        "agent_card_name": "Deploy Bot",
-                        "agent_card_skills": [
-                          "rollback",
-                          "diff"
-                        ],
                         "agent_id": "a2a_6mWqZ2pK9nLcR3tY8uVb4D",
-                        "agent_name": "deploy-bot",
-                        "auth_mode": "shared",
-                        "auth_type": "bearer",
+                        "account_id": 10023,
+                        "team_id": 0,
                         "can_edit": true,
-                        "card_resolve_timeout": 0,
-                        "card_url": "https://agents.example.com/deploy-bot/card",
-                        "created_at": 1716960000000,
-                        "created_by": 80011,
                         "environments": [
                           "env_8s7Hn2kLpQ3xYbVc4Wd2m"
                         ],
+                        "agent_name": "deploy-bot",
                         "instructions": "Inspect deployment pipelines and propose rollbacks when a canary fails health checks.",
-                        "status": "enabled",
+                        "card_url": "https://agents.example.com/deploy-bot/card",
+                        "auth_type": "bearer",
+                        "auth_config": {
+                          "token": "sk-a****9f2c"
+                        },
                         "streaming": true,
+                        "status": "enabled",
+                        "card_resolve_timeout": 0,
                         "task_timeout": 0,
-                        "team_id": 0,
+                        "auth_mode": "shared",
+                        "created_by": 80011,
+                        "created_at": 1716960000000,
                         "updated_at": 1717046400000
                       }
                     ],
                     "total": 1
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/ResponseEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/A2AAgentListResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -54775,6 +56623,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -54782,69 +56633,69 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/A2AAgentListRequest"
+              },
+              "example": {
+                "offset": 0,
+                "limit": 20,
+                "include_account": true
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/a2a-agent/update": {
+      "post": {
+        "operationId": "remote-agent-write-update",
+        "summary": "更新 A2A 智能体",
+        "description": "对 A2A 智能体执行部分更新；省略字段表示不变。",
+        "tags": [
+          "AI SRE/A2A 智能体"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "查询 A2A 智能体列表",
-        "tags": [
-          "AI SRE/A2A 智能体"
-        ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 分页使用 `offset`/`limit`（而非 `p`/`limit`）。\n- `scope=account` 仅返回账户级智能体；`scope=team` 仅返回调用者可见团队中的智能体；默认 `all` 两者兼含，受 `include_account` 影响。\n- `query` 会在智能体名称、指令、卡片 URL、智能体 ID 以及解析得到的卡片名称中执行不区分大小写的子串搜索。\n- `card_resolve_timeout` 与 `task_timeout` 目前恒为 `0` —— API 尚未提供设置方式。\n",
-          "href": "/zh/api-reference/ai-sre/a2a-agents/remote-agent-read-list",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **Agent 管理**（`ai-sre`） |\n\n## 使用说明\n\n- 需要对智能体当前所属团队有编辑权限：账户级智能体（`team_id=0`）仅账户 owner 或管理员可改；团队智能体仅该团队成员可改（owner/管理员也必须是该团队成员）。\n- 改到其他团队（`team_id > 0`）要求调用者属于目标团队；改为账户级（`team_id=0`）仅限账户 owner 或管理员。变更团队但未同时传 `environments` 时，现有 Runner 条目必须对调用者仍可选，否则更新被拒绝。\n- `auth_config` 整体替换：未传入的键会被删除。对 `api_key`、`token`、`client_secret`，回传详情接口返回的脱敏值会保留已存储的密钥，传空字符串则清除该密钥。\n- 传入 `auth_mode` 时，`secret_schema` 会被同一请求中的值覆盖（未传则置空）。`auth_mode` 或 `card_url` 实际发生变化时会清空 `oauth_metadata`，除非同时传入非空的 `oauth_metadata`；只传空的 `oauth_metadata` 不会改动已存储的值。\n- 修改 `card_url` 会重新执行创建时的智能体卡片兼容性检查；修改 `agent_name` 会重新校验命名规则。\n- 每次调用都会记录到账户审计日志。\n",
+          "href": "/zh/api-reference/ai-sre/a2a-agents/remote-agent-write-update",
           "metadata": {
-            "sidebarTitle": "查询 A2A 智能体列表"
+            "sidebarTitle": "更新 A2A 智能体"
           }
-        }
-      }
-    },
-    "/safari/a2a-agent/update": {
-      "post": {
-        "description": "对 A2A 智能体执行部分更新；省略字段表示不变。",
-        "operationId": "remote-agent-write-update",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "agent_id": "a2a_6mWqZ2pK9nLcR3tY8uVb4D",
-                "instructions": "Inspect deployment pipelines and propose rollbacks."
-              },
-              "schema": {
-                "$ref": "#/components/schemas/A2AAgentUpdateRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": null,
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/ResponseEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "description": "成功时恒为 null。",
-                          "type": "null"
+                          "type": "null",
+                          "description": "成功时不返回该字段，响应体只有 `request_id`。"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -54862,68 +56713,81 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/A2AAgentUpdateRequest"
+              },
+              "example": {
+                "agent_id": "a2a_6mWqZ2pK9nLcR3tY8uVb4D",
+                "instructions": "Inspect deployment pipelines and propose rollbacks."
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/artifact/gallery/delete": {
+      "post": {
+        "operationId": "artifact-write-delete",
+        "summary": "从产物库移除产物",
+        "description": "将产物从产物库移除；来源文件仍保留在会话中。",
+        "tags": [
+          "AI SRE/产物"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "更新 A2A 智能体",
-        "tags": [
-          "AI SRE/A2A 智能体"
-        ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **Agent 管理**（`ai-sre`） |\n\n## 使用说明\n\n- 任何字段变更前都需要对智能体*当前*所属团队具备编辑权限（`access.CanEdit`）。\n- 重新分配 `team_id` 需要对目标团队的权限；若团队变更且未同时传入新的环境绑定，则现有 Runner 绑定必须对调用者仍可选，否则更新将被拒绝。\n- 变更 `auth_mode` 时会始终一并重写 `secret_schema`；若变更 `auth_mode` 时未传入 `oauth_metadata`，则将其清空。\n- 对敏感的 `auth_config` 键（`api_key`、`token`、`client_secret`）回传挖码值或空字符串将保留已存储的密钥，而不会覆盖。\n- 每次调用都会记录到账户审计日志。\n",
-          "href": "/zh/api-reference/ai-sre/a2a-agents/remote-agent-write-update",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 该操作只是从产物库移除，不删除文件本身。文件仍保留在来源会话中，可再次发布，再次发布会恢复同一个 `artifact_id`。\n- 需要对该产物有 `can_edit` 权限（创建者、归属团队的任一成员，或能管理来源会话的成员），否则返回 `AccessDenied`。\n- 如果已开启公开分享，公开内容会在同一操作中删除，链接随即失效。所有成员对该产物的置顶也会被清除。\n- 若来源会话已被删除，文件本身会在产物移除 30 天后被永久删除。\n- 每次调用都会记录到账户审计日志。\n",
+          "href": "/zh/api-reference/ai-sre/artifacts/artifact-write-delete",
           "metadata": {
-            "sidebarTitle": "更新 A2A 智能体"
+            "sidebarTitle": "从产物库移除产物"
           }
-        }
-      }
-    },
-    "/safari/artifact/gallery/delete": {
-      "post": {
-        "description": "将产物从产物库移除；来源文件仍保留在会话中。",
-        "operationId": "artifact-write-delete",
+        },
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {
-                "artifact_id": "art_CWQzDU2PXSRJvKDhQbuMKu"
-              },
               "schema": {
                 "$ref": "#/components/schemas/ArtifactIdRequest"
+              },
+              "example": {
+                "artifact_id": "art_CWQzDU2PXSRJvKDhQbuMKu"
               }
             }
-          },
-          "required": true
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": null,
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/ResponseEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "description": "成功时恒为 null。",
-                          "type": "null"
+                          "type": "null",
+                          "description": "成功时不返回该字段，响应体只有 `request_id`。"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -54931,86 +56795,89 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
           "500": {
             "$ref": "#/components/responses/ServerError"
           }
-        },
+        }
+      }
+    },
+    "/safari/artifact/gallery/file-state": {
+      "post": {
+        "operationId": "artifact-read-get-file-state",
+        "summary": "查询文件发布状态",
+        "description": "批量查询文件是否已发布为产物。",
+        "tags": [
+          "AI SRE/产物"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "从产物库移除产物",
-        "tags": [
-          "AI SRE/产物"
-        ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 该操作只是从产物库移除，不会删除文件本身 —— 来源文件仍保留在会话中，可再次发布。\n- 如果产物已开启公开分享，公开内容会在同一操作中被销毁，公开链接立即失效。\n- 每次调用都会记录到账户审计日志。\n",
-          "href": "/zh/api-reference/ai-sre/artifacts/artifact-write-delete",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 用于判断会话中产出的文件是否已在产物库中，例如在调用 `/safari/artifact/gallery/publish-from-file` 之前。\n- 按文件所属会话和工作区路径匹配，而不是按精确的 `file_id`：已被重新发布的文件的旧版本也会返回当前产物。\n- 没有已发布产物的文件、以及账户内不存在的 ID 不会出现在 `items` 中；请按回显的 `file_id` 对应结果。\n",
+          "href": "/zh/api-reference/ai-sre/artifacts/artifact-read-get-file-state",
           "metadata": {
-            "sidebarTitle": "从产物库移除产物"
+            "sidebarTitle": "查询文件发布状态"
           }
-        }
-      }
-    },
-    "/safari/artifact/gallery/file-state": {
-      "post": {
-        "description": "批量查询文件是否已发布为产物。",
-        "operationId": "artifact-read-get-file-state",
+        },
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ArtifactFileStateRequest"
+              },
               "example": {
                 "file_ids": [
                   "pf_SdhEA5fbZJGnHzwrNJMMSB",
                   "pf_9kLm2nQpRsTuVwXyZaBcDe"
                 ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ArtifactFileStateRequest"
               }
             }
-          },
-          "required": true
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "items": [
-                      {
-                        "artifact_id": "art_VnfrWic8UbB9q3EfYR4Gmg",
-                        "file_id": "pf_SdhEA5fbZJGnHzwrNJMMSB",
-                        "gallery_path": "/ai-sre/artifacts/art_VnfrWic8UbB9q3EfYR4Gmg",
-                        "title": "SK 海力士 2026 Q2 财报深度分析"
-                      }
-                    ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/ResponseEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/ArtifactFileStateResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "items": [
+                      {
+                        "file_id": "pf_SdhEA5fbZJGnHzwrNJMMSB",
+                        "artifact_id": "art_VnfrWic8UbB9q3EfYR4Gmg",
+                        "title": "支付接口延迟复盘报告",
+                        "gallery_path": "/ai-sre/artifacts/art_VnfrWic8UbB9q3EfYR4Gmg"
+                      }
+                    ]
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -55018,96 +56885,100 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
           "500": {
             "$ref": "#/components/responses/ServerError"
           }
-        },
+        }
+      }
+    },
+    "/safari/artifact/gallery/get": {
+      "post": {
+        "operationId": "artifact-read-get",
+        "summary": "获取产物详情",
+        "description": "按 ID 获取单个已发布产物，包括来源文件、归属和公开分享状态。",
+        "tags": [
+          "AI SRE/产物"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "查询文件发布状态",
-        "tags": [
-          "AI SRE/产物"
-        ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 单次最多传入 50 个 `file_ids`；重复和空字符串会被忽略。\n- 没有已发布产物的文件不会出现在 `items` 中 —— 按回显的 `file_id` 对应结果。\n",
-          "href": "/zh/api-reference/ai-sre/artifacts/artifact-read-get-file-state",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 账户内任何成员都可按 ID 读取任意产物，包括其他成员的个人产物；`is_mine` 和 `can_edit` 按 `app_key` 所属成员计算。\n- 产物不存在或已移除时返回 `ResourceNotFound`。\n- 当 `share_enabled` 为 true 且 `file_id` 与 `share_file_id` 不一致时，公开快照已过期，可调用 `/safari/artifact/gallery/share/sync` 刷新。\n",
+          "href": "/zh/api-reference/ai-sre/artifacts/artifact-read-get",
           "metadata": {
-            "sidebarTitle": "查询文件发布状态"
+            "sidebarTitle": "获取产物详情"
           }
-        }
-      }
-    },
-    "/safari/artifact/gallery/get": {
-      "post": {
-        "description": "根据产物 ID 获取产物详情。",
-        "operationId": "artifact-read-get",
+        },
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {
-                "artifact_id": "art_VnfrWic8UbB9q3EfYR4Gmg"
-              },
               "schema": {
                 "$ref": "#/components/schemas/ArtifactIdRequest"
+              },
+              "example": {
+                "artifact_id": "art_VnfrWic8UbB9q3EfYR4Gmg"
               }
             }
-          },
-          "required": true
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "artifact_id": "art_VnfrWic8UbB9q3EfYR4Gmg",
-                    "can_edit": true,
-                    "content_type": "text/html",
-                    "created_at": 1785293373899,
-                    "creator_name": "yushuangyu",
-                    "file_id": "pf_SdhEA5fbZJGnHzwrNJMMSB",
-                    "is_mine": true,
-                    "name": "sk-hynix-q2-2026-report.html",
-                    "person_id": 2476444212131,
-                    "public_url": "https://console.flashcat.cloud/share/artifact/art_VnfrWic8UbB9q3EfYR4Gmg",
-                    "session_id": "sess_VCbVPZrq9YoyBu8sNCmqUy",
-                    "session_title": "分析海力士财报并发布报告",
-                    "share_enabled": true,
-                    "share_file_id": "pf_SdhEA5fbZJGnHzwrNJMMSB",
-                    "shared_at": 1785747928665,
-                    "shared_by": 3790925372131,
-                    "size": 18996,
-                    "team_id": 2477033058131,
-                    "team_name": "研发团队",
-                    "title": "SK 海力士 2026 Q2 财报深度分析",
-                    "updated_at": 1785747910219
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/ResponseEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/PublishedArtifactItem"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "artifact_id": "art_VnfrWic8UbB9q3EfYR4Gmg",
+                    "title": "支付接口延迟复盘报告",
+                    "team_id": 4012,
+                    "team_name": "SRE 团队",
+                    "person_id": 2476001,
+                    "creator_name": "张伟",
+                    "is_mine": true,
+                    "can_edit": true,
+                    "session_id": "sess_VCbVPZrq9YoyBu8sNCmqUy",
+                    "session_title": "排查支付接口延迟突增",
+                    "file_id": "pf_SdhEA5fbZJGnHzwrNJMMSB",
+                    "name": "checkout-latency-postmortem.html",
+                    "size": 18996,
+                    "content_type": "text/html",
+                    "created_at": 1785293373899,
+                    "updated_at": 1785747910219,
+                    "pinned_at": 1785750000000,
+                    "share_enabled": true,
+                    "public_url": "https://console.flashcat.cloud/share/artifact/art_VnfrWic8UbB9q3EfYR4Gmg",
+                    "shared_by": 2476001,
+                    "shared_at": 1785747928665,
+                    "share_file_id": "pf_SdhEA5fbZJGnHzwrNJMMSB"
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -55115,121 +56986,125 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
           "500": {
             "$ref": "#/components/responses/ServerError"
           }
-        },
+        }
+      }
+    },
+    "/safari/artifact/gallery/list": {
+      "post": {
+        "operationId": "artifact-read-list",
+        "summary": "查询产物列表",
+        "description": "分页查询调用者可见的产物列表，支持按标题搜索。",
+        "tags": [
+          "AI SRE/产物"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "获取产物详情",
-        "tags": [
-          "AI SRE/产物"
-        ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 可见范围为整个账号：任何有效 `app_key` 都能读取账号内任意产物。`is_mine` 和 `can_edit` 相对于 key 所属成员计算。\n- 当 `share_enabled` 为 true 且 `file_id` 与 `share_file_id` 不一致时，公开快照已过期 —— 调用 `/safari/artifact/gallery/share/sync` 刷新。\n",
-          "href": "/zh/api-reference/ai-sre/artifacts/artifact-read-get",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- `scope` 可选 `all`（默认：调用者自己的个人产物加上其所属全部团队的产物）、`personal`（仅调用者自己的个人产物）、`team`（仅调用者所属团队拥有的产物）。未知取值按 `all` 处理。\n- 可见范围按 `app_key` 所属成员的身份和实际团队成员关系计算，账户所有者和管理员在此也不会多看到产物。要按 ID 打开账户内任意产物，请用 `/safari/artifact/gallery/get`。\n- 调用者置顶的产物总排在最前；其余默认按 `updated_at` 倒序，可通过 `orderby`/`asc` 调整。\n",
+          "href": "/zh/api-reference/ai-sre/artifacts/artifact-read-list",
           "metadata": {
-            "sidebarTitle": "获取产物详情"
+            "sidebarTitle": "查询产物列表"
           }
-        }
-      }
-    },
-    "/safari/artifact/gallery/list": {
-      "post": {
-        "description": "分页查询调用者可见的产物列表，支持按标题搜索。",
-        "operationId": "artifact-read-list",
+        },
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {
-                "limit": 20,
-                "page": 1,
-                "scope": "all"
-              },
               "schema": {
                 "$ref": "#/components/schemas/ArtifactListRequest"
+              },
+              "example": {
+                "scope": "all",
+                "page": 1,
+                "limit": 20
               }
             }
-          },
-          "required": true
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ResponseEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/ArtifactListResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "items": [
                       {
                         "artifact_id": "art_VnfrWic8UbB9q3EfYR4Gmg",
+                        "title": "支付接口延迟复盘报告",
+                        "team_id": 4012,
+                        "team_name": "SRE 团队",
+                        "person_id": 2476001,
+                        "creator_name": "张伟",
+                        "is_mine": true,
                         "can_edit": true,
+                        "session_id": "sess_VCbVPZrq9YoyBu8sNCmqUy",
+                        "session_title": "排查支付接口延迟突增",
+                        "file_id": "pf_SdhEA5fbZJGnHzwrNJMMSB",
+                        "name": "checkout-latency-postmortem.html",
+                        "size": 18996,
                         "content_type": "text/html",
                         "created_at": 1785293373899,
-                        "creator_name": "yushuangyu",
-                        "file_id": "pf_SdhEA5fbZJGnHzwrNJMMSB",
-                        "is_mine": true,
-                        "name": "sk-hynix-q2-2026-report.html",
-                        "person_id": 2476444212131,
-                        "public_url": "https://console.flashcat.cloud/share/artifact/art_VnfrWic8UbB9q3EfYR4Gmg",
-                        "session_id": "sess_VCbVPZrq9YoyBu8sNCmqUy",
-                        "session_title": "分析海力士财报并发布报告",
+                        "updated_at": 1785747910219,
+                        "pinned_at": 1785750000000,
                         "share_enabled": true,
-                        "share_file_id": "pf_SdhEA5fbZJGnHzwrNJMMSB",
+                        "public_url": "https://console.flashcat.cloud/share/artifact/art_VnfrWic8UbB9q3EfYR4Gmg",
+                        "shared_by": 2476001,
                         "shared_at": 1785747928665,
-                        "shared_by": 3790925372131,
-                        "size": 18996,
-                        "team_id": 2477033058131,
-                        "team_name": "研发团队",
-                        "title": "SK 海力士 2026 Q2 财报深度分析",
-                        "updated_at": 1785747910219
+                        "share_file_id": "pf_SdhEA5fbZJGnHzwrNJMMSB"
                       },
                       {
                         "artifact_id": "art_CWQzDU2PXSRJvKDhQbuMKu",
-                        "can_edit": true,
-                        "content_type": "application/pdf",
-                        "created_at": 1785229432881,
-                        "creator_name": "牛伟利",
-                        "file_id": "pf_Jnc4E5YBcWLGzunB4ntP9s",
+                        "title": "告警降噪周报",
+                        "team_id": 4012,
+                        "team_name": "SRE 团队",
+                        "person_id": 2476002,
+                        "creator_name": "李娜",
                         "is_mine": false,
-                        "name": "rum_recommendation.pdf",
-                        "person_id": 3790925372131,
+                        "can_edit": true,
                         "session_id": "sess_QXUC9C2PYWP5EE7vETR3UD",
-                        "session_title": "生成 RUM 文档多格式",
+                        "session_title": "汇总上周告警噪声",
+                        "file_id": "pf_Jnc4E5YBcWLGzunB4ntP9s",
+                        "name": "alert-noise-weekly.pdf",
                         "size": 137107,
-                        "team_id": 2477033058131,
-                        "team_name": "研发团队",
-                        "title": "rum_recommendation",
+                        "content_type": "application/pdf",
+                        "created_at": 1785229432881,
                         "updated_at": 1785741344822
                       }
                     ],
                     "total": 17
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/ResponseEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/ArtifactListResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -55237,79 +57112,82 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
           "500": {
             "$ref": "#/components/responses/ServerError"
           }
-        },
+        }
+      }
+    },
+    "/safari/artifact/gallery/publish-from-file": {
+      "post": {
+        "operationId": "artifact-write-publish",
+        "summary": "发布文件为产物",
+        "description": "将会话中生成的文件发布到产物库。",
+        "tags": [
+          "AI SRE/产物"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "查询产物列表",
-        "tags": [
-          "AI SRE/产物"
-        ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- `scope` 可选 `all`（默认 —— 调用者自己的个人产物 + 其所属全部团队的产物）、`personal`（仅自己创建的）、`team`（仅所属团队的团队产物）。\n- `team_ids` 可在可见范围内进一步限定团队 —— 调用者不属于的团队不会有任何返回。\n- 默认按 `updated_at` 倒序；设置 `orderby` 为 `created_at` 可更换排序字段，`asc: true` 改为升序。\n- 使用 `app_key` 调用时，可见范围按 key 所属成员的身份计算 —— 返回该成员的个人产物及其所在团队的产物。\n",
-          "href": "/zh/api-reference/ai-sre/artifacts/artifact-read-list",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 能看到该文件的账户成员都可以发布。若该文件路径已有已发布产物，再次发布会替换该产物，需要对其有 `can_edit` 权限。\n- 允许的文件类型：HTML/Markdown、图片、PDF、文本/数据/代码文件以及 zip/tar 压缩包（按扩展名判断）。其他类型、超过 16 MiB 的文件、以及已无法取回的文件（runner 离线或文件过期）返回 `InvalidParameter`。\n- 发布按（来源会话 + 工作区路径）做 upsert：再次发布会以新的 `file_id` 替换标题和内容，`artifact_id` 不变，已有的公开快照因此过期，需同步刷新。再次发布已移除的产物会以同一 `artifact_id` 恢复，且分享处于关闭状态。\n- 新产物的创建者和个人/团队空间取自来源会话（会话所有者及其团队）；如需调整，发布后调用 `/safari/artifact/gallery/update`。\n- 每次调用都会记录到账户审计日志。\n",
+          "href": "/zh/api-reference/ai-sre/artifacts/artifact-write-publish",
           "metadata": {
-            "sidebarTitle": "查询产物列表"
+            "sidebarTitle": "发布文件为产物"
           }
-        }
-      }
-    },
-    "/safari/artifact/gallery/publish-from-file": {
-      "post": {
-        "description": "将会话中生成的文件发布到产物库。",
-        "operationId": "artifact-write-publish",
+        },
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {
-                "file_id": "pf_SdhEA5fbZJGnHzwrNJMMSB",
-                "title": "SK 海力士 2026 Q2 财报深度分析"
-              },
               "schema": {
                 "$ref": "#/components/schemas/ArtifactPublishFromFileRequest"
+              },
+              "example": {
+                "file_id": "pf_SdhEA5fbZJGnHzwrNJMMSB",
+                "title": "支付接口延迟复盘报告"
               }
             }
-          },
-          "required": true
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "artifact_id": "art_VnfrWic8UbB9q3EfYR4Gmg",
-                    "gallery_path": "/ai-sre/artifacts/art_VnfrWic8UbB9q3EfYR4Gmg",
-                    "title": "SK 海力士 2026 Q2 财报深度分析"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/ResponseEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/ArtifactPublishResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "artifact_id": "art_VnfrWic8UbB9q3EfYR4Gmg",
+                    "title": "支付接口延迟复盘报告",
+                    "gallery_path": "/ai-sre/artifacts/art_VnfrWic8UbB9q3EfYR4Gmg"
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -55317,80 +57195,83 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
           "500": {
             "$ref": "#/components/responses/ServerError"
           }
-        },
+        }
+      }
+    },
+    "/safari/artifact/gallery/share/enable": {
+      "post": {
+        "operationId": "artifact-write-share-enable",
+        "summary": "开启公开分享",
+        "description": "开启产物的匿名公开分享并返回公开链接。",
+        "tags": [
+          "AI SRE/产物"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "发布文件为产物",
-        "tags": [
-          "AI SRE/产物"
-        ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 允许的文件类型：HTML/Markdown、图片、PDF、文本/数据/代码文件以及 zip/tar 压缩包（按扩展名判断）。超过 16 MiB 的文件会被拒绝。\n- 发布按（来源会话 + 工作区路径）做 upsert —— 重复发布同一文件会替换产物内容并使用新的 `file_id`，已有的公开快照会因此过期，需执行分享同步刷新。\n- 产物继承来源会话的个人/团队空间；如需调整，发布后调用 `/safari/artifact/gallery/update` 转移。\n- 每次调用都会记录到账户审计日志。\n",
-          "href": "/zh/api-reference/ai-sre/artifacts/artifact-write-publish",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 公开链接是匿名的：任何拿到链接的人都可以查看内容，链接也可能被继续转发。内容会被复制到公开 CDN 对象上，访问链接时不经过本 API。\n- 需要对该产物有 `can_edit` 权限（创建者、归属团队的任一成员，或能管理来源会话的成员），否则返回 `AccessDenied`。\n- 幂等：对已分享的产物重复开启会原样返回当前状态；撤销后重新开启会得到同一个链接，因为链接以产物 ID 为标识。\n- 超过 16 MiB 的产物无法分享，调用返回 `InvalidParameter`。未配置公开分享的部署环境中，调用返回 `InternalError`。\n- 分享是内容快照：之后重新发布产物不会自动更新公开内容，需调用 `/safari/artifact/gallery/share/sync` 同步。\n- 每次调用都会记录到账户审计日志。\n",
+          "href": "/zh/api-reference/ai-sre/artifacts/artifact-write-share-enable",
           "metadata": {
-            "sidebarTitle": "发布文件为产物"
+            "sidebarTitle": "开启公开分享"
           }
-        }
-      }
-    },
-    "/safari/artifact/gallery/share/enable": {
-      "post": {
-        "description": "开启产物的匿名公开分享并返回公开链接。",
-        "operationId": "artifact-write-share-enable",
+        },
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {
-                "artifact_id": "art_VnfrWic8UbB9q3EfYR4Gmg"
-              },
               "schema": {
                 "$ref": "#/components/schemas/ArtifactIdRequest"
+              },
+              "example": {
+                "artifact_id": "art_VnfrWic8UbB9q3EfYR4Gmg"
               }
             }
-          },
-          "required": true
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "artifact_id": "art_VnfrWic8UbB9q3EfYR4Gmg",
-                    "public_url": "https://console.flashcat.cloud/share/artifact/art_VnfrWic8UbB9q3EfYR4Gmg",
-                    "share_enabled": true,
-                    "shared_at": 1785747928665,
-                    "shared_by": 2476444212131
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/ResponseEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/ArtifactShareState"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "artifact_id": "art_VnfrWic8UbB9q3EfYR4Gmg",
+                    "share_enabled": true,
+                    "public_url": "https://console.flashcat.cloud/share/artifact/art_VnfrWic8UbB9q3EfYR4Gmg",
+                    "shared_by": 2476001,
+                    "shared_at": 1785747928665
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -55398,75 +57279,77 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
           "500": {
             "$ref": "#/components/responses/ServerError"
           }
-        },
+        }
+      }
+    },
+    "/safari/artifact/gallery/share/revoke": {
+      "post": {
+        "operationId": "artifact-write-share-revoke",
+        "summary": "撤销公开分享",
+        "description": "撤销产物的公开分享，公开链接立即失效。",
+        "tags": [
+          "AI SRE/产物"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "开启公开分享",
-        "tags": [
-          "AI SRE/产物"
-        ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 公开链接是匿名的 —— 任何拿到链接的人都可以查看内容，链接也可能被继续转发。内容会被复制到公开 CDN 对象上，访问链接时不经过本 API。\n- 幂等：对已分享的产物重复开启会原样返回已有链接；撤销后重新开启也会得到同一个链接 —— 链接以产物 ID 为标识。\n- 超过 16 MiB 的产物无法分享，调用返回 `InvalidParameter`。\n- 分享是内容快照：之后重新发布产物不会自动更新公开内容，需调用 `/safari/artifact/gallery/share/sync` 同步。\n- 每次调用都会记录到账户审计日志。\n",
-          "href": "/zh/api-reference/ai-sre/artifacts/artifact-write-share-enable",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 公开 CDN 对象会被删除，链接随即失效。产物未开启分享时直接成功，不做任何变更。\n- 需要对该产物有 `can_edit` 权限（创建者、归属团队的任一成员，或能管理来源会话的成员），否则返回 `AccessDenied`。\n- 之后重新开启分享会返回同一个 `public_url`：链接以产物 ID 为标识，撤销并不能更换链接。\n- 每次调用都会记录到账户审计日志。\n",
+          "href": "/zh/api-reference/ai-sre/artifacts/artifact-write-share-revoke",
           "metadata": {
-            "sidebarTitle": "开启公开分享"
+            "sidebarTitle": "撤销公开分享"
           }
-        }
-      }
-    },
-    "/safari/artifact/gallery/share/revoke": {
-      "post": {
-        "description": "撤销产物的公开分享，公开链接立即失效。",
-        "operationId": "artifact-write-share-revoke",
+        },
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {
-                "artifact_id": "art_VnfrWic8UbB9q3EfYR4Gmg"
-              },
               "schema": {
                 "$ref": "#/components/schemas/ArtifactIdRequest"
+              },
+              "example": {
+                "artifact_id": "art_VnfrWic8UbB9q3EfYR4Gmg"
               }
             }
-          },
-          "required": true
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": null,
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/ResponseEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "description": "成功时恒为 null。",
-                          "type": "null"
+                          "type": "null",
+                          "description": "成功时不返回该字段，响应体只有 `request_id`。"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -55474,80 +57357,83 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
           "500": {
             "$ref": "#/components/responses/ServerError"
           }
-        },
+        }
+      }
+    },
+    "/safari/artifact/gallery/share/sync": {
+      "post": {
+        "operationId": "artifact-write-share-sync",
+        "summary": "更新公开分享快照",
+        "description": "将公开分享的内容快照更新为产物最新内容。",
+        "tags": [
+          "AI SRE/产物"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "撤销公开分享",
-        "tags": [
-          "AI SRE/产物"
-        ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 公开 CDN 对象会被删除，链接随即失效；产物未开启分享时该操作为空操作。\n- 之后重新开启分享会返回同一个 `public_url` —— 链接以产物 ID 为标识，撤销并不能用于更换链接。\n- 每次调用都会记录到账户审计日志。\n",
-          "href": "/zh/api-reference/ai-sre/artifacts/artifact-write-share-revoke",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 未开启分享时返回 `InvalidParameter`，请先开启分享。未配置公开分享的部署环境中，调用返回 `InternalError`。\n- 需要对该产物有 `can_edit` 权限（创建者、归属团队的任一成员，或能管理来源会话的成员），否则返回 `AccessDenied`。\n- 公开链接不变，只刷新快照内容和 `shared_at`；`shared_by` 仍为开启分享的成员。\n- 可通过产物详情中 `share_file_id != file_id` 判断快照是否过期，再决定是否同步。\n- 每次调用都会记录到账户审计日志。\n",
+          "href": "/zh/api-reference/ai-sre/artifacts/artifact-write-share-sync",
           "metadata": {
-            "sidebarTitle": "撤销公开分享"
+            "sidebarTitle": "更新公开分享快照"
           }
-        }
-      }
-    },
-    "/safari/artifact/gallery/share/sync": {
-      "post": {
-        "description": "将公开分享的内容快照更新为产物最新内容。",
-        "operationId": "artifact-write-share-sync",
+        },
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {
-                "artifact_id": "art_VnfrWic8UbB9q3EfYR4Gmg"
-              },
               "schema": {
                 "$ref": "#/components/schemas/ArtifactIdRequest"
+              },
+              "example": {
+                "artifact_id": "art_VnfrWic8UbB9q3EfYR4Gmg"
               }
             }
-          },
-          "required": true
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "artifact_id": "art_VnfrWic8UbB9q3EfYR4Gmg",
-                    "public_url": "https://console.flashcat.cloud/share/artifact/art_VnfrWic8UbB9q3EfYR4Gmg",
-                    "share_enabled": true,
-                    "shared_at": 1785829900000,
-                    "shared_by": 2476444212131
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/ResponseEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/ArtifactShareState"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "artifact_id": "art_VnfrWic8UbB9q3EfYR4Gmg",
+                    "share_enabled": true,
+                    "public_url": "https://console.flashcat.cloud/share/artifact/art_VnfrWic8UbB9q3EfYR4Gmg",
+                    "shared_by": 2476001,
+                    "shared_at": 1785829900000
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -55555,97 +57441,101 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
           "500": {
             "$ref": "#/components/responses/ServerError"
           }
-        },
+        }
+      }
+    },
+    "/safari/artifact/gallery/update": {
+      "post": {
+        "operationId": "artifact-write-update",
+        "summary": "更新产物",
+        "description": "更新产物标题，或在个人/团队空间之间转移产物。",
+        "tags": [
+          "AI SRE/产物"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "更新公开分享快照",
-        "tags": [
-          "AI SRE/产物"
-        ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 未开启分享时调用返回 `InvalidParameter` —— 请先开启分享。\n- 公开链接不变，仅更新快照内容和 `shared_at`。\n- 可通过产物详情中 `share_file_id != file_id` 判断快照是否过期，再决定是否同步。\n- 每次调用都会记录到账户审计日志。\n",
-          "href": "/zh/api-reference/ai-sre/artifacts/artifact-write-share-sync",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 仅更新传入的字段；不传 `title` 或 `team_id` 则保持不变。\n- 需要对该产物有 `can_edit` 权限（创建者、归属团队的任一成员，或能管理来源会话的成员），否则返回 `AccessDenied`。\n- `team_id: 0`（转为个人产物）仅创建者本人可执行；传入大于 0 的 `team_id` 时，调用者（`app_key` 调用时为 key 所属成员）必须是该团队成员。\n- 返回更新后的完整产物。\n- 每次调用都会记录到账户审计日志。\n",
+          "href": "/zh/api-reference/ai-sre/artifacts/artifact-write-update",
           "metadata": {
-            "sidebarTitle": "更新公开分享快照"
+            "sidebarTitle": "更新产物"
           }
-        }
-      }
-    },
-    "/safari/artifact/gallery/update": {
-      "post": {
-        "description": "更新产物标题，或在个人/团队空间之间转移产物。",
-        "operationId": "artifact-write-update",
+        },
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {
-                "artifact_id": "art_VnfrWic8UbB9q3EfYR4Gmg",
-                "title": "SK 海力士 2026 Q2 财报深度分析（终稿）"
-              },
               "schema": {
                 "$ref": "#/components/schemas/ArtifactUpdateRequest"
+              },
+              "example": {
+                "artifact_id": "art_VnfrWic8UbB9q3EfYR4Gmg",
+                "title": "支付接口延迟复盘报告（终稿）"
               }
             }
-          },
-          "required": true
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "artifact_id": "art_VnfrWic8UbB9q3EfYR4Gmg",
-                    "can_edit": true,
-                    "content_type": "text/html",
-                    "created_at": 1785293373899,
-                    "creator_name": "yushuangyu",
-                    "file_id": "pf_SdhEA5fbZJGnHzwrNJMMSB",
-                    "is_mine": true,
-                    "name": "sk-hynix-q2-2026-report.html",
-                    "person_id": 2476444212131,
-                    "public_url": "https://console.flashcat.cloud/share/artifact/art_VnfrWic8UbB9q3EfYR4Gmg",
-                    "session_id": "sess_VCbVPZrq9YoyBu8sNCmqUy",
-                    "session_title": "分析海力士财报并发布报告",
-                    "share_enabled": true,
-                    "share_file_id": "pf_SdhEA5fbZJGnHzwrNJMMSB",
-                    "shared_at": 1785747928665,
-                    "shared_by": 3790925372131,
-                    "size": 18996,
-                    "team_id": 2477033058131,
-                    "team_name": "研发团队",
-                    "title": "SK 海力士 2026 Q2 财报深度分析（终稿）",
-                    "updated_at": 1785829000000
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/ResponseEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/PublishedArtifactItem"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "artifact_id": "art_VnfrWic8UbB9q3EfYR4Gmg",
+                    "title": "支付接口延迟复盘报告（终稿）",
+                    "team_id": 4012,
+                    "team_name": "SRE 团队",
+                    "person_id": 2476001,
+                    "creator_name": "张伟",
+                    "is_mine": true,
+                    "can_edit": true,
+                    "session_id": "sess_VCbVPZrq9YoyBu8sNCmqUy",
+                    "session_title": "排查支付接口延迟突增",
+                    "file_id": "pf_SdhEA5fbZJGnHzwrNJMMSB",
+                    "name": "checkout-latency-postmortem.html",
+                    "size": 18996,
+                    "content_type": "text/html",
+                    "created_at": 1785293373899,
+                    "updated_at": 1785829000000,
+                    "pinned_at": 1785750000000,
+                    "share_enabled": true,
+                    "public_url": "https://console.flashcat.cloud/share/artifact/art_VnfrWic8UbB9q3EfYR4Gmg",
+                    "shared_by": 2476001,
+                    "shared_at": 1785747928665,
+                    "share_file_id": "pf_SdhEA5fbZJGnHzwrNJMMSB"
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -55653,81 +57543,84 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
           "500": {
             "$ref": "#/components/responses/ServerError"
           }
-        },
+        }
+      }
+    },
+    "/safari/artifact/sign": {
+      "post": {
+        "operationId": "artifact-read-sign",
+        "summary": "签发文件访问链接",
+        "description": "为文件签发短期有效的下载/预览链接。",
+        "tags": [
+          "AI SRE/产物"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "更新产物",
-        "tags": [
-          "AI SRE/产物"
-        ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 仅更新传入的字段 —— 不传 `title` 或 `team_id` 则对应字段保持不变。\n- `team_id: 0` 表示转为个人产物（仅创建者可管理）；传入大于 0 的 `team_id` 时，调用者（`app_key` 调用时为 key 所属成员）必须是该团队成员。\n- 返回更新后的完整产物。\n- 每次调用都会记录到账户审计日志。\n",
-          "href": "/zh/api-reference/ai-sre/artifacts/artifact-write-update",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 账户内已发布产物的文件都可签发；其他会话文件需要调用者能访问来源会话（或提供有效的 `share_token`）。文件不存在和无权访问都返回 `ResourceNotFound`。\n- 两个链接在 `expires_in` 秒（300 秒）后过期，需重新签发获取新链接。\n- 返回的是相对链接：拼接 `https://api.flashcat.cloud` 后通过 `GET /safari/artifact/stream` 访问，且须以签发时的同一成员身份认证。令牌与账户和该成员绑定，其他人无法使用。\n",
+          "href": "/zh/api-reference/ai-sre/artifacts/artifact-read-sign",
           "metadata": {
-            "sidebarTitle": "更新产物"
+            "sidebarTitle": "签发文件访问链接"
           }
-        }
-      }
-    },
-    "/safari/artifact/sign": {
-      "post": {
-        "description": "为文件签发短期有效的下载/预览链接。",
-        "operationId": "artifact-read-sign",
+        },
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {
-                "file_id": "pf_SdhEA5fbZJGnHzwrNJMMSB"
-              },
               "schema": {
                 "$ref": "#/components/schemas/ArtifactSignRequest"
+              },
+              "example": {
+                "file_id": "pf_SdhEA5fbZJGnHzwrNJMMSB"
               }
             }
-          },
-          "required": true
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "content_type": "text/html",
-                    "download_url": "/safari/artifact/stream?mode=download&t=cGZfU2RoRUE1ZmJaSkduSHp3ck5KTU1TQnxzZXNzX1ZDYlZQWnJxOVlveUJ1OHNOQ21xVXl8MjQ1MTAwMjc1MTEzMXwyNDc2NDQ0MjEyMTMxfDB8MHwxNzg4NTI5NjI2NTU0.hPQHab0MBNbnrHYwc6VwDJbGonIamfWUr0yeSmLHYAs",
-                    "expires_in": 300,
-                    "name": "sk-hynix-q2-2026-report.html",
-                    "preview_url": "/safari/artifact/stream?mode=preview&t=cGZfU2RoRUE1ZmJaSkduSHp3ck5KTU1TQnxzZXNzX1ZDYlZQWnJxOVlveUJ1OHNOQ21xVXl8MjQ1MTAwMjc1MTEzMXwyNDc2NDQ0MjEyMTMxfDB8MHwxNzg4NTI5NjI2NTU0.hPQHab0MBNbnrHYwc6VwDJbGonIamfWUr0yeSmLHYAs",
-                    "size": 18996
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/ResponseEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/SignedURLs"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "download_url": "/safari/artifact/stream?mode=download&t=eyJmaWxlX2lkIjoicGZfU2RoRUE1ZmJaSkduSHp3ck5KTU1TQiJ9.c2lnbmF0dXJl",
+                    "preview_url": "/safari/artifact/stream?mode=preview&t=eyJmaWxlX2lkIjoicGZfU2RoRUE1ZmJaSkduSHp3ck5KTU1TQiJ9.c2lnbmF0dXJl",
+                    "expires_in": 300,
+                    "name": "checkout-latency-postmortem.html",
+                    "size": 18996,
+                    "content_type": "text/html"
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -55735,74 +57628,98 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
           "500": {
             "$ref": "#/components/responses/ServerError"
           }
-        },
+        }
+      }
+    },
+    "/safari/artifact/stream": {
+      "get": {
+        "operationId": "artifact-read-stream",
+        "summary": "下载或预览文件",
+        "description": "使用签名令牌下载或预览文件内容。",
+        "tags": [
+          "AI SRE/产物"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "签发文件访问链接",
-        "tags": [
-          "AI SRE/产物"
-        ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 两个链接在 `expires_in` 秒（300 秒）后过期，需重新签发获取新链接。\n- 返回的是相对链接 —— 使用前拼接 `https://api.flashcat.cloud`，然后以 `GET /safari/artifact/stream` 访问。\n- 签名令牌与调用账号及 app_key 所属成员身份绑定 —— 链接泄露给其他账号或成员不可用。\n",
-          "href": "/zh/api-reference/ai-sre/artifacts/artifact-read-sign",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 使用 `/safari/artifact/sign` 返回的完整链接，并以签发时同一成员的 `app_key` 认证。令牌过期或不属于当前成员时返回 `ResourceNotFound`。\n- 存放在对象存储中的文件返回 `302`，跳转到 5 分钟内有效的预签名 URL，请跟随重定向。`download` 模式下的 CSV 文件，以及存放在 runner 上的文件，直接以 `200` 返回内容。\n- CSV 文件在 `download` 模式下会补上 UTF-8 BOM（原本没有时）并设置 `Content-Type: text/csv; charset=utf-8`，以便表格软件正确打开。\n- 存放在 runner 上的文件，若 runner 已不可用则返回 `410` 和纯文本提示；需重新运行任务生成文件。\n- 响应携带 `Cache-Control: private, no-store`。\n",
+          "href": "/zh/api-reference/ai-sre/artifacts/artifact-read-stream",
           "metadata": {
-            "sidebarTitle": "签发文件访问链接"
+            "sidebarTitle": "下载或预览文件"
           }
-        }
-      }
-    },
-    "/safari/artifact/stream": {
-      "get": {
-        "description": "使用签名令牌下载或预览文件内容。",
-        "operationId": "artifact-read-stream",
+        },
         "parameters": [
           {
-            "description": "由 `POST /safari/artifact/sign` 签发的令牌。与调用账号及成员绑定，有效期 5 分钟。",
-            "in": "query",
             "name": "t",
+            "in": "query",
             "required": true,
             "schema": {
               "type": "string"
-            }
+            },
+            "description": "由 `POST /safari/artifact/sign` 签发的令牌。与调用账号及成员绑定，有效期 5 分钟。"
           },
           {
-            "description": "`download`（默认）以附件形式返回文件；`preview` 以 inline 方式返回供浏览器预览。其他取值按 `download` 处理。",
-            "in": "query",
             "name": "mode",
+            "in": "query",
             "required": false,
             "schema": {
-              "default": "download",
+              "type": "string",
               "enum": [
                 "download",
                 "preview"
               ],
-              "type": "string"
-            }
+              "default": "download"
+            },
+            "description": "`download`（默认）以附件形式返回文件；`preview` 以 inline 方式返回供浏览器预览。其他取值按 `download` 处理。"
           }
         ],
         "responses": {
           "200": {
+            "description": "文件内容。存放在 runner 上的文件和 `download` 模式下的 CSV 文件直接返回内容。`Content-Disposition` 按 `mode` 为 `attachment` 或 `inline`。",
             "content": {
               "application/octet-stream": {
                 "schema": {
-                  "format": "binary",
-                  "type": "string"
+                  "type": "string",
+                  "format": "binary"
                 }
               }
-            },
-            "description": "文件内容流。当文件托管在自托管 runner 上时由服务端代理返回，Content-Disposition 随 `mode` 变化。"
+            }
           },
           "302": {
-            "description": "当文件存储在 S3 兼容存储中时，302 重定向到短期有效的预签名 URL。请跟随 `Location` 头，无响应体。"
+            "description": "重定向到 5 分钟内有效的对象存储预签名 URL（存放在对象存储中的文件）。URL 在 `Location` 响应头中。",
+            "headers": {
+              "Location": {
+                "description": "对象存储预签名 URL。",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            }
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "410": {
+            "description": "存放该文件的 runner 已不可用，响应体为纯文本提示。需重新运行任务生成文件。",
+            "content": {
+              "text/plain": {
+                "schema": {
+                  "type": "string"
+                }
+              }
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -55816,75 +57733,76 @@
           "500": {
             "$ref": "#/components/responses/ServerError"
           }
-        },
+        }
+      }
+    },
+    "/safari/automation/rule/create": {
+      "post": {
+        "operationId": "automation-rule-write-create",
+        "summary": "创建自动化规则",
+        "description": "创建自动化规则，可配置定时、HTTP POST、On-call 故障和作战室触发器。",
+        "tags": [
+          "AI SRE/自动化"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "下载或预览文件",
-        "tags": [
-          "AI SRE/产物"
-        ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **100 次/分钟**；**10 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 成功响应有两种形式：302 重定向到短期有效的对象存储预签名 URL（存储在 S3 兼容存储中的文件），或 200 二进制流（托管在自托管 runner 上的文件）。请跟随重定向。\n- 响应携带 `Cache-Control: private, no-store` —— 网关不会缓存。\n",
-          "href": "/zh/api-reference/ai-sre/artifacts/artifact-read-stream",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **Automation 管理**（`ai-sre`） |\n\n## 使用说明\n\n- 省略 `team_id` 或传 `0` 创建个人规则。创建团队规则要求调用者是该团队成员，账户所有者和管理员也不例外。\n- 规则的作用域在创建时确定：更新自动化规则时，`team_id` 与已存值不同会被拒绝。如需在其他作用域运行同一任务，请新建规则。\n- 即使只使用其他触发器，`cron_expr` 也必填；请传一个合法表达式并将 `schedule_trigger_enabled` 设为 `false`。\n- `cron_expr` 按 `timezone` 计算；未提供时依次使用调用者的成员时区、账户时区，最后为 `Asia/Shanghai`。\n- `http_post_trigger_enabled=true` 会创建并启用 HTTP POST 触发器。`http_post_token` 只在本次响应中返回，请妥善保存。触发方式：向 `http_post_trigger_url` 发送 `POST`，并带请求头 `Authorization: Bearer <http_post_token>`；可选的 JSON 请求体 `{\"text\": \"...\"}` 不超过 256 KB。\n- 只要传了任一 `oncall_incident_*` 字段，`oncall_incident_channel_ids` 与 `oncall_incident_severities` 都必须非空。命中条件的故障会以 `trigger_kind=oncall_incident` 发起运行。\n- 当 `war_room_trigger_enabled=true` 或传了 `war_room_channel_ids` 时，`war_room_channel_ids` 与 `war_room_severities` 都必须非空。命中条件的故障创建作战室（IM 群聊）后，Agent 会直接在该群聊中运行，运行记录的 `trigger_kind` 为 `war_room_created`。\n- 通过 API 创建的规则在 Web 控制台中运行（`execution_place=web_console`）；`run_in=current-chat` 仅在与 AI SRE Agent 的实时 IM 会话中可用，通过 API 传入会被拒绝。\n- 响应为新建的规则；对创建者而言 `can_edit` 恒为 `true`。\n- 每次调用都会记录到账户审计日志。\n",
+          "href": "/zh/api-reference/ai-sre/automations/automation-rule-write-create",
           "metadata": {
-            "sidebarTitle": "下载或预览文件"
+            "sidebarTitle": "创建自动化规则"
           }
-        }
-      }
-    },
-    "/safari/automation/rule/create": {
-      "post": {
-        "description": "创建自动化规则，支持 schedule、HTTP POST 和 On-call 故障触发器。",
-        "operationId": "automation-rule-write-create",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "cron_expr": "0 9 * * 1",
-                "enabled": true,
-                "http_post_trigger_enabled": true,
-                "name": "Weekly on-call review",
-                "oncall_incident_channel_ids": [
-                  456
-                ],
-                "oncall_incident_severities": [
-                  "Critical",
-                  "Warning"
-                ],
-                "oncall_incident_trigger_enabled": true,
-                "prompt": "Summarize last week's alert noise and escalation load.",
-                "schedule_trigger_enabled": true,
-                "team_id": 123,
-                "timezone": "Asia/Shanghai"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/AutomationRuleCreateRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ResponseEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/AutomationRuleItem"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
+                    "rule_id": "arule_7NnLzY2Qp8xS4kUaV3mR6b",
                     "account_id": 10023,
-                    "can_edit": true,
-                    "created_at": 1780367971228,
-                    "cron_expr": "0 9 * * 1",
+                    "team_id": 123,
+                    "owner_id": 80011,
+                    "name": "Weekly on-call review",
                     "enabled": true,
-                    "environment_id": "",
+                    "run_scope": "team",
+                    "cron_expr": "0 9 * * 1",
+                    "timezone": "Asia/Shanghai",
+                    "prompt": "Summarize last week's alert noise and escalation load.",
                     "environment_kind": "",
-                    "http_post_token": "sat_yQ9p8V7n6M5k4J3h2G1f0E9d8C7b6A5z4Y3x2W1v0U",
-                    "http_post_trigger_enabled": true,
+                    "environment_id": "",
+                    "schedule_trigger_id": "atrig_6aKp3wT9mQ2xVc8bR1nY7z",
+                    "schedule_trigger_enabled": true,
                     "http_post_trigger_id": "atrig_2bLq4xT8mP1sWd9cN3rF6y",
                     "http_post_trigger_url": "/safari/automation/triggers/atrig_2bLq4xT8mP1sWd9cN3rF6y/fire",
-                    "name": "Weekly on-call review",
+                    "http_post_trigger_enabled": true,
+                    "can_edit": true,
+                    "created_at": 1780367971228,
+                    "updated_at": 1780367971228,
+                    "http_post_token": "sat_yQ9p8V7n6M5k4J3h2G1f0E9d8C7b6A5z4Y3x2W1v0U",
+                    "schedule_next_fire_at_ms": 1780630800000,
+                    "oncall_incident_trigger_id": "atrig_9cVb2mN7qKs4dEa8T1rY5p",
+                    "oncall_incident_trigger_enabled": true,
                     "oncall_incident_channel_ids": [
                       456
                     ],
@@ -55892,39 +57810,19 @@
                       "Critical",
                       "Warning"
                     ],
-                    "oncall_incident_trigger_enabled": true,
-                    "oncall_incident_trigger_id": "atrig_9cVb2mN7qKs4dEa8T1rY5p",
-                    "owner_id": 80011,
-                    "prompt": "Summarize last week's alert noise and escalation load.",
-                    "rule_id": "arule_7NnLzY2Qp8xS4kUaV3mR6b",
-                    "run_scope": "team",
-                    "schedule_next_fire_at_ms": 1780630800000,
-                    "schedule_trigger_enabled": true,
-                    "schedule_trigger_id": "atrig_6aKp3wT9mQ2xVc8bR1nY7z",
-                    "team_id": 123,
-                    "timezone": "Asia/Shanghai",
-                    "updated_at": 1780367971228
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/ResponseEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/AutomationRuleItem"
-                        }
-                      },
-                      "type": "object"
+                    "oncall_incident_merge_similar": true,
+                    "war_room_trigger_enabled": false,
+                    "execution_place": "web_console",
+                    "execution_location": {
+                      "place": "web_console",
+                      "run_scope": "team",
+                      "team_id": 123,
+                      "description": "Web console"
                     }
-                  ]
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -55942,68 +57840,82 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/AutomationRuleCreateRequest"
+              },
+              "example": {
+                "name": "Weekly on-call review",
+                "team_id": 123,
+                "enabled": true,
+                "cron_expr": "0 9 * * 1",
+                "timezone": "Asia/Shanghai",
+                "schedule_trigger_enabled": true,
+                "prompt": "Summarize last week's alert noise and escalation load.",
+                "http_post_trigger_enabled": true,
+                "oncall_incident_trigger_enabled": true,
+                "oncall_incident_channel_ids": [
+                  456
+                ],
+                "oncall_incident_severities": [
+                  "Critical",
+                  "Warning"
+                ]
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/automation/rule/delete": {
+      "post": {
+        "operationId": "automation-rule-write-delete",
+        "summary": "删除自动化规则",
+        "description": "删除一条自动化规则，并同时删除其全部触发器及订阅。",
+        "tags": [
+          "AI SRE/自动化"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "创建自动化规则",
-        "tags": [
-          "AI SRE/自动化"
-        ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 有效 `app_key`；管理操作要求调用者可管理目标规则 |\n\n## 使用说明\n\n- 可以创建个人规则，也可以创建当前账户下任意团队的规则；`team_id` 之后可通过 update 改派（团队规则转个人仅 owner 可操作；转入团队要求调用者属于该团队）。\n- `cron_expr` 按 `timezone`（如提供）计算；未提供时依次回退到调用者的成员时区、账户时区，最后是服务端默认时区（Asia/Shanghai）。\n- `http_post_trigger_enabled=true` 会创建并启用 HTTP POST 触发器；响应中的 `http_post_token` 是仅在创建时返回的一次性值，请立即保存。\n- `oncall_incident_trigger_enabled=true` 时，`oncall_incident_channel_ids` 和 `oncall_incident_severities` 至少各需一项；匹配的故障会以 `trigger_kind=oncall_incident` 运行。\n- 每次调用都会记录到账户审计日志。\n",
-          "href": "/zh/api-reference/ai-sre/automations/automation-rule-write-create",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **Automation 管理**（`ai-sre`） |\n\n## 使用说明\n\n- 删除规则会同时移除其定时、HTTP POST、On-call 故障和作战室触发器；HTTP POST 触发器的 token 随之失效。\n- 管理权限：个人规则（`team_id=0`）仅创建者可管理；团队规则仅该团队成员可管理。账户所有者和管理员没有例外，需加入该团队。其他调用者会收到 `403`。\n- 同一规则正在执行另一次更新、删除或手动运行时，本调用返回 HTTP `423`，`code` 为 `\"RequestLocked\"`，请稍后重试。\n- 每次调用都会记录到账户审计日志。\n",
+          "href": "/zh/api-reference/ai-sre/automations/automation-rule-write-delete",
           "metadata": {
-            "sidebarTitle": "创建自动化规则"
+            "sidebarTitle": "删除自动化规则"
           }
-        }
-      }
-    },
-    "/safari/automation/rule/delete": {
-      "post": {
-        "description": "删除一条自动化规则。",
-        "operationId": "automation-rule-write-delete",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "rule_id": "arule_7NnLzY2Qp8xS4kUaV3mR6b"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/AutomationRuleIDRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": null,
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/ResponseEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "description": "成功时固定为 null。",
-                          "type": "null"
+                          "type": "null",
+                          "description": "成功时不返回该字段，响应体只有 `request_id`。"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -56021,58 +57933,87 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/AutomationRuleIDRequest"
+              },
+              "example": {
+                "rule_id": "arule_7NnLzY2Qp8xS4kUaV3mR6b"
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/automation/rule/get": {
+      "post": {
+        "operationId": "automation-rule-read-get",
+        "summary": "查看自动化规则",
+        "description": "按 ID 获取一条自动化规则，包括触发器配置和运行位置。",
+        "tags": [
+          "AI SRE/自动化"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "删除自动化规则",
-        "tags": [
-          "AI SRE/自动化"
-        ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 有效 `app_key`；管理操作要求调用者可管理目标规则 |\n\n## 使用说明\n\n- 删除规则会同时移除其 schedule、HTTP POST 和 On-call 故障触发器；被删除的 HTTP POST 触发器 token 会立即失效。\n- 每次调用都会记录到账户审计日志。\n",
-          "href": "/zh/api-reference/ai-sre/automations/automation-rule-write-delete",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **Automation 查看**（`ai-sre`） |\n\n## 使用说明\n\n- 管理权限：个人规则（`team_id=0`）仅创建者可管理；团队规则仅该团队成员可管理。账户所有者和管理员没有例外，需加入该团队。没有管理权限的调用者会收到 `403`。\n- 本接口不返回 `last_run`；运行状态请用列出自动化规则或列出自动化运行记录查询。\n- 本接口从不返回 `http_post_token`；它只在签发 token 时（创建、首次启用 HTTP POST 触发器或轮换）返回。\n",
+          "href": "/zh/api-reference/ai-sre/automations/automation-rule-read-get",
           "metadata": {
-            "sidebarTitle": "删除自动化规则"
+            "sidebarTitle": "查看自动化规则"
           }
-        }
-      }
-    },
-    "/safari/automation/rule/get": {
-      "post": {
-        "description": "按 ID 查看一条自动化规则。",
-        "operationId": "automation-rule-read-get",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "rule_id": "arule_7NnLzY2Qp8xS4kUaV3mR6b"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/AutomationRuleIDRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ResponseEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/AutomationRuleItem"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
+                    "rule_id": "arule_7NnLzY2Qp8xS4kUaV3mR6b",
                     "account_id": 10023,
-                    "can_edit": true,
-                    "created_at": 1780367971228,
-                    "cron_expr": "0 9 * * 1",
+                    "team_id": 123,
+                    "owner_id": 80011,
+                    "name": "Weekly on-call review",
                     "enabled": true,
-                    "environment_id": "",
+                    "run_scope": "team",
+                    "cron_expr": "0 9 * * 1",
+                    "timezone": "Asia/Shanghai",
+                    "prompt": "Summarize last week's alert noise and escalation load.",
                     "environment_kind": "",
-                    "http_post_trigger_enabled": true,
+                    "environment_id": "",
+                    "schedule_trigger_id": "atrig_6aKp3wT9mQ2xVc8bR1nY7z",
+                    "schedule_trigger_enabled": true,
                     "http_post_trigger_id": "atrig_2bLq4xT8mP1sWd9cN3rF6y",
                     "http_post_trigger_url": "/safari/automation/triggers/atrig_2bLq4xT8mP1sWd9cN3rF6y/fire",
-                    "name": "Weekly on-call review",
+                    "http_post_trigger_enabled": true,
+                    "can_edit": true,
+                    "created_at": 1780367971228,
+                    "updated_at": 1780367971228,
+                    "schedule_next_fire_at_ms": 1780630800000,
+                    "oncall_incident_trigger_id": "atrig_9cVb2mN7qKs4dEa8T1rY5p",
+                    "oncall_incident_trigger_enabled": true,
                     "oncall_incident_channel_ids": [
                       456
                     ],
@@ -56080,39 +58021,19 @@
                       "Critical",
                       "Warning"
                     ],
-                    "oncall_incident_trigger_enabled": true,
-                    "oncall_incident_trigger_id": "atrig_9cVb2mN7qKs4dEa8T1rY5p",
-                    "owner_id": 80011,
-                    "prompt": "Summarize last week's alert noise and escalation load.",
-                    "rule_id": "arule_7NnLzY2Qp8xS4kUaV3mR6b",
-                    "run_scope": "team",
-                    "schedule_next_fire_at_ms": 1780630800000,
-                    "schedule_trigger_enabled": true,
-                    "schedule_trigger_id": "atrig_6aKp3wT9mQ2xVc8bR1nY7z",
-                    "team_id": 123,
-                    "timezone": "Asia/Shanghai",
-                    "updated_at": 1780367971228
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/ResponseEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/AutomationRuleItem"
-                        }
-                      },
-                      "type": "object"
+                    "oncall_incident_merge_similar": true,
+                    "war_room_trigger_enabled": false,
+                    "execution_place": "web_console",
+                    "execution_location": {
+                      "place": "web_console",
+                      "run_scope": "team",
+                      "team_id": 123,
+                      "description": "Web console"
                     }
-                  ]
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -56130,61 +58051,90 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/AutomationRuleIDRequest"
+              },
+              "example": {
+                "rule_id": "arule_7NnLzY2Qp8xS4kUaV3mR6b"
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/automation/rule/list": {
+      "post": {
+        "operationId": "automation-rule-read-list",
+        "summary": "列出自动化规则",
+        "description": "列出调用者可见的自动化规则，按更新时间倒序，支持分页和过滤。",
+        "tags": [
+          "AI SRE/自动化"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "查看自动化规则",
-        "tags": [
-          "AI SRE/自动化"
-        ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 有效 `app_key`；调用者必须可管理目标规则 |\n\n## 使用说明\n\n- 管理权限指：个人规则仅限创建者；团队规则限账户管理员或规则所属团队成员。\n",
-          "href": "/zh/api-reference/ai-sre/automations/automation-rule-read-get",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **Automation 查看**（`ai-sre`） |\n\n## 使用说明\n\n- 可见范围：调用者自己的个人规则，加上调用者所属团队的团队规则。账户所有者和管理员同样只能看到自己所属团队的规则，看不到他人的个人规则。\n- `scope=personal` 只返回调用者的个人规则；`scope=team` 只返回调用者所属团队的规则。`team_ids` 只会进一步收窄结果，不会扩大访问范围。\n- 结果按 `updated_at` 倒序排列。规则运行过时，列表项会带上 `last_run`（最近一次运行）。\n- 列表项的 `can_edit` 表示调用者能否管理（获取、更新、删除、运行）该规则。\n",
+          "href": "/zh/api-reference/ai-sre/automations/automation-rule-read-list",
           "metadata": {
-            "sidebarTitle": "查看自动化规则"
+            "sidebarTitle": "列出自动化规则"
           }
-        }
-      }
-    },
-    "/safari/automation/rule/list": {
-      "post": {
-        "description": "列出当前调用者可见的自动化规则。",
-        "operationId": "automation-rule-read-list",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "limit": 20,
-                "scope": "all"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/AutomationRuleListRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ResponseEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/AutomationRuleListResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
+                    "total": 1,
                     "rules": [
                       {
+                        "rule_id": "arule_7NnLzY2Qp8xS4kUaV3mR6b",
                         "account_id": 10023,
-                        "can_edit": true,
-                        "created_at": 1780367971228,
-                        "cron_expr": "0 9 * * 1",
+                        "team_id": 123,
+                        "owner_id": 80011,
+                        "name": "Weekly on-call review",
                         "enabled": true,
-                        "environment_id": "",
+                        "run_scope": "team",
+                        "cron_expr": "0 9 * * 1",
+                        "timezone": "Asia/Shanghai",
+                        "prompt": "Summarize last week's alert noise and escalation load.",
                         "environment_kind": "",
-                        "http_post_trigger_enabled": true,
+                        "environment_id": "",
+                        "schedule_trigger_id": "atrig_6aKp3wT9mQ2xVc8bR1nY7z",
+                        "schedule_trigger_enabled": true,
                         "http_post_trigger_id": "atrig_2bLq4xT8mP1sWd9cN3rF6y",
                         "http_post_trigger_url": "/safari/automation/triggers/atrig_2bLq4xT8mP1sWd9cN3rF6y/fire",
-                        "name": "Weekly on-call review",
+                        "http_post_trigger_enabled": true,
+                        "can_edit": true,
+                        "created_at": 1780367971228,
+                        "updated_at": 1780367971228,
+                        "schedule_next_fire_at_ms": 1780630800000,
+                        "oncall_incident_trigger_id": "atrig_9cVb2mN7qKs4dEa8T1rY5p",
+                        "oncall_incident_trigger_enabled": true,
                         "oncall_incident_channel_ids": [
                           456
                         ],
@@ -56192,42 +58142,26 @@
                           "Critical",
                           "Warning"
                         ],
-                        "oncall_incident_trigger_enabled": true,
-                        "oncall_incident_trigger_id": "atrig_9cVb2mN7qKs4dEa8T1rY5p",
-                        "owner_id": 80011,
-                        "prompt": "Summarize last week's alert noise and escalation load.",
-                        "rule_id": "arule_7NnLzY2Qp8xS4kUaV3mR6b",
-                        "run_scope": "team",
-                        "schedule_next_fire_at_ms": 1780630800000,
-                        "schedule_trigger_enabled": true,
-                        "schedule_trigger_id": "atrig_6aKp3wT9mQ2xVc8bR1nY7z",
-                        "team_id": 123,
-                        "timezone": "Asia/Shanghai",
-                        "updated_at": 1780367971228
-                      }
-                    ],
-                    "total": 1
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/ResponseEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/AutomationRuleListResponse"
+                        "oncall_incident_merge_similar": true,
+                        "war_room_trigger_enabled": false,
+                        "execution_place": "web_console",
+                        "execution_location": {
+                          "place": "web_console",
+                          "run_scope": "team",
+                          "team_id": 123,
+                          "description": "Web console"
+                        },
+                        "last_run": {
+                          "run_id": "trun_5oDvqiG64uur6sBNsTc4u",
+                          "status": "succeeded",
+                          "started_at": 1780630800000
                         }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                      }
+                    ]
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -56245,49 +58179,69 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/AutomationRuleListRequest"
+              },
+              "example": {
+                "scope": "all",
+                "limit": 20
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/automation/rule/run": {
+      "post": {
+        "operationId": "automation-rule-write-run",
+        "summary": "运行自动化规则",
+        "description": "立即运行一次自动化规则，不受其触发器和启用状态限制。",
+        "tags": [
+          "AI SRE/自动化"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "列出自动化规则",
-        "tags": [
-          "AI SRE/自动化"
-        ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 有效 `app_key`；结果按调用者可见范围过滤 |\n\n## 使用说明\n\n- `all` 返回调用者自己的个人规则，以及调用者可访问团队的团队规则。\n- 账户管理员在列表中可见所有团队规则，但不可见他人的个人规则。\n- `team_ids` 只会收窄可见集合，不会扩大访问范围。\n",
-          "href": "/zh/api-reference/ai-sre/automations/automation-rule-read-list",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **100 次/分钟**；**5 次/秒** |\n| 权限要求 | **Automation 管理**（`ai-sre`） |\n\n## 使用说明\n\n- 手动运行不要求规则处于启用状态。规则配置无效（例如使用了规则作用域不允许的 BYOC 运行器），或唯一启用的触发器是作战室触发器（这类规则没有 Web 控制台运行）时，会在创建运行前返回 `400`。\n- 创建者已离开账户的个人规则会被自动停用，本调用返回 `400`。\n- 同一规则每分钟最多手动运行一次；窗口内的第二次调用返回 `429`，`code` 为 `\"RequestTooFrequently\"`。\n- 管理权限：个人规则（`team_id=0`）仅创建者可管理；团队规则仅该团队成员可管理。账户所有者和管理员没有例外，需加入该团队。\n- 同一规则正在执行另一次更新、删除或手动运行时，本调用返回 HTTP `423`，`code` 为 `\"RequestLocked\"`，请稍后重试。\n- 调用在 Agent 会话启动后即返回，不等待运行结束。可用列出自动化运行记录（`trigger_kind=manual`）查询完成情况。\n- 对在 IM 群聊中运行的规则（`execution_place=im`），响应不包含 `run.session_id`。\n- 每次调用都会记录到账户审计日志。\n",
+          "href": "/zh/api-reference/ai-sre/automations/automation-rule-write-run",
           "metadata": {
-            "sidebarTitle": "列出自动化规则"
+            "sidebarTitle": "运行自动化规则"
           }
-        }
-      }
-    },
-    "/safari/automation/rule/run": {
-      "post": {
-        "description": "立即手动运行一次自动化规则，不受其计划触发时间限制。",
-        "operationId": "automation-rule-write-run",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "rule_id": "arule_7NnLzY2Qp8xS4kUaV3mR6b"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/AutomationRuleIDRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ResponseEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/ManualRunRuleResult"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
+                    "rule_id": "arule_7NnLzY2Qp8xS4kUaV3mR6b",
+                    "trigger_kind": "manual",
                     "preflight": {
-                      "app_name": "ai-sre",
+                      "ok": true,
                       "checks": [
                         "rule_loaded",
                         "actor_authorized",
@@ -56295,38 +58249,19 @@
                         "runtime_scope_resolved",
                         "rule_config_valid"
                       ],
-                      "ok": true,
-                      "owner_id": 80011,
                       "scope": "team",
-                      "team_id": 123
+                      "owner_id": 80011,
+                      "team_id": 123,
+                      "app_name": "ai-sre"
                     },
-                    "rule_id": "arule_7NnLzY2Qp8xS4kUaV3mR6b",
                     "run": {
                       "run_id": "trun_5oDvqiG64uur6sBNsTc4u",
                       "session_id": "sess_f8oDvqiG64uur6sBNsTc4u"
-                    },
-                    "trigger_kind": "manual"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/ResponseEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/ManualRunRuleResult"
-                        }
-                      },
-                      "type": "object"
                     }
-                  ]
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -56344,70 +58279,88 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/AutomationRuleIDRequest"
+              },
+              "example": {
+                "rule_id": "arule_7NnLzY2Qp8xS4kUaV3mR6b"
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/automation/rule/update": {
+      "post": {
+        "operationId": "automation-rule-write-update",
+        "summary": "更新自动化规则",
+        "description": "更新自动化规则的字段和触发器配置；省略的字段保持不变。",
+        "tags": [
+          "AI SRE/自动化"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "运行自动化规则",
-        "tags": [
-          "AI SRE/自动化"
-        ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **100 次/分钟**；**5 次/秒** |\n| 权限要求 | 有效 `app_key`；调用者必须可管理目标规则 |\n\n## 使用说明\n\n- 同一规则的手动运行限速为每分钟最多一次；在此窗口内的第二次调用会返回 `429`，`code` 为 `\"RequestTooFrequently\"`。\n- 只有已启用的规则才能手动运行；已禁用或配置无效的规则会在创建运行前以 `400` 错误未通过预检。\n- 调用在底层 Agent 会话启动后即返回，而非等待运行结束；运行会继续异步执行——可使用列出自动化运行历史查询完成状态。\n- 以此方式发起的运行，`trigger_kind` 固定为 `manual`，在运行历史中与 `schedule`、`http_post`、`oncall_incident` 区分开来。\n- 每次调用都会记录到账户审计日志。\n",
-          "href": "/zh/api-reference/ai-sre/automations/automation-rule-write-run",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **Automation 管理**（`ai-sre`） |\n\n## 使用说明\n\n- 省略或传 `null` 的字段保持不变。`*_channel_ids` / `*_severities` 传空数组时也保留已存的列表。\n- `team_id` 不可修改：传入与已存值不同的值会返回 `400`；重复传入当前值是允许的。\n- `cron_expr` 与 `timezone` 可以单独传，另一个保持已存值。传 `timezone: \"\"` 会存为 `UTC`。\n- 只传 `environment_kind` 不传 `environment_id` 时，会清空已存的 `environment_id`。\n- 规则没有 HTTP POST 触发器时，`http_post_trigger_enabled=true` 会创建一个并返回其 token。`rotate_http_post_trigger_token=true` 会签发新 token（旧 token 立即失效），要求该触发器处于启用状态。新 token 只在本次响应中返回。\n- 通过更新新建 On-call 故障或作战室触发器时，必须同时提供对应的协作空间 ID 和严重程度。\n- 管理权限：个人规则（`team_id=0`）仅创建者可管理；团队规则仅该团队成员可管理。账户所有者和管理员没有例外，需加入该团队。\n- 同一规则正在执行另一次更新、删除或手动运行时，本调用返回 HTTP `423`，`code` 为 `\"RequestLocked\"`，请稍后重试。\n- 每次调用都会记录到账户审计日志。\n",
+          "href": "/zh/api-reference/ai-sre/automations/automation-rule-write-update",
           "metadata": {
-            "sidebarTitle": "运行自动化规则"
+            "sidebarTitle": "更新自动化规则"
           }
-        }
-      }
-    },
-    "/safari/automation/rule/update": {
-      "post": {
-        "description": "更新自动化规则的可变字段，包括 HTTP POST 与 On-call 故障触发器配置。",
-        "operationId": "automation-rule-write-update",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "cron_expr": "15 9 * * 1",
-                "enabled": true,
-                "oncall_incident_channel_ids": [
-                  456
-                ],
-                "oncall_incident_severities": [
-                  "Critical",
-                  "Warning"
-                ],
-                "oncall_incident_trigger_enabled": true,
-                "rotate_http_post_trigger_token": true,
-                "rule_id": "arule_7NnLzY2Qp8xS4kUaV3mR6b"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/AutomationRuleUpdateRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ResponseEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/AutomationRuleItem"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
+                    "rule_id": "arule_7NnLzY2Qp8xS4kUaV3mR6b",
                     "account_id": 10023,
-                    "can_edit": true,
-                    "created_at": 1780367971228,
-                    "cron_expr": "0 9 * * 1",
+                    "team_id": 123,
+                    "owner_id": 80011,
+                    "name": "Weekly on-call review",
                     "enabled": true,
-                    "environment_id": "",
+                    "run_scope": "team",
+                    "cron_expr": "0 9 * * 1",
+                    "timezone": "Asia/Shanghai",
+                    "prompt": "Summarize last week's alert noise and escalation load.",
                     "environment_kind": "",
-                    "http_post_token": "sat_yQ9p8V7n6M5k4J3h2G1f0E9d8C7b6A5z4Y3x2W1v0U",
-                    "http_post_trigger_enabled": true,
+                    "environment_id": "",
+                    "schedule_trigger_id": "atrig_6aKp3wT9mQ2xVc8bR1nY7z",
+                    "schedule_trigger_enabled": true,
                     "http_post_trigger_id": "atrig_2bLq4xT8mP1sWd9cN3rF6y",
                     "http_post_trigger_url": "/safari/automation/triggers/atrig_2bLq4xT8mP1sWd9cN3rF6y/fire",
-                    "name": "Weekly on-call review",
+                    "http_post_trigger_enabled": true,
+                    "can_edit": true,
+                    "created_at": 1780367971228,
+                    "updated_at": 1780367971228,
+                    "http_post_token": "sat_yQ9p8V7n6M5k4J3h2G1f0E9d8C7b6A5z4Y3x2W1v0U",
+                    "schedule_next_fire_at_ms": 1780630800000,
+                    "oncall_incident_trigger_id": "atrig_9cVb2mN7qKs4dEa8T1rY5p",
+                    "oncall_incident_trigger_enabled": true,
                     "oncall_incident_channel_ids": [
                       456
                     ],
@@ -56415,39 +58368,19 @@
                       "Critical",
                       "Warning"
                     ],
-                    "oncall_incident_trigger_enabled": true,
-                    "oncall_incident_trigger_id": "atrig_9cVb2mN7qKs4dEa8T1rY5p",
-                    "owner_id": 80011,
-                    "prompt": "Summarize last week's alert noise and escalation load.",
-                    "rule_id": "arule_7NnLzY2Qp8xS4kUaV3mR6b",
-                    "run_scope": "team",
-                    "schedule_next_fire_at_ms": 1780630800000,
-                    "schedule_trigger_enabled": true,
-                    "schedule_trigger_id": "atrig_6aKp3wT9mQ2xVc8bR1nY7z",
-                    "team_id": 123,
-                    "timezone": "Asia/Shanghai",
-                    "updated_at": 1780367971228
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/ResponseEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/AutomationRuleItem"
-                        }
-                      },
-                      "type": "object"
+                    "oncall_incident_merge_similar": true,
+                    "war_room_trigger_enabled": false,
+                    "execution_place": "web_console",
+                    "execution_location": {
+                      "place": "web_console",
+                      "run_scope": "team",
+                      "team_id": 123,
+                      "description": "Web console"
                     }
-                  ]
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -56465,96 +58398,106 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/AutomationRuleUpdateRequest"
+              },
+              "example": {
+                "rule_id": "arule_7NnLzY2Qp8xS4kUaV3mR6b",
+                "enabled": true,
+                "cron_expr": "15 9 * * 1",
+                "rotate_http_post_trigger_token": true,
+                "oncall_incident_trigger_enabled": true,
+                "oncall_incident_severities": [
+                  "Critical",
+                  "Warning"
+                ],
+                "oncall_incident_channel_ids": [
+                  456
+                ]
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/automation/run/list": {
+      "post": {
+        "operationId": "automation-run-read-list",
+        "summary": "列出自动化运行历史",
+        "description": "列出一条自动化规则的运行记录，按开始时间倒序，支持按状态、触发来源和时间过滤。",
+        "tags": [
+          "AI SRE/自动化"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "更新自动化规则",
-        "tags": [
-          "AI SRE/自动化"
-        ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 有效 `app_key`；管理操作要求调用者可管理目标规则 |\n\n## 使用说明\n\n- 省略或传 `null` 的字段保持不变。`team_id` 用于改派规则作用域：`0` 将团队规则转为个人规则（仅 owner 可操作），`>0` 转入调用者所属的团队。\n- `cron_expr` 与 `timezone` 可以分别更新——只传其中一个时，另一个保持当前已存储的值。\n- `rotate_http_post_trigger_token=true` 会签发新的 webhook token，且仅在本次响应中返回。\n- 如需由 On-call 故障触发，传入 `oncall_incident_trigger_enabled`、`oncall_incident_channel_ids` 与 `oncall_incident_severities`；匹配事件会以 `trigger_kind=oncall_incident` 运行。\n- 每次调用都会记录到账户审计日志。\n",
-          "href": "/zh/api-reference/ai-sre/automations/automation-rule-write-update",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **Automation 查看**（`ai-sre`） |\n\n## 使用说明\n\n- 管理权限：个人规则（`team_id=0`）仅创建者可管理；团队规则仅该团队成员可管理。账户所有者和管理员没有例外，需加入该团队。其他调用者会收到 `403`。\n- 运行记录保留 180 天；更早的 `started_after_ms` 会被提升到该下限。\n- 结果按 `started_at` 倒序排列。\n- 在 IM 群聊中执行的运行（`execution_place=im`）不返回 `session_id`、`joined_session_id` 和 `result_json`。\n",
+          "href": "/zh/api-reference/ai-sre/automations/automation-run-read-list",
           "metadata": {
-            "sidebarTitle": "更新自动化规则"
+            "sidebarTitle": "列出自动化运行历史"
           }
-        }
-      }
-    },
-    "/safari/automation/run/list": {
-      "post": {
-        "description": "列出调用者可管理规则的运行历史。",
-        "operationId": "automation-run-read-list",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "limit": 20,
-                "rule_id": "arule_7NnLzY2Qp8xS4kUaV3mR6b",
-                "trigger_kind": "schedule"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/AutomationRunListRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ResponseEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/AutomationRunListResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
+                    "total": 1,
                     "runs": [
                       {
+                        "run_id": "trun_5oDvqiG64uur6sBNsTc4u",
+                        "session_id": "sess_f8oDvqiG64uur6sBNsTc4u",
+                        "session_name": "Weekly on-call review",
+                        "kind": "automation_rule",
                         "account_id": 10023,
+                        "rule_id": "arule_7NnLzY2Qp8xS4kUaV3mR6b",
+                        "trigger_kind": "schedule",
+                        "execution_place": "web_console",
+                        "occurrence_key": "atrig_6aKp3wT9mQ2xVc8bR1nY7z:1780630800000",
+                        "status": "succeeded",
                         "attempts": 1,
+                        "started_at": 1780630800000,
                         "completed_at": 1780630923456,
-                        "created_at": 1780630800000,
                         "duration_ms": 123456,
                         "error_code": "",
                         "error_message": "",
-                        "kind": "automation_rule",
-                        "occurrence_key": "atrig_6aKp3wT9mQ2xVc8bR1nY7z:1780630800000",
+                        "stats_json": {},
                         "result_json": {
                           "session_id": "sess_f8oDvqiG64uur6sBNsTc4u"
                         },
-                        "rule_id": "arule_7NnLzY2Qp8xS4kUaV3mR6b",
-                        "run_id": "trun_5oDvqiG64uur6sBNsTc4u",
-                        "session_id": "sess_f8oDvqiG64uur6sBNsTc4u",
-                        "session_name": "Weekly on-call review",
-                        "started_at": 1780630800000,
-                        "stats_json": {},
-                        "status": "succeeded",
-                        "trigger_kind": "schedule",
+                        "created_at": 1780630800000,
                         "updated_at": 1780630923456
                       }
-                    ],
-                    "total": 1
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/ResponseEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/AutomationRunListResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                    ]
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -56572,77 +58515,85 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "security": [
-          {
-            "AppKeyAuth": []
-          }
-        ],
-        "summary": "列出自动化运行历史",
-        "tags": [
-          "AI SRE/自动化"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 有效 `app_key`；调用者必须可管理目标规则 |\n\n## 使用说明\n\n- 仅当调用者可管理规则时才可查看运行历史：个人规则仅限创建者；团队规则限账户管理员或规则所属团队成员。\n",
-          "href": "/zh/api-reference/ai-sre/automations/automation-run-read-list",
-          "metadata": {
-            "sidebarTitle": "列出自动化运行历史"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/AutomationRunListRequest"
+              },
+              "example": {
+                "rule_id": "arule_7NnLzY2Qp8xS4kUaV3mR6b",
+                "limit": 20,
+                "trigger_kind": "schedule"
+              }
+            }
           }
         }
       }
     },
     "/safari/automation/template/list": {
       "post": {
-        "description": "按语言列出自动化预设模板。",
         "operationId": "automation-template-read-list",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "locale": "en-US"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/AutomationTemplateListRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "列出自动化模板",
+        "description": "列出用于预填创建规则表单的内置自动化模板，支持中文或英文。",
+        "tags": [
+          "AI SRE/自动化"
+        ],
+        "security": [
+          {
+            "AppKeyAuth": []
+          }
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **Automation 查看**（`ai-sre`） |\n\n## 使用说明\n\n- 模板由平台内置，所有账户相同。\n- 语言规则：`locale` 含 `zh` 时返回中文模板，含 `en` 时返回英文模板，其他非空值返回中文。省略 `locale` 时，由查询参数 `locale`/`lang` 或请求头 `Accept-Language` 决定。\n- 每个模板相当于一份不完整的创建请求：将其字段传给创建自动化规则，并补上只有调用方能提供的内容（模板未提供时的 `cron_expr`、`timezone`、协作空间 ID）。\n",
+          "href": "/zh/api-reference/ai-sre/automations/automation-template-read-list",
+          "metadata": {
+            "sidebarTitle": "列出自动化模板"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "templates": [
-                      {
-                        "description": "Analyze incidents, alerts, response activity, notification load, and related changes from the past week.",
-                        "enabled": false,
-                        "icon": "chart-no-axes-combined",
-                        "name": "Weekly Insights",
-                        "prompt": "Generate a weekly insights report. Analyze incidents, alerts, response activity, notification load, and related changes from the past week. Focus on what happened this week, which signals deserve attention, and which improvement actions are most valuable. Do not modify any Flashduty business state.\n"
-                      }
-                    ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/ResponseEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/AutomationTemplateListResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "templates": [
+                      {
+                        "name": "Weekly Insights",
+                        "description": "Analyze incidents, alerts, response activity, notification load, and related changes from the past week.",
+                        "icon": "chart-no-axes-combined",
+                        "category": "Insights",
+                        "enabled": false,
+                        "prompt": "Generate a weekly insights report. Analyze incidents, alerts, response activity, notification load, and related changes from the past week. Focus on what happened this week, which signals deserve attention, and which improvement actions are most valuable. Do not modify any Flashduty business state.\n",
+                        "schedule_trigger_enabled": true,
+                        "cron_expr": "0 9 * * 1",
+                        "http_post_trigger_enabled": false,
+                        "oncall_incident_trigger_enabled": false,
+                        "war_room_trigger_enabled": false
+                      }
+                    ]
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -56660,67 +58611,70 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/AutomationTemplateListRequest"
+              },
+              "example": {
+                "locale": "en-US"
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/knowledge/file/delete": {
+      "post": {
+        "operationId": "knowledge-file-write-delete",
+        "summary": "删除知识文件",
+        "description": "按相对路径删除知识文件。",
+        "tags": [
+          "AI SRE/知识"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "列出自动化模板",
-        "tags": [
-          "AI SRE/自动化"
-        ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 有效 `app_key`；结果按调用者可见范围过滤 |\n",
-          "href": "/zh/api-reference/ai-sre/automations/automation-template-read-list",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **知识管理**（`ai-sre`） |\n\n## 使用说明\n\n- 删除不存在的文件也会成功，`status` 为 `ok`。\n- 知识中其他文件仍通过 @ref 引用目标文件时，删除失败并返回 `ReferenceExist`（列出引用方）；设置 `force` 可强制删除（引用方放在 `warnings` 中返回）。\n- 传入 `expected_version` 可确保自上次读取后无人修改知识时才删除；不一致时返回 HTTP 200，`status` 为 `conflict`。\n- 不传 `pack_id` 时操作账户知识；编辑账户知识需要账户 Owner 或管理员，编辑团队知识需要是该团队成员。\n- 每次调用都会记录到账户审计日志。\n",
+          "href": "/zh/api-reference/ai-sre/knowledge/knowledge-file-write-delete",
           "metadata": {
-            "sidebarTitle": "列出自动化模板"
+            "sidebarTitle": "删除知识文件"
           }
-        }
-      }
-    },
-    "/safari/knowledge/file/delete": {
-      "post": {
-        "description": "按相对路径删除知识文件。",
-        "operationId": "knowledge-file-write-delete",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "rel_path": "tmp/openapi-delete-example.md"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/KnowledgeFileDeleteRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/ResponseEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/KnowledgeFileDeleteResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "status": "ok",
+                    "version": 136
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -56738,79 +58692,80 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/KnowledgeFileDeleteRequest"
+              },
+              "example": {
+                "rel_path": "tmp/openapi-delete-example.md"
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/knowledge/file/get": {
+      "post": {
+        "operationId": "knowledge-file-read-get",
+        "summary": "获取知识文件",
+        "description": "返回知识文件的元数据及 Base64 编码的文件内容。",
+        "tags": [
+          "AI SRE/知识"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "删除知识文件",
-        "tags": [
-          "AI SRE/知识"
-        ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **知识管理**（`ai-sre`） |\n\n## 使用说明\n\n- 删除是幂等的——删除不存在的文件也会成功。\n- 当其他知识文件仍引用目标文件时，删除失败并返回 `ReferenceExist`（附带引用方列表）；设置 `force` 可强制删除（引用方以警告形式返回）。\n- 不传 `pack_id` 时默认账户范围知识；编辑账户知识需要账户 Owner/Admin 权限，编辑团队知识需要是该团队成员。\n- 每次调用都会记录到账户审计日志。\n",
-          "href": "/zh/api-reference/ai-sre/knowledge/knowledge-file-write-delete",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 文件内容以 Base64 编码放在 `content_b64` 中返回。\n- 路径下没有文件不算错误：响应中 `file` 为 `null`、`content_b64` 为空，并带上当前 `version`。`pack_id` 不存在时返回 `ResourceNotFound`。\n- 不传 `pack_id` 时读取账户知识（所有成员可读）；团队知识仅该团队成员可读。\n- 保留返回的 `version`，写回文件时作为 `expected_version` 传入，可避免覆盖他人的修改。\n",
+          "href": "/zh/api-reference/ai-sre/knowledge/knowledge-file-read-get",
           "metadata": {
-            "sidebarTitle": "删除知识文件"
+            "sidebarTitle": "获取知识文件"
           }
-        }
-      }
-    },
-    "/safari/knowledge/file/get": {
-      "post": {
-        "description": "返回知识文件的元数据及 Base64 编码的文件内容。",
-        "operationId": "knowledge-file-read-get",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "rel_path": "tmp/openapi-example.md"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/KnowledgeFileGetRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "content_b64": "IyBPcGVuQVBJIGV4YW1wbGUKVGVtcCBmaWxlIGZvciBBUEkgZG9jcyBleGFtcGxlLgo=",
-                    "file": {
-                      "checksum": "a0775f9b3f392cd0560b21ad2f579ae4a5d6b1282b9eb145688ba2de717a816d",
-                      "content_type": "text/markdown",
-                      "file_id": "kfl_gctXKRG45aFQGgxSFr59WY",
-                      "pack_id": "kpk_kE49k3FhecfJBwutbshEEc",
-                      "rel_path": "tmp/openapi-example.md",
-                      "size_bytes": 50,
-                      "updated_at_ms": 1786458764961,
-                      "updated_by": 2476444212131
-                    }
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/ResponseEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/KnowledgeFileGetResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "file": {
+                      "file_id": "kfl_gctXKRG45aFQGgxSFr59WY",
+                      "pack_id": "kpk_kE49k3FhecfJBwutbshEEc",
+                      "rel_path": "tmp/openapi-example.md",
+                      "content_type": "text/markdown",
+                      "size_bytes": 50,
+                      "checksum": "a0775f9b3f392cd0560b21ad2f579ae4a5d6b1282b9eb145688ba2de717a816d",
+                      "updated_by": 2476444212131,
+                      "updated_at_ms": 1786458764961
+                    },
+                    "content_b64": "IyBPcGVuQVBJIGV4YW1wbGUKVGVtcCBmaWxlIGZvciBBUEkgZG9jcyBleGFtcGxlLgo=",
+                    "version": 135
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -56818,6 +58773,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -56825,91 +58783,92 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/KnowledgeFileGetRequest"
+              },
+              "example": {
+                "rel_path": "tmp/openapi-example.md"
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/knowledge/file/list": {
+      "post": {
+        "operationId": "knowledge-file-read-list",
+        "summary": "查询知识文件列表",
+        "description": "查询知识文件列表，包含大小、校验和等元数据。",
+        "tags": [
+          "AI SRE/知识"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "获取知识文件",
-        "tags": [
-          "AI SRE/知识"
-        ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 文件内容通过 `content_b64`（Base64）返回；知识文件保证为 UTF-8 文本。\n- 不传 `pack_id` 时默认账户范围知识；读取团队范围知识需要是该团队成员。\n- 文件不存在时返回 `ResourceNotFound`（HTTP 400）。\n",
-          "href": "/zh/api-reference/ai-sre/knowledge/knowledge-file-read-get",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 不传 `pack_id` 时查询调用者的账户知识（不存在时创建一份空知识）。`pack_id` 不存在时返回 `ResourceNotFound`。\n- 账户知识所有成员可读；团队知识仅该团队成员可读。\n- `p`/`limit` 会被接受但不生效：始终返回全部文件。读取文件内容请用 `POST /safari/knowledge/file/get`。\n",
+          "href": "/zh/api-reference/ai-sre/knowledge/knowledge-file-read-list",
           "metadata": {
-            "sidebarTitle": "获取知识文件"
+            "sidebarTitle": "查询知识文件列表"
           }
-        }
-      }
-    },
-    "/safari/knowledge/file/list": {
-      "post": {
-        "description": "查询知识文件列表，包含大小、校验和等元数据。",
-        "operationId": "knowledge-file-read-list",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "pack_id": "kpk_kE49k3FhecfJBwutbshEEc"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/KnowledgeFileListRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ResponseEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/KnowledgeFileListResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "files": [
                       {
-                        "checksum": "fccc276c0d7fbae2e9508285cdde0f8475169634e89e466dac2e59f176c9be2f",
-                        "content_type": "text/markdown",
                         "file_id": "kfl_QvT4g3c8zAHxTthuT6hGne",
                         "pack_id": "kpk_kE49k3FhecfJBwutbshEEc",
                         "rel_path": "aliyun.md",
+                        "content_type": "text/markdown",
                         "size_bytes": 1436,
-                        "updated_at_ms": 1783311304757,
-                        "updated_by": 3790925372131
+                        "checksum": "fccc276c0d7fbae2e9508285cdde0f8475169634e89e466dac2e59f176c9be2f",
+                        "updated_by": 3790925372131,
+                        "updated_at_ms": 1783311304757
                       },
                       {
-                        "checksum": "450eabf178b41e46ea2f43d395a80bf8b956ddb9c9cea34f44ffc69a53e7a36b",
-                        "content_type": "text/markdown",
                         "file_id": "kfl_BMsQZCZSqhW4TFskYNb4H5",
                         "pack_id": "kpk_kE49k3FhecfJBwutbshEEc",
                         "rel_path": "DUTY.md",
+                        "content_type": "text/markdown",
                         "size_bytes": 1301,
-                        "updated_at_ms": 1784800003394,
-                        "updated_by": 2476444212131
+                        "checksum": "450eabf178b41e46ea2f43d395a80bf8b956ddb9c9cea34f44ffc69a53e7a36b",
+                        "updated_by": 2476444212131,
+                        "updated_at_ms": 1784800003394
                       }
                     ],
-                    "total": 17
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/ResponseEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/KnowledgeFileListResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                    "total": 2,
+                    "version": 134
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -56917,6 +58876,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -56924,80 +58886,80 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/KnowledgeFileListRequest"
+              },
+              "example": {
+                "pack_id": "kpk_kE49k3FhecfJBwutbshEEc"
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/knowledge/file/put": {
+      "post": {
+        "operationId": "knowledge-file-write-put",
+        "summary": "上传知识文件",
+        "description": "以 Base64 编码的内容创建或覆盖知识文件。",
+        "tags": [
+          "AI SRE/知识"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "查询知识文件列表",
-        "tags": [
-          "AI SRE/知识"
-        ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 不传 `pack_id` 时默认查询调用者的账户范围知识（不存在时惰性创建）。\n- 读取团队范围知识需要是该团队成员。\n- `p`/`limit` 参数会被接受，但当前实现始终返回完整文件列表。\n",
-          "href": "/zh/api-reference/ai-sre/knowledge/knowledge-file-read-list",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **知识管理**（`ai-sre`） |\n\n## 使用说明\n\n- 文件内容以 Base64 文本放在 JSON 字段 `content_b64` 中——不是 multipart 上传。写入已存在的 `rel_path` 会覆盖原文件。\n- 限制：单个文件不超过 1 MiB（`DUTY.md` 不超过 32 KiB），每份知识最多 100 个文件、总计 5 MiB。内容必须是不含 NUL 字节的 UTF-8 文本。超出限制或 `rel_path` 不合法时返回 `InvalidParameter`。\n- 传入 `expected_version`（来自上一次读取或写入）可确保期间无人修改知识时才写入；不一致时返回 HTTP 200，`status` 为 `conflict`，不写入任何内容。\n- 每次成功写入都会让知识 `version` 加 1；写入 `DUTY.md` 还会更新 `duty_version`。\n- 编辑账户知识需要账户 Owner 或管理员；编辑团队知识需要是该团队成员。\n- 每次调用都会记录到账户审计日志。\n",
+          "href": "/zh/api-reference/ai-sre/knowledge/knowledge-file-write-put",
           "metadata": {
-            "sidebarTitle": "查询知识文件列表"
+            "sidebarTitle": "上传知识文件"
           }
-        }
-      }
-    },
-    "/safari/knowledge/file/put": {
-      "post": {
-        "description": "以 Base64 编码的内容创建或覆盖知识文件。",
-        "operationId": "knowledge-file-write-put",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "content_b64": "IyBPcGVuQVBJIGV4YW1wbGUKVGVtcCBmaWxlIGZvciBBUEkgZG9jcyBleGFtcGxlLgo=",
-                "content_type": "text/markdown",
-                "rel_path": "tmp/openapi-example.md"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/KnowledgeFilePutRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "file": {
-                      "checksum": "a0775f9b3f392cd0560b21ad2f579ae4a5d6b1282b9eb145688ba2de717a816d",
-                      "content_type": "text/markdown",
-                      "file_id": "kfl_gctXKRG45aFQGgxSFr59WY",
-                      "pack_id": "kpk_kE49k3FhecfJBwutbshEEc",
-                      "rel_path": "tmp/openapi-example.md",
-                      "size_bytes": 50,
-                      "updated_at_ms": 1786458764961,
-                      "updated_by": 2476444212131
-                    }
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/ResponseEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/KnowledgeFilePutResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "status": "ok",
+                    "file": {
+                      "file_id": "kfl_gctXKRG45aFQGgxSFr59WY",
+                      "pack_id": "kpk_kE49k3FhecfJBwutbshEEc",
+                      "rel_path": "tmp/openapi-example.md",
+                      "content_type": "text/markdown",
+                      "size_bytes": 50,
+                      "checksum": "a0775f9b3f392cd0560b21ad2f579ae4a5d6b1282b9eb145688ba2de717a816d",
+                      "updated_by": 2476444212131,
+                      "updated_at_ms": 1786458764961
+                    },
+                    "version": 135
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -57015,102 +58977,107 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/KnowledgeFilePutRequest"
+              },
+              "example": {
+                "rel_path": "tmp/openapi-example.md",
+                "content_b64": "IyBPcGVuQVBJIGV4YW1wbGUKVGVtcCBmaWxlIGZvciBBUEkgZG9jcyBleGFtcGxlLgo=",
+                "content_type": "text/markdown",
+                "expected_version": 134
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/knowledge/get": {
+      "post": {
+        "operationId": "knowledge-pack-read-get",
+        "summary": "查看账户知识",
+        "description": "返回账户范围知识的元数据及其文件列表。",
+        "tags": [
+          "AI SRE/知识"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "上传知识文件",
-        "tags": [
-          "AI SRE/知识"
-        ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **知识管理**（`ai-sre`） |\n\n## 使用说明\n\n- 文件内容以 JSON 字段 `content_b64` 中的 Base64 文本上传——不是 multipart 上传。\n- 写入已存在的 `rel_path` 会覆盖原文件；`content_type` 留空时按扩展名推断（`.md` → `text/markdown`）。\n- 内容解码后必须是合法的 UTF-8 文本，二进制内容会被拒绝并返回 `InvalidParameter`。\n- 编辑账户范围知识需要账户 Owner/Admin 权限；编辑团队知识需要是该团队成员。\n- 每次调用都会记录到账户审计日志。\n",
-          "href": "/zh/api-reference/ai-sre/knowledge/knowledge-file-write-put",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 固定返回调用者的账户知识，没有 `pack_id` 参数。团队知识请先用 `POST /safari/knowledge/pack/list` 查到，再用 `POST /safari/knowledge/file/list` 列出文件。\n- 账户还没有知识时，本次调用会创建一份空知识，因此有效账户调用不会返回 not-found。\n- 账户内任何成员都能读取；`pack.can_edit` 表示调用者能否修改。\n",
+          "href": "/zh/api-reference/ai-sre/knowledge/knowledge-pack-read-get",
           "metadata": {
-            "sidebarTitle": "上传知识文件"
+            "sidebarTitle": "查看账户知识"
           }
-        }
-      }
-    },
-    "/safari/knowledge/get": {
-      "post": {
-        "description": "返回账户范围知识的元数据及其文件列表。",
-        "operationId": "knowledge-pack-read-get",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {},
-              "schema": {
-                "$ref": "#/components/schemas/KnowledgeGetRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ResponseEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/KnowledgeGetResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
+                    "pack": {
+                      "pack_id": "kpk_kE49k3FhecfJBwutbshEEc",
+                      "account_id": 2451002751131,
+                      "scope": "account",
+                      "scope_id": 2451002751131,
+                      "file_count": 2,
+                      "total_bytes": 2737,
+                      "version": 134,
+                      "duty_version": 130,
+                      "created_by": 2476444212131,
+                      "created_at_ms": 1778768680053,
+                      "updated_at_ms": 1786456567177,
+                      "can_edit": true
+                    },
                     "files": [
                       {
-                        "checksum": "fccc276c0d7fbae2e9508285cdde0f8475169634e89e466dac2e59f176c9be2f",
-                        "content_type": "text/markdown",
                         "file_id": "kfl_QvT4g3c8zAHxTthuT6hGne",
                         "pack_id": "kpk_kE49k3FhecfJBwutbshEEc",
                         "rel_path": "aliyun.md",
+                        "content_type": "text/markdown",
                         "size_bytes": 1436,
-                        "updated_at_ms": 1783311304757,
-                        "updated_by": 3790925372131
+                        "checksum": "fccc276c0d7fbae2e9508285cdde0f8475169634e89e466dac2e59f176c9be2f",
+                        "updated_by": 3790925372131,
+                        "updated_at_ms": 1783311304757
                       },
                       {
-                        "checksum": "450eabf178b41e46ea2f43d395a80bf8b956ddb9c9cea34f44ffc69a53e7a36b",
-                        "content_type": "text/markdown",
                         "file_id": "kfl_BMsQZCZSqhW4TFskYNb4H5",
                         "pack_id": "kpk_kE49k3FhecfJBwutbshEEc",
                         "rel_path": "DUTY.md",
+                        "content_type": "text/markdown",
                         "size_bytes": 1301,
-                        "updated_at_ms": 1784800003394,
-                        "updated_by": 2476444212131
+                        "checksum": "450eabf178b41e46ea2f43d395a80bf8b956ddb9c9cea34f44ffc69a53e7a36b",
+                        "updated_by": 2476444212131,
+                        "updated_at_ms": 1784800003394
                       }
-                    ],
-                    "pack": {
-                      "account_id": 2451002751131,
-                      "can_edit": true,
-                      "created_at_ms": 1778768680053,
-                      "created_by": 2476444212131,
-                      "duty_version": 130,
-                      "file_count": 17,
-                      "pack_id": "kpk_kE49k3FhecfJBwutbshEEc",
-                      "scope": "account",
-                      "scope_id": 2451002751131,
-                      "total_bytes": 41010,
-                      "updated_at_ms": 1786456567177,
-                      "version": 134
-                    }
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/ResponseEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/KnowledgeGetResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                    ]
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -57118,6 +59085,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -57125,69 +59095,67 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/KnowledgeGetRequest"
+              },
+              "example": {}
+            }
+          }
+        }
+      }
+    },
+    "/safari/knowledge/pack/delete": {
+      "post": {
+        "operationId": "knowledge-pack-write-delete",
+        "summary": "删除知识",
+        "description": "删除知识及其全部文件。",
+        "tags": [
+          "AI SRE/知识"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "查看账户知识",
-        "tags": [
-          "AI SRE/知识"
-        ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 固定返回调用者的账户范围知识——没有 `pack_id` 参数；如需团队知识请使用 `POST /safari/knowledge/pack/list`。\n- 账户知识在首次访问时惰性创建，因此有效账户调用不会返回 not-found。\n",
-          "href": "/zh/api-reference/ai-sre/knowledge/knowledge-pack-read-get",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **知识管理**（`ai-sre`） |\n\n## 使用说明\n\n- 删除知识及其包含的所有文件，没有恢复接口。\n- 需要对该知识有 `can_edit` 权限：账户知识需账户 Owner 或管理员，团队知识需是该团队成员。\n- 允许删除账户知识；下一次调用 `POST /safari/knowledge/get`（或不带 `pack_id` 的文件接口）会重新创建一份空知识。\n- 每次调用都会记录到账户审计日志。\n",
+          "href": "/zh/api-reference/ai-sre/knowledge/knowledge-pack-write-delete",
           "metadata": {
-            "sidebarTitle": "查看账户知识"
+            "sidebarTitle": "删除知识"
           }
-        }
-      }
-    },
-    "/safari/knowledge/pack/delete": {
-      "post": {
-        "description": "删除知识及其全部文件。",
-        "operationId": "knowledge-pack-write-delete",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "pack_id": "kpk_YqHXPTEUHQFGepUfRS7vsh"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/KnowledgePackDeleteRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "ok": true
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/ResponseEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/KnowledgePackDeleteResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "ok": true
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -57205,81 +59173,81 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/KnowledgePackDeleteRequest"
+              },
+              "example": {
+                "pack_id": "kpk_YqHXPTEUHQFGepUfRS7vsh"
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/knowledge/pack/ensure": {
+      "post": {
+        "operationId": "knowledge-pack-write-ensure",
+        "summary": "确保知识存在",
+        "description": "在指定范围幂等创建知识，已存在时直接返回现有知识。",
+        "tags": [
+          "AI SRE/知识"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "删除知识",
-        "tags": [
-          "AI SRE/知识"
-        ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **知识管理**（`ai-sre`） |\n\n## 使用说明\n\n- 删除知识会同时删除其中所有文件，且不可恢复。\n- 允许删除账户范围知识；下次访问时会重新创建一份空知识。\n- 每次调用都会记录到账户审计日志。\n",
-          "href": "/zh/api-reference/ai-sre/knowledge/knowledge-pack-write-delete",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **知识管理**（`ai-sre`） |\n\n## 使用说明\n\n- 幂等：若（`scope`, `scope_id`）已有知识则直接返回，否则创建一份空知识。\n- `account` 范围忽略 `scope_id`；只要该知识中没有 `DUTY.md`（包括被删除后），就会写入一份默认 `DUTY.md`。返回的 `file_count`/`version` 是写入前读取的，可能尚未包含该文件。\n- `account` 范围需要账户 Owner 或管理员；`team` 范围需要是该团队成员——Owner 和管理员也不例外。\n- 每次调用都会记录到账户审计日志。\n",
+          "href": "/zh/api-reference/ai-sre/knowledge/knowledge-pack-write-ensure",
           "metadata": {
-            "sidebarTitle": "删除知识"
+            "sidebarTitle": "确保知识存在"
           }
-        }
-      }
-    },
-    "/safari/knowledge/pack/ensure": {
-      "post": {
-        "description": "在指定范围幂等创建知识，已存在时直接返回现有知识。",
-        "operationId": "knowledge-pack-write-ensure",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "scope": "team",
-                "scope_id": 2477033058131
-              },
-              "schema": {
-                "$ref": "#/components/schemas/KnowledgePackEnsureRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "account_id": 2451002751131,
-                    "can_edit": true,
-                    "created_at_ms": 1778768680053,
-                    "created_by": 2476444212131,
-                    "duty_version": 130,
-                    "file_count": 17,
-                    "pack_id": "kpk_kE49k3FhecfJBwutbshEEc",
-                    "scope": "account",
-                    "scope_id": 2451002751131,
-                    "total_bytes": 41010,
-                    "updated_at_ms": 1786458765182,
-                    "version": 138
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/ResponseEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/KnowledgePackItem"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "pack_id": "kpk_5qRL34nKtoWM4nQVT2kHzy",
+                    "account_id": 2451002751131,
+                    "scope": "team",
+                    "scope_id": 2477033058131,
+                    "team_name": "SRE Team",
+                    "file_count": 4,
+                    "total_bytes": 11159,
+                    "version": 15,
+                    "duty_version": 15,
+                    "created_by": 2476444212131,
+                    "created_at_ms": 1782201586089,
+                    "updated_at_ms": 1785462092702,
+                    "can_edit": true
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -57297,103 +59265,101 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/KnowledgePackEnsureRequest"
+              },
+              "example": {
+                "scope": "team",
+                "scope_id": 2477033058131
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/knowledge/pack/list": {
+      "post": {
+        "operationId": "knowledge-pack-read-list",
+        "summary": "查询知识列表",
+        "description": "查询调用者可见的账户与团队范围知识列表。",
+        "tags": [
+          "AI SRE/知识"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "确保知识存在",
-        "tags": [
-          "AI SRE/知识"
-        ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **知识管理**（`ai-sre`） |\n\n## 使用说明\n\n- 幂等：若（`scope`, `scope_id`）已存在知识，则原样返回。\n- 账户范围忽略 `scope_id`（使用账户 ID），首次创建时会自动写入默认 `DUTY.md`。\n- 创建账户范围知识需要账户 Owner/Admin 权限；在团队下创建需要是该团队成员。\n- 每次调用都会记录到账户审计日志。\n",
-          "href": "/zh/api-reference/ai-sre/knowledge/knowledge-pack-write-ensure",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 返回账户知识，以及调用者所属团队的知识。对所有调用者都一样——Owner 和管理员也看不到自己未加入团队的知识。\n- 账户知识只有在被创建后才会出现（通过 `POST /safari/knowledge/get`、不带 `pack_id` 的文件接口或 `POST /safari/knowledge/pack/ensure`）；本接口不会创建它。\n- 先按 `query` 过滤，再用 `p`/`limit` 对过滤结果分页；`total` 为过滤后的总数。`p` 与 `limit` 都不传则返回全部。\n",
+          "href": "/zh/api-reference/ai-sre/knowledge/knowledge-pack-read-list",
           "metadata": {
-            "sidebarTitle": "确保知识存在"
+            "sidebarTitle": "查询知识列表"
           }
-        }
-      }
-    },
-    "/safari/knowledge/pack/list": {
-      "post": {
-        "description": "查询调用者可见的账户与团队范围知识列表。",
-        "operationId": "knowledge-pack-read-list",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "include_account": true,
-                "limit": 20,
-                "p": 1,
-                "scope": "all"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/KnowledgePackListRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ResponseEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/KnowledgePackListResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "packs": [
                       {
-                        "account_id": 2451002751131,
-                        "can_edit": true,
-                        "created_at_ms": 1778768680053,
-                        "created_by": 2476444212131,
-                        "duty_version": 130,
-                        "file_count": 17,
                         "pack_id": "kpk_kE49k3FhecfJBwutbshEEc",
+                        "account_id": 2451002751131,
                         "scope": "account",
                         "scope_id": 2451002751131,
-                        "total_bytes": 41010,
+                        "file_count": 2,
+                        "total_bytes": 2737,
+                        "version": 134,
+                        "duty_version": 130,
+                        "created_by": 2476444212131,
+                        "created_at_ms": 1778768680053,
                         "updated_at_ms": 1786456567177,
-                        "version": 134
+                        "can_edit": true
                       },
                       {
-                        "account_id": 2451002751131,
-                        "can_edit": true,
-                        "created_at_ms": 1782201586089,
-                        "created_by": 2476444212131,
-                        "duty_version": 15,
-                        "file_count": 4,
                         "pack_id": "kpk_5qRL34nKtoWM4nQVT2kHzy",
+                        "account_id": 2451002751131,
                         "scope": "team",
                         "scope_id": 2477033058131,
-                        "team_name": "研发团队",
+                        "team_name": "SRE Team",
+                        "file_count": 4,
                         "total_bytes": 11159,
+                        "version": 15,
+                        "duty_version": 15,
+                        "created_by": 2476444212131,
+                        "created_at_ms": 1782201586089,
                         "updated_at_ms": 1785462092702,
-                        "version": 15
+                        "can_edit": true
                       }
                     ],
-                    "total": 3
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/ResponseEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/KnowledgePackListResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                    "total": 2
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -57401,6 +59367,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -57408,83 +59377,84 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/KnowledgePackListRequest"
+              },
+              "example": {
+                "p": 1,
+                "limit": 20,
+                "scope": "all",
+                "include_account": true
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/knowledge/pack/update": {
+      "post": {
+        "operationId": "knowledge-pack-write-update",
+        "summary": "更新知识",
+        "description": "将知识移动到其他账户或团队范围。",
+        "tags": [
+          "AI SRE/知识"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "查询知识列表",
-        "tags": [
-          "AI SRE/知识"
-        ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 可见性与控制台一致：管理员可见账户知识及全部团队知识；非管理员可见账户知识及所属团队的知识，传入的 `team_ids` 会被静默过滤为其所属团队。\n- `scope` 用于选择 `all`（默认）、仅 `account` 或仅 `team`，会覆盖 `include_account`。\n- `query` 对知识 ID、范围和团队名称做大小写不敏感的子串过滤；`p`/`limit` 对过滤结果分页。\n",
-          "href": "/zh/api-reference/ai-sre/knowledge/knowledge-pack-read-list",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **知识管理**（`ai-sre`） |\n\n## 使用说明\n\n- `scope` 是唯一可修改的字段；不传或传入当前范围时不做修改，直接返回当前知识。\n- 调用者须能编辑知识当前所在范围（`can_edit`），并对目标范围有权限：自己所属的团队，或仅 Owner/管理员可设为 `account`。\n- 目标范围已有知识时返回 `ReferenceExist`，两份知识不会合并。文件和 `version` 随之移动，保持不变。\n- 每次调用都会记录到账户审计日志。\n",
+          "href": "/zh/api-reference/ai-sre/knowledge/knowledge-pack-write-update",
           "metadata": {
-            "sidebarTitle": "查询知识列表"
+            "sidebarTitle": "更新知识"
           }
-        }
-      }
-    },
-    "/safari/knowledge/pack/update": {
-      "post": {
-        "description": "将知识移动到其他账户或团队范围。",
-        "operationId": "knowledge-pack-write-update",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "pack_id": "kpk_5qRL34nKtoWM4nQVT2kHzy",
-                "scope": "team",
-                "scope_id": 2477033058131
-              },
-              "schema": {
-                "$ref": "#/components/schemas/KnowledgePackUpdateRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "account_id": 2451002751131,
-                    "can_edit": true,
-                    "created_at_ms": 1782201586089,
-                    "created_by": 2476444212131,
-                    "duty_version": 15,
-                    "file_count": 4,
-                    "pack_id": "kpk_5qRL34nKtoWM4nQVT2kHzy",
-                    "scope": "team",
-                    "scope_id": 2477033058131,
-                    "team_name": "研发团队",
-                    "total_bytes": 11159,
-                    "updated_at_ms": 1785462092702,
-                    "version": 15
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/ResponseEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/KnowledgePackItem"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "pack_id": "kpk_5qRL34nKtoWM4nQVT2kHzy",
+                    "account_id": 2451002751131,
+                    "scope": "team",
+                    "scope_id": 2477033058131,
+                    "team_name": "SRE Team",
+                    "file_count": 4,
+                    "total_bytes": 11159,
+                    "version": 15,
+                    "duty_version": 15,
+                    "created_by": 2476444212131,
+                    "created_at_ms": 1782201586089,
+                    "updated_at_ms": 1785462092702,
+                    "can_edit": true
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -57502,88 +59472,89 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/KnowledgePackUpdateRequest"
+              },
+              "example": {
+                "pack_id": "kpk_5qRL34nKtoWM4nQVT2kHzy",
+                "scope": "team",
+                "scope_id": 2477033058131
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/mcp/server/create": {
+      "post": {
+        "operationId": "mcp-write-server-create",
+        "summary": "创建 MCP 服务器",
+        "description": "在账户下注册新的 MCP 服务器（连接器）。",
+        "tags": [
+          "AI SRE/MCP 服务器"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "更新知识",
-        "tags": [
-          "AI SRE/知识"
-        ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **知识管理**（`ai-sre`） |\n\n## 使用说明\n\n- `scope` 是唯一可修改的字段；不传则为空操作，返回当前知识。\n- 团队范围必须传 `scope_id`；账户范围自动使用账户 ID。\n- 目标范围已存在知识时返回 `ReferenceExist`——两份知识不会被合并。\n- 每次调用都会记录到账户审计日志。\n",
-          "href": "/zh/api-reference/ai-sre/knowledge/knowledge-pack-write-update",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **MCP 管理**（`ai-sre`） |\n\n## 使用说明\n\n- `command`/`args`/`env` 用于 `stdio`；`url`/`headers` 用于 `sse`/`streamable-http`。\n- `server_name` 必须以字母开头，只能包含字母、数字、`-` 或 `_`，且在其作用域（账户级或单个团队）内唯一；违反时返回 `InvalidParameter`。\n- 未传 `source_template_name` 时，创建到团队（`team_id > 0`）要求调用者属于该团队，只有账户 owner 或管理员可以在账户级（`team_id=0`）创建。\n- 传入 `source_template_name` 表示安装市场模板：模板必须存在（否则返回 `ResourceNotFound`），`team_id` 被忽略、服务器一律建在账户级，且连接字段必须与模板一致，只能填写模板声明的参数值。若模板为按人认证、且其参数允许安装者决定目标主机，则仅账户 owner 或管理员可安装。\n- `environments` 的每一项必须是 `cloud`，或某个账户级 BYOC Runner、调用者所属团队的 BYOC Runner 的环境 ID；重复项会被去除，空字符串会被拒绝。省略或为空表示所有环境。\n- `per_user_secret` 认证模式要求 `secret_schema` 为合法 JSON 且包含非空的 `header_name`。\n- `env` 与 `headers` 中，键名包含 `KEY`、`SECRET`、`TOKEN`、`PASSWORD`、`PASSWD`、`CREDENTIAL` 或 `AUTHORIZATION`（不区分大小写）、或含 `PWD` / `PASS` 分段的值，以及已加密存储的值，会加密存储并在响应中脱敏。\n- 响应为已保存的服务器。之后服务端会通过已在线的执行环境在后台拉取其工具列表，调用不会等待该过程。\n- 每次调用都会记录到账户审计日志。\n",
+          "href": "/zh/api-reference/ai-sre/mcp-servers/mcp-write-server-create",
           "metadata": {
-            "sidebarTitle": "更新知识"
+            "sidebarTitle": "创建 MCP 服务器"
           }
-        }
-      }
-    },
-    "/safari/mcp/server/create": {
-      "post": {
-        "description": "在账户下注册新的 MCP 服务器（连接器）。",
-        "operationId": "mcp-write-server-create",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "description": "Query Prometheus metrics and alerts.",
-                "server_name": "prometheus",
-                "status": "enabled",
-                "transport": "streamable-http",
-                "url": "https://mcp.example.com/prometheus"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/MCPServerCreateRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "account_id": 10023,
-                    "auth_mode": "shared",
-                    "call_timeout": 60,
-                    "can_edit": true,
-                    "connect_timeout": 10,
-                    "created_at": 1716960000000,
-                    "created_by": 80011,
-                    "description": "Query Prometheus metrics and alerts.",
-                    "environments": [],
-                    "server_id": "mcp_4kP9wQ2nLceRtY7uVb3xA1",
-                    "server_name": "prometheus",
-                    "status": "enabled",
-                    "team_id": 0,
-                    "transport": "streamable-http",
-                    "updated_at": 1717046400000,
-                    "url": "https://mcp.example.com/prometheus"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/ResponseEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/MCPServerItem"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "server_id": "mcp_4kP9wQ2nLceRtY7uVb3xA1",
+                    "account_id": 10023,
+                    "team_id": 0,
+                    "can_edit": true,
+                    "environments": [],
+                    "server_name": "prometheus",
+                    "description": "Query Prometheus metrics and alerts.",
+                    "transport": "streamable-http",
+                    "url": "https://mcp.example.com/prometheus",
+                    "headers": {
+                      "Authorization": "Bear****f2c1"
+                    },
+                    "status": "enabled",
+                    "connect_timeout": 0,
+                    "call_timeout": 0,
+                    "auth_mode": "shared",
+                    "created_by": 80011,
+                    "created_at": 1716960000000,
+                    "updated_at": 1716960000000
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -57601,68 +59572,74 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/MCPServerCreateRequest"
+              },
+              "example": {
+                "server_name": "prometheus",
+                "description": "Query Prometheus metrics and alerts.",
+                "transport": "streamable-http",
+                "url": "https://mcp.example.com/prometheus",
+                "headers": {
+                  "Authorization": "Bearer example-token-f2c1"
+                },
+                "status": "enabled"
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/mcp/server/delete": {
+      "post": {
+        "operationId": "mcp-write-server-delete",
+        "summary": "删除 MCP 服务器",
+        "description": "按 ID 删除 MCP 服务器。",
+        "tags": [
+          "AI SRE/MCP 服务器"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "创建 MCP 服务器",
-        "tags": [
-          "AI SRE/MCP 服务器"
-        ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **MCP 管理**（`ai-sre`） |\n\n## 使用说明\n\n- `command`/`args`/`env` 用于 `stdio`；`url`/`headers` 用于 `sse`/`streamable-http`。\n- 服务器名称必须以字母开头，且只能包含字母、数字、`-` 或 `_`，在其作用域（账户范围或单个团队）内不区分大小写唯一；不满足则返回 InvalidParameter。\n- `environments` 限定服务器可运行的环境：`cloud` 和/或 BYOC Runner 的环境 ID 列表；省略或为空表示所有环境。\n- `per_user_secret` 认证模式要求 `secret_schema` 为合法 JSON 且包含非空的 `header_name`。\n- 每次调用都会记录到账户审计日志。\n",
-          "href": "/zh/api-reference/ai-sre/mcp-servers/mcp-write-server-create",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **MCP 管理**（`ai-sre`） |\n\n## 使用说明\n\n- 永久删除该服务器并清除其工具列表缓存；该服务器不再提供给 AI SRE 会话使用，名称可以重新使用。\n- 需要对服务器当前所属团队有编辑权限：账户级服务器（`team_id=0`）仅账户 owner 或管理员可改；团队服务器仅该团队成员可改（owner/管理员也必须是该团队成员）。\n- 服务器不存在时返回 `ResourceNotFound`。\n- 每次调用都会记录到账户审计日志。\n",
+          "href": "/zh/api-reference/ai-sre/mcp-servers/mcp-write-server-delete",
           "metadata": {
-            "sidebarTitle": "创建 MCP 服务器"
+            "sidebarTitle": "删除 MCP 服务器"
           }
-        }
-      }
-    },
-    "/safari/mcp/server/delete": {
-      "post": {
-        "description": "按 ID 删除 MCP 服务器。",
-        "operationId": "mcp-write-server-delete",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "server_id": "mcp_4kP9wQ2nLceRtY7uVb3xA1"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/MCPServerDeleteRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": null,
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/ResponseEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "description": "成功时恒为 null。",
-                          "type": "null"
+                          "type": "null",
+                          "description": "成功时不返回该字段，响应体只有 `request_id`。"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -57680,68 +59657,67 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/MCPServerDeleteRequest"
+              },
+              "example": {
+                "server_id": "mcp_4kP9wQ2nLceRtY7uVb3xA1"
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/mcp/server/disable": {
+      "post": {
+        "operationId": "mcp-write-server-disable",
+        "summary": "禁用 MCP 服务器",
+        "description": "禁用已启用的 MCP 服务器。",
+        "tags": [
+          "AI SRE/MCP 服务器"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "删除 MCP 服务器",
-        "tags": [
-          "AI SRE/MCP 服务器"
-        ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **MCP 管理**（`ai-sre`） |\n\n## 使用说明\n\n- 每次调用都会记录到账户审计日志。\n",
-          "href": "/zh/api-reference/ai-sre/mcp-servers/mcp-write-server-delete",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **MCP 管理**（`ai-sre`） |\n\n## 使用说明\n\n- 服务器已处于停用状态时返回 `InvalidParameter`。\n- 需要对服务器当前所属团队有编辑权限：账户级服务器（`team_id=0`）仅账户 owner 或管理员可改；团队服务器仅该团队成员可改（owner/管理员也必须是该团队成员）。\n- 停用后，该服务器的工具不再提供给 AI SRE 会话，配置保留。\n- 每次调用都会记录到账户审计日志。\n",
+          "href": "/zh/api-reference/ai-sre/mcp-servers/mcp-write-server-disable",
           "metadata": {
-            "sidebarTitle": "删除 MCP 服务器"
+            "sidebarTitle": "禁用 MCP 服务器"
           }
-        }
-      }
-    },
-    "/safari/mcp/server/disable": {
-      "post": {
-        "description": "禁用已启用的 MCP 服务器。",
-        "operationId": "mcp-write-server-disable",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "server_id": "mcp_4kP9wQ2nLceRtY7uVb3xA1"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/MCPServerStatusRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": null,
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/ResponseEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "description": "成功时恒为 null。",
-                          "type": "null"
+                          "type": "null",
+                          "description": "成功时不返回该字段，响应体只有 `request_id`。"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -57759,68 +59735,67 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/MCPServerStatusRequest"
+              },
+              "example": {
+                "server_id": "mcp_4kP9wQ2nLceRtY7uVb3xA1"
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/mcp/server/enable": {
+      "post": {
+        "operationId": "mcp-write-server-enable",
+        "summary": "启用 MCP 服务器",
+        "description": "启用已禁用的 MCP 服务器。",
+        "tags": [
+          "AI SRE/MCP 服务器"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "禁用 MCP 服务器",
-        "tags": [
-          "AI SRE/MCP 服务器"
-        ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **MCP 管理**（`ai-sre`） |\n\n## 使用说明\n\n- 对已禁用的服务器再次禁用会返回 InvalidParameter，而不是静默忽略。\n- 需要对服务器当前所属团队具有编辑权限：账户级服务器仅限所有者/管理员；团队级服务器要求调用者属于该团队（或为所有者/管理员）。\n- 每次调用都会记录到账户审计日志。\n",
-          "href": "/zh/api-reference/ai-sre/mcp-servers/mcp-write-server-disable",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **MCP 管理**（`ai-sre`） |\n\n## 使用说明\n\n- 服务器已处于启用状态时返回 `InvalidParameter`。\n- 需要对服务器当前所属团队有编辑权限：账户级服务器（`team_id=0`）仅账户 owner 或管理员可改；团队服务器仅该团队成员可改（owner/管理员也必须是该团队成员）。\n- 启用后，该服务器的工具会重新提供给 AI SRE 会话；工具列表缓存被清除，下次使用时重新拉取。\n- 每次调用都会记录到账户审计日志。\n",
+          "href": "/zh/api-reference/ai-sre/mcp-servers/mcp-write-server-enable",
           "metadata": {
-            "sidebarTitle": "禁用 MCP 服务器"
+            "sidebarTitle": "启用 MCP 服务器"
           }
-        }
-      }
-    },
-    "/safari/mcp/server/enable": {
-      "post": {
-        "description": "启用已禁用的 MCP 服务器。",
-        "operationId": "mcp-write-server-enable",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "server_id": "mcp_4kP9wQ2nLceRtY7uVb3xA1"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/MCPServerStatusRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": null,
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/ResponseEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "description": "成功时恒为 null。",
-                          "type": "null"
+                          "type": "null",
+                          "description": "成功时不返回该字段，响应体只有 `request_id`。"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -57838,84 +59813,87 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/MCPServerStatusRequest"
+              },
+              "example": {
+                "server_id": "mcp_4kP9wQ2nLceRtY7uVb3xA1"
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/mcp/server/get": {
+      "post": {
+        "operationId": "mcp-read-server-get",
+        "summary": "查看 MCP 服务器详情",
+        "description": "查看单个 MCP 服务器（纯数据库读取，不实时探测远端服务器）。",
+        "tags": [
+          "AI SRE/MCP 服务器"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "启用 MCP 服务器",
-        "tags": [
-          "AI SRE/MCP 服务器"
-        ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **MCP 管理**（`ai-sre`） |\n\n## 使用说明\n\n- 对已启用的服务器再次启用会返回 InvalidParameter，而不是静默忽略。\n- 需要对服务器当前所属团队具有编辑权限：账户级服务器仅限所有者/管理员；团队级服务器要求调用者属于该团队（或为所有者/管理员）。\n- 每次调用都会记录到账户审计日志。\n",
-          "href": "/zh/api-reference/ai-sre/mcp-servers/mcp-write-server-enable",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **60 次/分钟**；**3 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 纯数据库读取——不会实时探测远端服务器；返回存储的配置与缓存的 `ai_description`。\n- `env` 与 `headers` 中，键名包含 `KEY`、`SECRET`、`TOKEN`、`PASSWORD`、`PASSWD`、`CREDENTIAL` 或 `AUTHORIZATION`（不区分大小写）、或含 `PWD` / `PASS` 分段的值，以及已加密存储的值，会在响应中脱敏。\n- `test_error` 与 `tested_at` 反映最近一次在控制台发起的连接测试；从未测试过时不返回。\n- 服务器不存在时返回 `ResourceNotFound`。\n",
+          "href": "/zh/api-reference/ai-sre/mcp-servers/mcp-read-server-get",
           "metadata": {
-            "sidebarTitle": "启用 MCP 服务器"
+            "sidebarTitle": "查看 MCP 服务器详情"
           }
-        }
-      }
-    },
-    "/safari/mcp/server/get": {
-      "post": {
-        "description": "查看单个 MCP 服务器（纯数据库读取，不实时探测远端服务器）。",
-        "operationId": "mcp-read-server-get",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "server_id": "mcp_4kP9wQ2nLceRtY7uVb3xA1"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/MCPServerGetRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "account_id": 10023,
-                    "auth_mode": "shared",
-                    "call_timeout": 60,
-                    "can_edit": true,
-                    "connect_timeout": 10,
-                    "created_at": 1716960000000,
-                    "created_by": 80011,
-                    "description": "Query Prometheus metrics and alerts.",
-                    "environments": [],
-                    "server_id": "mcp_4kP9wQ2nLceRtY7uVb3xA1",
-                    "server_name": "prometheus",
-                    "status": "enabled",
-                    "team_id": 0,
-                    "transport": "streamable-http",
-                    "updated_at": 1717046400000,
-                    "url": "https://mcp.example.com/prometheus"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/ResponseEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/MCPServerItem"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "server_id": "mcp_4kP9wQ2nLceRtY7uVb3xA1",
+                    "account_id": 10023,
+                    "team_id": 0,
+                    "can_edit": true,
+                    "environments": [],
+                    "server_name": "prometheus",
+                    "description": "Query Prometheus metrics and alerts.",
+                    "transport": "streamable-http",
+                    "url": "https://mcp.example.com/prometheus",
+                    "headers": {
+                      "Authorization": "Bear****f2c1"
+                    },
+                    "status": "enabled",
+                    "connect_timeout": 0,
+                    "call_timeout": 0,
+                    "auth_mode": "shared",
+                    "created_by": 80011,
+                    "created_at": 1716960000000,
+                    "updated_at": 1717046400000
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -57923,6 +59901,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -57930,91 +59911,92 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/MCPServerGetRequest"
+              },
+              "example": {
+                "server_id": "mcp_4kP9wQ2nLceRtY7uVb3xA1"
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/mcp/server/list": {
+      "post": {
+        "operationId": "mcp-read-server-list",
+        "summary": "查询 MCP 服务器列表",
+        "description": "分页查询调用者在账户与团队范围内可见的 MCP 服务器。",
+        "tags": [
+          "AI SRE/MCP 服务器"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "查看 MCP 服务器详情",
-        "tags": [
-          "AI SRE/MCP 服务器"
-        ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 纯数据库读取——不会实时探测远端服务器；返回存储的配置（敏感值已脱敏）与缓存的 `ai_description`。\n",
-          "href": "/zh/api-reference/ai-sre/mcp-servers/mcp-read-server-get",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 分页使用 `p`/`limit`：`p` 小于 1 时按 1 处理，`limit` 小于 1 时按 20 处理。结果按名称、再按服务器 ID 升序排列。\n- 可见范围对所有调用者（含 owner 和管理员）都按真实团队成员关系计算：账户级记录，加上调用者所属团队的记录；`team_ids` 中不在此范围内的团队 ID 会被忽略。\n- `scope=account` 只返回账户级记录；`scope=team` 只返回团队记录；`all`（默认）返回团队记录，并在 `include_account` 不为 `false` 时一并返回账户级记录。\n- `query` 会对名称、描述、AI 生成描述、服务器 ID、传输协议、URL、命令及市场模板名称进行不区分大小写的子串匹配。\n- 响应不包含实时工具列表；每条记录的 `can_edit` 表示调用者能否修改该服务器。\n",
+          "href": "/zh/api-reference/ai-sre/mcp-servers/mcp-read-server-list",
           "metadata": {
-            "sidebarTitle": "查看 MCP 服务器详情"
+            "sidebarTitle": "查询 MCP 服务器列表"
           }
-        }
-      }
-    },
-    "/safari/mcp/server/list": {
-      "post": {
-        "description": "分页查询调用者在账户与团队范围内可见的 MCP 服务器。",
-        "operationId": "mcp-read-server-list",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "include_account": true,
-                "limit": 20,
-                "p": 1
-              },
-              "schema": {
-                "$ref": "#/components/schemas/MCPServerListRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "servers": [
-                      {
-                        "account_id": 10023,
-                        "auth_mode": "shared",
-                        "call_timeout": 60,
-                        "can_edit": true,
-                        "connect_timeout": 10,
-                        "created_at": 1716960000000,
-                        "created_by": 80011,
-                        "description": "Query Prometheus metrics and alerts.",
-                        "environments": [],
-                        "server_id": "mcp_4kP9wQ2nLceRtY7uVb3xA1",
-                        "server_name": "prometheus",
-                        "status": "enabled",
-                        "team_id": 0,
-                        "transport": "streamable-http",
-                        "updated_at": 1717046400000,
-                        "url": "https://mcp.example.com/prometheus"
-                      }
-                    ],
-                    "total": 1
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/ResponseEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/MCPServerListResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "total": 1,
+                    "servers": [
+                      {
+                        "server_id": "mcp_4kP9wQ2nLceRtY7uVb3xA1",
+                        "account_id": 10023,
+                        "team_id": 0,
+                        "can_edit": true,
+                        "environments": [],
+                        "server_name": "prometheus",
+                        "description": "Query Prometheus metrics and alerts.",
+                        "transport": "streamable-http",
+                        "url": "https://mcp.example.com/prometheus",
+                        "headers": {
+                          "Authorization": "Bear****f2c1"
+                        },
+                        "status": "enabled",
+                        "connect_timeout": 0,
+                        "call_timeout": 0,
+                        "auth_mode": "shared",
+                        "created_by": 80011,
+                        "created_at": 1716960000000,
+                        "updated_at": 1717046400000
+                      }
+                    ]
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -58022,6 +60004,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -58029,85 +60014,89 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/MCPServerListRequest"
+              },
+              "example": {
+                "p": 1,
+                "limit": 20,
+                "include_account": true
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/mcp/server/update": {
+      "post": {
+        "operationId": "mcp-write-server-update",
+        "summary": "更新 MCP 服务器",
+        "description": "更新 MCP 服务器配置；省略字段表示不变。",
+        "tags": [
+          "AI SRE/MCP 服务器"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "查询 MCP 服务器列表",
-        "tags": [
-          "AI SRE/MCP 服务器"
-        ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 响应不包含实时工具列表；工具列表在创建/更新后异步探测并缓存供运行时使用。\n- `query` 会对名称、描述、AI 生成描述、服务器 ID、传输协议、URL、命令及市场模板名称进行不区分大小写的子串匹配。\n",
-          "href": "/zh/api-reference/ai-sre/mcp-servers/mcp-read-server-list",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **MCP 管理**（`ai-sre`） |\n\n## 使用说明\n\n- 需要对服务器当前所属团队有编辑权限：账户级服务器（`team_id=0`）仅账户 owner 或管理员可改；团队服务器仅该团队成员可改（owner/管理员也必须是该团队成员）。\n- `server_name`、`description`、`transport`、`command`、`url`、`auth_mode` 仅在非空时修改，`connect_timeout` / `call_timeout` 仅在非零时修改，因此无法通过本接口清空这些字段。\n- `args`、`env`、`headers` 传入即整体替换：`env`/`headers` 中未传入的键会被删除。对受保护的 `env`/`headers` 键，回传脱敏值或空字符串会保留已存储的密钥。\n- 传入 `auth_mode` 时，`secret_schema` 会被同一请求中的值覆盖（未传则置空）。`auth_mode` 或 `url` 实际发生变化时会清空 `oauth_metadata`，除非同时传入非空的 `oauth_metadata`。\n- 改到其他团队（`team_id > 0`）要求调用者属于目标团队，且从市场安装的服务器不允许改到团队；改为账户级（`team_id=0`）仅限账户 owner 或管理员。变更团队但未同时传 `environments` 时，现有 Runner 条目必须对调用者仍可选，否则更新被拒绝。\n- `environments`：省略（或传 `null`）表示不变；传入列表即整体替换——空列表表示清除限制、恢复为所有环境。\n- 响应为更新后的服务器。若修改了连接相关字段，会清除工具列表缓存并在后台重新拉取。\n- 每次调用都会记录到账户审计日志。\n",
+          "href": "/zh/api-reference/ai-sre/mcp-servers/mcp-write-server-update",
           "metadata": {
-            "sidebarTitle": "查询 MCP 服务器列表"
+            "sidebarTitle": "更新 MCP 服务器"
           }
-        }
-      }
-    },
-    "/safari/mcp/server/update": {
-      "post": {
-        "description": "更新 MCP 服务器配置；省略字段表示不变。",
-        "operationId": "mcp-write-server-update",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "description": "Query Prometheus metrics, alerts, and rules.",
-                "server_id": "mcp_4kP9wQ2nLceRtY7uVb3xA1"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/MCPServerUpdateRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "account_id": 10023,
-                    "auth_mode": "shared",
-                    "call_timeout": 60,
-                    "can_edit": true,
-                    "connect_timeout": 10,
-                    "created_at": 1716960000000,
-                    "created_by": 80011,
-                    "description": "Query Prometheus metrics, alerts, and rules.",
-                    "environments": [],
-                    "server_id": "mcp_4kP9wQ2nLceRtY7uVb3xA1",
-                    "server_name": "prometheus",
-                    "status": "enabled",
-                    "team_id": 0,
-                    "transport": "streamable-http",
-                    "updated_at": 1717046400000,
-                    "url": "https://mcp.example.com/prometheus"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/ResponseEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/MCPServerItem"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "server_id": "mcp_4kP9wQ2nLceRtY7uVb3xA1",
+                    "account_id": 10023,
+                    "team_id": 0,
+                    "can_edit": true,
+                    "environments": [],
+                    "server_name": "prometheus",
+                    "description": "Query Prometheus metrics, alerts, and rules.",
+                    "transport": "streamable-http",
+                    "url": "https://mcp.example.com/prometheus",
+                    "headers": {
+                      "Authorization": "Bear****f2c1"
+                    },
+                    "status": "enabled",
+                    "connect_timeout": 0,
+                    "call_timeout": 0,
+                    "auth_mode": "shared",
+                    "created_by": 80011,
+                    "created_at": 1716960000000,
+                    "updated_at": 1717046400000
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -58125,68 +60114,68 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/MCPServerUpdateRequest"
+              },
+              "example": {
+                "server_id": "mcp_4kP9wQ2nLceRtY7uVb3xA1",
+                "description": "Query Prometheus metrics, alerts, and rules."
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/session/delete": {
+      "post": {
+        "operationId": "session-write-delete",
+        "summary": "删除会话",
+        "description": "软删除会话，并一并删除其子智能体会话和会话中展示过的文件。",
+        "tags": [
+          "AI SRE/会话"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "更新 MCP 服务器",
-        "tags": [
-          "AI SRE/MCP 服务器"
-        ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **MCP 管理**（`ai-sre`） |\n\n## 使用说明\n\n- `env`/`headers` 中的脱敏密钥会被保留——回传脱敏值不会覆盖已存储的真实密钥。\n- `environments` 是三态部分更新字段：省略（null）表示保持不变；传入列表即整体设置——空列表表示清除限制、恢复为所有环境。\n- 变更 `team_id` 需要对目标团队具有重新分配权限；若 `environments` 未随之修改，则当前环境列表在新团队下仍须对调用者可选，否则更新会被拒绝。\n- 每次调用都会记录到账户审计日志。\n",
-          "href": "/zh/api-reference/ai-sre/mcp-servers/mcp-write-server-update",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 需要会话的管理权限：个人会话（`team_id` = 0）仅创建者可删除；团队会话由创建者或所属团队成员删除。账户所有者和管理员没有豁免，其他调用者会收到 `AccessDenied`。\n- `session_id` 不存在或已删除时返回 `ResourceNotFound`。\n- 删除前会尽力停止该会话仍在运行的后台进程（后台命令、monitor）；停止失败不会阻止删除。\n- 子智能体会话和会话中展示过的文件在同一事务内删除；存储中的文件内容随后尽力清理。\n",
+          "href": "/zh/api-reference/ai-sre/sessions/session-write-delete",
           "metadata": {
-            "sidebarTitle": "更新 MCP 服务器"
+            "sidebarTitle": "删除会话"
           }
-        }
-      }
-    },
-    "/safari/session/delete": {
-      "post": {
-        "description": "按 ID 删除会话。",
-        "operationId": "session-write-delete",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "session_id": "sess_f8oDvqiG64uur6sBNsTc4u"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/SessionDeleteRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": null,
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/ResponseEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "description": "成功时恒为 null。",
-                          "type": "null"
+                          "type": "null",
+                          "description": "成功时不返回该字段，响应体只有 `request_id`。"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -58204,53 +60193,52 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/SessionDeleteRequest"
+              },
+              "example": {
+                "session_id": "sess_f8oDvqiG64uur6sBNsTc4u"
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/session/export": {
+      "post": {
+        "operationId": "session-read-export",
+        "summary": "导出会话记录",
+        "description": "以换行分隔的 JSON（NDJSON）流式导出会话的完整事件记录。",
+        "tags": [
+          "AI SRE/会话"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "删除会话",
-        "tags": [
-          "AI SRE/会话"
-        ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 个人会话仅创建者可删除；团队会话可由创建者、账户管理员或所属团队成员删除。\n- 这是软删除：会级联删除子智能体会话及其已展示的文件；底层 S3/MinIO 对象在事务提交后尽力清理，部分失败时可能残留孤立对象。\n",
-          "href": "/zh/api-reference/ai-sre/sessions/session-write-delete",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/天**；**200 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 个人会话仅创建者可导出；团队会话同一账户内的任何成员都可导出。分享链接不授予导出权限。会话不存在或已删除时返回 `ResourceNotFound`。\n- 响应为 `application/x-ndjson`，请逐行解析并写入文件，不要把整个响应体读进内存。\n- 第一行始终是 `session_meta` 对象。之后每行的 `type` 为 `user_message`、`system_reminder`、`agent_text`、`tool_call`、`subagent_dispatch`、`llm_call`、`final_answer` 或 `session_fork` 之一。\n- `include_subagents=true` 时，每条 `subagent_dispatch` 行之后紧跟对应子会话的事件流，以子会话自己的 `session_meta` 开头。\n- 请求 60 秒超时；非常大的会话可能无法在此时间内导出完毕。\n- 若开始输出后导出失败，响应体以一行 `{\"type\":\"error\",\"content\":\"...\"}` 结束，而不是错误信封——检查最后一行即可判断是否被截断。\n",
+          "href": "/zh/api-reference/ai-sre/sessions/session-read-export",
           "metadata": {
-            "sidebarTitle": "删除会话"
+            "sidebarTitle": "导出会话记录"
           }
-        }
-      }
-    },
-    "/safari/session/export": {
-      "post": {
-        "description": "以换行分隔的 JSON（NDJSON）流式导出会话的完整事件记录。",
-        "operationId": "session-read-export",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "include_subagents": false,
-                "session_id": "sess_f8oDvqiG64uur6sBNsTc4u"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/SessionExportRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "流式 NDJSON（application/x-ndjson）。每行一个 JSON 对象，以换行结束。第一行始终为 `session_meta` 信封，其后为会话事件。",
             "content": {
               "application/x-ndjson": {
                 "schema": {
-                  "description": "换行分隔的 JSON 流。请逐行解析，切勿缓冲整个响应体。",
-                  "type": "string"
+                  "type": "string",
+                  "description": "换行分隔的 JSON 流。请逐行解析，切勿缓冲整个响应体。"
                 }
               }
-            },
-            "description": "流式 NDJSON（application/x-ndjson）。每行一个 JSON 对象，以换行结束。第一行始终为 `session_meta` 信封，其后为会话事件。"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -58268,138 +60256,139 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/SessionExportRequest"
+              },
+              "example": {
+                "session_id": "sess_f8oDvqiG64uur6sBNsTc4u",
+                "include_subagents": false
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/session/get": {
+      "post": {
+        "operationId": "session-read-info",
+        "summary": "查看会话详情",
+        "description": "查看单个会话，并返回其最近事件的一页（向更早方向分页）。",
+        "tags": [
+          "AI SRE/会话"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "导出会话记录",
-        "tags": [
-          "AI SRE/会话"
-        ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/天**；**200 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 个人会话仅创建者可导出；团队会话允许同一账户内持有 `session_id` 的调用者导出。\n- 响应为 `application/x-ndjson`——请逐行解析并写入文件，切勿将整段记录读入内存。\n- 第一行始终为 `session_meta` 信封；`include_subagents=true` 会在派发行后内联各子会话的事件流。\n- 请求存在 60 秒的执行超时上限；非常大的会话可能无法在该时间内导出完成。\n- 若流在中途失败，响应会以一行 JSON 错误行结束，而非规范的错误信封（响应头已发出）——可通过检测该结尾行判断记录是否被截断。\n",
-          "href": "/zh/api-reference/ai-sre/sessions/session-read-export",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 个人会话仅创建者可读，或持有有效 `share_token` 的调用者只读访问。团队会话同一账户内的任何成员都可读。会话不存在、已删除或无权读取时返回 `ResourceNotFound`。\n- `events` 为最新的一页，按时间升序排列。如需更早的历史，把返回的 `search_after_ctx` 传回；游标格式错误返回 `InvalidParameter`。\n- 每页条数取 `limit`，其次 `num_recent_events`，都未设置时为 100（最大 1000）。内部控制事件不会返回，因此一页可能少于请求的条数。\n- `current_turn_*` 字段仅在 `is_running` 为 true 时填充。本接口中 `has_unread` 恒为 `false`、`pinned_at` 恒为 `0`；如需这两项请使用 `POST /safari/session/list`。\n- `pending_messages` 列出排在当前运行轮次之后的消息；没有排队消息时为空数组。\n",
+          "href": "/zh/api-reference/ai-sre/sessions/session-read-info",
           "metadata": {
-            "sidebarTitle": "导出会话记录"
+            "sidebarTitle": "查看会话详情"
           }
-        }
-      }
-    },
-    "/safari/session/get": {
-      "post": {
-        "description": "查看单个会话，并返回其最近事件的一页（向更早方向分页）。",
-        "operationId": "session-read-info",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "num_recent_events": 50,
-                "session_id": "sess_f8oDvqiG64uur6sBNsTc4u"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/SessionGetRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ResponseEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/SessionGetResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
+                    "session": {
+                      "session_id": "sess_f8oDvqiG64uur6sBNsTc4u",
+                      "session_name": "Investigate cloud-assistant first heartbeat",
+                      "app_name": "ai-sre",
+                      "entry_kind": "web",
+                      "person_id": "3790925372131",
+                      "team_id": 0,
+                      "is_mine": true,
+                      "can_view": true,
+                      "can_continue": true,
+                      "can_manage": true,
+                      "can_fork": true,
+                      "access_source": "owner",
+                      "share_enabled": true,
+                      "share_version": 3,
+                      "shared_at": 1780367971000,
+                      "shared_by": 3790925372131,
+                      "status": "enabled",
+                      "incognito": false,
+                      "created_at": 1780367971228,
+                      "updated_at": 1780367993457,
+                      "token_usage": {
+                        "input_tokens": 14948,
+                        "cached_tokens": 11520,
+                        "output_tokens": 888,
+                        "reasoning_tokens": 351
+                      },
+                      "current_context_tokens": 14948,
+                      "context_window": 131072,
+                      "archived_at": 0,
+                      "pinned_at": 0,
+                      "last_event_at": 1780367992649,
+                      "is_running": false,
+                      "standing_tasks": 0,
+                      "has_unread": false,
+                      "current_turn_started_at": 1780367971241,
+                      "current_turn_active_ms": 21408,
+                      "current_turn_wait_ms": 0,
+                      "current_turn_tokens": 0
+                    },
                     "events": [
                       {
-                        "author": "user",
-                        "created_at": 1780367971241,
                         "event_id": "evt_3aZQ9p",
-                        "partial": false,
                         "session_id": "sess_f8oDvqiG64uur6sBNsTc4u",
+                        "author": "user",
+                        "partial": false,
+                        "turn_complete": false,
                         "status": "normal",
-                        "turn_complete": false
+                        "created_at": 1780367971241
                       },
                       {
+                        "event_id": "evt_7bWk2r",
+                        "session_id": "sess_f8oDvqiG64uur6sBNsTc4u",
                         "author": "ai-sre",
                         "content": {
+                          "role": "model",
                           "parts": [
                             {
                               "text": "..."
                             }
-                          ],
-                          "role": "model"
+                          ]
                         },
-                        "created_at": 1780367992649,
-                        "event_id": "evt_7bWk2r",
                         "partial": false,
-                        "session_id": "sess_f8oDvqiG64uur6sBNsTc4u",
+                        "turn_complete": true,
                         "status": "normal",
-                        "turn_complete": true
+                        "created_at": 1780367992649
                       }
                     ],
                     "has_more_older": false,
-                    "session": {
-                      "access_source": "manager",
-                      "app_name": "ai-sre",
-                      "archived_at": 0,
-                      "can_continue": true,
-                      "can_fork": true,
-                      "can_manage": true,
-                      "can_view": true,
-                      "context_window": 0,
-                      "created_at": 1780367971228,
-                      "current_context_tokens": 14948,
-                      "current_turn_active_ms": 0,
-                      "current_turn_started_at": 0,
-                      "current_turn_tokens": 0,
-                      "current_turn_wait_ms": 0,
-                      "entry_kind": "web",
-                      "has_unread": true,
-                      "incognito": false,
-                      "is_mine": false,
-                      "is_running": false,
-                      "last_event_at": 1780367992649,
-                      "person_id": "3790925372131",
-                      "pinned_at": 0,
-                      "session_id": "sess_f8oDvqiG64uur6sBNsTc4u",
-                      "session_name": "Investigate cloud-assistant first heartbeat",
-                      "share_enabled": true,
-                      "share_version": 3,
-                      "shared_at": 1780367971000,
-                      "shared_by": 3790925372131,
-                      "status": "enabled",
-                      "team_id": 0,
-                      "token_usage": {
-                        "cached_tokens": 11520,
-                        "input_tokens": 14948,
-                        "output_tokens": 888,
-                        "reasoning_tokens": 351
-                      },
-                      "updated_at": 1780367993457
-                    },
-                    "suggest_init": false
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/ResponseEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/SessionGetResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                    "pending_messages": []
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -58417,114 +60406,113 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/SessionGetRequest"
+              },
+              "example": {
+                "session_id": "sess_f8oDvqiG64uur6sBNsTc4u",
+                "num_recent_events": 50
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/session/list": {
+      "post": {
+        "operationId": "session-read-list",
+        "summary": "查询会话列表",
+        "description": "分页查询调用者可见的智能体会话，可按应用、入口、归档状态与团队过滤。",
+        "tags": [
+          "AI SRE/会话"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "查看会话详情",
-        "tags": [
-          "AI SRE/会话"
-        ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 个人会话仅创建者可读；团队会话允许同一账户内持有 `session_id` 的调用者读取。\n- 使用上一次响应的 `search_after_ctx` 翻阅更早的历史。\n- `limit`（或旧版 `num_recent_events`）限制事件页大小；默认 100，最大 1000。\n- 格式错误的 `search_after_ctx` 会在触发任何数据库查询前立即返回 400。\n- `current_turn_*` 字段仅在会话 `is_running` 时才会填充；`suggest_init` 与 `session/list` 使用同一个账户级引导提示。\n",
-          "href": "/zh/api-reference/ai-sre/sessions/session-read-info",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 分页使用 `p`/`limit`（默认 20，最大 100）。调用者置顶且符合过滤条件的会话会额外插在第 1 页最前面（不占 `limit`），不会出现在后续页，也不计入 `total`。\n- `scope=all` 返回调用者创建的会话，以及绑定到调用者所在团队的会话。团队以实际成员关系为准，对所有角色一致；账户所有者和管理员在此看不到其他团队的会话。\n- `team_ids`、`person_ids`、`entry_kinds` 只会收窄可见范围。无痕会话永不列出；子智能体会话仅在 `include_subagent_sessions=true` 时返回。\n- `app_name=ai-sre` 时调用成员必须持有 AI SRE 席位，否则请求返回无许可证错误。\n- `creator_name`、`has_unread`、`pinned_at` 按调用者计算。`current_turn_*` 字段与 `context_window` 恒为 `0`，且不返回 `state`、`bound_environment`、`context_resolved`、`automation`、`has_open_tasks`；如需这些字段请使用 `POST /safari/session/get`。\n",
+          "href": "/zh/api-reference/ai-sre/sessions/session-read-list",
           "metadata": {
-            "sidebarTitle": "查看会话详情"
+            "sidebarTitle": "查询会话列表"
           }
-        }
-      }
-    },
-    "/safari/session/list": {
-      "post": {
-        "description": "分页查询调用者可见的智能体会话，可按应用、入口、归档状态与团队过滤。",
-        "operationId": "session-read-list",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "app_name": "ai-sre",
-                "limit": 2,
-                "orderby": "updated_at",
-                "scope": "all"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/SessionListRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ResponseEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/SessionListResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
+                    "total": 988,
                     "sessions": [
                       {
-                        "access_source": "manager",
+                        "session_id": "sess_f8oDvqiG64uur6sBNsTc4u",
+                        "session_name": "Investigate cloud-assistant first heartbeat",
                         "app_name": "ai-sre",
-                        "archived_at": 0,
-                        "can_continue": true,
-                        "can_fork": true,
-                        "can_manage": true,
-                        "can_view": true,
-                        "context_window": 0,
-                        "created_at": 1780367971228,
-                        "current_context_tokens": 14948,
-                        "current_turn_active_ms": 0,
-                        "current_turn_started_at": 0,
-                        "current_turn_tokens": 0,
-                        "current_turn_wait_ms": 0,
                         "entry_kind": "web",
-                        "has_unread": true,
-                        "incognito": false,
-                        "is_mine": false,
-                        "is_running": false,
-                        "last_event_at": 1780367992649,
                         "person_id": "3790925372131",
-                        "pinned_at": 0,
-                        "session_id": "sess_f8oDvqiG64uur6sBNsTc4u",
-                        "session_name": "Investigate cloud-assistant first heartbeat",
+                        "creator_name": "Alice Chen",
+                        "team_id": 0,
+                        "is_mine": true,
+                        "can_view": true,
+                        "can_continue": true,
+                        "can_manage": true,
+                        "can_fork": true,
+                        "access_source": "owner",
                         "share_enabled": true,
                         "share_version": 3,
                         "shared_at": 1780367971000,
                         "shared_by": 3790925372131,
                         "status": "enabled",
-                        "team_id": 0,
+                        "incognito": false,
+                        "created_at": 1780367971228,
+                        "updated_at": 1780367993457,
                         "token_usage": {
-                          "cached_tokens": 11520,
                           "input_tokens": 14948,
+                          "cached_tokens": 11520,
                           "output_tokens": 888,
                           "reasoning_tokens": 351
                         },
-                        "updated_at": 1780367993457
+                        "current_context_tokens": 14948,
+                        "context_window": 0,
+                        "archived_at": 0,
+                        "pinned_at": 0,
+                        "last_event_at": 1780367992649,
+                        "is_running": false,
+                        "standing_tasks": 0,
+                        "has_unread": true,
+                        "current_turn_started_at": 0,
+                        "current_turn_active_ms": 0,
+                        "current_turn_wait_ms": 0,
+                        "current_turn_tokens": 0
                       }
-                    ],
-                    "suggest_init": false,
-                    "total": 988
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/ResponseEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/SessionListResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                    ]
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -58542,68 +60530,70 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/SessionListRequest"
+              },
+              "example": {
+                "app_name": "ai-sre",
+                "limit": 2,
+                "orderby": "updated_at",
+                "scope": "all"
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/skill/delete": {
+      "post": {
+        "operationId": "skill-write-delete",
+        "summary": "删除技能",
+        "description": "软删除技能，智能体不再加载它，其名称可被重新使用。",
+        "tags": [
+          "AI SRE/技能"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "查询会话列表",
-        "tags": [
-          "AI SRE/会话"
-        ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 分页使用 `p`/`limit`（最大 100）；`scope` 默认 `all`。\n- `all` 返回调用者自己的个人会话，以及调用者可访问团队的团队会话；账户管理员可见所有团队会话，但不可见他人的个人会话。\n- `team_ids` 只会收窄可见集合，不会扩大访问范围。\n- `is_running` 反映实时运行集合；`has_unread` 按调用者各自计算；`current_turn_*` 字段在此接口恒为 0 —— 仅 `session/get` 会在会话运行时计算它们。\n- `suggest_init` 是账户级的引导提示（仅当账户在任何范围内都没有知识时为 true），与列表过滤条件无关。\n",
-          "href": "/zh/api-reference/ai-sre/sessions/session-read-list",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **Skill 管理**（`ai-sre`） |\n\n## 使用说明\n\n- 需要技能的编辑权限：账户级技能（`team_id` = 0）仅账户所有者和管理员可编辑；团队技能仅该团队成员可编辑（所有者和管理员没有豁免）。否则返回 `AccessDenied`。\n- 软删除：技能被改名并从所有接口中隐藏，原名称在其作用域内可被重新使用；已存储的压缩包不会删除。\n- `skill_id` 不存在或已删除时返回 `ResourceNotFound`。\n- 每次调用都会记录到账户审计日志。\n",
+          "href": "/zh/api-reference/ai-sre/skills/skill-write-delete",
           "metadata": {
-            "sidebarTitle": "查询会话列表"
+            "sidebarTitle": "删除技能"
           }
-        }
-      }
-    },
-    "/safari/skill/delete": {
-      "post": {
-        "description": "按 ID 删除技能。",
-        "operationId": "skill-write-delete",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "skill_id": "skill_8s7Hn2kLpQ3xYbVc4Wd2m"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/SkillDeleteRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": null,
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/ResponseEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "description": "成功时恒为 null。",
-                          "type": "null"
+                          "type": "null",
+                          "description": "成功时不返回该字段，响应体只有 `request_id`。"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -58621,68 +60611,67 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/SkillDeleteRequest"
+              },
+              "example": {
+                "skill_id": "skill_8s7Hn2kLpQ3xYbVc4Wd2m"
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/skill/disable": {
+      "post": {
+        "operationId": "skill-write-disable",
+        "summary": "禁用技能",
+        "description": "禁用已启用的技能，使智能体不再加载。",
+        "tags": [
+          "AI SRE/技能"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "删除技能",
-        "tags": [
-          "AI SRE/技能"
-        ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **Skill 管理**（`ai-sre`） |\n\n## 使用说明\n\n- 仅为软删除：将 `status` 置为 `deleted` 并重命名该行以释放原名称供复用；技能的压缩包不会从对象存储中删除。\n- 对已删除或不存在的 `skill_id` 再次删除会返回 `ResourceNotFound`，因为查找逻辑在执行删除前就已排除已删除的行。\n- 每次调用都会记录到账户审计日志。\n",
-          "href": "/zh/api-reference/ai-sre/skills/skill-write-delete",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **Skill 管理**（`ai-sre`） |\n\n## 使用说明\n\n- 需要技能的编辑权限：账户级技能（`team_id` = 0）仅账户所有者和管理员可编辑；团队技能仅该团队成员可编辑（所有者和管理员没有豁免）。否则返回 `AccessDenied`。\n- 仅可禁用 `enabled` 状态的技能；对已禁用的技能再次禁用返回 `InvalidParameter`。\n- 每次调用都会记录到账户审计日志。\n",
+          "href": "/zh/api-reference/ai-sre/skills/skill-write-disable",
           "metadata": {
-            "sidebarTitle": "删除技能"
+            "sidebarTitle": "禁用技能"
           }
-        }
-      }
-    },
-    "/safari/skill/disable": {
-      "post": {
-        "description": "禁用已启用的技能，使智能体不再加载。",
-        "operationId": "skill-write-disable",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "skill_id": "skill_8s7Hn2kLpQ3xYbVc4Wd2m"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/SkillStatusRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": null,
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/ResponseEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "description": "成功时恒为 null。",
-                          "type": "null"
+                          "type": "null",
+                          "description": "成功时不返回该字段，响应体只有 `request_id`。"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -58700,68 +60689,67 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "security": [
-          {
-            "AppKeyAuth": []
-          }
-        ],
-        "summary": "禁用技能",
-        "tags": [
-          "AI SRE/技能"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **Skill 管理**（`ai-sre`） |\n\n## 使用说明\n\n- 仅可禁用 `enabled` 状态的技能；已禁用的技能会返回 `InvalidParameter`。\n- 每次调用都会记录到账户审计日志。\n",
-          "href": "/zh/api-reference/ai-sre/skills/skill-write-disable",
-          "metadata": {
-            "sidebarTitle": "禁用技能"
-          }
-        }
-      }
-    },
-    "/safari/skill/enable": {
-      "post": {
-        "description": "启用已禁用的技能，使智能体可加载。",
-        "operationId": "skill-read-enable",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {
-                "skill_id": "skill_8s7Hn2kLpQ3xYbVc4Wd2m"
-              },
               "schema": {
                 "$ref": "#/components/schemas/SkillStatusRequest"
+              },
+              "example": {
+                "skill_id": "skill_8s7Hn2kLpQ3xYbVc4Wd2m"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/safari/skill/enable": {
+      "post": {
+        "operationId": "skill-read-enable",
+        "summary": "启用技能",
+        "description": "启用已禁用的技能，使智能体可加载。",
+        "tags": [
+          "AI SRE/技能"
+        ],
+        "security": [
+          {
+            "AppKeyAuth": []
+          }
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **Skill 管理**（`ai-sre`） |\n\n## 使用说明\n\n- 需要技能的编辑权限：账户级技能（`team_id` = 0）仅账户所有者和管理员可编辑；团队技能仅该团队成员可编辑（所有者和管理员没有豁免）。否则返回 `AccessDenied`。\n- 仅可启用 `disabled` 状态的技能；对已启用的技能再次启用返回 `InvalidParameter`。\n- 每次调用都会记录到账户审计日志。\n",
+          "href": "/zh/api-reference/ai-sre/skills/skill-read-enable",
+          "metadata": {
+            "sidebarTitle": "启用技能"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": null,
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/ResponseEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "description": "成功时恒为 null。",
-                          "type": "null"
+                          "type": "null",
+                          "description": "成功时不返回该字段，响应体只有 `request_id`。"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -58779,92 +60767,92 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/SkillStatusRequest"
+              },
+              "example": {
+                "skill_id": "skill_8s7Hn2kLpQ3xYbVc4Wd2m"
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/skill/get": {
+      "post": {
+        "operationId": "skill-read-get",
+        "summary": "查看技能详情",
+        "description": "查看单个技能，包含完整的 SKILL.md 内容。",
+        "tags": [
+          "AI SRE/技能"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "启用技能",
-        "tags": [
-          "AI SRE/技能"
-        ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **Skill 管理**（`ai-sre`） |\n\n## 使用说明\n\n- 仅可启用 `disabled` 状态的技能；已启用的技能会返回 `InvalidParameter`。\n- 每次调用都会记录到账户审计日志。\n",
-          "href": "/zh/api-reference/ai-sre/skills/skill-read-enable",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 账户内任何成员都可以按 ID 读取账户中的任意技能，包括自己不在的团队的技能；`can_edit` 表示调用者能否修改它。\n- `skill_id` 不存在或已删除时返回 `ResourceNotFound`。\n- 本接口不计算 `update_available`，恒为 `false`；如需查看市场更新请使用 `POST /safari/skill/list`。\n",
+          "href": "/zh/api-reference/ai-sre/skills/skill-read-get",
           "metadata": {
-            "sidebarTitle": "启用技能"
+            "sidebarTitle": "查看技能详情"
           }
-        }
-      }
-    },
-    "/safari/skill/get": {
-      "post": {
-        "description": "查看单个技能，包含完整的 SKILL.md 内容。",
-        "operationId": "skill-read-get",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "skill_id": "skill_8s7Hn2kLpQ3xYbVc4Wd2m"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/SkillGetRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ResponseEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/SkillItem"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
-                    "account_id": 10023,
-                    "author": "sre-team",
-                    "can_edit": true,
-                    "content": "---\nname: k8s-triage\ndescription: ...\n---\n# Triage steps",
-                    "created_at": 1716960000000,
-                    "created_by": 80011,
-                    "description": "Diagnose unhealthy Kubernetes workloads from cluster events and pod logs.",
-                    "description_en": "Diagnose unhealthy Kubernetes workloads from cluster events and pod logs.",
-                    "is_modified": false,
                     "skill_id": "skill_8s7Hn2kLpQ3xYbVc4Wd2m",
+                    "account_id": 10023,
+                    "team_id": 0,
                     "skill_name": "k8s-triage",
-                    "status": "enabled",
+                    "description": "Diagnose unhealthy Kubernetes workloads from cluster events and pod logs.",
+                    "version": "1.2.0",
                     "tags": [
                       "kubernetes",
                       "triage"
                     ],
-                    "team_id": 0,
+                    "author": "sre-team",
                     "tools": [
                       "bash",
                       "mcp:prometheus/query"
                     ],
-                    "update_available": false,
+                    "status": "enabled",
+                    "created_by": 80011,
+                    "created_at": 1716960000000,
                     "updated_at": 1717046400000,
-                    "version": "1.2.0"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/ResponseEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/SkillItem"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                    "can_edit": true,
+                    "update_available": false,
+                    "is_modified": false,
+                    "description_en": "Diagnose unhealthy Kubernetes workloads from cluster events and pod logs.",
+                    "content": "---\nname: k8s-triage\ndescription: ...\n---\n# Triage steps"
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -58872,6 +60860,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -58879,97 +60870,95 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/SkillGetRequest"
+              },
+              "example": {
+                "skill_id": "skill_8s7Hn2kLpQ3xYbVc4Wd2m"
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/skill/list": {
+      "post": {
+        "operationId": "skill-read-list",
+        "summary": "查询技能列表",
+        "description": "分页查询调用者在账户与团队范围内可见的 AI SRE 技能。",
+        "tags": [
+          "AI SRE/技能"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "查看技能详情",
-        "tags": [
-          "AI SRE/技能"
-        ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 若技能不存在或已被删除，返回 `ResourceNotFound`。\n- `can_edit` 反映团队成员关系，但读取本身不受团队限制，任意调用者均可访问。\n",
-          "href": "/zh/api-reference/ai-sre/skills/skill-read-get",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 返回账户级技能，以及调用者所在团队的技能，按 `skill_name` 升序排列。团队以实际成员关系为准，对所有角色一致；不属于调用者的 `team_ids` 会被静默忽略。\n- `scope` 会覆盖 `include_account`：`account` 只返回账户级技能，`team` 只返回调用者所在团队的技能。\n- 列表行不返回 `content`；如需正文请调用 `POST /safari/skill/get`。\n- `update_available` 将每个市场安装的技能与当前目录比对；目录加载失败时所有行均为 `false`，请求本身不会失败。\n",
+          "href": "/zh/api-reference/ai-sre/skills/skill-read-list",
           "metadata": {
-            "sidebarTitle": "查看技能详情"
+            "sidebarTitle": "查询技能列表"
           }
-        }
-      }
-    },
-    "/safari/skill/list": {
-      "post": {
-        "description": "分页查询调用者在账户与团队范围内可见的 AI SRE 技能。",
-        "operationId": "skill-read-list",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "include_account": true,
-                "limit": 20,
-                "p": 1
-              },
-              "schema": {
-                "$ref": "#/components/schemas/SkillListRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ResponseEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/SkillListResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
+                    "total": 1,
                     "skills": [
                       {
-                        "account_id": 10023,
-                        "author": "sre-team",
-                        "can_edit": true,
-                        "created_at": 1716960000000,
-                        "created_by": 80011,
-                        "description": "Diagnose unhealthy Kubernetes workloads from cluster events and pod logs.",
-                        "is_modified": false,
                         "skill_id": "skill_8s7Hn2kLpQ3xYbVc4Wd2m",
+                        "account_id": 10023,
+                        "team_id": 0,
                         "skill_name": "k8s-triage",
-                        "status": "enabled",
+                        "description": "Diagnose unhealthy Kubernetes workloads from cluster events and pod logs.",
+                        "version": "1.2.0",
                         "tags": [
                           "kubernetes",
                           "triage"
                         ],
-                        "team_id": 0,
+                        "author": "sre-team",
                         "tools": [
                           "bash",
                           "mcp:prometheus/query"
                         ],
-                        "update_available": false,
+                        "status": "enabled",
+                        "created_by": 80011,
+                        "created_at": 1716960000000,
                         "updated_at": 1717046400000,
-                        "version": "1.2.0"
+                        "can_edit": true,
+                        "update_available": false,
+                        "is_modified": false
                       }
-                    ],
-                    "total": 1
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/ResponseEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/SkillListResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                    ]
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -58977,6 +60966,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -58984,91 +60976,92 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/SkillListRequest"
+              },
+              "example": {
+                "p": 1,
+                "limit": 20,
+                "include_account": true
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/skill/update": {
+      "post": {
+        "operationId": "skill-write-update",
+        "summary": "更新技能",
+        "description": "更新技能的描述信息或重新分配团队范围。",
+        "tags": [
+          "AI SRE/技能"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "查询技能列表",
-        "tags": [
-          "AI SRE/技能"
-        ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 列表行中省略 `content` 字段；如需正文请单独查询某个技能。\n- `scope` 用于选择 `all`（默认）、仅 `account`、或仅 `team`，会覆盖 `include_account`；非管理员请求特定 `team_ids` 时会被静默过滤为其所属的团队。\n- `update_available` 每次调用会与市场目录比对一次；若目录加载失败，仅会隐藏该徽标，不会导致请求失败。\n",
-          "href": "/zh/api-reference/ai-sre/skills/skill-read-list",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **Skill 管理**（`ai-sre`） |\n\n## 使用说明\n\n- 需要技能的编辑权限：账户级技能（`team_id` = 0）仅账户所有者和管理员可编辑；团队技能仅该团队成员可编辑（所有者和管理员没有豁免）。否则返回 `AccessDenied`。\n- 只能修改 `description`、`description_en` 和 `team_id`；技能正文需上传新的压缩包修改。\n- `description` 仅在非空时修改，因此无法清空。`description_en` 只要传入就会修改；传空字符串即清空。\n- 移到团队（`team_id` > 0）要求调用者属于目标团队；移到账户级（`team_id` = 0）要求账户所有者或管理员。从市场安装的技能只能移到账户级。目标作用域内名称冲突时返回 `InvalidParameter`。\n- 每次调用都会记录到账户审计日志。\n",
+          "href": "/zh/api-reference/ai-sre/skills/skill-write-update",
           "metadata": {
-            "sidebarTitle": "查询技能列表"
+            "sidebarTitle": "更新技能"
           }
-        }
-      }
-    },
-    "/safari/skill/update": {
-      "post": {
-        "description": "更新技能的描述信息或重新分配团队范围。",
-        "operationId": "skill-write-update",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "description": "Updated triage runbook.",
-                "skill_id": "skill_8s7Hn2kLpQ3xYbVc4Wd2m"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/SkillUpdateRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ResponseEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/SkillItem"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
-                    "account_id": 10023,
-                    "author": "sre-team",
-                    "can_edit": true,
-                    "created_at": 1716960000000,
-                    "created_by": 80011,
-                    "description": "Updated triage runbook.",
-                    "is_modified": false,
                     "skill_id": "skill_8s7Hn2kLpQ3xYbVc4Wd2m",
+                    "account_id": 10023,
+                    "team_id": 0,
                     "skill_name": "k8s-triage",
-                    "status": "enabled",
+                    "description": "Updated triage runbook.",
+                    "version": "1.2.0",
                     "tags": [
                       "kubernetes",
                       "triage"
                     ],
-                    "team_id": 0,
+                    "author": "sre-team",
                     "tools": [
                       "bash",
                       "mcp:prometheus/query"
                     ],
-                    "update_available": false,
+                    "status": "enabled",
+                    "created_by": 80011,
+                    "created_at": 1716960000000,
                     "updated_at": 1717046400000,
-                    "version": "1.2.0"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/ResponseEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/SkillItem"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                    "can_edit": true,
+                    "update_available": false,
+                    "is_modified": false
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -59086,91 +61079,183 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/SkillUpdateRequest"
+              },
+              "example": {
+                "skill_id": "skill_8s7Hn2kLpQ3xYbVc4Wd2m",
+                "description": "Updated triage runbook."
+              }
+            }
+          }
+        }
+      }
+    },
+    "/safari/skill/upload": {
+      "post": {
+        "operationId": "skill-write-upload",
+        "summary": "上传技能",
+        "description": "上传技能压缩包（.skill/.zip/.tar.gz/.tgz）以创建或覆盖技能。",
+        "tags": [
+          "AI SRE/技能"
+        ],
         "security": [
           {
             "AppKeyAuth": []
           }
         ],
-        "summary": "更新技能",
-        "tags": [
-          "AI SRE/技能"
-        ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **Skill 管理**（`ai-sre`） |\n\n## 使用说明\n\n- 仅 `description`、`description_en` 与 `team_id` 可编辑；技能正文需通过重新上传修改。\n- `description` 仅在非空时更新 —— 无法通过该字段清空；`description_en` 可为 null，传入空字符串即可显式清空。\n- 将 `team_id` 重新分配到不同团队时，除编辑权限外还会触发第二重授权检查，验证调用者是否可将资源指派到目标团队。\n- 每次调用都会记录到账户审计日志。\n",
-          "href": "/zh/api-reference/ai-sre/skills/skill-write-update",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **30 次/分钟**；**3 次/秒** |\n| 权限要求 | **Skill 管理**（`ai-sre`） |\n\n## 使用说明\n\n- 以 `multipart/form-data` 提交，包含 `file` 部分。支持 `.skill`、`.zip`、`.tar.gz`、`.tgz`，最大 100 MB；压缩包必须包含 frontmatter 合法的 `SKILL.md`，且声明的每个工具都必须存在。\n- 不设置 `replace` 时在 `team_id` 中新建技能；该作用域内已有同名技能时返回 `InvalidParameter`。\n- `replace=true` 且不带 `skill_id` 时覆盖 `team_id` 中的同名技能（不存在则新建）。`replace=true` 且带 `skill_id` 时覆盖该技能；压缩包中的技能名称必须与之一致，否则返回 `InvalidParameter`。\n- 在 `team_id` 中新建要求调用者属于该团队（`team_id` = 0 要求账户所有者或管理员）。覆盖要求对已有技能有编辑权限。\n- 覆盖时保留 `skill_id` 和作用域，把 `status` 重置为 `enabled`，并把 `is_modified` 置为 `true`。响应中 `can_edit` 恒为 `true`。\n- 每次调用都会记录到账户审计日志。\n",
+          "href": "/zh/api-reference/ai-sre/skills/skill-write-upload",
           "metadata": {
-            "sidebarTitle": "更新技能"
+            "sidebarTitle": "上传技能"
           }
-        }
-      }
-    },
-    "/safari/skill/upload": {
-      "post": {
-        "description": "上传技能压缩包（.skill/.zip/.tar.gz/.tgz）以创建或覆盖技能。",
-        "operationId": "skill-write-upload",
-        "requestBody": {
-          "content": {
-            "multipart/form-data": {
-              "example": {
-                "replace": false,
-                "team_id": 0
-              },
-              "schema": {
-                "$ref": "#/components/schemas/SkillUploadRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ResponseEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/SkillItem"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
-                    "account_id": 10023,
-                    "author": "sre-team",
-                    "can_edit": true,
-                    "created_at": 1716960000000,
-                    "created_by": 80011,
-                    "description": "Diagnose unhealthy Kubernetes workloads from cluster events and pod logs.",
-                    "is_modified": false,
                     "skill_id": "skill_8s7Hn2kLpQ3xYbVc4Wd2m",
+                    "account_id": 10023,
+                    "team_id": 0,
                     "skill_name": "k8s-triage",
-                    "status": "enabled",
+                    "description": "Diagnose unhealthy Kubernetes workloads from cluster events and pod logs.",
+                    "version": "1.2.0",
                     "tags": [
                       "kubernetes",
                       "triage"
                     ],
-                    "team_id": 0,
+                    "author": "sre-team",
                     "tools": [
                       "bash",
                       "mcp:prometheus/query"
                     ],
-                    "update_available": false,
+                    "status": "enabled",
+                    "created_by": 80011,
+                    "created_at": 1716960000000,
                     "updated_at": 1717046400000,
-                    "version": "1.2.0"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
+                    "can_edit": true,
+                    "update_available": false,
+                    "is_modified": false
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "429": {
+            "$ref": "#/components/responses/TooManyRequests"
+          },
+          "500": {
+            "$ref": "#/components/responses/ServerError"
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "multipart/form-data": {
+              "schema": {
+                "$ref": "#/components/schemas/SkillUploadRequest"
+              },
+              "example": {
+                "team_id": 0,
+                "replace": false
+              }
+            }
+          }
+        }
+      }
+    },
+    "/schedule/by-person": {
+      "post": {
+        "operationId": "scheduleByPerson",
+        "summary": "查看成员值班状态",
+        "description": "查看某成员正在值班的班次、下一次值班以及其参与的全部启用排班。",
+        "tags": [
+          "On-call/值班排班"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- `current` 是正在进行的班次（含真实开始时间）；成员同时在多个值班表中值班时，返回结束最晚的那个。`next` 是最早的下一次值班。在当前时刻前后 45 天内找不到时为 `null`。\n- `schedules` 列出成员至少出现在一个未结束分层中的已启用值班表。已禁用的值班表不会列出，也不参与 `current`/`next` 的计算。\n- 可以查询账户内任意成员；`person_id` 可从成员列表获取。",
+          "href": "/zh/api-reference/on-call/schedules/schedule-by-person",
+          "metadata": {
+            "sidebarTitle": "查看成员值班状态"
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "成功",
+            "content": {
+              "application/json": {
                 "schema": {
                   "allOf": [
                     {
-                      "$ref": "#/components/schemas/ResponseEnvelope"
+                      "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/SkillItem"
+                          "$ref": "#/components/schemas/ScheduleByPersonResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "current": {
+                      "schedule_id": 2539108069860,
+                      "schedule_name": "Open Source Q&A",
+                      "start_at": 1773446400,
+                      "end_at": 1773532799
+                    },
+                    "next": {
+                      "schedule_id": 2539108069860,
+                      "schedule_name": "Open Source Q&A",
+                      "start_at": 1773532800
+                    },
+                    "schedules": [
+                      {
+                        "schedule_id": 2539108069860,
+                        "schedule_name": "Open Source Q&A"
+                      }
+                    ]
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -59188,86 +61273,64 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "security": [
-          {
-            "AppKeyAuth": []
-          }
-        ],
-        "summary": "上传技能",
-        "tags": [
-          "AI SRE/技能"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **30 次/分钟**；**3 次/秒** |\n| 权限要求 | **Skill 管理**（`ai-sre`） |\n\n## 使用说明\n\n- 以 `multipart/form-data` 提交，包含 `file` 部分；支持的压缩包类型为 `.skill`、`.zip`、`.tar.gz`、`.tgz`，最大 100MB（超限文件会在读取正文前即被拒绝）。\n- `skill_id` + `replace=true` 会定向覆盖该指定技能，且跳过团队归属校验，因为调用者本就拥有该行。\n- 仅 `replace=true`（不带 `skill_id`）会按技能名称做 upsert；不设置 `replace` 则始终创建新技能 —— 这两条路径都要求调用者被允许向目标 `team_id` 创建资源。\n- 响应始终将 `can_edit` 标记为 `true`。\n- 每次调用都会记录到账户审计日志。\n",
-          "href": "/zh/api-reference/ai-sre/skills/skill-write-upload",
-          "metadata": {
-            "sidebarTitle": "上传技能"
-          }
-        }
-      }
-    },
-    "/schedule/by-person": {
-      "post": {
-        "description": "查看某成员正在值班的班次、下一次值班以及其参与的全部启用排班。",
-        "operationId": "scheduleByPerson",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {
-                "person_id": 2476444212131
-              },
               "schema": {
                 "$ref": "#/components/schemas/ScheduleByPersonRequest"
+              },
+              "example": {
+                "person_id": 2476444212131
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/schedule/create": {
+      "post": {
+        "operationId": "scheduleCreate",
+        "summary": "创建值班表",
+        "description": "创建值班表，包括轮转分层和换班通知设置。",
+        "tags": [
+          "On-call/值班排班"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **值班管理**（`on-call`） |\n\n## 使用说明\n\n- `schedule_name`（或旧字段 `name`）必填，最长 40 个字符，且在账户内唯一。`description` 最长 500 个字符。\n- `time_zone` 决定值班表所有墙钟规则（交接时间、限制时段、星期、定时通知）所用的时区，创建后不可修改。不传时按 `Asia/Shanghai` 计算，读取时 `time_zone` 为空字符串。\n- 分层时间既可以用数字字段（`layer_start`、`handoff_time`、`restrict_periods` 等）传入，也可以用墙钟字符串（`starts_at`、`ends_at`、`handoff`、`restricts_wall`）传入；同时传入时以墙钟字段为准，并按值班表时区换算。\n- 值班表数量超过账户套餐上限时返回 `NoLicense` 错误。\n- 保存前可用 `/schedule/preview` 预览排班结果。\n- 每次调用都会记录到账户审计日志。",
+          "href": "/zh/api-reference/on-call/schedules/schedule-create",
+          "metadata": {
+            "sidebarTitle": "创建值班表"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "current": {
-                      "end_at": 1773532799,
-                      "schedule_id": 2539108069860,
-                      "schedule_name": "Open Source Q&A",
-                      "start_at": 1773446400
-                    },
-                    "next": {
-                      "end_at": 1773619199,
-                      "schedule_id": 2539108069860,
-                      "schedule_name": "Open Source Q&A",
-                      "start_at": 1773532800
-                    },
-                    "schedules": [
-                      {
-                        "schedule_id": 2539108069860,
-                        "schedule_name": "Open Source Q&A"
-                      }
-                    ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/ScheduleByPersonResponse"
+                          "$ref": "#/components/schemas/ScheduleIDResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "schedule_id": 6294534917601
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -59275,6 +61338,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -59282,135 +61348,134 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "查看成员值班状态",
-        "tags": [
-          "On-call/值班排班"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **值班查看**（`on-call`） 或 **值班管理**（`on-call`） |\n\n## 使用说明\n\n- `current` 为正在值班的班次（含真实开始时间）；`next` 为下一次值班，查询窗口内没有排班时缺省。\n- 已禁用的排班不会出现在列表中。",
-          "href": "/zh/api-reference/on-call/schedules/schedule-by-person",
-          "metadata": {
-            "sidebarTitle": "查看成员值班状态"
-          }
-        }
-      }
-    },
-    "/schedule/create": {
-      "post": {
-        "description": "创建新的值班表（分派策略值班表）。",
-        "operationId": "scheduleCreate",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ScheduleUpsertRequest"
+              },
               "example": {
+                "schedule_name": "Production On-Call",
                 "description": "Primary on-call rotation for the production team",
+                "team_id": 4291079133131,
+                "time_zone": "Asia/Shanghai",
                 "layers": [
                   {
-                    "day_mask": {
-                      "repeat": [
-                        1,
-                        2,
-                        3,
-                        4,
-                        5
-                      ]
-                    },
-                    "enable_time": 1712000000,
-                    "expire_time": 0,
-                    "fair_rotation": false,
+                    "layer_name": "Layer 1",
+                    "name": "Layer 1",
+                    "mode": 0,
+                    "weight": 0,
+                    "hidden": 0,
                     "groups": [
                       {
-                        "end": 0,
                         "group_name": "A",
+                        "name": "A",
                         "members": [
                           {
+                            "role_id": 0,
                             "person_ids": [
                               2451002751131
-                            ],
-                            "role_id": 0
+                            ]
                           }
                         ],
-                        "name": "A",
-                        "start": 0
+                        "start": 0,
+                        "end": 0
                       },
                       {
-                        "end": 0,
                         "group_name": "B",
+                        "name": "B",
                         "members": [
                           {
+                            "role_id": 0,
                             "person_ids": [
                               2476123212131
-                            ],
-                            "role_id": 0
+                            ]
                           }
                         ],
-                        "name": "B",
-                        "start": 0
+                        "start": 0,
+                        "end": 0
                       }
                     ],
+                    "rotation_unit": "day",
+                    "rotation_value": 1,
+                    "rotation_duration": 86400,
                     "handoff_time": 0,
-                    "hidden": 0,
-                    "layer_name": "Layer 1",
-                    "mask_continuous_enabled": false,
-                    "mode": 0,
-                    "name": "Layer 1",
-                    "restrict_end": 0,
+                    "enable_time": 1712000000,
+                    "expire_time": 0,
                     "restrict_mode": 0,
-                    "restrict_periods": [],
                     "restrict_start": 0,
-                    "rotation_duration": 86400,
-                    "rotation_unit": "day",
-                    "rotation_value": 1,
-                    "weight": 0
+                    "restrict_end": 0,
+                    "restrict_periods": [],
+                    "day_mask": {
+                      "repeat": [
+                        1,
+                        2,
+                        3,
+                        4,
+                        5
+                      ]
+                    },
+                    "fair_rotation": false,
+                    "mask_continuous_enabled": false
                   }
                 ],
                 "notify": {
                   "advance_in_time": 300,
+                  "fixed_time": null,
                   "by": {
                     "follow_preference": true,
                     "personal_channels": null
                   },
-                  "fixed_time": null,
                   "webhooks": null
-                },
-                "schedule_name": "Production On-Call",
-                "team_id": 4291079133131
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ScheduleUpsertRequest"
+                }
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/schedule/delete": {
+      "post": {
+        "operationId": "scheduleDelete",
+        "summary": "删除值班表",
+        "description": "按 ID 删除一个或多个值班表及其分层。",
+        "tags": [
+          "On-call/值班排班"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **值班管理**（`on-call`） |\n\n## 使用说明\n\n- 仍被分派策略引用的值班表不能删除：请求返回 HTTP 400 `ReferenceExist`，不会删除任何值班表，`data.refs` 列出引用它的规则（`kind`、`name`、`href`）。\n- 不存在的 ID 会被忽略。列出的值班表在同一事务中删除。\n- 每次调用都会记录到账户审计日志。",
+          "href": "/zh/api-reference/on-call/schedules/schedule-delete",
+          "metadata": {
+            "sidebarTitle": "删除值班表"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "schedule_id": 6294534917601
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/ScheduleIDResponse"
+                          "$ref": "#/components/schemas/ScheduleEmptyObject"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -59418,6 +61483,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -59425,387 +61493,316 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "创建值班表",
-        "tags": [
-          "On-call/值班排班"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **值班管理**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/schedules/schedule-create",
-          "metadata": {
-            "sidebarTitle": "创建值班表"
-          }
-        }
-      }
-    },
-    "/schedule/delete": {
-      "post": {
-        "description": "根据 ID 删除一个或多个值班表。",
-        "operationId": "scheduleDelete",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ScheduleIDsBodyRequest"
+              },
               "example": {
                 "schedule_ids": [
-                  2001
+                  5789640530410
                 ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ScheduleIDsBodyRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/schedule/info": {
+      "post": {
+        "operationId": "scheduleInfo",
+        "summary": "获取值班表详情",
+        "description": "返回单个值班表的配置及分层，并计算指定时间窗口（最长 45 天）内的班次。",
+        "tags": [
+          "On-call/值班排班"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **值班查看**（`on-call`） 或 **值班管理**（`on-call`） |\n\n## 使用说明\n\n- `start` 和 `end` 为 10 位 Unix 秒级时间戳；`end` 必须晚于 `start`，且相差不超过 45 天。\n- `schedule_layers`（及其别名 `layer_schedules`）是窗口内各个未隐藏分层的班次；`final_schedule` 是所有分层合并后的结果，`group` 为 `null` 的班次表示该时段无人值班。\n- 计算结果中的第一个班次可能早于 `start` 开始：在 `start` 时刻已经开始的班次按真实开始时间返回。\n- `cur_oncall` 是此刻正在进行的班次，`next_oncall` 是之后第一个有人值班的班次；在当前时刻前后 45 天内找不到时为 `null`，与请求的时间窗口无关。\n- `schedule_id` 不存在时返回 `400`。",
+          "href": "/zh/api-reference/on-call/schedules/schedule-info",
+          "metadata": {
+            "sidebarTitle": "获取值班表详情"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/ScheduleEmptyObject"
+                          "$ref": "#/components/schemas/ScheduleItem"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
-                }
-              }
-            },
-            "description": "成功"
-          },
-          "400": {
-            "$ref": "#/components/responses/BadRequest"
-          },
-          "401": {
-            "$ref": "#/components/responses/Unauthorized"
-          },
-          "429": {
-            "$ref": "#/components/responses/TooManyRequests"
-          },
-          "500": {
-            "$ref": "#/components/responses/ServerError"
-          }
-        },
-        "summary": "删除值班表",
-        "tags": [
-          "On-call/值班排班"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **值班管理**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/schedules/schedule-delete",
-          "metadata": {
-            "sidebarTitle": "删除值班表"
-          }
-        }
-      }
-    },
-    "/schedule/info": {
-      "post": {
-        "description": "返回值班表的详细信息，并按照指定时间窗口（最多 45 天）返回计算出的值班分层。",
-        "operationId": "scheduleInfo",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "end": 1712086400,
-                "schedule_id": 2001,
-                "start": 1712000000
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ScheduleInfoRequest"
-              }
-            }
-          },
-          "required": true
-        },
-        "responses": {
-          "200": {
-            "content": {
-              "application/json": {
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
+                    "id": 5789640530410,
+                    "name": "test-000001",
                     "account_id": 2451002751131,
+                    "group_id": 4291079133131,
+                    "time_zone": "Asia/Shanghai",
+                    "disabled": 0,
                     "create_at": 1766110836,
                     "create_by": 2476123212131,
-                    "cur_oncall": {
-                      "end": 1776009600,
-                      "group": {
-                        "end": 1776009600,
-                        "group_name": "A",
-                        "members": [
+                    "update_at": 1775205795,
+                    "update_by": 2476123212131,
+                    "layers": [
+                      {
+                        "account_id": 2451002751131,
+                        "name": "Layer 1",
+                        "schedule_id": 5789640530410,
+                        "hidden": 0,
+                        "mode": 0,
+                        "weight": 0,
+                        "groups": [
                           {
-                            "person_ids": [
-                              2451002751131
-                            ],
-                            "role_id": 0
-                          }
-                        ],
-                        "name": "A",
-                        "start": 1775972040
-                      },
-                      "index": 0,
-                      "start": 1775972040,
-                      "update_at": 0,
-                      "weight": 0
-                    },
-                    "description": "abc",
-                    "disabled": 0,
-                    "final_schedule": {
-                      "layer_name": "",
-                      "mode": 0,
-                      "name": "",
-                      "schedules": [
-                        {
-                          "end": 1776096000,
-                          "group": {
-                            "end": 1776096000,
                             "group_name": "A",
+                            "name": "A",
                             "members": [
                               {
+                                "role_id": 0,
                                 "person_ids": [
                                   3122470302131
-                                ],
-                                "role_id": 0
+                                ]
                               }
                             ],
-                            "name": "A",
-                            "start": 1776009600
+                            "start": 0,
+                            "end": 0
                           },
-                          "index": 0,
-                          "start": 1776009600
-                        }
-                      ]
-                    },
-                    "group_id": 4291079133131,
-                    "id": 5789640530410,
-                    "layer_schedules": [
+                          {
+                            "group_name": "B",
+                            "name": "B",
+                            "members": [
+                              {
+                                "role_id": 0,
+                                "person_ids": [
+                                  2659460982131
+                                ]
+                              }
+                            ],
+                            "start": 0,
+                            "end": 0
+                          }
+                        ],
+                        "rotation_duration": 86400,
+                        "handoff_time": 0,
+                        "enable_time": 1767542400,
+                        "expire_time": 0,
+                        "restrict_mode": 0,
+                        "restrict_start": 0,
+                        "restrict_end": 0,
+                        "restrict_periods": [],
+                        "day_mask": {
+                          "repeat": [
+                            1,
+                            2,
+                            3,
+                            4,
+                            5
+                          ]
+                        },
+                        "create_at": 1775205795,
+                        "create_by": 2476123212131,
+                        "update_at": 1775205795,
+                        "update_by": 2476123212131,
+                        "layer_name": "Layer 1",
+                        "fair_rotation": false,
+                        "layer_start": 1767542400,
+                        "layer_end": null,
+                        "rotation_unit": "day",
+                        "rotation_value": 1,
+                        "mask_continuous_enabled": false
+                      }
+                    ],
+                    "schedule_layers": [
                       {
                         "layer_name": "Layer 1",
-                        "mode": 0,
                         "name": "Layer 1",
+                        "mode": 0,
                         "schedules": [
                           {
+                            "start": 1776009600,
                             "end": 1776096000,
                             "group": {
-                              "end": 1776096000,
                               "group_name": "A",
+                              "name": "A",
                               "members": [
                                 {
+                                  "role_id": 0,
                                   "person_ids": [
                                     3122470302131
-                                  ],
-                                  "role_id": 0
+                                  ]
                                 }
                               ],
-                              "name": "A",
-                              "start": 1776009600
+                              "start": 1776009600,
+                              "end": 1776096000
+                            },
+                            "index": 0
+                          },
+                          {
+                            "start": 1776096000,
+                            "end": 1776182400,
+                            "group": {
+                              "group_name": "B",
+                              "name": "B",
+                              "members": [
+                                {
+                                  "role_id": 0,
+                                  "person_ids": [
+                                    2659460982131
+                                  ]
+                                }
+                              ],
+                              "start": 1776096000,
+                              "end": 1776182400
                             },
-                            "index": 0,
-                            "start": 1776009600
+                            "index": 0
                           }
                         ]
                       }
                     ],
-                    "layers": [
-                      {
-                        "account_id": 2451002751131,
-                        "create_at": 1775205795,
-                        "create_by": 2476123212131,
-                        "day_mask": {
-                          "repeat": [
-                            1,
-                            2,
-                            3,
-                            4,
-                            5
-                          ]
-                        },
-                        "enable_time": 1767542400,
-                        "expire_time": 0,
-                        "fair_rotation": false,
-                        "groups": [
-                          {
-                            "end": 0,
+                    "final_schedule": {
+                      "layer_name": "",
+                      "name": "",
+                      "mode": 0,
+                      "schedules": [
+                        {
+                          "start": 1776009600,
+                          "end": 1776096000,
+                          "group": {
                             "group_name": "A",
-                            "members": [
-                              {
-                                "person_ids": [
-                                  3122470302131
-                                ],
-                                "role_id": 0
-                              }
-                            ],
                             "name": "A",
-                            "start": 0
-                          },
-                          {
-                            "end": 0,
-                            "group_name": "B",
                             "members": [
                               {
+                                "role_id": 0,
                                 "person_ids": [
-                                  2659460982131
-                                ],
-                                "role_id": 0
-                              }
-                            ],
-                            "name": "B",
-                            "start": 0
-                          }
-                        ],
-                        "handoff_time": 0,
-                        "hidden": 0,
-                        "layer_end": null,
-                        "layer_name": "Layer 1",
-                        "layer_start": 1767542400,
-                        "mask_continuous_enabled": false,
-                        "mode": 0,
-                        "name": "Layer 1",
-                        "restrict_end": 0,
-                        "restrict_mode": 0,
-                        "restrict_periods": [],
-                        "restrict_start": 0,
-                        "rotation_duration": 86400,
-                        "rotation_unit": "day",
-                        "rotation_value": 1,
-                        "schedule_id": 5789640530410,
-                        "update_at": 1775205795,
-                        "update_by": 2476123212131,
-                        "weight": 0
-                      }
-                    ],
-                    "name": "test-000001",
-                    "next_oncall": {
-                      "end": 1776096000,
-                      "group": {
-                        "end": 1776096000,
-                        "group_name": "A",
-                        "members": [
-                          {
-                            "person_ids": [
-                              3122470302131
-                            ],
-                            "role_id": 0
-                          }
-                        ],
-                        "name": "A",
-                        "start": 1776009600
-                      },
-                      "index": 0,
-                      "start": 1776009600,
-                      "update_at": 0,
-                      "weight": 0
+                                  3122470302131
+                                ]
+                              }
+                            ],
+                            "start": 1776009600,
+                            "end": 1776096000
+                          },
+                          "index": 0
+                        }
+                      ]
                     },
                     "notify": {
                       "advance_in_time": 300,
+                      "fixed_time": null,
                       "by": {
                         "follow_preference": false,
                         "personal_channels": [
                           "email"
                         ]
                       },
-                      "fixed_time": null,
                       "webhooks": [
                         {
+                          "type": "feishu_app",
                           "settings": {
+                            "token": "",
                             "alias": "",
+                            "data_source_id": 5427276014131,
                             "chat_ids": [
                               "oc_60a6dc4c6e4e5cbc4934ef08aa7ff76d"
                             ],
-                            "data_source_id": 5427276014131,
-                            "sign_secret": "",
-                            "token": "",
-                            "verify_token": ""
-                          },
-                          "type": "feishu_app"
+                            "verify_token": "",
+                            "sign_secret": ""
+                          }
                         }
                       ]
                     },
                     "schedule_id": 5789640530410,
-                    "schedule_layers": [
+                    "schedule_name": "test-000001",
+                    "team_id": 4291079133131,
+                    "description": "abc",
+                    "layer_schedules": [
                       {
                         "layer_name": "Layer 1",
-                        "mode": 0,
                         "name": "Layer 1",
+                        "mode": 0,
                         "schedules": [
                           {
+                            "start": 1776009600,
                             "end": 1776096000,
                             "group": {
-                              "end": 1776096000,
                               "group_name": "A",
-                              "members": [
-                                {
-                                  "person_ids": [
-                                    3122470302131
-                                  ],
-                                  "role_id": 0
-                                }
-                              ],
                               "name": "A",
-                              "start": 1776009600
-                            },
-                            "index": 0,
-                            "start": 1776009600
-                          },
-                          {
-                            "end": 1776182400,
-                            "group": {
-                              "end": 1776182400,
-                              "group_name": "B",
                               "members": [
                                 {
+                                  "role_id": 0,
                                   "person_ids": [
-                                    2659460982131
-                                  ],
-                                  "role_id": 0
+                                    3122470302131
+                                  ]
                                 }
                               ],
-                              "name": "B",
-                              "start": 1776096000
+                              "start": 1776009600,
+                              "end": 1776096000
                             },
-                            "index": 0,
-                            "start": 1776096000
+                            "index": 0
                           }
                         ]
                       }
                     ],
-                    "schedule_name": "test-000001",
                     "status": 0,
-                    "team_id": 4291079133131,
-                    "update_at": 1775205795,
-                    "update_by": 2476123212131
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    "cur_oncall": {
+                      "start": 1775972040,
+                      "end": 1776009600,
+                      "group": {
+                        "group_name": "A",
+                        "name": "A",
+                        "members": [
+                          {
+                            "role_id": 0,
+                            "person_ids": [
+                              2451002751131
+                            ]
+                          }
+                        ],
+                        "start": 1775972040,
+                        "end": 1776009600
+                      },
+                      "update_at": 0,
+                      "weight": 0,
+                      "index": 0
                     },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/ScheduleItem"
-                        }
+                    "next_oncall": {
+                      "start": 1776009600,
+                      "end": 1776096000,
+                      "group": {
+                        "group_name": "A",
+                        "name": "A",
+                        "members": [
+                          {
+                            "role_id": 0,
+                            "person_ids": [
+                              3122470302131
+                            ]
+                          }
+                        ],
+                        "start": 1776009600,
+                        "end": 1776096000
                       },
-                      "type": "object"
+                      "update_at": 0,
+                      "weight": 0,
+                      "index": 0
                     }
-                  ]
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -59813,6 +61810,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -59820,121 +61820,120 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "获取值班表详情",
-        "tags": [
-          "On-call/值班排班"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **值班查看**（`on-call`） 或 **值班管理**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/schedules/schedule-info",
-          "metadata": {
-            "sidebarTitle": "获取值班表详情"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ScheduleInfoRequest"
+              },
+              "example": {
+                "schedule_id": 5789640530410,
+                "start": 1776009600,
+                "end": 1776268800
+              }
+            }
           }
         }
       }
     },
     "/schedule/infos": {
       "post": {
-        "description": "根据 ID 列表批量返回值班表信息。",
         "operationId": "scheduleInfos",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "schedule_ids": [
-                  2001,
-                  2002,
-                  2003
-                ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ScheduleIDsRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "批量获取值班表",
+        "description": "按 ID 批量返回值班表的基础配置，不含分层和班次计算结果。",
+        "tags": [
+          "On-call/值班排班"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **值班查看**（`on-call`） 或 **值班管理**（`on-call`） |\n\n## 使用说明\n\n- 只返回已保存的基础配置：`layers`、`schedule_layers`、`layer_schedules`、`cur_oncall`、`next_oncall` 恒为 `null`，`final_schedule` 为空。需要分层和班次时请使用 `/schedule/info`。\n- 不存在的 ID 会被跳过，不报错；已禁用的值班表也会返回。",
+          "href": "/zh/api-reference/on-call/schedules/schedule-infos",
+          "metadata": {
+            "sidebarTitle": "批量获取值班表"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/ScheduleSelfResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "items": [
                       {
+                        "id": 5789640530410,
+                        "name": "test-000001",
                         "account_id": 2451002751131,
+                        "group_id": 4291079133131,
+                        "time_zone": "Asia/Shanghai",
+                        "disabled": 0,
                         "create_at": 1766110836,
                         "create_by": 2476123212131,
-                        "cur_oncall": null,
-                        "description": "abc",
-                        "disabled": 0,
+                        "update_at": 1775205795,
+                        "update_by": 2476123212131,
+                        "layers": null,
+                        "schedule_layers": null,
                         "final_schedule": {
                           "layer_name": "",
-                          "mode": 0,
                           "name": "",
+                          "mode": 0,
                           "schedules": null
                         },
-                        "group_id": 4291079133131,
-                        "id": 5789640530410,
-                        "layer_schedules": null,
-                        "layers": null,
-                        "name": "test-000001",
-                        "next_oncall": null,
                         "notify": {
                           "advance_in_time": 300,
+                          "fixed_time": null,
                           "by": {
                             "follow_preference": false,
                             "personal_channels": [
                               "email"
                             ]
                           },
-                          "fixed_time": null,
                           "webhooks": [
                             {
+                              "type": "feishu_app",
                               "settings": {
+                                "token": "",
                                 "alias": "",
+                                "data_source_id": 5427276014131,
                                 "chat_ids": [
                                   "oc_60a6dc4c6e4e5cbc4934ef08aa7ff76d"
                                 ],
-                                "data_source_id": 5427276014131,
-                                "sign_secret": "",
-                                "token": "",
-                                "verify_token": ""
-                              },
-                              "type": "feishu_app"
+                                "verify_token": "",
+                                "sign_secret": ""
+                              }
                             }
                           ]
                         },
                         "schedule_id": 5789640530410,
-                        "schedule_layers": null,
                         "schedule_name": "test-000001",
-                        "status": 0,
                         "team_id": 4291079133131,
-                        "update_at": 1775205795,
-                        "update_by": 2476123212131
+                        "description": "abc",
+                        "layer_schedules": null,
+                        "status": 0,
+                        "cur_oncall": null,
+                        "next_oncall": null
                       }
                     ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/ScheduleSelfResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -59942,6 +61941,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -59949,157 +61951,159 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "批量获取值班表",
-        "tags": [
-          "On-call/值班排班"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **值班查看**（`on-call`） 或 **值班管理**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/schedules/schedule-infos",
-          "metadata": {
-            "sidebarTitle": "批量获取值班表"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ScheduleIDsRequest"
+              },
+              "example": {
+                "schedule_ids": [
+                  5789640530410,
+                  5432326025106
+                ]
+              }
+            }
           }
         }
       }
     },
     "/schedule/list": {
       "post": {
-        "description": "返回值班表的分页列表。若同时传入 start 与 end（间隔不超过 45 天），响应会包含计算后的排班分层。",
         "operationId": "scheduleList",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "is_my_team": true,
-                "limit": 20,
-                "p": 1,
-                "query": "production"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ScheduleListRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "查询值班表列表",
+        "description": "分页查询值班表，支持过滤；同时传入 `start` 和 `end` 时会一并计算班次。",
+        "tags": [
+          "On-call/值班排班"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 按创建时间从新到旧排序。`query` 对值班表名称或描述做子串匹配。\n- `is_my_team` 为 true 时只保留调用者所在团队的值班表；`is_my_manage` 为 true 时保留调用者所在团队的值班表以及调用者创建的值班表。两者不能同时为 true。`team_ids` 会与上述过滤取交集。\n- 不传 `start`/`end` 时只返回已保存的配置（`layers`、`schedule_layers`、`cur_oncall`、`next_oncall` 为 `null`）。两者都传时计算 `layers`、`schedule_layers`、`final_schedule`、`cur_oncall` 和 `next_oncall`；本接口中 `layer_schedules` 始终为 `null`。\n- `start` 和 `end` 为 10 位 Unix 秒级时间戳；`end` 必须晚于 `start`，且相差不超过 45 天。只传 `end` 不传 `start` 会被拒绝。",
+          "href": "/zh/api-reference/on-call/schedules/schedule-list",
+          "metadata": {
+            "sidebarTitle": "查询值班表列表"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/ScheduleListResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "items": [
                       {
+                        "id": 5789640530410,
+                        "name": "test-000001",
                         "account_id": 2451002751131,
+                        "group_id": 4291079133131,
+                        "time_zone": "Asia/Shanghai",
+                        "disabled": 0,
                         "create_at": 1766110836,
                         "create_by": 2476123212131,
-                        "cur_oncall": null,
-                        "description": "abc",
-                        "disabled": 0,
+                        "update_at": 1775205795,
+                        "update_by": 2476123212131,
+                        "layers": null,
+                        "schedule_layers": null,
                         "final_schedule": {
                           "layer_name": "",
-                          "mode": 0,
                           "name": "",
+                          "mode": 0,
                           "schedules": null
                         },
-                        "group_id": 4291079133131,
-                        "id": 5789640530410,
-                        "layer_schedules": null,
-                        "layers": null,
-                        "name": "test-000001",
-                        "next_oncall": null,
                         "notify": {
                           "advance_in_time": 300,
+                          "fixed_time": null,
                           "by": {
                             "follow_preference": false,
                             "personal_channels": [
                               "email"
                             ]
                           },
-                          "fixed_time": null,
                           "webhooks": [
                             {
+                              "type": "feishu_app",
                               "settings": {
+                                "token": "",
                                 "alias": "",
+                                "data_source_id": 5427276014131,
                                 "chat_ids": [
                                   "oc_60a6dc4c6e4e5cbc4934ef08aa7ff76d"
                                 ],
-                                "data_source_id": 5427276014131,
-                                "sign_secret": "",
-                                "token": "",
-                                "verify_token": ""
-                              },
-                              "type": "feishu_app"
+                                "verify_token": "",
+                                "sign_secret": ""
+                              }
                             }
                           ]
                         },
                         "schedule_id": 5789640530410,
-                        "schedule_layers": null,
                         "schedule_name": "test-000001",
-                        "status": 0,
                         "team_id": 4291079133131,
-                        "update_at": 1775205795,
-                        "update_by": 2476123212131
+                        "description": "abc",
+                        "layer_schedules": null,
+                        "status": 0,
+                        "cur_oncall": null,
+                        "next_oncall": null
                       },
                       {
+                        "id": 5432326025106,
+                        "name": "test-2509300001",
                         "account_id": 2451002751131,
+                        "group_id": 2477033058131,
+                        "time_zone": "",
+                        "disabled": 0,
                         "create_at": 1759132037,
                         "create_by": 2476123212131,
-                        "cur_oncall": null,
-                        "description": "",
-                        "disabled": 0,
+                        "update_at": 1775207501,
+                        "update_by": 2476123212131,
+                        "layers": null,
+                        "schedule_layers": null,
                         "final_schedule": {
                           "layer_name": "",
-                          "mode": 0,
                           "name": "",
+                          "mode": 0,
                           "schedules": null
                         },
-                        "group_id": 2477033058131,
-                        "id": 5432326025106,
-                        "layer_schedules": null,
-                        "layers": null,
-                        "name": "test-2509300001",
-                        "next_oncall": null,
                         "notify": {
                           "advance_in_time": 300,
+                          "fixed_time": null,
                           "by": {
                             "follow_preference": true,
                             "personal_channels": null
                           },
-                          "fixed_time": null,
                           "webhooks": null
                         },
                         "schedule_id": 5432326025106,
-                        "schedule_layers": null,
                         "schedule_name": "test-2509300001",
-                        "status": 0,
                         "team_id": 2477033058131,
-                        "update_at": 1775207501,
-                        "update_by": 2476123212131
+                        "description": "",
+                        "layer_schedules": null,
+                        "status": 0,
+                        "cur_oncall": null,
+                        "next_oncall": null
                       }
                     ],
                     "total": 41
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/ScheduleListResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -60107,6 +62111,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -60114,272 +62121,228 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "查询值班表列表",
-        "tags": [
-          "On-call/值班排班"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |",
-          "href": "/zh/api-reference/on-call/schedules/schedule-list",
-          "metadata": {
-            "sidebarTitle": "查询值班表列表"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ScheduleListRequest"
+              },
+              "example": {
+                "p": 1,
+                "limit": 20,
+                "query": "production",
+                "is_my_team": true
+              }
+            }
           }
         }
       }
     },
     "/schedule/preview": {
       "post": {
-        "description": "预览值班表配置生成的排班结果，不会持久化。请求体与创建/更新相同，并需要指定 start 和 end 时间窗口（最多 45 天）。",
         "operationId": "schedulePreview",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "end": 1712086400,
-                "layers": [
-                  {
-                    "day_mask": {
-                      "repeat": [
-                        1,
-                        2,
-                        3,
-                        4,
-                        5
-                      ]
-                    },
-                    "enable_time": 1712000000,
-                    "expire_time": 0,
-                    "fair_rotation": false,
-                    "groups": [
-                      {
-                        "end": 0,
-                        "group_name": "A",
-                        "members": [
-                          {
-                            "person_ids": [
-                              2451002751131
-                            ],
-                            "role_id": 0
-                          }
-                        ],
-                        "name": "A",
-                        "start": 0
-                      }
-                    ],
-                    "handoff_time": 0,
-                    "hidden": 0,
-                    "layer_name": "Layer 1",
-                    "mask_continuous_enabled": false,
-                    "mode": 0,
-                    "name": "Layer 1",
-                    "restrict_end": 0,
-                    "restrict_mode": 0,
-                    "restrict_periods": [],
-                    "restrict_start": 0,
-                    "rotation_duration": 86400,
-                    "rotation_unit": "day",
-                    "rotation_value": 1,
-                    "weight": 0
-                  }
-                ],
-                "schedule_name": "Preview Schedule",
-                "start": 1712000000
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ScheduleUpsertRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "预览值班表",
+        "description": "预览值班表配置生成的排班结果，不会持久化。请求体与创建/更新相同，并需要指定 start 和 end 时间窗口（最多 45 天）。",
+        "tags": [
+          "On-call/值班排班"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **100 次/分钟**；**5 次/秒** |\n| 权限要求 | **值班查看**（`on-call`） 或 **值班管理**（`on-call`） |\n\n## 使用说明\n\n- 不会保存任何数据。请求体字段与 `/schedule/create` 相同，另需必填的 `start`/`end` 窗口。`start` 和 `end` 为 10 位 Unix 秒级时间戳；`end` 必须晚于 `start`，且相差不超过 45 天。\n- 传入 `time_zone` 可按值班表将要使用的时区预览；不传时，墙钟时间按 `Asia/Shanghai` 解读。\n- 只有已保存的值班表才有的字段（`id`、`name`、`group_id`、`disabled`、`status`）按请求原样回显，通常为 `null`。\n- `cur_oncall` 是此刻正在进行的班次，`next_oncall` 是之后第一个有人值班的班次；在当前时刻前后 45 天内找不到时为 `null`，与请求的时间窗口无关。",
+          "href": "/zh/api-reference/on-call/schedules/schedule-preview",
+          "metadata": {
+            "sidebarTitle": "预览值班表"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/ScheduleItem"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
+                    "id": null,
+                    "name": null,
                     "account_id": 0,
+                    "group_id": null,
+                    "time_zone": "",
+                    "disabled": null,
                     "create_at": 0,
                     "create_by": 0,
-                    "cur_oncall": null,
-                    "description": null,
-                    "disabled": null,
-                    "end": 1776240000,
-                    "final_schedule": {
-                      "layer_name": "",
-                      "mode": 0,
-                      "name": "",
-                      "schedules": [
-                        {
-                          "end": 1776096000,
-                          "group": {
-                            "end": 1776096000,
-                            "group_name": "A",
-                            "members": [
-                              {
-                                "person_ids": [
-                                  2451002751131
-                                ],
-                                "role_id": 0
-                              }
-                            ],
-                            "name": "A",
-                            "start": 1776009600
-                          },
-                          "index": 0,
-                          "start": 1776009600
-                        }
-                      ]
-                    },
-                    "group_id": null,
-                    "id": null,
-                    "layer_schedules": null,
+                    "update_at": 0,
+                    "update_by": 0,
                     "layers": [
                       {
                         "account_id": 0,
-                        "create_at": 0,
-                        "create_by": 0,
-                        "day_mask": {
-                          "repeat": [
-                            1,
-                            2,
-                            3,
-                            4,
-                            5
-                          ]
-                        },
-                        "enable_time": 1775980800,
-                        "expire_time": 0,
-                        "fair_rotation": false,
+                        "name": "Layer 1",
+                        "schedule_id": 0,
+                        "hidden": 0,
+                        "mode": 0,
+                        "weight": 0,
                         "groups": [
                           {
-                            "end": 0,
                             "group_name": "A",
+                            "name": "A",
                             "members": [
                               {
+                                "role_id": 0,
                                 "person_ids": [
                                   2451002751131
-                                ],
-                                "role_id": 0
+                                ]
                               }
                             ],
-                            "name": "A",
-                            "start": 0
+                            "start": 0,
+                            "end": 0
                           },
                           {
-                            "end": 0,
                             "group_name": "B",
+                            "name": "B",
                             "members": [
                               {
+                                "role_id": 0,
                                 "person_ids": [
                                   2476123212131
-                                ],
-                                "role_id": 0
+                                ]
                               }
                             ],
-                            "name": "B",
-                            "start": 0
+                            "start": 0,
+                            "end": 0
                           }
                         ],
+                        "rotation_duration": 86400,
                         "handoff_time": 0,
-                        "hidden": 0,
-                        "layer_end": null,
-                        "layer_name": "Layer 1",
-                        "layer_start": 1775980800,
-                        "mask_continuous_enabled": false,
-                        "mode": 0,
-                        "name": "Layer 1",
-                        "restrict_end": 0,
+                        "enable_time": 1775980800,
+                        "expire_time": 0,
                         "restrict_mode": 0,
-                        "restrict_periods": [],
                         "restrict_start": 0,
-                        "rotation_duration": 86400,
-                        "rotation_unit": "day",
-                        "rotation_value": 1,
-                        "schedule_id": 0,
+                        "restrict_end": 0,
+                        "restrict_periods": [],
+                        "day_mask": {
+                          "repeat": [
+                            1,
+                            2,
+                            3,
+                            4,
+                            5
+                          ]
+                        },
+                        "create_at": 0,
+                        "create_by": 0,
                         "update_at": 0,
                         "update_by": 0,
-                        "weight": 0
+                        "layer_name": "Layer 1",
+                        "fair_rotation": false,
+                        "layer_start": 1775980800,
+                        "layer_end": null,
+                        "rotation_unit": "day",
+                        "rotation_value": 1,
+                        "mask_continuous_enabled": false
                       }
                     ],
-                    "name": null,
-                    "next_oncall": null,
-                    "notify": null,
-                    "schedule_id": 0,
                     "schedule_layers": [
                       {
                         "layer_name": "Layer 1",
-                        "mode": 0,
                         "name": "Layer 1",
+                        "mode": 0,
                         "schedules": [
                           {
+                            "start": 1776009600,
                             "end": 1776096000,
                             "group": {
-                              "end": 1776096000,
                               "group_name": "A",
+                              "name": "A",
                               "members": [
                                 {
+                                  "role_id": 0,
                                   "person_ids": [
                                     2451002751131
-                                  ],
-                                  "role_id": 0
+                                  ]
                                 }
                               ],
-                              "name": "A",
-                              "start": 1776009600
+                              "start": 1776009600,
+                              "end": 1776096000
                             },
-                            "index": 0,
-                            "start": 1776009600
+                            "index": 0
                           },
                           {
+                            "start": 1776096000,
                             "end": 1776182400,
                             "group": {
-                              "end": 1776182400,
                               "group_name": "B",
+                              "name": "B",
                               "members": [
                                 {
+                                  "role_id": 0,
                                   "person_ids": [
                                     2476123212131
-                                  ],
-                                  "role_id": 0
+                                  ]
                                 }
                               ],
-                              "name": "B",
-                              "start": 1776096000
+                              "start": 1776096000,
+                              "end": 1776182400
                             },
-                            "index": 0,
-                            "start": 1776096000
+                            "index": 0
                           }
                         ]
                       }
                     ],
-                    "schedule_name": null,
+                    "final_schedule": {
+                      "layer_name": "",
+                      "name": "",
+                      "mode": 0,
+                      "schedules": [
+                        {
+                          "start": 1776009600,
+                          "end": 1776096000,
+                          "group": {
+                            "group_name": "A",
+                            "name": "A",
+                            "members": [
+                              {
+                                "role_id": 0,
+                                "person_ids": [
+                                  2451002751131
+                                ]
+                              }
+                            ],
+                            "start": 1776009600,
+                            "end": 1776096000
+                          },
+                          "index": 0
+                        }
+                      ]
+                    },
                     "start": 1775980800,
-                    "status": null,
+                    "end": 1776240000,
+                    "notify": null,
+                    "schedule_id": 0,
+                    "schedule_name": null,
                     "team_id": null,
-                    "update_at": 0,
-                    "update_by": 0
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/ScheduleItem"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                    "description": null,
+                    "layer_schedules": null,
+                    "status": null,
+                    "cur_oncall": null,
+                    "next_oncall": null
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -60387,6 +62350,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -60394,165 +62360,213 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "预览值班表",
-        "tags": [
-          "On-call/值班排班"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **60 次/分钟**；**10 次/秒** |\n| 权限要求 | **值班查看**（`on-call`） 或 **值班管理**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/schedules/schedule-preview",
-          "metadata": {
-            "sidebarTitle": "预览值班表"
-          }
-        }
-      }
-    },
-    "/schedule/self": {
-      "post": {
-        "description": "返回当前用户被分配的值班表列表。",
-        "operationId": "scheduleSelf",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ScheduleUpsertRequest"
+              },
               "example": {
+                "schedule_name": "Preview Schedule",
+                "start": 1712000000,
                 "end": 1712086400,
-                "start": 1712000000
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ScheduleSelfRequest"
+                "layers": [
+                  {
+                    "layer_name": "Layer 1",
+                    "name": "Layer 1",
+                    "mode": 0,
+                    "weight": 0,
+                    "hidden": 0,
+                    "groups": [
+                      {
+                        "group_name": "A",
+                        "name": "A",
+                        "members": [
+                          {
+                            "role_id": 0,
+                            "person_ids": [
+                              2451002751131
+                            ]
+                          }
+                        ],
+                        "start": 0,
+                        "end": 0
+                      }
+                    ],
+                    "rotation_unit": "day",
+                    "rotation_value": 1,
+                    "rotation_duration": 86400,
+                    "handoff_time": 0,
+                    "enable_time": 1712000000,
+                    "expire_time": 0,
+                    "restrict_mode": 0,
+                    "restrict_start": 0,
+                    "restrict_end": 0,
+                    "restrict_periods": [],
+                    "day_mask": {
+                      "repeat": [
+                        1,
+                        2,
+                        3,
+                        4,
+                        5
+                      ]
+                    },
+                    "fair_rotation": false,
+                    "mask_continuous_enabled": false
+                  }
+                ]
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/schedule/self": {
+      "post": {
+        "operationId": "scheduleSelf",
+        "summary": "查询我的值班表",
+        "description": "列出调用成员所属的已启用值班表，并给出该成员在时间窗口内的班次。",
+        "tags": [
+          "On-call/值班排班"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **值班查看**（`on-call`） 或 **值班管理**（`on-call`） |\n\n## 使用说明\n\n- 列出调用成员出现在任一分层中的全部已启用值班表，不论其在窗口内是否值班。已禁用的值班表会被跳过。\n- `final_schedule` 只保留调用者本人的班次：调用者不在班的时段 `group` 为 `null`。`layers` 和 `schedule_layers` 描述整个值班表。\n- 本接口中 `cur_oncall` 和 `next_oncall` 恒为 `null`；如需调用者当前及下一次值班，请使用 `/schedule/by-person`。\n- `start` 和 `end` 为 10 位 Unix 秒级时间戳；`end` 必须晚于 `start`，且相差不超过 45 天。",
+          "href": "/zh/api-reference/on-call/schedules/schedule-self",
+          "metadata": {
+            "sidebarTitle": "查询我的值班表"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/ScheduleSelfResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "items": [
                       {
+                        "id": 2539108069860,
+                        "name": "Open Source Q&A",
                         "account_id": 2451002751131,
+                        "group_id": 2477033058131,
+                        "time_zone": "",
+                        "disabled": 0,
                         "create_at": 1702623874,
                         "create_by": 2451002751131,
-                        "cur_oncall": null,
-                        "description": "",
-                        "disabled": 0,
-                        "final_schedule": {
-                          "layer_name": "",
-                          "mode": 0,
-                          "name": "",
-                          "schedules": null
-                        },
-                        "group_id": 2477033058131,
-                        "id": 2539108069860,
-                        "layer_schedules": null,
+                        "update_at": 1710468081,
+                        "update_by": 2476444212131,
                         "layers": [
                           {
                             "account_id": 2451002751131,
-                            "create_at": 1702623874,
-                            "create_by": 2451002751131,
-                            "day_mask": {
-                              "repeat": [
-                                1,
-                                2,
-                                3,
-                                4,
-                                5
-                              ]
-                            },
-                            "enable_time": 1702623874,
-                            "expire_time": 0,
-                            "fair_rotation": false,
+                            "name": "Rule 1",
+                            "schedule_id": 2539108069860,
+                            "hidden": 0,
+                            "mode": 0,
+                            "weight": 0,
                             "groups": [
                               {
-                                "end": 0,
                                 "group_name": "A",
+                                "name": "A",
                                 "members": [
                                   {
+                                    "role_id": 0,
                                     "person_ids": [
                                       2476444212131
-                                    ],
-                                    "role_id": 0
+                                    ]
                                   }
                                 ],
-                                "name": "A",
-                                "start": 0
+                                "start": 0,
+                                "end": 0
                               },
                               {
-                                "end": 0,
                                 "group_name": "B",
+                                "name": "B",
                                 "members": [
                                   {
+                                    "role_id": 0,
                                     "person_ids": [
                                       2469167612131
-                                    ],
-                                    "role_id": 0
+                                    ]
                                   }
                                 ],
-                                "name": "B",
-                                "start": 0
+                                "start": 0,
+                                "end": 0
                               }
                             ],
+                            "rotation_duration": 86400,
                             "handoff_time": 0,
-                            "hidden": 0,
-                            "layer_end": null,
-                            "layer_name": "Rule 1",
-                            "layer_start": 1702623874,
-                            "mask_continuous_enabled": false,
-                            "mode": 0,
-                            "name": "Rule 1",
-                            "restrict_end": 0,
+                            "enable_time": 1702623874,
+                            "expire_time": 0,
                             "restrict_mode": 0,
-                            "restrict_periods": [],
                             "restrict_start": 0,
-                            "rotation_duration": 86400,
-                            "rotation_unit": "day",
-                            "rotation_value": 1,
-                            "schedule_id": 2539108069860,
+                            "restrict_end": 0,
+                            "restrict_periods": [],
+                            "day_mask": {
+                              "repeat": [
+                                1,
+                                2,
+                                3,
+                                4,
+                                5
+                              ]
+                            },
+                            "create_at": 1702623874,
+                            "create_by": 2451002751131,
                             "update_at": 1710468081,
                             "update_by": 2476444212131,
-                            "weight": 0
+                            "layer_name": "Rule 1",
+                            "fair_rotation": false,
+                            "layer_start": 1702623874,
+                            "layer_end": null,
+                            "rotation_unit": "day",
+                            "rotation_value": 1,
+                            "mask_continuous_enabled": false
                           }
                         ],
-                        "name": "Open Source Q&A",
-                        "next_oncall": null,
+                        "schedule_layers": null,
+                        "final_schedule": {
+                          "layer_name": "",
+                          "name": "",
+                          "mode": 0,
+                          "schedules": null
+                        },
                         "notify": {
-                          "by": null,
                           "fixed_time": null,
+                          "by": null,
                           "webhooks": null
                         },
                         "schedule_id": 2539108069860,
-                        "schedule_layers": null,
                         "schedule_name": "Open Source Q&A",
-                        "status": 0,
                         "team_id": 2477033058131,
-                        "update_at": 1710468081,
-                        "update_by": 2476444212131
+                        "description": "",
+                        "layer_schedules": null,
+                        "status": 0,
+                        "cur_oncall": null,
+                        "next_oncall": null
                       }
                     ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/ScheduleSelfResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -60560,6 +62574,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -60567,65 +62584,63 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "查询我的值班表",
-        "tags": [
-          "On-call/值班排班"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **值班查看**（`on-call`） 或 **值班管理**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/schedules/schedule-self",
-          "metadata": {
-            "sidebarTitle": "查询我的值班表"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ScheduleSelfRequest"
+              },
+              "example": {
+                "start": 1712000000,
+                "end": 1712086400
+              }
+            }
           }
         }
       }
     },
     "/schedule/update": {
       "post": {
-        "description": "更新已有的值班表，需要通过 schedule_id 指定值班表。",
         "operationId": "scheduleUpdate",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "description": "Updated primary on-call rotation",
-                "schedule_id": 2001,
-                "schedule_name": "Production On-Call (Updated)",
-                "team_id": 4291079133131
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ScheduleUpsertRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "更新值班表",
+        "description": "更新 `schedule_id` 指定的值班表；分层列表整体替换。",
+        "tags": [
+          "On-call/值班排班"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **值班管理**（`on-call`） |\n\n## 使用说明\n\n- `layers` 总是整体替换：请把要保留的分层全部传入。不传 `layers`（或传空数组）会删除所有分层。\n- 未传的 `schedule_name`、`description`、`team_id`、`notify` 和 `status` 保持原值。传入的 `notify` 会整体替换通知配置。\n- 更新时旧字段 `name` 和 `disabled` 不生效；改名请用 `schedule_name`，启用/禁用请用 `status`（`0` 启用，`1` 禁用）。\n- `time_zone` 不可修改：不传或传当前值；传入其他值会被拒绝。分层的墙钟字段按已保存的时区换算。\n- 每次调用都会记录到账户审计日志。",
+          "href": "/zh/api-reference/on-call/schedules/schedule-update",
+          "metadata": {
+            "sidebarTitle": "更新值班表"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/ScheduleEmptyObject"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -60633,6 +62648,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -60640,15 +62658,69 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "更新值班表",
-        "tags": [
-          "On-call/值班排班"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **值班管理**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/schedules/schedule-update",
-          "metadata": {
-            "sidebarTitle": "更新值班表"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ScheduleUpsertRequest"
+              },
+              "example": {
+                "schedule_id": 5789640530410,
+                "schedule_name": "Production On-Call",
+                "description": "Primary on-call rotation for the production team",
+                "team_id": 4291079133131,
+                "status": 0,
+                "layers": [
+                  {
+                    "layer_name": "Layer 1",
+                    "mode": 0,
+                    "groups": [
+                      {
+                        "group_name": "A",
+                        "members": [
+                          {
+                            "role_id": 0,
+                            "person_ids": [
+                              2451002751131
+                            ]
+                          }
+                        ]
+                      },
+                      {
+                        "group_name": "B",
+                        "members": [
+                          {
+                            "role_id": 0,
+                            "person_ids": [
+                              2476123212131
+                            ]
+                          }
+                        ]
+                      }
+                    ],
+                    "rotation_unit": "day",
+                    "rotation_value": 1,
+                    "starts_at": {
+                      "date": "2026-04-13",
+                      "time": "09:00"
+                    },
+                    "restrict_mode": 0,
+                    "day_mask": {
+                      "repeat": [
+                        1,
+                        2,
+                        3,
+                        4,
+                        5
+                      ]
+                    },
+                    "fair_rotation": false,
+                    "mask_continuous_enabled": false
+                  }
+                ]
+              }
+            }
           }
         }
       }
@@ -60688,16 +62760,21 @@
                         "created_at": 1712700000,
                         "git_commit_sha": "abc1234def5678",
                         "git_repository_url": "https://github.com/example/my-web-app",
-                        "key": "browser/my-web-app/1.0.0/main.js.map",
-                        "metadata": {},
+                        "key": "3f9a1c2e7b8d4e6f9a0b1c2d3e4f5a6b",
+                        "metadata": {
+                          "minified_url": "https://cdn.example.com/static/js/main.js"
+                        },
+                        "minified_path": "/js_sourcemap/my-web-app/1.0.0/static/js/main.js",
+                        "minified_url": "https://cdn.example.com/static/js/main.js",
                         "service": "my-web-app",
                         "size": 204800,
+                        "sourcemap_path": "/js_sourcemap/my-web-app/1.0.0/static/js/main.js.map",
                         "type": "browser",
                         "updated_at": 1712700000,
                         "version": "1.0.0"
                       }
                     ],
-                    "total": 3
+                    "total": 1
                   },
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 },
@@ -60726,6 +62803,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -60738,7 +62818,7 @@
           "RUM/RUM Sourcemap"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- `start_time` 和 `end_time` 为必填字段，均使用 Unix 时间戳（**毫秒**），最大时间跨度 365 天。\n- `type` 字段用于选择平台：`browser`（JavaScript）、`android` 或 `ios`。省略时默认为 `browser`。\n- 默认每页 20 条，最大 100 条，默认按 `created_at` 倒序排列。\n- Android 平台可用 `build_id` 匹配 Gradle 插件的构建标识；iOS 平台可用 `uuid` 匹配 dSYM bundle UUID。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- `start_time` 和 `end_time` 为必填字段，均使用 Unix 时间戳（**毫秒**），按上传时间过滤，最大时间跨度 365 天。\n- `type` 选择平台符号文件库：`browser`、`android`、`ios`、`miniprogram`、`react-native`、`harmony`、`flutter` 或 `electron`。省略时默认为 `browser`；其他取值（包括 `web`）返回空结果。\n- `kind: native` 会把 `android` 和 `harmony` 切换到各自的 native `.so` 符号库。\n- 默认每页 20 条，最大 100 条，默认按 `created_at` 倒序排列。\n- `build_id`、`uuid`、`query` 均为子串匹配。`uuid` 以及 iOS 的 `query` 会先转为大写并去掉连字符再匹配。\n- 无匹配记录时 `items` 和 `total` 都不返回，`data` 为空对象。",
           "href": "/zh/api-reference/rum/sourcemaps/sourcemap-read-list",
           "metadata": {
             "sidebarTitle": "查询 Sourcemap 列表"
@@ -60748,7 +62828,7 @@
     },
     "/sourcemap/stack/enrich": {
       "post": {
-        "description": "对 Browser、Android、iOS、小程序或 HarmonyOS 错误栈进行符号化或反混淆。",
+        "description": "使用某服务版本已上传的 Sourcemap 或符号文件，对错误栈进行符号化或反混淆。",
         "operationId": "sourcemap-read-stack-enrich",
         "requestBody": {
           "content": {
@@ -60826,6 +62906,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -60838,7 +62921,7 @@
           "RUM/RUM Sourcemap"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 为兼容旧调用，省略 `type` 时默认按 `browser` 处理。\n- 设置 1 到 20 之间的 `near` 可在转换后的栈帧附近返回源码片段。\n- Android NDK native 崩溃需传入 `arch` 和 `source_type: ndk`，后端会路由到 native 符号化逻辑。\n- iOS 崩溃栈需传入 `binary_images`，以便按上传的 dSYM 文件重定位地址。\n- `no_cache` 主要用于调试，会绕过已缓存的 enrich 结果。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 省略 `type` 时默认按 `browser` 处理。\n- `service`、`version` 须与上传时一致；找不到对应符号的栈帧会以 `converted: false` 返回。\n- 设置 1 到 20 之间的 `near` 可在转换后的栈帧附近返回源码片段。\n- `source_type`（错误事件的 `error.source_type`）会改变路由：`type: android` 时，值中含 `ndk`，或值为空但传了 `arch`，按 NDK native 符号处理；`type` 为 `flutter` 或 `react-native` 时，`ios` 走 dSYM，`android`/`ndk` 走 Android 符号；`type: electron` 时，`macos`/`windows`/`linux` 按 Breakpad 符号解析 minidump 栈帧。\n- iOS 崩溃栈需传入 `binary_images`，以便按上传的 dSYM 文件重定位地址。\n- 结果按错误栈缓存；`no_cache: true` 会绕过缓存，主要用于调试。",
           "href": "/zh/api-reference/rum/sourcemaps/sourcemap-read-stack-enrich",
           "metadata": {
             "sidebarTitle": "丰富错误栈信息"
@@ -60848,97 +62931,83 @@
     },
     "/status-page/change/active/list": {
       "get": {
-        "description": "查询状态页指定类型的进行中（非终态）事件列表。",
         "operationId": "statusPageChangeActiveList",
-        "parameters": [
-          {
-            "description": "状态页 ID。",
-            "in": "query",
-            "name": "page_id",
-            "required": true,
-            "schema": {
-              "format": "int64",
-              "type": "integer"
-            }
-          },
-          {
-            "description": "事件类型筛选，必填。仅返回进行中（非终态）事件：incident 含 investigating/identified/monitoring，maintenance 含 scheduled/ongoing。",
-            "in": "query",
-            "name": "type",
-            "required": true,
-            "schema": {
-              "enum": [
-                "incident",
-                "maintenance"
-              ],
-              "type": "string"
-            }
-          }
+        "summary": "查询状态页活跃事件列表",
+        "description": "查询状态页指定类型的进行中（非终态）事件列表。",
+        "tags": [
+          "On-call/状态页"
         ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 一次返回该类型全部非终态事件，按开始时间从新到旧排序：故障为 `investigating`/`identified`/`monitoring`，维护为 `scheduled`/`ongoing`。",
+          "href": "/zh/api-reference/on-call/status-pages/status-page-change-active-list",
+          "metadata": {
+            "sidebarTitle": "查询状态页活跃事件列表"
+          }
+        },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/StatusPageChangeListResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "items": [
                       {
+                        "change_id": 5821693893131,
+                        "page_id": 5750613685214,
+                        "type": "incident",
+                        "title": "Web Console Degraded Performance",
+                        "description": "We are currently investigating an issue affecting some services.",
+                        "status": "investigating",
                         "affected_components": [
                           {
-                            "available_since_seconds": 1765349358,
                             "component_id": "01KC3GAZ6ZJE40H55GM31RPWZE",
+                            "section_id": "01KC3FKKX5TSVG6Z3X1QNGF6V2",
                             "name": "Web Console",
+                            "available_since_seconds": 1765349358,
                             "order_id": 1,
-                            "section_id": "01KC3FKKX5TSVG6Z3X1QNGF6V2",
                             "status": "degraded"
-                          }
-                        ],
-                        "change_id": 5821693893131,
-                        "description": "We are currently investigating an issue affecting some services.",
-                        "notify_subscribers": true,
-                        "page_id": 5750613685214,
+                          }
+                        ],
                         "start_at_seconds": 1766736878,
-                        "status": "investigating",
-                        "title": "Web Console Degraded Performance",
-                        "type": "incident",
                         "updates": [
                           {
+                            "update_id": "01KDCVJQ88SZPHWPTDV2Z2AZW8",
                             "at_seconds": 1766736876,
+                            "status": "investigating",
+                            "description": "We are currently investigating an issue affecting some services.",
                             "component_changes": [
                               {
                                 "component_id": "01KC3GAZ6ZJE40H55GM31RPWZE",
                                 "component_name": "Web Console",
                                 "status": "degraded"
                               }
-                            ],
-                            "description": "We are currently investigating an issue affecting some services.",
-                            "status": "investigating",
-                            "update_id": "01KDCVJQ88SZPHWPTDV2Z2AZW8"
+                            ]
                           }
-                        ]
+                        ],
+                        "notify_subscribers": true
                       }
                     ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/StatusPageChangeListResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -60946,6 +63015,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -60953,83 +63025,77 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "查询状态页活跃事件列表",
-        "tags": [
-          "On-call/状态页"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |",
-          "href": "/zh/api-reference/on-call/status-pages/status-page-change-active-list",
-          "metadata": {
-            "sidebarTitle": "查询状态页活跃事件列表"
+        "parameters": [
+          {
+            "name": "page_id",
+            "in": "query",
+            "required": true,
+            "schema": {
+              "type": "integer",
+              "format": "int64"
+            },
+            "description": "状态页 ID。"
+          },
+          {
+            "name": "type",
+            "in": "query",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "enum": [
+                "incident",
+                "maintenance"
+              ]
+            },
+            "description": "事件类型筛选，必填。仅返回进行中（非终态）事件：incident 含 investigating/identified/monitoring，maintenance 含 scheduled/ongoing。"
           }
-        }
+        ]
       }
     },
     "/status-page/change/create": {
       "post": {
-        "description": "在状态页上创建新的故障或维护事件。",
         "operationId": "statusPageChangeCreate",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "description": "We are investigating degraded performance affecting the web console.",
-                "notify_subscribers": true,
-                "page_id": 5750613685214,
-                "start_at_seconds": 1712000000,
-                "status": "investigating",
-                "title": "Web Console Degraded Performance",
-                "type": "incident",
-                "updates": [
-                  {
-                    "component_changes": [
-                      {
-                        "component_id": "01KC3GAZ6ZJE40H55GM31RPWZE",
-                        "status": "degraded"
-                      }
-                    ],
-                    "description": "We are currently investigating an issue affecting some users.",
-                    "status": "investigating"
-                  }
-                ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/CreateStatusPageChangeRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "创建状态页事件",
+        "description": "在状态页上创建新的故障或维护事件。",
+        "tags": [
+          "On-call/状态页"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **状态页面事件管理**（`on-call`） |\n\n## 使用说明\n\n- `status` 以及 `updates` 中的组件状态都必须与 `type` 匹配，且每个 `component_id` 都必须是该状态页上已有的组件。\n- `updates` 必须按 `at_seconds` 非递减排列。若 `status` 为 `resolved` 或 `completed`，所有受影响组件的最终状态都必须是 `operational`。\n- `notify_subscribers` 为 `true` 时，仅针对 `updates` 中最后一条更新通知订阅者一次。\n- 维护事件开启 `auto_update_by_schedule` 后，服务端会在 `start_at_seconds` 将其从 `scheduled` 切换为 `ongoing`，在 `close_at_seconds` 从 `ongoing` 切换为 `completed`，并把受影响组件恢复为 `operational`。\n- 传入 `draft_id` 可发布由 `POST /status-page/draft/create` 存储的草稿；草稿必须指向同一状态页和 `type`，且只能发布一次。\n- 每次调用都会记录到账户审计日志，请勿在请求字段中写入敏感信息。",
+          "href": "/zh/api-reference/on-call/status-pages/status-page-change-create",
+          "metadata": {
+            "sidebarTitle": "创建状态页事件"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "change_id": 6294539747131,
-                    "change_name": "API Test Incident"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/StatusPageChangeCreateResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "change_id": 6294539747131,
+                    "change_name": "API Test Incident"
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -61037,6 +63103,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -61044,63 +63113,80 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "创建状态页事件",
-        "tags": [
-          "On-call/状态页"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **状态页面事件管理**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/status-pages/status-page-change-create",
-          "metadata": {
-            "sidebarTitle": "创建状态页事件"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CreateStatusPageChangeRequest"
+              },
+              "example": {
+                "page_id": 5750613685214,
+                "type": "incident",
+                "title": "Web Console Degraded Performance",
+                "description": "We are investigating degraded performance affecting the web console.",
+                "status": "investigating",
+                "start_at_seconds": 1712000000,
+                "notify_subscribers": true,
+                "updates": [
+                  {
+                    "status": "investigating",
+                    "description": "We are currently investigating an issue affecting some users.",
+                    "component_changes": [
+                      {
+                        "component_id": "01KC3GAZ6ZJE40H55GM31RPWZE",
+                        "status": "degraded"
+                      }
+                    ]
+                  }
+                ]
+              }
+            }
           }
         }
       }
     },
     "/status-page/change/delete": {
       "post": {
-        "description": "删除指定的状态页事件。",
         "operationId": "statusPageChangeDelete",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "change_id": 5821693893131,
-                "page_id": 5750613685214
-              },
-              "schema": {
-                "$ref": "#/components/schemas/DeleteStatusPageChangeRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "删除状态页事件",
+        "description": "删除状态页上的一个故障或维护事件。",
+        "tags": [
+          "On-call/状态页"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **状态页面事件管理**（`on-call`） |\n\n## 使用说明\n\n- 删除不存在的事件也返回成功。\n- 订阅该事件的订阅关系会被删除；自动更新的维护事件的定时状态切换会被取消。\n- 每次调用都会记录到账户审计日志，请勿在请求字段中写入敏感信息。",
+          "href": "/zh/api-reference/on-call/status-pages/status-page-change-delete",
+          "metadata": {
+            "sidebarTitle": "删除状态页事件"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -61108,6 +63194,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -61115,119 +63204,111 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "删除状态页事件",
-        "tags": [
-          "On-call/状态页"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **状态页面事件管理**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/status-pages/status-page-change-delete",
-          "metadata": {
-            "sidebarTitle": "删除状态页事件"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/DeleteStatusPageChangeRequest"
+              },
+              "example": {
+                "page_id": 5750613685214,
+                "change_id": 5821693893131
+              }
+            }
           }
         }
       }
     },
     "/status-page/change/info": {
       "get": {
-        "description": "获取状态页指定事件（故障或维护）的详细信息。",
         "operationId": "statusPageChangeInfo",
-        "parameters": [
-          {
-            "description": "状态页 ID。",
-            "in": "query",
-            "name": "page_id",
-            "required": true,
-            "schema": {
-              "format": "int64",
-              "type": "integer"
-            }
-          },
-          {
-            "description": "事件（变更）ID。",
-            "in": "query",
-            "name": "change_id",
-            "required": true,
-            "schema": {
-              "format": "int64",
-              "type": "integer"
-            }
-          }
+        "summary": "获取状态页事件详情",
+        "description": "获取状态页指定事件（故障或维护）的详细信息。",
+        "tags": [
+          "On-call/状态页"
         ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 返回全部受影响组件（包括隐藏组件）；组件名称、分组和排序取自状态页当前配置。\n- 状态页或事件不存在时返回 `ResourceNotFound`。",
+          "href": "/zh/api-reference/on-call/status-pages/status-page-change-info",
+          "metadata": {
+            "sidebarTitle": "获取状态页事件详情"
+          }
+        },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/StatusPageChangeItem"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
+                    "change_id": 5821693893131,
+                    "page_id": 5750613685214,
+                    "type": "incident",
+                    "title": "Web Console Degraded Performance",
+                    "description": "The issue has been resolved, and all services are operating normally.\n\nThank you for your patience.",
+                    "status": "resolved",
                     "affected_components": [
                       {
-                        "available_since_seconds": 1765349358,
                         "component_id": "01KC3GAZ6ZJE40H55GM31RPWZE",
+                        "section_id": "01KC3FKKX5TSVG6Z3X1QNGF6V2",
                         "name": "Web Console",
+                        "available_since_seconds": 1765349358,
                         "order_id": 1,
-                        "section_id": "01KC3FKKX5TSVG6Z3X1QNGF6V2",
                         "status": "operational"
                       }
                     ],
-                    "change_id": 5821693893131,
-                    "close_at_seconds": 1775529742,
-                    "description": "The issue has been resolved, and all services are operating normally.\n\nThank you for your patience.",
-                    "notify_subscribers": true,
-                    "page_id": 5750613685214,
                     "start_at_seconds": 1766736878,
-                    "status": "resolved",
-                    "title": "Web Console Degraded Performance",
-                    "type": "incident",
+                    "close_at_seconds": 1775529742,
                     "updates": [
                       {
+                        "update_id": "01KDCVJQ88SZPHWPTDV2Z2AZW8",
                         "at_seconds": 1766736876,
+                        "status": "investigating",
+                        "description": "We are currently investigating an issue affecting some services.",
                         "component_changes": [
                           {
                             "component_id": "01KC3GAZ6ZJE40H55GM31RPWZE",
                             "component_name": "Web Console",
                             "status": "degraded"
                           }
-                        ],
-                        "description": "We are currently investigating an issue affecting some services.",
-                        "status": "investigating",
-                        "update_id": "01KDCVJQ88SZPHWPTDV2Z2AZW8"
+                        ]
                       },
                       {
+                        "update_id": "01KNJX3KW873ZZSRZC14SGFYS3",
                         "at_seconds": 1775529742,
+                        "status": "resolved",
+                        "description": "The issue has been resolved, and all services are operating normally.",
                         "component_changes": [
                           {
                             "component_id": "01KC3GAZ6ZJE40H55GM31RPWZE",
                             "component_name": "Web Console",
                             "status": "operational"
                           }
-                        ],
-                        "description": "The issue has been resolved, and all services are operating normally.",
-                        "status": "resolved",
-                        "update_id": "01KNJX3KW873ZZSRZC14SGFYS3"
+                        ]
                       }
-                    ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/StatusPageChangeItem"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                    ],
+                    "notify_subscribers": true
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -61235,6 +63316,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -61242,246 +63326,248 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "获取状态页事件详情",
-        "tags": [
-          "On-call/状态页"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |",
-          "href": "/zh/api-reference/on-call/status-pages/status-page-change-info",
-          "metadata": {
-            "sidebarTitle": "获取状态页事件详情"
-          }
-        }
-      }
-    },
-    "/status-page/change/list": {
-      "get": {
-        "description": "查询状态页事件列表（管理端）。与公开展示接口不同，响应包含隐藏组件在内的完整数据。",
-        "operationId": "statusPageChangeList",
         "parameters": [
           {
-            "description": "状态页 ID。",
-            "in": "query",
             "name": "page_id",
-            "required": true,
-            "schema": {
-              "format": "int64",
-              "type": "integer"
-            }
-          },
-          {
-            "description": "事件活动时间窗的下界：仅返回在该 Unix 时间戳（秒）时仍未结束、或在该时刻之后结束的事件。",
-            "in": "query",
-            "name": "start_at_seconds",
-            "required": false,
-            "schema": {
-              "format": "int64",
-              "type": "integer"
-            }
-          },
-          {
-            "description": "事件活动时间窗的上界：仅返回在该 Unix 时间戳（秒）或之前开始的事件。",
             "in": "query",
-            "name": "end_at_seconds",
-            "required": false,
-            "schema": {
-              "format": "int64",
-              "type": "integer"
-            }
-          },
-          {
-            "description": "事件类型筛选条件。必填。",
-            "in": "query",
-            "name": "type",
             "required": true,
             "schema": {
-              "enum": [
-                "incident",
-                "maintenance"
-              ],
-              "type": "string"
-            }
+              "type": "integer",
+              "format": "int64"
+            },
+            "description": "状态页 ID。"
           },
           {
-            "description": "事件状态筛选条件。必填。必须是与所给 `type` 匹配的合法状态（`incident` 为 `investigating`/`identified`/`monitoring`/`resolved`；`maintenance` 为 `scheduled`/`ongoing`/`completed`）。",
+            "name": "change_id",
             "in": "query",
-            "name": "status",
             "required": true,
             "schema": {
-              "enum": [
-                "investigating",
-                "identified",
-                "monitoring",
-                "resolved",
-                "scheduled",
-                "ongoing",
-                "completed"
-              ],
-              "type": "string"
-            }
+              "type": "integer",
+              "format": "int64"
+            },
+            "description": "事件（变更）ID。"
           }
+        ]
+      }
+    },
+    "/status-page/change/list": {
+      "get": {
+        "operationId": "statusPageChangeList",
+        "summary": "查询状态页事件列表",
+        "description": "按状态和时间窗查询状态页的故障或维护事件，包含隐藏组件。",
+        "tags": [
+          "On-call/状态页"
         ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 一次返回全部匹配事件（不分页），按 `start_at_seconds` 从新到旧排序。\n- 不传 `start_at_seconds` 和 `end_at_seconds` 时不限制时间范围。",
+          "href": "/zh/api-reference/on-call/status-pages/status-page-change-list",
+          "metadata": {
+            "sidebarTitle": "查询状态页事件列表"
+          }
+        },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/StatusPageChangeListResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "items": [
                       {
+                        "change_id": 5821693893131,
+                        "page_id": 5750613685214,
+                        "type": "incident",
+                        "title": "Web Console Degraded Performance",
+                        "description": "The issue has been resolved, and all services are operating normally.",
+                        "status": "resolved",
                         "affected_components": [
                           {
-                            "available_since_seconds": 1765349358,
                             "component_id": "01KC3GAZ6ZJE40H55GM31RPWZE",
+                            "section_id": "01KC3FKKX5TSVG6Z3X1QNGF6V2",
                             "name": "Web Console",
+                            "available_since_seconds": 1765349358,
                             "order_id": 1,
-                            "section_id": "01KC3FKKX5TSVG6Z3X1QNGF6V2",
                             "status": "operational"
                           }
                         ],
-                        "change_id": 5821693893131,
-                        "close_at_seconds": 1775529742,
-                        "description": "The issue has been resolved, and all services are operating normally.",
-                        "notify_subscribers": true,
-                        "page_id": 5750613685214,
                         "start_at_seconds": 1766736878,
-                        "status": "resolved",
-                        "title": "Web Console Degraded Performance",
-                        "type": "incident",
+                        "close_at_seconds": 1775529742,
                         "updates": [
                           {
+                            "update_id": "01KDCVJQ88SZPHWPTDV2Z2AZW8",
                             "at_seconds": 1766736876,
+                            "status": "investigating",
+                            "description": "We are currently investigating an issue affecting some services.",
                             "component_changes": [
                               {
                                 "component_id": "01KC3GAZ6ZJE40H55GM31RPWZE",
                                 "component_name": "Web Console",
                                 "status": "degraded"
                               }
-                            ],
-                            "description": "We are currently investigating an issue affecting some services.",
-                            "status": "investigating",
-                            "update_id": "01KDCVJQ88SZPHWPTDV2Z2AZW8"
+                            ]
                           },
                           {
+                            "update_id": "01KNJX3KW873ZZSRZC14SGFYS3",
                             "at_seconds": 1775529742,
+                            "status": "resolved",
+                            "description": "The issue has been resolved, and all services are operating normally.",
                             "component_changes": [
                               {
                                 "component_id": "01KC3GAZ6ZJE40H55GM31RPWZE",
                                 "component_name": "Web Console",
                                 "status": "operational"
                               }
-                            ],
-                            "description": "The issue has been resolved, and all services are operating normally.",
-                            "status": "resolved",
-                            "update_id": "01KNJX3KW873ZZSRZC14SGFYS3"
+                            ]
                           }
-                        ]
+                        ],
+                        "notify_subscribers": true
                       }
                     ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/StatusPageChangeListResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                  }
                 }
               }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "429": {
+            "$ref": "#/components/responses/TooManyRequests"
+          },
+          "500": {
+            "$ref": "#/components/responses/ServerError"
+          }
+        },
+        "parameters": [
+          {
+            "name": "page_id",
+            "in": "query",
+            "required": true,
+            "schema": {
+              "type": "integer",
+              "format": "int64"
             },
-            "description": "成功"
+            "description": "状态页 ID。"
           },
-          "400": {
-            "$ref": "#/components/responses/BadRequest"
+          {
+            "name": "start_at_seconds",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "integer",
+              "format": "int64"
+            },
+            "description": "事件活动时间窗的下界：仅返回在该 Unix 时间戳（秒）时仍未结束、或在该时刻之后结束的事件。"
           },
-          "401": {
-            "$ref": "#/components/responses/Unauthorized"
+          {
+            "name": "end_at_seconds",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "integer",
+              "format": "int64"
+            },
+            "description": "事件活动时间窗的上界：仅返回在该 Unix 时间戳（秒）或之前开始的事件。"
           },
-          "429": {
-            "$ref": "#/components/responses/TooManyRequests"
+          {
+            "name": "type",
+            "in": "query",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "enum": [
+                "incident",
+                "maintenance"
+              ]
+            },
+            "description": "事件类型筛选条件。必填。"
           },
-          "500": {
-            "$ref": "#/components/responses/ServerError"
+          {
+            "name": "status",
+            "in": "query",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "enum": [
+                "investigating",
+                "identified",
+                "monitoring",
+                "resolved",
+                "scheduled",
+                "ongoing",
+                "completed"
+              ]
+            },
+            "description": "事件状态筛选条件。必填。必须是与所给 `type` 匹配的合法状态（`incident` 为 `investigating`/`identified`/`monitoring`/`resolved`；`maintenance` 为 `scheduled`/`ongoing`/`completed`）。"
           }
-        },
-        "summary": "查询状态页事件列表",
+        ]
+      }
+    },
+    "/status-page/change/timeline/create": {
+      "post": {
+        "operationId": "statusPageChangeTimelineCreate",
+        "summary": "创建事件时间线",
+        "description": "在状态页事件上添加时间线更新。",
         "tags": [
           "On-call/状态页"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |",
-          "href": "/zh/api-reference/on-call/status-pages/status-page-change-list",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **状态页面事件管理**（`on-call`） |\n\n## 使用说明\n\n- `at_seconds` 不能早于事件最新一条时间线更新的时间。\n- 与组件当前状态相同的组件变更会被丢弃，不写入该条更新。\n- 切换为 `resolved` 或 `completed` 时，所有受影响组件都必须为 `operational`；对已结束的事件发布非终态状态会重新打开该事件。\n- 事件描述会被更新为本条更新的描述。若事件开启了 `notify_subscribers`，会就本条更新通知订阅者。\n- 手动将自动更新的维护事件切换为 `ongoing` 或 `completed`，会取消对应的定时切换。\n- 传入 `draft_id` 可发布 `change_id` 指向本事件的草稿；草稿只能发布一次。\n- 每次调用都会记录到账户审计日志，请勿在请求字段中写入敏感信息。",
+          "href": "/zh/api-reference/on-call/status-pages/status-page-change-timeline-create",
           "metadata": {
-            "sidebarTitle": "查询状态页事件列表"
+            "sidebarTitle": "创建事件时间线"
           }
-        }
-      }
-    },
-    "/status-page/change/timeline/create": {
-      "post": {
-        "description": "在状态页事件上添加时间线更新。",
-        "operationId": "statusPageChangeTimelineCreate",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "at_seconds": 1712003600,
-                "change_id": 5821693893131,
-                "component_changes": [
-                  {
-                    "component_id": "01KC3GAZ6ZJE40H55GM31RPWZE",
-                    "status": "partial_outage"
-                  }
-                ],
-                "description": "We have identified the root cause and are working on a fix.",
-                "page_id": 5750613685214,
-                "status": "identified"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/CreateStatusPageChangeTimelineRequest"
-              }
-            }
-          },
-          "required": true
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "update_id": "01KP0311872NVYFRRQ82FWXAP4"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/StatusPageChangeTimelineCreateResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "update_id": "01KP0311872NVYFRRQ82FWXAP4"
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -61489,6 +63575,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -61496,64 +63585,72 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "创建事件时间线",
-        "tags": [
-          "On-call/状态页"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **状态页面事件管理**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/status-pages/status-page-change-timeline-create",
-          "metadata": {
-            "sidebarTitle": "创建事件时间线"
-          }
-        }
-      }
-    },
-    "/status-page/change/timeline/delete": {
-      "post": {
-        "description": "从状态页事件中删除时间线条目。",
-        "operationId": "statusPageChangeTimelineDelete",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CreateStatusPageChangeTimelineRequest"
+              },
               "example": {
-                "change_id": 5821693893131,
                 "page_id": 5750613685214,
-                "update_id": "01KP0311872NVYFRRQ82FWXAP4"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/DeleteStatusPageChangeTimelineRequest"
+                "change_id": 5821693893131,
+                "status": "identified",
+                "description": "We have identified the root cause and are working on a fix.",
+                "at_seconds": 1712003600,
+                "component_changes": [
+                  {
+                    "component_id": "01KC3GAZ6ZJE40H55GM31RPWZE",
+                    "status": "partial_outage"
+                  }
+                ]
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/status-page/change/timeline/delete": {
+      "post": {
+        "operationId": "statusPageChangeTimelineDelete",
+        "summary": "删除事件时间线",
+        "description": "从状态页事件中删除一条时间线更新。",
+        "tags": [
+          "On-call/状态页"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **状态页面事件管理**（`on-call`） |\n\n## 使用说明\n\n- 最新一条时间线更新不能删除，否则返回 `InvalidParameter`。\n- 删除后，事件的状态、描述、结束时间和受影响组件会根据剩余更新重新计算。\n- 事件不存在时返回成功；事件存在但 `update_id` 不存在时返回 `ResourceNotFound`。\n- 每次调用都会记录到账户审计日志，请勿在请求字段中写入敏感信息。",
+          "href": "/zh/api-reference/on-call/status-pages/status-page-change-timeline-delete",
+          "metadata": {
+            "sidebarTitle": "删除事件时间线"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -61561,6 +63658,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -61568,66 +63668,64 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "删除事件时间线",
-        "tags": [
-          "On-call/状态页"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **状态页面事件管理**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/status-pages/status-page-change-timeline-delete",
-          "metadata": {
-            "sidebarTitle": "删除事件时间线"
-          }
-        }
-      }
-    },
-    "/status-page/change/timeline/update": {
-      "post": {
-        "description": "更新状态页事件的时间线条目。",
-        "operationId": "statusPageChangeTimelineUpdate",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/DeleteStatusPageChangeTimelineRequest"
+              },
               "example": {
-                "at_seconds": 1712003600,
-                "change_id": 5821693893131,
-                "description": "Corrected description: root cause identified in database layer.",
                 "page_id": 5750613685214,
+                "change_id": 5821693893131,
                 "update_id": "01KP0311872NVYFRRQ82FWXAP4"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/UpdateStatusPageChangeTimelineRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/status-page/change/timeline/update": {
+      "post": {
+        "operationId": "statusPageChangeTimelineUpdate",
+        "summary": "更新事件时间线",
+        "description": "修改状态页事件时间线更新的时间或描述。",
+        "tags": [
+          "On-call/状态页"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **状态页面事件管理**（`on-call`） |\n\n## 使用说明\n\n- 只能修改 `at_seconds` 和 `description`；更新的状态和组件变更不可修改。\n- `at_seconds`（大于 0）与非空 `description` 至少传一个，否则返回 `InvalidParameter`。\n- `at_seconds` 必须介于前一条与后一条更新之间；修改第一条更新的时间会同步修改事件开始时间。\n- 修改最新一条更新的描述会同步更新事件描述。本接口不会通知订阅者。\n- 每次调用都会记录到账户审计日志，请勿在请求字段中写入敏感信息。",
+          "href": "/zh/api-reference/on-call/status-pages/status-page-change-timeline-update",
+          "metadata": {
+            "sidebarTitle": "更新事件时间线"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -61635,6 +63733,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -61642,64 +63743,66 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "更新事件时间线",
-        "tags": [
-          "On-call/状态页"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **状态页面事件管理**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/status-pages/status-page-change-timeline-update",
-          "metadata": {
-            "sidebarTitle": "更新事件时间线"
-          }
-        }
-      }
-    },
-    "/status-page/change/update": {
-      "post": {
-        "description": "更新已有状态页事件。",
-        "operationId": "statusPageChangeUpdate",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/UpdateStatusPageChangeTimelineRequest"
+              },
               "example": {
-                "change_id": 5821693893131,
                 "page_id": 5750613685214,
-                "title": "Web Console Degraded Performance (Updated)"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/UpdateStatusPageChangeRequest"
+                "change_id": 5821693893131,
+                "update_id": "01KP0311872NVYFRRQ82FWXAP4",
+                "description": "Corrected description: root cause identified in database layer.",
+                "at_seconds": 1712003600
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/status-page/change/update": {
+      "post": {
+        "operationId": "statusPageChangeUpdate",
+        "summary": "更新状态页事件",
+        "description": "更新状态页事件的标题、负责人或关联事件。",
+        "tags": [
+          "On-call/状态页"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **状态页面事件管理**（`on-call`） |\n\n## 使用说明\n\n- 状态、描述和组件影响无法通过本接口修改，请调用 `POST /status-page/change/timeline/create` 发布时间线更新。\n- `responders` 或 `linked_changes` 省略或为空数组时保留原列表，因此无法通过本接口清空。\n- 每次调用都会记录到账户审计日志，请勿在请求字段中写入敏感信息。",
+          "href": "/zh/api-reference/on-call/status-pages/status-page-change-update",
+          "metadata": {
+            "sidebarTitle": "更新状态页事件"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -61707,6 +63810,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -61714,65 +63820,64 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "更新状态页事件",
-        "tags": [
-          "On-call/状态页"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **状态页面事件管理**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/status-pages/status-page-change-update",
-          "metadata": {
-            "sidebarTitle": "更新状态页事件"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/UpdateStatusPageChangeRequest"
+              },
+              "example": {
+                "page_id": 5750613685214,
+                "change_id": 5821693893131,
+                "title": "Web Console Degraded Performance (Updated)"
+              }
+            }
           }
         }
       }
     },
     "/status-page/component/delete": {
       "post": {
-        "description": "从状态页删除服务组件。",
         "operationId": "statusPageComponentDelete",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "component_ids": [
-                  "01KP032KMN9YFBMPWANJMFZFG1"
-                ],
-                "page_id": 5750613685214
-              },
-              "schema": {
-                "$ref": "#/components/schemas/DeleteStatusPageComponentRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "删除状态页组件",
+        "description": "从状态页批量删除服务组件。",
+        "tags": [
+          "On-call/状态页"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **状态页面管理**（`on-call`） |\n\n## 使用说明\n\n- `component_ids` 中任一 ID 不存在于该状态页时，不会删除任何组件，但接口仍返回成功。\n- 订阅了被删除组件的订阅关系会被一并删除。\n- 每次调用都会记录到账户审计日志，请勿在请求字段中写入敏感信息。",
+          "href": "/zh/api-reference/on-call/status-pages/status-page-component-delete",
+          "metadata": {
+            "sidebarTitle": "删除状态页组件"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -61780,6 +63885,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -61787,74 +63895,69 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "删除状态页组件",
-        "tags": [
-          "On-call/状态页"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **状态页面管理**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/status-pages/status-page-component-delete",
-          "metadata": {
-            "sidebarTitle": "删除状态页组件"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/DeleteStatusPageComponentRequest"
+              },
+              "example": {
+                "page_id": 5750613685214,
+                "component_ids": [
+                  "01KP032KMN9YFBMPWANJMFZFG1"
+                ]
+              }
+            }
           }
         }
       }
     },
     "/status-page/component/upsert": {
       "post": {
-        "description": "在状态页上创建或更新服务组件。",
         "operationId": "statusPageComponentUpsert",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "components": [
-                  {
-                    "description": "Main web interface",
-                    "name": "Web Console",
-                    "order_id": 1,
-                    "section_id": "01KC3FKKX5TSVG6Z3X1QNGF6V2"
-                  }
-                ],
-                "page_id": 5750613685214
-              },
-              "schema": {
-                "$ref": "#/components/schemas/UpsertStatusPageComponentRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "创建或更新状态页组件",
+        "description": "在状态页上批量创建或更新服务组件。",
+        "tags": [
+          "On-call/状态页"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **状态页面管理**（`on-call`） |\n\n## 使用说明\n\n- 不带 `component_id` 的条目会创建组件；带 `component_id` 的条目更新对应组件。\n- 更新会用请求值覆盖 `name`、`description`、`section_id`、`order_id`、`hide_uptime` 和 `hide_all`，未传字段会被重置（不传 `section_id` 会把组件移到顶层）；更新时忽略 `available_since_seconds`。\n- 组件名称在状态页内必须唯一，`section_id` 必须是已有分组；任一条目无效则整个请求失败。\n- 每次调用都会记录到账户审计日志，请勿在请求字段中写入敏感信息。",
+          "href": "/zh/api-reference/on-call/status-pages/status-page-component-upsert",
+          "metadata": {
+            "sidebarTitle": "创建或更新状态页组件"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "component_ids": [
-                      "01KP032KMN9YFBMPWANJMFZFG1"
-                    ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/UpsertStatusPageComponentResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "component_ids": [
+                      "01KP032KMN9YFBMPWANJMFZFG1"
+                    ]
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -61862,6 +63965,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -61869,70 +63975,74 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "创建或更新状态页组件",
-        "tags": [
-          "On-call/状态页"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **状态页面管理**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/status-pages/status-page-component-upsert",
-          "metadata": {
-            "sidebarTitle": "创建或更新状态页组件"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/UpsertStatusPageComponentRequest"
+              },
+              "example": {
+                "page_id": 5750613685214,
+                "components": [
+                  {
+                    "name": "Web Console",
+                    "description": "Main web interface",
+                    "section_id": "01KC3FKKX5TSVG6Z3X1QNGF6V2",
+                    "order_id": 1
+                  }
+                ]
+              }
+            }
           }
         }
       }
     },
     "/status-page/create": {
       "post": {
-        "description": "创建一个新的状态页。",
         "operationId": "statusPageCreate",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "contact_info": "mailto:support@example.com",
-                "name": "My Status Page",
-                "page_header": "Welcome to our status page",
-                "type": "public",
-                "url_name": "my-status-page"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/CreateStatusPageRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "创建状态页",
+        "description": "为账户创建一个公开或内部状态页。",
+        "tags": [
+          "On-call/状态页"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **状态页面管理**（`on-call`） |\n\n## 使用说明\n\n- 状态页数量受 On-call 套餐限制：公开页免费版和标准版 1 个、专业版 5 个；内部页仅专业版可用，最多 20 个。超出返回 `InvalidParameter`。\n- `url_name` 会被规范化为小写 slug，且在账户内同类型状态页中必须唯一；响应中的 `page_url_name` 为最终值。\n- 公开页只支持邮件订阅，且只有公开页可设置 `custom_domain`；内部页只支持 IM 订阅。\n- 每次调用都会记录到账户审计日志，请勿在请求字段中写入敏感信息。",
+          "href": "/zh/api-reference/on-call/status-pages/status-page-create",
+          "metadata": {
+            "sidebarTitle": "创建状态页"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "page_id": 6294565612043,
-                    "page_name": "My Status Page",
-                    "page_url_name": "my-status-page"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/CreateStatusPageResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "page_id": 6294565612043,
+                    "page_name": "My Status Page",
+                    "page_url_name": "my-status-page"
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -61940,6 +64050,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -61947,62 +64060,72 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "创建状态页",
-        "tags": [
-          "On-call/状态页"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **状态页面管理**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/status-pages/status-page-create",
-          "metadata": {
-            "sidebarTitle": "创建状态页"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CreateStatusPageRequest"
+              },
+              "example": {
+                "name": "My Status Page",
+                "url_name": "my-status-page",
+                "type": "public",
+                "date_view": "list",
+                "display_uptime_mode": "chart_and_percentage",
+                "page_header": "Welcome to our status page",
+                "contact_info": "mailto:support@example.com",
+                "subscription": {
+                  "email": true,
+                  "im": false
+                }
+              }
+            }
           }
         }
       }
     },
     "/status-page/delete": {
       "post": {
-        "description": "删除指定的状态页。",
         "operationId": "statusPageDelete",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "page_id": 5750613685214
-              },
-              "schema": {
-                "$ref": "#/components/schemas/DeleteStatusPageRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "删除状态页",
+        "description": "删除状态页及其全部事件和订阅。",
+        "tags": [
+          "On-call/状态页"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **状态页面管理**（`on-call`） |\n\n## 使用说明\n\n- 删除不存在的状态页也返回成功。\n- 状态页的事件和订阅会在接口返回后于后台删除。\n- 每次调用都会记录到账户审计日志，请勿在请求字段中写入敏感信息。",
+          "href": "/zh/api-reference/on-call/status-pages/status-page-delete",
+          "metadata": {
+            "sidebarTitle": "删除状态页"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -62010,6 +64133,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -62017,78 +64143,65 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "删除状态页",
-        "tags": [
-          "On-call/状态页"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **状态页面管理**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/status-pages/status-page-delete",
-          "metadata": {
-            "sidebarTitle": "删除状态页"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/DeleteStatusPageRequest"
+              },
+              "example": {
+                "page_id": 5750613685214
+              }
+            }
           }
         }
       }
     },
     "/status-page/draft/create": {
       "post": {
-        "description": "存储状态页事件草稿，供人工在控制台审核后发布。",
         "operationId": "statusPageDraftCreate",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "draft": {
-                  "affected_components": [
-                    {
-                      "component_id": "01KC3GAZ6ZJE40H55GM31RPWZE",
-                      "status": "degraded"
-                    }
-                  ],
-                  "message": "We are investigating degraded performance affecting the web console.",
-                  "name": "Web Console Degraded Performance",
-                  "page_id": 5750613685214,
-                  "type": "incident",
-                  "v": 1
-                },
-                "source": "ai_sre:sess_01KC3H2A9ZQ8W7E6R5T4Y3U2I1"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/CreateStatusPageDraftRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "创建状态页草稿",
+        "description": "存储状态页事件草稿，供人工在控制台审核后发布。",
+        "tags": [
+          "On-call/状态页"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **状态页面事件管理**（`on-call`） |\n\n## 使用说明\n\n- `draft` 载荷将被原样存储（最大 64 KB）；控制台发布表单会读取它来预填事件内容。\n- `draft.page_id` 必须是调用方账户下的状态页，`draft.affected_components` 中的组件必须存在于该页，`draft.change_id` 大于 0 时必须指向同一 `type` 的事件。\n- 发布时将 `draft_id` 传给 `POST /status-page/change/create`（新事件）或 `POST /status-page/change/timeline/create`（向 `draft.change_id` 追加更新）；草稿只能发布一次。\n- 草稿创建 30 天后删除，无论是否已发布。\n- 每次调用都会记录到账户审计日志，请勿在请求字段中写入敏感信息。",
+          "href": "/zh/api-reference/on-call/status-pages/status-page-draft-create",
+          "metadata": {
+            "sidebarTitle": "创建状态页草稿"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "created_at": 1788000000,
-                    "draft_id": "draft_3xK9mQ2vN7pR4wT8yH1sJ5"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/StatusPageDraftCreateResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "draft_id": "draft_3xK9mQ2vN7pR4wT8yH1sJ5",
+                    "created_at": 1788000000
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -62096,6 +64209,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -62103,75 +64219,107 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "创建状态页草稿",
-        "tags": [
-          "On-call/状态页"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 任意有效 `app_key` 均可调用 |\n\n## 使用说明\n\n- `draft` 载荷将被原样存储（最大 64 KB）；控制台发布表单会读取它来预填事件内容。\n- 草稿保留 30 天，事件发布时被消费且仅可消费一次。\n- 每次调用都会记录到账户审计日志，请勿在请求字段中写入敏感信息。",
-          "href": "/zh/api-reference/on-call/status-pages/status-page-draft-create",
-          "metadata": {
-            "sidebarTitle": "创建状态页草稿"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CreateStatusPageDraftRequest"
+              },
+              "example": {
+                "draft": {
+                  "v": 1,
+                  "page_id": 5750613685214,
+                  "type": "incident",
+                  "name": "Web Console Degraded Performance",
+                  "message": "We are investigating degraded performance affecting the web console.",
+                  "affected_components": [
+                    {
+                      "component_id": "01KC3GAZ6ZJE40H55GM31RPWZE",
+                      "status": "degraded"
+                    }
+                  ]
+                },
+                "source": "ai_sre:sess_01KC3H2A9ZQ8W7E6R5T4Y3U2I1"
+              }
+            }
           }
         }
       }
     },
     "/status-page/info": {
       "get": {
-        "description": "获取指定状态页的详细配置信息。",
         "operationId": "statusPageInfo",
-        "parameters": [
-          {
-            "description": "状态页 ID。",
-            "in": "query",
-            "name": "page_id",
-            "required": true,
-            "schema": {
-              "format": "int64",
-              "type": "integer"
-            }
-          }
+        "summary": "获取状态页详情",
+        "description": "获取指定状态页的详细配置信息。",
+        "tags": [
+          "On-call/状态页"
         ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |",
+          "href": "/zh/api-reference/on-call/status-pages/status-page-info",
+          "metadata": {
+            "sidebarTitle": "获取状态页详情"
+          }
+        },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/StatusPageInfoResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
-                    "components": [
-                      {
-                        "available_since_seconds": 1765349358,
-                        "component_id": "01KC3GAZ6ZJE40H55GM31RPWZE",
-                        "name": "Web Console",
-                        "order_id": 1,
-                        "section_id": "01KC3FKKX5TSVG6Z3X1QNGF6V2"
-                      }
-                    ],
-                    "contact_info": "mailto:support@example.com",
+                    "page_id": 5750613685214,
+                    "name": "Flashduty Status Page",
+                    "url_name": "flashduty-statuspage",
+                    "type": "public",
                     "custom_domain": "status.example.com",
+                    "logo": "https://cdn.example.com/logo.png",
+                    "favicon": "https://cdn.example.com/favicon.png",
+                    "page_header": "Welcome to our status page",
+                    "page_footer": "2025 Example Corp",
+                    "date_view": "list",
+                    "display_uptime_mode": "chart_and_percentage",
                     "custom_links": [
                       {
                         "key": "Documentation",
                         "value": "https://docs.example.com"
                       }
                     ],
-                    "date_view": "list",
-                    "display_uptime_mode": "chart_and_percentage",
-                    "favicon": "https://cdn.example.com/favicon.png",
-                    "logo": "https://cdn.example.com/logo.png",
-                    "managed_domain_feature_enabled": true,
-                    "name": "Flashduty Status Page",
-                    "page_footer": "2025 Example Corp",
-                    "page_header": "Welcome to our status page",
-                    "page_id": 5750613685214,
+                    "contact_info": "mailto:support@example.com",
+                    "components": [
+                      {
+                        "component_id": "01KC3GAZ6ZJE40H55GM31RPWZE",
+                        "section_id": "01KC3FKKX5TSVG6Z3X1QNGF6V2",
+                        "name": "Web Console",
+                        "available_since_seconds": 1765349358,
+                        "order_id": 1
+                      }
+                    ],
                     "sections": [
                       {
-                        "description": "Our core services",
-                        "hide_all": false,
-                        "hide_uptime": false,
+                        "section_id": "01KC3FKKX5TSVG6Z3X1QNGF6V2",
                         "name": "Core Services",
+                        "description": "Our core services",
                         "order_id": 1,
-                        "section_id": "01KC3FKKX5TSVG6Z3X1QNGF6V2"
+                        "hide_uptime": false,
+                        "hide_all": false
                       }
                     ],
                     "subscription": {
@@ -62179,29 +64327,11 @@
                       "im": false
                     },
                     "template_preference": "message",
-                    "type": "public",
-                    "url_name": "flashduty-statuspage"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/StatusPageInfoResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                    "managed_domain_feature_enabled": true
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -62209,6 +64339,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -62216,95 +64349,169 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "获取状态页详情",
-        "tags": [
-          "On-call/状态页"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |",
-          "href": "/zh/api-reference/on-call/status-pages/status-page-info",
-          "metadata": {
-            "sidebarTitle": "获取状态页详情"
+        "parameters": [
+          {
+            "name": "page_id",
+            "in": "query",
+            "required": true,
+            "schema": {
+              "type": "integer",
+              "format": "int64"
+            },
+            "description": "状态页 ID。"
           }
-        }
+        ]
       }
     },
     "/status-page/list": {
       "get": {
-        "description": "查询账户下所有状态页，包含其组件与分组。",
         "operationId": "status-page-read-page-list",
+        "summary": "查询状态页列表",
+        "description": "查询账户下所有状态页，包含其组件与分组。",
+        "tags": [
+          "On-call/状态页"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 一次返回全部公开页和内部页（不分页），按创建时间从新到旧排序。",
+          "href": "/zh/api-reference/on-call/status-pages/status-page-read-page-list",
+          "metadata": {
+            "sidebarTitle": "查询状态页列表"
+          }
+        },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/ListStatusPageResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "items": [
                       {
-                        "components": [
+                        "page_id": 5750613685214,
+                        "name": "Example Status",
+                        "url_name": "example-status",
+                        "type": "public",
+                        "custom_domain": "status.example.com",
+                        "logo_url": "https://www.example.com",
+                        "page_header": "Example System Status",
+                        "date_view": "calendar",
+                        "display_uptime_mode": "chart_and_percentage",
+                        "custom_links": [
                           {
-                            "available_since_seconds": 1716962400,
-                            "component_id": "cmp_001",
-                            "description": "Core API service",
-                            "hide_all": false,
-                            "hide_uptime": false,
-                            "name": "API",
-                            "order_id": 1,
-                            "section_id": "sec_001"
+                            "key": "Home",
+                            "value": "https://www.example.com"
                           }
                         ],
-                        "contact_info": "mailto:support@acme.com",
-                        "custom_domain": "status.acme.com",
-                        "custom_links": [
+                        "contact_info": "mailto:support@example.com",
+                        "components": [
                           {
-                            "name": "Home",
-                            "url": "https://acme.com"
+                            "component_id": "01KC3GAZ6ZJE40H55GM31RPWZE",
+                            "section_id": "01KC3FKKX5TSVG6Z3X1QNGF6V2",
+                            "name": "API",
+                            "description": "Core API service",
+                            "available_since_seconds": 1716962400,
+                            "order_id": 1
                           }
                         ],
-                        "date_view": "calendar",
-                        "display_uptime_mode": "chart_and_percentage",
-                        "logo_url": "https://acme.com",
-                        "name": "Acme Status",
-                        "page_header": "Acme System Status",
-                        "page_id": 7001,
                         "sections": [
                           {
-                            "hide_all": false,
-                            "hide_uptime": false,
+                            "section_id": "01KC3FKKX5TSVG6Z3X1QNGF6V2",
                             "name": "Core Services",
+                            "description": "",
                             "order_id": 1,
-                            "section_id": "sec_001"
+                            "hide_uptime": false,
+                            "hide_all": false
                           }
                         ],
                         "subscription": {
                           "email": true,
                           "im": false
                         },
-                        "type": "public",
-                        "url_name": "acme"
+                        "template_preference": "message"
                       }
                     ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "429": {
+            "$ref": "#/components/responses/TooManyRequests"
+          },
+          "500": {
+            "$ref": "#/components/responses/ServerError"
+          }
+        }
+      }
+    },
+    "/status-page/migrate-email-subscribers": {
+      "post": {
+        "operationId": "statusPageMigrateEmailSubscribers",
+        "summary": "迁移邮件订阅者",
+        "description": "启动迁移任务，从 Atlassian Statuspage 将邮件订阅者导入到已有的 Flashduty 状态页。",
+        "tags": [
+          "On-call/状态页"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **30 次/分钟**；**2 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 需要 On-call 专业版套餐，否则返回 `AccessDenied`。\n- 异步执行并返回 `job_id`，请轮询 `GET /status-page/migration/status`。每个账户同一时间只能运行一个迁移任务。\n- 请在对同一源页面执行 `POST /status-page/migrate-structure` 之后调用：组件订阅会映射到结构迁移创建的组件，无法映射的订阅者改为订阅全部组件。\n- 非邮件、已隔离或无邮箱地址的订阅者会被跳过并计入 `progress.subscribers_skipped`；目标页上已存在的接收人保持不变。\n- 每次调用都会记录到账户审计日志，请勿在请求字段中写入敏感信息。",
+          "href": "/zh/api-reference/on-call/status-pages/status-page-migrate-email-subscribers",
+          "metadata": {
+            "sidebarTitle": "迁移邮件订阅者"
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "成功",
+            "content": {
+              "application/json": {
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/ListStatusPageResponse"
+                          "$ref": "#/components/schemas/StatusPageMigrationStartResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "job_id": "01KP0311872NVYFRRQ82FW0002"
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -62312,6 +64519,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -62319,66 +64529,66 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "查询状态页列表",
-        "tags": [
-          "On-call/状态页"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n",
-          "href": "/zh/api-reference/on-call/status-pages/status-page-read-page-list",
-          "metadata": {
-            "sidebarTitle": "查询状态页列表"
-          }
-        }
-      }
-    },
-    "/status-page/migrate-email-subscribers": {
-      "post": {
-        "description": "启动迁移任务，从 Atlassian Statuspage 将邮件订阅者导入到已有的 Flashduty 状态页。",
-        "operationId": "statusPageMigrateEmailSubscribers",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/MigrateStatusPageEmailSubscribersRequest"
+              },
               "example": {
                 "api_key": "sk-stsp-xxxxxxxxxxxxxxxxxxxx",
                 "source_page_id": "abcdefghij",
                 "target_page_id": 5750613685214
-              },
-              "schema": {
-                "$ref": "#/components/schemas/MigrateStatusPageEmailSubscribersRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/status-page/migrate-structure": {
+      "post": {
+        "operationId": "statusPageMigrateStructure",
+        "summary": "迁移状态页结构",
+        "description": "启动迁移任务，从 Atlassian Statuspage 导入结构和历史事件到新的 Flashduty 状态页。",
+        "tags": [
+          "On-call/状态页"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **30 次/分钟**；**2 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 需要 On-call 专业版套餐，否则返回 `AccessDenied`。\n- 异步执行：接口校验 API Key 和源页面后返回 `job_id`，导入在后台进行；请轮询 `GET /status-page/migration/status`。\n- 每个账户同一时间只能运行一个迁移任务，再次发起返回 `InvalidParameter`。\n- 会创建一个开启邮件订阅的公开状态页；对同一源页面再次执行时复用之前创建的状态页。\n- 导入分组（来自组件组）、组件、历史故障与维护以及故障模板；模板导入失败只记入 `progress.warnings`，不会导致任务失败。\n- 每次调用都会记录到账户审计日志，请勿在请求字段中写入敏感信息。",
+          "href": "/zh/api-reference/on-call/status-pages/status-page-migrate-structure",
+          "metadata": {
+            "sidebarTitle": "迁移状态页结构"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "job_id": "01KP0311872NVYFRRQ82FW0002"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/StatusPageMigrationStartResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "job_id": "01KP0311872NVYFRRQ82FW0001"
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -62386,72 +64596,73 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
           "500": {
-            "$ref": "#/components/responses/ServerError"
-          }
-        },
-        "summary": "迁移邮件订阅者",
-        "tags": [
-          "On-call/状态页"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **状态页面管理**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/status-pages/status-page-migrate-email-subscribers",
-          "metadata": {
-            "sidebarTitle": "迁移邮件订阅者"
-          }
-        }
-      }
-    },
-    "/status-page/migrate-structure": {
-      "post": {
-        "description": "启动迁移任务，从 Atlassian Statuspage 导入结构和历史事件到新的 Flashduty 状态页。",
-        "operationId": "statusPageMigrateStructure",
+            "$ref": "#/components/responses/ServerError"
+          }
+        },
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/MigrateStatusPageStructureRequest"
+              },
               "example": {
                 "api_key": "sk-stsp-xxxxxxxxxxxxxxxxxxxx",
                 "source_page_id": "abcdefghij"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/MigrateStatusPageStructureRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/status-page/migration/cancel": {
+      "post": {
+        "operationId": "statusPageMigrationCancel",
+        "summary": "取消状态页迁移",
+        "description": "取消正在运行的 Atlassian Statuspage 迁移任务。",
+        "tags": [
+          "On-call/状态页"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 只有 `status` 为 `running` 的任务可以取消，否则返回 `InvalidParameter`。\n- 任务会立即标记为 `cancelled`，账户可随即发起新的迁移；已导入的数据会保留。\n- 每次调用都会记录到账户审计日志，请勿在请求字段中写入敏感信息。",
+          "href": "/zh/api-reference/on-call/status-pages/status-page-migration-cancel",
+          "metadata": {
+            "sidebarTitle": "取消状态页迁移"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "job_id": "01KP0311872NVYFRRQ82FW0001"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/StatusPageMigrationStartResponse"
+                          "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -62459,6 +64670,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -62466,62 +64680,82 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "迁移状态页结构",
-        "tags": [
-          "On-call/状态页"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **状态页面管理**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/status-pages/status-page-migrate-structure",
-          "metadata": {
-            "sidebarTitle": "迁移状态页结构"
-          }
-        }
-      }
-    },
-    "/status-page/migration/cancel": {
-      "post": {
-        "description": "取消正在进行的状态页迁移任务。只能取消处于 `running` 状态的任务。",
-        "operationId": "statusPageMigrationCancel",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {
-                "job_id": "01KP0311872NVYFRRQ82FW0001"
-              },
               "schema": {
                 "$ref": "#/components/schemas/CancelStatusPageMigrationRequest"
+              },
+              "example": {
+                "job_id": "01KP0311872NVYFRRQ82FW0001"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/status-page/migration/status": {
+      "get": {
+        "operationId": "statusPageMigrationStatus",
+        "summary": "获取迁移状态",
+        "description": "获取状态页迁移任务的当前状态和进度。",
+        "tags": [
+          "On-call/状态页"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 轮询直到 `status` 不再是 `running`；`progress.completed_steps` 与 `progress.total_steps` 之比表示任务进度。\n- 任务状态在最后一次更新后保留 24 小时，过期后调用返回 `ResourceNotFound`。\n- `job_id` 属于其他账户时返回 `AccessDenied`。",
+          "href": "/zh/api-reference/on-call/status-pages/status-page-migration-status",
+          "metadata": {
+            "sidebarTitle": "获取迁移状态"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/EmptyResponse"
+                          "$ref": "#/components/schemas/StatusPageMigrationJob"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "job_id": "01KP0311872NVYFRRQ82FW0001",
+                    "account_id": 2451002751131,
+                    "source_page_id": "abcdefghij",
+                    "target_page_id": 5750613685214,
+                    "phase": "history",
+                    "status": "completed",
+                    "progress": {
+                      "total_steps": 5,
+                      "completed_steps": 5,
+                      "components_imported": 8,
+                      "sections_imported": 3,
+                      "incidents_imported": 12,
+                      "maintenances_imported": 2,
+                      "subscribers_imported": 0,
+                      "templates_imported": 0,
+                      "subscribers_skipped": 0
+                    },
+                    "created_at": 1766736878,
+                    "updated_at": 1766740000
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -62529,6 +64763,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -62536,80 +64773,60 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "取消状态页迁移",
-        "tags": [
-          "On-call/状态页"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **状态页面管理**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/status-pages/status-page-migration-cancel",
-          "metadata": {
-            "sidebarTitle": "取消状态页迁移"
-          }
-        }
-      }
-    },
-    "/status-page/migration/status": {
-      "get": {
-        "description": "获取状态页迁移任务的当前状态和进度。",
-        "operationId": "statusPageMigrationStatus",
         "parameters": [
           {
-            "description": "由 `migrate-structure` 或 `migrate-email-subscribers` 返回的迁移任务 ID。",
-            "in": "query",
             "name": "job_id",
+            "in": "query",
             "required": true,
             "schema": {
               "type": "string"
-            }
+            },
+            "description": "由 `migrate-structure` 或 `migrate-email-subscribers` 返回的迁移任务 ID。"
           }
+        ]
+      }
+    },
+    "/status-page/section/delete": {
+      "post": {
+        "operationId": "statusPageSectionDelete",
+        "summary": "删除状态页区域",
+        "description": "从状态页批量删除分组，分组内的组件会移到顶层。",
+        "tags": [
+          "On-call/状态页"
         ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **状态页面管理**（`on-call`） |\n\n## 使用说明\n\n- `section_ids` 中任一 ID 不存在于该状态页时，不会删除任何分组，但接口仍返回成功。\n- 被删除分组中的组件会保留并移到顶层。\n- 每次调用都会记录到账户审计日志，请勿在请求字段中写入敏感信息。",
+          "href": "/zh/api-reference/on-call/status-pages/status-page-section-delete",
+          "metadata": {
+            "sidebarTitle": "删除状态页区域"
+          }
+        },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "account_id": 2451002751131,
-                    "created_at": 1766736878,
-                    "job_id": "01KP0311872NVYFRRQ82FW0001",
-                    "phase": "history",
-                    "progress": {
-                      "completed_steps": 5,
-                      "components_imported": 8,
-                      "incidents_imported": 12,
-                      "maintenances_imported": 2,
-                      "sections_imported": 3,
-                      "subscribers_imported": 0,
-                      "subscribers_skipped": 0,
-                      "templates_imported": 0,
-                      "total_steps": 5
-                    },
-                    "source_page_id": "abcdefghij",
-                    "status": "completed",
-                    "target_page_id": 5750613685214,
-                    "updated_at": 1766740000
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/StatusPageMigrationJob"
+                          "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -62617,6 +64834,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -62624,65 +64844,69 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "获取迁移状态",
-        "tags": [
-          "On-call/状态页"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |",
-          "href": "/zh/api-reference/on-call/status-pages/status-page-migration-status",
-          "metadata": {
-            "sidebarTitle": "获取迁移状态"
-          }
-        }
-      }
-    },
-    "/status-page/section/delete": {
-      "post": {
-        "description": "从状态页删除区域。",
-        "operationId": "statusPageSectionDelete",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/DeleteStatusPageSectionRequest"
+              },
               "example": {
                 "page_id": 5750613685214,
                 "section_ids": [
                   "01KP032J1FV2H8DDGN0QSJ1CAR"
                 ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/DeleteStatusPageSectionRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/status-page/section/upsert": {
+      "post": {
+        "operationId": "statusPageSectionUpsert",
+        "summary": "创建或更新状态页区域",
+        "description": "在状态页上批量创建或更新用于组织组件的分组。",
+        "tags": [
+          "On-call/状态页"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **状态页面管理**（`on-call`） |\n\n## 使用说明\n\n- 不带 `section_id` 的条目会创建分组；带 `section_id` 的条目更新对应分组。\n- 更新会用请求值覆盖 `name`、`description`、`order_id`、`hide_uptime` 和 `hide_all`，未传字段会被重置。\n- 分组名称在状态页内必须唯一；任一条目无效则整个请求失败。\n- 每次调用都会记录到账户审计日志，请勿在请求字段中写入敏感信息。",
+          "href": "/zh/api-reference/on-call/status-pages/status-page-section-upsert",
+          "metadata": {
+            "sidebarTitle": "创建或更新状态页区域"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/EmptyResponse"
+                          "$ref": "#/components/schemas/UpsertStatusPageSectionResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "section_ids": [
+                      "01KP032J1FV2H8DDGN0QSJ1CAR"
+                    ]
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -62690,6 +64914,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -62697,73 +64924,54 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "删除状态页区域",
-        "tags": [
-          "On-call/状态页"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **状态页面管理**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/status-pages/status-page-section-delete",
-          "metadata": {
-            "sidebarTitle": "删除状态页区域"
-          }
-        }
-      }
-    },
-    "/status-page/section/upsert": {
-      "post": {
-        "description": "在状态页上创建或更新区域。",
-        "operationId": "statusPageSectionUpsert",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/UpsertStatusPageSectionRequest"
+              },
               "example": {
                 "page_id": 5750613685214,
                 "sections": [
                   {
-                    "description": "Our core services",
                     "name": "Core Services",
+                    "description": "Our core services",
                     "order_id": 1
                   }
                 ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/UpsertStatusPageSectionRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/status-page/subscriber/export": {
+      "post": {
+        "operationId": "statusPageSubscriberExport",
+        "summary": "导出订阅者",
+        "description": "以 CSV 文件导出状态页的订阅者。",
+        "tags": [
+          "On-call/状态页"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **100 次/天**；**20 次/分钟**；**10 次/秒** |\n| 权限要求 | **状态页面管理**（`on-call`） |\n\n## 使用说明\n\n- 需要 On-call 标准版及以上套餐，否则返回 `AccessDenied`。\n- 响应为 `text/csv` 附件而非 JSON 信封，列依次为 Method、Recipient、Components、Subscribe All（`Yes`/`No`）、Locale。\n- Components 列为以 `, ` 连接的组件名；位于分组内的组件写作 `分组名 › 组件名`。\n- 公开页导出邮件订阅者，内部页导出 IM 订阅者；按 `component_ids` 过滤时也会包含订阅了全部组件的订阅者。",
+          "href": "/zh/api-reference/on-call/status-pages/status-page-subscriber-export",
+          "metadata": {
+            "sidebarTitle": "导出订阅者"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功。CSV 附件，非 JSON 信封。",
             "content": {
-              "application/json": {
-                "example": {
-                  "data": {
-                    "section_ids": [
-                      "01KP032J1FV2H8DDGN0QSJ1CAR"
-                    ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
+              "text/csv": {
                 "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/UpsertStatusPageSectionResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
-                }
+                  "$ref": "#/components/schemas/StatusPageSubscriberExportResponse"
+                },
+                "example": "Method,Recipient,Components,Subscribe All,Locale\nemail,alice@example.com,,Yes,zh-CN\nemail,bob@example.com,\"Core Services › API\",No,en-US"
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -62771,6 +64979,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -62778,47 +64989,62 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "创建或更新状态页区域",
-        "tags": [
-          "On-call/状态页"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **状态页面管理**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/status-pages/status-page-section-upsert",
-          "metadata": {
-            "sidebarTitle": "创建或更新状态页区域"
-          }
-        }
-      }
-    },
-    "/status-page/subscriber/export": {
-      "post": {
-        "description": "以 CSV 附件形式导出状态页的订阅者列表。响应为 `text/csv` 文件，包含列：Method、Recipient、Components、Subscribe All、Locale。",
-        "operationId": "statusPageSubscriberExport",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {
-                "page_id": 5750613685214
-              },
               "schema": {
                 "$ref": "#/components/schemas/ExportStatusPageSubscribersRequest"
+              },
+              "example": {
+                "page_id": 5750613685214
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/status-page/subscriber/import": {
+      "post": {
+        "operationId": "statusPageSubscriberImport",
+        "summary": "批量导入订阅者",
+        "description": "批量导入状态页订阅者，不发送确认邮件。",
+        "tags": [
+          "On-call/状态页"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **60 次/分钟**；**3 次/秒** |\n| 权限要求 | **状态页面管理**（`on-call`） |\n\n## 使用说明\n\n- 需要 On-call 专业版套餐，且账户需开通订阅者导入白名单，否则返回 `AccessDenied`。\n- `method` 必须与状态页匹配：公开页且已开启邮件订阅时用 `email`，内部页且已开启 IM 订阅时用 `im`。\n- 每个导入的接收人在该状态页上已有的订阅会被导入内容整体替换。\n- `component_ids` 和 `change_ids` 中的每个 ID 都必须存在于该状态页，任一无效则整个请求失败。\n- 每次调用都会记录到账户审计日志，请勿在请求字段中写入敏感信息。",
+          "href": "/zh/api-reference/on-call/status-pages/status-page-subscriber-import",
+          "metadata": {
+            "sidebarTitle": "批量导入订阅者"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
-              "text/csv": {
-                "example": "Method,Recipient,Components,Subscribe All,Locale\nemail,alice@example.com,,Yes,zh-CN\nemail,bob@example.com,\"Core Services › API\",No,en-US",
+              "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/StatusPageSubscriberExportResponse"
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/EmptyResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功。CSV 附件，非 JSON 信封。"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -62826,6 +65052,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -62833,78 +65062,97 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "导出订阅者",
-        "tags": [
-          "On-call/状态页"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **100 次/天**；**20 次/分钟**；**10 次/秒** |\n| 权限要求 | **状态页面管理**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/status-pages/status-page-subscriber-export",
-          "metadata": {
-            "sidebarTitle": "导出订阅者"
-          }
-        }
-      }
-    },
-    "/status-page/subscriber/import": {
-      "post": {
-        "description": "批量导入状态页订阅者。账户需开通订阅者导入白名单，否则将被拒绝（返回权限不足错误）。",
-        "operationId": "statusPageSubscriberImport",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ImportStatusPageSubscribersRequest"
+              },
               "example": {
-                "method": "email",
                 "page_id": 5750613685214,
+                "method": "email",
                 "subscribers": [
                   {
+                    "recipient": "alice@example.com",
                     "all": true,
-                    "locale": "en-US",
-                    "recipient": "alice@example.com"
+                    "locale": "en-US"
                   },
                   {
-                    "all": false,
+                    "recipient": "bob@example.com",
                     "component_ids": [
                       "01KC3GAZ6ZJE40H55GM31RPWZE"
                     ],
-                    "locale": "zh-CN",
-                    "recipient": "bob@example.com"
+                    "all": false,
+                    "locale": "zh-CN"
                   }
                 ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ImportStatusPageSubscribersRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/status-page/subscriber/list": {
+      "get": {
+        "operationId": "statusPageSubscriberList",
+        "summary": "查询状态页订阅者列表",
+        "description": "查询已订阅状态页通知的用户列表。",
+        "tags": [
+          "On-call/状态页"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 公开页返回邮件订阅者，内部页返回 IM 订阅者。\n- 按 `component_ids` 过滤时，也会返回订阅了全部组件的订阅者。\n- 每一项合并了同一接收人的全部订阅；对单个事件的订阅不会列出。",
+          "href": "/zh/api-reference/on-call/status-pages/status-page-subscriber-list",
+          "metadata": {
+            "sidebarTitle": "查询状态页订阅者列表"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/EmptyResponse"
+                          "$ref": "#/components/schemas/StatusPageSubscriberListResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "total": 2,
+                    "has_next_page": false,
+                    "items": [
+                      {
+                        "recipient": "alice@example.com",
+                        "method": "email",
+                        "components": [],
+                        "all": true,
+                        "locale": "zh-CN"
+                      },
+                      {
+                        "recipient": "bob@example.com",
+                        "method": "email",
+                        "components": [],
+                        "all": true,
+                        "locale": "en-US"
+                      }
+                    ]
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -62912,121 +65160,105 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
           "500": {
             "$ref": "#/components/responses/ServerError"
           }
-        },
-        "summary": "批量导入订阅者",
-        "tags": [
-          "On-call/状态页"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **20 次/分钟**；**2 次/秒** |\n| 权限要求 | **状态页面管理**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/status-pages/status-page-subscriber-import",
-          "metadata": {
-            "sidebarTitle": "批量导入订阅者"
-          }
-        }
-      }
-    },
-    "/status-page/subscriber/list": {
-      "get": {
-        "description": "查询已订阅状态页通知的用户列表。",
-        "operationId": "statusPageSubscriberList",
+        },
         "parameters": [
           {
-            "description": "状态页 ID。",
-            "in": "query",
             "name": "page_id",
+            "in": "query",
             "required": true,
             "schema": {
-              "format": "int64",
-              "type": "integer"
-            }
+              "type": "integer",
+              "format": "int64"
+            },
+            "description": "状态页 ID。"
           },
           {
-            "description": "用于筛选订阅者的组件 ID，多个以英文逗号分隔。",
-            "in": "query",
             "name": "component_ids",
+            "in": "query",
             "required": false,
             "schema": {
               "type": "string"
-            }
+            },
+            "description": "用于筛选订阅者的组件 ID，多个以英文逗号分隔。"
           },
           {
-            "description": "页码（从 1 开始）。",
-            "in": "query",
             "name": "p",
+            "in": "query",
             "required": false,
             "schema": {
-              "default": 1,
+              "type": "integer",
               "format": "int64",
               "minimum": 1,
-              "type": "integer"
-            }
+              "default": 1
+            },
+            "description": "页码（从 1 开始）。"
           },
           {
-            "description": "每页条数（1-100）。",
-            "in": "query",
             "name": "limit",
+            "in": "query",
             "required": false,
             "schema": {
-              "default": 10,
+              "type": "integer",
               "format": "int64",
-              "maximum": 100,
               "minimum": 1,
-              "type": "integer"
-            }
+              "maximum": 100,
+              "default": 10
+            },
+            "description": "每页条数（1-100）。"
           }
+        ]
+      }
+    },
+    "/status-page/template/delete": {
+      "post": {
+        "operationId": "statusPageTemplateDelete",
+        "summary": "删除状态页模板",
+        "description": "删除状态页的一个完整状态更新模板或状态描述模板。",
+        "tags": [
+          "On-call/状态页"
         ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **状态页面管理**（`on-call`） |\n\n## 使用说明\n\n- 删除不存在的模板也返回成功。\n- 每次调用都会记录到账户审计日志，请勿在请求字段中写入敏感信息。",
+          "href": "/zh/api-reference/on-call/status-pages/status-page-template-delete",
+          "metadata": {
+            "sidebarTitle": "删除状态页模板"
+          }
+        },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "has_next_page": false,
-                    "items": [
-                      {
-                        "all": true,
-                        "components": [],
-                        "locale": "zh-CN",
-                        "method": "email",
-                        "recipient": "alice@example.com"
-                      },
-                      {
-                        "all": true,
-                        "components": [],
-                        "locale": "en-US",
-                        "method": "email",
-                        "recipient": "bob@example.com"
-                      }
-                    ],
-                    "total": 2
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/StatusPageSubscriberListResponse"
+                          "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -63034,6 +65266,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -63041,64 +65276,74 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "查询状态页订阅者列表",
-        "tags": [
-          "On-call/状态页"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |",
-          "href": "/zh/api-reference/on-call/status-pages/status-page-subscriber-list",
-          "metadata": {
-            "sidebarTitle": "查询状态页订阅者列表"
-          }
-        }
-      }
-    },
-    "/status-page/template/delete": {
-      "post": {
-        "description": "删除状态页的事件模板。",
-        "operationId": "statusPageTemplateDelete",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {
-                "page_id": 5720156736380,
-                "template_id": "01KP0339G5XDEPM4R86T2B23EP",
-                "type": "pre_defined"
-              },
               "schema": {
                 "$ref": "#/components/schemas/DeleteStatusPageTemplateRequest"
+              },
+              "example": {
+                "page_id": 5720156736380,
+                "type": "pre_defined",
+                "template_id": "01KP0339G5XDEPM4R86T2B23EP"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/status-page/template/list": {
+      "get": {
+        "operationId": "statusPageTemplateList",
+        "summary": "查询状态页模板列表",
+        "description": "查询状态页的完整状态更新模板或状态描述模板。",
+        "tags": [
+          "On-call/状态页"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |",
+          "href": "/zh/api-reference/on-call/status-pages/status-page-template-list",
+          "metadata": {
+            "sidebarTitle": "查询状态页模板列表"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/EmptyResponse"
+                          "$ref": "#/components/schemas/ListStatusPageTemplatesResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "items": [
+                      {
+                        "template_id": "01KC8KP6PHVPSCAB0BTKZBN2HR",
+                        "title": "Service Disruption",
+                        "type": "incident",
+                        "status": "identified",
+                        "description": "We have identified the root cause."
+                      }
+                    ]
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -63106,6 +65351,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -63113,84 +65361,76 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "删除状态页模板",
-        "tags": [
-          "On-call/状态页"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **状态页面管理**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/status-pages/status-page-template-delete",
-          "metadata": {
-            "sidebarTitle": "删除状态页模板"
-          }
-        }
-      }
-    },
-    "/status-page/template/list": {
-      "get": {
-        "description": "查询状态页的所有事件模板。",
-        "operationId": "statusPageTemplateList",
         "parameters": [
           {
-            "description": "状态页 ID。",
-            "in": "query",
             "name": "page_id",
+            "in": "query",
             "required": true,
             "schema": {
-              "format": "int64",
-              "type": "integer"
-            }
+              "type": "integer",
+              "format": "int64"
+            },
+            "description": "状态页 ID。"
           },
           {
-            "description": "模板类别。`pre_defined` 返回预定义事件模板；`message` 返回消息通知模板。",
-            "in": "query",
             "name": "type",
+            "in": "query",
             "required": true,
             "schema": {
+              "type": "string",
               "enum": [
                 "pre_defined",
                 "message"
-              ],
-              "type": "string"
-            }
+              ]
+            },
+            "description": "模板类别。`pre_defined` 返回预定义事件模板；`message` 返回消息通知模板。"
           }
+        ]
+      }
+    },
+    "/status-page/template/upsert": {
+      "post": {
+        "operationId": "statusPageTemplateUpsert",
+        "summary": "创建或更新状态页模板",
+        "description": "创建或更新状态页的完整状态更新模板或状态描述模板。",
+        "tags": [
+          "On-call/状态页"
         ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **状态页面管理**（`on-call`） |\n\n## 使用说明\n\n- 不传 `template.template_id` 时创建模板，传入时更新对应模板。`template_id` 不存在时返回 `InternalError`。\n- 更新时空字段保留原值。完整状态更新模板的 `type` 无法修改，状态描述模板的 `type` 可以修改。\n- 每次调用都会记录到账户审计日志，请勿在请求字段中写入敏感信息。",
+          "href": "/zh/api-reference/on-call/status-pages/status-page-template-upsert",
+          "metadata": {
+            "sidebarTitle": "创建或更新状态页模板"
+          }
+        },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "items": [
-                      {
-                        "description": "We have identified the root cause.",
-                        "status": "identified",
-                        "template_id": "01KC8KP6PHVPSCAB0BTKZBN2HR",
-                        "title": "Service Disruption",
-                        "type": "incident"
-                      }
-                    ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
-                          "$ref": "#/components/schemas/ListStatusPageTemplatesResponse"
+                          "$ref": "#/components/schemas/UpsertStatusPageTemplateResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "template_id": "01KP0339G5XDEPM4R86T2B23EP"
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -63198,6 +65438,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -63205,144 +65448,69 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "查询状态页模板列表",
-        "tags": [
-          "On-call/状态页"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |",
-          "href": "/zh/api-reference/on-call/status-pages/status-page-template-list",
-          "metadata": {
-            "sidebarTitle": "查询状态页模板列表"
-          }
-        }
-      }
-    },
-    "/status-page/template/upsert": {
-      "post": {
-        "description": "创建或更新状态页的事件模板。",
-        "operationId": "statusPageTemplateUpsert",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/UpsertStatusPageTemplateRequest"
+              },
               "example": {
                 "page_id": 5720156736380,
+                "type": "pre_defined",
                 "template": {
-                  "description": "We are investigating a service disruption affecting some users.",
-                  "status": "investigating",
                   "title": "Service Disruption",
+                  "status": "investigating",
+                  "description": "We are investigating a service disruption affecting some users.",
                   "type": "incident"
-                },
-                "type": "pre_defined"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/UpsertStatusPageTemplateRequest"
-              }
-            }
-          },
-          "required": true
-        },
-        "responses": {
-          "200": {
-            "content": {
-              "application/json": {
-                "example": {
-                  "data": {
-                    "template_id": "01KP0339G5XDEPM4R86T2B23EP"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/UpsertStatusPageTemplateResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
                 }
               }
-            },
-            "description": "成功"
-          },
-          "400": {
-            "$ref": "#/components/responses/BadRequest"
-          },
-          "401": {
-            "$ref": "#/components/responses/Unauthorized"
-          },
-          "429": {
-            "$ref": "#/components/responses/TooManyRequests"
-          },
-          "500": {
-            "$ref": "#/components/responses/ServerError"
-          }
-        },
-        "summary": "创建或更新状态页模板",
-        "tags": [
-          "On-call/状态页"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **状态页面管理**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/status-pages/status-page-template-upsert",
-          "metadata": {
-            "sidebarTitle": "创建或更新状态页模板"
+            }
           }
         }
       }
     },
     "/status-page/update": {
       "post": {
-        "description": "更新已有状态页的配置。",
         "operationId": "statusPageUpdate",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "contact_info": "mailto:support@example.com",
-                "name": "Flashduty Status Page (Updated)",
-                "page_header": "Updated status page header",
-                "page_id": 5750613685214
-              },
-              "schema": {
-                "$ref": "#/components/schemas/UpdateStatusPageRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "更新状态页",
+        "description": "更新已有状态页的配置，未传的字段保持不变。",
+        "tags": [
+          "On-call/状态页"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **状态页面管理**（`on-call`） |\n\n## 使用说明\n\n- 省略或传 `null` 的字段保持原值；传空字符串会清空该字符串字段。\n- `custom_links` 无法清空：省略或传空数组时保留当前链接。\n- 新的 `url_name` 会被规范化为 slug，且在账户内同类型状态页中必须唯一；内部页不能设置 `custom_domain`。\n- 每次调用都会记录到账户审计日志，请勿在请求字段中写入敏感信息。",
+          "href": "/zh/api-reference/on-call/status-pages/status-page-update",
+          "metadata": {
+            "sidebarTitle": "更新状态页"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -63350,6 +65518,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -63357,62 +65528,65 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "更新状态页",
-        "tags": [
-          "On-call/状态页"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **状态页面管理**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/status-pages/status-page-update",
-          "metadata": {
-            "sidebarTitle": "更新状态页"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/UpdateStatusPageRequest"
+              },
+              "example": {
+                "page_id": 5750613685214,
+                "name": "Flashduty Status Page (Updated)",
+                "page_header": "Updated status page header",
+                "contact_info": "mailto:support@example.com"
+              }
+            }
           }
         }
       }
     },
     "/team/delete": {
       "post": {
-        "description": "按 ID、名称或外部引用 ID 永久删除一个团队。",
         "operationId": "team-write-delete",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "team_id": 1001
-              },
-              "schema": {
-                "$ref": "#/components/schemas/TeamDeleteRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "删除团队",
+        "description": "按 ID、名称或外部引用 ID 删除团队，并移除其全部成员。",
+        "tags": [
+          "平台/团队管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **团队管理**（`organization`） |\n\n## 使用说明\n\n- `team_id`、`team_name`、`ref_id` 三者提供其一；同时传多个时依次以 `team_id`、`team_name`、`ref_id` 为准。\n- 除上述权限外，调用者还必须是团队成员、团队创建者、账户主体或拥有 Admin 角色，否则返回 `403 AccessDenied`。\n- 团队仍被分派策略、值班表、协作空间、通知模板、映射规则、服务日历或单点登录配置的默认团队引用时，返回 `400 ReferenceExist`，`data.refs` 列出每条引用（`kind`、`name`、`href`）。\n- 删除为软删除：团队成员全部移除，团队不再出现在列表和按名称/`ref_id` 的查找中，名称可以重新使用；按 `team_id` 调用 `POST /team/info` 仍能查到，`status` 为 `deleted`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "href": "/zh/api-reference/platform/teams/team-write-delete",
+          "metadata": {
+            "sidebarTitle": "删除团队"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/PlatformEmptyObject"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -63430,79 +65604,79 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "删除团队",
-        "tags": [
-          "平台/团队管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **团队管理**（`organization`） |\n\n## 使用说明\n\n- `team_id`、`team_name`、`ref_id` 三者至少提供一个。\n- 若团队仍被排班、分派策略等资源引用，会返回 `400 ReferenceExist`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
-          "href": "/zh/api-reference/platform/teams/team-write-delete",
-          "metadata": {
-            "sidebarTitle": "删除团队"
-          }
-        }
-      }
-    },
-    "/team/info": {
-      "post": {
-        "description": "按 ID、名称或外部引用 ID 返回单个团队的详细信息。",
-        "operationId": "team-read-info",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/TeamDeleteRequest"
+              },
               "example": {
                 "team_id": 1001
-              },
-              "schema": {
-                "$ref": "#/components/schemas/TeamInfoRequest"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/team/info": {
+      "post": {
+        "operationId": "team-read-info",
+        "summary": "查看团队详情",
+        "description": "按 ID、名称或外部引用 ID 返回单个团队的详细信息。",
+        "tags": [
+          "平台/团队管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- `team_id`、`team_name`、`ref_id` 三者提供其一；同时传多个时，`ref_id` 优先于 `team_name`，`team_name` 优先于 `team_id`。\n- 按 `team_name` 或 `ref_id` 查找只匹配未删除的团队；按 `team_id` 查找时已删除的团队也会返回，`status` 为 `deleted`。\n- 找不到团队时返回 `400 InvalidParameter`。",
+          "href": "/zh/api-reference/platform/teams/team-read-info",
+          "metadata": {
+            "sidebarTitle": "查看团队详情"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "account_id": 10023,
-                    "created_at": 1710000000,
-                    "creator_id": 80011,
-                    "creator_name": "alice",
-                    "description": "Backend reliability engineering team",
-                    "person_ids": [
-                      80011,
-                      80012
-                    ],
-                    "ref_id": "",
-                    "status": "enabled",
-                    "team_id": 1001,
-                    "team_name": "Backend SRE",
-                    "updated_at": 1712000000,
-                    "updated_by": 80011,
-                    "updated_by_name": "alice"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/TeamItem"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "account_id": 10023,
+                    "team_id": 1001,
+                    "team_name": "Backend SRE",
+                    "description": "Backend reliability engineering team",
+                    "status": "enabled",
+                    "updated_by_name": "alice",
+                    "updated_by": 80011,
+                    "creator_id": 80011,
+                    "creator_name": "",
+                    "created_at": 1710000000,
+                    "updated_at": 1712000000,
+                    "person_ids": [
+                      80011,
+                      80012
+                    ],
+                    "ref_id": ""
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -63510,90 +65684,90 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
           "500": {
             "$ref": "#/components/responses/ServerError"
           }
-        },
-        "summary": "查看团队详情",
-        "tags": [
-          "平台/团队管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- `team_id`、`team_name`、`ref_id` 三者至少提供一个。",
-          "href": "/zh/api-reference/platform/teams/team-read-info",
-          "metadata": {
-            "sidebarTitle": "查看团队详情"
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/TeamInfoRequest"
+              },
+              "example": {
+                "team_id": 1001
+              }
+            }
           }
         }
       }
     },
     "/team/infos": {
       "post": {
-        "description": "一次请求按 ID 列表批量返回多个团队的基本信息。",
         "operationId": "team-read-infos",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "team_ids": [
-                  1001,
-                  1002
-                ]
-              },
-              "schema": {
-                "$ref": "#/components/schemas/TeamInfosRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "批量查看团队信息",
+        "description": "一次请求按 ID 列表批量返回多个团队的基本信息。",
+        "tags": [
+          "平台/团队管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 重复的 ID 会去重；不属于本账户任何团队的 ID 会被忽略。\n- 已删除的团队仍会返回（`person_ids` 为空），因此历史记录里保存的团队 ID 依然能解析出名称。\n- 没有任何 ID 匹配时，`items` 为 `null`。",
+          "href": "/zh/api-reference/platform/teams/team-read-infos",
+          "metadata": {
+            "sidebarTitle": "批量查看团队信息"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/TeamInfosResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "items": [
                       {
+                        "team_id": 1001,
+                        "team_name": "Backend SRE",
                         "person_ids": [
                           80011,
                           80012
-                        ],
-                        "team_id": 1001,
-                        "team_name": "Backend SRE"
+                        ]
                       },
                       {
+                        "team_id": 1002,
+                        "team_name": "Frontend",
                         "person_ids": [
                           80013
-                        ],
-                        "team_id": 1002,
-                        "team_name": "Frontend"
+                        ]
                       }
                     ]
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/TeamInfosResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -63601,6 +65775,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -63608,88 +65785,89 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "批量查看团队信息",
-        "tags": [
-          "平台/团队管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 重复的 ID 会被去重；不匹配任何团队的 ID 会被忽略。",
-          "href": "/zh/api-reference/platform/teams/team-read-infos",
-          "metadata": {
-            "sidebarTitle": "批量查看团队信息"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/TeamInfosRequest"
+              },
+              "example": {
+                "team_ids": [
+                  1001,
+                  1002
+                ]
+              }
+            }
           }
         }
       }
     },
     "/team/list": {
       "post": {
-        "description": "分页返回当前账户下的团队列表。",
         "operationId": "team-read-list",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "asc": false,
-                "limit": 20,
-                "orderby": "created_at",
-                "p": 1
-              },
-              "schema": {
-                "$ref": "#/components/schemas/TeamListRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "查看团队列表",
+        "description": "分页返回当前账户下的团队列表。",
+        "tags": [
+          "平台/团队管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 传 `person_id` 只返回该人员所在的团队；`query` 对团队名称或描述做子串匹配。\n- 已删除的团队不会出现在列表中。",
+          "href": "/zh/api-reference/platform/teams/team-read-list",
+          "metadata": {
+            "sidebarTitle": "查看团队列表"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "items": [
-                      {
-                        "account_id": 10023,
-                        "created_at": 1710000000,
-                        "creator_id": 80011,
-                        "creator_name": "alice",
-                        "description": "",
-                        "person_ids": [
-                          80011
-                        ],
-                        "ref_id": "",
-                        "status": "enabled",
-                        "team_id": 1001,
-                        "team_name": "Backend SRE",
-                        "updated_at": 1712000000,
-                        "updated_by": 0,
-                        "updated_by_name": ""
-                      }
-                    ],
-                    "limit": 20,
-                    "p": 1,
-                    "total": 5
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/TeamListResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "p": 1,
+                    "limit": 20,
+                    "total": 1,
+                    "items": [
+                      {
+                        "account_id": 10023,
+                        "team_id": 1001,
+                        "team_name": "Backend SRE",
+                        "description": "Backend reliability engineering team",
+                        "status": "enabled",
+                        "updated_by_name": "alice",
+                        "updated_by": 80011,
+                        "creator_id": 80011,
+                        "creator_name": "",
+                        "created_at": 1710000000,
+                        "updated_at": 1712000000,
+                        "person_ids": [
+                          80011,
+                          80012
+                        ],
+                        "ref_id": ""
+                      }
+                    ]
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -63697,6 +65875,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -63704,70 +65885,68 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "查看团队列表",
-        "tags": [
-          "平台/团队管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 传入 `person_id` 可过滤返回指定人员所属的团队。\n- 默认 p=1、limit=20。",
-          "href": "/zh/api-reference/platform/teams/team-read-list",
-          "metadata": {
-            "sidebarTitle": "查看团队列表"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/TeamListRequest"
+              },
+              "example": {
+                "p": 1,
+                "limit": 20,
+                "orderby": "created_at",
+                "asc": false
+              }
+            }
           }
         }
       }
     },
     "/team/upsert": {
       "post": {
-        "description": "创建新团队或更新已有团队，更新时传入 `team_id`。",
         "operationId": "team-write-upsert",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "description": "Backend reliability engineering team",
-                "person_ids": [
-                  80011,
-                  80012
-                ],
-                "team_name": "Backend SRE"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/TeamUpsertRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "变更团队信息",
+        "description": "创建新团队或更新已有团队，更新时传入 `team_id`。",
+        "tags": [
+          "平台/团队管理"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **团队管理**（`organization`） |\n\n## 使用说明\n\n- 省略 `team_id`（或置为 0）表示创建团队；传入已有的 `team_id` 表示更新。`team_id` 找不到团队时返回 `400`。\n- `team_name` 在账户内的团队中必须唯一。名称已被其他团队使用时返回 `400`；但当 `team_id` 为 0 且 `reset_if_name_exist` 为 true 时，会更新该同名团队。\n- 成员列表总是整体替换：团队成员变为 `person_ids`、`emails`、`phones` 三者解析结果的并集。更新时三者都不传会清空所有成员。\n- 解析不到本账户成员（或账户主体）的条目会被静默丢弃，不会发出邀请。\n- 更新时 `description` 和 `ref_id` 也会被覆盖——不传即清空原值。\n- 更新团队时，调用者还必须是团队成员、团队创建者、账户主体或拥有 Admin 角色。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "href": "/zh/api-reference/platform/teams/team-write-upsert",
+          "metadata": {
+            "sidebarTitle": "变更团队信息"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "team_id": 1001,
-                    "team_name": "Backend SRE"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/TeamUpsertResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "team_id": 1001,
+                    "team_name": "Backend SRE"
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -63785,69 +65964,70 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "变更团队信息",
-        "tags": [
-          "平台/团队管理"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **团队管理**（`organization`） |\n\n## 使用说明\n\n- 省略 `team_id`（或置为 0）表示创建新团队；传入已有 ID 表示更新。\n- `team_name` 须为 1–39 个字符且在账户内唯一。\n- 传入 `person_ids` 可设置团队成员，会替换整个成员列表。\n- 传入 `emails` 或 `phones` 可按联系方式添加已有成员；匹配不到成员的联系方式会被忽略，不会发起邀请。\n- `ref_id` 是供第三方 HR 系统集成使用的外部标识。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
-          "href": "/zh/api-reference/platform/teams/team-write-upsert",
-          "metadata": {
-            "sidebarTitle": "变更团队信息"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/TeamUpsertRequest"
+              },
+              "example": {
+                "team_name": "Backend SRE",
+                "description": "Backend reliability engineering team",
+                "person_ids": [
+                  80011,
+                  80012
+                ]
+              }
+            }
           }
         }
       }
     },
     "/template/create": {
       "post": {
-        "description": "创建一个新的通知模板。",
         "operationId": "template-write-create",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "description": "Default template for production incidents.",
-                "email": "Incident {{ .IncidentName }} on {{ .Severity }}",
-                "sms": "[Flashduty] {{ .IncidentName }} — {{ .Severity }}",
-                "team_id": 0,
-                "template_name": "Prod incident default"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/TemplateCreateRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "创建模板",
+        "description": "创建通知模板，按通道配置消息模板。",
+        "tags": [
+          "On-call/通知模板"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **模板管理**（`on-call`） |\n\n## 使用说明\n\n- 需要专业版或更高版本的订阅，否则返回 `NoLicense`。\n- `template_name` 在账户未删除的模板中必须唯一，且不能与内置预设模板在任一支持语言下的名称相同，否则返回 `InvalidParameter`。\n- 每个非空的通道模板都会用模拟故障试渲染一次，任一通道有语法错误整个请求返回 `InvalidParameter`。`wecom_markdown_v2_enabled` 为 `true` 时，`wecom` 渲染结果不得超过 4,096 字节。\n- 留空的通道在发送通知时使用内置预设内容。\n- `team_id` 非 0 时必须是已存在的团队，否则返回 `InvalidParameter`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "href": "/zh/api-reference/on-call/notification-templates/template-write-create",
+          "metadata": {
+            "sidebarTitle": "创建模板"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "template_id": "6605a1b2c3d4e5f6a7b8c9d0",
-                    "template_name": "Prod incident default"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/TemplateCreateResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "template_id": "6605a1b2c3d4e5f6a7b8c9d0",
+                    "template_name": "Prod incident default"
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -63855,6 +66035,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -63862,62 +66045,66 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "创建模板",
-        "tags": [
-          "On-call/通知模板"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **模板管理**（`on-call`） |\n\n## 使用说明\n\n- `template_name` 必须在账户内唯一，重名会返回 `InvalidParameter`。\n- 服务端会对所有非空通道按 Mock 故障做一次渲染校验，任何通道的语法错误都会导致整个请求返回 `InvalidParameter`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
-          "href": "/zh/api-reference/on-call/notification-templates/template-write-create",
-          "metadata": {
-            "sidebarTitle": "创建模板"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/TemplateCreateRequest"
+              },
+              "example": {
+                "team_id": 0,
+                "template_name": "Prod incident default",
+                "description": "Default template for production incidents.",
+                "email": "Incident {{.Title}} is {{.IncidentSeverity}}",
+                "sms": "[Flashduty] {{.Title}} - {{.IncidentSeverity}}"
+              }
+            }
           }
         }
       }
     },
     "/template/delete": {
       "post": {
-        "description": "按 ID 软删除一个模板。",
         "operationId": "template-write-delete",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "template_id": "6605a1b2c3d4e5f6a7b8c9d0"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/TemplateIDRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "删除模板",
+        "description": "按 ID 软删除通知模板。",
+        "tags": [
+          "On-call/通知模板"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **模板管理**（`on-call`） |\n\n## 使用说明\n\n- 若仍有分派策略使用该模板，返回 HTTP 400 `ReferenceExist`，`data.refs` 列出引用方（`kind` 为 `escalate_rule`，含策略 `name` 和控制台 `href`）。\n- 模板的 `status` 变为 `deleted`：不再出现在 `/template/list` 中、名称可被复用，但 `/template/info` 仍能查到。\n- `template_id` 不存在或已删除时返回 `InvalidParameter`。\n- 仅账户管理员、模板创建者或模板所属团队的成员可以调用，其他人返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "href": "/zh/api-reference/on-call/notification-templates/template-write-delete",
+          "metadata": {
+            "sidebarTitle": "删除模板"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyObject"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -63935,87 +66122,95 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "删除模板",
-        "tags": [
-          "On-call/通知模板"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **模板管理**（`on-call`） |\n\n## 使用说明\n\n- 若模板仍被任何协作空间、分派策略或通知订阅引用，会返回 `400 ReferenceExist`。\n- 删除是软删除（`deleted_at` 被置值），记录仍保留用于审计，但模板不会再出现在列表中。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
-          "href": "/zh/api-reference/on-call/notification-templates/template-write-delete",
-          "metadata": {
-            "sidebarTitle": "删除模板"
-          }
-        }
-      }
-    },
-    "/template/info": {
-      "post": {
-        "description": "按 ID 返回单个通知模板。",
-        "operationId": "template-read-info",
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
-              "example": {
-                "template_id": "6605a1b2c3d4e5f6a7b8c9d0"
-              },
               "schema": {
                 "$ref": "#/components/schemas/TemplateIDRequest"
+              },
+              "example": {
+                "template_id": "6605a1b2c3d4e5f6a7b8c9d0"
               }
             }
-          },
-          "required": true
+          }
+        }
+      }
+    },
+    "/template/info": {
+      "post": {
+        "operationId": "template-read-info",
+        "summary": "查看模板详情",
+        "description": "按 ID 返回单个通知模板。",
+        "tags": [
+          "On-call/通知模板"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **模板查看**（`on-call`） 或 **模板管理**（`on-call`） |\n\n## 使用说明\n\n- `template_id` 传 `6321aad26c12104586a88916` 可获取内置预设模板：各通道内容使用账户语言，名称和描述使用调用方语言。\n- `template_id` 不存在时返回 `InvalidParameter`；已软删除的模板仍会返回，此时 `status` 为 `deleted`。",
+          "href": "/zh/api-reference/on-call/notification-templates/template-read-info",
+          "metadata": {
+            "sidebarTitle": "查看模板详情"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "account_id": 10023,
-                    "created_at": 1712700000,
-                    "creator_id": 80011,
-                    "description": "Default template for production incidents.",
-                    "dingtalk": "",
-                    "dingtalk_app": "",
-                    "email": "Incident {{ .IncidentName }} on {{ .Severity }}",
-                    "feishu": "",
-                    "feishu_app": "",
-                    "slack": "",
-                    "slack_app": "",
-                    "sms": "[Flashduty] {{ .IncidentName }} — {{ .Severity }}",
-                    "status": "enabled",
-                    "team_id": 0,
-                    "teams_app": "",
-                    "telegram": "",
-                    "template_id": "6605a1b2c3d4e5f6a7b8c9d0",
-                    "template_name": "Prod incident default",
-                    "updated_at": 1712702400,
-                    "updated_by": 80011,
-                    "voice": "",
-                    "wecom": "",
-                    "wecom_app": "",
-                    "zoom": ""
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/TemplateItem"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "account_id": 10023,
+                    "team_id": 0,
+                    "template_id": "6605a1b2c3d4e5f6a7b8c9d0",
+                    "template_name": "Prod incident default",
+                    "description": "Default template for production incidents.",
+                    "email": "Incident {{.Title}} is {{.IncidentSeverity}}",
+                    "sms": "[Flashduty] {{.Title}} - {{.IncidentSeverity}}",
+                    "voice": "",
+                    "dingtalk": "",
+                    "wecom": "",
+                    "feishu": "",
+                    "feishu_app": "",
+                    "dingtalk_app": "",
+                    "wecom_app": "",
+                    "slack_app": "",
+                    "teams_app": "",
+                    "telegram": "",
+                    "slack": "",
+                    "zoom": "",
+                    "wecom_markdown_v2_enabled": false,
+                    "feishu_app_card_v2_table_enabled": false,
+                    "feishu_app_card_v2_preserve_blank_lines": false,
+                    "feishu_app_war_room_enabled": false,
+                    "dingtalk_app_war_room_enabled": false,
+                    "slack_app_war_room_enabled": false,
+                    "incident_card_closed_action_apps": [],
+                    "incident_card_hidden_fields": {},
+                    "status": "enabled",
+                    "creator_id": 80011,
+                    "updated_by": 80011,
+                    "created_at": 1712700000,
+                    "updated_at": 1712702400
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -64023,6 +66218,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -64030,97 +66228,101 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "查看模板详情",
-        "tags": [
-          "On-call/通知模板"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **模板查看**（`on-call`） |\n\n## 使用说明\n\n- 传入 `000000000000000000000001` 作为 `template_id` 可以获取当前账户语种下的系统预置模板。",
-          "href": "/zh/api-reference/on-call/notification-templates/template-read-info",
-          "metadata": {
-            "sidebarTitle": "查看模板详情"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/TemplateIDRequest"
+              },
+              "example": {
+                "template_id": "6605a1b2c3d4e5f6a7b8c9d0"
+              }
+            }
           }
         }
       }
     },
     "/template/list": {
       "post": {
-        "description": "分页返回当前账户下的通知模板列表。",
         "operationId": "template-read-list",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "asc": false,
-                "is_my_team": false,
-                "limit": 20,
-                "orderby": "updated_at",
-                "p": 1
-              },
-              "schema": {
-                "$ref": "#/components/schemas/TemplateListRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "查询模板列表",
+        "description": "分页返回当前账户下的通知模板列表。",
+        "tags": [
+          "On-call/通知模板"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间查看**（`on-call`） 或 **协作空间管理**（`on-call`） 或 **模板查看**（`on-call`） 或 **模板管理**（`on-call`） |\n\n## 使用说明\n\n- 第一页的第一条总是内置预设模板（`template_id` 为 `6321aad26c12104586a88916`），不受过滤条件影响，并计入 `total`。\n- 按 `orderby`（默认 `created_at`）排序，默认倒序，`asc` 为 `true` 时正序。已软删除的模板不返回。\n- `is_my_team: true` 时只返回调用方所在团队的模板；同时传了 `team_ids` 则只保留两者共有的团队。若交集为空，则不按团队过滤，返回所有团队的模板。调用方不属于任何团队时返回空结果（`total` 为 0，也没有预设模板）。\n- `query` 是对 `template_name` 的正则匹配，不区分大小写；不合法的正则按普通文本匹配。",
+          "href": "/zh/api-reference/on-call/notification-templates/template-read-list",
+          "metadata": {
+            "sidebarTitle": "查询模板列表"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/TemplateListResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
+                    "total": 47,
                     "has_next_page": true,
                     "items": [
                       {
                         "account_id": 10023,
-                        "created_at": 1712700000,
-                        "creator_id": 80011,
+                        "team_id": 0,
+                        "template_id": "6605a1b2c3d4e5f6a7b8c9d0",
+                        "template_name": "Prod incident default",
                         "description": "Default template for production incidents.",
+                        "email": "Incident {{.Title}} is {{.IncidentSeverity}}",
+                        "sms": "[Flashduty] {{.Title}} - {{.IncidentSeverity}}",
+                        "voice": "",
                         "dingtalk": "",
-                        "dingtalk_app": "",
-                        "email": "Incident {{ .IncidentName }} on {{ .Severity }}",
+                        "wecom": "",
                         "feishu": "",
                         "feishu_app": "",
-                        "slack": "",
+                        "dingtalk_app": "",
+                        "wecom_app": "",
                         "slack_app": "",
-                        "sms": "[Flashduty] {{ .IncidentName }} — {{ .Severity }}",
-                        "status": "enabled",
-                        "team_id": 0,
                         "teams_app": "",
                         "telegram": "",
-                        "template_id": "6605a1b2c3d4e5f6a7b8c9d0",
-                        "template_name": "Prod incident default",
-                        "updated_at": 1712702400,
+                        "slack": "",
+                        "zoom": "",
+                        "wecom_markdown_v2_enabled": false,
+                        "feishu_app_card_v2_table_enabled": false,
+                        "feishu_app_card_v2_preserve_blank_lines": false,
+                        "feishu_app_war_room_enabled": false,
+                        "dingtalk_app_war_room_enabled": false,
+                        "slack_app_war_room_enabled": false,
+                        "incident_card_closed_action_apps": [],
+                        "incident_card_hidden_fields": {},
+                        "status": "enabled",
+                        "creator_id": 80011,
                         "updated_by": 80011,
-                        "voice": "",
-                        "wecom": "",
-                        "wecom_app": "",
-                        "zoom": ""
+                        "created_at": 1712700000,
+                        "updated_at": 1712702400
                       }
-                    ],
-                    "total": 47
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/TemplateListResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                    ]
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -64128,6 +66330,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -64135,79 +66340,106 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "查询模板列表",
-        "tags": [
-          "On-call/通知模板"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **模板查看**（`on-call`） 或 **模板管理**（`on-call`） |\n\n## 使用说明\n\n- 默认返回第 1 页、每页 20 条。响应中的 `has_next_page` 可以直接告知是否还有下一页，无需额外计数请求。\n- 当 `is_my_team=true` 时 `team_ids` 字段会被忽略。",
-          "href": "/zh/api-reference/on-call/notification-templates/template-read-list",
-          "metadata": {
-            "sidebarTitle": "查询模板列表"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/TemplateListRequest"
+              },
+              "example": {
+                "p": 1,
+                "limit": 20,
+                "orderby": "updated_at",
+                "asc": false,
+                "is_my_team": false
+              }
+            }
           }
         }
       }
     },
     "/template/preview": {
       "post": {
-        "description": "使用故障数据或模拟数据渲染通知模板并返回结果。",
         "operationId": "template-read-preview",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "content": "Incident {{.Title}} is {{.Status}}",
-                "incident_card_hidden_fields": {
-                  "feishu_app": [
-                    "responders"
-                  ]
-                },
-                "incident_id": "664a1b2c3d4e5f6a7b8c9d0e",
-                "type": "feishu_app"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/PreviewTemplateRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "预览模板",
+        "description": "用故障数据或模拟数据渲染模板，返回该通道实际会发送的内容。",
+        "tags": [
+          "On-call/通知模板"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **100 次/分钟**；**5 次/秒** |\n| 权限要求 | **模板查看**（`on-call`） 或 **模板管理**（`on-call`） |\n\n## 使用说明\n\n- 传 `incident_id` 时用该故障渲染（须为账户内存在的故障，否则返回 `InvalidParameter`），否则用模拟故障。`content` 为空时预览该通道的内置预设内容。\n- 模板错误不会返回 HTTP 错误：响应中 `success` 为 `false`，`message` 说明原因。\n- `card` 描述渲染结果外层的消息框架（邮件主题、IM 应用卡片的元素和按钮），仅 `email`、`feishu_app`、`dingtalk_app`、`wecom_app`、`slack_app`、`teams_app` 返回，其他类型省略。依赖集成的按钮（AI 分析、作战室）不会出现。\n- `incident_card_hidden_fields` 作用于 IM 应用卡片；不支持的应用类型或字段名返回 `InvalidParameter`。\n- 该接口不会发送消息，也不会保存任何内容。",
+          "href": "/zh/api-reference/on-call/notification-templates/template-read-preview",
+          "metadata": {
+            "sidebarTitle": "预览模板"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "content": "Incident Database latency spike is Critical",
-                    "fixed_fields": [
-                      {
-                        "field": "channel",
-                        "value": "Payment Alerts"
-                      }
-                    ],
-                    "message": "",
-                    "success": true
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/PreviewTemplateResponse"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "success": true,
+                    "content": "**Database latency spike** is Critical",
+                    "message": "",
+                    "card": {
+                      "title": "Database latency spike",
+                      "elements": [
+                        {
+                          "type": "template"
+                        },
+                        {
+                          "type": "divider"
+                        },
+                        {
+                          "type": "actions",
+                          "actions": [
+                            {
+                              "text": "Acknowledge",
+                              "style": "primary"
+                            },
+                            {
+                              "text": "Resolve",
+                              "style": "danger"
+                            },
+                            {
+                              "text": "Snooze",
+                              "style": "select"
+                            }
+                          ]
+                        }
+                      ]
+                    },
+                    "blocks": [
+                      {
+                        "type": "markdown",
+                        "content": "**Database latency spike** is Critical"
+                      }
+                    ],
+                    "size_bytes": 38,
+                    "size_limit_bytes": 30720
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -64215,6 +66447,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -64222,66 +66457,69 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "预览模板",
-        "tags": [
-          "On-call/通知模板"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **60 次/分钟**；**10 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- `incident_card_hidden_fields` 仅用于受支持的 IM 故障卡片预览；不支持的应用类型或字段名会返回 `InvalidParameter`。\n- 只有所选 IM 预览存在非空固定故障卡片值时，才会返回 `fixed_fields`。",
-          "href": "/zh/api-reference/on-call/notification-templates/template-read-preview",
-          "metadata": {
-            "sidebarTitle": "预览模板"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PreviewTemplateRequest"
+              },
+              "example": {
+                "content": "**{{.Title}}** is {{.IncidentSeverity}}",
+                "type": "feishu_app",
+                "incident_id": "664a1b2c3d4e5f6a7b8c9d0e",
+                "incident_card_hidden_fields": {
+                  "feishu_app": [
+                    "responders"
+                  ]
+                }
+              }
+            }
           }
         }
       }
     },
     "/template/update": {
       "post": {
-        "description": "更新指定模板。仅写入请求中出现的字段：省略的通道保持当前内容，显式传空字符串表示清空该通道。",
         "operationId": "template-write-update",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "description": "Updated description.",
-                "email": "Incident {{ .IncidentName }} on {{ .Severity }}",
-                "sms": "[Flashduty] {{ .IncidentName }} — {{ .Severity }}",
-                "template_id": "6605a1b2c3d4e5f6a7b8c9d0",
-                "template_name": "Prod incident default"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/TemplateUpdateRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "更新模板",
+        "description": "更新通知模板，只写入请求中出现的字段。",
+        "tags": [
+          "On-call/通知模板"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **模板管理**（`on-call`） |\n\n## 使用说明\n\n- `template_name` 每次都必填且总会被写入。其他字段不传则保持原值；某个通道传空字符串表示清空，之后该通道的通知使用内置预设内容。\n- 请求中每个非空的通道模板都会用模拟故障试渲染一次，任一通道有语法错误整个请求返回 `InvalidParameter`。`wecom_markdown_v2_enabled` 为 `true` 时，`wecom` 渲染结果不得超过 4,096 字节。\n- `incident_card_hidden_fields` 和 `incident_card_closed_action_apps` 一旦传入，整体替换已存的值。\n- `template_id` 不存在时返回 `InvalidParameter`；新的 `template_name` 不能与其他模板重名。\n- 仅账户管理员、模板创建者或模板所属团队的成员可以调用，其他人返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "href": "/zh/api-reference/on-call/notification-templates/template-write-update",
+          "metadata": {
+            "sidebarTitle": "更新模板"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {},
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/EmptyObject"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {}
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -64299,82 +66537,85 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "更新模板",
-        "tags": [
-          "On-call/通知模板"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **模板管理**（`on-call`） |\n\n## 使用说明\n\n- 仅写入请求中出现的字段：省略的通道保持当前内容；想清空某通道，把该字段显式设置为空字符串。\n- 调用者必须对目标模板所属团队拥有数据权限，否则返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
-          "href": "/zh/api-reference/on-call/notification-templates/template-write-update",
-          "metadata": {
-            "sidebarTitle": "更新模板"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/TemplateUpdateRequest"
+              },
+              "example": {
+                "template_id": "6605a1b2c3d4e5f6a7b8c9d0",
+                "template_name": "Prod incident default",
+                "description": "Updated description.",
+                "email": "Incident {{.Title}} is {{.IncidentSeverity}}",
+                "sms": "[Flashduty] {{.Title}} - {{.IncidentSeverity}}"
+              }
+            }
           }
         }
       }
     },
     "/webhook/history/detail": {
       "post": {
-        "description": "获取指定 Webhook 推送尝试的详细请求体和响应信息。",
         "operationId": "webhookHistoryDetail",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "event_id": "20260412Xatt9hrXsgmFkBR78WF655",
-                "integration_id": 6113996590131
-              },
-              "schema": {
-                "$ref": "#/components/schemas/GetWebhookHistoryDetailRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "获取 Webhook 推送详情",
+        "description": "获取指定 Webhook 推送尝试的详细请求体和响应信息。",
+        "tags": [
+          "On-call/集成中心"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- `event_id` 与 `integration_id` 取自 `POST /webhook/history/list` 返回的记录；`event_id` 以推送日期（`YYYYMMDD`）开头，查询依赖该日期。\n- 未找到记录时 `data` 为空对象。\n- 部署未开启推送历史记录时返回 `InvalidParameter`。",
+          "href": "/zh/api-reference/on-call/integrations/webhook-history-detail",
+          "metadata": {
+            "sidebarTitle": "获取 Webhook 推送详情"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
-                "example": {
-                  "data": {
-                    "attempt": 1,
-                    "channel_id": 2551105804131,
-                    "channel_name": "Production Alerts",
-                    "duration": 132,
-                    "endpoint": "https://example.com/webhook",
-                    "event_id": "20260412Xatt9hrXsgmFkBR78WF655",
-                    "event_time": "2026-04-12 13:31:11.357472",
-                    "event_type": "a_update",
-                    "integration_id": 5321026051131,
-                    "ref_id": "69da3f0ef77b1b51f40e83cc",
-                    "ref_title": "High CPU Usage on host-01",
-                    "request_body": "{\"event_type\":\"a_update\",\"event_id\":\"d789d65951c0532ea9b6a1d99b707054\"}",
-                    "request_headers": "{\"Content-Type\":\"application/json\"}",
-                    "response_body": "{\"ok\":true}",
-                    "response_headers": "{\"Content-Type\":\"application/json\"}",
-                    "status": "success",
-                    "status_code": 200,
-                    "webhook_type": "alert"
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
                 "schema": {
                   "allOf": [
                     {
                       "$ref": "#/components/schemas/SuccessEnvelope"
                     },
                     {
+                      "type": "object",
                       "properties": {
                         "data": {
                           "$ref": "#/components/schemas/WebhookHistoryDetail"
                         }
-                      },
-                      "type": "object"
+                      }
                     }
                   ]
+                },
+                "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+                  "data": {
+                    "integration_id": 5321026051131,
+                    "event_id": "20260412Xatt9hrXsgmFkBR78WF655",
+                    "webhook_type": "alert",
+                    "event_type": "a_update",
+                    "channel_id": 2551105804131,
+                    "ref_id": "69da3f0ef77b1b51f40e83cc",
+                    "request_headers": "{\"Content-Type\":\"application/json\"}",
+                    "request_body": "{\"event_type\":\"a_update\",\"event_id\":\"d789d65951c0532ea9b6a1d99b707054\"}",
+                    "endpoint": "https://example.com/webhook",
+                    "attempt": 1,
+                    "duration": 132,
+                    "status": "success",
+                    "status_code": 200,
+                    "response_headers": "{\"Content-Type\":\"application/json\"}",
+                    "response_body": "{\"ok\":true}",
+                    "event_time": "2026-04-12 13:31:11.357472",
+                    "ref_title": "High CPU Usage on host-01",
+                    "channel_name": "Production Alerts"
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -64382,6 +66623,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -64389,85 +66633,82 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "获取 Webhook 推送详情",
-        "tags": [
-          "On-call/集成中心"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **集成中心查看**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/integrations/webhook-history-detail",
-          "metadata": {
-            "sidebarTitle": "获取 Webhook 推送详情"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/GetWebhookHistoryDetailRequest"
+              },
+              "example": {
+                "event_id": "20260412Xatt9hrXsgmFkBR78WF655",
+                "integration_id": 6113996590131
+              }
+            }
           }
         }
       }
     },
     "/webhook/history/list": {
       "post": {
-        "description": "查询出站 Webhook 通知的推送历史记录。",
         "operationId": "webhookHistoryList",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "example": {
-                "end_time": 1775203200000,
-                "integration_id": 6113996590131,
-                "limit": 20,
-                "start_time": 1775116800000,
-                "status": "success"
-              },
-              "schema": {
-                "$ref": "#/components/schemas/ListWebhookHistoryRequest"
-              }
-            }
-          },
-          "required": true
+        "summary": "查询 Webhook 推送历史",
+        "description": "查询出站 Webhook 通知的推送历史记录。",
+        "tags": [
+          "On-call/集成中心"
+        ],
+        "x-mint": {
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- `start_time` 和 `end_time` 为 Unix 毫秒时间戳。\n- 每条记录对应一个事件向一个地址的一次推送；`attempt` 为 HTTP 尝试次数，仅在连接错误时重试。\n- 保存的请求与响应 Header 和 Body 会被截断。\n- 传入上次响应中的 `search_after_ctx` 获取下一页；最后一页时它为空字符串。\n- 部署未开启推送历史记录时返回 `InvalidParameter`。",
+          "href": "/zh/api-reference/on-call/integrations/webhook-history-list",
+          "metadata": {
+            "sidebarTitle": "查询 Webhook 推送历史"
+          }
         },
         "responses": {
           "200": {
+            "description": "成功",
             "content": {
               "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/SuccessEnvelope"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "data": {
+                          "$ref": "#/components/schemas/ListWebhookHistoryResponse"
+                        }
+                      }
+                    }
+                  ]
+                },
                 "example": {
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "items": [
                       {
-                        "attempt": 1,
-                        "channel_id": 2551105804131,
-                        "duration": 132,
-                        "endpoint": "https://example.com/webhook",
+                        "integration_id": 5321026051131,
                         "event_id": "20260412Xatt9hrXsgmFkBR78WF655",
-                        "event_time": "2026-04-12 13:31:11.357472",
+                        "webhook_type": "alert",
                         "event_type": "a_update",
-                        "integration_id": 5321026051131,
+                        "channel_id": 2551105804131,
                         "ref_id": "69da3f0ef77b1b51f40e83cc",
+                        "endpoint": "https://example.com/webhook",
+                        "attempt": 1,
+                        "duration": 132,
                         "status": "success",
                         "status_code": 200,
-                        "webhook_type": "alert"
+                        "event_time": "2026-04-12 13:31:11.357472"
                       }
                     ],
                     "search_after_ctx": "eyJldmVudF90aW1lIjoiMjAyNi0wNC0xMlQxMzoxNToyNi4zODI1NDcrMDg6MDAiLCJldmVudF9pZCI6IjIwMjYwNDEybUdzeFAzZHJwRmZzNFpDUWQycFNEcCJ9",
                     "total": 346
-                  },
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
-                },
-                "schema": {
-                  "allOf": [
-                    {
-                      "$ref": "#/components/schemas/SuccessEnvelope"
-                    },
-                    {
-                      "properties": {
-                        "data": {
-                          "$ref": "#/components/schemas/ListWebhookHistoryResponse"
-                        }
-                      },
-                      "type": "object"
-                    }
-                  ]
+                  }
                 }
               }
-            },
-            "description": "成功"
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -64475,6 +66716,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -64482,15 +66726,21 @@
             "$ref": "#/components/responses/ServerError"
           }
         },
-        "summary": "查询 Webhook 推送历史",
-        "tags": [
-          "On-call/集成中心"
-        ],
-        "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **集成中心查看**（`on-call`） |",
-          "href": "/zh/api-reference/on-call/integrations/webhook-history-list",
-          "metadata": {
-            "sidebarTitle": "查询 Webhook 推送历史"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ListWebhookHistoryRequest"
+              },
+              "example": {
+                "limit": 20,
+                "start_time": 1775116800000,
+                "end_time": 1775203200000,
+                "integration_id": 6113996590131,
+                "status": "success"
+              }
+            }
           }
         }
       }
@@ -64499,12 +66749,12 @@
       "post": {
         "operationId": "memberNotify",
         "summary": "通知成员",
-        "description": "以调用方身份向账户成员发送邮件，邮件内容由调用方提供。仅可使用 AI SRE 会话凭据调用；使用其他凭据调用会返回 AccessDenied 错误。邮件投递是异步的——`accepted` 表示邮件已入队，并不代表已送达。",
+        "description": "以调用方 AI SRE 会话的身份，向账户成员发送其撰写的邮件。",
         "tags": [
           "平台/成员管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ----- |\n| 速率限制 | 每个账户 **200 次/分钟**；**10 次/秒** |\n| 权限要求 | 无——仅可使用 AI SRE 会话凭据调用；使用其他凭据调用会返回 AccessDenied |\n\n## 使用说明\n\n- 不是调用方账户内活跃成员、或没有邮箱地址的收件人会被跳过，不会导致整个请求失败。\n- 是否发送邮件取决于每个收件人针对此类消息的通知偏好设置；未设置偏好的收件人默认会收到邮件。\n- 收件人收到的邮件正文就是清洗后的 `html`，平台不会在其前后添加任何内容；发件人名称显示为调用方姓名加“(via AI SRE)”。\n- 发送前，服务端会检查提交的 `html`，如果其中包含移除后会改变收件人所见内容的构造（`<style>`、`<svg>`、`<iframe>`、`<object>`、`<embed>`、`<form>`、`<input>`、`<button>`、`src` 缺失或不是 `https` 的 `<img>`，或 href 不属于 `http`/`https`/`mailto` 的 `<a>`），会返回 `400` / `InvalidParameter` 并拒绝请求；错误消息会逐一列出触发的构造及需要如何修改，且不会入队——不占用每小时限额，也不占用同轮次去重。不影响渲染效果的标签（`<script>`、`<meta>`、`<link>`、`<base>`、`on*` 事件属性）仍会被静默清洗，不会触发拒绝。\n- 同一收件人通过该接口每小时最多收到 20 封邮件；超出后同一窗口内该收件人的后续投递会被跳过并返回 `rate_limited`。\n- 在同一个 AI SRE 会话轮次内重复调用，不会向已收到邮件的收件人重复发送；重复的收件人会被跳过并返回 `duplicate`。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **200 次/分钟**；**10 次/秒** |\n| 权限要求 | 无 —— 但对调用凭据有要求，见使用说明 |\n\n## 使用说明\n\n- 仅可使用 AI SRE 会话凭据调用；使用其他凭据调用会返回 `AccessDenied`。\n- 邮件投递是异步的——`accepted` 表示邮件已入队，并不代表已送达。\n- 不是调用方账户内活跃成员、或没有邮箱地址的收件人会被跳过，不会导致整个请求失败。\n- 是否发送邮件取决于每个收件人针对此类消息的通知偏好设置；未设置偏好的收件人默认会收到邮件。\n- 收件人收到的邮件正文就是清洗后的 `html`，平台不会在其前后添加任何内容；发件人名称显示为调用方姓名加“(via AI SRE)”。\n- 发送前，服务端会检查提交的 `html`，如果其中包含移除后会改变收件人所见内容的构造（`<style>`、`<svg>`、`<iframe>`、`<object>`、`<embed>`、`<form>`、`<input>`、`<button>`、`src` 缺失或不是 `https` 的 `<img>`，或 href 不属于 `http`/`https`/`mailto` 的 `<a>`），会返回 `400` / `InvalidParameter` 并拒绝请求；错误消息会逐一列出触发的构造及需要如何修改，且不会入队——不占用每小时限额，也不占用同轮次去重。不影响渲染效果的标签（`<script>`、`<meta>`、`<link>`、`<base>`、`on*` 事件属性）仍会被静默清洗，不会触发拒绝。\n- 同一收件人通过该接口每小时最多收到 20 封邮件；超出后同一窗口内该收件人的后续投递会被跳过并返回 `rate_limited`。\n- 在同一个 AI SRE 会话轮次内重复调用，不会向已收到邮件的收件人重复发送；重复的收件人会被跳过并返回 `duplicate`。",
           "href": "/zh/api-reference/platform/members/member-notify",
           "metadata": {
             "sidebarTitle": "通知成员"
@@ -64608,7 +66858,7 @@
           "Monitors/仪表盘"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | **300 requests/minute**; **20 requests/second** per account |\n| 权限要求 | **仪表盘管理**（`monit`） |\n\n## 使用说明\n\n- `dashboard_id` 由调用方提供，因此超时后重试会以 `DashboardIDConflict` 失败，而不会创建第二个仪表盘。\n- `definition` 上限 1 MiB，请求体上限 2 MiB。\n- 会记录审计日志。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **仪表盘管理**（`monit`） |\n\n## 使用说明\n\n- `dashboard_id` 由调用方生成（小写的 canonical UUIDv7）。超时后用同一 ID 重试会以 `DashboardIDConflict`（HTTP 409）失败，而不会创建第二个仪表盘。\n- `folder_id` 必须是`app_key` 所属成员可访问的目录：其本人创建或归属其所在团队的目录及这些目录的全部子目录；账户所有者与管理员可访问全部目录之一，否则以 `FolderNotFound`（HTTP 404）失败。\n- 新仪表盘的 `revision` 从 1 开始；下次更新、移动或删除时把它作为 `expected_revision` 传入。\n- `definition` 不合法时返回 `InvalidParameter`（HTTP 400），错误信息按 `<JSON 指针>: <原因>` 逐条列出违规项。定义超过 1 MiB 或超出数量上限（如每个 tab 的 section 数、面板数、查询数或变量数），或请求体超过 2 MiB，返回 `EntityTooLarge`（HTTP 413）；`schema_version` 不是 `dashboard.v1` 时返回 `UnsupportedSchemaVersion`（HTTP 422）。\n- 会记录审计日志。",
           "href": "/zh/api-reference/monitors/dashboards/monit-dashboard-write-create",
           "metadata": {
             "sidebarTitle": "创建仪表盘"
@@ -64713,7 +66963,7 @@
                                       "legend_alias": "{{env}} requests",
                                       "query": {
                                         "mode": "range",
-                                        "expr": "sum(rate(http_requests_total{env=\"{{env}}\"}[5m]))",
+                                        "expr": "sum(rate(http_requests_total{env=\"${env}\"}[5m]))",
                                         "args": {},
                                         "min_step_seconds": 30
                                       }
@@ -64847,7 +67097,7 @@
                                   "legend_alias": "{{env}} requests",
                                   "query": {
                                     "mode": "range",
-                                    "expr": "sum(rate(http_requests_total{env=\"{{env}}\"}[5m]))",
+                                    "expr": "sum(rate(http_requests_total{env=\"${env}\"}[5m]))",
                                     "args": {},
                                     "min_step_seconds": 30
                                   }
@@ -64886,7 +67136,7 @@
           "Monitors/仪表盘"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | **1,000 requests/minute**; **50 requests/second** per account |\n| 权限要求 | 任意有效 `app_key`；结果限于其所属成员可读的目录 |\n\n## 使用说明\n\n- 位于回收站的仪表盘返回 `DashboardDeleted`，不返回定义。\n- 该读接口除目录可读性外无额外权限点：`app_key` 只能看到其所属成员可读目录下的仪表盘。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 只能看到位于`app_key` 所属成员可访问的目录：其本人创建或归属其所在团队的目录及这些目录的全部子目录；账户所有者与管理员可访问全部目录中的仪表盘；其他仪表盘返回 `DashboardNotFound`（HTTP 404）。\n- 位于回收站的仪表盘返回 `DashboardDeleted`（HTTP 410），不返回定义；可用 `POST /monit/dashboard/trash/list` 找到它，再用 `POST /monit/dashboard/restore` 恢复。\n- 下次更新、移动或删除时，把返回的 `revision` 作为 `expected_revision` 传入。",
           "href": "/zh/api-reference/monitors/dashboards/monit-dashboard-read-get",
           "metadata": {
             "sidebarTitle": "查看仪表盘详情"
@@ -64991,7 +67241,7 @@
                                       "legend_alias": "{{env}} requests",
                                       "query": {
                                         "mode": "range",
-                                        "expr": "sum(rate(http_requests_total{env=\"{{env}}\"}[5m]))",
+                                        "expr": "sum(rate(http_requests_total{env=\"${env}\"}[5m]))",
                                         "args": {},
                                         "min_step_seconds": 30
                                       }
@@ -65073,7 +67323,7 @@
           "Monitors/仪表盘"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | **300 requests/minute**; **20 requests/second** per account |\n| 权限要求 | **仪表盘管理**（`monit`） |\n\n## 使用说明\n\n- 发送的是完整定义——这不是部分更新。\n- `expected_revision` 必须等于已存版本号，否则返回 `DashboardRevisionConflict`。\n- 定义逐字节相同时 `changed` 为 false，且不会产生新版本。\n- 仅当调用过程中调用方失去该目录的读权限时，响应中的 `resource` 才为 null。\n- 会记录审计日志。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **仪表盘管理**（`monit`） |\n\n## 使用说明\n\n- 需要发送完整定义；未包含的内容会被删除，不会沿用已存版本。\n- `expected_revision` 必须等于已存版本号，否则以 `DashboardRevisionConflict`（HTTP 409）失败；请重新读取仪表盘后重试。\n- 成功后 `revision` 加 1，并记录一条带 `message` 的版本。规范化后的定义与 `schema_version` 都与已存内容相同时，`changed` 为 false，`revision` 不变，也不会记录版本。\n- 标题与描述会去除首尾空白，未填写的数值 `unit` 会存为 `unitless`，因此返回的 `definition` 可能与请求略有不同。\n- 位于回收站的仪表盘返回 `DashboardDeleted`（HTTP 410）；调用方无权访问其所在目录时返回 `AccessDenied`。校验与大小错误与 `POST /monit/dashboard/create` 相同。\n- 会记录审计日志。",
           "href": "/zh/api-reference/monitors/dashboards/monit-dashboard-write-update",
           "metadata": {
             "sidebarTitle": "更新仪表盘"
@@ -65180,7 +67430,7 @@
                                         "legend_alias": "{{env}} requests",
                                         "query": {
                                           "mode": "range",
-                                          "expr": "sum(rate(http_requests_total{env=\"{{env}}\"}[5m]))",
+                                          "expr": "sum(rate(http_requests_total{env=\"${env}\"}[5m]))",
                                           "args": {},
                                           "min_step_seconds": 30
                                         }
@@ -65315,7 +67565,7 @@
                                   "legend_alias": "{{env}} requests",
                                   "query": {
                                     "mode": "range",
-                                    "expr": "sum(rate(http_requests_total{env=\"{{env}}\"}[5m]))",
+                                    "expr": "sum(rate(http_requests_total{env=\"${env}\"}[5m]))",
                                     "args": {},
                                     "min_step_seconds": 30
                                   }
@@ -65355,7 +67605,7 @@
           "Monitors/仪表盘"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | **300 requests/minute**; **20 requests/second** per account |\n| 权限要求 | **仪表盘管理**（`monit`） |\n\n## 使用说明\n\n- 源目录与目标目录都必须可写。\n- 定义不变，因此仅当仪表盘已在 `folder_id` 中时 `changed` 才为 false。\n- 会记录审计日志。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **仪表盘管理**（`monit`） |\n\n## 使用说明\n\n- 调用方必须同时能访问当前目录与目标目录（本人创建或归属其团队的目录及其子目录；账户所有者与管理员可访问全部目录）。无权访问当前目录返回 `AccessDenied`；目标目录不存在或无权访问返回 `FolderNotFound`（HTTP 404）。\n- 定义不会改动，但真正移动时 `revision` 仍会加 1 并记录一条版本。若仪表盘已在 `folder_id` 中，`changed` 为 false，且不做任何写入。\n- `expected_revision` 必须等于已存版本号，否则返回 `DashboardRevisionConflict`（HTTP 409）；位于回收站的仪表盘返回 `DashboardDeleted`（HTTP 410）。\n- 会记录审计日志。",
           "href": "/zh/api-reference/monitors/dashboards/monit-dashboard-write-move",
           "metadata": {
             "sidebarTitle": "移动仪表盘"
@@ -65462,7 +67712,7 @@
                                         "legend_alias": "{{env}} requests",
                                         "query": {
                                           "mode": "range",
-                                          "expr": "sum(rate(http_requests_total{env=\"{{env}}\"}[5m]))",
+                                          "expr": "sum(rate(http_requests_total{env=\"${env}\"}[5m]))",
                                           "args": {},
                                           "min_step_seconds": 30
                                         }
@@ -65539,12 +67789,12 @@
       "post": {
         "operationId": "monit-dashboard-write-delete",
         "summary": "删除仪表盘",
-        "description": "把仪表盘移入回收站。",
+        "description": "把仪表盘移入回收站，30 天内可恢复。",
         "tags": [
           "Monitors/仪表盘"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | **300 requests/minute**; **20 requests/second** per account |\n| 权限要求 | **仪表盘管理**（`monit`） |\n\n## 使用说明\n\n- 这是软删除：定义保留 30 天，可用 `POST /monit/dashboard/restore` 恢复。\n- 返回的 `revision` 是本次删除记录的版本号。\n- 会记录审计日志。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **仪表盘管理**（`monit`） |\n\n## 使用说明\n\n- 这是软删除：仪表盘进入回收站，删除 30 天后连同全部版本被永久清除。在此之前可用 `POST /monit/dashboard/restore` 恢复。\n- 删除会使 `revision` 加 1；返回的 `revision` 就是恢复时要传入的 `expected_revision`。\n- `expected_revision` 必须等于已存版本号，否则返回 `DashboardRevisionConflict`（HTTP 409）；删除已在回收站中的仪表盘返回 `DashboardDeleted`（HTTP 410）。\n- 会记录审计日志。",
           "href": "/zh/api-reference/monitors/dashboards/monit-dashboard-write-delete",
           "metadata": {
             "sidebarTitle": "删除仪表盘"
@@ -65621,7 +67871,7 @@
           "Monitors/仪表盘"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | **300 requests/minute**; **20 requests/second** per account |\n| 权限要求 | **仪表盘管理**（`monit`） |\n\n## 使用说明\n\n- 省略 `folder_id` 表示恢复到原目录；若原目录已不可写，调用会以 `RestoreFolderRequired` 失败，此时必须指定目标目录。\n- 恢复一个不在回收站中的仪表盘会以 `DashboardNotFound` 失败。\n- 会记录审计日志。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **仪表盘管理**（`monit`） |\n\n## 使用说明\n\n- 只能恢复回收站中的仪表盘；其他仪表盘返回 `DashboardNotFound`（HTTP 404）。\n- `expected_revision` 必须等于该仪表盘在回收站中的当前版本号（即删除接口返回、回收站列表中显示的 `revision`），否则返回 `DashboardRevisionConflict`（HTTP 409）。\n- 省略 `folder_id` 表示恢复到原目录。若原目录已不存在，账户所有者与管理员会收到 `RestoreFolderRequired`（HTTP 409），需指定目标目录；其他成员只能恢复原目录仍可访问的仪表盘，否则返回 `DashboardNotFound`。\n- 目标目录不存在或无权访问时返回 `FolderNotFound`（HTTP 404）。恢复会使 `revision` 加 1。\n- 会记录审计日志。",
           "href": "/zh/api-reference/monitors/dashboards/monit-dashboard-write-restore",
           "metadata": {
             "sidebarTitle": "恢复仪表盘"
@@ -65726,7 +67976,7 @@
                                       "legend_alias": "{{env}} requests",
                                       "query": {
                                         "mode": "range",
-                                        "expr": "sum(rate(http_requests_total{env=\"{{env}}\"}[5m]))",
+                                        "expr": "sum(rate(http_requests_total{env=\"${env}\"}[5m]))",
                                         "args": {},
                                         "min_step_seconds": 30
                                       }
@@ -65802,12 +68052,12 @@
       "post": {
         "operationId": "monit-dashboard-read-list",
         "summary": "查询仪表盘列表",
-        "description": "列出某个目录下的仪表盘。",
+        "description": "列出某个目录下直接存放的仪表盘，支持关键词搜索与分页。",
         "tags": [
           "Monitors/仪表盘"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | **1,000 requests/minute**; **50 requests/second** per account |\n| 权限要求 | 任意有效 `app_key`；结果限于其所属成员可读的目录 |\n\n## 使用说明\n\n- `folder_id` 必填；列表始终包含子目录。\n- `query` 按空白拆分后匹配标题与描述。\n- 此处排序键仅限 `title` 与 `updated_at`，最多两个，默认按 `updated_at` 倒序。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 只返回直接存放在 `folder_id` 中的仪表盘，不包含其子目录中的仪表盘。跨目录查找请用 `POST /monit/dashboard/search`。\n- `folder_id` 必须是`app_key` 所属成员可访问的目录：其本人创建或归属其所在团队的目录及这些目录的全部子目录；账户所有者与管理员可访问全部目录之一，否则以 `FolderNotFound`（HTTP 404）失败。回收站中的仪表盘不会被列出。\n- `query` 按空白拆分为多个词；标题或描述中包含每一个词（子串匹配）的仪表盘才会命中。\n- 排序键为 `title` 与 `updated_at`，最多两个且不可重复；默认按 `updated_at` 倒序，相同值再按 `dashboard_id` 排序。",
           "href": "/zh/api-reference/monitors/dashboards/monit-dashboard-read-list",
           "metadata": {
             "sidebarTitle": "查询仪表盘列表"
@@ -65912,7 +68162,7 @@
           "Monitors/仪表盘"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | **1,000 requests/minute**; **50 requests/second** per account |\n| 权限要求 | 任意有效 `app_key`；结果限于其所属成员可读的目录 |\n\n## 使用说明\n\n- `query` 至少需要一个单词；空查询会以 `InvalidParameter` 失败。\n- 范围限于 `app_key` 所属成员可读的目录——该接口不会扩大访问范围。\n- 排序键仅限 `title` 与 `updated_at`。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- `query` 至少需要一个词；为空或只含空白时以 `InvalidParameter` 失败。标题或描述中包含每一个词（子串匹配）的仪表盘才会命中。\n- 结果只包含`app_key` 所属成员可访问的目录：其本人创建或归属其所在团队的目录及这些目录的全部子目录；账户所有者与管理员可访问全部目录中的仪表盘。回收站中的仪表盘不会返回。\n- 排序键为 `title` 与 `updated_at`，最多两个且不可重复；默认按 `updated_at` 倒序。",
           "href": "/zh/api-reference/monitors/dashboards/monit-dashboard-read-search",
           "metadata": {
             "sidebarTitle": "搜索仪表盘"
@@ -66016,7 +68266,7 @@
           "Monitors/仪表盘"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | **1,000 requests/minute**; **50 requests/second** per account |\n| 权限要求 | **仪表盘管理**（`monit`） |\n\n## 使用说明\n\n- 排序键仅限 `title` 与 `deleted_at`，默认按 `deleted_at` 倒序。\n- 与读接口不同，该接口受「仪表盘管理」权限点管控。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **仪表盘管理**（`monit`） |\n\n## 使用说明\n\n- 列出位于`app_key` 所属成员可访问的目录：其本人创建或归属其所在团队的目录及这些目录的全部子目录；账户所有者与管理员可访问全部目录中的已删除仪表盘。每条记录在删除 30 天后被永久清除。\n- 排序键为 `title` 与 `deleted_at`，最多两个且不可重复；默认按 `deleted_at` 倒序。\n- 与其他仪表盘读接口不同，该接口需要「仪表盘管理」权限。",
           "href": "/zh/api-reference/monitors/dashboards/monit-dashboard-trash-read-list",
           "metadata": {
             "sidebarTitle": "查询回收站仪表盘"
@@ -66116,7 +68366,7 @@
           "Monitors/仪表盘"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | **1,000 requests/minute**; **50 requests/second** per account |\n| 权限要求 | 任意有效 `app_key`；结果限于其所属成员可读的目录 |\n\n## 使用说明\n\n- 最多保留 20 个版本（含当前版本）；产生新版本时更早的会被丢弃。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 按最新在前最多返回最近 20 个版本。创建、每次改变定义的更新、移动、删除与恢复都会记录一个版本；更早的版本会被清理。\n- 只有通过 `POST /monit/dashboard/update` 并附带说明写入的版本才有 `message`。\n- 只能看到位于`app_key` 所属成员可访问的目录：其本人创建或归属其所在团队的目录及这些目录的全部子目录；账户所有者与管理员可访问全部目录中的仪表盘，其他返回 `DashboardNotFound`（HTTP 404）；位于回收站的仪表盘返回 `DashboardDeleted`（HTTP 410）。",
           "href": "/zh/api-reference/monitors/dashboards/monit-dashboard-revision-read-list",
           "metadata": {
             "sidebarTitle": "查询仪表盘版本列表"
@@ -66206,7 +68456,7 @@
           "Monitors/仪表盘"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | **1,000 requests/minute**; **50 requests/second** per account |\n| 权限要求 | 任意有效 `app_key`；结果限于其所属成员可读的目录 |\n\n## 使用说明\n\n- 版本号按仪表盘独立编号，从 1 开始。\n- 已滚动出 20 条窗口的版本会返回 `DashboardNotFound`。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 版本号按仪表盘独立编号，从 1（创建）开始。早于最近 20 个的版本已被清理，返回 `DashboardNotFound`（HTTP 404）。\n- 只能看到位于`app_key` 所属成员可访问的目录：其本人创建或归属其所在团队的目录及这些目录的全部子目录；账户所有者与管理员可访问全部目录中的仪表盘；位于回收站的仪表盘返回 `DashboardDeleted`（HTTP 410），需先恢复才能读取历史。",
           "href": "/zh/api-reference/monitors/dashboards/monit-dashboard-revision-read-get",
           "metadata": {
             "sidebarTitle": "查看仪表盘版本详情"
@@ -66307,7 +68557,7 @@
                                       "legend_alias": "{{env}} requests",
                                       "query": {
                                         "mode": "range",
-                                        "expr": "sum(rate(http_requests_total{env=\"{{env}}\"}[5m]))",
+                                        "expr": "sum(rate(http_requests_total{env=\"${env}\"}[5m]))",
                                         "args": {},
                                         "min_step_seconds": 30
                                       }
@@ -66386,7 +68636,7 @@
           "Monitors/仪表盘"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | **1,000 requests/minute**; **50 requests/second** per account |\n| 权限要求 | 任意有效 `app_key`；结果限于其所属成员可读的目录 |\n\n## 使用说明\n\n- 用于渲染导航，或让 Agent 在执行前定位面板 ID——可避免拉取完整定义。\n- 设置 `target_id` 时只返回包含该 tab/section/panel 的分支；ID 不存在会以 `TargetNotFound` 失败。\n- 面板条目只含可视化 `kind` 与数据源类型，不包含面板查询。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 可用于渲染导航，或在调用 `POST /monit/dashboard/panel/run` 前定位面板 ID，而无需下载查询。\n- `target_id` 为 tab ID 时返回整个 tab；为 section ID 时返回该 tab，但只含该 section 且不含顶层面板；为面板 ID 时只返回该面板及其所在 tab/section。ID 不存在时以 `TargetNotFound`（HTTP 404）失败。\n- 面板条目只含可视化 `kind` 与数据源类型，不含查询。数据源变量的 `selection` 固定为 `single` 且不含 `all`。\n- 只能看到位于`app_key` 所属成员可访问的目录：其本人创建或归属其所在团队的目录及这些目录的全部子目录；账户所有者与管理员可访问全部目录中的仪表盘；位于回收站的仪表盘返回 `DashboardDeleted`（HTTP 410）。",
           "href": "/zh/api-reference/monitors/dashboards/monit-dashboard-read-outline",
           "metadata": {
             "sidebarTitle": "获取仪表盘大纲"
@@ -66529,7 +68779,7 @@
           "Monitors/仪表盘"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | **16 requests/second** (no per-minute cap) per account |\n| 权限要求 | **数据源查看**（`monit`） |\n\n## 使用说明\n\n- 无法解析的变量不会导致调用失败：其条目会带上 `error`，并且不出现在 `selections` 中。\n- 显式传入空的 `values` 表示未解析——解析器不会回退到存储的默认值。\n- 选择最多 20 个变量；变量名需匹配 `^[A-Za-z_][A-Za-z0-9_]{0,63}$`。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **16 次/秒**（无每分钟上限） |\n| 权限要求 | **数据源查看**（`monit`） |\n\n## 使用说明\n\n- 解析已存仪表盘当前版本的变量。`variables` 是调用方当前的选择；未给出的变量回退到存储的默认值（`custom`、`query` 变量用 `default`；`datasource` 变量用 `default_datasource_id`，若它已不在候选项中，则取按名称排序的第一个候选项）。\n- 无法解析的变量不会导致调用失败：其条目会带上 `error`，并且不出现在 `selections` 中。常见原因：既无选择也无默认值、所选值不在候选项中、依赖项未解析、数据源不可达。\n- 显式传入空的 `values` 表示未解析（`variable_invalid`），解析器不会回退到存储的默认值。\n- 变量按依赖顺序解析，依赖了失败变量的变量也会报错。`variables` 中出现仪表盘未定义的变量名时，调用以 HTTP 400 失败。\n- 每个变量最多返回 1000 个候选项，所有候选项合计须在 8 MiB 以内，否则以 `EntityTooLarge`（HTTP 413）失败。`query` 变量只能对 Prometheus、MySQL、Loki 数据源执行。\n- 调用方须能看到该仪表盘所在的目录，否则返回 `DashboardNotFound`（HTTP 404）。整个调用有 35 秒的总时限，超时返回 `RuntimeTimeout`（HTTP 504）。",
           "href": "/zh/api-reference/monitors/dashboards/monit-dashboard-variable-read-resolve",
           "metadata": {
             "sidebarTitle": "解析仪表盘变量"
@@ -66650,7 +68900,7 @@
           "Monitors/仪表盘"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | **16 requests/second** (no per-minute cap) per account |\n| 权限要求 | **数据源查看**（`monit`） |\n\n## 使用说明\n\n- `context` 为 `new` 时指向尚无仪表盘的目录，为 `existing` 时指向已存仪表盘；两者字段混用会校验失败。\n- 不落库，因此响应中没有 `dashboard_id` 或 `revision`。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **16 次/秒**（无每分钟上限） |\n| 权限要求 | **数据源查看**（`monit`） |\n\n## 使用说明\n\n- 解析尚未存入仪表盘的草稿变量列表，便于编辑器在保存前测试变量。不落库，因此响应中没有 `dashboard_id` 或 `revision`。\n- 草稿属于已存仪表盘时，`context.kind` 为 `existing` 并带 `dashboard_id`；仪表盘尚不存在时为 `new` 并带 `folder_id`；混用另一种类型的字段会校验失败（HTTP 400）。调用方需要能访问该仪表盘所在目录或该目录（否则返回 403/404）。\n- 草稿 `variables` 按与已存定义相同的规则校验（名称、依赖、选项上限、最多 20 个变量、1 MiB）；违规时以 HTTP 400 失败，超出大小限制时为 HTTP 413。\n- 解析行为与「解析仪表盘变量」一致：失败的变量带 `error` 且不出现在 `selections` 中，空的 `values` 选择视为未解析。\n- 整个调用有 35 秒的总时限，超时返回 `RuntimeTimeout`（HTTP 504）。",
           "href": "/zh/api-reference/monitors/dashboards/monit-dashboard-variable-read-preview",
           "metadata": {
             "sidebarTitle": "预览草稿变量"
@@ -66799,7 +69049,7 @@
           "Monitors/仪表盘"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | **16 requests/second** (no per-minute cap) per account |\n| 权限要求 | **数据源查看**（`monit`） |\n\n## 使用说明\n\n- 用于在真正执行前展示面板将命中哪个数据源、使用什么表达式。\n- `panel_ids` 接受 1～100 个唯一 ID；面板在仪表盘中不存在时产生 `state: \"error\"` 条目，而不会使整个调用失败。\n- 只有部分查询解析成功的面板返回 `state: \"partial\"`。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **16 次/秒**（无每分钟上限） |\n| 权限要求 | **数据源查看**（`monit`） |\n\n## 使用说明\n\n- 用于在运行之前展示面板将命中哪个数据源、使用什么表达式。不会执行任何查询。\n- `panel_ids` 接受 1～100 个唯一 ID，按请求顺序返回。面板不在该仪表盘中时，返回 `state: \"error\"`、原因 `panel_missing`，而不会使整个调用失败；文本面板返回 `state: \"error\"`、原因 `invalid_request`。\n- 面板的全部查询解析成功时 `state` 为 `success`，只有部分成功为 `partial`，全部失败为 `error`。`queries` 列出解析成功的查询；`error` 只报告第一个失败。\n- 内置时间变量（如步长、时间范围）根据 `time` 和 `max_data_points` 渲染；`preserve_builtin_variables` 为 `true` 时原样保留，供调用方用自己的窗口渲染。用户变量始终会被解析。\n- 面板查询只能绑定到 Prometheus、MySQL、Loki 数据源。整个调用有 35 秒的总时限，超时返回 `RuntimeTimeout`（HTTP 504）。",
           "href": "/zh/api-reference/monitors/dashboards/monit-dashboard-query-read-resolve",
           "metadata": {
             "sidebarTitle": "解析面板查询"
@@ -66925,7 +69175,7 @@
           "Monitors/仪表盘"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | **16 requests/second** (no per-minute cap) per account |\n| 权限要求 | **数据源查看**（`monit`） |\n\n## 使用说明\n\n- 省略 `revision` 表示按当前版本运行；传入它可让调用返回过期错误，而不是返回已被覆盖的数据。\n- `run_state` 汇总各查询状态——部分 ref 成功为 `partial`；数据源接受了调用但查询不匹配其类型时为 `incompatible`。\n- 每个 ref 的 `execution` 载荷随数据源而异且原样透传；`child_request_id` 可用于追踪底层数据源调用。\n- `max_data_points` 默认 100，取值 2～5000。整个响应上限 8 MiB。\n- 单个面板内查询的并发上限为 6。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **32 次/秒**（无每分钟上限） |\n| 权限要求 | **数据源查看**（`monit`） |\n\n## 使用说明\n\n- 对已存仪表盘当前版本的单个面板，把其全部查询发往对应数据源执行。即使所有查询都失败，调用仍返回 HTTP 200，请查看 `run_state` 以及各 ref 的 `state`、`error`。\n- 省略 `revision`（或传 0）表示按当前版本运行。传入它时，若仪表盘已被修改，调用以 `DashboardRevisionConflict`（HTTP 409）失败，而不是返回基于过期定义的数据。\n- `run_state` 汇总各 ref：全部成功为 `success`，至少一个成功且至少一个未成功为 `partial`，否则为 `cancelled`、`incompatible` 或 `error`。查询已执行但结果与面板可视化不匹配（例如配置的值字段缺失或不是数值）时，该 ref 为 `incompatible`。\n- 每个 ref 的 `execution` 随数据源而异且原样透传；`child_request_id` 标识底层数据源调用。文本面板不能运行（HTTP 400），`panel_id` 不存在时返回 `TargetNotFound`（HTTP 404）。\n- `max_data_points` 默认 100，取值 2～5000。单个面板内最多同时运行 6 个查询。响应超过 8 MiB 时以 `EntityTooLarge`（HTTP 413）拒绝，而不会截断。整个调用有 35 秒的总时限，超时返回 `RuntimeTimeout`（HTTP 504）。",
           "href": "/zh/api-reference/monitors/dashboards/monit-dashboard-panel-read-run",
           "metadata": {
             "sidebarTitle": "运行仪表盘面板"
@@ -67086,7 +69336,7 @@
           "Monitors/仪表盘"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | **16 requests/second** (no per-minute cap) per account |\n| 权限要求 | **数据源查看**（`monit`） |\n\n## 使用说明\n\n- 用于在用户仍在编辑时校验面板——不会写入任何内容，也不会产生版本。\n- 草稿同样受已存仪表盘的全部限制：网格重叠、各可视化类型的查询数量，以及 1 MiB 定义上限。\n- 响应结构与面板运行一致，只是不含 `dashboard_id`。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **32 次/秒**（无每分钟上限） |\n| 权限要求 | **数据源查看**（`monit`） |\n\n## 使用说明\n\n- 用于在用户仍在编辑面板时检查它：草稿面板及其变量被内联执行，不会写入任何内容，也不会产生版本。\n- `context` 把草稿关联到已存仪表盘（`existing` 并带 `dashboard_id`）或尚无仪表盘的目录（`new` 并带 `folder_id`）。调用方需要能访问该仪表盘所在目录或该目录。\n- 草稿 `panel` 与 `variables` 按与已存定义相同的规则校验（网格、各可视化类型的查询数量、变量引用），且不得超过 1 MiB；违规时以 HTTP 400 失败，超出大小限制时为 HTTP 413。文本面板不能预览。\n- 响应结构与面板运行一致，只是不含 `dashboard_id` 和 `revision`。即使所有查询都失败，也返回 HTTP 200，请查看 `run_state` 以及各 ref 的 `state`、`error`。\n- `max_data_points` 默认 100，取值 2～5000。同时最多运行 6 个查询。响应超过 8 MiB 时以 `EntityTooLarge`（HTTP 413）拒绝。整个调用有 35 秒的总时限，超时返回 `RuntimeTimeout`（HTTP 504）。",
           "href": "/zh/api-reference/monitors/dashboards/monit-dashboard-panel-read-preview",
           "metadata": {
             "sidebarTitle": "预览草稿面板"
@@ -67238,7 +69488,7 @@
                       "legend_alias": "{{env}} requests",
                       "query": {
                         "mode": "range",
-                        "expr": "sum(rate(http_requests_total{env=\"{{env}}\"}[5m]))",
+                        "expr": "sum(rate(http_requests_total{env=\"${env}\"}[5m]))",
                         "args": {},
                         "min_step_seconds": 30
                       }
@@ -67305,16 +69555,16 @@
     "/monit/folder/list": {
       "post": {
         "operationId": "monit-folder-read-list",
-        "summary": "查询监控节点列表",
+        "summary": "查询监控目录列表",
         "description": "列出调用方可读的全部监控节点。",
         "tags": [
           "Monitors/规则分组"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | **1,000 requests/minute**; **50 requests/second** per account |\n| 权限要求 | **告警规则查看** 或 **节点权限查看**（`monit`） |\n\n## 使用说明\n\n- 响应是可读目录的扁平列表而非树：请用 `parent_id` 与 `parent_path` 重建层级，并在客户端自行搜索。\n- 仪表盘与告警规则共用这棵目录树，因此同一批 ID 会作为仪表盘载荷中的 `folder_id` 出现。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **告警规则查看**、**告警规则管理**、**节点权限查看**或**节点权限管理**（`monit`） |\n\n## 使用说明\n\n- 响应是可见文件夹的扁平列表而非树：请用 `parent_id` 与 `parent_path` 重建层级，并在客户端自行搜索。账户下没有可见文件夹时返回 `[]`。\n- 账户所有者和管理员可看到全部文件夹。其他成员可看到自己创建的文件夹、归属于自己所在团队的文件夹、这些文件夹下的全部子文件夹，以及到达它们所需经过的祖先文件夹。\n- 仪表盘与告警规则共用这棵文件夹树，因此同一批 ID 会作为仪表盘载荷和告警规则中的 `folder_id` 出现。",
           "href": "/zh/api-reference/monitors/rule-folders/monit-folder-read-list",
           "metadata": {
-            "sidebarTitle": "查询监控节点列表"
+            "sidebarTitle": "查询监控目录列表"
           }
         },
         "responses": {
@@ -67369,6 +69619,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -67387,7 +69640,7 @@
           "On-call/集成中心"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **集成中心查看**（`on-call`） |\n\n## 使用说明\n\n- 不传 `orderby` 时按控制台排序返回，此时 `p`/`limit` 依然生效。\n- `supports_api_create` 表示该类型能否通过 `POST /integration/create` 创建。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **集成中心查看**（`on-call`） |\n\n## 使用说明\n\n- 不传 `orderby` 时按控制台排序返回，此时 `p`/`limit` 依然生效。\n- `supports_api_create` 表示该类型能否通过 `POST /integration/create` 创建。\n- `category` 取值不做校验，未知值会返回空列表。",
           "href": "/zh/api-reference/on-call/integrations/integration-api-read-type-list",
           "metadata": {
             "sidebarTitle": "查询集成类型列表"
@@ -67448,6 +69701,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -67481,7 +69737,7 @@
           "On-call/集成中心"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **集成中心查看**（`on-call`） |\n\n## 使用说明\n\n- `orderby` 默认 `created_at`；`plugin_type` 按底层插件排序。\n- `plugin_type`、`status`、`category` 支持逗号分隔多值；`ref_ids` 每个值必须以 `c_`、`a_` 或 `w_` 开头；`c_` 过滤值通过格式校验，但不会返回协作空间专属集成。\n- 传入 `is_my_team` 时仅返回你所在团队的集成，`team_ids` 会在该范围内进一步收窄。\n- 这些接口仅管理公共（账户级）集成，不管理协作空间专属集成。\n- 列表项包含 `settings`、`integration_key`、`plugin_id`、`account_id` 及旧 ID 别名 `data_source_id`。`settings` 中已保存的密钥类值返回 `******`，`integration_key` 按原值返回。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **集成中心查看**（`on-call`） |\n\n## 使用说明\n\n- `orderby` 默认 `created_at`；`plugin_type` 按底层插件排序。结果先按 `ref_id` 升序排列，`orderby` 在相同 `ref_id` 内生效。\n- `plugin_type`、`status`、`category` 支持逗号分隔多值；`ref_ids` 每个值必须以 `c_`、`a_` 或 `w_` 开头；`c_` 过滤值通过格式校验，但不会返回协作空间专属集成。\n- 传入 `is_my_team` 时仅返回你所在团队的集成，`team_ids` 会在该范围内进一步收窄；你不属于任何团队，或 `team_ids` 与你的团队没有交集时，返回空列表。\n- 这些接口仅管理公共（账户级）集成，不管理协作空间专属集成。\n- 列表项包含 `settings`、`integration_key`、`plugin_id`、`account_id` 及旧 ID 别名 `data_source_id`。`settings` 中已保存的密钥类值返回 `******`，`integration_key` 按原值返回。",
           "href": "/zh/api-reference/on-call/integrations/integration-api-read-list",
           "metadata": {
             "sidebarTitle": "查询集成列表"
@@ -67553,6 +69809,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -67586,7 +69845,7 @@
           "On-call/集成中心"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **集成中心查看**（`on-call`） |\n\n## 使用说明\n\n- 这些接口仅管理公共（账户级）集成，不管理协作空间专属集成。\n- `settings` 中已保存的密钥类值返回 `******`，未设置的保持为空；集成 Key 按原值返回。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **集成中心查看**（`on-call`） |\n\n## 使用说明\n\n- 这些接口仅管理公共（账户级）集成，不管理协作空间专属集成。\n- `settings` 中已保存的密钥类值返回 `******`，未设置的保持为空；集成 Key 按原值返回。\n- ID 不存在或属于协作空间专属集成时返回 `ResourceNotFound`。",
           "href": "/zh/api-reference/on-call/integrations/integration-api-read-info",
           "metadata": {
             "sidebarTitle": "查询集成详情"
@@ -67648,6 +69907,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -67679,7 +69941,7 @@
           "On-call/集成中心"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **集成中心管理**（`on-call`） |\n\n## 使用说明\n\n- `plugin_type` 必须是 `POST /integration/type/list` 中 `supports_api_create: true` 的类型，否则返回 `InvalidParameter`。\n- 这些接口仅管理公共（账户级）集成，不管理协作空间专属集成。\n- 不传 `integration_key` 时自动生成；传入时须满足长度、账户后缀与唯一性校验。\n- 传 `is_test: true` 时请检查 `test.success`，不能只根据 HTTP 200 判断插件测试成功。\n- 每次调用都会记录到账户审计日志。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **集成中心管理**（`on-call`） |\n\n## 使用说明\n\n- `plugin_type` 必须是 `POST /integration/type/list` 中 `supports_api_create: true` 的类型，否则返回 `InvalidParameter`。\n- `status` 为 `disabled` 的类型返回 `InvalidParameter`；当前套餐不包含的类型返回 `NoLicense`。\n- 这些接口仅管理公共（账户级）集成，不管理协作空间专属集成。\n- 不传 `integration_key` 时自动生成；传入时须满足长度、账户后缀与唯一性校验。\n- 传 `is_test: true` 时请检查 `test.success`，不能只根据 HTTP 200 判断插件测试成功。\n- 每次调用都会记录到账户审计日志。",
           "href": "/zh/api-reference/on-call/integrations/integration-api-write-create",
           "metadata": {
             "sidebarTitle": "创建集成"
@@ -67725,6 +69987,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -67764,7 +70029,7 @@
           "On-call/集成中心"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **集成中心管理**（`on-call`） |\n\n## 使用说明\n\n- 仅发送的字段会被修改，未发送的字段保持原值。\n- 提交 `settings` 会替换配置；已识别的敏感字段不传或传 `******` 时保留原值。保留已存密钥的同时修改它的发送目标（如 `endpoint`、`url`、数据库主机或端口、IM 接口地址）会被拒绝，需要随新目标重新填写密钥；没有已存值的字段传 `******` 也会被拒绝。清空 Headers 请传 `headers: {}`；清空 Body 请使用该集成类型的显式空值。\n- 同时提交 `settings` 与 `is_test: true` 可获得插件测试结果，返回的 settings 中密钥同样返回 `******`。\n- 这些接口仅管理公共（账户级）集成，不管理协作空间专属集成。\n- 写操作还需对象权限：主体账户、管理员、创建者或所属团队成员可操作；未设置团队时，拥有集成中心管理权限的成员可操作，只读集成不可修改。\n- 每次调用都会记录到账户审计日志。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **集成中心管理**（`on-call`） |\n\n## 使用说明\n\n- 仅发送的字段会被修改，未发送的字段保持原值。\n- 提交 `settings` 会替换配置；已识别的敏感字段不传或传 `******` 时保留原值。保留已存密钥的同时修改它的发送目标（如 `endpoint`、`url`、数据库主机或端口、IM 接口地址）会被拒绝，需要随新目标重新填写密钥；没有已存值的字段传 `******` 也会被拒绝。清空 Headers 请传 `headers: {}`；清空 Body 请使用该集成类型的显式空值。\n- 同时提交 `settings` 与 `is_test: true` 可获得插件测试结果，返回的 settings 中密钥同样返回 `******`。\n- 处理期间若有其他请求修改了同一集成的配置，本次调用返回 `RequestLocked`，重试即可。当前套餐已不包含该集成类型时返回 `NoLicense`。\n- 这些接口仅管理公共（账户级）集成，不管理协作空间专属集成。\n- 写操作还需对象权限：主体账户、管理员、创建者或所属团队成员可操作；未设置团队时，拥有集成中心管理权限的成员可操作，只读集成不可修改。\n- 每次调用都会记录到账户审计日志。",
           "href": "/zh/api-reference/on-call/integrations/integration-api-write-update",
           "metadata": {
             "sidebarTitle": "更新集成"
@@ -67830,6 +70095,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -67907,6 +70175,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -67938,7 +70209,7 @@
           "On-call/集成中心"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **集成中心管理**（`on-call`） |\n\n## 使用说明\n\n- 启用会恢复该集成的拉取任务与心跳，并要求当前套餐包含该集成类型。\n- 每次调用都会记录到账户审计日志。\n- 这些接口仅管理公共（账户级）集成，不管理协作空间专属集成。\n- 写操作还需对象权限：主体账户、管理员、创建者或所属团队成员可操作；未设置团队时，拥有集成中心管理权限的成员可操作，只读集成不可修改。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **集成中心管理**（`on-call`） |\n\n## 使用说明\n\n- 启用会恢复该集成的拉取任务与心跳，并要求当前套餐包含该集成类型。\n- 对已启用的集成调用启用、或对已禁用的集成调用禁用，会直接成功且不做变更。\n- 每次调用都会记录到账户审计日志。\n- 这些接口仅管理公共（账户级）集成，不管理协作空间专属集成。\n- 写操作还需对象权限：主体账户、管理员、创建者或所属团队成员可操作；未设置团队时，拥有集成中心管理权限的成员可操作，只读集成不可修改。",
           "href": "/zh/api-reference/on-call/integrations/integration-api-write-enable",
           "metadata": {
             "sidebarTitle": "启用集成"
@@ -67977,6 +70248,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -68008,7 +70282,7 @@
           "On-call/集成中心"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **集成中心管理**（`on-call`） |\n\n## 使用说明\n\n- 禁用后停止接收事件并暂停定时拉取任务，配置保留，可再次启用。\n- 每次调用都会记录到账户审计日志。\n- 这些接口仅管理公共（账户级）集成，不管理协作空间专属集成。\n- 写操作还需对象权限：主体账户、管理员、创建者或所属团队成员可操作；未设置团队时，拥有集成中心管理权限的成员可操作，只读集成不可修改。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **集成中心管理**（`on-call`） |\n\n## 使用说明\n\n- 禁用后停止接收事件并暂停定时拉取任务，配置保留，可再次启用。\n- 对已启用的集成调用启用、或对已禁用的集成调用禁用，会直接成功且不做变更。\n- 每次调用都会记录到账户审计日志。\n- 这些接口仅管理公共（账户级）集成，不管理协作空间专属集成。\n- 写操作还需对象权限：主体账户、管理员、创建者或所属团队成员可操作；未设置团队时，拥有集成中心管理权限的成员可操作，只读集成不可修改。",
           "href": "/zh/api-reference/on-call/integrations/integration-api-write-disable",
           "metadata": {
             "sidebarTitle": "禁用集成"
@@ -68047,6 +70321,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -68119,6 +70396,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -68145,12 +70425,12 @@
       "post": {
         "operationId": "monit-folder-read-health",
         "summary": "获取监控目录健康摘要",
-        "description": "获取可见目录的健康摘要，包含后代目录中的问题。",
+        "description": "获取可见监控文件夹的问题标记，包含后代文件夹中的问题。",
         "tags": [
           "Monitors/规则分组"
         ],
         "x-mint": {
-          "content": "## 限制\n\n| 项目 | 值 |\n| ------ | ----- |\n| 频率限制 | 每账户 **30 次/分钟**；**2 次/秒** |\n| 权限 | **告警规则查看**、**告警规则管理**、**节点权限查看**或**节点权限管理**（`monit`） |\n\n## 使用说明\n\n- 问题包括活跃告警和告警规则运行问题，并向可见祖先目录汇总。\n- 此操作扫描目录规则和运行状态，请避免频繁轮询。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **30 次/分钟**；**2 次/秒** |\n| 权限要求 | **告警规则查看**、**告警规则管理**、**节点权限查看**或**节点权限管理**（`monit`） |\n\n## 使用说明\n\n- `items` 对调用方可见的每个文件夹返回一项（与 `/monit/folder/list` 的范围相同），按 `id` 升序排列。\n- 当文件夹自身或其任一后代文件夹中的规则存在活跃告警或运行问题时，`has_issue` 为 true，且该问题也会显示在每一级可见的祖先文件夹上。只统计调用方可读文件夹中的规则。\n- 此操作会扫描文件夹中的规则和运行状态，请避免频繁轮询。",
           "href": "/zh/api-reference/monitors/rule-folders/monit-folder-read-health",
           "metadata": {
             "sidebarTitle": "获取监控目录健康摘要"
@@ -68196,6 +70476,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -68209,12 +70492,12 @@
       "post": {
         "operationId": "monit-folder-write-create",
         "summary": "创建监控目录",
-        "description": "在顶层或有权访问的父目录下创建监控目录。",
+        "description": "在根级别或调用方有权修改的父文件夹下创建监控文件夹。",
         "tags": [
           "Monitors/规则分组"
         ],
         "x-mint": {
-          "content": "## 限制\n\n| 项目 | 值 |\n| ------ | ----- |\n| 频率限制 | 每账户 **300 次/分钟**；**20 次/秒** |\n| 权限 | **告警规则管理**或**节点权限管理**（`monit`） |\n\n## 使用说明\n\n- 传入 `parent_id: 0` 或省略该字段以创建顶层目录。您必须有权访问父目录。\n- 每次调用均记录账户审计日志。请勿在请求字段中传入密钥。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **告警规则管理**或**节点权限管理**（`monit`） |\n\n## 使用说明\n\n- 传入 `parent_id: 0` 或省略该字段以创建根文件夹。要在某个父文件夹下创建，调用方必须有权修改它：账户所有者或管理员、该父文件夹或其任一祖先的创建者，或者被分配到该父文件夹或其任一祖先的团队成员。父文件夹不存在时返回 `InvalidParameter`，无权修改父文件夹时返回 `AccessDenied`。\n- 响应为新创建的文件夹。\n- 每次调用均记录账户审计日志。请勿在请求字段中传入密钥。",
           "href": "/zh/api-reference/monitors/rule-folders/monit-folder-write-create",
           "metadata": {
             "sidebarTitle": "创建监控目录"
@@ -68267,6 +70550,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -68296,12 +70582,12 @@
       "post": {
         "operationId": "monit-folder-write-update",
         "summary": "更新监控目录",
-        "description": "替换有权访问的监控目录的名称、备注和团队归属。",
+        "description": "替换调用方有权修改的监控文件夹的名称、备注和团队归属。",
         "tags": [
           "Monitors/规则分组"
         ],
         "x-mint": {
-          "content": "## 限制\n\n| 项目 | 值 |\n| ------ | ----- |\n| 频率限制 | 每账户 **300 次/分钟**；**20 次/秒** |\n| 权限 | **告警规则管理**或**节点权限管理**（`monit`） |\n\n## 使用说明\n\n- 必须传入 `id` 和 `name`。此操作替换可编辑字段：省略 `note` 会清空备注，省略 `team_id` 会重置为 0。\n- 请使用移动接口更改父目录。\n- 每次调用均记录账户审计日志。请勿在请求字段中传入密钥。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **告警规则管理**或**节点权限管理**（`monit`） |\n\n## 使用说明\n\n- 必须传入 `id` 和 `name`。此操作替换可编辑字段：省略 `note` 会清空备注，省略 `team_id` 会重置为 0。\n- 调用方必须有权修改该文件夹：账户所有者或管理员、该文件夹的创建者或其任一祖先的创建者，或者被分配到该文件夹或其任一祖先的团队成员。文件夹不存在时返回 `InvalidParameter`，无权修改时返回 `AccessDenied`。\n- 请使用移动接口更改父文件夹。响应为更新后的文件夹。\n- 每次调用均记录账户审计日志。请勿在请求字段中传入密钥。",
           "href": "/zh/api-reference/monitors/rule-folders/monit-folder-write-update",
           "metadata": {
             "sidebarTitle": "更新监控目录"
@@ -68354,6 +70640,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -68388,7 +70677,7 @@
           "Monitors/规则分组"
         ],
         "x-mint": {
-          "content": "## 限制\n\n| 项目 | 值 |\n| ------ | ----- |\n| 频率限制 | 每账户 **300 次/分钟**；**20 次/秒** |\n| 权限 | **告警规则管理**或**节点权限管理**（`monit`） |\n\n## 使用说明\n\n- 您必须有权访问源目录和目标目录。\n- 必须传入 `dest_parent_id`；移至顶层时显式传 0。不能移至自身或后代目录下。\n- 后代目录路径在同一事务中更新。\n- 每次调用均记录账户审计日志。请勿在请求字段中传入密钥。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **告警规则管理**或**节点权限管理**（`monit`） |\n\n## 使用说明\n\n- 调用方必须有权修改源文件夹；除非 `dest_parent_id` 为 0，还必须有权修改目标文件夹。\n- 必须传入 `dest_parent_id`；移至根级别时显式传 0。它不能等于 `id`，不能移至自身或后代文件夹下，否则返回 `InvalidParameter`。移动到当前父文件夹时请求成功，但不产生任何变化。\n- 后代文件夹的路径在同一事务中更新，该文件夹及其全部后代的最后更新人都会记为调用方。\n- 每次调用均记录账户审计日志。请勿在请求字段中传入密钥。",
           "href": "/zh/api-reference/monitors/rule-folders/monit-folder-write-move",
           "metadata": {
             "sidebarTitle": "移动监控目录"
@@ -68428,6 +70717,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -68455,12 +70747,12 @@
       "post": {
         "operationId": "monit-folder-write-delete",
         "summary": "删除监控目录",
-        "description": "移除子目录、规则和仪表盘后，删除有权访问的监控目录。",
+        "description": "删除调用方有权修改的空监控文件夹。",
         "tags": [
           "Monitors/规则分组"
         ],
         "x-mint": {
-          "content": "## 限制\n\n| 项目 | 值 |\n| ------ | ----- |\n| 频率限制 | 每账户 **300 次/分钟**；**20 次/秒** |\n| 权限 | **告警规则管理**或**节点权限管理**（`monit`） |\n\n## 使用说明\n\n- 只能删除空目录。存在子目录、告警规则或仪表盘时，返回 HTTP 409，错误码为 `FolderNotEmpty`。\n- 每次调用均记录账户审计日志。请勿在请求字段中传入密钥。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **告警规则管理**或**节点权限管理**（`monit`） |\n\n## 使用说明\n\n- 只能删除空文件夹，不会替您删除其中的内容。存在子文件夹、告警规则或仪表盘时，返回 HTTP 409，错误码为 `FolderNotEmpty`。\n- 调用方必须有权修改该文件夹。文件夹不存在时返回 `InvalidParameter`，无权修改时返回 `AccessDenied`。\n- 每次调用均记录账户审计日志。请勿在请求字段中传入密钥。",
           "href": "/zh/api-reference/monitors/rule-folders/monit-folder-write-delete",
           "metadata": {
             "sidebarTitle": "删除监控目录"
@@ -68500,6 +70792,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
diff --git a/api-reference/platform.openapi.en.json b/api-reference/platform.openapi.en.json
index bb12d2e2e..19f73a016 100644
--- a/api-reference/platform.openapi.en.json
+++ b/api-reference/platform.openapi.en.json
@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Flashduty Open API",
-    "description": "Public HTTP API for the Flashduty incident management platform — incidents, notification templates, channels, schedules, monitors, RUM, and platform administration. Every operation is authenticated with an `app_key` query parameter issued from the Flashduty console under Account → APP Keys. Responses follow a uniform envelope: `{ request_id, data }` on success, `{ request_id, error }` on failure.",
+    "description": "Public HTTP API for the Flashduty incident management platform — incidents, notification templates, channels, schedules, monitors, RUM, and platform administration. Every operation is authenticated with an `app_key` query parameter created in the Flashduty console under My → APP Key (or sent in the `Fd-App-Key` header). Responses follow a uniform envelope: `{ request_id, data }` on success, `{ request_id, error }` on failure.",
     "version": "1.0.0"
   },
   "servers": [
@@ -48,7 +48,7 @@
           "Platform/Teams"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Filter by `person_id` to return teams that a specific person belongs to.\n- Defaults: p=1, limit=20.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Filter by `person_id` to return only the teams that person belongs to; `query` matches a substring of the team name or description.\n- Deleted teams are never listed.",
           "href": "/en/api-reference/platform/teams/team-read-list",
           "metadata": {
             "sidebarTitle": "List teams"
@@ -79,23 +79,24 @@
                   "data": {
                     "p": 1,
                     "limit": 20,
-                    "total": 5,
+                    "total": 1,
                     "items": [
                       {
                         "account_id": 10023,
                         "team_id": 1001,
                         "team_name": "Backend SRE",
+                        "description": "Backend reliability engineering team",
                         "status": "enabled",
+                        "updated_by_name": "alice",
+                        "updated_by": 80011,
                         "creator_id": 80011,
+                        "creator_name": "",
                         "created_at": 1710000000,
                         "updated_at": 1712000000,
                         "person_ids": [
-                          80011
+                          80011,
+                          80012
                         ],
-                        "description": "",
-                        "updated_by_name": "",
-                        "updated_by": 0,
-                        "creator_name": "alice",
                         "ref_id": ""
                       }
                     ]
@@ -110,6 +111,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -144,7 +148,7 @@
           "Platform/Teams"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Duplicate IDs are deduplicated; IDs that match no team are ignored.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Duplicate IDs are deduplicated; IDs that match no team in the account are ignored.\n- Deleted teams are still returned (with an empty `person_ids`), so team IDs stored in older records still resolve to a name.\n- When no ID matches, `items` is `null`.",
           "href": "/en/api-reference/platform/teams/team-read-infos",
           "metadata": {
             "sidebarTitle": "Batch get teams"
@@ -201,6 +205,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -230,12 +237,12 @@
       "post": {
         "operationId": "role-write-disable",
         "summary": "Disable a role",
-        "description": "Disable a custom role to prevent it from granting permissions.",
+        "description": "Set a custom role's status to disabled without deleting it.",
         "tags": [
           "Platform/Roles & permissions"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Roles Manage** (`organization`) |\n\n## Usage\n\n- Members who held this role lose its permissions immediately.\n- Built-in roles always remain enabled; enabling or disabling them is a silent no-op.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Roles Manage** (`organization`) |\n\n## Usage\n\n- Only a role in `enabled` status can be disabled; calling it on a role that is already disabled returns `400 InvalidParameter`.\n- The built-in roles (`2`, `6`, `8`) cannot be disabled: the call succeeds but changes nothing.\n- A role ID that does not exist or was deleted is ignored and the call succeeds.\n- Disabling does not revoke the role from the members who hold it.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/platform/roles-permissions/role-write-disable",
           "metadata": {
             "sidebarTitle": "Disable a role"
@@ -303,12 +310,12 @@
       "post": {
         "operationId": "role-write-delete",
         "summary": "Delete a role",
-        "description": "Delete a custom role. While members still hold the role, the call fails with `ReferenceExist` unless `is_force` is true.",
+        "description": "Delete a custom role, optionally revoking it from every member who still holds it.",
         "tags": [
           "Platform/Roles & permissions"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Roles Manage** (`organization`) |\n\n## Usage\n\n- Built-in roles are synthetic and are never deleted; the call is a no-op for them.\n- While any member still holds the role, the default (`is_force=false`) call fails with error code `ReferenceExist` and the holders listed in `data.refs`. Set `is_force=true` to revoke the role from all holders and delete it in one call.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Roles Manage** (`organization`) |\n\n## Usage\n\n- While members still hold the role, the call fails with `400 ReferenceExist` and lists them in `data.refs` (`kind` `member`); set `is_force` to `true` to revoke the role from all of them and then delete it.\n- A role selected as a default role in the SSO configuration cannot be deleted, even with `is_force`; the call fails with `400 ReferenceExist` until it is unselected there.\n- A role ID that does not exist or was already deleted is ignored and the call succeeds.\n- Do not pass a built-in role ID (`2`, `6`, `8`): the built-in role itself is not deleted, but with `is_force: true` it is revoked from every member who holds it.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/platform/roles-permissions/role-write-delete",
           "metadata": {
             "sidebarTitle": "Delete a role"
@@ -381,7 +388,7 @@
           "Platform/Members"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Including the account ID returns the account owner, with `as` `account`. Other IDs are looked up among the account's members, including removed ones (`status` `deleted`), so IDs saved in older records still resolve.\n- Duplicate IDs are deduplicated; IDs that match neither are omitted.",
           "href": "/en/api-reference/platform/members/person-infos",
           "metadata": {
             "sidebarTitle": "Batch get persons"
@@ -446,6 +453,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -475,12 +485,12 @@
       "post": {
         "operationId": "memberInfo",
         "summary": "Get current member info",
-        "description": "Return the profile of the member the credential belongs to. Requires a member-scoped credential — calls authenticated as the account principal (e.g. an account-level app key) are rejected with a 400.",
+        "description": "Return the profile and account context of the member who owns the credential.",
         "tags": [
           "Platform/Members"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — but the credential must belong to a member; account-principal credentials (e.g. an account-level app key) are rejected with a 400 |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — but see the credential requirement under Usage |\n\n## Usage\n\n- Requires a member credential; calls made with the account owner's credentials return `400 BadRequest`. Use `POST /account/info` for the account owner.\n- `time_zone` is the member's own setting (empty string = follow the account), `account_time_zone` is the account's setting, and `resolved_time_zone` is the zone to render times in.",
           "href": "/en/api-reference/platform/members/member-info",
           "metadata": {
             "sidebarTitle": "Get current member info"
@@ -530,7 +540,8 @@
                     "member_name": "Alice",
                     "phone": "+86185****0300",
                     "phone_verified": true,
-                    "time_zone": "Asia/Shanghai"
+                    "time_zone": "Asia/Shanghai",
+                    "resolved_time_zone": "Asia/Shanghai"
                   }
                 }
               }
@@ -542,6 +553,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -566,12 +580,12 @@
       "post": {
         "operationId": "role-read-list-permission",
         "summary": "List permissions",
-        "description": "Return all available permissions, optionally filtered to those granted to specific roles.",
+        "description": "List permission entries and mark which of them the given roles grant.",
         "tags": [
           "Platform/Roles & permissions"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Pass `role_ids` to filter permissions to those granted to those roles.\n- Pass `with_all: true` to include all permissions regardless of role filter, with `is_granted` set to indicate which are granted to the specified roles.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- With `with_all: true`, every permission is returned and `is_granted` marks the ones granted by any role in `role_ids`.\n- With `with_all` false (the default), only the permissions granted by `role_ids` are returned — a call without `role_ids` returns an empty list.\n- `permission_name`, `description`, and `class` follow the request language (`Accept-Language` header, or the `locale`/`lang` query parameter).",
           "href": "/en/api-reference/platform/roles-permissions/role-read-list-permission",
           "metadata": {
             "sidebarTitle": "List permissions"
@@ -624,6 +638,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -658,7 +675,7 @@
           "Platform/Teams"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- At least one of `team_id`, `team_name`, or `ref_id` must be provided.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Provide one of `team_id`, `team_name`, or `ref_id`; when several are sent, `ref_id` wins over `team_name`, which wins over `team_id`.\n- Lookups by `team_name` or `ref_id` only match non-deleted teams; a lookup by `team_id` also returns a deleted team, with `status` `deleted`.\n- When no team matches, the call returns `400 InvalidParameter`.",
           "href": "/en/api-reference/platform/teams/team-read-info",
           "metadata": {
             "sidebarTitle": "Get team detail"
@@ -695,7 +712,7 @@
                     "updated_by_name": "alice",
                     "updated_by": 80011,
                     "creator_id": 80011,
-                    "creator_name": "alice",
+                    "creator_name": "",
                     "created_at": 1710000000,
                     "updated_at": 1712000000,
                     "person_ids": [
@@ -714,6 +731,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -740,12 +760,12 @@
       "post": {
         "operationId": "team-write-delete",
         "summary": "Delete a team",
-        "description": "Permanently delete a team by ID, name, or external reference ID.",
+        "description": "Delete a team by ID, name, or external reference ID and remove all of its members.",
         "tags": [
           "Platform/Teams"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Teams Manage** (`organization`) |\n\n## Usage\n\n- At least one of `team_id`, `team_name`, or `ref_id` must be provided.\n- Fails with `400 ReferenceExist` if the team is still referenced by schedules, escalation rules, or other resources.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Teams Manage** (`organization`) |\n\n## Usage\n\n- Provide one of `team_id`, `team_name`, or `ref_id`; when several are sent, `team_id` wins, then `team_name`, then `ref_id`.\n- Besides the permission above, the caller must be a member of the team, its creator, the account owner, or hold the Admin role; otherwise the call returns `403 AccessDenied`.\n- Fails with `400 ReferenceExist` while the team is still referenced by escalation rules, schedules, channels, notification templates, mapping schemas, service calendars, or the default teams of the SSO configuration; `data.refs` lists each reference (`kind`, `name`, `href`).\n- Deletion is soft: all members are removed from the team, the team disappears from lists and name/`ref_id` lookups, its name can be reused, and `POST /team/info` by `team_id` still returns it with `status` `deleted`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/platform/teams/team-write-delete",
           "metadata": {
             "sidebarTitle": "Delete a team"
@@ -818,7 +838,7 @@
           "Platform/Roles & permissions"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- IDs `2`, `6`, and `8` return the built-in Admin, Responder, and Viewer roles; their `description` follows the request language.\n- A role ID that does not exist or was deleted returns `400 InvalidParameter`.",
           "href": "/en/api-reference/platform/roles-permissions/role-read-info",
           "metadata": {
             "sidebarTitle": "Get role detail"
@@ -848,17 +868,18 @@
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "role_id": 2,
-                    "role_name": "Account Admin",
-                    "description": "Account admin with all permissions.",
+                    "role_name": "Admin",
+                    "description": "Account Administrator, has all account permissions and can assist the main account in managing all affairs.",
                     "status": "enabled",
                     "permission_ids": [
                       101,
                       102,
-                      201
+                      201,
+                      701
                     ],
                     "editable": false,
-                    "created_at": 1700000000,
-                    "updated_at": 1700000000
+                    "created_at": 1653530940,
+                    "updated_at": 1653530940
                   }
                 }
               }
@@ -870,6 +891,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -901,7 +925,7 @@
           "Platform/Members"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Members Manage** (`organization`) |\n\n## Usage\n\n- `country_code` must be an ISO 3166-1 alpha-2 region code (e.g. \"CN\"). It is validated and normalized to upper case before storage; invalid values are rejected with a 400.\n- When a member's `phone` has no \"+\" prefix, it is parsed with that member's `country_code` as the region hint (defaults to \"CN\" when omitted).",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Members Manage** (`organization`) |\n\n## Usage\n\n- Each entry needs `email`, or `member_name` together with `phone`.\n- Entries whose email or phone already belongs to a member of the account are skipped silently; `items` lists only the members created by this call and is `null` when none were created.\n- New members are created in `pending` status and are sent an invitation by email or SMS.\n- Emails are stored in lower case. If the account restricts member email domains, an address outside the allowlist returns `400`; duplicate emails or phones within one request also return `400`.\n- `country_code` must be an ISO 3166-1 alpha-2 region code (e.g. \"CN\"). It is validated and normalized to upper case before storage; invalid values are rejected with a 400.\n- When a member's `phone` has no \"+\" prefix, it is parsed with that member's `country_code` as the region hint (defaults to \"CN\" when omitted).\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/platform/members/member-invite",
           "metadata": {
             "sidebarTitle": "Invite members"
@@ -951,6 +975,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -999,7 +1026,7 @@
           "Platform/Roles & permissions"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Roles Manage** (`organization`) |\n\n## Usage\n\n- Built-in roles always remain enabled; enabling or disabling them is a silent no-op.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Roles Manage** (`organization`) |\n\n## Usage\n\n- Only a role in `disabled` status can be enabled; calling it on an enabled role — including the built-in roles — returns `400 InvalidParameter`.\n- A role ID that does not exist or was deleted is ignored and the call succeeds.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/platform/roles-permissions/role-write-enable",
           "metadata": {
             "sidebarTitle": "Enable a role"
@@ -1072,7 +1099,7 @@
           "Platform/Roles & permissions"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Built-in roles (`editable: false`) cannot be modified or deleted.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Custom roles (enabled and disabled) come first, sorted by `orderby`/`asc`; the three built-in roles — `2` Admin, `6` Responder, `8` Viewer — are appended at the end unless `no_global` is true, and are counted in `total`.\n- Built-in roles have `editable: false`, and their `description` follows the request language (`Accept-Language` header, or the `locale`/`lang` query parameter).",
           "href": "/en/api-reference/platform/roles-permissions/role-read-list",
           "metadata": {
             "sidebarTitle": "List roles"
@@ -1101,17 +1128,60 @@
                 "example": {
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
-                    "total": 3,
+                    "total": 4,
                     "items": [
+                      {
+                        "role_id": 150,
+                        "role_name": "On-call Manager",
+                        "description": "Manage on-call rotations and incidents.",
+                        "status": "enabled",
+                        "permission_ids": [
+                          501,
+                          502
+                        ],
+                        "editable": true,
+                        "created_at": 1710000000,
+                        "updated_at": 1712000000
+                      },
                       {
                         "role_id": 2,
-                        "role_name": "Account Admin",
-                        "description": "",
+                        "role_name": "Admin",
+                        "description": "Account Administrator, has all account permissions and can assist the main account in managing all affairs.",
                         "status": "enabled",
-                        "permission_ids": [],
+                        "permission_ids": [
+                          101,
+                          102,
+                          201,
+                          701
+                        ],
+                        "editable": false,
+                        "created_at": 1653530940,
+                        "updated_at": 1653530940
+                      },
+                      {
+                        "role_id": 6,
+                        "role_name": "Responder",
+                        "description": "Responder, has standard permissions except billing center, member management, role management and single sign-on management, suitable for members handling daily operations.",
+                        "status": "enabled",
+                        "permission_ids": [
+                          201,
+                          701
+                        ],
+                        "editable": false,
+                        "created_at": 1653530940,
+                        "updated_at": 1653530940
+                      },
+                      {
+                        "role_id": 8,
+                        "role_name": "Viewer",
+                        "description": "Viewer, has most read-only permissions except audit and onboarding, suitable for members who only need to view data.",
+                        "status": "enabled",
+                        "permission_ids": [
+                          103
+                        ],
                         "editable": false,
-                        "created_at": 1700000000,
-                        "updated_at": 1700000000
+                        "created_at": 1653530940,
+                        "updated_at": 1653530940
                       }
                     ]
                   }
@@ -1125,6 +1195,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -1157,7 +1230,7 @@
           "Platform/Members"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Identify the member with one of `member_id`, `member_name`, `email`, `phone`, or `ref_id`. If multiple identifiers are present, the server checks them in that order.\n- `updates.country_code` is an ISO 3166-1 alpha-2 region code (e.g. \"CN\", \"US\"). It is an independently updatable field: `updates.phone` is not required, and the new region is stored even when the phone is unchanged. An explicit empty string is rejected with a 400.\n- When `updates.phone` has no \"+\" prefix, it is parsed with `updates.country_code` as the region hint, falling back to the member's stored region and then to \"CN\". Legacy digit calling codes such as \"86\" remain accepted only as parsing hints — stored values are always ISO region codes.\n- The top-level `country_code` is only a parsing hint for the identifying `phone`; it is never stored.\n- Put the profile fields to write under `updates`: `member_name`, `password`, `phone`, `country_code`, `email`, `avatar`, `locale`, `time_zone`, or `ref_id`.\n- Members provisioned by SSO cannot be changed when SSO marks them as externally managed.\n- `updates` must carry at least one field; an object with every field omitted is rejected.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Identify the member with one of `member_id`, `member_name`, `email`, `phone`, or `ref_id`. If multiple identifiers are present, the server checks them in that order.\n- The caller must be the account owner, the member themself, or hold the Admin role; otherwise the call returns `403 AccessDenied`.\n- Put the fields to write under `updates`: `member_name`, `password`, `phone`, `country_code`, `email`, `avatar`, `locale`, `time_zone`, or `ref_id`. Omitted or `null` fields keep their current value; `updates` must carry at least one field.\n- A new `member_name`, `email`, or `phone` must not belong to another member of the account; a conflict returns `400`. A changed `email` or `phone` is marked unverified unless `from` is `api` and the account has member invitations disabled.\n- `updates.time_zone` set to an empty string clears the member's own time zone, so the member follows the account's.\n- `updates.country_code` is an ISO 3166-1 alpha-2 region code (e.g. \"CN\", \"US\"). It is an independently updatable field: `updates.phone` is not required, and the new region is stored even when the phone is unchanged. An explicit empty string is rejected with a 400.\n- When `updates.phone` has no \"+\" prefix, it is parsed with `updates.country_code` as the region hint, falling back to the member's stored region and then to \"CN\". Legacy digit calling codes such as \"86\" remain accepted only as parsing hints — stored values are always ISO region codes.\n- The top-level `country_code` is only a parsing hint for the identifying `phone`; it is never stored.\n- Fields are written one at a time; if a later field fails validation, the fields written before it in the same call stay saved.\n- Members provisioned through SSO cannot be changed while the SSO configuration marks them non-editable.\n- Concurrent profile updates or invitations in the same account can return `429 RequestTooFrequently`; retry after a moment.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/platform/members/member-reset-info",
           "metadata": {
             "sidebarTitle": "Reset member info"
@@ -1196,6 +1269,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -1232,7 +1308,7 @@
           "Platform/Audit logs"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Audit Read** (`organization`) |\n\n## Usage\n\n- Time range is required. Maximum span is 90 days. Both `start_time` and `end_time` are Unix epoch **seconds**.\n- Use `search_after_ctx` from the previous response to fetch the next page. The token is opaque — do not construct it manually.\n- The retention window depends on the account's license. Queries beyond the retention boundary silently return an empty result rather than an error.\n- `limit` accepts 0–99; omitting it (or 0) returns all matching rows in the window with no page-size cap. Rows are returned newest first.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Audit Read** (`organization`) |\n\n## Usage\n\n- Time range is required. Maximum span is 90 days. Both `start_time` and `end_time` are Unix epoch **seconds**.\n- Use `search_after_ctx` from the previous response to fetch the next page. The token is opaque — do not construct it manually.\n- The retention window depends on the account's license. Queries beyond the retention boundary silently return an empty result rather than an error.\n- Pass an explicit `limit` (1–99) for predictable paging; when it is omitted or 0 the server chooses the page size, which may be the whole result set. Entries are returned newest first.",
           "href": "/en/api-reference/platform/audit-logs/audit-read-search",
           "metadata": {
             "sidebarTitle": "Search audit logs"
@@ -1293,6 +1369,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -1330,7 +1409,7 @@
           "Platform/Roles & permissions"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Roles Manage** (`organization`) |\n\n## Usage\n\n- Members who already have the role are silently skipped.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Roles Manage** (`organization`) |\n\n## Usage\n\n- Every ID in `member_ids` must be a member of the account, with no duplicates; otherwise the call returns `400` and nobody is changed.\n- `role_id` must be a built-in role or a custom role that has not been deleted (disabled roles are accepted); otherwise the call returns `400`.\n- Members provisioned through SSO cannot be changed while the SSO configuration marks them non-editable; the call returns `400`.\n- Members who already hold the role keep it unchanged.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/platform/roles-permissions/role-write-grant-role",
           "metadata": {
             "sidebarTitle": "Grant role to members"
@@ -1402,12 +1481,12 @@
       "post": {
         "operationId": "memberUpdateRole",
         "summary": "Update member roles",
-        "description": "Replace all role assignments for a member at once. Role IDs that do not exist are silently dropped; an empty `role_ids` resets the member to the built-in Viewer role (ID 8).",
+        "description": "Replace a member's role assignments with the given set of roles.",
         "tags": [
           "Platform/Members"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Members Manage** (`organization`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Members Manage** (`organization`) |\n\n## Usage\n\n- An empty or omitted `role_ids` assigns the built-in Viewer role (`8`).\n- Role IDs that do not exist are dropped; if none of the given IDs exist, the member ends up with no roles.\n- Members provisioned through SSO cannot be changed while the SSO configuration marks them non-editable; the call returns `400`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/platform/members/member-update-role",
           "metadata": {
             "sidebarTitle": "Update member roles"
@@ -1446,6 +1525,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -1481,7 +1563,7 @@
           "Platform/Roles & permissions"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Roles Manage** (`organization`) |\n\n## Usage\n\n- Omit `role_id` (or set to 0) to create; pass an existing ID to update.\n- `role_name` must be 1–39 characters and unique within the account.\n- `permission_ids` sets the full permission set for the role, replacing any previous assignment.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Roles Manage** (`organization`) |\n\n## Usage\n\n- Omit `role_id` (or set it to 0) to create a role; pass the ID of a custom role to update it.\n- `role_name` must be unique in the account, including the built-in names `Admin`, `Responder`, and `Viewer`; a conflict returns `400`.\n- An update overwrites `role_name`, `description`, and `permission_ids` together: omitting `description` clears it, and omitting `permission_ids` removes every permission from the role.\n- Updating a disabled role re-enables it.\n- Every ID in `permission_ids` must be a permission returned by `POST /role/permission/list` (with `with_all: true`); otherwise the call returns `400` and nothing changes.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/platform/roles-permissions/role-write-upsert",
           "metadata": {
             "sidebarTitle": "Create or update a role"
@@ -1557,12 +1639,12 @@
       "post": {
         "operationId": "role-read-list-permission-factor",
         "summary": "List permission factors",
-        "description": "Return all permission factors (API, button, menu, URL, visit) granted to the calling member, optionally filtered by type. Requires a member-scoped credential — calls authenticated as the account principal (e.g. an account-level app key) are rejected with a 400, because the account principal implicitly holds every permission.",
+        "description": "List the permission factors granted to the calling member through their roles.",
         "tags": [
           "Platform/Roles & permissions"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — but the credential must belong to a member; account-principal credentials (e.g. an account-level app key) are rejected with a 400 |\n\n## Usage\n\n- Permission factors are the fine-grained controls that make up each permission.\n- `factor_types` accepts: `api`, `button`, `visit`, `menu`, `url`.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — but see the credential requirement under Usage |\n\n## Usage\n\n- Requires a member credential: calls made with the account owner's credentials return `400 InvalidParameter`, because the account owner implicitly holds every permission.\n- Factors come from all roles the calling member holds and are deduplicated; the order is not stable. A member with no roles gets an empty array.\n- `factor_types` filters by type (`api`, `button`, `visit`, `menu`, `url`); omit it to return all types. An unsupported type returns `400`.",
           "href": "/en/api-reference/platform/roles-permissions/role-read-list-permission-factor",
           "metadata": {
             "sidebarTitle": "List permission factors"
@@ -1607,6 +1689,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -1640,7 +1725,7 @@
           "Platform/Roles & permissions"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Roles Manage** (`organization`) |\n\n## Usage\n\n- Members who don't have the role are silently skipped.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Roles Manage** (`organization`) |\n\n## Usage\n\n- Every ID in `member_ids` must be a member of the account, with no duplicates; otherwise the call returns `400` and nobody is changed.\n- `role_id` must be a built-in role or a custom role that has not been deleted (disabled roles are accepted); otherwise the call returns `400`.\n- Members provisioned through SSO cannot be changed while the SSO configuration marks them non-editable; the call returns `400`.\n- Members who don't hold the role are left unchanged; revoking a member's last role leaves them with no roles.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/platform/roles-permissions/role-write-revoke-role",
           "metadata": {
             "sidebarTitle": "Revoke role from members"
@@ -1716,7 +1801,7 @@
           "Platform/Audit logs"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Audit Read** (`organization`) |\n\n## Usage\n\n- Use the `name` values from this response as `operations` filter values in `POST /audit/search`.\n- `name_cn` is the human-readable Chinese label shown in the console; `name` is the stable wire value to filter on.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Audit Read** (`organization`) |\n\n## Usage\n\n- Use the `name` values from this response as `operations` filter values in `POST /audit/search`.\n- `name_cn` is the Chinese label shown in the console, returned in Chinese regardless of the request language; `name` is the stable value to filter on.",
           "href": "/en/api-reference/platform/audit-logs/audit-read-operation-list",
           "metadata": {
             "sidebarTitle": "List auditable operation types"
@@ -1770,6 +1855,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -1799,7 +1887,7 @@
           "Platform/Teams"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Teams Manage** (`organization`) |\n\n## Usage\n\n- Omit `team_id` (or set to 0) to create a new team; pass an existing ID to update.\n- `team_name` must be 1–39 characters and unique within the account.\n- Pass `person_ids` to set team membership; this replaces the entire member list.\n- Pass `emails` or `phones` to add existing members by contact; contacts that match no member are ignored — nobody is invited.\n- `ref_id` is an external identifier for integration with third-party HR systems.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Teams Manage** (`organization`) |\n\n## Usage\n\n- Omit `team_id` (or set it to 0) to create a team; pass an existing `team_id` to update it. A `team_id` that matches no team returns `400`.\n- `team_name` must be unique among the account's teams. A name used by another team returns `400`, except when `team_id` is 0 and `reset_if_name_exist` is true — then that team is updated.\n- Membership is always replaced: the team's members become exactly the union of `person_ids`, `emails`, and `phones`. Omitting all three on an update removes every member.\n- Entries that do not resolve to a member of the account (or the account owner) are silently dropped; nobody is invited.\n- On update, `description` and `ref_id` are overwritten as well — omitting them clears the stored values.\n- Updating also requires the caller to be a team member, the team creator, the account owner, or hold the Admin role.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/platform/teams/team-write-upsert",
           "metadata": {
             "sidebarTitle": "Create or update a team"
@@ -1875,12 +1963,12 @@
       "post": {
         "operationId": "memberGrantRole",
         "summary": "Grant role to member",
-        "description": "Add role assignments to a member. Role IDs that do not exist are silently ignored; if none resolve, the call is a no-op success.",
+        "description": "Add one or more roles to a member's existing role assignments.",
         "tags": [
           "Platform/Members"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Members Manage** (`organization`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Members Manage** (`organization`) |\n\n## Usage\n\n- Role IDs that do not exist are ignored; if none of them exist, the call succeeds without changes.\n- Roles the member already holds are kept once; no duplicates are added.\n- Members provisioned through SSO cannot be changed while the SSO configuration marks them non-editable; the call returns `400`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/platform/members/member-grant-role",
           "metadata": {
             "sidebarTitle": "Grant role to member"
@@ -1919,6 +2007,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -1948,12 +2039,12 @@
       "post": {
         "operationId": "memberRevokeRole",
         "summary": "Revoke role from member",
-        "description": "Remove role assignments from a member. Role IDs that do not exist are silently ignored; if none resolve, the call is a no-op success.",
+        "description": "Remove one or more roles from a member's role assignments.",
         "tags": [
           "Platform/Members"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Members Manage** (`organization`) |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Members Manage** (`organization`) |\n\n## Usage\n\n- Role IDs that do not exist are ignored; if none of them exist, the call succeeds without changes.\n- Revoking every role leaves the member with no roles; it does not fall back to Viewer.\n- Members provisioned through SSO cannot be changed while the SSO configuration marks them non-editable; the call returns `400`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/platform/members/member-revoke-role",
           "metadata": {
             "sidebarTitle": "Revoke role from member"
@@ -1992,6 +2083,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -2026,7 +2120,7 @@
           "Platform/Members"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Members Manage** (`organization`) |\n\n## Usage\n\n- By default (`is_force=false`), the system checks whether the member is referenced by other resources (e.g., escalation rules, schedules). If references exist, the API returns error code `ReferenceExist` with the reference list in `data.refs`. Set `is_force=true` to skip the reference check and force delete.\n- Members provisioned via SSO with `sso_user_non_editable=true` cannot be deleted through this API. Disable that SSO restriction first.\n- This operation is recorded in the audit log.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Members Manage** (`organization`) |\n\n## Usage\n\n- Identify the member with one of the lookup fields; when several are sent, the first non-empty one wins in the order `member_id`, `member_name`, `email`, `phone`, `ref_id`.\n- Unless `is_force` is true, the call fails with `400 ReferenceExist` while the member belongs to a team, is a direct target of an escalation rule, or is in a schedule; `data.refs` lists each reference. A forced delete skips this check and leaves those references in place.\n- Deletion is soft: the member's status becomes `deleted`, any license seat the member holds is released, and the member's SSO identity links are removed. The member still resolves through `POST /person/infos`.\n- Members provisioned through SSO cannot be deleted while the SSO configuration marks them non-editable; the call returns `400`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/platform/members/member-delete",
           "metadata": {
             "sidebarTitle": "Delete member"
@@ -2065,6 +2159,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -2096,7 +2193,7 @@
           "Platform/Members"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Returns members in `enabled` or `pending` status. Removed members and the account owner are not listed; resolve their IDs with `POST /person/infos`.\n- `role_id` returns the members holding that role; `member_id` returns at most that one member.",
           "href": "/en/api-reference/platform/members/member-list",
           "metadata": {
             "sidebarTitle": "List members"
@@ -2180,6 +2277,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -2258,7 +2358,7 @@
                     "phone": "138****8000",
                     "country_code": "CN",
                     "email": "ops@acme.example",
-                    "avatar": "https://cdn.flashcat.cloud/avatar/acme.png",
+                    "avatar": "https://example.com/avatar/acme.png",
                     "locale": "zh-CN",
                     "time_zone": "Asia/Shanghai",
                     "created_at": 1716960000,
@@ -2282,6 +2382,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -2293,7 +2396,7 @@
           "metadata": {
             "sidebarTitle": "Get account detail"
           },
-          "content": "| Permission | Description |\n| --- | --- |\n| None | None — any valid app_key can call this operation. |\n\nFind this operation in the [Platform API reference](/en/api-reference/platform/account/account-read-info).",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — but see the credential requirement under Usage |\n\n## Usage\n\n- Requires the account owner's credentials (for example an app key created by the account owner); member credentials return `401 Unauthorized`. Members can use `POST /member/info` instead.\n- `restrictions` is present only when join or access restrictions have been configured; `mp_plat` and `mp_account_id` only for accounts provisioned through a cloud marketplace.",
           "href": "/en/api-reference/platform/account/account-read-info"
         }
       }
@@ -2302,12 +2405,12 @@
       "post": {
         "operationId": "memberNotify",
         "summary": "Notify members",
-        "description": "Send an email to account members on behalf of the caller, with content the caller supplies. Only callable with a credential minted for an AI SRE session; any other credential is rejected with `AccessDenied`. Delivery is asynchronous — `accepted` means the email was queued, not that it was delivered.",
+        "description": "Email account members a message written by the calling AI SRE session.",
         "tags": [
           "Platform/Members"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **200 requests/minute**; **10 requests/second** per account |\n| Permissions | None — callable only with an AI SRE session credential; any other credential is rejected with `AccessDenied` |\n\n## Usage\n\n- Recipients that are not active members of the caller's account, or that have no email address on file, are skipped rather than failing the whole request.\n- Whether email is included follows each recipient's own notification preferences for this kind of message; a recipient with no preference set defaults to receiving it.\n- Recipients receive exactly the sanitized `html` as the email body, with nothing added around it. The sender name shows the caller's name followed by \"(via AI SRE)\".\n- Before sending, the server inspects the submitted `html` and rejects the request with `400` / `InvalidParameter` when it contains constructs whose removal would change what recipients see (`<style>`, `<svg>`, `<iframe>`, `<object>`, `<embed>`, `<form>`, `<input>`, `<button>`, an `<img>` with a missing or non-`https` `src`, or an `<a>` whose href scheme is not `http`, `https`, or `mailto`); the error message names each construct and what to change, and nothing is queued — neither the hourly limit nor the per-turn duplicate check is consumed. Tags whose removal does not change rendering (`<script>`, `<meta>`, `<link>`, `<base>`, `on*` handlers) are still sanitized silently and never trigger a rejection.\n- At most 20 emails are delivered to the same recipient through this endpoint per hour; further deliveries to that recipient in the same window are skipped with `rate_limited`.\n- Retrying the same call within the same AI SRE session turn does not send a duplicate email to a recipient who already received one; the repeat is skipped with `duplicate`.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **200 requests/minute**; **10 requests/second** per account |\n| Permissions | None — but see the credential requirement under Usage |\n\n## Usage\n\n- Only callable with a credential minted for an AI SRE session; any other credential is rejected with `AccessDenied`.\n- Delivery is asynchronous — `accepted` means the email was queued, not that it was delivered.\n- Recipients that are not active members of the caller's account, or that have no email address on file, are skipped rather than failing the whole request.\n- Whether email is included follows each recipient's own notification preferences for this kind of message; a recipient with no preference set defaults to receiving it.\n- Recipients receive exactly the sanitized `html` as the email body, with nothing added around it. The sender name shows the caller's name followed by \"(via AI SRE)\".\n- Before sending, the server inspects the submitted `html` and rejects the request with `400` / `InvalidParameter` when it contains constructs whose removal would change what recipients see (`<style>`, `<svg>`, `<iframe>`, `<object>`, `<embed>`, `<form>`, `<input>`, `<button>`, an `<img>` with a missing or non-`https` `src`, or an `<a>` whose href scheme is not `http`, `https`, or `mailto`); the error message names each construct and what to change, and nothing is queued — neither the hourly limit nor the per-turn duplicate check is consumed. Tags whose removal does not change rendering (`<script>`, `<meta>`, `<link>`, `<base>`, `on*` handlers) are still sanitized silently and never trigger a rejection.\n- At most 20 emails are delivered to the same recipient through this endpoint per hour; further deliveries to that recipient in the same window are skipped with `rate_limited`.\n- Retrying the same call within the same AI SRE session turn does not send a duplicate email to a recipient who already received one; the repeat is skipped with `duplicate`.",
           "href": "/en/api-reference/platform/members/member-notify",
           "metadata": {
             "sidebarTitle": "Notify members"
@@ -2409,7 +2512,7 @@
         "type": "apiKey",
         "in": "query",
         "name": "app_key",
-        "description": "App key issued from the Flashduty console under Account → APP Keys. Required on every public API call. Keep it secret — it grants the same access as the owning account."
+        "description": "APP Key created in the Flashduty console under My → APP Key. Send it as the `app_key` query parameter or in the `Fd-App-Key` request header. Its effective access is the intersection of the key's permission scope and the creator's current role permissions. Keep it secret."
       }
     },
     "responses": {
@@ -2456,7 +2559,7 @@
         }
       },
       "Forbidden": {
-        "description": "The app_key is valid but lacks permission for this operation.",
+        "description": "The app_key is valid, but its permission scope or the creator's role does not allow this operation or object.",
         "content": {
           "application/json": {
             "schema": {
@@ -2498,7 +2601,7 @@
         }
       },
       "TooManyRequests": {
-        "description": "Rate limit hit. Either the global API limit, a per-account limit, or a per-integration limit.",
+        "description": "Rate limit hit (per-account limit or the operation's platform-wide limit). Wait for the number of seconds in `Flashcat-Request-Rate-Limit-Delay`, then retry.",
         "content": {
           "application/json": {
             "schema": {
@@ -2516,6 +2619,15 @@
               }
             }
           }
+        },
+        "headers": {
+          "Flashcat-Request-Rate-Limit-Delay": {
+            "description": "Seconds until the current rate-limit window resets. Absent when the request was rejected by the gateway's global protection limit.",
+            "schema": {
+              "type": "integer",
+              "minimum": 0
+            }
+          }
         }
       },
       "ServerError": {
@@ -2570,7 +2682,7 @@
           "account_id": {
             "type": "integer",
             "format": "uint64",
-            "description": "ID of the account."
+            "description": "ID of the account the entry belongs to."
           },
           "member_id": {
             "type": "integer",
@@ -2602,7 +2714,10 @@
             "description": "JSON-encoded request body. Bodies containing sensitive fields are base64url-encoded instead; bodies over 10 KB are replaced by a truncation placeholder."
           },
           "params": {
-            "type": "array",
+            "type": [
+              "array",
+              "string"
+            ],
             "items": {
               "type": "object",
               "properties": {
@@ -2616,7 +2731,7 @@
                 }
               }
             },
-            "description": "URL path parameters as an array of key-value pairs, or an empty array when none."
+            "description": "URL path parameters as an array of `Key`/`Value` pairs (an empty array when none). Some deployments return the same array as a JSON-encoded string."
           },
           "is_dangerous": {
             "type": "boolean",
@@ -2632,7 +2747,7 @@
               "member",
               "service"
             ],
-            "description": "Kind of the caller. `member` — an interactive member session; `service` — an app key credential."
+            "description": "Kind of the caller. `member` — a member or account-owner session; `service` — an app key or a short-lived key issued to AI SRE."
           },
           "credential_type": {
             "type": "string",
@@ -2710,7 +2825,7 @@
           },
           "limit": {
             "type": "integer",
-            "description": "Page size, 0–99. Omit or set to 0 for no page-size cap — all matching rows in the window are returned.",
+            "description": "Page size, 0–99. Omit or set to 0 to let the server choose the page size (it may return every matching entry).",
             "minimum": 0,
             "maximum": 99,
             "example": 20
@@ -2787,7 +2902,7 @@
           },
           "message": {
             "type": "string",
-            "description": "Human-readable error message, localized by the caller's Accept-Language. May contain field names, IDs, or other context from the failing request.",
+            "description": "Human-readable error message in the response language (`locale` / `lang` query parameter or `Accept-Language` header). May name the offending field; do not parse it.",
             "example": "The specified parameter template_id is not valid."
           }
         },
@@ -2798,7 +2913,7 @@
       },
       "ErrorCode": {
         "type": "string",
-        "description": "Flashduty error code enum. Every failed API response sets `error.code` to one of these stable wire strings. HTTP status is informational — the authoritative signal is the enum value.\n\n| Code | HTTP | Meaning |\n|---|---|---|\n| `OK` | 200 | Reserved — not returned on real errors. |\n| `InvalidParameter` | 400 | A required parameter is missing or failed validation. |\n| `BadRequest` | 400 | Generic 400 used when no more specific code fits. |\n| `InvalidContentType` | 400 | The `Content-Type` header is not `application/json`. |\n| `ResourceNotFound` | 400 | The referenced resource does not exist. Note: returned as HTTP 400, not 404 (historical choice). |\n| `NoLicense` | 400 | The feature is license-gated and no active license was found. |\n| `ReferenceExist` | 400 | Deletion blocked — other entities still reference this resource. |\n| `Unauthorized` | 401 | `app_key` is missing, invalid, or expired. |\n| `BalanceNotEnough` | 402 | Billing-gated operation with insufficient account balance. |\n| `AccessDenied` | 403 | Authenticated but lacking the permission required for this operation. |\n| `RouteNotFound` | 404 | The request URL path is not a known route. |\n| `MethodNotAllowed` | 405 | The HTTP method is not allowed on this otherwise-known path. |\n| `UndonedOrderExist` | 409 | An outstanding billing order blocks this new one. Wait and retry. |\n| `RequestLocked` | 423 | Operation temporarily locked due to repeated failures. |\n| `EntityTooLarge` | 413 | Request body exceeds the configured max size. |\n| `RequestTooFrequently` | 429 | Rate limit hit — API-global, per-account, or per-integration. |\n| `RequestVerifyRequired` | 428 | Second-factor verification required but not supplied. |\n| `DangerousOperation` | 428 | High-risk operation requires MFA verification. |\n| `InternalError` | 500 | Unhandled server-side error. Include `request_id` in the bug report. |\n| `ServiceUnavailable` | 503 | A backend dependency is unavailable. Try again later. |",
+        "description": "Error code. Every failed response sets `error.code` to one of these stable strings; branch on it rather than on the HTTP status.\n\n| Code | HTTP | Meaning |\n|---|---|---|\n| `OK` | 200 | Reserved; never returned on a failed request. |\n| `InvalidParameter` | 400 | A parameter is missing, has the wrong type, or failed validation; `message` usually names the field. |\n| `BadRequest` | 400 | The request breaks a business rule or conflicts with the current state of an object; `message` says which. |\n| `InvalidContentType` | 400 | The body is not sent as `application/json`. |\n| `ResourceNotFound` | 400 | The referenced object does not exist in this account or was deleted. Returned as HTTP 400, not 404. |\n| `NoLicense` | 400 | The account's plan does not include the feature, a plan quota is used up, the plan has expired, or credits are insufficient. |\n| `ReferenceExist` | 400 | The object is still referenced by other objects, so it cannot be deleted. |\n| `Unauthorized` | 401 | The APP Key is missing, invalid, or deleted. |\n| `BalanceNotEnough` | 402 | Console-only (billing); not returned by Open API operations. |\n| `AccessDenied` | 403 | The APP Key's permission scope or the creator's role does not allow this operation or object. |\n| `RouteNotFound` | 404 | No operation matches the HTTP method and path. |\n| `MethodNotAllowed` | 405 | The path exists but not for this HTTP method. |\n| `UndonedOrderExist` | 409 | Console-only (billing); not returned by Open API operations. |\n| `EntityTooLarge` | 413 | The request body exceeds the size limit. |\n| `RequestLocked` | 423 | Console-only (sign-in protection); not returned by Open API operations. |\n| `RequestVerifyRequired` | 428 | Console-only (verification code); not returned by Open API operations. |\n| `DangerousOperation` | 428 | Console-only (MFA for high-risk actions); not returned by Open API operations. |\n| `RequestTooFrequently` | 429 | A rate limit was hit; wait for the `Flashcat-Request-Rate-Limit-Delay` response header (seconds) before retrying. |\n| `InternalError` | 500 | Unexpected server error; retry with backoff and include `request_id` when reporting. |\n| `ServiceUnavailable` | 503 | A backend dependency is overloaded or unavailable; retry with backoff. |",
         "enum": [
           "OK",
           "InvalidParameter",
@@ -2813,35 +2928,35 @@
           "RouteNotFound",
           "MethodNotAllowed",
           "UndonedOrderExist",
-          "RequestLocked",
           "EntityTooLarge",
-          "RequestTooFrequently",
+          "RequestLocked",
           "RequestVerifyRequired",
           "DangerousOperation",
+          "RequestTooFrequently",
           "InternalError",
           "ServiceUnavailable"
         ],
         "x-enumDescriptions": {
-          "OK": "Reserved — not returned on real errors.",
-          "InvalidParameter": "A required parameter is missing or failed validation.",
-          "BadRequest": "Generic 400 used when no more specific code fits.",
-          "InvalidContentType": "The `Content-Type` header is not `application/json`.",
-          "ResourceNotFound": "The referenced resource does not exist. Note: returned as HTTP 400, not 404 (historical choice).",
-          "NoLicense": "The feature is license-gated and no active license was found.",
-          "ReferenceExist": "Deletion blocked — other entities still reference this resource.",
-          "Unauthorized": "`app_key` is missing, invalid, or expired.",
-          "BalanceNotEnough": "Billing-gated operation with insufficient account balance.",
-          "AccessDenied": "Authenticated but lacking the permission required for this operation.",
-          "RouteNotFound": "The request URL path is not a known route.",
-          "MethodNotAllowed": "The HTTP method is not allowed on this otherwise-known path.",
-          "UndonedOrderExist": "An outstanding billing order blocks this new one. Wait and retry.",
-          "RequestLocked": "Operation temporarily locked due to repeated failures.",
-          "EntityTooLarge": "Request body exceeds the configured max size.",
-          "RequestTooFrequently": "Rate limit hit — API-global, per-account, or per-integration.",
-          "RequestVerifyRequired": "Second-factor verification required but not supplied.",
-          "DangerousOperation": "High-risk operation requires MFA verification.",
-          "InternalError": "Unhandled server-side error. Include `request_id` in the bug report.",
-          "ServiceUnavailable": "A backend dependency is unavailable. Try again later."
+          "OK": "Reserved; never returned on a failed request.",
+          "InvalidParameter": "A parameter is missing, has the wrong type, or failed validation; `message` usually names the field.",
+          "BadRequest": "The request breaks a business rule or conflicts with the current state of an object; `message` says which.",
+          "InvalidContentType": "The body is not sent as `application/json`.",
+          "ResourceNotFound": "The referenced object does not exist in this account or was deleted. Returned as HTTP 400, not 404.",
+          "NoLicense": "The account's plan does not include the feature, a plan quota is used up, the plan has expired, or credits are insufficient.",
+          "ReferenceExist": "The object is still referenced by other objects, so it cannot be deleted.",
+          "Unauthorized": "The APP Key is missing, invalid, or deleted.",
+          "BalanceNotEnough": "Console-only (billing); not returned by Open API operations.",
+          "AccessDenied": "The APP Key's permission scope or the creator's role does not allow this operation or object.",
+          "RouteNotFound": "No operation matches the HTTP method and path.",
+          "MethodNotAllowed": "The path exists but not for this HTTP method.",
+          "UndonedOrderExist": "Console-only (billing); not returned by Open API operations.",
+          "EntityTooLarge": "The request body exceeds the size limit.",
+          "RequestLocked": "Console-only (sign-in protection); not returned by Open API operations.",
+          "RequestVerifyRequired": "Console-only (verification code); not returned by Open API operations.",
+          "DangerousOperation": "Console-only (MFA for high-risk actions); not returned by Open API operations.",
+          "RequestTooFrequently": "A rate limit was hit; wait for the `Flashcat-Request-Rate-Limit-Delay` response header (seconds) before retrying.",
+          "InternalError": "Unexpected server error; retry with backoff and include `request_id` when reporting.",
+          "ServiceUnavailable": "A backend dependency is overloaded or unavailable; retry with backoff."
         },
         "example": "InvalidParameter"
       },
@@ -2875,7 +2990,7 @@
           },
           "email": {
             "type": "string",
-            "description": "Email address. Required when `phone` is not provided."
+            "description": "Email address, stored in lower case. Required when `phone` is not provided."
           },
           "phone": {
             "type": "string",
@@ -2891,7 +3006,7 @@
               "type": "integer",
               "format": "uint64"
             },
-            "description": "Role IDs to assign"
+            "description": "Role IDs to assign: built-in `2` (Admin), `6` (Responder), `8` (Viewer), or custom role IDs from `POST /role/list`. Defaults to Viewer (`8`) when omitted; an ID that does not exist returns `400`."
           },
           "locale": {
             "type": "string",
@@ -2899,15 +3014,15 @@
               "zh-CN",
               "en-US"
             ],
-            "description": "Locale. One of: `zh-CN` (Simplified Chinese), `en-US` (English); other values are rejected with a 400."
+            "description": "Locale: `zh-CN` (Simplified Chinese) or `en-US` (English); other values are rejected with a 400. Defaults to the account's locale when omitted."
           },
           "time_zone": {
             "type": "string",
-            "description": "Time zone"
+            "description": "IANA time zone name such as `Asia/Shanghai`. Omit it to have the member follow the account's time zone; an invalid name returns `400`."
           },
           "ref_id": {
             "type": "string",
-            "description": "External reference ID"
+            "description": "External reference ID (for example an employee ID in an HR system), usable later as a lookup key in `POST /member/delete` and `POST /member/info/reset`."
           }
         }
       },
@@ -2942,7 +3057,7 @@
           },
           "is_force": {
             "type": "boolean",
-            "description": "Force delete. Defaults to false, which checks for references from escalation rules, schedules, etc. Set to true to skip the reference check and delete immediately",
+            "description": "Skip the reference check. When false (default), the call fails with `ReferenceExist` if the member belongs to a team, is targeted by an escalation rule, or is in a schedule. A forced delete does not remove those references.",
             "default": false
           }
         },
@@ -2991,11 +3106,11 @@
           "account_id": {
             "type": "integer",
             "format": "uint64",
-            "description": "Account ID"
+            "description": "ID of the account the member belongs to."
           },
           "account_name": {
             "type": "string",
-            "description": "Account name"
+            "description": "Name of the account (organization)."
           },
           "account_avatar": {
             "type": "string",
@@ -3003,7 +3118,7 @@
           },
           "account_email": {
             "type": "string",
-            "description": "Account email"
+            "description": "Contact email of the account owner."
           },
           "account_role_ids": {
             "type": "array",
@@ -3011,7 +3126,7 @@
               "type": "integer",
               "format": "uint64"
             },
-            "description": "Assigned role IDs"
+            "description": "IDs of the roles assigned to the member; resolve them with `POST /role/list`."
           },
           "account_locale": {
             "type": "string",
@@ -3019,16 +3134,20 @@
           },
           "account_time_zone": {
             "type": "string",
-            "description": "Account-level time zone (e.g. Asia/Shanghai). Omitted when the account has none set."
+            "description": "The account's IANA time zone setting; empty string when the account has none. Always present."
+          },
+          "resolved_time_zone": {
+            "type": "string",
+            "description": "Effective time zone to render times in: the member's `time_zone` if valid, otherwise the account's, otherwise `Asia/Shanghai`. Always present."
           },
           "domain": {
             "type": "string",
-            "description": "Account domain"
+            "description": "Account domain, the subdomain used to sign in to the console."
           },
           "member_id": {
             "type": "integer",
             "format": "uint64",
-            "description": "Member ID"
+            "description": "ID of the calling member."
           },
           "member_name": {
             "type": "string",
@@ -3064,7 +3183,7 @@
           },
           "time_zone": {
             "type": "string",
-            "description": "Member's IANA time zone. Omitted when the member has none set."
+            "description": "The member's own IANA time zone setting; empty string when the member follows the account's time zone. Always present."
           },
           "is_external": {
             "type": "boolean",
@@ -3077,7 +3196,10 @@
           },
           "mp_plat": {
             "type": "string",
-            "description": "Cloud marketplace platform the account was provisioned from. Omitted when the account did not come from a marketplace."
+            "description": "Cloud marketplace the account was provisioned from: `aws` — AWS Marketplace. Omitted when the account did not come from a marketplace.",
+            "enum": [
+              "aws"
+            ]
           },
           "mp_account_id": {
             "type": "string",
@@ -3100,7 +3222,10 @@
           "country_code",
           "avatar",
           "is_external",
-          "created_at"
+          "created_at",
+          "time_zone",
+          "account_time_zone",
+          "resolved_time_zone"
         ]
       },
       "MemberInviteRequest": {
@@ -3129,11 +3254,14 @@
         "description": "Invite members response",
         "properties": {
           "items": {
-            "type": "array",
+            "type": [
+              "array",
+              "null"
+            ],
             "items": {
               "$ref": "#/components/schemas/NewMemberItem"
             },
-            "description": "Newly created members"
+            "description": "Members created by this call; entries skipped because they already exist are not listed. `null` when no member was created."
           }
         }
       },
@@ -3161,16 +3289,16 @@
           "account_id": {
             "type": "integer",
             "format": "uint64",
-            "description": "Account ID"
+            "description": "ID of the account the member belongs to."
           },
           "member_id": {
             "type": "integer",
             "format": "uint64",
-            "description": "Member ID"
+            "description": "Member ID; the same value is used as the person ID in other APIs (for example `person_ids`)."
           },
           "member_name": {
             "type": "string",
-            "description": "Display name"
+            "description": "Display name, unique in the account."
           },
           "country_code": {
             "type": "string",
@@ -3178,40 +3306,39 @@
           },
           "phone": {
             "type": "string",
-            "description": "Masked phone number"
+            "description": "Phone number in E.164 form with the middle digits masked (for example `+86151****6519`); empty string when unset."
           },
           "email": {
             "type": "string",
-            "description": "Email address"
+            "description": "Email address in lower case; empty string when unset."
           },
           "locale": {
             "type": "string",
-            "description": "Member's locale preference (e.g. `zh-CN`). Omitted when empty — the list endpoint does not populate it."
+            "description": "Locale preference. Not populated by `POST /member/list`, so it is always omitted there."
           },
           "time_zone": {
             "type": "string",
-            "description": "Member's IANA time zone (e.g. `Asia/Shanghai`). Omitted when empty — the list endpoint does not populate it."
+            "description": "The member's own IANA time zone setting (for example `Asia/Shanghai`). Omitted when unset, which means the member follows the account's time zone; `POST /member/info` returns the effective zone."
           },
           "phone_verified": {
             "type": "boolean",
-            "description": "Phone verified"
+            "description": "`true` once the member has verified the phone number."
           },
           "email_verified": {
             "type": "boolean",
-            "description": "Email verified"
+            "description": "`true` once the member has verified the email address."
           },
           "avatar": {
             "type": "string",
-            "description": "Avatar URL"
+            "description": "Avatar image URL or path; empty string when unset."
           },
           "status": {
             "type": "string",
             "enum": [
               "enabled",
-              "pending",
-              "deleted"
+              "pending"
             ],
-            "description": "Member status. `enabled` — active member; `pending` — invited but not yet accepted; `deleted` — removed from the organization."
+            "description": "Member status. `enabled` — active member; `pending` — invited but has not accepted yet. Removed members are not listed."
           },
           "account_role_ids": {
             "type": "array",
@@ -3219,15 +3346,15 @@
               "type": "integer",
               "format": "uint64"
             },
-            "description": "Role IDs"
+            "description": "IDs of the roles assigned to the member: built-in `2` (Admin), `6` (Responder), `8` (Viewer), or custom role IDs from `POST /role/list`."
           },
           "is_external": {
             "type": "boolean",
-            "description": "Provisioned via SSO"
+            "description": "`true` when the member was provisioned through SSO rather than invited or registered."
           },
           "ref_id": {
             "type": "string",
-            "description": "External reference ID"
+            "description": "External reference ID (for example an employee ID in an HR system); empty string when unset."
           },
           "created_at": {
             "type": "integer",
@@ -3258,7 +3385,7 @@
           "p": {
             "type": "integer",
             "minimum": 1,
-            "description": "Page number, 1-based"
+            "description": "Page number, starting at 1. Defaults to the first page."
           },
           "limit": {
             "type": "integer",
@@ -3281,7 +3408,7 @@
           },
           "query": {
             "type": "string",
-            "description": "Substring match on member name or email; if the keyword parses as a phone number, an exact phone match is also applied"
+            "description": "Keyword. Matches a substring of the member name or email; a numeric keyword also matches an exact member ID, and a keyword that parses as a phone number (without `+`, parsed as a Chinese number) also matches the exact phone."
           }
         }
       },
@@ -3291,22 +3418,22 @@
         "properties": {
           "p": {
             "type": "integer",
-            "description": "Current page"
+            "description": "Page number from the request; `0` when `p` was omitted (the first page is returned)."
           },
           "limit": {
             "type": "integer",
-            "description": "Page size"
+            "description": "Page size applied; 100 when `limit` was omitted."
           },
           "total": {
             "type": "integer",
-            "description": "Total count"
+            "description": "Number of members matching the filters, across all pages."
           },
           "items": {
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/MemberItem"
             },
-            "description": "Member items"
+            "description": "Members on this page; empty array when none match."
           }
         },
         "required": [
@@ -3396,7 +3523,7 @@
             ],
             "minLength": 2,
             "maxLength": 39,
-            "description": "New display name."
+            "description": "New display name, 2–39 characters, unique in the account."
           },
           "password": {
             "type": [
@@ -3410,7 +3537,7 @@
               "string",
               "null"
             ],
-            "description": "New phone number. Include country_code when the number is not in E.164 format."
+            "description": "New phone number; include `country_code` when it is not in E.164 format. Must not belong to another member; the new number is marked unverified (see `from`)."
           },
           "country_code": {
             "type": [
@@ -3424,7 +3551,7 @@
               "string",
               "null"
             ],
-            "description": "New email address."
+            "description": "New email address. Must not belong to another member; the new address is marked unverified (see `from`)."
           },
           "avatar": {
             "type": [
@@ -3450,14 +3577,14 @@
               "string",
               "null"
             ],
-            "description": "New IANA time zone name, such as Asia/Shanghai."
+            "description": "New IANA time zone name such as `Asia/Shanghai`; an empty string clears it so the member follows the account's time zone. An invalid name returns `400`."
           },
           "ref_id": {
             "type": [
               "string",
               "null"
             ],
-            "description": "New external reference ID."
+            "description": "New external reference ID; an empty string clears it."
           }
         }
       },
@@ -3472,7 +3599,7 @@
           "member_id": {
             "type": "integer",
             "format": "uint64",
-            "description": "Member ID"
+            "description": "ID of the member whose roles change (from `POST /member/list`)."
           },
           "role_ids": {
             "type": "array",
@@ -3495,7 +3622,7 @@
           "member_id": {
             "type": "integer",
             "format": "uint64",
-            "description": "Member ID"
+            "description": "ID of the member whose roles change (from `POST /member/list`)."
           },
           "role_ids": {
             "type": "array",
@@ -3517,7 +3644,7 @@
           "member_id": {
             "type": "integer",
             "format": "uint64",
-            "description": "Member ID"
+            "description": "ID of the member whose roles change (from `POST /member/list`)."
           },
           "role_ids": {
             "type": "array",
@@ -3525,7 +3652,7 @@
               "type": "integer",
               "format": "uint64"
             },
-            "description": "New role ID set. Replaces the member's existing roles entirely (not additive); get IDs from `POST /role/list`. Leave empty to reset to the built-in Viewer role (ID 8)"
+            "description": "New role ID set; replaces the member's existing roles entirely (not additive). Get IDs from `POST /role/list`."
           }
         }
       },
@@ -3536,11 +3663,11 @@
           "member_id": {
             "type": "integer",
             "format": "uint64",
-            "description": "Member ID"
+            "description": "ID of the newly created member."
           },
           "member_name": {
             "type": "string",
-            "description": "Member display name"
+            "description": "Display name stored for the member; derived from the email prefix when `member_name` was omitted."
           }
         }
       },
@@ -3738,12 +3865,12 @@
           "account_id": {
             "type": "integer",
             "format": "uint64",
-            "description": "Account ID"
+            "description": "ID of the account the person belongs to."
           },
           "person_id": {
             "type": "integer",
             "format": "uint64",
-            "description": "Person ID"
+            "description": "Person ID: the account ID for the account owner, otherwise the member ID."
           },
           "person_name": {
             "type": "string",
@@ -3755,11 +3882,11 @@
           },
           "locale": {
             "type": "string",
-            "description": "Locale. Omitted when empty."
+            "description": "Locale preference (`zh-CN` or `en-US`). Omitted when unset."
           },
           "time_zone": {
             "type": "string",
-            "description": "Time zone. Omitted when empty."
+            "description": "IANA time zone setting: the member's own setting, or the account's for the account owner. Omitted when unset (a member without a setting follows the account's time zone)."
           },
           "email": {
             "type": "string",
@@ -3775,7 +3902,7 @@
           },
           "email_verified": {
             "type": "boolean",
-            "description": "Email verified"
+            "description": "`true` when the email address is verified; for the account owner, `true` whenever an email is set."
           },
           "as": {
             "type": "string",
@@ -3815,7 +3942,7 @@
               "type": "integer",
               "format": "uint64"
             },
-            "description": "Member IDs to grant/revoke the role."
+            "description": "IDs of the members to grant the role to or revoke it from (from `POST /member/list`). All must be members of the account; duplicates are rejected."
           },
           "role_id": {
             "type": "integer",
@@ -3867,15 +3994,15 @@
           "role_id": {
             "type": "integer",
             "format": "uint64",
-            "description": "Unique role ID."
+            "description": "Role ID. Built-in roles use the fixed IDs `2` (Admin), `6` (Responder), and `8` (Viewer)."
           },
           "role_name": {
             "type": "string",
-            "description": "Role display name."
+            "description": "Role name, unique in the account. The built-in roles are named `Admin`, `Responder`, and `Viewer` in every language."
           },
           "description": {
             "type": "string",
-            "description": "Role description."
+            "description": "Role description. For built-in roles it is localized by the request language."
           },
           "status": {
             "type": "string",
@@ -3883,7 +4010,7 @@
               "enabled",
               "disabled"
             ],
-            "description": "Role status."
+            "description": "Role status. `enabled` — active; `disabled` — turned off with `POST /role/disable`. Built-in roles are always `enabled`; deleted roles are never returned."
           },
           "permission_ids": {
             "type": "array",
@@ -3891,16 +4018,16 @@
               "type": "integer",
               "format": "uint64"
             },
-            "description": "IDs of permissions granted by this role."
+            "description": "IDs of the permissions the role grants, in ascending order; resolve them with `POST /role/permission/list`. Empty array when none."
           },
           "editable": {
             "type": "boolean",
-            "description": "False for built-in roles which cannot be modified."
+            "description": "`false` for the built-in roles (Admin, Responder, Viewer); `true` for custom roles."
           },
           "created_at": {
             "type": "integer",
             "format": "int64",
-            "description": "Unix epoch seconds the role was created."
+            "description": "Time the role was created, Unix timestamp in seconds. Built-in roles carry a fixed timestamp."
           },
           "updated_at": {
             "type": "integer",
@@ -3941,7 +4068,7 @@
         "properties": {
           "total": {
             "type": "integer",
-            "description": "Total role count."
+            "description": "Number of roles returned: custom roles plus the 3 built-in roles unless `no_global` is true."
           },
           "items": {
             "type": "array",
@@ -3962,11 +4089,11 @@
               "type": "integer",
               "format": "uint64"
             },
-            "description": "Filter to permissions granted to these roles."
+            "description": "Role IDs (built-in or custom) whose granted permissions to return or mark. IDs that do not exist are ignored."
           },
           "with_all": {
             "type": "boolean",
-            "description": "If true, return all permissions with is_granted set to indicate which are granted."
+            "description": "When true, return every permission and use `is_granted` to mark the ones granted by `role_ids`. When false (default), return only the granted permissions."
           }
         }
       },
@@ -3996,7 +4123,7 @@
           "role_id": {
             "type": "integer",
             "format": "uint64",
-            "description": "Role ID. Omit or set to 0 to create."
+            "description": "ID of the custom role to update. Omit or set to 0 to create a new role. Do not pass the built-in role IDs `2`, `6`, or `8`."
           },
           "role_name": {
             "type": "string",
@@ -4007,7 +4134,7 @@
           "description": {
             "type": "string",
             "maxLength": 499,
-            "description": "Role description."
+            "description": "Role description, up to 499 characters. Omitting it on update clears the stored description."
           },
           "permission_ids": {
             "type": "array",
@@ -4015,7 +4142,7 @@
               "type": "integer",
               "format": "uint64"
             },
-            "description": "Permission IDs to grant. Replaces the existing set."
+            "description": "IDs of the permissions the role grants (from `POST /role/permission/list`). Replaces the existing set; omitting it or sending an empty array leaves the role with no permissions."
           }
         }
       },
@@ -4048,12 +4175,11 @@
             "example": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
           },
           "data": {
-            "description": "Endpoint-specific payload. See each operation's 200 response schema."
+            "description": "Operation-specific payload, documented in each operation's 200 response. Operations without a payload return `{}` or omit `data` entirely."
           }
         },
         "required": [
-          "request_id",
-          "data"
+          "request_id"
         ]
       },
       "TeamBriefItem": {
@@ -4063,11 +4189,11 @@
           "team_id": {
             "type": "integer",
             "format": "uint64",
-            "description": "Team ID."
+            "description": "Team ID, one of the requested `team_ids`."
           },
           "team_name": {
             "type": "string",
-            "description": "Team name."
+            "description": "Team name. Deleted teams are included, so this can be the name of a team that no longer appears in `POST /team/list`."
           },
           "person_ids": {
             "type": "array",
@@ -4181,11 +4307,14 @@
         ],
         "properties": {
           "items": {
-            "type": "array",
+            "type": [
+              "array",
+              "null"
+            ],
             "items": {
               "$ref": "#/components/schemas/TeamBriefItem"
             },
-            "description": "Array of brief team info for the matched `team_ids`; may be null when no ID matches."
+            "description": "Brief info for the matched teams, including deleted ones; `null` when no ID matches."
           }
         }
       },
@@ -4236,7 +4365,7 @@
           },
           "updated_by_name": {
             "type": "string",
-            "description": "Display name of the last editor."
+            "description": "Name of the last editor: the member's name, or the account name when the account owner made the change; empty string when unknown."
           },
           "updated_by": {
             "type": "integer",
@@ -4268,7 +4397,7 @@
               "type": "integer",
               "format": "uint64"
             },
-            "description": "Member IDs of team members."
+            "description": "Person IDs of the team's members (member IDs; the account owner's ID when the owner is in the team). Empty array when the team has no members."
           },
           "ref_id": {
             "type": "string",
@@ -4329,15 +4458,15 @@
         "properties": {
           "p": {
             "type": "integer",
-            "description": "Current page number."
+            "description": "Page number from the request; `0` when `p` was omitted (the first page is returned)."
           },
           "limit": {
             "type": "integer",
-            "description": "Page size used."
+            "description": "Page size applied; 20 when `limit` was omitted."
           },
           "total": {
             "type": "integer",
-            "description": "Total number of teams matching the filter."
+            "description": "Number of non-deleted teams matching the filters, across all pages."
           },
           "items": {
             "type": "array",
@@ -4358,7 +4487,7 @@
           "team_id": {
             "type": "integer",
             "format": "uint64",
-            "description": "Team ID. Omit or set to 0 to create a new team."
+            "description": "ID of the team to update. Omit or set to 0 to create a new team; a non-zero ID must belong to an existing team of the account."
           },
           "team_name": {
             "type": "string",
@@ -4369,7 +4498,7 @@
           "description": {
             "type": "string",
             "maxLength": 500,
-            "description": "Free-form description."
+            "description": "Free-form description, up to 500 characters. On update, omitting it clears the stored description."
           },
           "person_ids": {
             "type": "array",
@@ -4377,7 +4506,7 @@
               "type": "integer",
               "format": "uint64"
             },
-            "description": "Member IDs to set as team members. Replaces the existing member list."
+            "description": "Person IDs to place in the team (member IDs, or the account ID for the account owner). Together with `emails` and `phones` they replace the entire member list; IDs that are not members of the account are ignored."
           },
           "emails": {
             "type": "array",
@@ -4385,22 +4514,22 @@
               "type": "string",
               "format": "email"
             },
-            "description": "Add existing members to the team by email. Addresses that don't match an existing member are silently ignored — no invitation is sent."
+            "description": "Emails of existing members to place in the team; merged with `person_ids` and `phones`. Addresses that match no member are ignored and no invitation is sent."
           },
           "phones": {
             "type": "array",
             "items": {
               "type": "string"
             },
-            "description": "Add existing members to the team by phone number. Numbers not in E.164 format are parsed with `countryCode`; an unparseable number fails the whole request with a 400. Numbers that parse but match no existing member are silently ignored."
+            "description": "Phone numbers of existing members to place in the team; merged with `person_ids` and `emails`. Numbers without a `+` prefix are parsed with `countryCode`; an unparseable number fails the whole request with `400`, and numbers that match no member are ignored."
           },
           "countryCode": {
             "type": "string",
-            "description": "Default country code applied to any `phones` entries that are not in E.164 format."
+            "description": "Region hint for `phones` entries without a `+` prefix: an ISO 3166-1 alpha-2 code such as `CN` (the default when omitted) or a digit calling code such as `86`."
           },
           "ref_id": {
             "type": "string",
-            "description": "External reference ID for HR system integration."
+            "description": "External reference ID (for example a department ID in an HR system), usable as a lookup key in `POST /team/info` and `POST /team/delete`. On update, omitting it clears the stored value."
           },
           "reset_if_name_exist": {
             "type": "boolean",
@@ -4437,7 +4566,7 @@
           },
           "account_name": {
             "type": "string",
-            "description": "Account name."
+            "description": "Account (organization) name shown in the console."
           },
           "domain": {
             "type": "string",
@@ -4468,11 +4597,11 @@
           },
           "locale": {
             "type": "string",
-            "description": "Account language preference (e.g. zh-CN, en-US)."
+            "description": "Account language preference (`zh-CN` or `en-US`); empty string when not set."
           },
           "time_zone": {
             "type": "string",
-            "description": "Account default timezone (IANA name, e.g. Asia/Shanghai)."
+            "description": "Account default time zone (IANA name, e.g. `Asia/Shanghai`); members without their own setting follow it. Empty string when not set."
           },
           "created_at": {
             "type": "integer",
@@ -4484,18 +4613,24 @@
             "description": "Account access restrictions. Omitted when none are configured.",
             "properties": {
               "ips": {
-                "type": "array",
+                "type": [
+                  "array",
+                  "null"
+                ],
                 "items": {
                   "type": "string"
                 },
-                "description": "Allowed source IP/CIDR whitelist."
+                "description": "Source IP addresses or CIDR ranges allowed to call the console and API for this account; `null` or empty when unrestricted."
               },
               "email_domains": {
-                "type": "array",
+                "type": [
+                  "array",
+                  "null"
+                ],
                 "items": {
                   "type": "string"
                 },
-                "description": "Allowed login email domains."
+                "description": "Email domains allowed for new members; invitations to other domains are rejected. `null` or empty when unrestricted."
               },
               "allow_subdomain": {
                 "type": "boolean",
@@ -4505,7 +4640,10 @@
           },
           "mp_plat": {
             "type": "string",
-            "description": "Cloud marketplace platform the account was provisioned from. Omitted when the account did not come from a marketplace."
+            "description": "Cloud marketplace the account was provisioned from: `aws` — AWS Marketplace. Omitted when the account did not come from a marketplace.",
+            "enum": [
+              "aws"
+            ]
           },
           "mp_account_id": {
             "type": "string",
@@ -4541,7 +4679,7 @@
           "is_force": {
             "type": "boolean",
             "default": false,
-            "description": "When false (default), deletion fails with a `ReferenceExist` error listing the members that still hold the role in `data.refs`. When true, the role is first revoked from all holders and then deleted."
+            "description": "When false (default), deletion fails with `ReferenceExist` while members still hold the role, listing them in `data.refs`. When true, the role is first revoked from all holders and then deleted. Does not bypass the SSO default-role check."
           }
         }
       },
diff --git a/api-reference/platform.openapi.zh.json b/api-reference/platform.openapi.zh.json
index 4cc32029a..e66336065 100644
--- a/api-reference/platform.openapi.zh.json
+++ b/api-reference/platform.openapi.zh.json
@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Flashduty 开放 API",
-    "description": "Flashduty 事件管理平台的公开 HTTP API —— 覆盖故障、通知模板、协作空间、值班排班、监控、RUM、以及平台管理。每次调用都需在 query 中携带 `app_key`，该 key 在 Flashduty 控制台 账户 → APP Key 中签发。所有响应使用统一结构：成功时为 `{ request_id, data }`，失败时为 `{ request_id, error }`。",
+    "description": "Flashduty 事件管理平台的公开 HTTP API —— 覆盖故障、通知模板、协作空间、值班排班、监控、RUM、以及平台管理。每次调用都需在 query 中携带 `app_key`，该 key 在 Flashduty 控制台 我的 → APP Key 中创建（也可放在请求头 `Fd-App-Key` 中）。所有响应使用统一结构：成功时为 `{ request_id, data }`，失败时为 `{ request_id, error }`。",
     "version": "1.0.0"
   },
   "servers": [
@@ -48,7 +48,7 @@
           "平台/团队管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 传入 `person_id` 可过滤返回指定人员所属的团队。\n- 默认 p=1、limit=20。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 传 `person_id` 只返回该人员所在的团队；`query` 对团队名称或描述做子串匹配。\n- 已删除的团队不会出现在列表中。",
           "href": "/zh/api-reference/platform/teams/team-read-list",
           "metadata": {
             "sidebarTitle": "查看团队列表"
@@ -79,23 +79,24 @@
                   "data": {
                     "p": 1,
                     "limit": 20,
-                    "total": 5,
+                    "total": 1,
                     "items": [
                       {
                         "account_id": 10023,
                         "team_id": 1001,
                         "team_name": "Backend SRE",
+                        "description": "Backend reliability engineering team",
                         "status": "enabled",
+                        "updated_by_name": "alice",
+                        "updated_by": 80011,
                         "creator_id": 80011,
+                        "creator_name": "",
                         "created_at": 1710000000,
                         "updated_at": 1712000000,
                         "person_ids": [
-                          80011
+                          80011,
+                          80012
                         ],
-                        "description": "",
-                        "updated_by_name": "",
-                        "updated_by": 0,
-                        "creator_name": "alice",
                         "ref_id": ""
                       }
                     ]
@@ -110,6 +111,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -144,7 +148,7 @@
           "平台/团队管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 重复的 ID 会被去重；不匹配任何团队的 ID 会被忽略。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 重复的 ID 会去重；不属于本账户任何团队的 ID 会被忽略。\n- 已删除的团队仍会返回（`person_ids` 为空），因此历史记录里保存的团队 ID 依然能解析出名称。\n- 没有任何 ID 匹配时，`items` 为 `null`。",
           "href": "/zh/api-reference/platform/teams/team-read-infos",
           "metadata": {
             "sidebarTitle": "批量查看团队信息"
@@ -201,6 +205,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -230,12 +237,12 @@
       "post": {
         "operationId": "role-write-disable",
         "summary": "禁用角色",
-        "description": "禁用自定义角色，使其停止授予权限。",
+        "description": "将自定义角色置为禁用状态，但不删除它。",
         "tags": [
           "平台/角色与权限"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **角色管理**（`organization`） |\n\n## 使用说明\n\n- 持有该角色的成员将立即失去其权限。\n- 内置角色始终保持启用状态；对其启用/禁用为静默空操作。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **角色管理**（`organization`） |\n\n## 使用说明\n\n- 只有 `enabled` 状态的角色可以禁用；对已禁用的角色调用会返回 `400 InvalidParameter`。\n- 内置角色（`2`、`6`、`8`）无法禁用：调用返回成功，但不做任何修改。\n- 角色 ID 不存在或已删除时不做任何操作，调用仍返回成功。\n- 禁用角色不会把它从持有该角色的成员身上解除。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/platform/roles-permissions/role-write-disable",
           "metadata": {
             "sidebarTitle": "禁用角色"
@@ -303,12 +310,12 @@
       "post": {
         "operationId": "role-write-delete",
         "summary": "删除角色",
-        "description": "删除一个自定义角色。当仍有成员持有该角色时，除非 `is_force` 为 true，否则调用失败并返回 `ReferenceExist`。",
+        "description": "删除自定义角色，可选择先从所有仍持有它的成员身上解除。",
         "tags": [
           "平台/角色与权限"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **角色管理**（`organization`） |\n\n## 使用说明\n\n- 内置角色是虚拟数据，永远不会被删除；对内置角色调用等同空操作。\n- 默认（`is_force=false`）情况下，只要还有成员持有该角色，调用就会失败并返回 `ReferenceExist` 错误码，持有成员列在 `data.refs` 中。设置 `is_force=true` 可先从所有持有成员解除该角色再删除。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **角色管理**（`organization`） |\n\n## 使用说明\n\n- 仍有成员持有该角色时，调用返回 `400 ReferenceExist`，并在 `data.refs` 中列出这些成员（`kind` 为 `member`）；设置 `is_force` 为 `true` 会先从所有持有成员解除该角色再删除。\n- 被单点登录配置选为默认角色的角色无法删除，即使设置 `is_force` 也一样；在单点登录配置中取消选择前，调用会返回 `400 ReferenceExist`。\n- 角色 ID 不存在或已删除时不做任何操作，调用仍返回成功。\n- 不要传内置角色 ID（`2`、`6`、`8`）：内置角色本身不会被删除，但设置 `is_force: true` 时会把它从所有持有成员身上解除。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/platform/roles-permissions/role-write-delete",
           "metadata": {
             "sidebarTitle": "删除角色"
@@ -381,7 +388,7 @@
           "平台/成员管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 传入账户 ID 会返回账户主体，`as` 为 `account`。其他 ID 在本账户成员中查找，包括已删除的成员（`status` 为 `deleted`），因此历史记录里保存的 ID 依然能解析。\n- 重复的 ID 会去重；两者都匹配不上的 ID 会被省略。",
           "href": "/zh/api-reference/platform/members/person-infos",
           "metadata": {
             "sidebarTitle": "批量获取人员信息"
@@ -446,6 +453,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -475,12 +485,12 @@
       "post": {
         "operationId": "memberInfo",
         "summary": "获取当前成员信息",
-        "description": "返回当前凭据所属成员的完整资料。需要成员级凭据——以账户主体身份（如账户级 App Key）调用会被拒绝并返回 400。",
+        "description": "返回当前凭据所属成员的资料及其所在账户信息。",
         "tags": [
           "平台/成员管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 但凭据必须属于某个成员；以账户主体身份（如账户级 App Key）调用会被拒绝并返回 400 |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 但对调用凭据有要求，见使用说明 |\n\n## 使用说明\n\n- 需要成员凭据；使用账户主体凭据调用会返回 `400 BadRequest`。账户主体请使用 `POST /account/info`。\n- `time_zone` 是成员自己的设置（空字符串表示跟随账户），`account_time_zone` 是账户的设置，`resolved_time_zone` 是实际用于展示时间的时区。",
           "href": "/zh/api-reference/platform/members/member-info",
           "metadata": {
             "sidebarTitle": "获取当前成员信息"
@@ -530,7 +540,8 @@
                     "member_name": "Alice",
                     "phone": "+86185****0300",
                     "phone_verified": true,
-                    "time_zone": "Asia/Shanghai"
+                    "time_zone": "Asia/Shanghai",
+                    "resolved_time_zone": "Asia/Shanghai"
                   }
                 }
               }
@@ -542,6 +553,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -566,12 +580,12 @@
       "post": {
         "operationId": "role-read-list-permission",
         "summary": "查看角色权限集合",
-        "description": "返回所有可用权限，可按角色 ID 过滤仅返回指定角色已授予的权限。",
+        "description": "列出权限项，并标记其中哪些由指定角色授予。",
         "tags": [
           "平台/角色与权限"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 传入 `role_ids` 可过滤只返回指定角色已授予的权限。\n- 传入 `with_all: true` 可返回全部权限，并在每项中通过 `is_granted` 标记是否已授予。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- `with_all: true` 时返回全部权限，`is_granted` 标记 `role_ids` 中任一角色授予的权限。\n- `with_all` 为 false（默认）时只返回 `role_ids` 授予的权限——不传 `role_ids` 会得到空列表。\n- `permission_name`、`description`、`class` 随请求语言变化（`Accept-Language` 请求头，或 `locale`/`lang` 查询参数）。",
           "href": "/zh/api-reference/platform/roles-permissions/role-read-list-permission",
           "metadata": {
             "sidebarTitle": "查看角色权限集合"
@@ -624,6 +638,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -658,7 +675,7 @@
           "平台/团队管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- `team_id`、`team_name`、`ref_id` 三者至少提供一个。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- `team_id`、`team_name`、`ref_id` 三者提供其一；同时传多个时，`ref_id` 优先于 `team_name`，`team_name` 优先于 `team_id`。\n- 按 `team_name` 或 `ref_id` 查找只匹配未删除的团队；按 `team_id` 查找时已删除的团队也会返回，`status` 为 `deleted`。\n- 找不到团队时返回 `400 InvalidParameter`。",
           "href": "/zh/api-reference/platform/teams/team-read-info",
           "metadata": {
             "sidebarTitle": "查看团队详情"
@@ -695,7 +712,7 @@
                     "updated_by_name": "alice",
                     "updated_by": 80011,
                     "creator_id": 80011,
-                    "creator_name": "alice",
+                    "creator_name": "",
                     "created_at": 1710000000,
                     "updated_at": 1712000000,
                     "person_ids": [
@@ -714,6 +731,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -740,12 +760,12 @@
       "post": {
         "operationId": "team-write-delete",
         "summary": "删除团队",
-        "description": "按 ID、名称或外部引用 ID 永久删除一个团队。",
+        "description": "按 ID、名称或外部引用 ID 删除团队，并移除其全部成员。",
         "tags": [
           "平台/团队管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **团队管理**（`organization`） |\n\n## 使用说明\n\n- `team_id`、`team_name`、`ref_id` 三者至少提供一个。\n- 若团队仍被排班、分派策略等资源引用，会返回 `400 ReferenceExist`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **团队管理**（`organization`） |\n\n## 使用说明\n\n- `team_id`、`team_name`、`ref_id` 三者提供其一；同时传多个时依次以 `team_id`、`team_name`、`ref_id` 为准。\n- 除上述权限外，调用者还必须是团队成员、团队创建者、账户主体或拥有 Admin 角色，否则返回 `403 AccessDenied`。\n- 团队仍被分派策略、值班表、协作空间、通知模板、映射规则、服务日历或单点登录配置的默认团队引用时，返回 `400 ReferenceExist`，`data.refs` 列出每条引用（`kind`、`name`、`href`）。\n- 删除为软删除：团队成员全部移除，团队不再出现在列表和按名称/`ref_id` 的查找中，名称可以重新使用；按 `team_id` 调用 `POST /team/info` 仍能查到，`status` 为 `deleted`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/platform/teams/team-write-delete",
           "metadata": {
             "sidebarTitle": "删除团队"
@@ -818,7 +838,7 @@
           "平台/角色与权限"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- ID `2`、`6`、`8` 返回内置的 Admin、Responder、Viewer 角色，其 `description` 随请求语言变化。\n- 角色 ID 不存在或已删除时返回 `400 InvalidParameter`。",
           "href": "/zh/api-reference/platform/roles-permissions/role-read-info",
           "metadata": {
             "sidebarTitle": "查看角色详情"
@@ -848,17 +868,18 @@
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "role_id": 2,
-                    "role_name": "Account Admin",
-                    "description": "Account admin with all permissions.",
+                    "role_name": "Admin",
+                    "description": "Account Administrator, has all account permissions and can assist the main account in managing all affairs.",
                     "status": "enabled",
                     "permission_ids": [
                       101,
                       102,
-                      201
+                      201,
+                      701
                     ],
                     "editable": false,
-                    "created_at": 1700000000,
-                    "updated_at": 1700000000
+                    "created_at": 1653530940,
+                    "updated_at": 1653530940
                   }
                 }
               }
@@ -870,6 +891,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -901,7 +925,7 @@
           "平台/成员管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **成员管理**（`organization`） |\n\n## 使用说明\n\n- `country_code` 必须是 ISO 3166-1 alpha-2 地区代码（如 \"CN\"）；写入前校验并统一转为大写，非法值返回 400。\n- 当成员的 `phone` 不带 \"+\" 前缀时，按该成员的 `country_code` 作为地区提示解析（未传时默认 \"CN\"）。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **成员管理**（`organization`） |\n\n## 使用说明\n\n- 每个条目需要提供 `email`，或同时提供 `member_name` 和 `phone`。\n- 邮箱或手机号已属于本账户成员的条目会被静默跳过；`items` 只列出本次新建的成员，一个都没有创建时为 `null`。\n- 新成员以 `pending` 状态创建，并通过邮件或短信收到邀请。\n- 邮箱以小写存储。账户限制了成员邮箱域名时，不在白名单内的地址返回 `400`；同一请求内邮箱或手机号重复也返回 `400`。\n- `country_code` 必须是 ISO 3166-1 alpha-2 地区代码（如 \"CN\"）；写入前校验并统一转为大写，非法值返回 400。\n- 当成员的 `phone` 不带 \"+\" 前缀时，按该成员的 `country_code` 作为地区提示解析（未传时默认 \"CN\"）。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/platform/members/member-invite",
           "metadata": {
             "sidebarTitle": "邀请成员"
@@ -951,6 +975,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -999,7 +1026,7 @@
           "平台/角色与权限"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **角色管理**（`organization`） |\n\n## 使用说明\n\n- 内置角色始终保持启用状态；对其启用/禁用为静默空操作。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **角色管理**（`organization`） |\n\n## 使用说明\n\n- 只有 `disabled` 状态的角色可以启用；对已启用的角色（包括内置角色）调用会返回 `400 InvalidParameter`。\n- 角色 ID 不存在或已删除时不做任何操作，调用仍返回成功。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/platform/roles-permissions/role-write-enable",
           "metadata": {
             "sidebarTitle": "启用角色"
@@ -1072,7 +1099,7 @@
           "平台/角色与权限"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 内置角色（`editable: false`）不可修改或删除。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 自定义角色（含启用和禁用）排在前面，按 `orderby`/`asc` 排序；三个内置角色——`2` Admin、`6` Responder、`8` Viewer——追加在末尾（`no_global` 为 true 时不返回），并计入 `total`。\n- 内置角色的 `editable` 为 false，其 `description` 随请求语言变化（`Accept-Language` 请求头，或 `locale`/`lang` 查询参数）。",
           "href": "/zh/api-reference/platform/roles-permissions/role-read-list",
           "metadata": {
             "sidebarTitle": "查看角色列表"
@@ -1101,17 +1128,60 @@
                 "example": {
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
-                    "total": 3,
+                    "total": 4,
                     "items": [
+                      {
+                        "role_id": 150,
+                        "role_name": "On-call Manager",
+                        "description": "Manage on-call rotations and incidents.",
+                        "status": "enabled",
+                        "permission_ids": [
+                          501,
+                          502
+                        ],
+                        "editable": true,
+                        "created_at": 1710000000,
+                        "updated_at": 1712000000
+                      },
                       {
                         "role_id": 2,
-                        "role_name": "Account Admin",
-                        "description": "",
+                        "role_name": "Admin",
+                        "description": "Account Administrator, has all account permissions and can assist the main account in managing all affairs.",
                         "status": "enabled",
-                        "permission_ids": [],
+                        "permission_ids": [
+                          101,
+                          102,
+                          201,
+                          701
+                        ],
                         "editable": false,
-                        "created_at": 1700000000,
-                        "updated_at": 1700000000
+                        "created_at": 1653530940,
+                        "updated_at": 1653530940
+                      },
+                      {
+                        "role_id": 6,
+                        "role_name": "Responder",
+                        "description": "Responder, has standard permissions except billing center, member management, role management and single sign-on management, suitable for members handling daily operations.",
+                        "status": "enabled",
+                        "permission_ids": [
+                          201,
+                          701
+                        ],
+                        "editable": false,
+                        "created_at": 1653530940,
+                        "updated_at": 1653530940
+                      },
+                      {
+                        "role_id": 8,
+                        "role_name": "Viewer",
+                        "description": "Viewer, has most read-only permissions except audit and onboarding, suitable for members who only need to view data.",
+                        "status": "enabled",
+                        "permission_ids": [
+                          103
+                        ],
+                        "editable": false,
+                        "created_at": 1653530940,
+                        "updated_at": 1653530940
                       }
                     ]
                   }
@@ -1125,6 +1195,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -1157,7 +1230,7 @@
           "平台/成员管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 使用 `member_id`、`member_name`、`email`、`phone` 或 `ref_id` 中任一字段定位成员；如果同时传多个字段，服务端按上述顺序匹配。\n- `updates.country_code` 为 ISO 3166-1 alpha-2 地区代码（如 \"CN\"、\"US\"）。它是独立可更新字段：无需同时传 `updates.phone`，即使手机号不变也会写入新的地区代码；显式传空字符串会被拒绝（400）。\n- 当 `updates.phone` 不带 \"+\" 前缀时，按 `updates.country_code` 作为地区提示解析；未传时依次回退到成员已存的地区代码、默认值 \"CN\"。\"86\" 等数字电话区号仅在解析场景兼容，存储值一律为 ISO 地区代码。\n- 顶层的 `country_code` 仅作为定位用 `phone` 的解析提示，不会被存储。\n- `updates` 承载要写入的新资料，支持 `member_name`、`password`、`phone`、`country_code`、`email`、`avatar`、`locale`、`time_zone`、`ref_id`。\n- 由 SSO 托管且不可编辑的成员不能通过此接口修改。\n- `updates` 至少要带一个字段；所有字段都不传的空对象会被拒绝。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 使用 `member_id`、`member_name`、`email`、`phone` 或 `ref_id` 中任一字段定位成员；如果同时传多个字段，服务端按上述顺序匹配。\n- 调用者必须是账户主体、该成员本人或拥有 Admin 角色，否则返回 `403 AccessDenied`。\n- `updates` 承载要写入的新资料，支持 `member_name`、`password`、`phone`、`country_code`、`email`、`avatar`、`locale`、`time_zone`、`ref_id`。省略或为 `null` 的字段保持原值；`updates` 至少要带一个字段。\n- 新的 `member_name`、`email`、`phone` 不能已属于本账户其他成员，冲突时返回 `400`。修改后的 `email` 或 `phone` 会被标记为未验证，除非 `from` 为 `api` 且账户关闭了成员邀请。\n- `updates.time_zone` 传空字符串会清除成员自己的时区，使其跟随账户时区。\n- `updates.country_code` 为 ISO 3166-1 alpha-2 地区代码（如 \"CN\"、\"US\"）。它是独立可更新字段：无需同时传 `updates.phone`，即使手机号不变也会写入新的地区代码；显式传空字符串会被拒绝（400）。\n- 当 `updates.phone` 不带 \"+\" 前缀时，按 `updates.country_code` 作为地区提示解析；未传时依次回退到成员已存的地区代码、默认值 \"CN\"。\"86\" 等数字电话区号仅在解析场景兼容，存储值一律为 ISO 地区代码。\n- 顶层的 `country_code` 仅作为定位用 `phone` 的解析提示，不会被存储。\n- 各字段逐个写入；若后面的字段校验失败，同一次调用中已写入的字段不会回滚。\n- 通过单点登录同步的成员，在单点登录配置将其设为不可编辑时无法修改。\n- 同一账户内并发的资料更新或成员邀请可能返回 `429 RequestTooFrequently`，请稍后重试。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/platform/members/member-reset-info",
           "metadata": {
             "sidebarTitle": "重置成员信息"
@@ -1196,6 +1269,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -1232,7 +1308,7 @@
           "平台/审计日志"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **审计查看**（`organization`） |\n\n## 使用说明\n\n- 时间范围必填。最大跨度 90 天，`start_time` 和 `end_time` 均为 Unix 时间戳（**秒**）。\n- 使用上次响应中的 `search_after_ctx` 获取下一页。该 token 是不透明的，请勿手动构造。\n- 可查询的时间窗口受账户许可证限制，超出保留期的查询会静默返回空结果，而不是报错。\n- `limit` 取值 0–99；省略（或传 0）表示不分页，返回窗口内全部匹配记录。记录按时间倒序返回。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **审计查看**（`organization`） |\n\n## 使用说明\n\n- 必须指定时间范围，跨度最长 90 天。`start_time` 和 `end_time` 均为 Unix 时间戳（**秒**）。\n- 使用上一次响应中的 `search_after_ctx` 获取下一页。该游标是不透明的，请勿自行构造。\n- 可查询的保留期取决于账户的 License。超出保留期的查询会直接返回空结果，而不是报错。\n- 建议显式传 `limit`（1–99）以便稳定分页；不传或为 0 时由服务端决定每页条数，可能一次返回全部结果。结果按时间倒序返回。",
           "href": "/zh/api-reference/platform/audit-logs/audit-read-search",
           "metadata": {
             "sidebarTitle": "检索审计日志"
@@ -1293,6 +1369,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -1330,7 +1409,7 @@
           "平台/角色与权限"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **角色管理**（`organization`） |\n\n## 使用说明\n\n- 已持有该角色的成员会被静默跳过。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **角色管理**（`organization`） |\n\n## 使用说明\n\n- `member_ids` 中的每个 ID 都必须是本账户成员且不能重复，否则返回 `400`，不修改任何人。\n- `role_id` 必须是内置角色或未删除的自定义角色（已禁用的角色也可以），否则返回 `400`。\n- 通过单点登录同步的成员，在单点登录配置将其设为不可编辑时无法修改，调用返回 `400`。\n- 已持有该角色的成员保持不变。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/platform/roles-permissions/role-write-grant-role",
           "metadata": {
             "sidebarTitle": "授予成员账户权限"
@@ -1402,12 +1481,12 @@
       "post": {
         "operationId": "memberUpdateRole",
         "summary": "更新成员角色",
-        "description": "一次性整体替换成员的角色。不存在的角色 ID 会被静默丢弃；`role_ids` 为空时重置为内置 Viewer 角色（ID 8）。",
+        "description": "用给定的角色集合整体替换成员的角色。",
         "tags": [
           "平台/成员管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **成员管理**（`organization`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **成员管理**（`organization`） |\n\n## 使用说明\n\n- `role_ids` 为空或不传时，分配内置的 Viewer 角色（`8`）。\n- 不存在的角色 ID 会被丢弃；若给定的 ID 全部不存在，成员最终将没有任何角色。\n- 通过单点登录同步的成员，在单点登录配置将其设为不可编辑时无法修改，调用返回 `400`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/platform/members/member-update-role",
           "metadata": {
             "sidebarTitle": "更新成员角色"
@@ -1446,6 +1525,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -1481,7 +1563,7 @@
           "平台/角色与权限"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **角色管理**（`organization`） |\n\n## 使用说明\n\n- 省略 `role_id`（或置为 0）表示创建；传入已有 ID 表示更新。\n- `role_name` 须为 1–39 个字符且在账户内唯一。\n- `permission_ids` 会完整替换角色的权限集合。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **角色管理**（`organization`） |\n\n## 使用说明\n\n- 省略 `role_id`（或置为 0）表示创建角色；传入自定义角色的 ID 表示更新。\n- `role_name` 在账户内必须唯一，也不能与内置名称 `Admin`、`Responder`、`Viewer` 重复；冲突时返回 `400`。\n- 更新会同时覆盖 `role_name`、`description`、`permission_ids`：不传 `description` 会清空描述，不传 `permission_ids` 会移除该角色的全部权限。\n- 更新一个已禁用的角色会使其重新启用。\n- `permission_ids` 中的每个 ID 都必须是 `POST /role/permission/list`（`with_all: true`）返回的权限，否则返回 `400`，不做任何修改。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/platform/roles-permissions/role-write-upsert",
           "metadata": {
             "sidebarTitle": "创建或更新角色"
@@ -1557,12 +1639,12 @@
       "post": {
         "operationId": "role-read-list-permission-factor",
         "summary": "查看权限因子集合",
-        "description": "返回当前成员拥有的权限因子（API、按钮、菜单、URL、页面访问），可按类型过滤。需要成员级凭据——以账户主体身份（如账户级 App Key）调用会被拒绝并返回 400，因为账户主体天然拥有全部权限。",
+        "description": "列出调用成员通过其角色获得的权限因子。",
         "tags": [
           "平台/角色与权限"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 但凭据必须属于某个成员；以账户主体身份（如账户级 App Key）调用会被拒绝并返回 400 |\n\n## 使用说明\n\n- 权限因子是每个权限的细粒度控制项。\n- `factor_types` 可选值：`api`、`button`、`visit`、`menu`、`url`。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 但对调用凭据有要求，见使用说明 |\n\n## 使用说明\n\n- 需要成员凭据：使用账户主体凭据调用会返回 `400 InvalidParameter`，因为账户主体天然拥有全部权限。\n- 权限因子来自调用成员持有的所有角色，并已去重；返回顺序不固定。没有角色的成员得到空数组。\n- `factor_types` 按类型过滤（`api`、`button`、`visit`、`menu`、`url`）；不传则返回全部类型。传入不支持的类型返回 `400`。",
           "href": "/zh/api-reference/platform/roles-permissions/role-read-list-permission-factor",
           "metadata": {
             "sidebarTitle": "查看权限因子集合"
@@ -1607,6 +1689,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -1640,7 +1725,7 @@
           "平台/角色与权限"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **角色管理**（`organization`） |\n\n## 使用说明\n\n- 未持有该角色的成员会被静默跳过。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **角色管理**（`organization`） |\n\n## 使用说明\n\n- `member_ids` 中的每个 ID 都必须是本账户成员且不能重复，否则返回 `400`，不修改任何人。\n- `role_id` 必须是内置角色或未删除的自定义角色（已禁用的角色也可以），否则返回 `400`。\n- 通过单点登录同步的成员，在单点登录配置将其设为不可编辑时无法修改，调用返回 `400`。\n- 未持有该角色的成员保持不变；解除成员的最后一个角色后，该成员将没有任何角色。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/platform/roles-permissions/role-write-revoke-role",
           "metadata": {
             "sidebarTitle": "解除成员账户权限"
@@ -1716,7 +1801,7 @@
           "平台/审计日志"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **审计查看**（`organization`） |\n\n## 使用说明\n\n- 将本接口返回的 `name` 值作为 `POST /audit/search` 的 `operations` 过滤参数使用。\n- `name_cn` 是控制台展示的中文标签；`name` 是用于过滤的稳定字段值。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **审计查看**（`organization`） |\n\n## 使用说明\n\n- 将响应中的 `name` 值作为 `POST /audit/search` 的 `operations` 过滤值。\n- `name_cn` 是控制台中显示的中文标签，不随请求语言变化；`name` 是用于过滤的稳定值。",
           "href": "/zh/api-reference/platform/audit-logs/audit-read-operation-list",
           "metadata": {
             "sidebarTitle": "查看事件类型列表"
@@ -1770,6 +1855,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -1799,7 +1887,7 @@
           "平台/团队管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **团队管理**（`organization`） |\n\n## 使用说明\n\n- 省略 `team_id`（或置为 0）表示创建新团队；传入已有 ID 表示更新。\n- `team_name` 须为 1–39 个字符且在账户内唯一。\n- 传入 `person_ids` 可设置团队成员，会替换整个成员列表。\n- 传入 `emails` 或 `phones` 可按联系方式添加已有成员；匹配不到成员的联系方式会被忽略，不会发起邀请。\n- `ref_id` 是供第三方 HR 系统集成使用的外部标识。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **团队管理**（`organization`） |\n\n## 使用说明\n\n- 省略 `team_id`（或置为 0）表示创建团队；传入已有的 `team_id` 表示更新。`team_id` 找不到团队时返回 `400`。\n- `team_name` 在账户内的团队中必须唯一。名称已被其他团队使用时返回 `400`；但当 `team_id` 为 0 且 `reset_if_name_exist` 为 true 时，会更新该同名团队。\n- 成员列表总是整体替换：团队成员变为 `person_ids`、`emails`、`phones` 三者解析结果的并集。更新时三者都不传会清空所有成员。\n- 解析不到本账户成员（或账户主体）的条目会被静默丢弃，不会发出邀请。\n- 更新时 `description` 和 `ref_id` 也会被覆盖——不传即清空原值。\n- 更新团队时，调用者还必须是团队成员、团队创建者、账户主体或拥有 Admin 角色。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/platform/teams/team-write-upsert",
           "metadata": {
             "sidebarTitle": "变更团队信息"
@@ -1875,12 +1963,12 @@
       "post": {
         "operationId": "memberGrantRole",
         "summary": "授予成员角色",
-        "description": "为成员追加角色授权。不存在的角色 ID 会被静默忽略；若全部无法解析，则调用成功但不产生任何变更。",
+        "description": "为成员在现有角色之外追加一个或多个角色。",
         "tags": [
           "平台/成员管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **成员管理**（`organization`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **成员管理**（`organization`） |\n\n## 使用说明\n\n- 不存在的角色 ID 会被忽略；全部不存在时调用成功但不做任何修改。\n- 成员已持有的角色只保留一份，不会重复添加。\n- 通过单点登录同步的成员，在单点登录配置将其设为不可编辑时无法修改，调用返回 `400`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/platform/members/member-grant-role",
           "metadata": {
             "sidebarTitle": "授予成员角色"
@@ -1919,6 +2007,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -1948,12 +2039,12 @@
       "post": {
         "operationId": "memberRevokeRole",
         "summary": "解除成员角色",
-        "description": "解除成员的角色授权。不存在的角色 ID 会被静默忽略；若全部无法解析，则调用成功但不产生任何变更。",
+        "description": "从成员的角色中移除一个或多个角色。",
         "tags": [
           "平台/成员管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **成员管理**（`organization`） |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **成员管理**（`organization`） |\n\n## 使用说明\n\n- 不存在的角色 ID 会被忽略；全部不存在时调用成功但不做任何修改。\n- 解除全部角色后成员将没有任何角色，不会回退为 Viewer。\n- 通过单点登录同步的成员，在单点登录配置将其设为不可编辑时无法修改，调用返回 `400`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/platform/members/member-revoke-role",
           "metadata": {
             "sidebarTitle": "解除成员角色"
@@ -1992,6 +2083,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -2026,7 +2120,7 @@
           "平台/成员管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **成员管理**（`organization`） |\n\n## 使用说明\n\n- 默认情况下（`is_force=false`），系统会检查该成员是否被其他资源引用（如分派策略、值班表等）。如果存在引用，接口将返回错误码 `ReferenceExist` 并在 `data.refs` 中返回引用列表。设置 `is_force=true` 可跳过引用检查，直接强制删除。\n- 通过 SSO 同步且 SSO 配置了成员不可编辑（`sso_user_non_editable=true`）的成员，无法通过此接口删除。需要先在 SSO 配置中关闭该限制。\n- 此操作会记录审计日志。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **成员管理**（`organization`） |\n\n## 使用说明\n\n- 使用任一查找字段定位成员；同时传多个时，按 `member_id`、`member_name`、`email`、`phone`、`ref_id` 的顺序取第一个非空字段。\n- 除非 `is_force` 为 true，成员仍属于某个团队、被分派策略直接指定或在值班表中时，调用返回 `400 ReferenceExist`，`data.refs` 列出每条引用。强制删除会跳过检查，且不会清理这些引用。\n- 删除为软删除：成员状态变为 `deleted`，释放其占用的 License 席位，并移除其单点登录身份关联。之后仍可通过 `POST /person/infos` 解析该成员。\n- 通过单点登录同步的成员，在单点登录配置将其设为不可编辑时无法删除，调用返回 `400`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/platform/members/member-delete",
           "metadata": {
             "sidebarTitle": "删除成员"
@@ -2065,6 +2159,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -2096,7 +2193,7 @@
           "平台/成员管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 返回 `enabled` 或 `pending` 状态的成员。已删除的成员和账户主体不会出现在列表中，可用 `POST /person/infos` 解析其 ID。\n- `role_id` 返回持有该角色的成员；`member_id` 最多返回该成员一人。",
           "href": "/zh/api-reference/platform/members/member-list",
           "metadata": {
             "sidebarTitle": "查询成员列表"
@@ -2180,6 +2277,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -2258,7 +2358,7 @@
                     "phone": "138****8000",
                     "country_code": "CN",
                     "email": "ops@acme.example",
-                    "avatar": "https://cdn.flashcat.cloud/avatar/acme.png",
+                    "avatar": "https://example.com/avatar/acme.png",
                     "locale": "zh-CN",
                     "time_zone": "Asia/Shanghai",
                     "created_at": 1716960000,
@@ -2282,6 +2382,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -2293,7 +2396,7 @@
           "metadata": {
             "sidebarTitle": "查看主体信息"
           },
-          "content": "| 权限 | 描述 |\n| --- | --- |\n| 无 | 无 — 任意有效的 app_key 均可调用此操作。 |\n\n在 [平台 API 参考](/zh/api-reference/platform/account/account-read-info) 中查看此操作。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 但对调用凭据有要求，见使用说明 |\n\n## 使用说明\n\n- 需要账户主体的凭据（如账户主体创建的 App Key）；使用成员凭据调用会返回 `401 Unauthorized`。成员可改用 `POST /member/info`。\n- `restrictions` 仅在配置过加入限制或访问限制时返回；`mp_plat`、`mp_account_id` 仅对通过云市场开通的账户返回。",
           "href": "/zh/api-reference/platform/account/account-read-info"
         }
       }
@@ -2302,12 +2405,12 @@
       "post": {
         "operationId": "memberNotify",
         "summary": "通知成员",
-        "description": "以调用方身份向账户成员发送邮件，邮件内容由调用方提供。仅可使用 AI SRE 会话凭据调用；使用其他凭据调用会返回 AccessDenied 错误。邮件投递是异步的——`accepted` 表示邮件已入队，并不代表已送达。",
+        "description": "以调用方 AI SRE 会话的身份，向账户成员发送其撰写的邮件。",
         "tags": [
           "平台/成员管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ----- |\n| 速率限制 | 每个账户 **200 次/分钟**；**10 次/秒** |\n| 权限要求 | 无——仅可使用 AI SRE 会话凭据调用；使用其他凭据调用会返回 AccessDenied |\n\n## 使用说明\n\n- 不是调用方账户内活跃成员、或没有邮箱地址的收件人会被跳过，不会导致整个请求失败。\n- 是否发送邮件取决于每个收件人针对此类消息的通知偏好设置；未设置偏好的收件人默认会收到邮件。\n- 收件人收到的邮件正文就是清洗后的 `html`，平台不会在其前后添加任何内容；发件人名称显示为调用方姓名加“(via AI SRE)”。\n- 发送前，服务端会检查提交的 `html`，如果其中包含移除后会改变收件人所见内容的构造（`<style>`、`<svg>`、`<iframe>`、`<object>`、`<embed>`、`<form>`、`<input>`、`<button>`、`src` 缺失或不是 `https` 的 `<img>`，或 href 不属于 `http`/`https`/`mailto` 的 `<a>`），会返回 `400` / `InvalidParameter` 并拒绝请求；错误消息会逐一列出触发的构造及需要如何修改，且不会入队——不占用每小时限额，也不占用同轮次去重。不影响渲染效果的标签（`<script>`、`<meta>`、`<link>`、`<base>`、`on*` 事件属性）仍会被静默清洗，不会触发拒绝。\n- 同一收件人通过该接口每小时最多收到 20 封邮件；超出后同一窗口内该收件人的后续投递会被跳过并返回 `rate_limited`。\n- 在同一个 AI SRE 会话轮次内重复调用，不会向已收到邮件的收件人重复发送；重复的收件人会被跳过并返回 `duplicate`。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **200 次/分钟**；**10 次/秒** |\n| 权限要求 | 无 —— 但对调用凭据有要求，见使用说明 |\n\n## 使用说明\n\n- 仅可使用 AI SRE 会话凭据调用；使用其他凭据调用会返回 `AccessDenied`。\n- 邮件投递是异步的——`accepted` 表示邮件已入队，并不代表已送达。\n- 不是调用方账户内活跃成员、或没有邮箱地址的收件人会被跳过，不会导致整个请求失败。\n- 是否发送邮件取决于每个收件人针对此类消息的通知偏好设置；未设置偏好的收件人默认会收到邮件。\n- 收件人收到的邮件正文就是清洗后的 `html`，平台不会在其前后添加任何内容；发件人名称显示为调用方姓名加“(via AI SRE)”。\n- 发送前，服务端会检查提交的 `html`，如果其中包含移除后会改变收件人所见内容的构造（`<style>`、`<svg>`、`<iframe>`、`<object>`、`<embed>`、`<form>`、`<input>`、`<button>`、`src` 缺失或不是 `https` 的 `<img>`，或 href 不属于 `http`/`https`/`mailto` 的 `<a>`），会返回 `400` / `InvalidParameter` 并拒绝请求；错误消息会逐一列出触发的构造及需要如何修改，且不会入队——不占用每小时限额，也不占用同轮次去重。不影响渲染效果的标签（`<script>`、`<meta>`、`<link>`、`<base>`、`on*` 事件属性）仍会被静默清洗，不会触发拒绝。\n- 同一收件人通过该接口每小时最多收到 20 封邮件；超出后同一窗口内该收件人的后续投递会被跳过并返回 `rate_limited`。\n- 在同一个 AI SRE 会话轮次内重复调用，不会向已收到邮件的收件人重复发送；重复的收件人会被跳过并返回 `duplicate`。",
           "href": "/zh/api-reference/platform/members/member-notify",
           "metadata": {
             "sidebarTitle": "通知成员"
@@ -2409,7 +2512,7 @@
         "type": "apiKey",
         "in": "query",
         "name": "app_key",
-        "description": "在 Flashduty 控制台 账户 → APP Key 中签发的 app_key。调用任何公开 API 时都必须携带。它等同于所属账户的身份凭证，请妥善保管。"
+        "description": "在 Flashduty 控制台 我的 → APP Key 中创建的 APP Key。可通过 query 参数 `app_key` 或请求头 `Fd-App-Key` 传入。实际可访问范围是该 APP Key 的权限范围与创建者当前角色权限的交集，请妥善保管。"
       }
     },
     "responses": {
@@ -2456,7 +2559,7 @@
         }
       },
       "Forbidden": {
-        "description": "app_key 有效但没有执行该操作的权限。",
+        "description": "app_key 有效，但其权限范围或创建者角色不允许该操作或该对象。",
         "content": {
           "application/json": {
             "schema": {
@@ -2498,7 +2601,7 @@
         }
       },
       "TooManyRequests": {
-        "description": "命中限流。可能是全局 API 限流、账户级限流或集成级限流。限流按账户聚合。",
+        "description": "触发频率限制（账户级限制或该接口的平台级上限）。请等待响应头 `Flashcat-Request-Rate-Limit-Delay` 给出的秒数后重试。",
         "content": {
           "application/json": {
             "schema": {
@@ -2516,6 +2619,15 @@
               }
             }
           }
+        },
+        "headers": {
+          "Flashcat-Request-Rate-Limit-Delay": {
+            "description": "距当前限流窗口重置的秒数。请求被网关全局保护限流拒绝时不返回该响应头。",
+            "schema": {
+              "type": "integer",
+              "minimum": 0
+            }
+          }
         }
       },
       "ServerError": {
@@ -2570,7 +2682,7 @@
           "account_id": {
             "type": "integer",
             "format": "uint64",
-            "description": "账户 ID。"
+            "description": "该条记录所属账户的 ID。"
           },
           "member_id": {
             "type": "integer",
@@ -2602,7 +2714,10 @@
             "description": "JSON 编码的请求体。包含敏感字段时整体改为 base64url 编码存储；超过 10 KB 时以截断占位说明替代。"
           },
           "params": {
-            "type": "array",
+            "type": [
+              "array",
+              "string"
+            ],
             "items": {
               "type": "object",
               "properties": {
@@ -2616,7 +2731,7 @@
                 }
               }
             },
-            "description": "URL 路径参数的键值对数组，无参数时为空数组。"
+            "description": "URL 路径参数，为 `Key`/`Value` 键值对数组（没有时为空数组）。部分部署形态会以 JSON 编码的字符串形式返回同一数组。"
           },
           "is_dangerous": {
             "type": "boolean",
@@ -2632,7 +2747,7 @@
               "member",
               "service"
             ],
-            "description": "调用方类型。`member` —— 成员会话；`service` —— App Key 凭据。"
+            "description": "调用方类型。`member`——成员或账户主体的会话；`service`——App Key，或签发给 AI SRE 的短期密钥。"
           },
           "credential_type": {
             "type": "string",
@@ -2710,7 +2825,7 @@
           },
           "limit": {
             "type": "integer",
-            "description": "分页大小，0–99。省略或传 0 表示不分页——返回时间窗内全部匹配记录。",
+            "description": "每页条数，0–99。不传或为 0 时由服务端决定每页条数（可能返回全部匹配条目）。",
             "minimum": 0,
             "maximum": 99,
             "example": 20
@@ -2787,7 +2902,7 @@
           },
           "message": {
             "type": "string",
-            "description": "用户可读的错误描述，语言会跟随调用方的 Accept-Language。可能包含字段名、ID 等请求上下文。",
+            "description": "按响应语言（query 参数 `locale` / `lang` 或请求头 `Accept-Language`）返回的错误描述，可能包含出错的字段名，请不要解析它。",
             "example": "The specified parameter template_id is not valid."
           }
         },
@@ -2798,7 +2913,7 @@
       },
       "ErrorCode": {
         "type": "string",
-        "description": "Flashduty 错误码枚举。每个失败响应的 `error.code` 都是下列稳定值之一，HTTP 状态码仅作参考。\n\n| 错误码 | HTTP | 含义 |\n|---|---|---|\n| `OK` | 200 | 保留值，正常错误响应不会返回。 |\n| `InvalidParameter` | 400 | 必填参数缺失或未通过校验。 |\n| `BadRequest` | 400 | 通用的 400 错误，通常是请求本身不合法。 |\n| `InvalidContentType` | 400 | 请求头 `Content-Type` 不是 `application/json`。 |\n| `ResourceNotFound` | 400 | 目标资源不存在。注意 HTTP 状态码是 400 而非 404（历史设计）。 |\n| `NoLicense` | 400 | 功能需要有效授权，但未找到可用的 license。 |\n| `ReferenceExist` | 400 | 该资源仍被其他实体引用，无法删除。 |\n| `Unauthorized` | 401 | `app_key` 缺失、无效或已过期。 |\n| `BalanceNotEnough` | 402 | 账户余额不足，无法执行需要计费的操作。 |\n| `AccessDenied` | 403 | 身份认证通过，但 RBAC 权限不足以执行该操作。 |\n| `RouteNotFound` | 404 | 请求的 URL 路径不是已知路由。 |\n| `MethodNotAllowed` | 405 | 当前路径不接受所使用的 HTTP 方法。 |\n| `UndonedOrderExist` | 409 | 账户存在未完成的订单，请稍后重试。 |\n| `RequestLocked` | 423 | 因连续失败被临时锁定。 |\n| `EntityTooLarge` | 413 | 请求体超过允许的最大长度。 |\n| `RequestTooFrequently` | 429 | 命中限流（全局、账户级或集成级）。 |\n| `RequestVerifyRequired` | 428 | 操作需要二次验证码，但未提供。 |\n| `DangerousOperation` | 428 | 危险操作，需要进行 MFA 验证。 |\n| `InternalError` | 500 | 服务端未预期错误。反馈问题请附上 `request_id`。 |\n| `ServiceUnavailable` | 503 | 后端依赖不可用，请稍后重试。 |",
+        "description": "错误码。所有失败响应都会把 `error.code` 设为下列稳定字符串之一，请以它而不是 HTTP 状态码做判断。\n\n| 错误码 | HTTP | 含义 |\n|---|---|---|\n| `OK` | 200 | 保留值，失败的请求不会返回。 |\n| `InvalidParameter` | 400 | 参数缺失、类型错误或未通过校验，`message` 通常会指出字段名。 |\n| `BadRequest` | 400 | 请求违反业务规则或与对象当前状态冲突，`message` 会说明原因。 |\n| `InvalidContentType` | 400 | 请求体没有以 `application/json` 发送。 |\n| `ResourceNotFound` | 400 | 引用的对象在本账户中不存在或已删除。注意 HTTP 状态码是 400 而不是 404。 |\n| `NoLicense` | 400 | 账户套餐不包含该功能、套餐配额已用完、套餐已过期或额度不足。 |\n| `ReferenceExist` | 400 | 对象仍被其他对象引用，无法删除。 |\n| `Unauthorized` | 401 | APP Key 缺失、无效或已删除。 |\n| `BalanceNotEnough` | 402 | 仅用于控制台计费流程，Open API 接口不会返回。 |\n| `AccessDenied` | 403 | APP Key 的权限范围或创建者角色不允许该操作或该对象。 |\n| `RouteNotFound` | 404 | 没有与该 HTTP 方法和路径匹配的接口。 |\n| `MethodNotAllowed` | 405 | 路径存在，但不支持该 HTTP 方法。 |\n| `UndonedOrderExist` | 409 | 仅用于控制台计费流程，Open API 接口不会返回。 |\n| `EntityTooLarge` | 413 | 请求体超出大小限制。 |\n| `RequestLocked` | 423 | 仅用于控制台登录保护，Open API 接口不会返回。 |\n| `RequestVerifyRequired` | 428 | 仅用于控制台验证码流程，Open API 接口不会返回。 |\n| `DangerousOperation` | 428 | 仅用于控制台高风险操作的 MFA 校验，Open API 接口不会返回。 |\n| `RequestTooFrequently` | 429 | 触发频率限制；请等待响应头 `Flashcat-Request-Rate-Limit-Delay` 给出的秒数后再重试。 |\n| `InternalError` | 500 | 服务端意外错误；请退避后重试，反馈问题时附上 `request_id`。 |\n| `ServiceUnavailable` | 503 | 后端依赖过载或不可用，请退避后重试。 |",
         "enum": [
           "OK",
           "InvalidParameter",
@@ -2813,35 +2928,35 @@
           "RouteNotFound",
           "MethodNotAllowed",
           "UndonedOrderExist",
-          "RequestLocked",
           "EntityTooLarge",
-          "RequestTooFrequently",
+          "RequestLocked",
           "RequestVerifyRequired",
           "DangerousOperation",
+          "RequestTooFrequently",
           "InternalError",
           "ServiceUnavailable"
         ],
         "x-enumDescriptions": {
-          "OK": "保留值，正常错误响应不会返回。",
-          "InvalidParameter": "必填参数缺失或未通过校验。",
-          "BadRequest": "通用的 400 错误，通常是请求本身不合法。",
-          "InvalidContentType": "请求头 `Content-Type` 不是 `application/json`。",
-          "ResourceNotFound": "目标资源不存在。注意 HTTP 状态码是 400 而非 404（历史设计）。",
-          "NoLicense": "功能需要有效授权，但未找到可用的 license。",
-          "ReferenceExist": "该资源仍被其他实体引用，无法删除。",
-          "Unauthorized": "`app_key` 缺失、无效或已过期。",
-          "BalanceNotEnough": "账户余额不足，无法执行需要计费的操作。",
-          "AccessDenied": "身份认证通过，但 RBAC 权限不足以执行该操作。",
-          "RouteNotFound": "请求的 URL 路径不是已知路由。",
-          "MethodNotAllowed": "当前路径不接受所使用的 HTTP 方法。",
-          "UndonedOrderExist": "账户存在未完成的订单，请稍后重试。",
-          "RequestLocked": "因连续失败被临时锁定。",
-          "EntityTooLarge": "请求体超过允许的最大长度。",
-          "RequestTooFrequently": "命中限流（全局、账户级或集成级）。",
-          "RequestVerifyRequired": "操作需要二次验证码，但未提供。",
-          "DangerousOperation": "危险操作，需要进行 MFA 验证。",
-          "InternalError": "服务端未预期错误。反馈问题请附上 `request_id`。",
-          "ServiceUnavailable": "后端依赖不可用，请稍后重试。"
+          "OK": "保留值，失败的请求不会返回。",
+          "InvalidParameter": "参数缺失、类型错误或未通过校验，`message` 通常会指出字段名。",
+          "BadRequest": "请求违反业务规则或与对象当前状态冲突，`message` 会说明原因。",
+          "InvalidContentType": "请求体没有以 `application/json` 发送。",
+          "ResourceNotFound": "引用的对象在本账户中不存在或已删除。注意 HTTP 状态码是 400 而不是 404。",
+          "NoLicense": "账户套餐不包含该功能、套餐配额已用完、套餐已过期或额度不足。",
+          "ReferenceExist": "对象仍被其他对象引用，无法删除。",
+          "Unauthorized": "APP Key 缺失、无效或已删除。",
+          "BalanceNotEnough": "仅用于控制台计费流程，Open API 接口不会返回。",
+          "AccessDenied": "APP Key 的权限范围或创建者角色不允许该操作或该对象。",
+          "RouteNotFound": "没有与该 HTTP 方法和路径匹配的接口。",
+          "MethodNotAllowed": "路径存在，但不支持该 HTTP 方法。",
+          "UndonedOrderExist": "仅用于控制台计费流程，Open API 接口不会返回。",
+          "EntityTooLarge": "请求体超出大小限制。",
+          "RequestLocked": "仅用于控制台登录保护，Open API 接口不会返回。",
+          "RequestVerifyRequired": "仅用于控制台验证码流程，Open API 接口不会返回。",
+          "DangerousOperation": "仅用于控制台高风险操作的 MFA 校验，Open API 接口不会返回。",
+          "RequestTooFrequently": "触发频率限制；请等待响应头 `Flashcat-Request-Rate-Limit-Delay` 给出的秒数后再重试。",
+          "InternalError": "服务端意外错误；请退避后重试，反馈问题时附上 `request_id`。",
+          "ServiceUnavailable": "后端依赖过载或不可用，请退避后重试。"
         },
         "example": "InvalidParameter"
       },
@@ -2875,7 +2990,7 @@
           },
           "email": {
             "type": "string",
-            "description": "邮箱地址。未提供 `phone` 时必填。"
+            "description": "邮箱地址，以小写存储。未提供 `phone` 时必填。"
           },
           "phone": {
             "type": "string",
@@ -2891,7 +3006,7 @@
               "type": "integer",
               "format": "uint64"
             },
-            "description": "授予的角色 ID 列表"
+            "description": "要分配的角色 ID：内置的 `2`（Admin）、`6`（Responder）、`8`（Viewer），或 `POST /role/list` 中的自定义角色 ID。不传时默认为 Viewer（`8`）；不存在的 ID 返回 `400`。"
           },
           "locale": {
             "type": "string",
@@ -2899,15 +3014,15 @@
               "zh-CN",
               "en-US"
             ],
-            "description": "语言。可选值：`zh-CN`（简体中文）、`en-US`（英文）；非法值返回 400。"
+            "description": "语言：`zh-CN`（简体中文）或 `en-US`（英文），其他值返回 400。不传时使用账户的语言设置。"
           },
           "time_zone": {
             "type": "string",
-            "description": "时区"
+            "description": "IANA 时区名称，如 `Asia/Shanghai`。不传则成员跟随账户时区；名称无效时返回 `400`。"
           },
           "ref_id": {
             "type": "string",
-            "description": "外部引用 ID"
+            "description": "外部引用 ID（如 HR 系统中的员工号），之后可在 `POST /member/delete`、`POST /member/info/reset` 中作为查找键。"
           }
         }
       },
@@ -2942,7 +3057,7 @@
           },
           "is_force": {
             "type": "boolean",
-            "description": "是否强制删除。默认 false，会检查成员是否被分派策略、值班表等资源引用；设为 true 则跳过引用检查直接删除",
+            "description": "跳过引用检查。为 false（默认）时，若成员属于某个团队、被分派策略指定或在值班表中，调用返回 `ReferenceExist`。强制删除不会移除这些引用。",
             "default": false
           }
         },
@@ -2991,11 +3106,11 @@
           "account_id": {
             "type": "integer",
             "format": "uint64",
-            "description": "账户 ID"
+            "description": "成员所属账户的 ID。"
           },
           "account_name": {
             "type": "string",
-            "description": "账户名称"
+            "description": "账户（组织）名称。"
           },
           "account_avatar": {
             "type": "string",
@@ -3003,7 +3118,7 @@
           },
           "account_email": {
             "type": "string",
-            "description": "账户邮箱"
+            "description": "账户主体的联系邮箱。"
           },
           "account_role_ids": {
             "type": "array",
@@ -3011,7 +3126,7 @@
               "type": "integer",
               "format": "uint64"
             },
-            "description": "授予的角色 ID 列表"
+            "description": "成员被分配的角色 ID，可通过 `POST /role/list` 解析。"
           },
           "account_locale": {
             "type": "string",
@@ -3019,16 +3134,20 @@
           },
           "account_time_zone": {
             "type": "string",
-            "description": "账户级时区（如 Asia/Shanghai）。账户未设置时不返回。"
+            "description": "账户设置的 IANA 时区；账户未设置时为空字符串。始终返回。"
+          },
+          "resolved_time_zone": {
+            "type": "string",
+            "description": "实际生效的时区：成员的 `time_zone` 有效时取它，否则取账户时区，再否则为 `Asia/Shanghai`。始终返回。"
           },
           "domain": {
             "type": "string",
-            "description": "账户域名"
+            "description": "账户域名，即登录控制台所用的子域名。"
           },
           "member_id": {
             "type": "integer",
             "format": "uint64",
-            "description": "成员 ID"
+            "description": "调用成员的 ID。"
           },
           "member_name": {
             "type": "string",
@@ -3064,7 +3183,7 @@
           },
           "time_zone": {
             "type": "string",
-            "description": "成员的 IANA 时区。成员未设置时不返回。"
+            "description": "成员自己设置的 IANA 时区；跟随账户时区时为空字符串。始终返回。"
           },
           "is_external": {
             "type": "boolean",
@@ -3077,7 +3196,10 @@
           },
           "mp_plat": {
             "type": "string",
-            "description": "账户来源的云市场平台。账户非来自云市场时不返回。"
+            "description": "账户开通来源的云市场：`aws`——AWS Marketplace。账户并非来自云市场时省略。",
+            "enum": [
+              "aws"
+            ]
           },
           "mp_account_id": {
             "type": "string",
@@ -3100,7 +3222,10 @@
           "country_code",
           "avatar",
           "is_external",
-          "created_at"
+          "created_at",
+          "time_zone",
+          "account_time_zone",
+          "resolved_time_zone"
         ]
       },
       "MemberInviteRequest": {
@@ -3129,11 +3254,14 @@
         "description": "邀请成员响应",
         "properties": {
           "items": {
-            "type": "array",
+            "type": [
+              "array",
+              "null"
+            ],
             "items": {
               "$ref": "#/components/schemas/NewMemberItem"
             },
-            "description": "新建的成员列表"
+            "description": "本次新建的成员；因已存在而跳过的条目不会列出。一个都没有创建时为 `null`。"
           }
         }
       },
@@ -3161,16 +3289,16 @@
           "account_id": {
             "type": "integer",
             "format": "uint64",
-            "description": "账户 ID"
+            "description": "成员所属账户的 ID。"
           },
           "member_id": {
             "type": "integer",
             "format": "uint64",
-            "description": "成员 ID"
+            "description": "成员 ID；在其他接口中同一值即人员 ID（如 `person_ids`）。"
           },
           "member_name": {
             "type": "string",
-            "description": "显示名称"
+            "description": "显示名称，在账户内唯一。"
           },
           "country_code": {
             "type": "string",
@@ -3178,40 +3306,39 @@
           },
           "phone": {
             "type": "string",
-            "description": "脱敏手机号"
+            "description": "E.164 格式的手机号，中间几位已打码（如 `+86151****6519`）；未设置时为空字符串。"
           },
           "email": {
             "type": "string",
-            "description": "邮箱地址"
+            "description": "邮箱地址（小写）；未设置时为空字符串。"
           },
           "locale": {
             "type": "string",
-            "description": "成员语言偏好（如 `zh-CN`）。为空时不返回——列表接口不填充该字段。"
+            "description": "语言偏好。`POST /member/list` 不填充该字段，因此始终省略。"
           },
           "time_zone": {
             "type": "string",
-            "description": "成员的 IANA 时区（如 `Asia/Shanghai`）。为空时不返回——列表接口不填充该字段。"
+            "description": "成员自己设置的 IANA 时区（如 `Asia/Shanghai`）。未设置时省略，表示跟随账户时区；生效时区可通过 `POST /member/info` 获取。"
           },
           "phone_verified": {
             "type": "boolean",
-            "description": "手机已验证"
+            "description": "成员已验证手机号时为 `true`。"
           },
           "email_verified": {
             "type": "boolean",
-            "description": "邮箱已验证"
+            "description": "成员已验证邮箱时为 `true`。"
           },
           "avatar": {
             "type": "string",
-            "description": "头像 URL"
+            "description": "头像图片 URL 或路径；未设置时为空字符串。"
           },
           "status": {
             "type": "string",
             "enum": [
               "enabled",
-              "pending",
-              "deleted"
+              "pending"
             ],
-            "description": "成员状态。`enabled` — 已激活成员；`pending` — 已邀请但尚未接受；`deleted` — 已从组织移除。"
+            "description": "成员状态。`enabled`——正常成员；`pending`——已邀请但尚未接受。已删除的成员不会列出。"
           },
           "account_role_ids": {
             "type": "array",
@@ -3219,15 +3346,15 @@
               "type": "integer",
               "format": "uint64"
             },
-            "description": "角色 ID 列表"
+            "description": "成员被分配的角色 ID：内置的 `2`（Admin）、`6`（Responder）、`8`（Viewer），或 `POST /role/list` 中的自定义角色 ID。"
           },
           "is_external": {
             "type": "boolean",
-            "description": "是否通过 SSO 创建"
+            "description": "成员通过单点登录同步创建（而非邀请或注册）时为 `true`。"
           },
           "ref_id": {
             "type": "string",
-            "description": "外部引用 ID"
+            "description": "外部引用 ID（如 HR 系统中的员工号）；未设置时为空字符串。"
           },
           "created_at": {
             "type": "integer",
@@ -3258,7 +3385,7 @@
           "p": {
             "type": "integer",
             "minimum": 1,
-            "description": "页码，从 1 开始"
+            "description": "页码，从 1 开始。默认第一页。"
           },
           "limit": {
             "type": "integer",
@@ -3281,7 +3408,7 @@
           },
           "query": {
             "type": "string",
-            "description": "按成员名称或邮箱做子串匹配；若可解析为手机号，则同时按手机号精确匹配"
+            "description": "搜索关键字。对成员名称或邮箱做子串匹配；纯数字关键字还会精确匹配成员 ID；能解析为手机号的关键字（不带 `+` 时按中国号码解析）还会精确匹配手机号。"
           }
         }
       },
@@ -3291,22 +3418,22 @@
         "properties": {
           "p": {
             "type": "integer",
-            "description": "当前页码"
+            "description": "请求中的页码；未传 `p` 时为 `0`（返回的是第一页）。"
           },
           "limit": {
             "type": "integer",
-            "description": "每页条数"
+            "description": "实际使用的每页条数；未传 `limit` 时为 100。"
           },
           "total": {
             "type": "integer",
-            "description": "总数"
+            "description": "符合筛选条件的成员总数（跨所有页）。"
           },
           "items": {
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/MemberItem"
             },
-            "description": "成员列表"
+            "description": "当前页的成员；没有匹配时为空数组。"
           }
         },
         "required": [
@@ -3396,7 +3523,7 @@
             ],
             "minLength": 2,
             "maxLength": 39,
-            "description": "新的显示名称。"
+            "description": "新的显示名称，2–39 个字符，在账户内唯一。"
           },
           "password": {
             "type": [
@@ -3410,7 +3537,7 @@
               "string",
               "null"
             ],
-            "description": "新的手机号；如不是 E.164 格式，可同时传 country_code。"
+            "description": "新的手机号；非 E.164 格式时请同时传 `country_code`。不能已属于其他成员；新号码会被标记为未验证（见 `from`）。"
           },
           "country_code": {
             "type": [
@@ -3424,7 +3551,7 @@
               "string",
               "null"
             ],
-            "description": "新的邮箱地址。"
+            "description": "新的邮箱地址。不能已属于其他成员；新地址会被标记为未验证（见 `from`）。"
           },
           "avatar": {
             "type": [
@@ -3450,14 +3577,14 @@
               "string",
               "null"
             ],
-            "description": "新的 IANA 时区名称，例如 Asia/Shanghai。"
+            "description": "新的 IANA 时区名称，如 `Asia/Shanghai`；传空字符串会清除该设置，使成员跟随账户时区。名称无效时返回 `400`。"
           },
           "ref_id": {
             "type": [
               "string",
               "null"
             ],
-            "description": "新的外部引用 ID。"
+            "description": "新的外部引用 ID；传空字符串会清空。"
           }
         }
       },
@@ -3472,7 +3599,7 @@
           "member_id": {
             "type": "integer",
             "format": "uint64",
-            "description": "成员 ID"
+            "description": "要修改角色的成员 ID（取自 `POST /member/list`）。"
           },
           "role_ids": {
             "type": "array",
@@ -3495,7 +3622,7 @@
           "member_id": {
             "type": "integer",
             "format": "uint64",
-            "description": "成员 ID"
+            "description": "要修改角色的成员 ID（取自 `POST /member/list`）。"
           },
           "role_ids": {
             "type": "array",
@@ -3517,7 +3644,7 @@
           "member_id": {
             "type": "integer",
             "format": "uint64",
-            "description": "成员 ID"
+            "description": "要修改角色的成员 ID（取自 `POST /member/list`）。"
           },
           "role_ids": {
             "type": "array",
@@ -3525,7 +3652,7 @@
               "type": "integer",
               "format": "uint64"
             },
-            "description": "新的角色 ID 集合，整体替换成员现有角色（非追加）；可通过 `POST /role/list` 获取，留空时重置为内置 Viewer 角色（ID 8）"
+            "description": "新的角色 ID 集合，整体替换成员现有角色（不是追加）。ID 可通过 `POST /role/list` 获取。"
           }
         }
       },
@@ -3536,11 +3663,11 @@
           "member_id": {
             "type": "integer",
             "format": "uint64",
-            "description": "成员 ID"
+            "description": "新建成员的 ID。"
           },
           "member_name": {
             "type": "string",
-            "description": "成员显示名称"
+            "description": "为成员保存的显示名称；未传 `member_name` 时取邮箱前缀。"
           }
         }
       },
@@ -3738,12 +3865,12 @@
           "account_id": {
             "type": "integer",
             "format": "uint64",
-            "description": "账户 ID"
+            "description": "人员所属账户的 ID。"
           },
           "person_id": {
             "type": "integer",
             "format": "uint64",
-            "description": "人员 ID"
+            "description": "人员 ID：账户主体为账户 ID，其他人为成员 ID。"
           },
           "person_name": {
             "type": "string",
@@ -3755,11 +3882,11 @@
           },
           "locale": {
             "type": "string",
-            "description": "语言。为空时不返回。"
+            "description": "语言偏好（`zh-CN` 或 `en-US`）。未设置时省略。"
           },
           "time_zone": {
             "type": "string",
-            "description": "时区。为空时不返回。"
+            "description": "IANA 时区设置：成员为其自己的设置，账户主体为账户设置。未设置时省略（未设置的成员跟随账户时区）。"
           },
           "email": {
             "type": "string",
@@ -3775,7 +3902,7 @@
           },
           "email_verified": {
             "type": "boolean",
-            "description": "邮箱已验证"
+            "description": "邮箱已验证时为 `true`；账户主体只要设置了邮箱即为 `true`。"
           },
           "as": {
             "type": "string",
@@ -3815,7 +3942,7 @@
               "type": "integer",
               "format": "uint64"
             },
-            "description": "要授予/撤销角色的成员 ID 列表。"
+            "description": "要授予或解除该角色的成员 ID（取自 `POST /member/list`）。必须全部是本账户成员，不能重复。"
           },
           "role_id": {
             "type": "integer",
@@ -3867,15 +3994,15 @@
           "role_id": {
             "type": "integer",
             "format": "uint64",
-            "description": "唯一角色 ID。"
+            "description": "角色 ID。内置角色使用固定 ID：`2`（Admin）、`6`（Responder）、`8`（Viewer）。"
           },
           "role_name": {
             "type": "string",
-            "description": "角色显示名称。"
+            "description": "角色名称，在账户内唯一。内置角色在所有语言下都命名为 `Admin`、`Responder`、`Viewer`。"
           },
           "description": {
             "type": "string",
-            "description": "角色描述。"
+            "description": "角色描述。内置角色的描述随请求语言本地化。"
           },
           "status": {
             "type": "string",
@@ -3883,7 +4010,7 @@
               "enabled",
               "disabled"
             ],
-            "description": "角色状态。"
+            "description": "角色状态。`enabled`——启用；`disabled`——已通过 `POST /role/disable` 禁用。内置角色始终为 `enabled`；已删除的角色不会返回。"
           },
           "permission_ids": {
             "type": "array",
@@ -3891,16 +4018,16 @@
               "type": "integer",
               "format": "uint64"
             },
-            "description": "该角色授予的权限 ID 列表。"
+            "description": "该角色授予的权限 ID，升序排列，可通过 `POST /role/permission/list` 解析。没有权限时为空数组。"
           },
           "editable": {
             "type": "boolean",
-            "description": "内置角色为 false，不可修改。"
+            "description": "内置角色（Admin、Responder、Viewer）为 `false`；自定义角色为 `true`。"
           },
           "created_at": {
             "type": "integer",
             "format": "int64",
-            "description": "创建时间（Unix 秒）。"
+            "description": "角色创建时间，Unix 时间戳（秒）。内置角色为固定值。"
           },
           "updated_at": {
             "type": "integer",
@@ -3941,7 +4068,7 @@
         "properties": {
           "total": {
             "type": "integer",
-            "description": "角色总数。"
+            "description": "返回的角色数：自定义角色数加上 3 个内置角色（`no_global` 为 true 时不含内置角色）。"
           },
           "items": {
             "type": "array",
@@ -3962,11 +4089,11 @@
               "type": "integer",
               "format": "uint64"
             },
-            "description": "按角色 ID 过滤，只返回这些角色已授予的权限。"
+            "description": "要返回或标记其已授予权限的角色 ID（内置或自定义）。不存在的 ID 会被忽略。"
           },
           "with_all": {
             "type": "boolean",
-            "description": "若为 true，返回所有权限并用 is_granted 标记哪些已授予。"
+            "description": "为 true 时返回全部权限，并用 `is_granted` 标记 `role_ids` 授予的权限。为 false（默认）时只返回已授予的权限。"
           }
         }
       },
@@ -3996,7 +4123,7 @@
           "role_id": {
             "type": "integer",
             "format": "uint64",
-            "description": "角色 ID，省略或置为 0 表示创建。"
+            "description": "要更新的自定义角色 ID。省略或置为 0 表示创建新角色。不要传内置角色 ID `2`、`6`、`8`。"
           },
           "role_name": {
             "type": "string",
@@ -4007,7 +4134,7 @@
           "description": {
             "type": "string",
             "maxLength": 499,
-            "description": "角色描述。"
+            "description": "角色描述，最多 499 个字符。更新时不传会清空原有描述。"
           },
           "permission_ids": {
             "type": "array",
@@ -4015,7 +4142,7 @@
               "type": "integer",
               "format": "uint64"
             },
-            "description": "要授予的权限 ID 列表，会替换现有权限集合。"
+            "description": "角色授予的权限 ID（取自 `POST /role/permission/list`）。整体替换原有权限；不传或传空数组会使角色没有任何权限。"
           }
         }
       },
@@ -4048,12 +4175,11 @@
             "example": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
           },
           "data": {
-            "description": "每个接口自己的业务 payload，详见各接口的 200 响应 schema。"
+            "description": "接口返回的数据，格式见各接口的 200 响应。没有返回数据的接口会返回 `{}` 或完全不带 `data`。"
           }
         },
         "required": [
-          "request_id",
-          "data"
+          "request_id"
         ]
       },
       "TeamBriefItem": {
@@ -4063,11 +4189,11 @@
           "team_id": {
             "type": "integer",
             "format": "uint64",
-            "description": "团队 ID。"
+            "description": "团队 ID，取自请求中的 `team_ids`。"
           },
           "team_name": {
             "type": "string",
-            "description": "团队名称。"
+            "description": "团队名称。结果包含已删除的团队，因此可能是已不在 `POST /team/list` 中出现的团队名称。"
           },
           "person_ids": {
             "type": "array",
@@ -4181,11 +4307,14 @@
         ],
         "properties": {
           "items": {
-            "type": "array",
+            "type": [
+              "array",
+              "null"
+            ],
             "items": {
               "$ref": "#/components/schemas/TeamBriefItem"
             },
-            "description": "按请求 `team_ids` 命中的团队简要信息数组；未命中任何 ID 时可能为 null。"
+            "description": "匹配到的团队简要信息（包括已删除的团队）；没有任何 ID 匹配时为 `null`。"
           }
         }
       },
@@ -4236,7 +4365,7 @@
           },
           "updated_by_name": {
             "type": "string",
-            "description": "最后修改人显示名称。"
+            "description": "最后编辑人的名称：成员名称；账户主体编辑时为账户名称；无法解析时为空字符串。"
           },
           "updated_by": {
             "type": "integer",
@@ -4268,7 +4397,7 @@
               "type": "integer",
               "format": "uint64"
             },
-            "description": "团队成员的成员 ID 列表。"
+            "description": "团队成员的人员 ID（即成员 ID；账户主体在团队中时为账户 ID）。团队没有成员时为空数组。"
           },
           "ref_id": {
             "type": "string",
@@ -4329,15 +4458,15 @@
         "properties": {
           "p": {
             "type": "integer",
-            "description": "当前页码。"
+            "description": "请求中的页码；未传 `p` 时为 `0`（返回的是第一页）。"
           },
           "limit": {
             "type": "integer",
-            "description": "本次使用的分页大小。"
+            "description": "实际使用的每页条数；未传 `limit` 时为 20。"
           },
           "total": {
             "type": "integer",
-            "description": "符合过滤条件的团队总数。"
+            "description": "符合筛选条件的未删除团队总数（跨所有页）。"
           },
           "items": {
             "type": "array",
@@ -4358,7 +4487,7 @@
           "team_id": {
             "type": "integer",
             "format": "uint64",
-            "description": "团队 ID，省略或置为 0 表示创建新团队。"
+            "description": "要更新的团队 ID。省略或置为 0 表示创建新团队；非 0 时必须是本账户已有团队的 ID。"
           },
           "team_name": {
             "type": "string",
@@ -4369,7 +4498,7 @@
           "description": {
             "type": "string",
             "maxLength": 500,
-            "description": "自定义描述。"
+            "description": "自由文本描述，最多 500 个字符。更新时不传会清空原有描述。"
           },
           "person_ids": {
             "type": "array",
@@ -4377,7 +4506,7 @@
               "type": "integer",
               "format": "uint64"
             },
-            "description": "设置为团队成员的成员 ID 列表，会替换现有成员列表。"
+            "description": "要加入团队的人员 ID（成员 ID；账户主体使用账户 ID）。与 `emails`、`phones` 合并后整体替换成员列表；不是本账户成员的 ID 会被忽略。"
           },
           "emails": {
             "type": "array",
@@ -4385,22 +4514,22 @@
               "type": "string",
               "format": "email"
             },
-            "description": "按邮箱匹配现有成员加入团队；未匹配到成员的地址会被静默忽略，不会发起邀请。"
+            "description": "要加入团队的已有成员邮箱，与 `person_ids`、`phones` 合并。匹配不到成员的邮箱会被忽略，不会发出邀请。"
           },
           "phones": {
             "type": "array",
             "items": {
               "type": "string"
             },
-            "description": "按手机号把已存在的成员加入团队。非 E.164 格式的号码会按 `countryCode` 解析；无法解析的号码导致整个请求返回 400。能解析但不属于任何现有成员的号码会被静默忽略。"
+            "description": "要加入团队的已有成员手机号，与 `person_ids`、`emails` 合并。不带 `+` 前缀的号码按 `countryCode` 解析；无法解析的号码会使整个请求返回 `400`，匹配不到成员的号码会被忽略。"
           },
           "countryCode": {
             "type": "string",
-            "description": "默认国家区号，用于 `phones` 中未采用 E.164 格式的手机号。"
+            "description": "`phones` 中不带 `+` 前缀号码的地区提示：ISO 3166-1 alpha-2 地区代码（如 `CN`，未传时默认）或数字区号（如 `86`）。"
           },
           "ref_id": {
             "type": "string",
-            "description": "供 HR 系统集成使用的外部引用 ID。"
+            "description": "外部引用 ID（如 HR 系统中的部门 ID），可在 `POST /team/info`、`POST /team/delete` 中作为查找键。更新时不传会清空原值。"
           },
           "reset_if_name_exist": {
             "type": "boolean",
@@ -4437,7 +4566,7 @@
           },
           "account_name": {
             "type": "string",
-            "description": "主体名称。"
+            "description": "在控制台中显示的账户（组织）名称。"
           },
           "domain": {
             "type": "string",
@@ -4468,11 +4597,11 @@
           },
           "locale": {
             "type": "string",
-            "description": "主体语言偏好（例如 zh-CN、en-US）。"
+            "description": "账户语言偏好（`zh-CN` 或 `en-US`）；未设置时为空字符串。"
           },
           "time_zone": {
             "type": "string",
-            "description": "主体默认时区（IANA 名称，例如 Asia/Shanghai）。"
+            "description": "账户默认时区（IANA 名称，如 `Asia/Shanghai`），未设置个人时区的成员跟随该时区。未设置时为空字符串。"
           },
           "created_at": {
             "type": "integer",
@@ -4484,18 +4613,24 @@
             "description": "账户访问限制。未配置时不返回。",
             "properties": {
               "ips": {
-                "type": "array",
+                "type": [
+                  "array",
+                  "null"
+                ],
                 "items": {
                   "type": "string"
                 },
-                "description": "允许的来源 IP/CIDR 白名单。"
+                "description": "允许访问本账户控制台和 API 的来源 IP 或 CIDR 网段；不限制时为 `null` 或空。"
               },
               "email_domains": {
-                "type": "array",
+                "type": [
+                  "array",
+                  "null"
+                ],
                 "items": {
                   "type": "string"
                 },
-                "description": "允许的登录邮箱域名。"
+                "description": "允许新成员使用的邮箱域名；邀请其他域名的地址会被拒绝。不限制时为 `null` 或空。"
               },
               "allow_subdomain": {
                 "type": "boolean",
@@ -4505,7 +4640,10 @@
           },
           "mp_plat": {
             "type": "string",
-            "description": "账户来源的云市场平台。账户非来自云市场时不返回。"
+            "description": "账户开通来源的云市场：`aws`——AWS Marketplace。账户并非来自云市场时省略。",
+            "enum": [
+              "aws"
+            ]
           },
           "mp_account_id": {
             "type": "string",
@@ -4541,7 +4679,7 @@
           "is_force": {
             "type": "boolean",
             "default": false,
-            "description": "为 false（默认）时，若仍有成员持有该角色，删除失败并返回 `ReferenceExist` 错误，`data.refs` 中列出持有成员；为 true 时先从所有持有成员解除该角色，再删除角色。"
+            "description": "为 false（默认）时，只要还有成员持有该角色，删除就会失败并返回 `ReferenceExist`，持有成员列在 `data.refs` 中。为 true 时，先从所有持有成员解除该角色再删除。不会跳过单点登录默认角色检查。"
           }
         }
       },
diff --git a/api-reference/rum.openapi.en.json b/api-reference/rum.openapi.en.json
index ea3b96477..66c46f870 100644
--- a/api-reference/rum.openapi.en.json
+++ b/api-reference/rum.openapi.en.json
@@ -41,7 +41,7 @@
             }
           }
         },
-        "description": "The app_key is valid but lacks permission for this operation."
+        "description": "The app_key is valid, but its permission scope or the creator's role does not allow this operation or object."
       },
       "NotFound": {
         "content": {
@@ -104,7 +104,16 @@
             }
           }
         },
-        "description": "Rate limit hit. Either the global API limit, a per-account limit, or a per-integration limit."
+        "description": "Rate limit hit (per-account limit or the operation's platform-wide limit). Wait for the number of seconds in `Flashcat-Request-Rate-Limit-Delay`, then retry.",
+        "headers": {
+          "Flashcat-Request-Rate-Limit-Delay": {
+            "description": "Seconds until the current rate-limit window resets. Absent when the request was rejected by the gateway's global protection limit.",
+            "schema": {
+              "type": "integer",
+              "minimum": 0
+            }
+          }
+        }
       },
       "Unauthorized": {
         "content": {
@@ -136,9 +145,9 @@
             "$ref": "#/components/schemas/ErrorCode"
           },
           "message": {
-            "description": "Human-readable error message, localized by the caller's Accept-Language. May contain field names, IDs, or other context from the failing request.",
-            "example": "The specified parameter template_id is not valid.",
-            "type": "string"
+            "type": "string",
+            "description": "Human-readable error message in the response language (`locale` / `lang` query parameter or `Accept-Language` header). May name the offending field; do not parse it.",
+            "example": "The specified parameter template_id is not valid."
           }
         },
         "required": [
@@ -148,12 +157,12 @@
         "type": "object"
       },
       "EmptyResponse": {
-        "description": "Empty response body. The server returns `data: null` on success.",
+        "description": "No payload. Depending on the operation, `data` is `{}` or omitted from the envelope; rely only on the HTTP 200 status and the absence of `error`.",
         "properties": {},
         "type": "object"
       },
       "ErrorCode": {
-        "description": "Flashduty error code enum. Every failed API response sets `error.code` to one of these stable wire strings. HTTP status is informational — the authoritative signal is the enum value.\n\n| Code | HTTP | Meaning |\n|---|---|---|\n| `OK` | 200 | Reserved — not returned on real errors. |\n| `InvalidParameter` | 400 | A required parameter is missing or failed validation. |\n| `BadRequest` | 400 | Generic 400 used when no more specific code fits. |\n| `InvalidContentType` | 400 | The `Content-Type` header is not `application/json`. |\n| `ResourceNotFound` | 400 | The referenced resource does not exist. Note: returned as HTTP 400, not 404 (historical choice). |\n| `NoLicense` | 400 | The feature is license-gated and no active license was found. |\n| `ReferenceExist` | 400 | Deletion blocked — other entities still reference this resource. |\n| `Unauthorized` | 401 | `app_key` is missing, invalid, or expired. |\n| `BalanceNotEnough` | 402 | Billing-gated operation with insufficient account balance. |\n| `AccessDenied` | 403 | Authenticated but lacking the permission required for this operation. |\n| `RouteNotFound` | 404 | The request URL path is not a known route. |\n| `MethodNotAllowed` | 405 | The HTTP method is not allowed on this otherwise-known path. |\n| `UndonedOrderExist` | 409 | An outstanding billing order blocks this new one. Wait and retry. |\n| `RequestLocked` | 423 | Operation temporarily locked due to repeated failures. |\n| `EntityTooLarge` | 413 | Request body exceeds the configured max size. |\n| `RequestTooFrequently` | 429 | Rate limit hit — API-global, per-account, or per-integration. |\n| `RequestVerifyRequired` | 428 | Second-factor verification required but not supplied. |\n| `DangerousOperation` | 428 | High-risk operation requires MFA verification. |\n| `InternalError` | 500 | Unhandled server-side error. Include `request_id` in the bug report. |\n| `ServiceUnavailable` | 503 | A backend dependency is unavailable. Try again later. |",
+        "description": "Error code. Every failed response sets `error.code` to one of these stable strings; branch on it rather than on the HTTP status.\n\n| Code | HTTP | Meaning |\n|---|---|---|\n| `OK` | 200 | Reserved; never returned on a failed request. |\n| `InvalidParameter` | 400 | A parameter is missing, has the wrong type, or failed validation; `message` usually names the field. |\n| `BadRequest` | 400 | The request breaks a business rule or conflicts with the current state of an object; `message` says which. |\n| `InvalidContentType` | 400 | The body is not sent as `application/json`. |\n| `ResourceNotFound` | 400 | The referenced object does not exist in this account or was deleted. Returned as HTTP 400, not 404. |\n| `NoLicense` | 400 | The account's plan does not include the feature, a plan quota is used up, the plan has expired, or credits are insufficient. |\n| `ReferenceExist` | 400 | The object is still referenced by other objects, so it cannot be deleted. |\n| `Unauthorized` | 401 | The APP Key is missing, invalid, or deleted. |\n| `BalanceNotEnough` | 402 | Console-only (billing); not returned by Open API operations. |\n| `AccessDenied` | 403 | The APP Key's permission scope or the creator's role does not allow this operation or object. |\n| `RouteNotFound` | 404 | No operation matches the HTTP method and path. |\n| `MethodNotAllowed` | 405 | The path exists but not for this HTTP method. |\n| `UndonedOrderExist` | 409 | Console-only (billing); not returned by Open API operations. |\n| `EntityTooLarge` | 413 | The request body exceeds the size limit. |\n| `RequestLocked` | 423 | Console-only (sign-in protection); not returned by Open API operations. |\n| `RequestVerifyRequired` | 428 | Console-only (verification code); not returned by Open API operations. |\n| `DangerousOperation` | 428 | Console-only (MFA for high-risk actions); not returned by Open API operations. |\n| `RequestTooFrequently` | 429 | A rate limit was hit; wait for the `Flashcat-Request-Rate-Limit-Delay` response header (seconds) before retrying. |\n| `InternalError` | 500 | Unexpected server error; retry with backoff and include `request_id` when reporting. |\n| `ServiceUnavailable` | 503 | A backend dependency is overloaded or unavailable; retry with backoff. |",
         "enum": [
           "OK",
           "InvalidParameter",
@@ -168,37 +177,37 @@
           "RouteNotFound",
           "MethodNotAllowed",
           "UndonedOrderExist",
-          "RequestLocked",
           "EntityTooLarge",
-          "RequestTooFrequently",
+          "RequestLocked",
           "RequestVerifyRequired",
           "DangerousOperation",
+          "RequestTooFrequently",
           "InternalError",
           "ServiceUnavailable"
         ],
         "example": "InvalidParameter",
         "type": "string",
         "x-enumDescriptions": {
-          "AccessDenied": "Authenticated but lacking the permission required for this operation.",
-          "BadRequest": "Generic 400 used when no more specific code fits.",
-          "BalanceNotEnough": "Billing-gated operation with insufficient account balance.",
-          "DangerousOperation": "High-risk operation requires MFA verification.",
-          "EntityTooLarge": "Request body exceeds the configured max size.",
-          "InternalError": "Unhandled server-side error. Include `request_id` in the bug report.",
-          "InvalidContentType": "The `Content-Type` header is not `application/json`.",
-          "InvalidParameter": "A required parameter is missing or failed validation.",
-          "MethodNotAllowed": "The HTTP method is not allowed on this otherwise-known path.",
-          "NoLicense": "The feature is license-gated and no active license was found.",
-          "OK": "Reserved — not returned on real errors.",
-          "ReferenceExist": "Deletion blocked — other entities still reference this resource.",
-          "RequestLocked": "Operation temporarily locked due to repeated failures.",
-          "RequestTooFrequently": "Rate limit hit — API-global, per-account, or per-integration.",
-          "RequestVerifyRequired": "Second-factor verification required but not supplied.",
-          "ResourceNotFound": "The referenced resource does not exist. Note: returned as HTTP 400, not 404 (historical choice).",
-          "RouteNotFound": "The request URL path is not a known route.",
-          "ServiceUnavailable": "A backend dependency is unavailable. Try again later.",
-          "Unauthorized": "`app_key` is missing, invalid, or expired.",
-          "UndonedOrderExist": "An outstanding billing order blocks this new one. Wait and retry."
+          "OK": "Reserved; never returned on a failed request.",
+          "InvalidParameter": "A parameter is missing, has the wrong type, or failed validation; `message` usually names the field.",
+          "BadRequest": "The request breaks a business rule or conflicts with the current state of an object; `message` says which.",
+          "InvalidContentType": "The body is not sent as `application/json`.",
+          "ResourceNotFound": "The referenced object does not exist in this account or was deleted. Returned as HTTP 400, not 404.",
+          "NoLicense": "The account's plan does not include the feature, a plan quota is used up, the plan has expired, or credits are insufficient.",
+          "ReferenceExist": "The object is still referenced by other objects, so it cannot be deleted.",
+          "Unauthorized": "The APP Key is missing, invalid, or deleted.",
+          "BalanceNotEnough": "Console-only (billing); not returned by Open API operations.",
+          "AccessDenied": "The APP Key's permission scope or the creator's role does not allow this operation or object.",
+          "RouteNotFound": "No operation matches the HTTP method and path.",
+          "MethodNotAllowed": "The path exists but not for this HTTP method.",
+          "UndonedOrderExist": "Console-only (billing); not returned by Open API operations.",
+          "EntityTooLarge": "The request body exceeds the size limit.",
+          "RequestLocked": "Console-only (sign-in protection); not returned by Open API operations.",
+          "RequestVerifyRequired": "Console-only (verification code); not returned by Open API operations.",
+          "DangerousOperation": "Console-only (MFA for high-risk actions); not returned by Open API operations.",
+          "RequestTooFrequently": "A rate limit was hit; wait for the `Flashcat-Request-Rate-Limit-Delay` response header (seconds) before retrying.",
+          "InternalError": "Unexpected server error; retry with backoff and include `request_id` when reporting.",
+          "ServiceUnavailable": "A backend dependency is overloaded or unavailable; retry with backoff."
         }
       },
       "ErrorResponse": {
@@ -242,7 +251,7 @@
         "description": "Get remote config request",
         "properties": {
           "application_id": {
-            "description": "RUM application ID.",
+            "description": "RUM application ID. Get application IDs via `POST /rum/application/list`.",
             "type": "string"
           }
         },
@@ -255,7 +264,15 @@
         "description": "Live remote configuration and its version.",
         "properties": {
           "config": {
-            "$ref": "#/components/schemas/RemoteConfig"
+            "anyOf": [
+              {
+                "$ref": "#/components/schemas/RemoteConfig"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "The live configuration (the newest published version). `null` when the application has never been configured."
           },
           "updated_at": {
             "description": "Unix timestamp in milliseconds - when the current version was published. 0 when never configured.",
@@ -267,13 +284,18 @@
             "type": "integer"
           }
         },
-        "type": "object"
+        "type": "object",
+        "required": [
+          "config",
+          "version",
+          "updated_at"
+        ]
       },
       "ListRemoteConfigHistoryRequest": {
         "description": "Remote configuration history request. Newest first by default.",
         "properties": {
           "application_id": {
-            "description": "RUM application ID.",
+            "description": "RUM application ID. Get application IDs via `POST /rum/application/list`.",
             "type": "string"
           },
           "asc": {
@@ -282,13 +304,12 @@
           },
           "limit": {
             "default": 20,
-            "description": "Page size. Default 20, max 100.",
-            "maximum": 100,
+            "description": "Page size. `0` or a negative value means 20; values above 100 are treated as 100.",
             "type": "integer"
           },
           "orderby": {
             "default": "updated_at",
-            "description": "Sort field. Default: `updated_at`.",
+            "description": "Sort field:\n\n- `updated_at`: publish time (default).\n- `version`: version number.\n\nAny other value falls back to `updated_at`.",
             "enum": [
               "updated_at",
               "version"
@@ -312,43 +333,49 @@
         "description": "Remote configuration history page.",
         "properties": {
           "has_next_page": {
-            "description": "Whether more pages remain.",
+            "description": "`true` when more versions remain after this page.",
             "type": "boolean"
           },
           "items": {
-            "description": "Version items, newest first by default.",
+            "description": "Versions on this page, newest first by default. Empty array when the application has never been configured.",
             "items": {
               "$ref": "#/components/schemas/RemoteConfigHistoryItem"
             },
             "type": "array"
           },
           "total": {
-            "description": "Total number of versions.",
+            "description": "Number of retained versions (at most 50).",
             "type": "integer"
           }
         },
-        "type": "object"
+        "type": "object",
+        "required": [
+          "total",
+          "has_next_page",
+          "items"
+        ]
       },
       "PreviewRemoteConfigRequest": {
         "description": "Preview request. Omit `config` to preview the currently live configuration.",
         "properties": {
           "app_version": {
-            "description": "App version the simulated client reports.",
+            "description": "App version the simulated client reports, compared exactly with rules' `match.app_version` (no range or prefix matching). Omitted = not reported.",
             "type": "string"
           },
           "application_id": {
-            "description": "RUM application ID.",
+            "description": "RUM application ID. Get application IDs via `POST /rum/application/list`.",
             "type": "string"
           },
           "config": {
-            "$ref": "#/components/schemas/RemoteConfig"
+            "$ref": "#/components/schemas/RemoteConfig",
+            "description": "Draft configuration to evaluate, validated like `POST /rum/application/remote-config/update`. Omit to evaluate the live configuration."
           },
           "env": {
-            "description": "Environment the simulated client reports.",
+            "description": "Environment the simulated client reports, compared exactly with rules' `match.env`. Omitted = not reported, so rules that test `env` cannot match.",
             "type": "string"
           },
           "sdk": {
-            "description": "SDK name and version the simulated client reports, e.g. `web@2.4.1`.",
+            "description": "SDK identifier the simulated client reports, e.g. `web@2.4.1`, compared exactly with rules' `match.sdk`. Omitted = not reported.",
             "type": "string"
           }
         },
@@ -361,14 +388,19 @@
         "description": "Values the simulated client would receive.",
         "properties": {
           "hit_rule_index": {
-            "description": "0-based index of the rule that decided the result, or -1 when only the default applied.",
+            "description": "0-based index into `config.rules` of the first rule that matched, or `-1` when no rule matched (only `default` applied) or the configuration is disabled or absent.",
             "type": "integer"
           },
           "values": {
-            "$ref": "#/components/schemas/RemoteConfigValues"
+            "$ref": "#/components/schemas/RemoteConfigValues",
+            "description": "`default` merged with the matching rule's `set`. Fields set by neither are omitted; an empty object means the client keeps all its init values."
           }
         },
-        "type": "object"
+        "type": "object",
+        "required": [
+          "values",
+          "hit_rule_index"
+        ]
       },
       "RemoteConfig": {
         "description": "The whole per-application remote configuration. A change reaches an SDK asynchronously and is applied when that SDK creates its next session, so a running session never flips a decision mid-flight.",
@@ -383,29 +415,35 @@
             "type": "string"
           },
           "custom": {
-            "additionalProperties": {},
-            "description": "Application-defined pass-through values handed to the host app verbatim. At most 5 keys, each key up to 64 bytes, each value up to 4 KB of JSON nested at most 3 levels, 16 KB in total. Anyone holding the public client token can read it.",
+            "additionalProperties": {
+              "description": "Any JSON value: string, number, boolean, array or object."
+            },
+            "description": "Free-form key/value map that SDKs hand to the host app verbatim; the platform does not interpret it. At most 5 keys, each key 1–64 bytes, each value valid JSON of at most 4 KB nested at most 3 levels, 16 KB in total. Anyone holding the public client token can read it. Omitted from responses when empty.",
             "maxProperties": 5,
             "type": "object"
           },
           "default": {
-            "$ref": "#/components/schemas/RemoteConfigValues"
+            "$ref": "#/components/schemas/RemoteConfigValues",
+            "description": "Values every client receives unless a matching rule overrides them."
           },
           "enabled": {
-            "description": "Kill switch. When false the engine reports no values at all and SDKs fall back to their init values.",
+            "description": "Kill switch. When `false` the SDK config endpoint returns no values and SDKs fall back to their init values; `default` and `rules` are kept. Treated as `false` when omitted.",
             "type": "boolean"
           },
           "refresh_on_foreground": {
-            "description": "Let clients re-check the configuration when they return to the foreground instead of waiting for the next poll.",
+            "description": "If `true`, clients re-check the configuration when they return to the foreground instead of waiting for the next poll. Default `false`; omitted from responses when `false`.",
             "type": "boolean"
           },
           "rules": {
-            "description": "Targeting rules, evaluated in order; at most 20 per application.",
+            "description": "Targeting rules, evaluated in order; the first match wins. At most 20. Can be `null` when the configuration was saved without rules.",
             "items": {
               "$ref": "#/components/schemas/RemoteConfigRule"
             },
             "maxItems": 20,
-            "type": "array"
+            "type": [
+              "array",
+              "null"
+            ]
           }
         },
         "type": "object"
@@ -414,18 +452,19 @@
         "description": "One published remote configuration version.",
         "properties": {
           "config": {
-            "$ref": "#/components/schemas/RemoteConfig"
+            "$ref": "#/components/schemas/RemoteConfig",
+            "description": "The configuration content that went live under this version."
           },
           "content_hash": {
-            "description": "Hash of the configuration content; lets the console identify versions with identical content.",
+            "description": "Fingerprint of the stored configuration: the first 16 hex characters of its SHA-256. Versions with equal hashes have identical content. Can be empty for older versions.",
             "type": "string"
           },
           "equivalent_to": {
-            "description": "Earliest version carrying the same content, when that is not this version itself.",
+            "description": "Earliest retained version with the same `content_hash`, e.g. the version a revert restored. Omitted when this version is itself the earliest.",
             "type": "integer"
           },
           "reason": {
-            "description": "Operator's note left when the version was published. Empty when none was given.",
+            "description": "Free-text note (not an enum) sent as `reason` when the version was published or reverted; `\"\"` when none was given.",
             "type": "string"
           },
           "updated_at": {
@@ -439,7 +478,7 @@
             "type": "integer"
           },
           "updated_by_name": {
-            "description": "Name of the member who published the version.",
+            "description": "Name of the member who published the version at publish time, truncated to 128 characters.",
             "type": "string"
           },
           "version": {
@@ -447,18 +486,35 @@
             "type": "integer"
           }
         },
-        "type": "object"
+        "type": "object",
+        "required": [
+          "config",
+          "version",
+          "content_hash",
+          "reason",
+          "updated_by",
+          "updated_by_name",
+          "updated_at"
+        ]
       },
       "RemoteConfigRule": {
-        "description": "One targeting rule: when `match` holds, `set` overrides `default`. The first matching rule wins and evaluation stops there - rule order is the priority.",
+        "description": "One targeting rule: when every `match` condition holds, `set` overrides `default`. The first matching rule wins and evaluation stops there; rule order is the priority. `set` must set at least one value.",
         "properties": {
           "match": {
             "additionalProperties": {
               "maxLength": 256,
+              "minLength": 1,
               "type": "string"
             },
-            "description": "Key/value conditions the SDK's config request must equal. Keys are limited to `env`, `app_version` and `sdk`; values are at most 256 bytes.",
+            "description": "Conditions on what the SDK reports in its config request, combined with AND and compared as exact strings. Keys are limited to `env`, `app_version` and `sdk`; values are 1–256 bytes. A key the SDK does not report never matches.",
             "minProperties": 1,
+            "propertyNames": {
+              "enum": [
+                "env",
+                "app_version",
+                "sdk"
+              ]
+            },
             "type": "object"
           },
           "set": {
@@ -475,7 +531,7 @@
         "description": "The SDK knobs a configuration can set. Every field is optional: a value absent from both rule and default is omitted from the SDK response, which tells the SDK to keep its init value.",
         "properties": {
           "defaultPrivacyLevel": {
-            "description": "How Session Replay masks a page by default.",
+            "description": "How Session Replay masks a page by default:\n\n- `mask`: replaces text and hides input values.\n- `mask-user-input`: keeps page text but hides what users type.\n- `allow`: records the page as it is; content already uploaded cannot be masked later.",
             "enum": [
               "mask",
               "mask-user-input",
@@ -501,7 +557,7 @@
             ]
           },
           "sessionReplaySampleRate": {
-            "description": "Session Replay sampling rate (0-100).",
+            "description": "Percentage of sessions that record Session Replay (0–100).",
             "maximum": 100,
             "minimum": 0,
             "type": [
@@ -510,7 +566,7 @@
             ]
           },
           "sessionSampleRate": {
-            "description": "Session sampling rate (0-100).",
+            "description": "Percentage of sessions collected (0–100).",
             "maximum": 100,
             "minimum": 0,
             "type": [
@@ -519,7 +575,7 @@
             ]
           },
           "traceSampleRate": {
-            "description": "Trace sampling rate (0-100): which sessions inject trace headers into their requests.",
+            "description": "Percentage of sessions that inject trace headers into their requests (0–100). Decided per session: a session traces all of its requests or none.",
             "maximum": 100,
             "minimum": 0,
             "type": [
@@ -534,16 +590,16 @@
         "description": "Republish an earlier version's content under a new version number.",
         "properties": {
           "application_id": {
-            "description": "RUM application ID.",
+            "description": "RUM application ID. Get application IDs via `POST /rum/application/list`.",
             "type": "string"
           },
           "reason": {
-            "description": "Operator's note. The console fills in `rolled back to vN` when left empty.",
+            "description": "Optional free-text note (not an enum), at most 255 characters, stored verbatim and returned as `reason` by `POST /rum/application/remote-config/history/list`. The server does not fill it in when omitted.",
             "maxLength": 255,
             "type": "string"
           },
           "version": {
-            "description": "History version to republish.",
+            "description": "Version to restore. Must be one of the retained versions listed by `POST /rum/application/remote-config/history/list`.",
             "minimum": 1,
             "type": "integer"
           }
@@ -558,7 +614,7 @@
         "description": "Version created by the revert.",
         "properties": {
           "version": {
-            "description": "New version number created by the revert.",
+            "description": "New version number created by the revert (previous highest version + 1).",
             "type": "integer"
           }
         },
@@ -568,12 +624,15 @@
         "description": "Alert settings for the application.",
         "properties": {
           "channel_ids": {
-            "description": "Channel IDs to send alerts to. Used only when `delivery_mode` is `oncall`.",
+            "description": "On-call channel IDs that receive the alerts; used only when `delivery_mode` is `oncall`. Kept as a draft in `webhook` mode. Can be `null` when never set.",
             "items": {
               "format": "int64",
               "type": "integer"
             },
-            "type": "array"
+            "type": [
+              "array",
+              "null"
+            ]
           },
           "delivery_mode": {
             "description": "Alert delivery channel: `oncall` routes alert events through Flashduty On-call, `webhook` POSTs them directly to `webhook_url`. An empty value is treated as `oncall`, and on create/update it is persisted as the deployment default (`webhook` on RUM-only on-premises deployments, `oncall` otherwise). Omitted when empty (legacy rows).",
@@ -584,7 +643,7 @@
             "type": "string"
           },
           "enabled": {
-            "description": "Whether alerting is enabled.",
+            "description": "Whether alerting is on. `false` turns alerting off; with `false`, `webhook_url` is not checked.",
             "type": "boolean"
           },
           "integration_id": {
@@ -593,7 +652,7 @@
             "type": "integer"
           },
           "webhook_url": {
-            "description": "URL that receives alert events when `delivery_mode` is `webhook`; required in that mode, ignored otherwise. Omitted when empty.",
+            "description": "URL that receives alert events when `delivery_mode` is `webhook`. Required in that mode while `enabled` is `true`; must use `http` or `https`, and on Flashduty cloud must not resolve to a private, loopback, link-local or reserved address. Ignored in `oncall` mode. Omitted from responses when empty.",
             "format": "uri",
             "type": "string"
           }
@@ -617,7 +676,7 @@
             "type": "string"
           },
           "is_private": {
-            "description": "Restrict access to team members only.",
+            "description": "If `true`, only the account owner, account admins, the creator and members of the owning team can see or edit the application. Default `false`.",
             "type": "boolean"
           },
           "links": {
@@ -633,11 +692,11 @@
             "description": "Source code repositories to link, in order; the first entry is the primary repository. At most 10 entries."
           },
           "no_geo": {
-            "description": "Do not infer geographic location.",
+            "description": "If `true`, geographic location is not inferred from the client IP. Default `false`.",
             "type": "boolean"
           },
           "no_ip": {
-            "description": "Do not collect IP addresses.",
+            "description": "If `true`, client IP addresses are not collected. Default `false`.",
             "type": "boolean"
           },
           "team_id": {
@@ -648,7 +707,7 @@
           },
           "tracing": {
             "$ref": "#/components/schemas/RumApplicationTracing",
-            "description": "Optional APM tracing integration configuration."
+            "description": "Optional APM tracing integration configuration. Stored as empty (`enabled: false`, empty `open_type` and `endpoint`) when omitted."
           },
           "type": {
             "description": "Platform identifier:\n\n| Value | Meaning |\n|---|---|\n| `browser` | Web browser application (JavaScript SDK) |\n| `ios` | Apple iOS application |\n| `android` | Android application |\n| `react-native` | React Native application |\n| `flutter` | Flutter application |\n| `kotlin-multiplatform` | Kotlin Multiplatform application |\n| `roku` | Roku channel application |\n| `unity` | Unity application |\n| `miniprogram` | WeChat mini program |\n| `harmony` | HarmonyOS application |\n| `electron` | Electron desktop application |",
@@ -679,7 +738,7 @@
         "description": "Result of creating a RUM application.",
         "properties": {
           "application_id": {
-            "description": "Auto-generated unique application ID.",
+            "description": "Server-generated application ID (22-character short UUID); pass it as `application_id` to the other application operations.",
             "type": "string"
           },
           "application_name": {
@@ -687,11 +746,16 @@
             "type": "string"
           },
           "client_token": {
-            "description": "Token for RUM SDK initialization.",
+            "description": "Token used to initialize the RUM SDK. Also returned by `POST /rum/application/info`.",
             "type": "string"
           }
         },
-        "type": "object"
+        "type": "object",
+        "required": [
+          "application_id",
+          "application_name",
+          "client_token"
+        ]
       },
       "RumApplicationIDRequest": {
         "description": "Request with a single application ID.",
@@ -710,7 +774,7 @@
         "description": "Batch application info request.",
         "properties": {
           "application_ids": {
-            "description": "Up to 200 application IDs. Get IDs via `POST /rum/application/list`.",
+            "description": "Up to 200 application IDs. Duplicates are collapsed, and unknown or deleted IDs are skipped. Get IDs via `POST /rum/application/list`.",
             "items": {
               "type": "string"
             },
@@ -727,26 +791,29 @@
         "description": "Batch application info response.",
         "properties": {
           "items": {
-            "description": "Application info items matching the requested `application_ids` (max 200, deduplicated).",
+            "description": "Applications found among the requested `application_ids`, in no guaranteed order. Empty array when none match.",
             "items": {
               "$ref": "#/components/schemas/RumApplicationItem"
             },
             "type": "array"
           }
         },
-        "type": "object"
+        "type": "object",
+        "required": [
+          "items"
+        ]
       },
       "RumApplicationItem": {
         "description": "A RUM application.",
         "properties": {
           "account_id": {
-            "description": "Account ID.",
+            "description": "ID of the Flashduty account that owns the application.",
             "format": "int64",
             "type": "integer"
           },
           "alerting": {
             "$ref": "#/components/schemas/RumApplicationAlerting",
-            "description": "Alerting configuration of the application."
+            "description": "Alerting configuration of the application. Always an object."
           },
           "application_id": {
             "description": "Unique application ID.",
@@ -766,17 +833,17 @@
             "type": "integer"
           },
           "created_by": {
-            "description": "Creator member ID.",
+            "description": "Member ID of the creator. The creator can always edit the application.",
             "format": "int64",
             "type": "integer"
           },
           "is_private": {
-            "description": "If `true`, the application is only accessible to team members.",
+            "description": "If `true`, only the account owner, account admins, the creator and members of the owning team can see or edit the application.",
             "type": "boolean"
           },
           "links": {
             "$ref": "#/components/schemas/RumApplicationLinks",
-            "description": "External-link integration configuration."
+            "description": "External-link integration configuration. Always an object; `systems` can be `null` when no system was ever saved."
           },
           "repositories": {
             "type": "array",
@@ -784,7 +851,7 @@
               "$ref": "#/components/schemas/RumApplicationRepository"
             },
             "maxItems": 10,
-            "description": "Linked source code repositories, in order; the first entry is the primary repository. Linking grants no access by itself: AI sessions can only read repositories granted to the account's GitHub App installations."
+            "description": "Linked source code repositories, in order; the first entry is the primary repository. Empty array when none are linked. Linking grants no access by itself: AI sessions can only read repositories granted to the account's GitHub App installations."
           },
           "no_geo": {
             "description": "If `true`, geographic location is not inferred from IP.",
@@ -795,7 +862,7 @@
             "type": "boolean"
           },
           "status": {
-            "description": "Application status. One of `enabled` (active, receiving data), `disabled` (deactivated), `deleted` (soft-delete marker; every query filters it out, so it never actually appears in responses).",
+            "description": "Application status:\n\n- `enabled`: the SDK `client_token` is accepted and data is collected. Every application created through the API starts in this state.\n- `disabled`: the `client_token` is rejected, so no new data is collected. No public operation sets this status.\n- `deleted`: soft-delete marker; deleted applications are filtered out of every response, so this value is never returned.",
             "enum": [
               "enabled",
               "disabled",
@@ -804,13 +871,13 @@
             "type": "string"
           },
           "team_id": {
-            "description": "Owning team ID.",
+            "description": "Owning team ID. Members of this team can edit the application and, when it is private, see it.",
             "format": "int64",
             "type": "integer"
           },
           "tracing": {
             "$ref": "#/components/schemas/RumApplicationTracing",
-            "description": "APM tracing integration configuration."
+            "description": "APM tracing integration configuration. Always an object; when tracing was never configured it is `enabled: false` with empty `open_type` and `endpoint`."
           },
           "type": {
             "description": "Platform identifier:\n\n| Value | Meaning |\n|---|---|\n| `browser` | Web browser application (JavaScript SDK) |\n| `ios` | Apple iOS application |\n| `android` | Android application |\n| `react-native` | React Native application |\n| `flutter` | Flutter application |\n| `kotlin-multiplatform` | Kotlin Multiplatform application |\n| `roku` | Roku channel application |\n| `unity` | Unity application |\n| `miniprogram` | WeChat mini program |\n| `harmony` | HarmonyOS application |\n| `electron` | Electron desktop application |",
@@ -840,13 +907,33 @@
             "type": "integer"
           }
         },
-        "type": "object"
+        "type": "object",
+        "required": [
+          "account_id",
+          "application_id",
+          "application_name",
+          "type",
+          "client_token",
+          "team_id",
+          "is_private",
+          "no_ip",
+          "no_geo",
+          "alerting",
+          "tracing",
+          "links",
+          "repositories",
+          "status",
+          "created_by",
+          "updated_by",
+          "created_at",
+          "updated_at"
+        ]
       },
       "RumApplicationLink": {
         "description": "External system link rendered on matching RUM event detail pages.",
         "properties": {
           "enabled": {
-            "description": "Whether this external system link is enabled.",
+            "description": "Whether this external system link is shown. Treated as `false` when omitted.",
             "type": "boolean"
           },
           "event_types": {
@@ -867,15 +954,15 @@
             "type": "array"
           },
           "icon_color": {
-            "description": "Display color for the link icon.",
+            "description": "Display color for the link icon, e.g. `#0F766E`. Omitted from responses when empty.",
             "type": "string"
           },
           "icon_text": {
-            "description": "Short text shown in the link icon.",
+            "description": "Short text shown in the link icon, e.g. `S3`. Omitted from responses when empty.",
             "type": "string"
           },
           "id": {
-            "description": "Stable client-side identifier for this external system.",
+            "description": "Client-chosen identifier for this external system, kept as sent; the server does not validate it.",
             "type": "string"
           },
           "name": {
@@ -900,7 +987,7 @@
         "description": "External link integration settings for the application.",
         "properties": {
           "enabled": {
-            "description": "Whether external link integration is enabled.",
+            "description": "Master switch for the external-link integration. Treated as `false` when omitted.",
             "type": "boolean"
           },
           "systems": {
@@ -923,11 +1010,11 @@
         "description": "Filters for listing RUM applications.",
         "properties": {
           "asc": {
-            "description": "Sort ascending if `true`.",
+            "description": "Sort ascending if `true`; default `false` (descending).",
             "type": "boolean"
           },
           "is_my_team": {
-            "description": "If `true`, return only applications belonging to the current user's teams.",
+            "description": "If `true`, return only applications owned by teams the caller belongs to. Has no effect when the caller belongs to no team.",
             "type": "boolean"
           },
           "limit": {
@@ -950,7 +1037,7 @@
             "type": "integer"
           },
           "query": {
-            "description": "Substring match on the application name.",
+            "description": "Substring match on the application name (SQL `LIKE`, so `%` and `_` act as wildcards).",
             "type": "string"
           },
           "team_id": {
@@ -969,7 +1056,7 @@
             "type": "boolean"
           },
           "items": {
-            "description": "RUM applications of the current page.",
+            "description": "RUM applications on the current page. Empty array when nothing matches.",
             "items": {
               "$ref": "#/components/schemas/RumApplicationItem"
             },
@@ -980,24 +1067,30 @@
             "type": "integer"
           }
         },
-        "type": "object"
+        "type": "object",
+        "required": [
+          "has_next_page",
+          "total",
+          "items"
+        ]
       },
       "RumApplicationTracing": {
         "description": "APM tracing integration settings.",
         "properties": {
           "enabled": {
-            "description": "Whether tracing integration is enabled.",
+            "description": "Whether trace links are shown on RUM events.",
             "type": "boolean"
           },
           "endpoint": {
-            "description": "Trace endpoint URL (http or https).",
+            "description": "Trace endpoint URL; must start with `http` or `https`. Required whenever `tracing` is sent, even with `enabled: false`. Empty in responses when tracing was never configured.",
             "type": "string"
           },
           "open_type": {
-            "description": "How to open the trace link. One of `popup` (open trace details in a popup) or `tab` (open in a new browser tab).",
+            "description": "How the trace link opens:\n\n- `popup`: open trace details in a popup.\n- `tab`: open them in a new browser tab.\n- `\"\"` (empty): returned only when tracing was never configured; rejected in requests.",
             "enum": [
               "popup",
-              "tab"
+              "tab",
+              ""
             ],
             "type": "string"
           }
@@ -1014,7 +1107,7 @@
         "properties": {
           "alerting": {
             "$ref": "#/components/schemas/RumApplicationAlerting",
-            "description": "Alerting configuration. Omit to leave unchanged.",
+            "description": "Alerting configuration. When sent, it replaces the stored alerting object (except `integration_id`, which the server manages). Omit to leave unchanged.",
             "x-flashduty-preserve-absence": true
           },
           "application_id": {
@@ -1031,7 +1124,7 @@
             ]
           },
           "is_private": {
-            "description": "Restrict access to members of the owning team; `false` explicitly makes the application public. Omit to leave unchanged.",
+            "description": "`true` limits access to the account owner, account admins, the creator and members of the owning team; `false` makes the application visible to everyone in the account. Omit to leave unchanged.",
             "type": [
               "boolean",
               "null"
@@ -1039,7 +1132,7 @@
           },
           "links": {
             "$ref": "#/components/schemas/RumApplicationLinks",
-            "description": "External-link integration configuration. Omit to leave unchanged.",
+            "description": "External-link integration configuration. When sent, it replaces the stored object, including the whole `systems` list. Omit to leave unchanged.",
             "x-flashduty-preserve-absence": true
           },
           "repositories": {
@@ -1066,7 +1159,7 @@
             ]
           },
           "team_id": {
-            "description": "Owning team ID. Get team IDs via `POST /team/list`. Omit to leave unchanged.",
+            "description": "New owning team ID. Get team IDs via `POST /team/list`. Omit to leave unchanged. Moving the application to another team changes who can edit it.",
             "exclusiveMinimum": 0,
             "format": "int64",
             "type": [
@@ -1076,7 +1169,7 @@
           },
           "tracing": {
             "$ref": "#/components/schemas/RumApplicationTracing",
-            "description": "APM tracing integration configuration. Omit to leave unchanged."
+            "description": "APM tracing integration configuration. When sent, it replaces the stored object and must carry a valid `open_type` and `endpoint`. Omit to leave unchanged."
           },
           "type": {
             "description": "Application type. Omit to leave unchanged. Platform identifier:\n\n| Value | Meaning |\n|---|---|\n| `browser` | Web browser application (JavaScript SDK) |\n| `ios` | Apple iOS application |\n| `android` | Android application |\n| `react-native` | React Native application |\n| `flutter` | Flutter application |\n| `kotlin-multiplatform` | Kotlin Multiplatform application |\n| `roku` | Roku channel application |\n| `unity` | Unity application |\n| `miniprogram` | WeChat mini program |\n| `harmony` | HarmonyOS application |\n| `electron` | Electron desktop application |",
@@ -1108,15 +1201,15 @@
         "description": "Metadata for one returned column.",
         "properties": {
           "name": {
-            "description": "Column name.",
+            "description": "Column name or alias as written in `sql`; `ts` for the bucket column of `time_series` queries.",
             "type": "string"
           },
           "nullable": {
-            "description": "Whether values in this column may be null.",
+            "description": "Whether values in this column may be `null`. `true` when the driver cannot tell.",
             "type": "boolean"
           },
           "type": {
-            "description": "Backend database type name for this column.",
+            "description": "Column type name as reported by the database driver, such as `VARCHAR`, `BIGINT`, `DOUBLE` or `DATETIME`. It depends on the selected column or expression, so the set is open; use it as a hint for parsing `values`.",
             "type": "string"
           }
         },
@@ -1131,11 +1224,11 @@
         "description": "One RUM data query definition.",
         "properties": {
           "disable_sampling": {
-            "description": "When true, asks the query engine to avoid sampling when possible.",
+            "description": "When `true`, the query always runs on the full data and the response never carries `sampling`. When `false` (default), the server may sample aggregate queries over large time windows.",
             "type": "boolean"
           },
           "dql": {
-            "description": "Optional RUM DQL filter expression used together with SQL validation.",
+            "description": "Optional RUM DQL filter. It is translated and `AND`-ed into the `WHERE` clause of `sql`. A DQL parse error is reported in this query's `error` entry.",
             "type": "string"
           },
           "format": {
@@ -1153,28 +1246,28 @@
           },
           "interval": {
             "default": 3600,
-            "description": "Time bucket interval in seconds for `time_series` queries.",
+            "description": "Minimum time-bucket width in **milliseconds** for `time_series` queries. Default 3600 (3.6 seconds). The effective width is the smallest step of a fixed ladder that is at least this value and at least the window length divided by `max_points`; it is returned as `interval`. Ignored for `table` queries.",
             "exclusiveMinimum": 0,
             "format": "int64",
             "type": "integer"
           },
           "max_points": {
             "default": 1226,
-            "description": "Maximum number of points for `time_series` queries.",
+            "description": "Upper bound on the number of buckets for `time_series` queries. Default 1226. The bucket width grows so that the window holds at most this many buckets. Ignored for `table` queries.",
             "exclusiveMinimum": 0,
             "format": "int64",
             "type": "integer"
           },
           "search_after_ctx": {
-            "description": "Opaque cursor returned by a previous table query for continuing pagination.",
+            "description": "Cursor from a previous response's `search_after_ctx`, to fetch the next page of the same `table` query. Only used by non-aggregate queries with `ORDER BY` and no `OFFSET`. An invalid value makes this query fail.",
             "type": "string"
           },
           "sql": {
-            "description": "RUM SQL query to execute.",
+            "description": "RUM SQL `SELECT` statement. `FROM` names a scope table (`sessions`, `views`, `actions`, `errors`, `resources`, `long_tasks`, `vitals`, `issues`, `sourcemaps`); columns are `field_key` values from `POST /rum/field/list`. The server adds the account and time-range filters.",
             "type": "string"
           },
           "time_zone": {
-            "description": "IANA time zone name used when evaluating time functions, such as `Asia/Shanghai`.",
+            "description": "IANA time zone name, such as `Asia/Shanghai`, used to align `time_series` bucket boundaries to local time. Defaults to UTC alignment. Ignored for `table` queries; an unknown name fails the request with `InvalidParameter`.",
             "type": "string"
           }
         },
@@ -1194,7 +1287,7 @@
           },
           "error": {
             "$ref": "#/components/schemas/DutyError",
-            "description": "Subquery failure details. Omitted when the query succeeded."
+            "description": "Set when this query failed after request validation (unknown table or column, invalid `dql` or `search_after_ctx`, database error). The code is always `InternalError`. Omitted when the query succeeded."
           }
         },
         "type": "object"
@@ -1242,14 +1335,14 @@
         "description": "Rows and metadata returned by one RUM data query.",
         "properties": {
           "fields": {
-            "description": "Column metadata for the values matrix.",
+            "description": "Column metadata, one entry per returned column, in the same order as `values`. For `time_series` queries the first column is `ts`.",
             "items": {
               "$ref": "#/components/schemas/RumDataFieldMeta"
             },
             "type": "array"
           },
           "interval": {
-            "description": "Effective time bucket interval in seconds. Omitted for `table`-format queries.",
+            "description": "Effective time-bucket width in **milliseconds** used by a `time_series` query. Omitted for `table` queries.",
             "format": "int64",
             "type": "integer"
           },
@@ -1258,14 +1351,17 @@
             "description": "Sampling metadata. Omitted when the query did not use sampling."
           },
           "search_after_ctx": {
-            "description": "Opaque cursor for continuing paginated table queries. Omitted when the query is not a cursor-paginated table query or no further pages exist.",
+            "description": "Cursor for the next page of a non-aggregate `table` query with `ORDER BY` and no `OFFSET`. Present only when this page returned as many rows as the `LIMIT`; omitted otherwise.",
             "type": "string"
           },
           "values": {
-            "description": "Rows returned by the query. Each row aligns with `fields` by index.",
+            "description": "Result values in column-major order: `values[i]` is the list of every row's value for column `fields[i]`. A column is `null` when the query returned no rows. Datetime values are returned as RFC 3339 strings.",
             "items": {
               "items": {},
-              "type": "array"
+              "type": [
+                "array",
+                "null"
+              ]
             },
             "type": "array"
           }
@@ -1284,7 +1380,7 @@
             "type": "boolean"
           },
           "scale_factor": {
-            "description": "Multiplier used to scale sampled counts back to estimated full counts.",
+            "description": "Multiplier applied to scale sampled results back to estimated full values. `COUNT`, `SUM` and `COUNT(DISTINCT)` columns in `values` are already multiplied by it; other aggregates are returned as computed on the sample.",
             "type": "number"
           }
         },
@@ -1302,13 +1398,13 @@
             "type": "string"
           },
           "description": {
-            "description": "Rule description, up to 512 characters.",
+            "description": "Rule description, up to 512 characters. Defaults to an empty string.",
             "maxLength": 512,
             "type": "string"
           },
           "filters": {
             "$ref": "#/components/schemas/RumErrorIngestionOrFilters",
-            "description": "Filter conditions (OR-of-ANDs) to match errors; matched errors are dropped and not ingested."
+            "description": "Conditions (OR-of-ANDs) that select errors. A matched error is still stored but is not grouped into any issue."
           },
           "rule_name": {
             "description": "Rule name, 1-128 characters.",
@@ -1351,11 +1447,11 @@
         "description": "A single filter condition matched against one error field.",
         "properties": {
           "key": {
-            "description": "Field key. One of `error.usr_id`, `error.usr_email`, `error.error_type`, `error.error_message`, `error.error_stack`, `error.view_url`, `error.env`, `error.version`, `error.service`, `error.browser_name`, `error.browser_version`, `error.fingerprint`, `error.is_crash`, or a `context.`-prefixed custom context path (up to 3 levels deep).",
+            "description": "Field to match. One of `error.usr_id`, `error.usr_email`, `error.error_type`, `error.error_message`, `error.error_stack`, `error.view_url`, `error.env`, `error.version`, `error.service`, `error.browser_name`, `error.browser_version`, `error.fingerprint`, `error.is_crash` (value `true` or `false`), or a `context.`-prefixed path into the error's custom context. Context objects are flattened with dots up to 3 levels (`context.a.b.c`); a deeper object is compared as its JSON text, and array values can't be matched.",
             "type": "string"
           },
           "oper": {
-            "description": "Match mode: `IN` matches when the field value matches any entry in `vals`; `NOTIN` matches when it matches none.",
+            "description": "Match mode:\n- `IN`: matches when the field value matches any entry in `vals`. A context field the error doesn't carry never matches.\n- `NOTIN`: matches when the field value matches none of `vals`. A context field the error doesn't carry always matches.",
             "enum": [
               "IN",
               "NOTIN"
@@ -1363,7 +1459,7 @@
             "type": "string"
           },
           "vals": {
-            "description": "Values to match against, at least 1 entry. Each entry is an exact string, or a special pattern using wildcards (`*`/`?`), a regexp wrapped in `/`, a `cidr:`-prefixed CIDR match, or a `num:lt|le|gt|ge:`-prefixed numeric comparison.",
+            "description": "Values to match against, at least 1 entry. Each entry is one of: an exact, case-sensitive string; a wildcard pattern using `*`/`?` that must match the whole value; a regexp wrapped in `/` (matches anywhere in the value unless anchored); `cidr:<range>` (the value is parsed as an IP); or `num:lt|le|gt|ge:<number>` (the value is parsed as a number, non-numeric values don't match).",
             "items": {
               "type": "string"
             },
@@ -1382,28 +1478,28 @@
         "description": "A snapshot of every rule for the application at one history version.",
         "properties": {
           "rules": {
-            "description": "The application's complete rule list as of this version.",
+            "description": "The application's complete non-deleted rule list as it was just before the change that created this version. Empty for the version created by the application's first rule.",
             "items": {
               "$ref": "#/components/schemas/RumErrorIngestionRuleSnapshotItem"
             },
             "type": "array"
           },
           "updated_at": {
-            "description": "Unix timestamp in milliseconds when this snapshot was recorded.",
+            "description": "Time of the change that created this version, as a Unix timestamp in milliseconds.",
             "format": "int64",
             "type": "integer"
           },
           "updated_by": {
-            "description": "Member ID whose action triggered this snapshot.",
+            "description": "Member ID of the person who made the change that created this version.",
             "format": "int64",
             "type": "integer"
           },
           "updated_by_name": {
-            "description": "Display name of the member whose action triggered this snapshot.",
+            "description": "Display name of that member at the time of the change.",
             "type": "string"
           },
           "version": {
-            "description": "History version number, incrementing from 1.",
+            "description": "History version number, starting at 1 and incremented by every write. Pass it to `POST /rum/error-ingestion/rules/history/revert`.",
             "type": "integer"
           }
         },
@@ -1425,20 +1521,23 @@
           },
           "asc": {
             "default": false,
-            "description": "Sort ascending instead of the default descending order.",
+            "description": "`true` sorts ascending; `false` (default) sorts descending, newest first.",
             "type": "boolean"
           },
           "limit": {
             "default": 20,
-            "description": "Page size. Default 20, capped at 100; values ≤ 0 fall back to the default.",
+            "description": "Page size. Default 20; values above 100 are clamped to 100, and values of 0 or below fall back to 20.",
             "format": "int64",
-            "maximum": 100,
             "type": "integer"
           },
           "orderby": {
             "default": "updated_at",
-            "description": "Sort column: `updated_at` or `version`. Unrecognized values fall back to `updated_at`.",
-            "type": "string"
+            "description": "Sort column:\n- `updated_at`: time of the change that created the version (default).\n- `version`: version number.\nAny other value falls back to `updated_at`.",
+            "type": "string",
+            "enum": [
+              "updated_at",
+              "version"
+            ]
           },
           "p": {
             "default": 0,
@@ -1457,7 +1556,7 @@
         "description": "Paginated error ingestion rule history.",
         "properties": {
           "has_next_page": {
-            "description": "Whether another page of history exists after this one.",
+            "description": "`true` when more versions exist after this page.",
             "type": "boolean"
           },
           "items": {
@@ -1468,7 +1567,7 @@
             "type": "array"
           },
           "total": {
-            "description": "Total number of history versions for the application.",
+            "description": "Total number of history versions for the application, across all pages.",
             "format": "int64",
             "type": "integer"
           }
@@ -1510,7 +1609,7 @@
         "type": "object"
       },
       "RumErrorIngestionOrFilters": {
-        "description": "OR-of-ANDs filter set. The outer array is OR — an error matches the rule if it matches at least one inner AND-group.",
+        "description": "OR-of-ANDs filter set. The outer array is OR: an error matches the rule if it matches at least one inner AND-group. An empty outer array never matches; an empty inner group matches every error.",
         "items": {
           "description": "AND-group. The group only matches when every condition inside it matches.",
           "items": {
@@ -1543,20 +1642,20 @@
         "description": "An error ingestion rule.",
         "properties": {
           "created_at": {
-            "description": "Unix timestamp in milliseconds when the rule was created.",
+            "description": "Unix timestamp in milliseconds when the rule was created; reset to the revert time when the rule is restored by a history revert.",
             "format": "int64",
             "type": "integer"
           },
           "description": {
-            "description": "Rule description, up to 512 characters.",
+            "description": "Rule description, up to 512 characters; empty string when none was given.",
             "type": "string"
           },
           "filters": {
             "$ref": "#/components/schemas/RumErrorIngestionOrFilters",
-            "description": "The rule's filter conditions."
+            "description": "The rule's conditions. An error that matches them is stored but not grouped into any issue."
           },
           "rule_id": {
-            "description": "Rule ID.",
+            "description": "Rule ID, generated by the server on `create`. It stays the same across updates and history reverts.",
             "type": "string"
           },
           "rule_name": {
@@ -1564,7 +1663,7 @@
             "type": "string"
           },
           "status": {
-            "description": "Current status of the rule.",
+            "description": "Rule status:\n- `enabled`: the rule is applied to newly ingested errors.\n- `disabled`: the rule is kept but not applied.",
             "enum": [
               "enabled",
               "disabled"
@@ -1572,7 +1671,7 @@
             "type": "string"
           },
           "updated_at": {
-            "description": "Unix timestamp in milliseconds when the rule was last updated.",
+            "description": "Unix timestamp in milliseconds of the last update, enable, or disable; reset to the revert time when the rule is restored by a history revert.",
             "format": "int64",
             "type": "integer"
           }
@@ -1610,7 +1709,7 @@
         "description": "One rule record inside a history snapshot. Carries the raw storage fields, a superset of the fields returned by `list`.",
         "properties": {
           "account_id": {
-            "description": "Account ID.",
+            "description": "ID of the account that owns the rule.",
             "format": "int64",
             "type": "integer"
           },
@@ -1629,12 +1728,12 @@
             "type": "integer"
           },
           "deleted_at": {
-            "description": "Unix timestamp in milliseconds when the row was soft-deleted; `0` when not deleted.",
+            "description": "Soft-delete time as a Unix timestamp in milliseconds. Always `0` here, because snapshots contain only non-deleted rules.",
             "format": "int64",
             "type": "integer"
           },
           "description": {
-            "description": "Rule description.",
+            "description": "Rule description as of this snapshot version; empty string when none was given.",
             "type": "string"
           },
           "filters": {
@@ -1642,20 +1741,20 @@
             "description": "The rule's filter conditions as of this snapshot version."
           },
           "id": {
-            "description": "Internal row ID.",
+            "description": "Internal storage row ID. Not accepted by any endpoint; use `rule_id` instead. Changes when the rule is restored by a history revert.",
             "format": "int64",
             "type": "integer"
           },
           "rule_id": {
-            "description": "Rule ID.",
+            "description": "Rule ID, the same value `list` returns for this rule.",
             "type": "string"
           },
           "rule_name": {
-            "description": "Rule name.",
+            "description": "Rule name as of this snapshot version.",
             "type": "string"
           },
           "status": {
-            "description": "The rule's status as of this snapshot version.",
+            "description": "The rule's status as of this snapshot version:\n- `enabled`: applied to newly ingested errors.\n- `disabled`: kept but not applied.",
             "enum": [
               "enabled",
               "disabled"
@@ -1668,7 +1767,7 @@
             "type": "integer"
           },
           "updated_by": {
-            "description": "Member ID who last updated the rule.",
+            "description": "Member ID who last updated the rule before this snapshot.",
             "format": "int64",
             "type": "integer"
           }
@@ -1733,7 +1832,7 @@
         "description": "Parameters for counting facet value distribution.",
         "properties": {
           "dql": {
-            "description": "RUM DQL filter expression applied before counting.",
+            "description": "RUM DQL filter expression applied before counting. Fields in it are validated against the `scope`.",
             "type": "string"
           },
           "end_time": {
@@ -1743,11 +1842,11 @@
             "type": "integer"
           },
           "facet_key": {
-            "description": "Field key whose value distribution to count; must be a registered field of the given `scope`. List available fields via `POST /rum/field/list`.",
+            "description": "Field key whose value distribution to count, such as `error_type`. Must be a facet field of the given `scope` with `show_type: list` and a non-array `value_type`. List candidates with `POST /rum/field/list`.",
             "type": "string"
           },
           "facet_value": {
-            "description": "When set, filter events where `facet_key` equals this value before counting. Accepts string, number, or boolean."
+            "description": "When set, count only events whose `facet_key` equals this value. The JSON type must match the field's `value_type` (string, number or boolean); a mismatch returns `InvalidParameter`. When omitted, events with a `null` value are excluded."
           },
           "kind": {
             "description": "Symbol kind, used only when `scope` is `sourcemap` and only meaningful for `android`/`harmony`: `mapping` (default) selects ProGuard/R8 mappings or ArkTS sourcemaps, `native` selects native .so symbols.",
@@ -1779,7 +1878,7 @@
             "type": "string"
           },
           "sql": {
-            "description": "SQL WHERE clause (no SELECT) for additional filtering.",
+            "description": "Bare SQL `WHERE` condition (without the `WHERE` keyword) for extra filtering, such as `env = 'prod'`. Any occurrence of `SELECT` is rejected.",
             "type": "string"
           },
           "start_time": {
@@ -1871,7 +1970,7 @@
             "type": "string"
           },
           "group": {
-            "description": "Display group for this field.",
+            "description": "Display group used to cluster fields in the console, such as `error`, `action` or `device`. Empty when the field has no group.",
             "type": "string"
           },
           "is_facet": {
@@ -1883,7 +1982,7 @@
             "type": "boolean"
           },
           "scopes": {
-            "description": "RUM scopes this field appears in.",
+            "description": "RUM scopes this field appears in, using the same values as the request `scopes` (for example `error`, `issue`).",
             "items": {
               "type": "string"
             },
@@ -1898,15 +1997,34 @@
             "type": "string"
           },
           "status": {
-            "description": "Field status, e.g. `active`.",
+            "description": "Field status. `enabled`: the field is in use. `disabled`: the field is defined but switched off. Deleted fields are never returned.",
+            "enum": [
+              "enabled",
+              "disabled"
+            ],
             "type": "string"
           },
           "unit_family": {
-            "description": "Measurement unit family, e.g. `time`, `bytes`. Empty for dimensionless fields.",
+            "description": "Measurement unit family. `time`: a duration or timestamp (see `unit_name`). `bytes`: a size in bytes. Empty string for dimensionless fields.",
+            "enum": [
+              "",
+              "time",
+              "bytes"
+            ],
             "type": "string"
           },
           "unit_name": {
-            "description": "Specific measurement unit, e.g. `millisecond`, `byte`.",
+            "description": "Unit of the stored value. Durations: `nanosecond`, `microsecond`, `millisecond`, `second`. Timestamps: `unix_millisecond`, `unix_second`. Sizes: `byte`. Empty string for dimensionless fields. Most built-in duration fields are in `nanosecond`.",
+            "enum": [
+              "",
+              "nanosecond",
+              "microsecond",
+              "millisecond",
+              "second",
+              "unix_millisecond",
+              "unix_second",
+              "byte"
+            ],
             "type": "string"
           },
           "value_type": {
@@ -2007,11 +2125,11 @@
             "type": "boolean"
           },
           "console_origin": {
-            "description": "Console origin used to build the `issue_url` column, e.g. `https://console.flashcat.cloud`. The service cannot infer it (SaaS, on-premises and dev releases answer on different origins).",
+            "description": "Console origin used to build the `issue_url` column, e.g. `https://console.flashcat.cloud`; a trailing `/` is trimmed. The service cannot infer it. When omitted, `issue_url` holds only the path `/rum/error-tracking/issue/<issue_id>`.",
             "type": "string"
           },
           "dql": {
-            "description": "DQL query for advanced filtering. Cannot be used with `sql`.",
+            "description": "DQL query for advanced filtering. Field names must be fields of the `issue` scope (see `POST /rum/field/list` with `scopes: [\"issue\"]`); a bare full-text term searches the error message. Cannot be used with `sql`.",
             "type": "string"
           },
           "end_time": {
@@ -2024,7 +2142,7 @@
             "type": "boolean"
           },
           "export_fields": {
-            "description": "CSV columns to export, in the order they appear. Unknown keys are rejected with a parameter error; an empty array uses the default column set.\n\n| Value | Column content |\n|---|---|\n| `issue_id` | Issue ID |\n| `issue_url` | Console URL of the issue detail page (built from `console_origin`) |\n| `application_name` | Owning application name |\n| `service` | Service name |\n| `error_type` | Error type |\n| `error_message` | Error message |\n| `status` | Triage status |\n| `severity` | Severity |\n| `is_crash` | Whether the error caused a crash |\n| `error_count` | Error occurrence count |\n| `session_count` | Affected session count |\n| `first_seen_at` | First occurrence time (rendered in `time_zone`) |\n| `first_seen_version` | Application version at first occurrence |\n| `last_seen_at` | Most recent occurrence time (rendered in `time_zone`) |\n| `last_seen_version` | Application version at the most recent occurrence |\n| `versions` | All affected versions |\n| `suspected_cause` | Suspected cause category |\n| `resolved_at` | Resolution time (rendered in `time_zone`) |",
+            "description": "CSV columns to export, in the order they appear. Unknown keys are rejected with a parameter error and duplicates are dropped. Empty or omitted: every column below except the `sample_first_*` group.\n\n| Value | Column content |\n|---|---|\n| `issue_id` | Issue ID |\n| `issue_url` | Console URL of the issue detail page (built from `console_origin`) |\n| `application_name` | Owning application name |\n| `service` | Service name |\n| `error_type` | Error type |\n| `error_message` | Error message |\n| `status` | Triage status |\n| `severity` | Severity |\n| `is_crash` | Whether the error caused a crash |\n| `error_count` | Error occurrence count |\n| `session_count` | Affected session count |\n| `first_seen_at` | First occurrence time (rendered in `time_zone`) |\n| `first_seen_version` | Application version at first occurrence |\n| `last_seen_at` | Most recent occurrence time (rendered in `time_zone`) |\n| `last_seen_version` | Application version at the most recent occurrence |\n| `versions` | All affected versions |\n| `suspected_cause` | Suspected cause category |\n| `resolved_at` | Resolution time (rendered in `time_zone`); empty while unresolved |\n| `sample_time` | Latest error event in the time window: time of the event (rendered in `time_zone`) |\n| `sample_version` | Latest error event in the time window: application version |\n| `sample_view` | Latest error event in the time window: view name, or the view URL when the name is empty |\n| `sample_session_id` | Latest error event in the time window: session ID |\n| `sample_device` | Latest error event in the time window: device brand and model |\n| `sample_os` | Latest error event in the time window: OS name and version |\n| `sample_browser` | Latest error event in the time window: browser name and version |\n| `sample_stack` | Latest error event in the time window: error stack, truncated to the first 20 lines |\n| `sample_first_time` | Earliest error event in the time window: time of the event (rendered in `time_zone`) |\n| `sample_first_version` | Earliest error event in the time window: application version |\n| `sample_first_view` | Earliest error event in the time window: view name, or the view URL when the name is empty |\n| `sample_first_session_id` | Earliest error event in the time window: session ID |\n| `sample_first_device` | Earliest error event in the time window: device brand and model |\n| `sample_first_os` | Earliest error event in the time window: OS name and version |\n| `sample_first_browser` | Earliest error event in the time window: browser name and version |\n| `sample_first_stack` | Earliest error event in the time window: error stack, truncated to the first 20 lines |",
             "items": {
               "enum": [
                 "issue_id",
@@ -2044,7 +2162,23 @@
                 "last_seen_version",
                 "versions",
                 "suspected_cause",
-                "resolved_at"
+                "resolved_at",
+                "sample_time",
+                "sample_version",
+                "sample_view",
+                "sample_session_id",
+                "sample_device",
+                "sample_os",
+                "sample_browser",
+                "sample_stack",
+                "sample_first_time",
+                "sample_first_version",
+                "sample_first_view",
+                "sample_first_session_id",
+                "sample_first_device",
+                "sample_first_os",
+                "sample_first_browser",
+                "sample_first_stack"
               ],
               "type": "string"
             },
@@ -2073,11 +2207,11 @@
             "type": "integer"
           },
           "sql": {
-            "description": "SQL-style query for advanced filtering. Cannot be used with `dql`.",
+            "description": "SQL-style WHERE condition for advanced filtering, without the `WHERE` keyword (for example `error_count > 100`). Field names must be fields of the `issue` scope; any text containing `SELECT` is rejected. Cannot be used with `dql`.",
             "type": "string"
           },
           "start_time": {
-            "description": "Start of the time range, Unix epoch milliseconds.",
+            "description": "Start of the time range, Unix timestamp in milliseconds (a value that looks like seconds is rejected). Issues are matched by creation time unless `by_intersection` is `true`.",
             "format": "int64",
             "type": "integer"
           },
@@ -2118,7 +2252,7 @@
             "type": "array"
           },
           "time_zone": {
-            "description": "IANA time zone used to render timestamps in the CSV, e.g. `Asia/Shanghai` or `UTC`. Default: `Asia/Shanghai`.",
+            "description": "IANA time zone used to render the CSV time columns and the file name, e.g. `Asia/Shanghai` or `UTC`. Default: `Asia/Shanghai`. An unknown zone name returns `InvalidParameter`.",
             "type": "string"
           }
         },
@@ -2169,7 +2303,7 @@
                 "type": "string"
               },
               "type": {
-                "description": "Error type, from the error event's `error_type` field as reported by the SDK.",
+                "description": "Error type reported by the SDK in the error event's `error_type` field — free-form, not a fixed set. Browser errors carry the JavaScript exception name, e.g. `Error`, `TypeError`, `ReferenceError`.",
                 "type": "string"
               }
             },
@@ -2219,7 +2353,7 @@
             "type": "object"
           },
           "regression": {
-            "description": "Regression metadata. Present only when a previously resolved issue re-occurred.",
+            "description": "Regression record. Present only after a resolved issue was reopened because its error recurred; cleared when the issue is resolved again.",
             "properties": {
               "regressed_at": {
                 "description": "Time the regression was detected, Unix timestamp in milliseconds.",
@@ -2239,15 +2373,23 @@
             "type": "object"
           },
           "resolved_at": {
-            "description": "Time the issue was marked resolved, Unix timestamp in milliseconds; 0 while unresolved.",
+            "description": "Time the issue was marked resolved (by a user or automatically), Unix timestamp in milliseconds; `0` while unresolved.",
             "format": "int64",
             "type": "integer"
           },
           "resolved_by": {
-            "description": "Person ID of the user who marked the issue resolved; 0 while unresolved.",
+            "description": "Person ID of the user who marked the issue resolved; `0` while unresolved or when the issue was resolved automatically.",
             "format": "int64",
             "type": "integer"
           },
+          "resolve_mode": {
+            "description": "How the issue reacts when its error recurs after being resolved: `any` reopens it on any recurrence; `version` reopens it only when the error recurs in an application version the issue has not been seen in (errors without a version always reopen it). New issues and automatic resolution use `version`; resolving through `POST /rum/issue/update` without `resolve_mode` sets `any`.",
+            "enum": [
+              "any",
+              "version"
+            ],
+            "type": "string"
+          },
           "service": {
             "description": "Name of the service that produced this issue, taken from the error event's `service` field.",
             "type": "string"
@@ -2258,7 +2400,7 @@
             "type": "integer"
           },
           "severity": {
-            "description": "Issue severity: `Critical`, `Warning`, or `Info`. Empty string on legacy issues created before severity existed.",
+            "description": "Issue severity, fixed when the issue is created: the first matching enabled preset severity rule (see `POST /rum/issue/preset-severity/rules/list`) decides it, otherwise a built-in rule (crashes are `Critical`; other errors are scored by environment and message keywords). An error only joins an existing issue of equal or higher severity, so the same error can produce separate issues per severity. Empty string on legacy issues created before severity existed.",
             "enum": [
               "Critical",
               "Warning",
@@ -2267,7 +2409,7 @@
             "type": "string"
           },
           "status": {
-            "description": "Triage status of the issue; soft-deleted (`deleted`) issues are never returned.\n\n| Value | Meaning |\n|---|---|\n| `for_review` | Pending triage |\n| `reviewed` | Reviewed |\n| `ignored` | Ignored |\n| `resolved` | Resolved |",
+            "description": "Triage status of the issue; soft-deleted (`deleted`) issues are never returned. The system resolves an issue automatically when its error has not been seen for 14 days, or when a newer application version reports no such error, and reopens a resolved issue as `for_review` when the error recurs (see `resolve_mode`).\n\n| Value | Meaning |\n|---|---|\n| `for_review` | Pending triage |\n| `reviewed` | Reviewed |\n| `ignored` | Ignored |\n| `resolved` | Resolved |",
             "enum": [
               "for_review",
               "reviewed",
@@ -2285,7 +2427,7 @@
                 "type": "integer"
               },
               "reason": {
-                "description": "Explanation for the cause determination, generated only by AI analysis; empty string when AI is disabled or analysis has not run.",
+                "description": "Free-text explanation of the cause, written only by AI analysis; empty string when AI analysis is disabled, has not run yet, or the cause was set by a user.",
                 "type": "string"
               },
               "source": {
@@ -2322,14 +2464,40 @@
             "type": "integer"
           },
           "versions": {
-            "description": "Deduplicated list of application versions in which this issue has occurred; may contain an empty string for events without version info.",
+            "description": "Deduplicated list of application versions in which this issue has occurred; may contain an empty string for events without version info. `null` on issues that never recorded a version list.",
             "items": {
               "type": "string"
             },
-            "type": "array"
+            "type": [
+              "array",
+              "null"
+            ]
           }
         },
-        "type": "object"
+        "type": "object",
+        "required": [
+          "team_id",
+          "issue_id",
+          "application_id",
+          "application_name",
+          "service",
+          "status",
+          "error_count",
+          "session_count",
+          "is_crash",
+          "age",
+          "resolved_at",
+          "resolved_by",
+          "resolve_mode",
+          "created_at",
+          "updated_at",
+          "first_seen",
+          "last_seen",
+          "error",
+          "suspected_cause",
+          "versions",
+          "severity"
+        ]
       },
       "RumIssueListRequest": {
         "description": "Filters for listing issues.",
@@ -2350,7 +2518,7 @@
             "type": "boolean"
           },
           "dql": {
-            "description": "DQL query for advanced filtering. Cannot be used with `sql`.",
+            "description": "DQL query for advanced filtering. Field names must be fields of the `issue` scope (see `POST /rum/field/list` with `scopes: [\"issue\"]`); a bare full-text term searches the error message. Cannot be used with `sql`.",
             "type": "string"
           },
           "end_time": {
@@ -2385,11 +2553,11 @@
             "type": "integer"
           },
           "sql": {
-            "description": "SQL-style query for advanced filtering. Cannot be used with `dql`.",
+            "description": "SQL-style WHERE condition for advanced filtering, without the `WHERE` keyword (for example `error_count > 100`). Field names must be fields of the `issue` scope; any text containing `SELECT` is rejected. Cannot be used with `dql`.",
             "type": "string"
           },
           "start_time": {
-            "description": "Start of the time range, Unix epoch milliseconds.",
+            "description": "Start of the time range, Unix timestamp in milliseconds (a value that looks like seconds is rejected). Issues are matched by creation time unless `by_intersection` is `true`.",
             "format": "int64",
             "type": "integer"
           },
@@ -2464,7 +2632,7 @@
             "type": "string"
           },
           "status": {
-            "description": "New status. Setting `resolved` records the resolution time and operator; switching away from `resolved` clears them.\n\n| Value | Meaning |\n|---|---|\n| `for_review` | Pending triage |\n| `reviewed` | Reviewed |\n| `ignored` | Ignored |\n| `resolved` | Resolved |",
+            "description": "New status. Setting `resolved` on an unresolved issue records the resolution time and operator and clears `regression`; switching away from `resolved` clears the resolution time and operator. Omit to keep the current status.\n\n| Value | Meaning |\n|---|---|\n| `for_review` | Pending triage |\n| `reviewed` | Reviewed |\n| `ignored` | Ignored |\n| `resolved` | Resolved |",
             "enum": [
               "for_review",
               "reviewed",
@@ -2473,6 +2641,14 @@
             ],
             "type": "string"
           },
+          "resolve_mode": {
+            "description": "How the issue reacts when its error recurs after being resolved. Applied only together with `status: resolved`; defaults to `any` there when omitted, and is ignored with any other status.\n\n| Value | Meaning |\n|---|---|\n| `any` | Reopen the issue on any recurrence |\n| `version` | Reopen only when the error recurs in an application version the issue has not been seen in; errors without a version always reopen it |",
+            "enum": [
+              "any",
+              "version"
+            ],
+            "type": "string"
+          },
           "suspected_cause": {
             "description": "New suspected cause; setting it marks the cause source as `user`, overriding the automatic classification. One of:\n\n| Value | Meaning |\n|---|---|\n| `api.failed_request` | API request failure |\n| `network.error` | Network connectivity error |\n| `code.exception` | Code exception |\n| `code.invalid_object_access` | Invalid object access |\n| `code.invalid_argument` | Invalid argument |\n| `unknown` | Unknown cause |",
             "enum": [
@@ -2504,7 +2680,7 @@
             "type": "string"
           },
           "filters": {
-            "description": "OR-of-ANDs filter structure: the outer array is OR'd, each inner array is AND'd. A rule matches an error when at least one inner AND-group fully matches.",
+            "description": "OR-of-ANDs filter structure: the outer array is OR'd, each inner array is AND'd. A rule matches an error when at least one inner AND-group fully matches. An empty outer array never matches; an empty inner group matches every error.",
             "items": {
               "items": {
                 "$ref": "#/components/schemas/RumPresetSeverityRuleFilterCondition"
@@ -2563,7 +2739,7 @@
         "description": "One filter condition within an AND group.",
         "properties": {
           "key": {
-            "description": "Filter attribute key. Only these Error-level attributes are supported for preset severity rules.\n\n| Value | Meaning |\n|---|---|\n| `error.usr_id` | User ID |\n| `error.usr_email` | User email |\n| `error.view_url` | Full URL of the page where the error occurred |\n| `error.view_url_path` | URL path of the page where the error occurred |\n| `error.error_type` | Error type |\n| `error.error_message` | Error message |\n| `error.env` | Environment (e.g. production/staging) |\n| `error.service` | Service name |\n| `error.device_type` | Device type |\n| `error.os_name` | Operating system name |\n| `error.browser_name` | Browser name |\n| `error.is_crash` | Whether the error is a crash (boolean) |",
+            "description": "Filter attribute key. Only these Error-level attributes are supported for preset severity rules.\n\n| Value | Meaning |\n|---|---|\n| `error.usr_id` | User ID |\n| `error.usr_email` | User email |\n| `error.view_url` | Full URL of the page where the error occurred |\n| `error.view_url_path` | URL path of the page where the error occurred |\n| `error.error_type` | Error type |\n| `error.error_message` | Error message |\n| `error.env` | Environment (e.g. production/staging) |\n| `error.service` | Service name |\n| `error.device_type` | Device type |\n| `error.os_name` | Operating system name |\n| `error.browser_name` | Browser name |\n| `error.is_crash` | Whether the error is a crash, compared as the string `true` or `false` |",
             "enum": [
               "error.usr_id",
               "error.usr_email",
@@ -2581,7 +2757,7 @@
             "type": "string"
           },
           "oper": {
-            "description": "Match semantics: `IN` matches when the field's value matches any of `vals`; `NOTIN` matches when it matches none of them (and matches when the field is absent).",
+            "description": "Match semantics: `IN` matches when the attribute value matches any of `vals`; `NOTIN` matches when it matches none of them. An attribute the error does not carry is compared as an empty string.",
             "enum": [
               "IN",
               "NOTIN"
@@ -2589,7 +2765,7 @@
             "type": "string"
           },
           "vals": {
-            "description": "Values to match against. Each entry supports exact string match, wildcard (`*`/`?`), regex (wrap in `/.../`), CIDR (`cidr:10.0.0.0/8`) for IP-shaped values, or numeric comparison (`num:gt:100`, `num:le:50`, etc.).",
+            "description": "Values to match against; at least one, none empty. Each entry is one of: an exact, case-sensitive whole-value match; a wildcard pattern with `*`/`?` (whole value); a regular expression wrapped in `/.../` (matches anywhere in the value unless anchored with `^`/`$`); `cidr:<network>` for IP-shaped values, e.g. `cidr:10.0.0.0/8`; or a numeric comparison `num:<op>:<number>` with `op` one of `lt`, `le`, `gt`, `ge`, e.g. `num:gt:100`. For `error.is_crash`, use `true` or `false`.",
             "items": {
               "type": "string"
             },
@@ -2759,7 +2935,7 @@
             "type": "string"
           },
           "filters": {
-            "description": "OR-of-ANDs filter structure: the outer array is OR'd, each inner array is AND'd. A rule matches an error when at least one inner AND-group fully matches.",
+            "description": "OR-of-ANDs filter structure: the outer array is OR'd, each inner array is AND'd. A rule matches an error when at least one inner AND-group fully matches. An empty outer array never matches; an empty inner group matches every error.",
             "items": {
               "items": {
                 "$ref": "#/components/schemas/RumPresetSeverityRuleFilterCondition"
@@ -2863,7 +3039,7 @@
             "type": "string"
           },
           "filters": {
-            "description": "OR-of-ANDs filter structure: the outer array is OR'd, each inner array is AND'd. A rule matches an error when at least one inner AND-group fully matches.",
+            "description": "OR-of-ANDs filter structure: the outer array is OR'd, each inner array is AND'd. A rule matches an error when at least one inner AND-group fully matches. An empty outer array never matches; an empty inner group matches every error.",
             "items": {
               "items": {
                 "$ref": "#/components/schemas/RumPresetSeverityRuleFilterCondition"
@@ -2987,7 +3163,7 @@
             ]
           },
           "filters": {
-            "description": "OR-of-ANDs filter structure: the outer array is OR'd, each inner array is AND'd. A rule matches an error when at least one inner AND-group fully matches.",
+            "description": "New OR-of-ANDs filter structure; replaces the whole current structure. Omit or pass `null` to leave unchanged. The outer array is OR'd, each inner array is AND'd; an empty outer array never matches, an empty inner group matches every error.",
             "items": {
               "items": {
                 "$ref": "#/components/schemas/RumPresetSeverityRuleFilterCondition"
@@ -3047,15 +3223,15 @@
         "type": "object"
       },
       "RumReplayForegroundPeriod": {
-        "description": "A time span during which the app was in the foreground (mobile sessions).",
+        "description": "A span during which a view was in the foreground (focused).",
         "properties": {
           "end": {
-            "description": "Unix timestamp in milliseconds when the foreground period ended.",
+            "description": "End of the foreground period, in **nanoseconds** since the start of the view identified by `view_id` (not a Unix timestamp).",
             "format": "int64",
             "type": "integer"
           },
           "start": {
-            "description": "Unix timestamp in milliseconds when the foreground period started.",
+            "description": "Start of the foreground period, in **nanoseconds** since the start of the view identified by `view_id` (not a Unix timestamp).",
             "format": "int64",
             "type": "integer"
           },
@@ -3069,7 +3245,7 @@
       "RumReplaySession": {
         "properties": {
           "end": {
-            "description": "Unix timestamp in milliseconds when the session ended (or was last updated, if still active).",
+            "description": "Unix timestamp in milliseconds of the session end: the later of the session's recorded end and the end of its last returned view.",
             "format": "int64",
             "type": "integer"
           },
@@ -3078,7 +3254,7 @@
             "type": "boolean"
           },
           "server_time_delta": {
-            "description": "Clock skew in milliseconds between the client and Flashduty's servers, added to client timestamps for correction.",
+            "description": "Always `0`: timestamps are returned as recorded by the client, without clock-skew correction.",
             "format": "int64",
             "type": "integer"
           },
@@ -3110,7 +3286,20 @@
       "RumReplayView": {
         "properties": {
           "container_source": {
-            "description": "SDK platform of the container app, when this view is embedded (e.g. a WebView inside a native app). Omitted when the view is not embedded.",
+            "description": "SDK platform of the app that embeds this view (for example a WebView inside a native app). Omitted when the view is not embedded.\n\n| Value | Meaning |\n|---|---|\n| `browser` | Web browser application |\n| `ios` | Apple iOS application |\n| `android` | Android application |\n| `react-native` | React Native application |\n| `flutter` | Flutter application |\n| `kotlin-multiplatform` | Kotlin Multiplatform application |\n| `roku` | Roku channel application |\n| `unity` | Unity application |\n| `miniprogram` | WeChat mini program |\n| `harmony` | HarmonyOS application |\n| `electron` | Electron desktop application |",
+            "enum": [
+              "browser",
+              "ios",
+              "android",
+              "react-native",
+              "flutter",
+              "kotlin-multiplatform",
+              "roku",
+              "unity",
+              "miniprogram",
+              "harmony",
+              "electron"
+            ],
             "type": "string"
           },
           "container_view_id": {
@@ -3127,7 +3316,7 @@
             "type": "boolean"
           },
           "loading_type": {
-            "description": "How the view was entered, e.g. `initial_load`, `route_change`.",
+            "description": "How the view was entered, as reported by the SDK. Web: `initial_load`, `route_change`. Mobile: `activity_display`, `activity_redisplay`, `fragment_display`, `fragment_redisplay`, `view_controller_display`, `view_controller_redisplay`. Empty when not reported.",
             "type": "string"
           },
           "name": {
@@ -3135,7 +3324,7 @@
             "type": "string"
           },
           "server_time_delta": {
-            "description": "Clock skew in milliseconds between the client and Flashduty's servers, added to client timestamps for correction.",
+            "description": "Always `0`: timestamps are returned as recorded by the client, without clock-skew correction.",
             "format": "int64",
             "type": "integer"
           },
@@ -3251,7 +3440,7 @@
             "type": "integer"
           },
           "session_investigate.free_cnt": {
-            "description": "Free quota for investigate sessions per application, per billing window.",
+            "description": "Free quota of investigate (error tracking) sessions per application, per billing window. A negative value means unlimited.",
             "format": "int64",
             "type": "integer"
           },
@@ -3261,11 +3450,11 @@
             "type": "integer"
           },
           "session_limit_reached": {
-            "description": "`true` when a `version=free` account has exceeded its combined free session quota across all applications. Always `false` for non-free plans.",
+            "description": "`true` when a `version=free` account's investigate or replay sessions in the current window have reached the per-application free quota multiplied by the number of applications. Always `false` for non-free plans and for accounts without applications.",
             "type": "boolean"
           },
           "session_measure.free_cnt": {
-            "description": "Free quota for measure sessions per application, per billing window.",
+            "description": "Free quota of measure (performance) sessions per application, per billing window. A negative value means unlimited.",
             "format": "int64",
             "type": "integer"
           },
@@ -3275,7 +3464,7 @@
             "type": "integer"
           },
           "session_replay.free_cnt": {
-            "description": "Free quota for session-replay sessions per application, per billing window.",
+            "description": "Free quota of session-replay sessions per application, per billing window. A negative value means unlimited.",
             "format": "int64",
             "type": "integer"
           },
@@ -3362,7 +3551,7 @@
             "description": "Device that recorded the session."
           },
           "foreground_periods": {
-            "description": "Foreground periods across the session (mobile sessions only; empty for web).",
+            "description": "Periods during which a view was in the foreground (focused), collected from every returned view. Empty when the SDK reported none.",
             "items": {
               "$ref": "#/components/schemas/RumReplayForegroundPeriod"
             },
@@ -3373,7 +3562,7 @@
             "description": "Session bounds and state."
           },
           "views": {
-            "description": "Every view recorded during the session, in chronological order.",
+            "description": "Views of the session that carry replay data, ordered by start time.",
             "items": {
               "$ref": "#/components/schemas/RumReplayView"
             },
@@ -3390,7 +3579,7 @@
             "type": "string"
           },
           "ts": {
-            "description": "Unix timestamp in milliseconds of the session start time. Optional; disambiguates when a session ID has been reused across different time windows.",
+            "description": "Session start time, Unix milliseconds. Optional. When set, it must match the session's start exactly; use it to pick one session when a `session_id` was reused.",
             "exclusiveMinimum": 0,
             "format": "int64",
             "type": "integer"
@@ -3420,7 +3609,7 @@
             "type": "string"
           },
           "ts": {
-            "description": "Unix timestamp in milliseconds. When set (and `search_after_ctx` is empty), seeks to the most recent full-snapshot segment at or before this time instead of starting from the beginning.",
+            "description": "Unix timestamp in milliseconds. When set and `search_after_ctx` is empty, paging starts at the last full-snapshot segment at or before this time (searching up to 4 hours back); if none is found, paging starts from the beginning.",
             "exclusiveMinimum": 0,
             "format": "int64",
             "type": "integer"
@@ -3443,14 +3632,14 @@
         "description": "Presigned segment URLs, returned only when `url_mode` is `true`.",
         "properties": {
           "items": {
-            "description": "Presigned, time-limited URLs (valid 1 hour) for downloading each segment's raw compressed bytes.",
+            "description": "Presigned URLs (valid 1 hour) for downloading each segment object. The object body is zlib-compressed; decompress it to get the segment JSON.",
             "items": {
               "type": "string"
             },
             "type": "array"
           },
           "search_after_ctx": {
-            "description": "Pagination cursor to pass as `search_after_ctx` on the next call. Empty when this page was the last one.",
+            "description": "Cursor to pass as `search_after_ctx` on the next call. Set whenever this page returned `limit` segments (the next page may then be empty); empty string when fewer were returned.",
             "type": "string"
           }
         },
@@ -3460,11 +3649,11 @@
         "description": "Parameters for sending a sample RUM alert webhook.",
         "properties": {
           "application_id": {
-            "description": "RUM application ID. Get application IDs via `POST /rum/application/list`.",
+            "description": "RUM application whose name is put in the sample event's `labels.application_name`. The caller must be able to edit it. Get application IDs via `POST /rum/application/list`.",
             "type": "string"
           },
           "webhook_url": {
-            "description": "Webhook URL to receive the sample alert event.",
+            "description": "Webhook URL to receive the sample alert event; must use `http` or `https`. Not saved: use `POST /rum/application/update` with `alerting.webhook_url` to store it.",
             "format": "uri",
             "type": "string"
           }
@@ -3479,15 +3668,15 @@
         "description": "Result of the webhook test delivery.",
         "properties": {
           "message": {
-            "description": "`ok` on success, otherwise the delivery error message.",
+            "description": "`ok` on success. Otherwise `unexpected status <code>` when the endpoint answered with an error status, or `request failed: <error>` when no response was received.",
             "type": "string"
           },
           "ok": {
-            "description": "Whether the webhook endpoint accepted the sample event.",
+            "description": "`true` when the endpoint answered with a status below 400 (after following redirects); `false` otherwise.",
             "type": "boolean"
           },
           "status_code": {
-            "description": "HTTP status code returned by the webhook endpoint. 0 when the request did not receive a response.",
+            "description": "HTTP status code of the last delivery attempt. `0` when no response was received (connection error or timeout).",
             "type": "integer"
           }
         },
@@ -3542,11 +3731,6 @@
             "type": "string"
           }
         },
-        "required": [
-          "uuid",
-          "name",
-          "is_system"
-        ],
         "type": "object"
       },
       "SourcemapCodeSnippet": {
@@ -3618,7 +3802,7 @@
             "type": "string"
           },
           "key": {
-            "description": "Storage key uniquely identifying this sourcemap file.",
+            "description": "Record identifier: a 32-character MD5 hex digest derived from the uploaded file's identity (storage path, or service/version/build identifiers for native symbols).",
             "type": "string"
           },
           "metadata": {
@@ -3679,7 +3863,7 @@
             "type": "boolean"
           },
           "build_id": {
-            "description": "Android only. Filter by Gradle plugin build identifier. Max 200 characters.",
+            "description": "Substring filter on the build ID (Android Gradle plugin build identifier, or the build ID of native symbols). Max 200 characters.",
             "maxLength": 200,
             "type": "string"
           },
@@ -3751,7 +3935,7 @@
             "type": "string"
           },
           "uuid": {
-            "description": "iOS only. Filter by dSYM bundle UUID. Max 200 characters.",
+            "description": "iOS only. Substring filter on the dSYM UUID; upper-cased and stripped of hyphens before matching. Max 200 characters.",
             "maxLength": 200,
             "type": "string"
           },
@@ -3793,7 +3977,7 @@
         "description": "Stack trace enrichment request.",
         "properties": {
           "arch": {
-            "description": "Android NDK architecture such as `arm`, `arm64`, `x86`, or `x64`.",
+            "description": "Native CPU architecture, such as `arm`, `arm64`, `x86` or `x64`. With `type: android` and an empty `source_type`, sending `arch` selects NDK native symbolication.",
             "type": "string"
           },
           "binary_images": {
@@ -3830,7 +4014,7 @@
             "type": "string"
           },
           "source_type": {
-            "description": "Android error source type. Use `ndk` with `arch` for native symbolication.",
+            "description": "The error's `error.source_type` as reported by the SDK. It reroutes symbolication: for `android`, a value containing `ndk` selects NDK native symbols; for `flutter` and `react-native`, `ios` selects dSYM and `android`/`ndk` selects Android symbols; for `electron`, `macos`, `windows` or `linux` selects Breakpad symbols. Ignored for other types.",
             "type": "string"
           },
           "stack": {
@@ -3932,7 +4116,7 @@
         "description": "Success response envelope. On every 2xx response, `request_id` identifies the call (also mirrored in the `Flashcat-Request-Id` header) and `data` holds the endpoint-specific payload. Failure responses use a different shape — see `ErrorResponse`.",
         "properties": {
           "data": {
-            "description": "Endpoint-specific payload. See each operation's 200 response schema."
+            "description": "Operation-specific payload, documented in each operation's 200 response. Operations without a payload return `{}` or omit `data` entirely."
           },
           "request_id": {
             "description": "Unique ID for this request. Mirrored in the Flashcat-Request-Id response header. Include it when reporting issues.",
@@ -3941,8 +4125,7 @@
           }
         },
         "required": [
-          "request_id",
-          "data"
+          "request_id"
         ],
         "type": "object"
       },
@@ -3950,14 +4133,15 @@
         "description": "Publish a whole new remote configuration version. The client sends the complete object, not a patch: rule order carries meaning.",
         "properties": {
           "application_id": {
-            "description": "RUM application ID.",
+            "description": "RUM application ID. Get application IDs via `POST /rum/application/list`.",
             "type": "string"
           },
           "config": {
-            "$ref": "#/components/schemas/RemoteConfig"
+            "$ref": "#/components/schemas/RemoteConfig",
+            "description": "The complete configuration to publish."
           },
           "reason": {
-            "description": "Operator's note on why this version was published. Stored verbatim.",
+            "description": "Optional free-text note (not an enum) on why this version was published, at most 255 characters; stored verbatim and returned as `reason` by `POST /rum/application/remote-config/history/list`.",
             "maxLength": 255,
             "type": "string"
           }
@@ -3972,7 +4156,7 @@
         "description": "Version allocated to the published configuration.",
         "properties": {
           "version": {
-            "description": "New published version number.",
+            "description": "Version number allocated to the published configuration (previous highest version + 1).",
             "type": "integer"
           }
         },
@@ -4004,7 +4188,7 @@
     },
     "securitySchemes": {
       "AppKeyAuth": {
-        "description": "App key issued from the Flashduty console under Account → APP Keys. Required on every public API call. Keep it secret — it grants the same access as the owning account.",
+        "description": "APP Key created in the Flashduty console under My → APP Key. Send it as the `app_key` query parameter or in the `Fd-App-Key` request header. Its effective access is the intersection of the key's permission scope and the creator's current role permissions. Keep it secret.",
         "in": "query",
         "name": "app_key",
         "type": "apiKey"
@@ -4012,7 +4196,7 @@
     }
   },
   "info": {
-    "description": "Public HTTP API for the Flashduty incident management platform — incidents, notification templates, channels, schedules, monitors, RUM, and platform administration. Every operation is authenticated with an `app_key` query parameter issued from the Flashduty console under Account → APP Keys. Responses follow a uniform envelope: `{ request_id, data }` on success, `{ request_id, error }` on failure.",
+    "description": "Public HTTP API for the Flashduty incident management platform — incidents, notification templates, channels, schedules, monitors, RUM, and platform administration. Every operation is authenticated with an `app_key` query parameter created in the Flashduty console under My → APP Key (or sent in the `Fd-App-Key` header). Responses follow a uniform envelope: `{ request_id, data }` on success, `{ request_id, error }` on failure.",
     "title": "Flashduty Open API",
     "version": "1.0.0"
   },
@@ -4092,6 +4276,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -4104,7 +4291,7 @@
           "RUM/Applications"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Applications Manage** (`rum`) |\n\n## Usage\n\n- `type` must be one of: `browser`, `ios`, `android`, `react-native`, `flutter`, `kotlin-multiplatform`, `roku`, `unity`, `miniprogram`, `harmony`, `electron`.\n- `links.systems[].url` must start with `http` or `https`; `${var}` tokens are resolved from RUM event context.\n- `links.systems[].event_types` accepts: `crash`, `error`, `view`, `action`, `resource`, `session`, `all`.\n- `client_token` is auto-generated and used to initialize the RUM SDK.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Applications Manage** (`rum`) |\n\n## Usage\n\n- `type` must be one of: `browser`, `ios`, `android`, `react-native`, `flutter`, `kotlin-multiplatform`, `roku`, `unity`, `miniprogram`, `harmony`, `electron`.\n- `client_token` is generated by the server and used to initialize the RUM SDK; it is also returned later by `POST /rum/application/info`.\n- When `tracing` is sent, `open_type` (`popup` or `tab`) and an `http`/`https` `endpoint` are required even if `enabled` is `false`.\n- `links.systems[].url` must start with `http` or `https`; each system needs a `name` and at least one `event_types` entry.\n- With `alerting.delivery_mode` `oncall` (the default on Flashduty cloud), the server creates or reuses the account's RUM alerting integration and returns its ID as `alerting.integration_id`.\n- The team in `team_id` is not checked against the caller's own team memberships.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/rum/applications/rum-application-write-create",
           "metadata": {
             "sidebarTitle": "Create application"
@@ -4162,6 +4349,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -4174,7 +4364,7 @@
           "RUM/Applications"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Applications Manage** (`rum`) |\n\n## Usage\n\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Applications Manage** (`rum`) |\n\n## Usage\n\n- Deletion is a soft delete: the application disappears from list, info and infos, and later calls with its ID fail (`InvalidParameter`, or `ResourceNotFound` for remote-config operations). There is no restore operation.\n- The application's `client_token` stops being accepted by the data intake within about 5 minutes; data already collected is not removed.\n- The caller must be able to edit the application: the account owner, an account admin, the application's creator, or a member of its owning team; anyone else gets `AccessDenied`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/rum/applications/rum-application-write-delete",
           "metadata": {
             "sidebarTitle": "Delete application"
@@ -4211,7 +4401,8 @@
                         2490121812131
                       ],
                       "enabled": true,
-                      "integration_id": 4759595678131
+                      "integration_id": 4759595678131,
+                      "delivery_mode": "oncall"
                     },
                     "application_id": "WoyQQ3BohkdtPivubEvE8o",
                     "application_name": "flashcat-rum",
@@ -4247,7 +4438,13 @@
                     },
                     "type": "browser",
                     "updated_at": 1773398630657,
-                    "updated_by": 3790925372131
+                    "updated_by": 3790925372131,
+                    "repositories": [
+                      {
+                        "repo": "acme/web-app",
+                        "subdir": "apps/web"
+                      }
+                    ]
                   },
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 },
@@ -4276,6 +4473,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -4288,7 +4488,7 @@
           "RUM/Applications"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- An unknown or deleted `application_id` returns `InvalidParameter`.\n- A private application (`is_private: true`) is readable only by the account owner, account admins, its creator and members of its owning team; others get `AccessDenied`.",
           "href": "/en/api-reference/rum/applications/rum-application-read-info",
           "metadata": {
             "sidebarTitle": "Get application detail"
@@ -4331,7 +4531,8 @@
                             5967875767131
                           ],
                           "enabled": true,
-                          "integration_id": 4759595678131
+                          "integration_id": 4759595678131,
+                          "delivery_mode": "oncall"
                         },
                         "application_id": "eWbr4xk3ZRnLabRa6unqwD",
                         "application_name": "Flashduty DEV",
@@ -4354,7 +4555,8 @@
                         },
                         "type": "browser",
                         "updated_at": 1772096392711,
-                        "updated_by": 3122470302131
+                        "updated_by": 3122470302131,
+                        "repositories": []
                       },
                       {
                         "account_id": 2451002751131,
@@ -4363,7 +4565,8 @@
                             2490121812131
                           ],
                           "enabled": true,
-                          "integration_id": 4759595678131
+                          "integration_id": 4759595678131,
+                          "delivery_mode": "oncall"
                         },
                         "application_id": "WoyQQ3BohkdtPivubEvE8o",
                         "application_name": "flashcat-rum",
@@ -4399,7 +4602,8 @@
                         },
                         "type": "browser",
                         "updated_at": 1773398630657,
-                        "updated_by": 3790925372131
+                        "updated_by": 3790925372131,
+                        "repositories": []
                       }
                     ]
                   },
@@ -4430,6 +4634,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -4442,7 +4649,7 @@
           "RUM/Applications"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Maximum 200 IDs per request.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Duplicate IDs are collapsed; unknown or deleted IDs are skipped without an error, so `items` can be shorter than `application_ids`.\n- The order of `items` is not guaranteed to follow `application_ids`.",
           "href": "/en/api-reference/rum/applications/rum-application-read-infos",
           "metadata": {
             "sidebarTitle": "Batch get applications"
@@ -4485,7 +4692,8 @@
                             2490121812131
                           ],
                           "enabled": true,
-                          "integration_id": 4759595678131
+                          "integration_id": 4759595678131,
+                          "delivery_mode": "oncall"
                         },
                         "application_id": "WoyQQ3BohkdtPivubEvE8o",
                         "application_name": "flashcat-rum",
@@ -4521,7 +4729,8 @@
                         },
                         "type": "browser",
                         "updated_at": 1773398630657,
-                        "updated_by": 3790925372131
+                        "updated_by": 3790925372131,
+                        "repositories": []
                       },
                       {
                         "account_id": 2451002751131,
@@ -4531,7 +4740,8 @@
                             5967875767131
                           ],
                           "enabled": true,
-                          "integration_id": 4759595678131
+                          "integration_id": 4759595678131,
+                          "delivery_mode": "oncall"
                         },
                         "application_id": "eWbr4xk3ZRnLabRa6unqwD",
                         "application_name": "Flashduty DEV",
@@ -4554,7 +4764,8 @@
                         },
                         "type": "browser",
                         "updated_at": 1772096392711,
-                        "updated_by": 3122470302131
+                        "updated_by": 3122470302131,
+                        "repositories": []
                       }
                     ],
                     "total": 7
@@ -4586,6 +4797,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -4598,7 +4812,7 @@
           "RUM/Applications"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Use `is_my_team` to filter applications belonging to the current user's teams.\n- Default page size is 20, maximum is 100.\n- `orderby` accepts `created_at` or `updated_at`.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Private applications the caller cannot access are left out; the account owner and account admins see every application.\n- `is_my_team: true` keeps only applications owned by the caller's teams. If the caller belongs to no team, the filter is not applied.\n- `team_id`, `query` and `is_my_team` combine with AND.\n- Sorted by `updated_at` descending unless `orderby`/`asc` say otherwise.",
           "href": "/en/api-reference/rum/applications/rum-application-read-list",
           "metadata": {
             "sidebarTitle": "List applications"
@@ -4687,6 +4901,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -4699,7 +4916,7 @@
           "RUM/Applications"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Version `0` means the application has never been configured; SDKs then run entirely on their init values.\n- A change reaches a client when its next session starts unless activation is set to `immediate`.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Before the first publish, `version` and `updated_at` are `0` and `config` is `null`; SDKs then run entirely on their init values.\n- A change reaches a client when its next session starts unless `activation` is `immediate`.\n- An unknown or deleted `application_id` returns `ResourceNotFound`. A private application (`is_private: true`) is readable only by the account owner, account admins, its creator and members of its owning team; others get `AccessDenied`.",
           "href": "/en/api-reference/rum/applications/rum-application-remote-config-read-get",
           "metadata": {
             "sidebarTitle": "Get remote config detail"
@@ -4765,12 +4982,13 @@
                             }
                           ]
                         },
-                        "content_hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
-                        "reason": "Tighten replay sampling for the Q4 launch",
+                        "content_hash": "9f86d081884c7d65",
+                        "reason": "Re-apply the v7 sampling after the test",
                         "updated_at": 1773398630657,
                         "updated_by": 4441703362131,
                         "updated_by_name": "Alice Zhang",
-                        "version": 8
+                        "version": 8,
+                        "equivalent_to": 7
                       },
                       {
                         "config": {
@@ -4801,7 +5019,7 @@
                             }
                           ]
                         },
-                        "content_hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
+                        "content_hash": "9f86d081884c7d65",
                         "reason": "",
                         "updated_at": 1772398630657,
                         "updated_by": 4441703362131,
@@ -4838,6 +5056,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -4850,7 +5071,7 @@
           "RUM/Applications"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Newest first by default (`orderby=updated_at`, `asc=false`).\n- `content_hash` and `equivalent_to` identify versions whose content is identical, so the console can say \"this is an earlier version's content\" instead of showing a false difference.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Only the 50 most recent versions are kept; older versions are deleted when a new one is published and can no longer be listed or reverted to.\n- Newest first by default (`orderby=updated_at`, `asc=false`). An unrecognized `orderby` falls back to `updated_at`; ties are broken by `version`.\n- `content_hash` and `equivalent_to` identify versions with identical content, e.g. a revert that restored an earlier version.",
           "href": "/en/api-reference/rum/applications/rum-application-remote-config-read-history-list",
           "metadata": {
             "sidebarTitle": "List remote config history"
@@ -4912,6 +5133,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -4924,7 +5148,7 @@
           "RUM/Applications"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Applications Manage** (`rum`) |\n\n## Usage\n\n- History is never rewritten: the revert publishes the earlier version's content under a NEW version number.\n- An empty `reason` is filled in by the console as `rolled back to vN`.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Applications Manage** (`rum`) |\n\n## Usage\n\n- History is never rewritten: the revert publishes the earlier version's content under a new version number, which is returned.\n- `version` must still be in the retained history (the 50 most recent versions); otherwise the call returns `InvalidParameter` (`version not found`).\n- The restored content is validated against the current rules again and is rejected with `InvalidParameter` if it no longer passes.\n- The server does not generate a `reason`; an omitted `reason` is stored as an empty string.\n- The caller must be able to edit the application: the account owner, an account admin, the application's creator, or a member of its owning team; anyone else gets `AccessDenied`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/rum/applications/rum-application-remote-config-write-history-revert",
           "metadata": {
             "sidebarTitle": "Revert remote config"
@@ -4992,6 +5216,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -5004,7 +5231,7 @@
           "RUM/Applications"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Runs the same matcher as the engine, so the result matches what production clients receive.\n- Omit `config` to preview the currently live configuration.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Runs the same rule matcher the SDK config endpoint uses and publishes nothing.\n- Omit `config` to preview the live configuration; a supplied `config` is validated like an update and invalid drafts return `InvalidParameter`.\n- Rule conditions compare exact strings; a rule that tests `env`, `app_version` or `sdk` never matches when that field is omitted from the request.\n- If the configuration is disabled (`enabled: false`) or has never been published, `values` is empty and `hit_rule_index` is `-1`.",
           "href": "/en/api-reference/rum/applications/rum-application-remote-config-read-preview",
           "metadata": {
             "sidebarTitle": "Preview remote config"
@@ -5093,6 +5320,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -5105,7 +5335,7 @@
           "RUM/Applications"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Applications Manage** (`rum`) |\n\n## Usage\n\n- The client sends the complete object, not a patch: rule order is the priority, so a partial update has no unambiguous interpretation.\n- Each call allocates a new version and records a history row in the same transaction as the write.\n- Call `POST /rum/application/remote-config/preview` first to check what clients would receive.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Applications Manage** (`rum`) |\n\n## Usage\n\n- Send the complete configuration, not a patch: rule order is the priority, so a partial update has no unambiguous meaning.\n- Every call publishes a new version, even when the content is unchanged or `enabled` is `false`; only the 50 most recent versions are kept.\n- Call `POST /rum/application/remote-config/preview` first to check what clients would receive.\n- The caller must be able to edit the application: the account owner, an account admin, the application's creator, or a member of its owning team; anyone else gets `AccessDenied`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/rum/applications/rum-application-remote-config-write-update",
           "metadata": {
             "sidebarTitle": "Update remote config"
@@ -5115,7 +5345,7 @@
     },
     "/rum/application/update": {
       "post": {
-        "description": "Update an existing RUM application. All fields except `application_id` are optional — only provided fields are updated.",
+        "description": "Update selected fields of a RUM application; fields left out of the request keep their current values.",
         "operationId": "rum-application-write-update",
         "requestBody": {
           "content": {
@@ -5187,6 +5417,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -5199,7 +5432,7 @@
           "RUM/Applications"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Applications Manage** (`rum`) |\n\n## Usage\n\n- `links.systems[].url` must start with `http` or `https`; `${var}` tokens are resolved from RUM event context.\n- `links.systems[].event_types` accepts: `crash`, `error`, `view`, `action`, `resource`, `session`, `all`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Applications Manage** (`rum`) |\n\n## Usage\n\n- Only fields present in the request are changed. `alerting`, `tracing` and `links` replace the whole stored object when sent; `repositories` replaces the whole list.\n- When `tracing` is sent, `open_type` (`popup` or `tab`) and an `http`/`https` `endpoint` are required even if `enabled` is `false`.\n- `links.systems[].url` must start with `http` or `https`; each system needs a `name` and at least one `event_types` entry.\n- When `alerting` is sent with `delivery_mode` `oncall`, the existing `integration_id` is kept (or one is assigned); a client-supplied `integration_id` is ignored.\n- An unknown or deleted `application_id` returns `InvalidParameter`. The caller must be able to edit the application: the account owner, an account admin, the application's creator, or a member of its owning team; anyone else gets `AccessDenied`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/rum/applications/rum-application-write-update",
           "metadata": {
             "sidebarTitle": "Update application"
@@ -5215,7 +5448,7 @@
           "content": {
             "application/json": {
               "example": {
-                "application_id": "rum-app-prod",
+                "application_id": "WoyQQ3BohkdtPivubEvE8o",
                 "webhook_url": "https://hooks.example.com/rum-alerts"
               },
               "schema": {
@@ -5277,7 +5510,7 @@
           "RUM/Applications"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Applications Manage** (`rum`) |\n\n## Usage\n\n- The endpoint validates the URL before sending the sample event.\n- A failed delivery still returns HTTP 200 with `ok=false` and the delivery error in `message`.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- The URL must use `http` or `https`; on Flashduty cloud, hosts that resolve to private, loopback, link-local or reserved addresses are rejected with `InvalidParameter`.\n- The sample body has the same shape as real alert events: `account_id`, `data_source_type` (`rum.alert`), `title`, `event_severity`, `event_status`, `description`, `alert_key`, `labels`, and `event_time` (Unix seconds).\n- Each attempt times out after 10 seconds; transport errors, 5xx and 429 responses are retried up to 2 times.\n- A failed delivery still returns HTTP 200 with `ok: false` and the reason in `message`.\n- The caller must be able to edit the application: the account owner, an account admin, the application's creator, or a member of its owning team; anyone else gets `AccessDenied`.",
           "href": "/en/api-reference/rum/applications/rum-application-webhook-test",
           "metadata": {
             "sidebarTitle": "Test application webhook"
@@ -5298,8 +5531,7 @@
                   {
                     "format": "table",
                     "id": "errors_by_type",
-                    "sql": "SELECT error.type, count(*) AS errors FROM error GROUP BY error.type ORDER BY errors DESC LIMIT 10",
-                    "time_zone": "Asia/Shanghai"
+                    "sql": "SELECT error_type, count(*) AS errors FROM errors GROUP BY error_type ORDER BY errors DESC LIMIT 10"
                   }
                 ],
                 "start_time": 1712620800000
@@ -5321,23 +5553,23 @@
                       "data": {
                         "fields": [
                           {
-                            "name": "error.type",
-                            "nullable": false,
-                            "type": "String"
+                            "name": "error_type",
+                            "nullable": true,
+                            "type": "VARCHAR"
                           },
                           {
                             "name": "errors",
                             "nullable": false,
-                            "type": "UInt64"
+                            "type": "BIGINT"
                           }
                         ],
                         "values": [
                           [
                             "TypeError",
-                            1523
+                            "ReferenceError"
                           ],
                           [
-                            "ReferenceError",
+                            1523,
                             342
                           ]
                         ]
@@ -5371,6 +5603,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -5383,7 +5618,7 @@
           "RUM/Data query"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Send 1 to 10 queries in one request; each query `id` becomes a key in the response object.\n- `start_time` and `end_time` are required Unix epoch milliseconds. The maximum time range is 31 days.\n- Use `format: table` for tabular results, or `format: time_series` for bucketed time-series results.\n- For `time_series`, `interval` defaults to 3600 seconds and `max_points` defaults to 1226 when omitted.\n- `search_after_ctx` is returned by paginated table queries and can be sent back to continue scanning.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Send 1 to 10 queries in one request; each query `id` becomes a key in the response object.\n- `start_time` and `end_time` are Unix epoch milliseconds, at most 31 days apart. The server adds the time-range and account filters itself; you do not need them in `sql`.\n- `FROM` names a RUM scope table: `sessions`, `views`, `actions`, `errors`, `resources`, `long_tasks`, `vitals`, `issues` or `sourcemaps` (the singular form is also accepted). Column names are the `field_key` values returned by `POST /rum/field/list`.\n- A query whose top-level `AND` conditions pin `application_id` (`=` or `IN`) must name applications the caller can read: a private application the caller's team does not own fails the whole request with `AccessDenied`, an unknown one with `ResourceNotFound`, and one request may name at most 50 distinct applications. A query that names no application silently skips the private applications the caller cannot read.\n- Malformed SQL, an invalid `time_zone` or an out-of-range time window fails the whole request with `InvalidParameter`. A query that fails later (unknown table or column, invalid `dql`, invalid `search_after_ctx`, database error) only sets `error` on its own entry, with code `InternalError`; the other queries still return `data`.\n- `values` is column-major: `values[i]` holds every row's value of column `fields[i]`.\n- `table` queries return at most 1,000 rows; a missing `LIMIT` or one above 1,000 is replaced with 1,000. A non-aggregate query with `ORDER BY` and no `OFFSET` returns `search_after_ctx` when the page is full — send it back with the same `sql` to get the next page.\n- `time_series` queries get a `ts` column prepended (bucket start, Unix milliseconds), grouped and ordered by it. The bucket width, returned as `interval` in milliseconds, is the smallest step from a fixed ladder (1, 2, 5, 10, 20, 50, 100, 200, 500 ms; 1, 2, 5, 10, 15, 30 s; 1, 2, 5, 10, 15, 30 min; 1, 2, 3, 6, 12 h; 1, 2, 3, 7 d; 30, 60, 90, 180 d) that is at least both `interval` and the window length divided by `max_points`.\n- On large time windows an aggregate query may run on sampled data; the response then carries `sampling`, and `COUNT`, `SUM` and `COUNT(DISTINCT)` columns are already multiplied by `scale_factor`. Set `disable_sampling: true` to always query the full data.",
           "href": "/en/api-reference/rum/data-query/rum-read-data-query",
           "metadata": {
             "sidebarTitle": "Query RUM data"
@@ -5393,43 +5628,36 @@
     },
     "/rum/error-ingestion/rules/create": {
       "post": {
-        "description": "Create a new error ingestion rule that filters which errors are stored.",
+        "description": "Create a rule whose matching errors are kept out of issue grouping; matched errors are still stored.",
         "operationId": "rum-error-ingestion-rules-create",
         "requestBody": {
           "content": {
             "application/json": {
               "example": {
                 "application_id": "WoyQQ3BohkdtPivubEvE8o",
-                "description": "Only ingest TypeError/ReferenceError from production, excluding Safari.",
+                "description": "Keep cross-origin script errors, ResizeObserver warnings, and debug pages out of issues.",
                 "filters": [
                   [
                     {
-                      "key": "error.env",
-                      "oper": "IN",
-                      "vals": [
-                        "production"
-                      ]
-                    },
-                    {
-                      "key": "error.error_type",
+                      "key": "error.error_message",
                       "oper": "IN",
                       "vals": [
-                        "TypeError",
-                        "ReferenceError"
+                        "Script error.",
+                        "ResizeObserver loop*"
                       ]
                     }
                   ],
                   [
                     {
-                      "key": "error.browser_name",
-                      "oper": "NOTIN",
+                      "key": "error.view_url",
+                      "oper": "IN",
                       "vals": [
-                        "Safari"
+                        "https://example.com/debug/*"
                       ]
                     }
                   ]
                 ],
-                "rule_name": "Production console errors"
+                "rule_name": "Ignore browser noise"
               },
               "schema": {
                 "$ref": "#/components/schemas/RumErrorIngestionCreateRequest"
@@ -5445,7 +5673,7 @@
                 "example": {
                   "data": {
                     "rule_id": "9spXEVoMeZWujjz25yrgTe",
-                    "rule_name": "Production console errors"
+                    "rule_name": "Ignore browser noise"
                   },
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 },
@@ -5474,6 +5702,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -5486,7 +5717,7 @@
           "RUM/Error ingestion rules"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Create, update, enable, disable, and delete all snapshot the application's full current rule set into history first, so `history/list` reflects every mutation.\n- Every condition key in `filters` must be one of the supported `error.*` fields or a `context.*` path; unsupported keys are rejected with `InvalidParameter`.\n- New rules are created with status `enabled`; call `disable` afterward if the rule should start inactive.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- A matched error is still stored and queryable, but is not grouped into any issue, and its `issue_grouping_excluded` field is set to `true`.\n- Rules are matched against the error's raw type and message as reported by the SDK, before the server parses the stack trace.\n- Every condition key in `filters` must be one of the supported `error.*` fields or a `context.*` path; unsupported keys, unknown operators, empty `vals`, or invalid regexp/CIDR/number patterns return `InvalidParameter`.\n- New rules start with status `enabled`; call `disable` afterward if the rule should start inactive.\n- Each write first saves the application's whole rule set, as it was before the change, as a new history version.\n- Ingestion reads enabled rules from a per-application cache that lives 5 seconds, so the change applies to newly ingested errors within about 5 seconds.\n- Requires edit access to the application (account owner or admin, the application's creator, or a member of its team); otherwise returns `AccessDenied`. An unknown `application_id` returns `ResourceNotFound`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/rum/error-ingestion-rules/rum-error-ingestion-rules-create",
           "metadata": {
             "sidebarTitle": "Create an error ingestion rule"
@@ -5545,6 +5776,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -5557,7 +5791,7 @@
           "RUM/Error ingestion rules"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- The rule disappears from `list` immediately, but the enabled-rule set used for filtering is cached for up to 5 seconds, so errors ingested shortly after deletion can still be matched against it.\n- Returns `ResourceNotFound` if `rule_id` doesn't exist under `application_id`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- The rule disappears from `list` immediately and can't be enabled or updated again; to bring it back, revert to a history version that still contains it.\n- Returns `ResourceNotFound` if `rule_id` doesn't exist (or was deleted) under `application_id`.\n- Each write first saves the application's whole rule set, as it was before the change, as a new history version.\n- Ingestion reads enabled rules from a per-application cache that lives 5 seconds, so the change applies to newly ingested errors within about 5 seconds.\n- Requires edit access to the application (account owner or admin, the application's creator, or a member of its team); otherwise returns `AccessDenied`. An unknown `application_id` returns `ResourceNotFound`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/rum/error-ingestion-rules/rum-error-ingestion-rules-delete",
           "metadata": {
             "sidebarTitle": "Delete an error ingestion rule"
@@ -5616,6 +5850,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -5628,7 +5865,7 @@
           "RUM/Error ingestion rules"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- A disabled rule is kept and still returned by `list`, but is skipped when matching incoming errors.\n- Returns `ResourceNotFound` if `rule_id` doesn't exist under `application_id`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- A disabled rule is kept and still returned by `list`, but is skipped when matching incoming errors.\n- Returns `ResourceNotFound` if `rule_id` doesn't exist (or was deleted) under `application_id`.\n- Each write first saves the application's whole rule set, as it was before the change, as a new history version.\n- Ingestion reads enabled rules from a per-application cache that lives 5 seconds, so the change applies to newly ingested errors within about 5 seconds.\n- Requires edit access to the application (account owner or admin, the application's creator, or a member of its team); otherwise returns `AccessDenied`. An unknown `application_id` returns `ResourceNotFound`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/rum/error-ingestion-rules/rum-error-ingestion-rules-disable",
           "metadata": {
             "sidebarTitle": "Disable an error ingestion rule"
@@ -5687,6 +5924,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -5699,7 +5939,7 @@
           "RUM/Error ingestion rules"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Returns `ResourceNotFound` if `rule_id` doesn't exist under `application_id`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Enabling a rule that is already enabled succeeds and still writes a history version.\n- Returns `ResourceNotFound` if `rule_id` doesn't exist (or was deleted) under `application_id`.\n- Each write first saves the application's whole rule set, as it was before the change, as a new history version.\n- Ingestion reads enabled rules from a per-application cache that lives 5 seconds, so the change applies to newly ingested errors within about 5 seconds.\n- Requires edit access to the application (account owner or admin, the application's creator, or a member of its team); otherwise returns `AccessDenied`. An unknown `application_id` returns `ResourceNotFound`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/rum/error-ingestion-rules/rum-error-ingestion-rules-enable",
           "metadata": {
             "sidebarTitle": "Enable an error ingestion rule"
@@ -5744,38 +5984,31 @@
                             "created_at": 1786000000000,
                             "created_by": 1001,
                             "deleted_at": 0,
-                            "description": "Only ingest TypeError/ReferenceError from production, excluding Safari.",
+                            "description": "Keep cross-origin script errors, ResizeObserver warnings, and debug pages out of issues.",
                             "filters": [
                               [
                                 {
-                                  "key": "error.env",
-                                  "oper": "IN",
-                                  "vals": [
-                                    "production"
-                                  ]
-                                },
-                                {
-                                  "key": "error.error_type",
+                                  "key": "error.error_message",
                                   "oper": "IN",
                                   "vals": [
-                                    "TypeError",
-                                    "ReferenceError"
+                                    "Script error.",
+                                    "ResizeObserver loop*"
                                   ]
                                 }
                               ],
                               [
                                 {
-                                  "key": "error.browser_name",
-                                  "oper": "NOTIN",
+                                  "key": "error.view_url",
+                                  "oper": "IN",
                                   "vals": [
-                                    "Safari"
+                                    "https://example.com/debug/*"
                                   ]
                                 }
                               ]
                             ],
                             "id": 1044,
                             "rule_id": "9spXEVoMeZWujjz25yrgTe",
-                            "rule_name": "Production console errors",
+                            "rule_name": "Ignore browser noise",
                             "status": "enabled",
                             "updated_at": 1786000000000,
                             "updated_by": 1001
@@ -5823,6 +6056,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -5835,7 +6071,7 @@
           "RUM/Error ingestion rules"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- One history item is a full snapshot of every rule for the application at that point in time, not a diff of a single rule.\n- `p` is a zero-based page number, not a byte offset — the server computes `offset = p * limit` internally.\n- `orderby` accepts `updated_at` or `version`; any other value silently falls back to `updated_at`.\n- `limit` defaults to 20 and is capped at 100 server-side; values above 100 are silently clamped, values of 0 or below fall back to the default.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Each write first saves the rule set as it was before the change, so version N holds the rules just before the Nth change, and its `updated_by`/`updated_at` identify that change. The current rule set is returned by `list`, not here.\n- One history item is a full snapshot of every non-deleted rule for the application, not a diff of a single rule.\n- `p` is a zero-based page number: the server skips `p * limit` items.\n- `limit` defaults to 20 and is capped at 100; values above 100 are clamped, values of 0 or below fall back to the default.\n- Any member can read a public application; a private application requires edit access (account owner or admin, its creator, or a member of its team), otherwise `AccessDenied`. An unknown `application_id` returns `ResourceNotFound`.",
           "href": "/en/api-reference/rum/error-ingestion-rules/rum-error-ingestion-rules-history-list",
           "metadata": {
             "sidebarTitle": "List error ingestion rule history"
@@ -5894,6 +6130,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -5906,7 +6145,7 @@
           "RUM/Error ingestion rules"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Revert replaces the entire rule set for the application — rules created after the target version are removed, not merged.\n- The current state is snapshotted into history before the revert runs, so a revert can itself be undone by reverting again.\n- Returns `InvalidParameter` (not `ResourceNotFound`) when `version` doesn't exist for the application.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Version N holds the rules as they were just before the Nth change, so reverting to version N undoes change N and every later change.\n- Revert replaces the entire rule set for the application: rules that are not in the target version are removed, not merged.\n- Restored rules keep their `rule_id`, name, description, filters, and status; their `created_at` and `updated_at` are reset to the revert time.\n- The current state is saved as a new history version before the revert runs, so a revert can itself be undone by reverting again.\n- Returns `InvalidParameter` (not `ResourceNotFound`) when `version` doesn't exist for the application.\n- Ingestion reads enabled rules from a per-application cache that lives 5 seconds, so the change applies to newly ingested errors within about 5 seconds.\n- Requires edit access to the application (account owner or admin, the application's creator, or a member of its team); otherwise returns `AccessDenied`. An unknown `application_id` returns `ResourceNotFound`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/rum/error-ingestion-rules/rum-error-ingestion-rules-history-revert",
           "metadata": {
             "sidebarTitle": "Revert error ingestion rules to a history version"
@@ -5940,37 +6179,30 @@
                     "items": [
                       {
                         "created_at": 1786000000000,
-                        "description": "Only ingest TypeError/ReferenceError from production, excluding Safari.",
+                        "description": "Known browser noise and errors from internal debug pages.",
                         "filters": [
                           [
                             {
-                              "key": "error.env",
-                              "oper": "IN",
-                              "vals": [
-                                "production"
-                              ]
-                            },
-                            {
-                              "key": "error.error_type",
+                              "key": "error.error_message",
                               "oper": "IN",
                               "vals": [
-                                "TypeError",
-                                "ReferenceError"
+                                "Script error.",
+                                "ResizeObserver loop*"
                               ]
                             }
                           ],
                           [
                             {
-                              "key": "error.browser_name",
-                              "oper": "NOTIN",
+                              "key": "error.view_url",
+                              "oper": "IN",
                               "vals": [
-                                "Safari"
+                                "https://example.com/debug/*"
                               ]
                             }
                           ]
                         ],
                         "rule_id": "9spXEVoMeZWujjz25yrgTe",
-                        "rule_name": "Production console errors",
+                        "rule_name": "Ignore browser noise",
                         "status": "enabled",
                         "updated_at": 1786003600000
                       }
@@ -6003,6 +6235,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -6015,7 +6250,7 @@
           "RUM/Error ingestion rules"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Deleted rules are excluded; only rules with status `enabled` or `disabled` are returned.\n- Rules are ordered newest-created first.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Deleted rules are excluded; only rules with status `enabled` or `disabled` are returned.\n- Rules are ordered newest-created first. The list is not paginated.\n- Any member can read a public application; a private application requires edit access (account owner or admin, its creator, or a member of its team), otherwise `AccessDenied`. An unknown `application_id` returns `ResourceNotFound`.",
           "href": "/en/api-reference/rum/error-ingestion-rules/rum-error-ingestion-rules-list",
           "metadata": {
             "sidebarTitle": "List error ingestion rules"
@@ -6032,7 +6267,7 @@
             "application/json": {
               "example": {
                 "application_id": "WoyQQ3BohkdtPivubEvE8o",
-                "description": "Now also excludes staging traffic.",
+                "description": "Known browser noise and errors from internal debug pages.",
                 "rule_id": "9spXEVoMeZWujjz25yrgTe"
               },
               "schema": {
@@ -6075,6 +6310,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -6087,7 +6325,7 @@
           "RUM/Error ingestion rules"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Only fields present in the request are changed; omitted fields keep their current value.\n- Calling update with no fields set is a no-op that still returns success.\n- Returns `ResourceNotFound` if `rule_id` doesn't exist under `application_id`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Only fields present in the request are changed; omitted or `null` fields keep their current value.\n- Calling update with no fields set changes nothing and writes no history version, but still returns success.\n- New `filters` are validated the same way as on `create`; invalid ones return `InvalidParameter`.\n- Returns `ResourceNotFound` if `rule_id` doesn't exist (or was deleted) under `application_id`.\n- Each write first saves the application's whole rule set, as it was before the change, as a new history version.\n- Ingestion reads enabled rules from a per-application cache that lives 5 seconds, so the change applies to newly ingested errors within about 5 seconds.\n- Requires edit access to the application (account owner or admin, the application's creator, or a member of its team); otherwise returns `AccessDenied`. An unknown `application_id` returns `ResourceNotFound`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/rum/error-ingestion-rules/rum-error-ingestion-rules-update",
           "metadata": {
             "sidebarTitle": "Update an error ingestion rule"
@@ -6104,7 +6342,7 @@
             "application/json": {
               "example": {
                 "end_time": 1712707200000,
-                "facet_key": "error.type",
+                "facet_key": "error_type",
                 "limit": 10,
                 "scope": "error",
                 "start_time": 1712620800000
@@ -6164,6 +6402,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -6176,7 +6417,7 @@
           "RUM/Facets"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **100 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Use `POST /rum/field/list` with `is_facet: true` to discover available `facet_key` values for each scope.\n- The `scope` must be one of: `session`, `view`, `action`, `error`, `resource`, `long_task`, `vital`, `issue`, `sourcemap`.\n- Pass `dql` to further filter events before counting. DQL syntax follows the RUM query language.\n- Pass `sql` with a WHERE-clause only (no SELECT) for SQL-style filtering.\n- Default limit is 100; maximum is 100.\n- Time range is required (`start_time` / `end_time` in Unix epoch **milliseconds**). Maximum span is 31 days.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **100 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Use `POST /rum/field/list` with `is_facet: true` to discover `facet_key` values for each scope.\n- `facet_key` must be a facet field (`is_facet: true`) of the requested `scope` with `show_type: list` and a non-array `value_type`; otherwise the call returns `InvalidParameter`.\n- Events where `facet_key` is `null` are not counted. Pass `facet_value` to count only events equal to that value; its JSON type must match the field's `value_type`.\n- Pass `dql` to filter events before counting. Pass `sql` as a bare `WHERE` condition; the word `SELECT` anywhere in it (case-insensitive) is rejected.\n- `limit` defaults to 100; maximum is 100.\n- `start_time` / `end_time` are required Unix epoch **milliseconds**, at most 31 days apart.\n- For `scope: sourcemap`, `type` and `kind` choose which symbol store is counted.",
           "href": "/en/api-reference/rum/facets/rum-read-facet-count",
           "metadata": {
             "sidebarTitle": "Count facet value distribution"
@@ -6213,19 +6454,20 @@
                     "items": [
                       {
                         "account_id": 0,
-                        "description": "The type of the error.",
+                        "description": "Error type or class depending on the language. Examples: `TypeError`, `NotFoundError`.",
                         "edit_able": false,
                         "enum_values": [],
-                        "field_key": "error.type",
-                        "field_name": "Error type",
-                        "group": "Error",
+                        "field_key": "error_type",
+                        "field_name": "Error Type",
+                        "group": "error",
                         "is_facet": true,
                         "queryable": true,
                         "scopes": [
-                          "error"
+                          "error",
+                          "issue"
                         ],
                         "show_type": "list",
-                        "status": "active",
+                        "status": "enabled",
                         "unit_family": "",
                         "unit_name": "",
                         "value_type": "string"
@@ -6259,6 +6501,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -6281,7 +6526,7 @@
     },
     "/rum/issue/export": {
       "post": {
-        "description": "Export the filtered RUM error tracking issues as a CSV file. The response is a `text/csv` stream delivered with `Content-Disposition: attachment` — it is not a JSON envelope; non-console callers can read the `X-Export-Total` and `X-Export-Truncated` response headers.",
+        "description": "Export the issues matching the `POST /rum/issue/list` filters as a CSV file of at most 100 rows.",
         "operationId": "rum-issue-read-export",
         "requestBody": {
           "content": {
@@ -6349,6 +6594,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -6361,7 +6609,7 @@
           "RUM/Issues"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **200 requests/day**; **100 requests/minute**; **10 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- The response is a `text/csv` stream delivered with `Content-Disposition: attachment` — it is not wrapped in the standard envelope. The filename is `rum-issues-<timestamp>.csv`, stamped in the requested `time_zone`. Read `X-Export-Total` and `X-Export-Truncated` response headers instead of a body field.\n- The export reads the first 100 matching rows (`ExportMaxRows`); `X-Export-Truncated` is `true` when more issues match. `p` and `limit` are ignored.\n- The request filters are exactly those of `POST /rum/issue/list` — an export is \"what I am looking at, as a file\".\n- `export_fields` names the CSV columns in the order they appear. Unknown keys are rejected with a parameter error; an empty array uses the default column set.\n- `time_zone` must be a valid IANA zone name (e.g. `Asia/Shanghai`, `UTC`); timestamps are rendered in that zone and time columns carry the zone in their header. Invalid names are rejected.\n- `console_origin` is used to build the `issue_url` column; the service cannot infer it (SaaS, on-premises and dev releases answer on different origins).\n- Every call is recorded in the account's audit log with the caller's member ID, request payload, and resulting error (if any). Do not put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **200 requests/day**; **100 requests/minute**; **10 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- On success the body is a `text/csv` attachment named `rum-issues-<yyyyMMdd-HHmmss>.csv` (stamped in `time_zone`), not the JSON envelope. Validation and other errors still return the JSON error envelope.\n- `X-Export-Total` carries the number of matching issues; `X-Export-Truncated` is `true` when more than 100 matched and only the first 100 (in `orderby` order) were written. `p` and `limit` are ignored.\n- The filters behave exactly as in `POST /rum/issue/list`, including the exclusion of private applications the caller cannot access.\n- `export_fields` lists the columns in output order; unknown keys are rejected, duplicates are dropped, and an empty or omitted array exports every column except the `sample_first_*` group.\n- `sample_*` columns describe the latest error event of the issue inside `[start_time, end_time]`, `sample_first_*` the earliest; they are empty when the issue has no event in that window.\n- Header titles are English, or Chinese when the request locale is Chinese (`Accept-Language` header, or `locale` / `lang` query parameter). Time columns are rendered as `yyyy-MM-dd HH:mm:ss` in `time_zone`, carry the zone in their header, and are empty when the time is unset.\n- Cells starting with `=`, `+`, `-`, `@`, tab or carriage return are prefixed with `'` so spreadsheets do not evaluate them as formulas.\n- Every call is recorded in the account's audit log with the caller's member ID, request payload, and resulting error (if any). Do not put secrets in request fields.",
           "href": "/en/api-reference/rum/issues/rum-issue-read-export",
           "metadata": {
             "sidebarTitle": "Export issues as CSV"
@@ -6413,6 +6661,7 @@
                     },
                     "resolved_at": 0,
                     "resolved_by": 0,
+                    "resolve_mode": "version",
                     "service": "fd-console",
                     "session_count": 381,
                     "severity": "Info",
@@ -6456,6 +6705,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -6468,7 +6720,7 @@
           "RUM/Issues"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- `team_id` is the owning application's **current** team; `POST /rum/issue/list` and `POST /rum/issue/export` report the team recorded when the issue was first seen, which differs once the application moves to another team.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- `team_id` is the owning application's **current** team; `POST /rum/issue/list` and `POST /rum/issue/export` report the team recorded when the issue was first seen, which differs once the application moves to another team.\n- An unknown or deleted `issue_id` returns `InvalidParameter` (\"The specified issue does not exist\"), not `ResourceNotFound`.",
           "href": "/en/api-reference/rum/issues/rum-issue-read-info",
           "metadata": {
             "sidebarTitle": "Get issue detail"
@@ -6533,6 +6785,7 @@
                         },
                         "resolved_at": 0,
                         "resolved_by": 0,
+                        "resolve_mode": "version",
                         "service": "fd-console",
                         "session_count": 381,
                         "severity": "Info",
@@ -6571,6 +6824,7 @@
                         },
                         "resolved_at": 0,
                         "resolved_by": 0,
+                        "resolve_mode": "version",
                         "service": "fd-console",
                         "session_count": 1,
                         "severity": "Info",
@@ -6617,6 +6871,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -6629,7 +6886,7 @@
           "RUM/Issues"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- `start_time` and `end_time` are millisecond timestamps. Maximum range: 183 days.\n- `statuses` filters by issue status. Valid values: `for_review`, `reviewed`, `ignored`, `resolved`.\n- `orderby` accepts: `created_at`, `updated_at`, `session_count`, `error_count`, `severity`.\n- Use `dql` or `sql` for advanced filtering. Cannot provide both.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- `start_time` and `end_time` are millisecond timestamps. Maximum range: 183 days.\n- By default an issue matches when it was created inside the window; with `by_intersection=true` it matches when it was created before `end_time` and last seen at or after `start_time`.\n- Issues of private applications are excluded unless the caller is the account owner or an admin, created the application, or belongs to its team.\n- `statuses` filters by issue status. Valid values: `for_review`, `reviewed`, `ignored`, `resolved`.\n- `orderby` accepts: `created_at`, `updated_at` (default), `session_count`, `error_count`, `severity`. With `severity`, issues without a severity always sort last.\n- Use `dql` or `sql` for advanced filtering. Cannot provide both.",
           "href": "/en/api-reference/rum/issues/rum-issue-read-list",
           "metadata": {
             "sidebarTitle": "List issues"
@@ -6712,6 +6969,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -6724,7 +6984,7 @@
           "RUM/Issue preset severity rules"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- `filters.*.key` accepts only a fixed set of Error-level attributes; any other key returns `InvalidParameter`.\n- Pass at least one condition group: an empty `filters` array is accepted but produces a rule that can never match.\n- The new rule is created enabled and appended with the lowest evaluation precedence (`priority` = current max + 1); use the `reorder` operation to move it earlier.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- `filters.*.key` accepts only a fixed set of Error-level attributes; any other key returns `InvalidParameter`.\n- Pass at least one condition group: an empty `filters` array is accepted but produces a rule that can never match.\n- The new rule is created enabled and appended with the lowest evaluation precedence (`priority` = current max + 1); use the `reorder` operation to move it earlier.\n- Requires edit rights on the application (account owner or admin, the application's creator, or a member of its team); otherwise returns `AccessDenied`. An unknown `application_id` returns `ResourceNotFound`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/rum/issue-preset-severity-rules/rum-issue-preset-severity-rules-create",
           "metadata": {
             "sidebarTitle": "Create preset severity rule"
@@ -6755,7 +7015,6 @@
             "content": {
               "application/json": {
                 "example": {
-                  "data": {},
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 },
                 "schema": {
@@ -6783,6 +7042,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -6795,7 +7057,7 @@
           "RUM/Issue preset severity rules"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Returns `ResourceNotFound` if `rule_id` does not exist in the application.\n- Deletion is a soft delete: the rule stops being listed immediately, but enabled rules are cached for up to 5 seconds, so it can still be evaluated against errors ingested shortly afterwards. Its pre-delete state remains visible via the history endpoints.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Returns `ResourceNotFound` if `rule_id` does not exist in the application.\n- Deletion is a soft delete: the rule stops being listed immediately, but enabled rules are cached for up to 5 seconds, so it can still be evaluated against errors ingested shortly afterwards. Its pre-delete state remains visible via the history endpoints.\n- Requires edit rights on the application (account owner or admin, the application's creator, or a member of its team); otherwise returns `AccessDenied`. An unknown `application_id` returns `ResourceNotFound`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/rum/issue-preset-severity-rules/rum-issue-preset-severity-rules-delete",
           "metadata": {
             "sidebarTitle": "Delete preset severity rule"
@@ -6826,7 +7088,6 @@
             "content": {
               "application/json": {
                 "example": {
-                  "data": {},
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 },
                 "schema": {
@@ -6854,6 +7115,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -6866,7 +7130,7 @@
           "RUM/Issue preset severity rules"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Returns `ResourceNotFound` if `rule_id` does not exist in the application.\n- A disabled rule is skipped during evaluation but keeps its `priority` slot; the cache can take up to 5 seconds to reflect the change.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Returns `ResourceNotFound` if `rule_id` does not exist in the application.\n- A disabled rule is skipped during evaluation but keeps its `priority` slot; the cache can take up to 5 seconds to reflect the change.\n- Requires edit rights on the application (account owner or admin, the application's creator, or a member of its team); otherwise returns `AccessDenied`. An unknown `application_id` returns `ResourceNotFound`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/rum/issue-preset-severity-rules/rum-issue-preset-severity-rules-disable",
           "metadata": {
             "sidebarTitle": "Disable preset severity rule"
@@ -6897,7 +7161,6 @@
             "content": {
               "application/json": {
                 "example": {
-                  "data": {},
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 },
                 "schema": {
@@ -6925,6 +7188,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -6937,7 +7203,7 @@
           "RUM/Issue preset severity rules"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Returns `ResourceNotFound` if `rule_id` does not exist in the application.\n- Enabled rules are cached for up to 5 seconds, so the effect on newly ingested errors can lag by a few seconds.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Returns `ResourceNotFound` if `rule_id` does not exist in the application.\n- Enabled rules are cached for up to 5 seconds, so the effect on newly ingested errors can lag by a few seconds.\n- Requires edit rights on the application (account owner or admin, the application's creator, or a member of its team); otherwise returns `AccessDenied`. An unknown `application_id` returns `ResourceNotFound`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/rum/issue-preset-severity-rules/rum-issue-preset-severity-rules-enable",
           "metadata": {
             "sidebarTitle": "Enable preset severity rule"
@@ -7113,6 +7379,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -7125,7 +7394,7 @@
           "RUM/Issue preset severity rules"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Each entry is an application-level snapshot of every rule as it existed immediately *before* the mutation that produced it — not a diff. A fresh snapshot is written before every create/update/enable/disable/delete/reorder/revert call that actually changes something — an `update` carrying none of the mutable fields returns success without writing one — so `version=1` is typically an empty rule set captured just before the first rule was ever created.\n- `rules` items carry the full internal row (including `account_id`, `created_by`, `id`, `deleted_at`), which is a wider shape than the one returned by `rules/list`.\n- `limit` defaults to 20 and is silently capped at 100 rather than rejected.\n- `orderby` accepts only `updated_at` or `version`; any other value (including omitted) falls back to `updated_at` rather than erroring.\n- Results sort descending by default; pass `asc=true` for ascending order.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Each entry is an application-level snapshot of every rule as it existed immediately *before* the mutation that produced it — not a diff. A snapshot is written before every successful create/update/enable/disable/delete/reorder/revert call, even one that leaves the rules unchanged (for example enabling a rule that is already enabled); only an `update` carrying none of the mutable fields skips it. `version=1` is therefore typically an empty rule set captured just before the first rule was created.\n- `rules` items carry the full internal row (including `account_id`, `created_by`, `id`, `deleted_at`), which is a wider shape than the one returned by `rules/list`.\n- `limit` defaults to 20 and is silently capped at 100 rather than rejected.\n- `orderby` accepts only `updated_at` or `version`; any other value (including omitted) falls back to `updated_at` rather than erroring.\n- Results sort descending by default; pass `asc=true` for ascending order.\n- Rules of a private application can be read only by callers with edit rights on it (account owner or admin, its creator, or a member of its team); others get `AccessDenied`. An unknown `application_id` returns `ResourceNotFound`.",
           "href": "/en/api-reference/rum/issue-preset-severity-rules/rum-issue-preset-severity-rules-history-list",
           "metadata": {
             "sidebarTitle": "List preset severity rule history"
@@ -7156,7 +7425,6 @@
             "content": {
               "application/json": {
                 "example": {
-                  "data": {},
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 },
                 "schema": {
@@ -7184,6 +7452,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -7196,7 +7467,7 @@
           "RUM/Issue preset severity rules"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Replaces the entire current rule set with the snapshot's rows: `rule_id`, `priority`, `filters`, `severity`, `status`, and `created_by` are preserved from the snapshot, but `created_at`/`updated_at` are reset to the revert time and `updated_by` is set to the reverting user.\n- Returns `InvalidParameter` (not `ResourceNotFound`) when `version` does not correspond to an existing history snapshot for the application.\n- The revert itself is captured as a new history snapshot before it is applied, so a revert can itself be reverted.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Replaces the entire current rule set with the snapshot's rows: `rule_id`, `priority`, `filters`, `severity`, `status`, and `created_by` are preserved from the snapshot, but `created_at`/`updated_at` are reset to the revert time and `updated_by` is set to the reverting user.\n- Returns `InvalidParameter` (not `ResourceNotFound`) when `version` does not correspond to an existing history snapshot for the application.\n- The revert itself is captured as a new history snapshot before it is applied, so a revert can itself be reverted.\n- Requires edit rights on the application (account owner or admin, the application's creator, or a member of its team); otherwise returns `AccessDenied`. An unknown `application_id` returns `ResourceNotFound`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/rum/issue-preset-severity-rules/rum-issue-preset-severity-rules-history-revert",
           "metadata": {
             "sidebarTitle": "Revert preset severity rules to a history snapshot"
@@ -7306,6 +7577,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -7318,7 +7592,7 @@
           "RUM/Issue preset severity rules"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Rules are returned ordered by `priority` ascending, then `created_at` ascending — the same order they are evaluated in.\n- Only enabled rules are evaluated against incoming errors; the first enabled rule (in priority order) whose filters match an error wins and assigns its `severity`. Errors matching no enabled rule keep their default severity.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Rules are returned ordered by `priority` ascending, then `created_at` ascending — the same order they are evaluated in.\n- Only enabled rules are evaluated against incoming errors; the first enabled rule (in priority order) whose filters match an error wins and assigns its `severity`. Errors matching no enabled rule get a built-in severity: crashes are `Critical`, other errors are scored by environment and message keywords.\n- Severity is decided once, when an error creates a new issue; a rule change affects only errors ingested afterwards (enabled rules are cached for up to 5 seconds) and never re-grades existing issues.\n- Rules of a private application can be read only by callers with edit rights on it (account owner or admin, its creator, or a member of its team); others get `AccessDenied`. An unknown `application_id` returns `ResourceNotFound`.",
           "href": "/en/api-reference/rum/issue-preset-severity-rules/rum-issue-preset-severity-rules-list",
           "metadata": {
             "sidebarTitle": "List preset severity rules"
@@ -7350,7 +7624,6 @@
             "content": {
               "application/json": {
                 "example": {
-                  "data": {},
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 },
                 "schema": {
@@ -7378,6 +7651,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -7390,7 +7666,7 @@
           "RUM/Issue preset severity rules"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- This moves exactly one rule, not a full reordering: `drag_rule_id`'s `priority` is set to `target_rule_id`'s current `priority`, and every rule between the two original positions — the target rule itself included — shifts by one to close the gap.\n- Lower `priority` numbers are evaluated first; moving toward a lower-numbered target moves the rule earlier in evaluation order, and toward a higher-numbered target moves it later.\n- Returns `ResourceNotFound` if either `drag_rule_id` or `target_rule_id` does not exist in the application.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- This moves exactly one rule, not a full reordering: `drag_rule_id`'s `priority` is set to `target_rule_id`'s current `priority`, and every rule between the two original positions — the target rule itself included — shifts by one to close the gap.\n- Lower `priority` numbers are evaluated first; moving toward a lower-numbered target moves the rule earlier in evaluation order, and toward a higher-numbered target moves it later.\n- Returns `ResourceNotFound` if either `drag_rule_id` or `target_rule_id` does not exist in the application.\n- Requires edit rights on the application (account owner or admin, the application's creator, or a member of its team); otherwise returns `AccessDenied`. An unknown `application_id` returns `ResourceNotFound`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/rum/issue-preset-severity-rules/rum-issue-preset-severity-rules-reorder",
           "metadata": {
             "sidebarTitle": "Reorder preset severity rule"
@@ -7423,7 +7699,6 @@
             "content": {
               "application/json": {
                 "example": {
-                  "data": {},
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 },
                 "schema": {
@@ -7451,6 +7726,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -7463,7 +7741,7 @@
           "RUM/Issue preset severity rules"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Only fields present in the request are changed; omitted fields keep their current value.\n- Returns `ResourceNotFound` if `rule_id` does not exist in the application.\n- If `filters` is provided it replaces the entire filter structure and is revalidated against the same allowed key set as `create`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Only fields present in the request are changed; omitted fields keep their current value.\n- Returns `ResourceNotFound` if `rule_id` does not exist in the application.\n- If `filters` is provided it replaces the entire filter structure and is revalidated against the same allowed key set as `create`.\n- Requires edit rights on the application (account owner or admin, the application's creator, or a member of its team); otherwise returns `AccessDenied`. An unknown `application_id` returns `ResourceNotFound`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/rum/issue-preset-severity-rules/rum-issue-preset-severity-rules-update",
           "metadata": {
             "sidebarTitle": "Update preset severity rule"
@@ -7522,6 +7800,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -7534,7 +7815,7 @@
           "RUM/Issues"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- `status` valid values: `for_review`, `reviewed`, `ignored`, `resolved`.\n- `suspected_cause` valid values: `api.failed_request`, `network.error`, `code.exception`, `code.invalid_object_access`, `code.invalid_argument`, `unknown`.\n- Setting `status` to `resolved` also stamps `resolved_at` and `resolved_by` on the issue; moving a resolved issue back to another status clears them.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Only the fields you send are applied; sending a `status` equal to the current one changes nothing.\n- Setting `status` to `resolved` on an unresolved issue stamps `resolved_at` and `resolved_by` and clears `regression`; moving a resolved issue to another status clears `resolved_at` and `resolved_by`.\n- `resolve_mode` is applied only together with `status: resolved`, and defaults to `any` when omitted there; send it with `status: resolved` on an already resolved issue to change only the mode.\n- When the application's alerting is enabled, resolving an issue sends its recovery alert right away.\n- Setting `suspected_cause` marks the cause as user-set (`suspected_cause.source` = `user`, `person_id` = caller), and automatic analysis no longer overwrites it.\n- An unknown `issue_id` returns `InvalidParameter` (\"The specified issue does not exist\").\n- Every call is recorded in the account audit log. Don't put secrets in request fields.",
           "href": "/en/api-reference/rum/issues/rum-issue-write-update",
           "metadata": {
             "sidebarTitle": "Update issue"
@@ -7618,6 +7899,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -7630,7 +7914,7 @@
           "RUM/Resources"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Returns `ResourceNotFound` when the account has no RUM resource provisioned yet, or when the resource's status is `deleted`/`destroyed`.\n- `no_cache=true` bypasses the short-lived cache of the resource record itself (plan version, quotas, status). The `used_cnt` figures come from a separate hourly cache that this flag does not affect, so they can lag behind live usage either way.\n- The used-count fields reflect the current 30-day billing window (`window_start_time` to `window_end_time`), not lifetime totals.\n- `expired_at` is only populated on on-premises deployments, from the license expiry date; it is omitted entirely for SaaS accounts.\n- For `version=free` accounts, `session_limit_reached` is `true` once usage exceeds the combined free quota across all applications (per-app free quota × application count); it stays `false` while the account has no applications yet.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Returns `ResourceNotFound` when the account has no RUM resource provisioned yet, or when the resource's status is `deleted`/`destroyed`.\n- `no_cache=true` bypasses the short-lived cache of the resource record itself (plan version, quotas, status). The `used_cnt` figures come from a separate hourly cache that this flag does not affect, so they can lag behind live usage either way.\n- The used-count fields reflect the current 30-day billing window (`window_start_time` to `window_end_time`), not lifetime totals.\n- A negative `free_cnt` means the quota is unlimited.\n- `expired_at` is only populated on on-premises deployments, from the license expiry date; it is omitted entirely for SaaS accounts.\n- For `version=free` accounts, `session_limit_reached` becomes `true` once investigate or replay usage reaches the per-application free quota × the number of applications (measure sessions are not counted); it stays `false` while the account has no applications.",
           "href": "/en/api-reference/rum/resources/rum-resource-read-info",
           "metadata": {
             "sidebarTitle": "Get RUM resource info"
@@ -7677,8 +7961,6 @@
                     },
                     "views": [
                       {
-                        "container_source": "",
-                        "container_view_id": "",
                         "end": 1752480600000,
                         "is_active": false,
                         "loading_type": "initial_load",
@@ -7718,6 +8000,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -7730,7 +8015,7 @@
           "RUM/Session replay"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Returns `InvalidParameter` if the session does not exist, or if it has no replay data recorded (`session_has_replay` is false).\n- Returns `InvalidParameter` if no views are found within the session's time window.\n- Pass `ts` to disambiguate when a `session_id` has been reused across different time windows.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Returns `InvalidParameter` if the session does not exist, or if it has no replay data recorded (`session_has_replay` is false).\n- Returns `InvalidParameter` if no view with replay data is found between the session start and 4 hours after its recorded end.\n- `ts` must equal the session's start time exactly (Unix milliseconds); any other value makes the session lookup miss and returns `InvalidParameter`.\n- All timestamps are client times; no clock-skew correction is applied (`server_time_delta` is always `0`).",
           "href": "/en/api-reference/rum/session-replay/rum-session-replay-read-metadata",
           "metadata": {
             "sidebarTitle": "Get session replay metadata"
@@ -7746,7 +8031,7 @@
           "content": {
             "application/json": {
               "example": {
-                "limit": 20,
+                "limit": 2,
                 "session_id": "0a4a2e64-8a4f-4b9a-9c1e-3a2f9e6d7c81",
                 "url_mode": true
               },
@@ -7764,8 +8049,8 @@
                 "example": {
                   "data": {
                     "items": [
-                      "https://rum-replay.flashcat.cloud/short-term/2451002751131/0a4a2e64-8a4f-4b9a-9c1e-3a2f9e6d7c81/segments/1752480001234?X-Amz-Signature=example",
-                      "https://rum-replay.flashcat.cloud/short-term/2451002751131/0a4a2e64-8a4f-4b9a-9c1e-3a2f9e6d7c81/segments/1752480032456?X-Amz-Signature=example"
+                      "https://replay-storage.example.com/short-term/2451002751131/0a4a2e64-8a4f-4b9a-9c1e-3a2f9e6d7c81/segments/1752480001234?X-Amz-Signature=example",
+                      "https://replay-storage.example.com/short-term/2451002751131/0a4a2e64-8a4f-4b9a-9c1e-3a2f9e6d7c81/segments/1752480032456?X-Amz-Signature=example"
                     ],
                     "search_after_ctx": "c2hvcnQtdGVybS8yNDUxMDAyNzUxMTMxLzBhNGEyZTY0LThhNGYtNGI5YS05YzFlLTNhMmY5ZTZkN2M4MS9zZWdtZW50cy8xNzUyNDgwMDMyNDU2"
                   },
@@ -7810,6 +8095,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -7822,7 +8110,7 @@
           "RUM/Session replay"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- When `url_mode` is `false` (default), the response streams `application/x-ndjson` — one decompressed replay segment JSON object per line — and is **not** wrapped in the standard envelope. The pagination cursor for the next call is returned in the `X-Search-After-Ctx` response header instead of a body field.\n- When `url_mode` is `true`, the response is a normal JSON envelope containing presigned download URLs (valid 1 hour) instead of the raw segment bytes.\n- Pass `ts` to seek to the most recent full-snapshot segment at or before that time, instead of paging from the start of the session.\n- `limit` accepts 1-99; values of 100 or more are rejected.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- When `url_mode` is `false` (default), the response streams `application/x-ndjson` — one decompressed replay segment JSON object per line — and is **not** wrapped in the standard envelope. The pagination cursor for the next call is returned in the `X-Search-After-Ctx` response header instead of a body field. A segment that cannot be read is skipped silently.\n- When `url_mode` is `true`, the response is a normal JSON envelope containing presigned download URLs (valid 1 hour) for the zlib-compressed segment objects.\n- Pass `ts` (without `search_after_ctx`) to start from the last full-snapshot segment at or before that time, searching up to 4 hours back; if none is found, paging starts from the beginning.\n- A cursor is returned whenever a page is full (`limit` segments), so the last page can be empty.\n- `limit` accepts 1-99; values of 100 or more are rejected.",
           "href": "/en/api-reference/rum/session-replay/rum-session-replay-read-segments",
           "metadata": {
             "sidebarTitle": "List session replay segments"
@@ -7865,16 +8153,21 @@
                         "created_at": 1712700000,
                         "git_commit_sha": "abc1234def5678",
                         "git_repository_url": "https://github.com/example/my-web-app",
-                        "key": "browser/my-web-app/1.0.0/main.js.map",
-                        "metadata": {},
+                        "key": "3f9a1c2e7b8d4e6f9a0b1c2d3e4f5a6b",
+                        "metadata": {
+                          "minified_url": "https://cdn.example.com/static/js/main.js"
+                        },
+                        "minified_path": "/js_sourcemap/my-web-app/1.0.0/static/js/main.js",
+                        "minified_url": "https://cdn.example.com/static/js/main.js",
                         "service": "my-web-app",
                         "size": 204800,
+                        "sourcemap_path": "/js_sourcemap/my-web-app/1.0.0/static/js/main.js.map",
                         "type": "browser",
                         "updated_at": 1712700000,
                         "version": "1.0.0"
                       }
                     ],
-                    "total": 3
+                    "total": 1
                   },
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 },
@@ -7903,6 +8196,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -7915,7 +8211,7 @@
           "RUM/Sourcemaps"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- `start_time` and `end_time` are required — both use Unix epoch **milliseconds**. Maximum window is 365 days.\n- The `type` field selects the platform: `browser` (JavaScript), `android`, or `ios`. Defaults to `browser` when omitted.\n- Default page size is 20; maximum is 100. Default sort is `created_at` descending.\n- For Android, `build_id` matches the Gradle plugin build identifier. For iOS, `uuid` matches the dSYM bundle UUID.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- `start_time` and `end_time` are required — both use Unix epoch **milliseconds** and filter by upload time. Maximum window is 365 days.\n- `type` selects the platform store: `browser`, `android`, `ios`, `miniprogram`, `react-native`, `harmony`, `flutter` or `electron`. Defaults to `browser` when omitted; any other value (including `web`) returns an empty result.\n- `kind: native` switches `android` and `harmony` to their native `.so` symbol stores.\n- Default page size is 20; maximum is 100. Default sort is `created_at` descending.\n- `build_id`, `uuid` and `query` are substring matches. `uuid` and iOS `query` values are upper-cased and stripped of hyphens before matching.\n- When nothing matches, both `items` and `total` are omitted and `data` is an empty object.",
           "href": "/en/api-reference/rum/sourcemaps/sourcemap-read-list",
           "metadata": {
             "sidebarTitle": "List sourcemaps"
@@ -7925,7 +8221,7 @@
     },
     "/sourcemap/stack/enrich": {
       "post": {
-        "description": "Symbolicate or deobfuscate a browser, Android, iOS, Mini Program, or HarmonyOS stack trace.",
+        "description": "Symbolicate or deobfuscate a stack trace with the sourcemaps or symbol files uploaded for a service version.",
         "operationId": "sourcemap-read-stack-enrich",
         "requestBody": {
           "content": {
@@ -8003,6 +8299,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -8015,7 +8314,7 @@
           "RUM/Sourcemaps"
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- `type` defaults to `browser` when omitted for backward compatibility.\n- Set `near` from 1 to 20 to include source-code snippets around converted frames.\n- For Android NDK native crashes, provide `arch` and `source_type: ndk` so the backend routes to native symbolication.\n- For iOS crash stacks, pass `binary_images` so addresses can be relocated against the uploaded dSYM files.\n- `no_cache` is intended for debugging and bypasses cached enrich results.",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- `type` defaults to `browser` when omitted.\n- `service` and `version` must match the values used at upload time; frames with no matching symbols come back with `converted: false`.\n- Set `near` from 1 to 20 to include source-code snippets around converted frames.\n- `source_type` (the error's `error.source_type`) can reroute the request: with `type: android`, a value containing `ndk` — or an empty value plus `arch` — uses NDK native symbols; with `type: flutter` or `react-native`, `ios` uses dSYM and `android`/`ndk` uses Android symbols; with `type: electron`, `macos`/`windows`/`linux` uses Breakpad symbols for minidump frames.\n- For iOS crash stacks, pass `binary_images` so addresses can be relocated against the uploaded dSYM files.\n- Results are cached per stack; `no_cache: true` bypasses the cache and is intended for debugging.",
           "href": "/en/api-reference/rum/sourcemaps/sourcemap-read-stack-enrich",
           "metadata": {
             "sidebarTitle": "Enrich a stack trace"
@@ -8073,4 +8372,4 @@
       "name": "RUM/Resources"
     }
   ]
-}
\ No newline at end of file
+}
diff --git a/api-reference/rum.openapi.zh.json b/api-reference/rum.openapi.zh.json
index f447f52fe..2e2384743 100644
--- a/api-reference/rum.openapi.zh.json
+++ b/api-reference/rum.openapi.zh.json
@@ -41,7 +41,7 @@
             }
           }
         },
-        "description": "app_key 有效但没有执行该操作的权限。"
+        "description": "app_key 有效，但其权限范围或创建者角色不允许该操作或该对象。"
       },
       "NotFound": {
         "content": {
@@ -104,7 +104,16 @@
             }
           }
         },
-        "description": "命中限流。可能是全局 API 限流、账户级限流或集成级限流。限流按账户聚合。"
+        "description": "触发频率限制（账户级限制或该接口的平台级上限）。请等待响应头 `Flashcat-Request-Rate-Limit-Delay` 给出的秒数后重试。",
+        "headers": {
+          "Flashcat-Request-Rate-Limit-Delay": {
+            "description": "距当前限流窗口重置的秒数。请求被网关全局保护限流拒绝时不返回该响应头。",
+            "schema": {
+              "type": "integer",
+              "minimum": 0
+            }
+          }
+        }
       },
       "Unauthorized": {
         "content": {
@@ -136,9 +145,9 @@
             "$ref": "#/components/schemas/ErrorCode"
           },
           "message": {
-            "description": "用户可读的错误描述，语言会跟随调用方的 Accept-Language。可能包含字段名、ID 等请求上下文。",
-            "example": "The specified parameter template_id is not valid.",
-            "type": "string"
+            "type": "string",
+            "description": "按响应语言（query 参数 `locale` / `lang` 或请求头 `Accept-Language`）返回的错误描述，可能包含出错的字段名，请不要解析它。",
+            "example": "The specified parameter template_id is not valid."
           }
         },
         "required": [
@@ -148,12 +157,12 @@
         "type": "object"
       },
       "EmptyResponse": {
-        "description": "空响应体。成功时服务端返回 `data: null`。",
+        "description": "无返回数据。不同接口的 `data` 可能是 `{}`，也可能不出现在响应中；请只根据 HTTP 200 且没有 `error` 判断成功。",
         "properties": {},
         "type": "object"
       },
       "ErrorCode": {
-        "description": "Flashduty 错误码枚举。每个失败响应的 `error.code` 都是下列稳定值之一，HTTP 状态码仅作参考。\n\n| 错误码 | HTTP | 含义 |\n|---|---|---|\n| `OK` | 200 | 保留值，正常错误响应不会返回。 |\n| `InvalidParameter` | 400 | 必填参数缺失或未通过校验。 |\n| `BadRequest` | 400 | 通用的 400 错误，通常是请求本身不合法。 |\n| `InvalidContentType` | 400 | 请求头 `Content-Type` 不是 `application/json`。 |\n| `ResourceNotFound` | 400 | 目标资源不存在。注意 HTTP 状态码是 400 而非 404（历史设计）。 |\n| `NoLicense` | 400 | 功能需要有效授权，但未找到可用的 license。 |\n| `ReferenceExist` | 400 | 该资源仍被其他实体引用，无法删除。 |\n| `Unauthorized` | 401 | `app_key` 缺失、无效或已过期。 |\n| `BalanceNotEnough` | 402 | 账户余额不足，无法执行需要计费的操作。 |\n| `AccessDenied` | 403 | 身份认证通过，但 RBAC 权限不足以执行该操作。 |\n| `RouteNotFound` | 404 | 请求的 URL 路径不是已知路由。 |\n| `MethodNotAllowed` | 405 | 当前路径不接受所使用的 HTTP 方法。 |\n| `UndonedOrderExist` | 409 | 账户存在未完成的订单，请稍后重试。 |\n| `RequestLocked` | 423 | 因连续失败被临时锁定。 |\n| `EntityTooLarge` | 413 | 请求体超过允许的最大长度。 |\n| `RequestTooFrequently` | 429 | 命中限流（全局、账户级或集成级）。 |\n| `RequestVerifyRequired` | 428 | 操作需要二次验证码，但未提供。 |\n| `DangerousOperation` | 428 | 危险操作，需要进行 MFA 验证。 |\n| `InternalError` | 500 | 服务端未预期错误。反馈问题请附上 `request_id`。 |\n| `ServiceUnavailable` | 503 | 后端依赖不可用，请稍后重试。 |",
+        "description": "错误码。所有失败响应都会把 `error.code` 设为下列稳定字符串之一，请以它而不是 HTTP 状态码做判断。\n\n| 错误码 | HTTP | 含义 |\n|---|---|---|\n| `OK` | 200 | 保留值，失败的请求不会返回。 |\n| `InvalidParameter` | 400 | 参数缺失、类型错误或未通过校验，`message` 通常会指出字段名。 |\n| `BadRequest` | 400 | 请求违反业务规则或与对象当前状态冲突，`message` 会说明原因。 |\n| `InvalidContentType` | 400 | 请求体没有以 `application/json` 发送。 |\n| `ResourceNotFound` | 400 | 引用的对象在本账户中不存在或已删除。注意 HTTP 状态码是 400 而不是 404。 |\n| `NoLicense` | 400 | 账户套餐不包含该功能、套餐配额已用完、套餐已过期或额度不足。 |\n| `ReferenceExist` | 400 | 对象仍被其他对象引用，无法删除。 |\n| `Unauthorized` | 401 | APP Key 缺失、无效或已删除。 |\n| `BalanceNotEnough` | 402 | 仅用于控制台计费流程，Open API 接口不会返回。 |\n| `AccessDenied` | 403 | APP Key 的权限范围或创建者角色不允许该操作或该对象。 |\n| `RouteNotFound` | 404 | 没有与该 HTTP 方法和路径匹配的接口。 |\n| `MethodNotAllowed` | 405 | 路径存在，但不支持该 HTTP 方法。 |\n| `UndonedOrderExist` | 409 | 仅用于控制台计费流程，Open API 接口不会返回。 |\n| `EntityTooLarge` | 413 | 请求体超出大小限制。 |\n| `RequestLocked` | 423 | 仅用于控制台登录保护，Open API 接口不会返回。 |\n| `RequestVerifyRequired` | 428 | 仅用于控制台验证码流程，Open API 接口不会返回。 |\n| `DangerousOperation` | 428 | 仅用于控制台高风险操作的 MFA 校验，Open API 接口不会返回。 |\n| `RequestTooFrequently` | 429 | 触发频率限制；请等待响应头 `Flashcat-Request-Rate-Limit-Delay` 给出的秒数后再重试。 |\n| `InternalError` | 500 | 服务端意外错误；请退避后重试，反馈问题时附上 `request_id`。 |\n| `ServiceUnavailable` | 503 | 后端依赖过载或不可用，请退避后重试。 |",
         "enum": [
           "OK",
           "InvalidParameter",
@@ -168,37 +177,37 @@
           "RouteNotFound",
           "MethodNotAllowed",
           "UndonedOrderExist",
-          "RequestLocked",
           "EntityTooLarge",
-          "RequestTooFrequently",
+          "RequestLocked",
           "RequestVerifyRequired",
           "DangerousOperation",
+          "RequestTooFrequently",
           "InternalError",
           "ServiceUnavailable"
         ],
         "example": "InvalidParameter",
         "type": "string",
         "x-enumDescriptions": {
-          "AccessDenied": "身份认证通过，但 RBAC 权限不足以执行该操作。",
-          "BadRequest": "通用的 400 错误，通常是请求本身不合法。",
-          "BalanceNotEnough": "账户余额不足，无法执行需要计费的操作。",
-          "DangerousOperation": "危险操作，需要进行 MFA 验证。",
-          "EntityTooLarge": "请求体超过允许的最大长度。",
-          "InternalError": "服务端未预期错误。反馈问题请附上 `request_id`。",
-          "InvalidContentType": "请求头 `Content-Type` 不是 `application/json`。",
-          "InvalidParameter": "必填参数缺失或未通过校验。",
-          "MethodNotAllowed": "当前路径不接受所使用的 HTTP 方法。",
-          "NoLicense": "功能需要有效授权，但未找到可用的 license。",
-          "OK": "保留值，正常错误响应不会返回。",
-          "ReferenceExist": "该资源仍被其他实体引用，无法删除。",
-          "RequestLocked": "因连续失败被临时锁定。",
-          "RequestTooFrequently": "命中限流（全局、账户级或集成级）。",
-          "RequestVerifyRequired": "操作需要二次验证码，但未提供。",
-          "ResourceNotFound": "目标资源不存在。注意 HTTP 状态码是 400 而非 404（历史设计）。",
-          "RouteNotFound": "请求的 URL 路径不是已知路由。",
-          "ServiceUnavailable": "后端依赖不可用，请稍后重试。",
-          "Unauthorized": "`app_key` 缺失、无效或已过期。",
-          "UndonedOrderExist": "账户存在未完成的订单，请稍后重试。"
+          "OK": "保留值，失败的请求不会返回。",
+          "InvalidParameter": "参数缺失、类型错误或未通过校验，`message` 通常会指出字段名。",
+          "BadRequest": "请求违反业务规则或与对象当前状态冲突，`message` 会说明原因。",
+          "InvalidContentType": "请求体没有以 `application/json` 发送。",
+          "ResourceNotFound": "引用的对象在本账户中不存在或已删除。注意 HTTP 状态码是 400 而不是 404。",
+          "NoLicense": "账户套餐不包含该功能、套餐配额已用完、套餐已过期或额度不足。",
+          "ReferenceExist": "对象仍被其他对象引用，无法删除。",
+          "Unauthorized": "APP Key 缺失、无效或已删除。",
+          "BalanceNotEnough": "仅用于控制台计费流程，Open API 接口不会返回。",
+          "AccessDenied": "APP Key 的权限范围或创建者角色不允许该操作或该对象。",
+          "RouteNotFound": "没有与该 HTTP 方法和路径匹配的接口。",
+          "MethodNotAllowed": "路径存在，但不支持该 HTTP 方法。",
+          "UndonedOrderExist": "仅用于控制台计费流程，Open API 接口不会返回。",
+          "EntityTooLarge": "请求体超出大小限制。",
+          "RequestLocked": "仅用于控制台登录保护，Open API 接口不会返回。",
+          "RequestVerifyRequired": "仅用于控制台验证码流程，Open API 接口不会返回。",
+          "DangerousOperation": "仅用于控制台高风险操作的 MFA 校验，Open API 接口不会返回。",
+          "RequestTooFrequently": "触发频率限制；请等待响应头 `Flashcat-Request-Rate-Limit-Delay` 给出的秒数后再重试。",
+          "InternalError": "服务端意外错误；请退避后重试，反馈问题时附上 `request_id`。",
+          "ServiceUnavailable": "后端依赖过载或不可用，请退避后重试。"
         }
       },
       "ErrorResponse": {
@@ -242,7 +251,7 @@
         "description": "获取远程配置请求",
         "properties": {
           "application_id": {
-            "description": "RUM 应用 ID。",
+            "description": "RUM 应用 ID，可通过 `POST /rum/application/list` 获取。",
             "type": "string"
           }
         },
@@ -255,7 +264,15 @@
         "description": "当前生效的远程配置及其版本。",
         "properties": {
           "config": {
-            "$ref": "#/components/schemas/RemoteConfig"
+            "anyOf": [
+              {
+                "$ref": "#/components/schemas/RemoteConfig"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "线上生效的配置（最新发布的版本）。应用从未配置过时为 `null`。"
           },
           "updated_at": {
             "description": "Unix 时间戳（毫秒）—— 当前版本发布时间。从未配置时为 0。",
@@ -267,13 +284,18 @@
             "type": "integer"
           }
         },
-        "type": "object"
+        "type": "object",
+        "required": [
+          "config",
+          "version",
+          "updated_at"
+        ]
       },
       "ListRemoteConfigHistoryRequest": {
         "description": "远程配置历史查询请求。默认按最新在前排序。",
         "properties": {
           "application_id": {
-            "description": "RUM 应用 ID。",
+            "description": "RUM 应用 ID，可通过 `POST /rum/application/list` 获取。",
             "type": "string"
           },
           "asc": {
@@ -282,13 +304,12 @@
           },
           "limit": {
             "default": 20,
-            "description": "每页条数。默认 20，最大 100。",
-            "maximum": 100,
+            "description": "每页条数。`0` 或负数按 20 处理；大于 100 时按 100 处理。",
             "type": "integer"
           },
           "orderby": {
             "default": "updated_at",
-            "description": "排序字段。默认 `updated_at`。",
+            "description": "排序字段：\n\n- `updated_at`：发布时间（默认）。\n- `version`：版本号。\n\n其他取值会回退为 `updated_at`。",
             "enum": [
               "updated_at",
               "version"
@@ -312,43 +333,49 @@
         "description": "远程配置历史分页结果。",
         "properties": {
           "has_next_page": {
-            "description": "是否还有下一页。",
+            "description": "本页之后还有更多版本时为 `true`。",
             "type": "boolean"
           },
           "items": {
-            "description": "版本列表，默认最新在前。",
+            "description": "本页的版本，默认最新在前。应用从未配置过时为空数组。",
             "items": {
               "$ref": "#/components/schemas/RemoteConfigHistoryItem"
             },
             "type": "array"
           },
           "total": {
-            "description": "版本总数。",
+            "description": "保留的版本总数（最多 50 个）。",
             "type": "integer"
           }
         },
-        "type": "object"
+        "type": "object",
+        "required": [
+          "total",
+          "has_next_page",
+          "items"
+        ]
       },
       "PreviewRemoteConfigRequest": {
         "description": "预览请求。省略 `config` 时预览当前生效配置。",
         "properties": {
           "app_version": {
-            "description": "模拟客户端上报的应用版本。",
+            "description": "模拟客户端上报的应用版本，与规则的 `match.app_version` 精确比较（不支持范围或前缀匹配）。不传表示未上报。",
             "type": "string"
           },
           "application_id": {
-            "description": "RUM 应用 ID。",
+            "description": "RUM 应用 ID，可通过 `POST /rum/application/list` 获取。",
             "type": "string"
           },
           "config": {
-            "$ref": "#/components/schemas/RemoteConfig"
+            "$ref": "#/components/schemas/RemoteConfig",
+            "description": "要评估的草稿配置，按 `POST /rum/application/remote-config/update` 的规则校验。不传则评估线上配置。"
           },
           "env": {
-            "description": "模拟客户端上报的环境。",
+            "description": "模拟客户端上报的环境，与规则的 `match.env` 精确比较。不传表示未上报，依赖 `env` 的规则不会命中。",
             "type": "string"
           },
           "sdk": {
-            "description": "模拟客户端上报的 SDK 名称与版本，如 `web@2.4.1`。",
+            "description": "模拟客户端上报的 SDK 标识，例如 `web@2.4.1`，与规则的 `match.sdk` 精确比较。不传表示未上报。",
             "type": "string"
           }
         },
@@ -361,14 +388,19 @@
         "description": "模拟客户端将拿到的配置值。",
         "properties": {
           "hit_rule_index": {
-            "description": "决定结果的规则下标（从 0 开始）；仅命中默认值时为 -1。",
+            "description": "第一个命中规则在 `config.rules` 中的下标（从 0 开始）；没有规则命中（只用了 `default`）或配置已关闭/不存在时为 `-1`。",
             "type": "integer"
           },
           "values": {
-            "$ref": "#/components/schemas/RemoteConfigValues"
+            "$ref": "#/components/schemas/RemoteConfigValues",
+            "description": "`default` 与命中规则 `set` 合并后的结果。两者都未设置的字段会被省略；空对象表示客户端保留全部初始化参数。"
           }
         },
-        "type": "object"
+        "type": "object",
+        "required": [
+          "values",
+          "hit_rule_index"
+        ]
       },
       "RemoteConfig": {
         "description": "单个应用的完整远程配置。变更异步到达 SDK，并在其创建下一个会话时生效，正在进行的会话不会被中途改变。",
@@ -383,29 +415,35 @@
             "type": "string"
           },
           "custom": {
-            "additionalProperties": {},
-            "description": "应用自定义的透传值，原样下发给宿主应用。最多 5 个键，键长不超过 64 字节，单值不超过 4 KB JSON 且嵌套不超过 3 层，总计不超过 16 KB。持有公开 client token 的任何人都能读到它。",
+            "additionalProperties": {
+              "description": "任意 JSON 值：字符串、数字、布尔、数组或对象。"
+            },
+            "description": "SDK 原样交给宿主应用的自由键值对，平台不解析其内容。最多 5 个键，每个键 1–64 字节，每个值为合法 JSON、不超过 4 KB 且嵌套不超过 3 层，总计不超过 16 KB。持有公开 client token 的任何人都能读到它。为空时响应中省略。",
             "maxProperties": 5,
             "type": "object"
           },
           "default": {
-            "$ref": "#/components/schemas/RemoteConfigValues"
+            "$ref": "#/components/schemas/RemoteConfigValues",
+            "description": "所有客户端都会收到的值，命中的规则可覆盖其中的字段。"
           },
           "enabled": {
-            "description": "总开关。为 false 时引擎不下发任何值，SDK 沿用初始化值。",
+            "description": "总开关。为 `false` 时 SDK 配置下发端不返回任何值，SDK 回退到初始化参数；`default` 和 `rules` 仍会保留。不传时视为 `false`。",
             "type": "boolean"
           },
           "refresh_on_foreground": {
-            "description": "允许客户端回到前台时重新拉取配置，而不是等待下一次轮询。",
+            "description": "为 `true` 时，客户端回到前台时会重新拉取配置，而不是等待下一次轮询。默认 `false`；为 `false` 时响应中省略。",
             "type": "boolean"
           },
           "rules": {
-            "description": "定向规则，按顺序评估；每个应用最多 20 条。",
+            "description": "定向规则，按顺序评估，第一条命中的规则生效。最多 20 条。保存时未带规则则可能为 `null`。",
             "items": {
               "$ref": "#/components/schemas/RemoteConfigRule"
             },
             "maxItems": 20,
-            "type": "array"
+            "type": [
+              "array",
+              "null"
+            ]
           }
         },
         "type": "object"
@@ -414,18 +452,19 @@
         "description": "一个已发布的远程配置版本。",
         "properties": {
           "config": {
-            "$ref": "#/components/schemas/RemoteConfig"
+            "$ref": "#/components/schemas/RemoteConfig",
+            "description": "该版本生效的配置内容。"
           },
           "content_hash": {
-            "description": "配置内容的哈希；控制台用它识别内容相同的版本。",
+            "description": "所存配置的指纹：SHA-256 的前 16 位十六进制字符。哈希相同的版本内容完全相同。较早的版本可能为空。",
             "type": "string"
           },
           "equivalent_to": {
-            "description": "与本版本内容相同的最早版本号（当不是本版本自身时返回）。",
+            "description": "具有相同 `content_hash` 的最早保留版本，例如回滚所恢复的版本。本版本自身就是最早版本时省略。",
             "type": "integer"
           },
           "reason": {
-            "description": "发布该版本时操作者留下的说明，未填写则为空。",
+            "description": "发布或回滚时通过 `reason` 填写的自由文本备注（非枚举）；未填写时为 `\"\"`。",
             "type": "string"
           },
           "updated_at": {
@@ -439,7 +478,7 @@
             "type": "integer"
           },
           "updated_by_name": {
-            "description": "发布该版本的成员名称。",
+            "description": "发布该版本的成员在发布时的名称，最多保留 128 个字符。",
             "type": "string"
           },
           "version": {
@@ -447,18 +486,35 @@
             "type": "integer"
           }
         },
-        "type": "object"
+        "type": "object",
+        "required": [
+          "config",
+          "version",
+          "content_hash",
+          "reason",
+          "updated_by",
+          "updated_by_name",
+          "updated_at"
+        ]
       },
       "RemoteConfigRule": {
-        "description": "单条定向规则：当 `match` 条件满足时，`set` 覆盖 `default`。规则按顺序评估，第一条命中的规则生效——规则顺序即优先级。",
+        "description": "单条定向规则：`match` 的所有条件都满足时，`set` 覆盖 `default`。第一条命中的规则生效并停止评估，规则顺序即优先级。`set` 至少要设置一个值。",
         "properties": {
           "match": {
             "additionalProperties": {
               "maxLength": 256,
+              "minLength": 1,
               "type": "string"
             },
-            "description": "SDK 配置请求必须相等的键值对。键仅支持 `env`、`app_version`、`sdk`；值最长 256 字节。",
+            "description": "针对 SDK 配置请求上报内容的条件，各条件之间为“与”关系，按字符串精确比较。键仅支持 `env`、`app_version`、`sdk`；值为 1–256 字节。SDK 未上报的键一定不命中。",
             "minProperties": 1,
+            "propertyNames": {
+              "enum": [
+                "env",
+                "app_version",
+                "sdk"
+              ]
+            },
             "type": "object"
           },
           "set": {
@@ -475,7 +531,7 @@
         "description": "配置可设置的 SDK 参数。每个字段都是可选的：规则与默认值都未设置的字段不会出现在 SDK 响应中，SDK 将沿用初始化值。",
         "properties": {
           "defaultPrivacyLevel": {
-            "description": "Session Replay 默认的页面脱敏方式。",
+            "description": "Session Replay 默认的页面脱敏方式：\n\n- `mask`：替换页面文本并隐藏输入值。\n- `mask-user-input`：保留页面文本，只隐藏用户输入的内容。\n- `allow`：按原样录制页面；已上传的内容无法事后脱敏。",
             "enum": [
               "mask",
               "mask-user-input",
@@ -501,7 +557,7 @@
             ]
           },
           "sessionReplaySampleRate": {
-            "description": "Session Replay 采样率（0-100）。",
+            "description": "录制 Session Replay 的会话比例，百分比（0–100）。",
             "maximum": 100,
             "minimum": 0,
             "type": [
@@ -510,7 +566,7 @@
             ]
           },
           "sessionSampleRate": {
-            "description": "会话采样率（0-100）。",
+            "description": "会话采集比例，百分比（0–100）。",
             "maximum": 100,
             "minimum": 0,
             "type": [
@@ -519,7 +575,7 @@
             ]
           },
           "traceSampleRate": {
-            "description": "Trace 采样率（0-100）：哪些会话会在请求中注入 Trace 头。",
+            "description": "向请求注入链路头的会话比例，百分比（0–100）。按会话决定：一个会话要么全部请求都带链路头，要么都不带。",
             "maximum": 100,
             "minimum": 0,
             "type": [
@@ -534,16 +590,16 @@
         "description": "将历史版本的内容重新发布为新的版本号。",
         "properties": {
           "application_id": {
-            "description": "RUM 应用 ID。",
+            "description": "RUM 应用 ID，可通过 `POST /rum/application/list` 获取。",
             "type": "string"
           },
           "reason": {
-            "description": "操作者说明。控制台留空时会自动填入 `rolled back to vN`。",
+            "description": "可选的自由文本备注（非枚举），最多 255 个字符，按原样保存，并在 `POST /rum/application/remote-config/history/list` 的 `reason` 中返回。不传时服务端不会自动填充。",
             "maxLength": 255,
             "type": "string"
           },
           "version": {
-            "description": "要重新发布的历史版本号。",
+            "description": "要恢复的版本号，必须是 `POST /rum/application/remote-config/history/list` 中仍保留的版本。",
             "minimum": 1,
             "type": "integer"
           }
@@ -558,7 +614,7 @@
         "description": "回滚创建的版本。",
         "properties": {
           "version": {
-            "description": "回滚生成的新的版本号。",
+            "description": "回滚生成的新版本号（此前最大版本号 + 1）。",
             "type": "integer"
           }
         },
@@ -568,12 +624,15 @@
         "description": "应用的告警配置。",
         "properties": {
           "channel_ids": {
-            "description": "接收告警的协作空间 ID 列表，仅在 `delivery_mode` 为 `oncall` 时使用。",
+            "description": "接收告警的协作空间 ID 列表，仅在 `delivery_mode` 为 `oncall` 时使用；`webhook` 模式下作为草稿保留。从未设置时可能为 `null`。",
             "items": {
               "format": "int64",
               "type": "integer"
             },
-            "type": "array"
+            "type": [
+              "array",
+              "null"
+            ]
           },
           "delivery_mode": {
             "description": "告警投递方式：`oncall` 经 Flashduty On-call 投递，`webhook` 直接 POST 到 `webhook_url`。空值按 `oncall` 处理；创建/更新时空值会落库为部署默认值（纯 RUM 私有化部署默认 `webhook`，其他场景默认 `oncall`）。为空（历史数据）时省略该字段。",
@@ -584,7 +643,7 @@
             "type": "string"
           },
           "enabled": {
-            "description": "是否启用告警。",
+            "description": "是否开启告警。`false` 表示关闭告警，此时不校验 `webhook_url`。",
             "type": "boolean"
           },
           "integration_id": {
@@ -593,7 +652,7 @@
             "type": "integer"
           },
           "webhook_url": {
-            "description": "`delivery_mode` 为 `webhook` 时接收告警事件的 URL，该模式下必填，其他模式下忽略；为空时省略该字段。",
+            "description": "`delivery_mode` 为 `webhook` 时接收告警事件的 URL。该模式下 `enabled` 为 `true` 时必填；必须使用 `http` 或 `https`，在 Flashduty 云端不能解析到私有、回环、链路本地或保留地址。`oncall` 模式下忽略。为空时响应中省略该字段。",
             "format": "uri",
             "type": "string"
           }
@@ -617,7 +676,7 @@
             "type": "string"
           },
           "is_private": {
-            "description": "是否仅限团队成员访问。",
+            "description": "为 `true` 时，仅账户所有者、账户管理员、创建者和所属团队成员可以查看或编辑该应用。默认 `false`。",
             "type": "boolean"
           },
           "links": {
@@ -633,11 +692,11 @@
             "description": "要关联的代码仓库，有序；第一个为主仓库。最多 10 个。"
           },
           "no_geo": {
-            "description": "不推断地理位置。",
+            "description": "为 `true` 时不根据客户端 IP 推断地理位置。默认 `false`。",
             "type": "boolean"
           },
           "no_ip": {
-            "description": "不采集 IP 地址。",
+            "description": "为 `true` 时不采集客户端 IP 地址。默认 `false`。",
             "type": "boolean"
           },
           "team_id": {
@@ -648,7 +707,7 @@
           },
           "tracing": {
             "$ref": "#/components/schemas/RumApplicationTracing",
-            "description": "APM 链路追踪集成配置，可选。"
+            "description": "可选的 APM 链路集成配置。不传时保存为空配置（`enabled: false`，`open_type` 和 `endpoint` 为空）。"
           },
           "type": {
             "description": "平台标识：\n\n| 值 | 含义 |\n|---|---|\n| `browser` | 浏览器 Web 应用（JavaScript SDK） |\n| `ios` | 苹果 iOS 应用 |\n| `android` | Android 应用 |\n| `react-native` | React Native 应用 |\n| `flutter` | Flutter 应用 |\n| `kotlin-multiplatform` | Kotlin Multiplatform 应用 |\n| `roku` | Roku 频道应用 |\n| `unity` | Unity 应用 |\n| `miniprogram` | 微信小程序 |\n| `harmony` | 鸿蒙 HarmonyOS 应用 |\n| `electron` | Electron 桌面应用 |",
@@ -679,7 +738,7 @@
         "description": "创建 RUM 应用的结果。",
         "properties": {
           "application_id": {
-            "description": "自动生成的唯一应用 ID。",
+            "description": "服务端生成的应用 ID（22 位短 UUID），在其他应用接口中作为 `application_id` 使用。",
             "type": "string"
           },
           "application_name": {
@@ -687,11 +746,16 @@
             "type": "string"
           },
           "client_token": {
-            "description": "用于 RUM SDK 初始化的令牌。",
+            "description": "用于初始化 RUM SDK 的令牌，也可通过 `POST /rum/application/info` 获取。",
             "type": "string"
           }
         },
-        "type": "object"
+        "type": "object",
+        "required": [
+          "application_id",
+          "application_name",
+          "client_token"
+        ]
       },
       "RumApplicationIDRequest": {
         "description": "包含单个应用 ID 的请求。",
@@ -710,7 +774,7 @@
         "description": "批量查询应用信息请求。",
         "properties": {
           "application_ids": {
-            "description": "最多 200 个应用 ID，可通过 `POST /rum/application/list` 获取。",
+            "description": "最多 200 个应用 ID。重复 ID 会被去重，不存在或已删除的 ID 会被跳过。可通过 `POST /rum/application/list` 获取 ID。",
             "items": {
               "type": "string"
             },
@@ -727,26 +791,29 @@
         "description": "批量查询应用信息响应。",
         "properties": {
           "items": {
-            "description": "与请求的 `application_ids`（最多 200 个，自动去重）匹配的应用信息列表。",
+            "description": "在请求的 `application_ids` 中找到的应用，顺序不固定。均未找到时为空数组。",
             "items": {
               "$ref": "#/components/schemas/RumApplicationItem"
             },
             "type": "array"
           }
         },
-        "type": "object"
+        "type": "object",
+        "required": [
+          "items"
+        ]
       },
       "RumApplicationItem": {
         "description": "单个 RUM 应用。",
         "properties": {
           "account_id": {
-            "description": "账户 ID。",
+            "description": "应用所属 Flashduty 账户的 ID。",
             "format": "int64",
             "type": "integer"
           },
           "alerting": {
             "$ref": "#/components/schemas/RumApplicationAlerting",
-            "description": "应用的告警配置。"
+            "description": "应用的告警配置，始终为对象。"
           },
           "application_id": {
             "description": "唯一应用 ID。",
@@ -766,17 +833,17 @@
             "type": "integer"
           },
           "created_by": {
-            "description": "创建者成员 ID。",
+            "description": "创建者的成员 ID。创建者始终可以编辑该应用。",
             "format": "int64",
             "type": "integer"
           },
           "is_private": {
-            "description": "为 `true` 时仅团队成员可访问。",
+            "description": "为 `true` 时，仅账户所有者、账户管理员、创建者和所属团队成员可以查看或编辑该应用。",
             "type": "boolean"
           },
           "links": {
             "$ref": "#/components/schemas/RumApplicationLinks",
-            "description": "外部链接集成配置。"
+            "description": "外部链接集成配置，始终为对象；从未保存过任何系统时 `systems` 可能为 `null`。"
           },
           "repositories": {
             "type": "array",
@@ -784,7 +851,7 @@
               "$ref": "#/components/schemas/RumApplicationRepository"
             },
             "maxItems": 10,
-            "description": "关联的代码仓库，有序；第一个为主仓库。关联本身不授予任何访问权限：AI 会话只能读取本账户 GitHub App 安装已授权的仓库。"
+            "description": "关联的源码仓库，按顺序排列，第一个为主仓库；未关联时为空数组。关联本身不授予访问权限：AI 会话只能读取账户的 GitHub App 安装已授权的仓库。"
           },
           "no_geo": {
             "description": "为 `true` 时不推断地理位置。",
@@ -795,7 +862,7 @@
             "type": "boolean"
           },
           "status": {
-            "description": "应用状态。取值：`enabled`（启用中，正常接收数据）、`disabled`（已停用）、`deleted`（已删除的软删除标记；所有查询都会过滤该状态，响应中实际不会出现）。",
+            "description": "应用状态：\n\n- `enabled`：SDK 的 `client_token` 可用，正常采集数据。通过接口创建的应用都处于此状态。\n- `disabled`：`client_token` 被拒绝，不再采集新数据。没有公开接口会设置此状态。\n- `deleted`：软删除标记；已删除的应用不会出现在任何响应中，因此不会返回该值。",
             "enum": [
               "enabled",
               "disabled",
@@ -804,13 +871,13 @@
             "type": "string"
           },
           "team_id": {
-            "description": "所属团队 ID。",
+            "description": "所属团队 ID。该团队成员可以编辑该应用，应用为私有时也只有他们（及管理员、创建者）可见。",
             "format": "int64",
             "type": "integer"
           },
           "tracing": {
             "$ref": "#/components/schemas/RumApplicationTracing",
-            "description": "APM 链路追踪集成配置。"
+            "description": "APM 链路集成配置。始终为对象；从未配置时为 `enabled: false`，`open_type` 与 `endpoint` 为空。"
           },
           "type": {
             "description": "平台标识：\n\n| 值 | 含义 |\n|---|---|\n| `browser` | 浏览器 Web 应用（JavaScript SDK） |\n| `ios` | 苹果 iOS 应用 |\n| `android` | Android 应用 |\n| `react-native` | React Native 应用 |\n| `flutter` | Flutter 应用 |\n| `kotlin-multiplatform` | Kotlin Multiplatform 应用 |\n| `roku` | Roku 频道应用 |\n| `unity` | Unity 应用 |\n| `miniprogram` | 微信小程序 |\n| `harmony` | 鸿蒙 HarmonyOS 应用 |\n| `electron` | Electron 桌面应用 |",
@@ -840,13 +907,33 @@
             "type": "integer"
           }
         },
-        "type": "object"
+        "type": "object",
+        "required": [
+          "account_id",
+          "application_id",
+          "application_name",
+          "type",
+          "client_token",
+          "team_id",
+          "is_private",
+          "no_ip",
+          "no_geo",
+          "alerting",
+          "tracing",
+          "links",
+          "repositories",
+          "status",
+          "created_by",
+          "updated_by",
+          "created_at",
+          "updated_at"
+        ]
       },
       "RumApplicationLink": {
         "description": "在匹配的 RUM 事件详情页展示的外部系统链接。",
         "properties": {
           "enabled": {
-            "description": "是否启用该外部系统链接。",
+            "description": "是否显示该外部系统链接。不传时视为 `false`。",
             "type": "boolean"
           },
           "event_types": {
@@ -867,15 +954,15 @@
             "type": "array"
           },
           "icon_color": {
-            "description": "链接图标显示颜色。",
+            "description": "链接图标的显示颜色，例如 `#0F766E`。为空时响应中省略。",
             "type": "string"
           },
           "icon_text": {
-            "description": "链接图标中显示的短文本。",
+            "description": "链接图标中显示的短文本，例如 `S3`。为空时响应中省略。",
             "type": "string"
           },
           "id": {
-            "description": "外部系统的稳定客户端标识。",
+            "description": "客户端自定义的外部系统标识，按原样保存，服务端不做校验。",
             "type": "string"
           },
           "name": {
@@ -900,7 +987,7 @@
         "description": "应用的外部链接集成配置。",
         "properties": {
           "enabled": {
-            "description": "是否启用外部链接集成。",
+            "description": "外部链接集成的总开关。不传时视为 `false`。",
             "type": "boolean"
           },
           "systems": {
@@ -923,11 +1010,11 @@
         "description": "查询 RUM 应用列表的过滤参数。",
         "properties": {
           "asc": {
-            "description": "为 `true` 时升序排列。",
+            "description": "为 `true` 时升序；默认 `false`（降序）。",
             "type": "boolean"
           },
           "is_my_team": {
-            "description": "为 `true` 时仅返回当前用户所在团队的应用。",
+            "description": "为 `true` 时只返回调用者所在团队拥有的应用；调用者不属于任何团队时不生效。",
             "type": "boolean"
           },
           "limit": {
@@ -950,7 +1037,7 @@
             "type": "integer"
           },
           "query": {
-            "description": "按应用名称做子串匹配搜索。",
+            "description": "按应用名称做子串匹配（SQL `LIKE`，因此 `%` 和 `_` 会被当作通配符）。",
             "type": "string"
           },
           "team_id": {
@@ -969,7 +1056,7 @@
             "type": "boolean"
           },
           "items": {
-            "description": "当前页的 RUM 应用列表。",
+            "description": "当前页的 RUM 应用；无匹配时为空数组。",
             "items": {
               "$ref": "#/components/schemas/RumApplicationItem"
             },
@@ -980,24 +1067,30 @@
             "type": "integer"
           }
         },
-        "type": "object"
+        "type": "object",
+        "required": [
+          "has_next_page",
+          "total",
+          "items"
+        ]
       },
       "RumApplicationTracing": {
         "description": "APM 链路追踪集成配置。",
         "properties": {
           "enabled": {
-            "description": "是否启用链路追踪集成。",
+            "description": "是否在 RUM 事件上显示链路链接。",
             "type": "boolean"
           },
           "endpoint": {
-            "description": "链路 Endpoint URL（http 或 https）。",
+            "description": "链路系统地址，必须以 `http` 或 `https` 开头。只要传入 `tracing` 就必填，即使 `enabled` 为 `false`。从未配置链路时，响应中为空字符串。",
             "type": "string"
           },
           "open_type": {
-            "description": "链路链接的打开方式。取值：`popup`（在弹窗中打开链路详情）、`tab`（在新标签页中打开）。",
+            "description": "链路链接的打开方式：\n\n- `popup`：在弹窗中打开链路详情。\n- `tab`：在新的浏览器标签页中打开。\n- `\"\"`（空）：仅在从未配置链路时返回；请求中不接受。",
             "enum": [
               "popup",
-              "tab"
+              "tab",
+              ""
             ],
             "type": "string"
           }
@@ -1014,7 +1107,7 @@
         "properties": {
           "alerting": {
             "$ref": "#/components/schemas/RumApplicationAlerting",
-            "description": "告警配置；不传则保持不变。",
+            "description": "告警配置。传入时整体替换已保存的告警配置（`integration_id` 由服务端维护除外）。不传则保持不变。",
             "x-flashduty-preserve-absence": true
           },
           "application_id": {
@@ -1031,7 +1124,7 @@
             ]
           },
           "is_private": {
-            "description": "是否仅限所属团队成员访问；`false` 显式改为公开访问；不传则保持不变。",
+            "description": "`true` 表示仅账户所有者、账户管理员、创建者和所属团队成员可访问；`false` 表示账户内所有人可见。不传则保持不变。",
             "type": [
               "boolean",
               "null"
@@ -1039,7 +1132,7 @@
           },
           "links": {
             "$ref": "#/components/schemas/RumApplicationLinks",
-            "description": "外部链接集成配置；不传则保持不变。",
+            "description": "外部链接集成配置。传入时整体替换已保存的对象（包括整个 `systems` 列表）。不传则保持不变。",
             "x-flashduty-preserve-absence": true
           },
           "repositories": {
@@ -1066,7 +1159,7 @@
             ]
           },
           "team_id": {
-            "description": "应用所属团队 ID，可通过 `POST /team/list` 获取；不传则保持不变。",
+            "description": "新的所属团队 ID，可通过 `POST /team/list` 获取。不传则保持不变。更换团队会改变可编辑该应用的人员。",
             "exclusiveMinimum": 0,
             "format": "int64",
             "type": [
@@ -1076,7 +1169,7 @@
           },
           "tracing": {
             "$ref": "#/components/schemas/RumApplicationTracing",
-            "description": "APM 链路追踪集成配置；不传则保持不变。"
+            "description": "APM 链路集成配置。传入时整体替换已保存的对象，且必须包含合法的 `open_type` 和 `endpoint`。不传则保持不变。"
           },
           "type": {
             "description": "应用类型，不传则不修改。平台标识：\n\n| 值 | 含义 |\n|---|---|\n| `browser` | 浏览器 Web 应用（JavaScript SDK） |\n| `ios` | 苹果 iOS 应用 |\n| `android` | Android 应用 |\n| `react-native` | React Native 应用 |\n| `flutter` | Flutter 应用 |\n| `kotlin-multiplatform` | Kotlin Multiplatform 应用 |\n| `roku` | Roku 频道应用 |\n| `unity` | Unity 应用 |\n| `miniprogram` | 微信小程序 |\n| `harmony` | 鸿蒙 HarmonyOS 应用 |\n| `electron` | Electron 桌面应用 |",
@@ -1108,15 +1201,15 @@
         "description": "单个返回列的元信息。",
         "properties": {
           "name": {
-            "description": "列名。",
+            "description": "列名或 `sql` 中写的别名；`time_series` 查询的时间桶列为 `ts`。",
             "type": "string"
           },
           "nullable": {
-            "description": "该列的值是否可能为 null。",
+            "description": "该列取值是否可能为 `null`。驱动无法判断时为 `true`。",
             "type": "boolean"
           },
           "type": {
-            "description": "该列的后端数据库类型名称。",
+            "description": "数据库驱动报告的列类型名，如 `VARCHAR`、`BIGINT`、`DOUBLE`、`DATETIME`。取决于所选列或表达式，取值集合不固定，可作为解析 `values` 的参考。",
             "type": "string"
           }
         },
@@ -1131,11 +1224,11 @@
         "description": "单个 RUM 数据查询定义。",
         "properties": {
           "disable_sampling": {
-            "description": "为 true 时，请求查询引擎尽可能避免采样。",
+            "description": "为 `true` 时始终查询全量数据，响应不会出现 `sampling`。为 `false`（默认）时，服务端可能对大时间跨度的聚合查询进行抽样。",
             "type": "boolean"
           },
           "dql": {
-            "description": "可选的 RUM DQL 过滤表达式，会和 SQL 校验一起使用。",
+            "description": "可选的 RUM DQL 过滤表达式，会被转换后以 `AND` 方式并入 `sql` 的 `WHERE` 子句。DQL 解析失败时在该查询的 `error` 中返回。",
             "type": "string"
           },
           "format": {
@@ -1153,28 +1246,28 @@
           },
           "interval": {
             "default": 3600,
-            "description": "`time_series` 查询的时间桶间隔，单位秒。",
+            "description": "`time_series` 查询的最小时间桶宽度，单位为**毫秒**，默认 3600（即 3.6 秒）。实际桶宽取固定档位中同时不小于该值和「时间跨度 ÷ `max_points`」的最小一档，并在结果的 `interval` 中返回。`table` 查询忽略此字段。",
             "exclusiveMinimum": 0,
             "format": "int64",
             "type": "integer"
           },
           "max_points": {
             "default": 1226,
-            "description": "`time_series` 查询最多返回的点数。",
+            "description": "`time_series` 查询的时间桶数量上限，默认 1226。服务端会放大桶宽，使时间范围内的桶数不超过该值。`table` 查询忽略此字段。",
             "exclusiveMinimum": 0,
             "format": "int64",
             "type": "integer"
           },
           "search_after_ctx": {
-            "description": "上一次表格查询返回的不透明游标，用于继续分页。",
+            "description": "上一次响应返回的 `search_after_ctx`，用于获取同一 `table` 查询的下一页。仅对不含聚合、带 `ORDER BY` 且无 `OFFSET` 的查询生效。传入无效值会导致该查询失败。",
             "type": "string"
           },
           "sql": {
-            "description": "要执行的 RUM SQL 查询。",
+            "description": "RUM SQL `SELECT` 语句。`FROM` 填写数据表名（`sessions`、`views`、`actions`、`errors`、`resources`、`long_tasks`、`vitals`、`issues`、`sourcemaps`），列名为 `POST /rum/field/list` 返回的 `field_key`。服务端会自动追加账户与时间范围过滤。",
             "type": "string"
           },
           "time_zone": {
-            "description": "计算时间函数时使用的 IANA 时区名称，例如 `Asia/Shanghai`。",
+            "description": "IANA 时区名，如 `Asia/Shanghai`，用于让 `time_series` 的时间桶边界按当地时间对齐；不传时按 UTC 对齐。`table` 查询忽略此字段；无效时区会使整个请求返回 `InvalidParameter`。",
             "type": "string"
           }
         },
@@ -1194,7 +1287,7 @@
           },
           "error": {
             "$ref": "#/components/schemas/DutyError",
-            "description": "子查询失败的错误详情；查询成功时省略。"
+            "description": "查询在请求校验通过后失败时返回（表或列不存在、`dql` 或 `search_after_ctx` 无效、数据库报错），错误码固定为 `InternalError`。查询成功时不返回。"
           }
         },
         "type": "object"
@@ -1242,14 +1335,14 @@
         "description": "单个 RUM 数据查询返回的行数据和元信息。",
         "properties": {
           "fields": {
-            "description": "返回值矩阵的列元信息。",
+            "description": "列元数据，每个返回列一项，顺序与 `values` 一致。`time_series` 查询的第一列为 `ts`。",
             "items": {
               "$ref": "#/components/schemas/RumDataFieldMeta"
             },
             "type": "array"
           },
           "interval": {
-            "description": "时序查询实际使用的时间桶间隔，单位秒；`table` 格式查询时省略。",
+            "description": "`time_series` 查询实际使用的时间桶宽度，单位为**毫秒**。`table` 查询不返回此字段。",
             "format": "int64",
             "type": "integer"
           },
@@ -1258,14 +1351,17 @@
             "description": "采样元信息；查询未使用采样时省略。"
           },
           "search_after_ctx": {
-            "description": "用于继续表格查询分页的不透明游标；非游标分页的表格查询或没有更多分页时省略。",
+            "description": "不含聚合、带 `ORDER BY` 且无 `OFFSET` 的 `table` 查询的下一页游标。仅当本页行数达到 `LIMIT` 时返回，否则不返回。",
             "type": "string"
           },
           "values": {
-            "description": "查询返回的行数据。每一行按下标与 `fields` 对齐。",
+            "description": "按列组织的结果值：`values[i]` 是列 `fields[i]` 在所有行上的取值列表。查询无结果时各列为 `null`。日期时间值以 RFC 3339 字符串返回。",
             "items": {
               "items": {},
-              "type": "array"
+              "type": [
+                "array",
+                "null"
+              ]
             },
             "type": "array"
           }
@@ -1284,7 +1380,7 @@
             "type": "boolean"
           },
           "scale_factor": {
-            "description": "将采样计数放大为全量估算值时使用的倍率。",
+            "description": "将抽样结果换算为全量估计值的倍数。`values` 中的 `COUNT`、`SUM`、`COUNT(DISTINCT)` 列已乘以该值；其他聚合按抽样数据的计算结果原样返回。",
             "type": "number"
           }
         },
@@ -1302,13 +1398,13 @@
             "type": "string"
           },
           "description": {
-            "description": "规则描述，最多 512 个字符。",
+            "description": "规则描述，最多 512 个字符，不传时为空字符串。",
             "maxLength": 512,
             "type": "string"
           },
           "filters": {
             "$ref": "#/components/schemas/RumErrorIngestionOrFilters",
-            "description": "用于匹配错误的过滤条件（OR-of-ANDs 结构）；命中的错误会被丢弃，不再采集入库。"
+            "description": "用于匹配错误的过滤条件（OR-of-ANDs 结构）。命中的错误仍会入库，但不会被归入任何问题。"
           },
           "rule_name": {
             "description": "规则名称，1-128 个字符。",
@@ -1351,11 +1447,11 @@
         "description": "单条过滤条件，匹配错误的某一个字段。",
         "properties": {
           "key": {
-            "description": "字段 key。取值范围：`error.usr_id`、`error.usr_email`、`error.error_type`、`error.error_message`、`error.error_stack`、`error.view_url`、`error.env`、`error.version`、`error.service`、`error.browser_name`、`error.browser_version`、`error.fingerprint`、`error.is_crash`，或以 `context.` 为前缀、最多三级嵌套的自定义上下文字段。",
+            "description": "要匹配的字段。可选 `error.usr_id`、`error.usr_email`、`error.error_type`、`error.error_message`、`error.error_stack`、`error.view_url`、`error.env`、`error.version`、`error.service`、`error.browser_name`、`error.browser_version`、`error.fingerprint`、`error.is_crash`（取值为 `true` 或 `false`），或以 `context.` 开头、指向错误自定义上下文的路径。上下文对象按点号展开，最多 3 级（`context.a.b.c`）；更深的对象按其 JSON 文本比较，数组类型的值无法匹配。",
             "type": "string"
           },
           "oper": {
-            "description": "匹配方式：`IN` 表示字段值命中 `vals` 中任意一项即匹配，`NOTIN` 表示都不命中才匹配。",
+            "description": "匹配方式：\n- `IN`：字段值命中 `vals` 中任意一项即匹配；错误中不存在的上下文字段永不匹配。\n- `NOTIN`：字段值与 `vals` 中每一项都不命中才匹配；错误中不存在的上下文字段总是匹配。",
             "enum": [
               "IN",
               "NOTIN"
@@ -1363,7 +1459,7 @@
             "type": "string"
           },
           "vals": {
-            "description": "待匹配的取值列表，至少 1 项。每项为精确字符串，或使用通配符（`*`/`?`）、正则（以 `/` 包裹）、`cidr:` 前缀、`num:lt|le|gt|ge:` 前缀表示的特殊匹配模式。",
+            "description": "待匹配的取值列表，至少 1 项。每项可以是：精确字符串（区分大小写）；使用 `*`/`?` 的通配符模式（需匹配整个值）；以 `/` 包裹的正则（未加锚点时匹配值中任意位置）；`cidr:<网段>`（字段值按 IP 解析）；或 `num:lt|le|gt|ge:<数字>`（字段值按数字解析，非数字不匹配）。",
             "items": {
               "type": "string"
             },
@@ -1382,28 +1478,28 @@
         "description": "某一历史版本下，应用全部规则的快照。",
         "properties": {
           "rules": {
-            "description": "此版本下应用的完整规则列表。",
+            "description": "生成此版本的那次变更之前，该应用全部未删除规则的完整列表。应用创建第一条规则时生成的版本中该列表为空。",
             "items": {
               "$ref": "#/components/schemas/RumErrorIngestionRuleSnapshotItem"
             },
             "type": "array"
           },
           "updated_at": {
-            "description": "快照生成时间，Unix 毫秒时间戳。",
+            "description": "生成此版本的那次变更发生的时间，Unix 毫秒时间戳。",
             "format": "int64",
             "type": "integer"
           },
           "updated_by": {
-            "description": "触发此次快照的成员 ID。",
+            "description": "做出此次变更（生成此版本）的成员 ID。",
             "format": "int64",
             "type": "integer"
           },
           "updated_by_name": {
-            "description": "触发此次快照的成员名称。",
+            "description": "该成员在变更时的显示名称。",
             "type": "string"
           },
           "version": {
-            "description": "历史版本号，从 1 开始递增。",
+            "description": "历史版本号，从 1 开始，每次写操作加 1。可传给 `POST /rum/error-ingestion/rules/history/revert` 进行回滚。",
             "type": "integer"
           }
         },
@@ -1425,20 +1521,23 @@
           },
           "asc": {
             "default": false,
-            "description": "按升序排序，默认按降序排序。",
+            "description": "`true` 为升序；`false`（默认）为降序，最新的在前。",
             "type": "boolean"
           },
           "limit": {
             "default": 20,
-            "description": "每页条数，默认 20，服务端上限 100；小于等于 0 时回退为默认值。",
+            "description": "每页条数。默认 20；超过 100 时按 100 处理，小于等于 0 时回退为 20。",
             "format": "int64",
-            "maximum": 100,
             "type": "integer"
           },
           "orderby": {
             "default": "updated_at",
-            "description": "排序字段：`updated_at` 或 `version`；无法识别的值会回退为 `updated_at`。",
-            "type": "string"
+            "description": "排序字段：\n- `updated_at`：生成该版本的变更时间（默认）。\n- `version`：版本号。\n传入其他值时回退为 `updated_at`。",
+            "type": "string",
+            "enum": [
+              "updated_at",
+              "version"
+            ]
           },
           "p": {
             "default": 0,
@@ -1457,7 +1556,7 @@
         "description": "分页返回的错误采集规则历史。",
         "properties": {
           "has_next_page": {
-            "description": "是否还有下一页历史记录。",
+            "description": "本页之后还有更多版本时为 `true`。",
             "type": "boolean"
           },
           "items": {
@@ -1468,7 +1567,7 @@
             "type": "array"
           },
           "total": {
-            "description": "该应用的历史版本总数。",
+            "description": "该应用历史版本的总数（不受分页影响）。",
             "format": "int64",
             "type": "integer"
           }
@@ -1510,7 +1609,7 @@
         "type": "object"
       },
       "RumErrorIngestionOrFilters": {
-        "description": "OR-of-ANDs 过滤器集合：外层数组为 OR，一个错误只要匹配其中任意一个内层 AND 组即视为命中该规则。",
+        "description": "OR-of-ANDs 过滤器集合：外层数组为 OR，一个错误只要匹配其中任意一个内层 AND 组即视为命中该规则。外层数组为空时规则永不命中；内层出现空 AND 组时会命中所有错误。",
         "items": {
           "description": "AND 组：仅当组内每个条件都匹配时，该组才算命中。",
           "items": {
@@ -1543,20 +1642,20 @@
         "description": "错误采集规则。",
         "properties": {
           "created_at": {
-            "description": "规则创建时间，Unix 毫秒时间戳。",
+            "description": "规则创建时间，Unix 毫秒时间戳；通过历史回滚恢复的规则会重置为回滚时间。",
             "format": "int64",
             "type": "integer"
           },
           "description": {
-            "description": "规则描述，最多 512 个字符。",
+            "description": "规则描述，最多 512 个字符；未填写时为空字符串。",
             "type": "string"
           },
           "filters": {
             "$ref": "#/components/schemas/RumErrorIngestionOrFilters",
-            "description": "该规则的过滤条件。"
+            "description": "规则的过滤条件。命中的错误会入库，但不会被归入任何问题。"
           },
           "rule_id": {
-            "description": "规则 ID。",
+            "description": "规则 ID，由服务端在 `create` 时生成，更新和历史回滚后保持不变。",
             "type": "string"
           },
           "rule_name": {
@@ -1564,7 +1663,7 @@
             "type": "string"
           },
           "status": {
-            "description": "规则当前状态。",
+            "description": "规则状态：\n- `enabled`：对新上报的错误生效。\n- `disabled`：规则保留但不生效。",
             "enum": [
               "enabled",
               "disabled"
@@ -1572,7 +1671,7 @@
             "type": "string"
           },
           "updated_at": {
-            "description": "规则最近更新时间，Unix 毫秒时间戳。",
+            "description": "最近一次更新、启用或禁用的时间，Unix 毫秒时间戳；通过历史回滚恢复的规则会重置为回滚时间。",
             "format": "int64",
             "type": "integer"
           }
@@ -1610,7 +1709,7 @@
         "description": "历史快照中的一条规则记录，包含内部存储字段（区别于 `list` 返回的精简字段集）。",
         "properties": {
           "account_id": {
-            "description": "账户 ID。",
+            "description": "规则所属账户的 ID。",
             "format": "int64",
             "type": "integer"
           },
@@ -1629,12 +1728,12 @@
             "type": "integer"
           },
           "deleted_at": {
-            "description": "软删除时间，Unix 毫秒时间戳；未删除时为 0。",
+            "description": "软删除时间，Unix 毫秒时间戳。此处恒为 `0`，因为快照只包含未删除的规则。",
             "format": "int64",
             "type": "integer"
           },
           "description": {
-            "description": "规则描述。",
+            "description": "该规则在此快照版本中的描述；未填写时为空字符串。",
             "type": "string"
           },
           "filters": {
@@ -1642,20 +1741,20 @@
             "description": "该规则在此快照版本中的过滤条件。"
           },
           "id": {
-            "description": "内部行 ID。",
+            "description": "内部存储行 ID，任何接口都不接受该值，请使用 `rule_id`。通过历史回滚恢复规则后会变化。",
             "format": "int64",
             "type": "integer"
           },
           "rule_id": {
-            "description": "规则 ID。",
+            "description": "规则 ID，与 `list` 返回的该规则 ID 相同。",
             "type": "string"
           },
           "rule_name": {
-            "description": "规则名称。",
+            "description": "该规则在此快照版本中的名称。",
             "type": "string"
           },
           "status": {
-            "description": "该规则在此快照版本中的状态。",
+            "description": "该规则在此快照版本中的状态：\n- `enabled`：对新上报的错误生效。\n- `disabled`：规则保留但不生效。",
             "enum": [
               "enabled",
               "disabled"
@@ -1668,7 +1767,7 @@
             "type": "integer"
           },
           "updated_by": {
-            "description": "最近更新者成员 ID。",
+            "description": "此快照之前最后一次修改该规则的成员 ID。",
             "format": "int64",
             "type": "integer"
           }
@@ -1733,7 +1832,7 @@
         "description": "分面值分布统计的请求参数。",
         "properties": {
           "dql": {
-            "description": "统计前应用的 RUM DQL 过滤表达式。",
+            "description": "统计前应用的 RUM DQL 过滤表达式，其中的字段会按 `scope` 校验。",
             "type": "string"
           },
           "end_time": {
@@ -1743,11 +1842,11 @@
             "type": "integer"
           },
           "facet_key": {
-            "description": "要统计值分布的字段键；必须是该 `scope` 下已注册的字段，可用字段可通过 `POST /rum/field/list` 查询。",
+            "description": "要统计取值分布的字段 key，如 `error_type`。必须是所给 `scope` 下 `show_type` 为 `list`、`value_type` 非数组类型的分面字段。可通过 `POST /rum/field/list` 查询候选字段。",
             "type": "string"
           },
           "facet_value": {
-            "description": "设置后，统计前会先过滤 `facet_key` 等于该值的事件。接受字符串、数字或布尔值。"
+            "description": "传入时只统计 `facet_key` 等于该值的事件。JSON 类型须与字段的 `value_type` 一致（字符串、数字或布尔），不一致返回 `InvalidParameter`。不传时排除取值为 `null` 的事件。"
           },
           "kind": {
             "description": "符号类型，仅在 `scope` 为 `sourcemap` 时使用，且只对 `android`/`harmony` 有意义：`mapping`（默认）选择 ProGuard/R8 mapping 或 ArkTS Sourcemap，`native` 选择 native .so 符号。",
@@ -1779,7 +1878,7 @@
             "type": "string"
           },
           "sql": {
-            "description": "仅含 WHERE 子句（无 SELECT）的 SQL 附加过滤条件。",
+            "description": "额外的 SQL 过滤条件，只写 `WHERE` 后面的条件本身（不含 `WHERE` 关键字），如 `env = 'prod'`。出现 `SELECT` 会被拒绝。",
             "type": "string"
           },
           "start_time": {
@@ -1871,7 +1970,7 @@
             "type": "string"
           },
           "group": {
-            "description": "字段的展示分组。",
+            "description": "控制台中对字段分组展示所用的组名，如 `error`、`action`、`device`；无分组时为空。",
             "type": "string"
           },
           "is_facet": {
@@ -1883,7 +1982,7 @@
             "type": "boolean"
           },
           "scopes": {
-            "description": "该字段所属的 RUM scope 列表。",
+            "description": "该字段所属的 RUM scope，取值与请求中的 `scopes` 相同（如 `error`、`issue`）。",
             "items": {
               "type": "string"
             },
@@ -1898,15 +1997,34 @@
             "type": "string"
           },
           "status": {
-            "description": "字段状态，如 `active`。",
+            "description": "字段状态。`enabled`：字段在用；`disabled`：字段已定义但被停用。已删除的字段不会返回。",
+            "enum": [
+              "enabled",
+              "disabled"
+            ],
             "type": "string"
           },
           "unit_family": {
-            "description": "计量单位族，如 `time`、`bytes`。无量纲字段为空。",
+            "description": "计量单位族。`time`：时长或时间戳（具体见 `unit_name`）；`bytes`：字节大小；无量纲字段为空字符串。",
+            "enum": [
+              "",
+              "time",
+              "bytes"
+            ],
             "type": "string"
           },
           "unit_name": {
-            "description": "具体计量单位，如 `millisecond`、`byte`。",
+            "description": "存储值的单位。时长：`nanosecond`、`microsecond`、`millisecond`、`second`；时间戳：`unix_millisecond`、`unix_second`；大小：`byte`；无量纲字段为空字符串。大多数内置时长字段以 `nanosecond` 存储。",
+            "enum": [
+              "",
+              "nanosecond",
+              "microsecond",
+              "millisecond",
+              "second",
+              "unix_millisecond",
+              "unix_second",
+              "byte"
+            ],
             "type": "string"
           },
           "value_type": {
@@ -2007,11 +2125,11 @@
             "type": "boolean"
           },
           "console_origin": {
-            "description": "用于拼接 `issue_url` 列的控制台地址，如 `https://console.flashcat.cloud`；服务无法自行推断（SaaS、私有化与 dev 环境地址不同）。",
+            "description": "用于拼接 `issue_url` 列的控制台地址，如 `https://console.flashcat.cloud`，末尾的 `/` 会被去掉；服务无法自行推断。不传时 `issue_url` 只包含路径 `/rum/error-tracking/issue/<issue_id>`。",
             "type": "string"
           },
           "dql": {
-            "description": "DQL 高级过滤查询，不能与 `sql` 同时使用。",
+            "description": "DQL 高级过滤查询。字段名必须属于 `issue` 范围（可通过 `POST /rum/field/list` 并传 `scopes: [\"issue\"]` 查询）；不带字段名的全文检索词匹配错误信息。不能与 `sql` 同时使用。",
             "type": "string"
           },
           "end_time": {
@@ -2024,7 +2142,7 @@
             "type": "boolean"
           },
           "export_fields": {
-            "description": "要导出的 CSV 列，按出现顺序排列。未知键会被参数校验拒绝；传空数组则使用默认列集。\n\n| 值 | 列内容 |\n|---|---|\n| `issue_id` | Issue ID |\n| `issue_url` | Issue 详情页的控制台链接（基于 `console_origin` 拼接） |\n| `application_name` | 所属应用名称 |\n| `service` | 服务名 |\n| `error_type` | 错误类型 |\n| `error_message` | 错误信息 |\n| `status` | 处理状态 |\n| `severity` | 严重性 |\n| `is_crash` | 是否导致崩溃 |\n| `error_count` | 错误发生次数 |\n| `session_count` | 受影响会话数 |\n| `first_seen_at` | 首次出现时间（按 `time_zone` 渲染） |\n| `first_seen_version` | 首次出现时的应用版本 |\n| `last_seen_at` | 最近出现时间（按 `time_zone` 渲染） |\n| `last_seen_version` | 最近出现时的应用版本 |\n| `versions` | 涉及的所有版本 |\n| `suspected_cause` | 疑似根因分类 |\n| `resolved_at` | 解决时间（按 `time_zone` 渲染） |",
+            "description": "要导出的 CSV 列，按出现顺序排列。未知键会被参数校验拒绝，重复键会被去掉。传空数组或不传时导出下表中除 `sample_first_*` 外的全部列。\n\n| 值 | 列内容 |\n|---|---|\n| `issue_id` | Issue ID |\n| `issue_url` | Issue 详情页的控制台链接（基于 `console_origin` 拼接） |\n| `application_name` | 所属应用名称 |\n| `service` | 服务名 |\n| `error_type` | 错误类型 |\n| `error_message` | 错误信息 |\n| `status` | 处理状态 |\n| `severity` | 严重性 |\n| `is_crash` | 是否导致崩溃 |\n| `error_count` | 错误发生次数 |\n| `session_count` | 受影响会话数 |\n| `first_seen_at` | 首次出现时间（按 `time_zone` 渲染） |\n| `first_seen_version` | 首次出现时的应用版本 |\n| `last_seen_at` | 最近出现时间（按 `time_zone` 渲染） |\n| `last_seen_version` | 最近出现时的应用版本 |\n| `versions` | 涉及的所有版本 |\n| `suspected_cause` | 疑似根因分类 |\n| `resolved_at` | 解决时间（按 `time_zone` 渲染）；未解决时为空 |\n| `sample_time` | 时间窗内最近一条错误事件的事件发生时间（按 `time_zone` 渲染） |\n| `sample_version` | 时间窗内最近一条错误事件的应用版本 |\n| `sample_view` | 时间窗内最近一条错误事件的页面名称，名称为空时为页面 URL |\n| `sample_session_id` | 时间窗内最近一条错误事件的会话 ID |\n| `sample_device` | 时间窗内最近一条错误事件的设备品牌与型号 |\n| `sample_os` | 时间窗内最近一条错误事件的操作系统名称与版本 |\n| `sample_browser` | 时间窗内最近一条错误事件的浏览器名称与版本 |\n| `sample_stack` | 时间窗内最近一条错误事件的错误堆栈，最多保留前 20 行 |\n| `sample_first_time` | 时间窗内最早一条错误事件的事件发生时间（按 `time_zone` 渲染） |\n| `sample_first_version` | 时间窗内最早一条错误事件的应用版本 |\n| `sample_first_view` | 时间窗内最早一条错误事件的页面名称，名称为空时为页面 URL |\n| `sample_first_session_id` | 时间窗内最早一条错误事件的会话 ID |\n| `sample_first_device` | 时间窗内最早一条错误事件的设备品牌与型号 |\n| `sample_first_os` | 时间窗内最早一条错误事件的操作系统名称与版本 |\n| `sample_first_browser` | 时间窗内最早一条错误事件的浏览器名称与版本 |\n| `sample_first_stack` | 时间窗内最早一条错误事件的错误堆栈，最多保留前 20 行 |",
             "items": {
               "enum": [
                 "issue_id",
@@ -2044,7 +2162,23 @@
                 "last_seen_version",
                 "versions",
                 "suspected_cause",
-                "resolved_at"
+                "resolved_at",
+                "sample_time",
+                "sample_version",
+                "sample_view",
+                "sample_session_id",
+                "sample_device",
+                "sample_os",
+                "sample_browser",
+                "sample_stack",
+                "sample_first_time",
+                "sample_first_version",
+                "sample_first_view",
+                "sample_first_session_id",
+                "sample_first_device",
+                "sample_first_os",
+                "sample_first_browser",
+                "sample_first_stack"
               ],
               "type": "string"
             },
@@ -2073,11 +2207,11 @@
             "type": "integer"
           },
           "sql": {
-            "description": "SQL 式高级过滤查询，不能与 `dql` 同时使用。",
+            "description": "SQL 风格的 WHERE 条件，用于高级过滤，不带 `WHERE` 关键字（例如 `error_count > 100`）。字段名必须属于 `issue` 范围；包含 `SELECT` 的内容会被拒绝。不能与 `dql` 同时使用。",
             "type": "string"
           },
           "start_time": {
-            "description": "时间范围起始，Unix 毫秒时间戳。",
+            "description": "时间范围起点，Unix 毫秒时间戳（秒级时间戳会被拒绝）。默认按 Issue 创建时间匹配，`by_intersection` 为 `true` 时按活跃区间匹配。",
             "format": "int64",
             "type": "integer"
           },
@@ -2118,7 +2252,7 @@
             "type": "array"
           },
           "time_zone": {
-            "description": "渲染 CSV 时间戳所用的 IANA 时区名，如 `Asia/Shanghai`、`UTC`；默认 `Asia/Shanghai`。",
+            "description": "用于渲染 CSV 时间列和文件名的 IANA 时区，如 `Asia/Shanghai` 或 `UTC`。默认 `Asia/Shanghai`。时区名无效时返回 `InvalidParameter`。",
             "type": "string"
           }
         },
@@ -2169,7 +2303,7 @@
                 "type": "string"
               },
               "type": {
-                "description": "错误类型，来自错误事件的 `error_type` 字段（由 SDK 上报）。",
+                "description": "SDK 在错误事件 `error_type` 字段中上报的错误类型，为自由文本而非固定取值。浏览器错误为 JavaScript 异常名，如 `Error`、`TypeError`、`ReferenceError`。",
                 "type": "string"
               }
             },
@@ -2219,7 +2353,7 @@
             "type": "object"
           },
           "regression": {
-            "description": "回溯元数据，仅在已解决的 Issue 再次出现时存在。",
+            "description": "回归记录。仅在已解决的 Issue 因错误再次出现被重新打开后存在；Issue 再次被解决时清除。",
             "properties": {
               "regressed_at": {
                 "description": "检测到回溯的时间，Unix 毫秒时间戳。",
@@ -2239,15 +2373,23 @@
             "type": "object"
           },
           "resolved_at": {
-            "description": "标记为已解决的时间，Unix 时间戳（毫秒）；未解决时为 0。",
+            "description": "Issue 被标记为已解决（用户操作或系统自动）的时间，Unix 毫秒时间戳；未解决时为 `0`。",
             "format": "int64",
             "type": "integer"
           },
           "resolved_by": {
-            "description": "将 Issue 标记为已解决的用户 Person ID；未解决时为 0。",
+            "description": "将 Issue 标记为已解决的用户 Person ID；未解决或由系统自动解决时为 `0`。",
             "format": "int64",
             "type": "integer"
           },
+          "resolve_mode": {
+            "description": "Issue 已解决后错误再次出现时的处理方式：`any` 表示再次出现即重新打开；`version` 表示仅当错误出现在该 Issue 未出现过的应用版本中时才重新打开（不带版本的错误总会重新打开）。新建 Issue 和自动解决使用 `version`；通过 `POST /rum/issue/update` 解决且未传 `resolve_mode` 时设为 `any`。",
+            "enum": [
+              "any",
+              "version"
+            ],
+            "type": "string"
+          },
           "service": {
             "description": "产生该 Issue 的服务名，来自错误事件的 `service` 字段。",
             "type": "string"
@@ -2258,7 +2400,7 @@
             "type": "integer"
           },
           "severity": {
-            "description": "Issue 严重性：`Critical`（严重）、`Warning`（警告）、`Info`（提示）；引入严重性之前创建的历史 Issue 为空字符串。",
+            "description": "Issue 严重性，在 Issue 创建时确定：由第一条命中的已启用预设严重性规则决定（见 `POST /rum/issue/preset-severity/rules/list`），未命中时使用内置规则（崩溃为 `Critical`，其他错误按环境与错误信息关键词打分）。错误只会归入严重性相同或更高的已有 Issue，因此同一错误可能按严重性分成多个 Issue。引入严重性之前创建的旧 Issue 为空字符串。",
             "enum": [
               "Critical",
               "Warning",
@@ -2267,7 +2409,7 @@
             "type": "string"
           },
           "status": {
-            "description": "Issue 的处理状态；已软删除（`deleted`）的 Issue 不会出现在响应中。\n\n| 值 | 含义 |\n|---|---|\n| `for_review` | 待处理 |\n| `reviewed` | 已查看 |\n| `ignored` | 已忽略 |\n| `resolved` | 已解决 |",
+            "description": "Issue 的处理状态；已软删除（`deleted`）的 Issue 不会返回。错误 14 天未再出现，或应用发布了不再上报该错误的新版本时，系统会自动将 Issue 置为已解决；已解决的 Issue 再次出现错误时会重新打开为 `for_review`（见 `resolve_mode`）。\n\n| 值 | 含义 |\n|---|---|\n| `for_review` | 待处理 |\n| `reviewed` | 已查看 |\n| `ignored` | 已忽略 |\n| `resolved` | 已解决 |",
             "enum": [
               "for_review",
               "reviewed",
@@ -2285,7 +2427,7 @@
                 "type": "integer"
               },
               "reason": {
-                "description": "根因判定的理由说明，仅 AI 自动分析时生成；未启用 AI 或尚未分析时为空字符串。",
+                "description": "根因判定的自由文本说明，仅由 AI 分析生成；未启用 AI 分析、尚未分析或根因由用户指定时为空字符串。",
                 "type": "string"
               },
               "source": {
@@ -2322,14 +2464,40 @@
             "type": "integer"
           },
           "versions": {
-            "description": "该 Issue 出现过错误的应用版本列表（去重）；事件未携带版本信息时可能包含空字符串。",
+            "description": "该 Issue 出现过错误的应用版本列表（去重）；事件未携带版本信息时可能包含空字符串。从未记录版本列表的 Issue 返回 `null`。",
             "items": {
               "type": "string"
             },
-            "type": "array"
+            "type": [
+              "array",
+              "null"
+            ]
           }
         },
-        "type": "object"
+        "type": "object",
+        "required": [
+          "team_id",
+          "issue_id",
+          "application_id",
+          "application_name",
+          "service",
+          "status",
+          "error_count",
+          "session_count",
+          "is_crash",
+          "age",
+          "resolved_at",
+          "resolved_by",
+          "resolve_mode",
+          "created_at",
+          "updated_at",
+          "first_seen",
+          "last_seen",
+          "error",
+          "suspected_cause",
+          "versions",
+          "severity"
+        ]
       },
       "RumIssueListRequest": {
         "description": "查询 Issue 列表的过滤参数。",
@@ -2350,7 +2518,7 @@
             "type": "boolean"
           },
           "dql": {
-            "description": "DQL 高级过滤查询，不能与 `sql` 同时使用。",
+            "description": "DQL 高级过滤查询。字段名必须属于 `issue` 范围（可通过 `POST /rum/field/list` 并传 `scopes: [\"issue\"]` 查询）；不带字段名的全文检索词匹配错误信息。不能与 `sql` 同时使用。",
             "type": "string"
           },
           "end_time": {
@@ -2385,11 +2553,11 @@
             "type": "integer"
           },
           "sql": {
-            "description": "SQL 式高级过滤查询，不能与 `dql` 同时使用。",
+            "description": "SQL 风格的 WHERE 条件，用于高级过滤，不带 `WHERE` 关键字（例如 `error_count > 100`）。字段名必须属于 `issue` 范围；包含 `SELECT` 的内容会被拒绝。不能与 `dql` 同时使用。",
             "type": "string"
           },
           "start_time": {
-            "description": "时间范围起始，Unix 毫秒时间戳。",
+            "description": "时间范围起点，Unix 毫秒时间戳（秒级时间戳会被拒绝）。默认按 Issue 创建时间匹配，`by_intersection` 为 `true` 时按活跃区间匹配。",
             "format": "int64",
             "type": "integer"
           },
@@ -2464,7 +2632,7 @@
             "type": "string"
           },
           "status": {
-            "description": "新状态。设为 `resolved` 会记录解决时间与操作人；从 `resolved` 改为其他状态会将其清除。\n\n| 值 | 含义 |\n|---|---|\n| `for_review` | 待处理 |\n| `reviewed` | 已查看 |\n| `ignored` | 已忽略 |\n| `resolved` | 已解决 |",
+            "description": "新状态。将未解决的 Issue 设为 `resolved` 会记录解决时间与操作人并清除 `regression`；从 `resolved` 改为其他状态会清除解决时间与操作人。不传则保持当前状态。\n\n| 值 | 含义 |\n|---|---|\n| `for_review` | 待处理 |\n| `reviewed` | 已查看 |\n| `ignored` | 已忽略 |\n| `resolved` | 已解决 |",
             "enum": [
               "for_review",
               "reviewed",
@@ -2473,6 +2641,14 @@
             ],
             "type": "string"
           },
+          "resolve_mode": {
+            "description": "Issue 已解决后错误再次出现时的处理方式。只在同时传 `status: resolved` 时生效，此时不传默认为 `any`；传其他状态时忽略。\n\n| 值 | 含义 |\n|---|---|\n| `any` | 错误再次出现即重新打开 |\n| `version` | 仅当错误出现在该 Issue 未出现过的应用版本中时才重新打开；不带版本的错误总会重新打开 |",
+            "enum": [
+              "any",
+              "version"
+            ],
+            "type": "string"
+          },
           "suspected_cause": {
             "description": "新的疑似原因；设置后原因来源会标记为 `user`（用户指定），覆盖自动判定结果。取值：\n\n| 值 | 含义 |\n|---|---|\n| `api.failed_request` | API/接口请求失败 |\n| `network.error` | 网络连接错误 |\n| `code.exception` | 代码异常 |\n| `code.invalid_object_access` | 非法对象访问 |\n| `code.invalid_argument` | 非法参数 |\n| `unknown` | 未知原因 |",
             "enum": [
@@ -2504,7 +2680,7 @@
             "type": "string"
           },
           "filters": {
-            "description": "OR-of-ANDs 过滤结构：外层数组之间为 OR，内层数组内为 AND。当至少一个内层 AND 分组完全匹配时，该规则命中此错误。",
+            "description": "OR-of-ANDs 过滤结构：外层数组之间为 OR，内层数组内为 AND。当至少一个内层 AND 分组完全匹配时，该规则命中此错误。外层为空数组时永不命中；内层为空分组时命中所有错误。",
             "items": {
               "items": {
                 "$ref": "#/components/schemas/RumPresetSeverityRuleFilterCondition"
@@ -2563,7 +2739,7 @@
         "description": "AND 分组内的单条过滤条件。",
         "properties": {
           "key": {
-            "description": "过滤属性键。预设严重性规则仅支持以下 Error 级别属性。\n\n| 值 | 含义 |\n|---|---|\n| `error.usr_id` | 用户 ID |\n| `error.usr_email` | 用户邮箱 |\n| `error.view_url` | 错误发生页面的完整 URL |\n| `error.view_url_path` | 错误发生页面的 URL 路径 |\n| `error.error_type` | 错误类型 |\n| `error.error_message` | 错误信息 |\n| `error.env` | 环境（如 production/staging） |\n| `error.service` | 服务名 |\n| `error.device_type` | 设备类型 |\n| `error.os_name` | 操作系统名称 |\n| `error.browser_name` | 浏览器名称 |\n| `error.is_crash` | 是否为崩溃错误（布尔） |",
+            "description": "过滤属性键。预设严重性规则仅支持以下 Error 级别属性。\n\n| 值 | 含义 |\n|---|---|\n| `error.usr_id` | 用户 ID |\n| `error.usr_email` | 用户邮箱 |\n| `error.view_url` | 错误发生页面的完整 URL |\n| `error.view_url_path` | 错误发生页面的 URL 路径 |\n| `error.error_type` | 错误类型 |\n| `error.error_message` | 错误信息 |\n| `error.env` | 环境（如 production/staging） |\n| `error.service` | 服务名 |\n| `error.device_type` | 设备类型 |\n| `error.os_name` | 操作系统名称 |\n| `error.browser_name` | 浏览器名称 |\n| `error.is_crash` | 是否为崩溃错误，按字符串 `true` 或 `false` 比较 |",
             "enum": [
               "error.usr_id",
               "error.usr_email",
@@ -2581,7 +2757,7 @@
             "type": "string"
           },
           "oper": {
-            "description": "匹配语义：`IN` 表示字段值匹配 `vals` 中任意一个即命中；`NOTIN` 表示一个都不匹配才命中（字段缺失时也视为命中）。",
+            "description": "匹配语义：`IN` 表示属性值匹配 `vals` 中任意一个即命中；`NOTIN` 表示一个都不匹配才命中。错误未携带的属性按空字符串参与比较。",
             "enum": [
               "IN",
               "NOTIN"
@@ -2589,7 +2765,7 @@
             "type": "string"
           },
           "vals": {
-            "description": "待匹配的值列表。每一项支持精确字符串匹配、通配符（`*`/`?`）、正则（用 `/.../` 包裹）、面向 IP 类字段的 CIDR（`cidr:10.0.0.0/8`），或数值比较（如 `num:gt:100`、`num:le:50`）。",
+            "description": "待匹配的值列表，至少一项且不能为空字符串。每一项可以是：区分大小写的整值精确匹配；含 `*`/`?` 的通配符（匹配整个值）；用 `/.../` 包裹的正则（未用 `^`/`$` 锚定时匹配值中任意位置）；面向 IP 类值的 `cidr:<网段>`，如 `cidr:10.0.0.0/8`；或数值比较 `num:<op>:<数字>`，`op` 为 `lt`、`le`、`gt`、`ge` 之一，如 `num:gt:100`。`error.is_crash` 请使用 `true` 或 `false`。",
             "items": {
               "type": "string"
             },
@@ -2759,7 +2935,7 @@
             "type": "string"
           },
           "filters": {
-            "description": "OR-of-ANDs 过滤结构：外层数组之间为 OR，内层数组内为 AND。当至少一个内层 AND 分组完全匹配时，该规则命中此错误。",
+            "description": "OR-of-ANDs 过滤结构：外层数组之间为 OR，内层数组内为 AND。当至少一个内层 AND 分组完全匹配时，该规则命中此错误。外层为空数组时永不命中；内层为空分组时命中所有错误。",
             "items": {
               "items": {
                 "$ref": "#/components/schemas/RumPresetSeverityRuleFilterCondition"
@@ -2863,7 +3039,7 @@
             "type": "string"
           },
           "filters": {
-            "description": "OR-of-ANDs 过滤结构：外层数组之间为 OR，内层数组内为 AND。当至少一个内层 AND 分组完全匹配时，该规则命中此错误。",
+            "description": "OR-of-ANDs 过滤结构：外层数组之间为 OR，内层数组内为 AND。当至少一个内层 AND 分组完全匹配时，该规则命中此错误。外层为空数组时永不命中；内层为空分组时命中所有错误。",
             "items": {
               "items": {
                 "$ref": "#/components/schemas/RumPresetSeverityRuleFilterCondition"
@@ -2987,7 +3163,7 @@
             ]
           },
           "filters": {
-            "description": "OR-of-ANDs 过滤结构：外层数组之间为 OR，内层数组内为 AND。当至少一个内层 AND 分组完全匹配时，该规则命中此错误。",
+            "description": "新的 OR-of-ANDs 过滤结构，整体替换当前结构。不传或传 `null` 则保持不变。外层数组之间为 OR，内层数组内为 AND；外层为空数组时永不命中，内层为空分组时命中所有错误。",
             "items": {
               "items": {
                 "$ref": "#/components/schemas/RumPresetSeverityRuleFilterCondition"
@@ -3047,15 +3223,15 @@
         "type": "object"
       },
       "RumReplayForegroundPeriod": {
-        "description": "App 处于前台的一段时间区间（移动端会话）。",
+        "description": "视图处于前台（获得焦点）的一段时间。",
         "properties": {
           "end": {
-            "description": "前台区间结束的 Unix 毫秒时间戳。",
+            "description": "前台时间段的结束，表示距 `view_id` 对应视图开始时刻的**纳秒**数（不是 Unix 时间戳）。",
             "format": "int64",
             "type": "integer"
           },
           "start": {
-            "description": "前台区间开始的 Unix 毫秒时间戳。",
+            "description": "前台时间段的开始，表示距 `view_id` 对应视图开始时刻的**纳秒**数（不是 Unix 时间戳）。",
             "format": "int64",
             "type": "integer"
           },
@@ -3069,7 +3245,7 @@
       "RumReplaySession": {
         "properties": {
           "end": {
-            "description": "会话结束（或活跃会话最后更新）的 Unix 毫秒时间戳。",
+            "description": "会话结束时间（Unix 毫秒）：取会话记录的结束时间与所返回视图最晚结束时间中的较大值。",
             "format": "int64",
             "type": "integer"
           },
@@ -3078,7 +3254,7 @@
             "type": "boolean"
           },
           "server_time_delta": {
-            "description": "客户端与 Flashduty 服务端之间的时钟偏移（毫秒），用于校正客户端时间戳。",
+            "description": "恒为 `0`：时间戳按客户端记录原样返回，不做时钟偏差校正。",
             "format": "int64",
             "type": "integer"
           },
@@ -3110,7 +3286,20 @@
       "RumReplayView": {
         "properties": {
           "container_source": {
-            "description": "该视图嵌套展示时，容器应用的 SDK 平台（如原生应用内的 WebView）；未嵌套时省略。",
+            "description": "嵌入该视图的宿主应用的 SDK 平台（例如原生应用中的 WebView）。视图未被嵌入时不返回。\n\n| 取值 | 含义 |\n|---|---|\n| `browser` | Web 浏览器应用 |\n| `ios` | Apple iOS 应用 |\n| `android` | Android 应用 |\n| `react-native` | React Native 应用 |\n| `flutter` | Flutter 应用 |\n| `kotlin-multiplatform` | Kotlin Multiplatform 应用 |\n| `roku` | Roku 频道应用 |\n| `unity` | Unity 应用 |\n| `miniprogram` | 微信小程序 |\n| `harmony` | HarmonyOS 应用 |\n| `electron` | Electron 桌面应用 |",
+            "enum": [
+              "browser",
+              "ios",
+              "android",
+              "react-native",
+              "flutter",
+              "kotlin-multiplatform",
+              "roku",
+              "unity",
+              "miniprogram",
+              "harmony",
+              "electron"
+            ],
             "type": "string"
           },
           "container_view_id": {
@@ -3127,7 +3316,7 @@
             "type": "boolean"
           },
           "loading_type": {
-            "description": "进入该视图的方式，如 `initial_load`、`route_change`。",
+            "description": "SDK 上报的视图进入方式。Web：`initial_load`、`route_change`；移动端：`activity_display`、`activity_redisplay`、`fragment_display`、`fragment_redisplay`、`view_controller_display`、`view_controller_redisplay`。未上报时为空。",
             "type": "string"
           },
           "name": {
@@ -3135,7 +3324,7 @@
             "type": "string"
           },
           "server_time_delta": {
-            "description": "客户端与 Flashduty 服务端之间的时钟偏移（毫秒），用于校正客户端时间戳。",
+            "description": "恒为 `0`：时间戳按客户端记录原样返回，不做时钟偏差校正。",
             "format": "int64",
             "type": "integer"
           },
@@ -3251,7 +3440,7 @@
             "type": "integer"
           },
           "session_investigate.free_cnt": {
-            "description": "每个应用、每个计费窗口的异常追踪会话免费额度。",
+            "description": "每个应用在每个计费窗口内的 investigate（错误追踪） 会话免费额度。负数表示不限量。",
             "format": "int64",
             "type": "integer"
           },
@@ -3261,11 +3450,11 @@
             "type": "integer"
           },
           "session_limit_reached": {
-            "description": "`version=free` 的账户在所有应用的免费会话额度合计用尽后为 `true`；非免费套餐恒为 `false`。",
+            "description": "`version=free` 的账户在当前窗口内的 investigate 或 replay 会话数达到「单应用免费额度 × 应用数」时为 `true`。非免费套餐、或账户尚无应用时始终为 `false`。",
             "type": "boolean"
           },
           "session_measure.free_cnt": {
-            "description": "每个应用、每个计费窗口的性能监控会话免费额度。",
+            "description": "每个应用在每个计费窗口内的 measure（性能） 会话免费额度。负数表示不限量。",
             "format": "int64",
             "type": "integer"
           },
@@ -3275,7 +3464,7 @@
             "type": "integer"
           },
           "session_replay.free_cnt": {
-            "description": "每个应用、每个计费窗口的会话重放免费额度。",
+            "description": "每个应用在每个计费窗口内的 会话回放 会话免费额度。负数表示不限量。",
             "format": "int64",
             "type": "integer"
           },
@@ -3362,7 +3551,7 @@
             "description": "录制该会话的设备。"
           },
           "foreground_periods": {
-            "description": "会话内的前台时间区间（仅移动端会话；Web 端为空）。",
+            "description": "视图处于前台（获得焦点）的时间段，汇总自所有返回的视图。SDK 未上报时为空数组。",
             "items": {
               "$ref": "#/components/schemas/RumReplayForegroundPeriod"
             },
@@ -3373,7 +3562,7 @@
             "description": "会话的起止时间与状态。"
           },
           "views": {
-            "description": "会话内录制的全部视图，按时间顺序排列。",
+            "description": "该会话中带有回放数据的视图，按开始时间升序排列。",
             "items": {
               "$ref": "#/components/schemas/RumReplayView"
             },
@@ -3390,7 +3579,7 @@
             "type": "string"
           },
           "ts": {
-            "description": "会话起始时间的 Unix 毫秒时间戳。可选；当 `session_id` 在不同时间窗口内被复用时用于区分。",
+            "description": "会话开始时间，Unix 毫秒时间戳，可选。传入时必须与会话开始时间完全一致；用于在 `session_id` 被复用时选中其中一个会话。",
             "exclusiveMinimum": 0,
             "format": "int64",
             "type": "integer"
@@ -3420,7 +3609,7 @@
             "type": "string"
           },
           "ts": {
-            "description": "Unix 毫秒时间戳。设置该字段且 `search_after_ctx` 为空时，将从该时间点之前最近的一个全量快照分段开始，而非从头开始。",
+            "description": "Unix 毫秒时间戳。传入且 `search_after_ctx` 为空时，从该时间点及之前最近的全量快照分段开始分页（最多向前查找 4 小时）；找不到时从头开始。",
             "exclusiveMinimum": 0,
             "format": "int64",
             "type": "integer"
@@ -3443,14 +3632,14 @@
         "description": "分段的预签名下载地址，仅当 `url_mode` 为 `true` 时返回。",
         "properties": {
           "items": {
-            "description": "预签名、限时（1 小时内有效）的下载地址，用于获取每个分段的原始压缩字节。",
+            "description": "各分段对象的预签名下载地址，1 小时内有效。对象内容为 zlib 压缩数据，解压后即为分段 JSON。",
             "items": {
               "type": "string"
             },
             "type": "array"
           },
           "search_after_ctx": {
-            "description": "用于下一次调用 `search_after_ctx` 的分页游标。为该会话最后一页时为空。",
+            "description": "下一次调用时作为 `search_after_ctx` 传入的游标。本页返回满 `limit` 个分段时即会给出（下一页可能为空）；不足 `limit` 时为空字符串。",
             "type": "string"
           }
         },
@@ -3460,11 +3649,11 @@
         "description": "发送 RUM 告警样例 Webhook 的参数。",
         "properties": {
           "application_id": {
-            "description": "RUM 应用 ID，可通过 `POST /rum/application/list` 获取。",
+            "description": "RUM 应用 ID，其名称会写入样例事件的 `labels.application_name`。调用者须对该应用有编辑权。可通过 `POST /rum/application/list` 获取应用 ID。",
             "type": "string"
           },
           "webhook_url": {
-            "description": "接收样例告警事件的 Webhook URL。",
+            "description": "接收样例告警事件的 Webhook URL，必须使用 `http` 或 `https`。不会被保存：如需保存，请通过 `POST /rum/application/update` 设置 `alerting.webhook_url`。",
             "format": "uri",
             "type": "string"
           }
@@ -3479,15 +3668,15 @@
         "description": "Webhook 测试投递结果。",
         "properties": {
           "message": {
-            "description": "成功时为 `ok`，失败时为投递错误信息。",
+            "description": "成功时为 `ok`。否则：对端返回错误状态码时为 `unexpected status <code>`，未收到响应时为 `request failed: <error>`。",
             "type": "string"
           },
           "ok": {
-            "description": "Webhook 端点是否接受了样例事件。",
+            "description": "对端（跟随重定向后）返回 400 以下状态码时为 `true`，否则为 `false`。",
             "type": "boolean"
           },
           "status_code": {
-            "description": "Webhook 端点返回的 HTTP 状态码。未收到响应时为 0。",
+            "description": "最后一次投递尝试的 HTTP 状态码。未收到响应（连接错误或超时）时为 `0`。",
             "type": "integer"
           }
         },
@@ -3542,11 +3731,6 @@
             "type": "string"
           }
         },
-        "required": [
-          "uuid",
-          "name",
-          "is_system"
-        ],
         "type": "object"
       },
       "SourcemapCodeSnippet": {
@@ -3618,7 +3802,7 @@
             "type": "string"
           },
           "key": {
-            "description": "唯一标识该 Sourcemap 文件的存储键。",
+            "description": "记录标识：根据上传文件的身份（存储路径，或 native 符号的服务/版本/构建标识）计算出的 32 位十六进制 MD5 摘要。",
             "type": "string"
           },
           "metadata": {
@@ -3679,7 +3863,7 @@
             "type": "boolean"
           },
           "build_id": {
-            "description": "仅 Android。按 Gradle 插件构建标识过滤。最多 200 个字符。",
+            "description": "按构建 ID 子串过滤（Android Gradle 插件构建标识，或 native 符号的 build ID）。最多 200 个字符。",
             "maxLength": 200,
             "type": "string"
           },
@@ -3751,7 +3935,7 @@
             "type": "string"
           },
           "uuid": {
-            "description": "仅 iOS。按 dSYM bundle UUID 过滤。最多 200 个字符。",
+            "description": "仅 iOS。按 dSYM UUID 子串过滤，匹配前会转为大写并去掉连字符。最多 200 个字符。",
             "maxLength": 200,
             "type": "string"
           },
@@ -3793,7 +3977,7 @@
         "description": "错误栈 enrich 请求。",
         "properties": {
           "arch": {
-            "description": "Android NDK 架构，例如 `arm`、`arm64`、`x86` 或 `x64`。",
+            "description": "native CPU 架构，如 `arm`、`arm64`、`x86`、`x64`。`type: android` 且 `source_type` 为空时，传入 `arch` 即按 NDK native 符号化。",
             "type": "string"
           },
           "binary_images": {
@@ -3830,7 +4014,7 @@
             "type": "string"
           },
           "source_type": {
-            "description": "Android 错误来源类型；native 符号化时配合 `arch` 传入 `ndk`。",
+            "description": "SDK 上报的错误 `error.source_type`，会改变符号化路由：`android` 下值中含 `ndk` 时使用 NDK native 符号；`flutter` 与 `react-native` 下 `ios` 使用 dSYM、`android`/`ndk` 使用 Android 符号；`electron` 下 `macos`、`windows`、`linux` 使用 Breakpad 符号。其他类型忽略此字段。",
             "type": "string"
           },
           "stack": {
@@ -3932,7 +4116,7 @@
         "description": "成功响应结构。2xx 响应中 `request_id` 标识本次调用（同时出现在 `Flashcat-Request-Id` 响应头中），`data` 为接口业务 payload。失败响应使用不同结构，参见 `ErrorResponse`。",
         "properties": {
           "data": {
-            "description": "每个接口自己的业务 payload，详见各接口的 200 响应 schema。"
+            "description": "接口返回的数据，格式见各接口的 200 响应。没有返回数据的接口会返回 `{}` 或完全不带 `data`。"
           },
           "request_id": {
             "description": "本次请求的唯一 ID，也会在 Flashcat-Request-Id 响应头中返回。反馈问题时请一并附上。",
@@ -3941,8 +4125,7 @@
           }
         },
         "required": [
-          "request_id",
-          "data"
+          "request_id"
         ],
         "type": "object"
       },
@@ -3950,14 +4133,15 @@
         "description": "发布一个全新的远程配置版本。客户端需提交完整对象而非增量补丁：规则顺序承载语义。",
         "properties": {
           "application_id": {
-            "description": "RUM 应用 ID。",
+            "description": "RUM 应用 ID，可通过 `POST /rum/application/list` 获取。",
             "type": "string"
           },
           "config": {
-            "$ref": "#/components/schemas/RemoteConfig"
+            "$ref": "#/components/schemas/RemoteConfig",
+            "description": "要发布的完整配置。"
           },
           "reason": {
-            "description": "操作者留下的发布说明，原样保存。",
+            "description": "可选的自由文本备注（非枚举），说明发布该版本的原因，最多 255 个字符；按原样保存，并在 `POST /rum/application/remote-config/history/list` 的 `reason` 中返回。",
             "maxLength": 255,
             "type": "string"
           }
@@ -3972,7 +4156,7 @@
         "description": "本次发布分配到的版本号。",
         "properties": {
           "version": {
-            "description": "新发布的版本号。",
+            "description": "为本次发布分配的版本号（此前最大版本号 + 1）。",
             "type": "integer"
           }
         },
@@ -4004,7 +4188,7 @@
     },
     "securitySchemes": {
       "AppKeyAuth": {
-        "description": "在 Flashduty 控制台 账户 → APP Key 中签发的 app_key。调用任何公开 API 时都必须携带。它等同于所属账户的身份凭证，请妥善保管。",
+        "description": "在 Flashduty 控制台 我的 → APP Key 中创建的 APP Key。可通过 query 参数 `app_key` 或请求头 `Fd-App-Key` 传入。实际可访问范围是该 APP Key 的权限范围与创建者当前角色权限的交集，请妥善保管。",
         "in": "query",
         "name": "app_key",
         "type": "apiKey"
@@ -4012,7 +4196,7 @@
     }
   },
   "info": {
-    "description": "Flashduty 事件管理平台的公开 HTTP API —— 覆盖故障、通知模板、协作空间、值班排班、监控、RUM、以及平台管理。每次调用都需在 query 中携带 `app_key`，该 key 在 Flashduty 控制台 账户 → APP Key 中签发。所有响应使用统一结构：成功时为 `{ request_id, data }`，失败时为 `{ request_id, error }`。",
+    "description": "Flashduty 事件管理平台的公开 HTTP API —— 覆盖故障、通知模板、协作空间、值班排班、监控、RUM、以及平台管理。每次调用都需在 query 中携带 `app_key`，该 key 在 Flashduty 控制台 我的 → APP Key 中创建（也可放在请求头 `Fd-App-Key` 中）。所有响应使用统一结构：成功时为 `{ request_id, data }`，失败时为 `{ request_id, error }`。",
     "title": "Flashduty 开放 API",
     "version": "1.0.0"
   },
@@ -4092,6 +4276,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -4104,7 +4291,7 @@
           "RUM/应用管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **应用管理**（`rum`） |\n\n## 使用说明\n\n- `type` 须为以下之一：`browser`、`ios`、`android`、`react-native`、`flutter`、`kotlin-multiplatform`、`roku`、`unity`、`miniprogram`、`harmony`、`electron`。\n- `links.systems[].url` 必须以 `http` 或 `https` 开头；`${var}` 变量会根据 RUM 事件上下文解析。\n- `links.systems[].event_types` 支持：`crash`、`error`、`view`、`action`、`resource`、`session`、`all`。\n- `client_token` 自动生成，用于初始化 RUM SDK。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **应用管理**（`rum`） |\n\n## 使用说明\n\n- `type` 须为以下之一：`browser`、`ios`、`android`、`react-native`、`flutter`、`kotlin-multiplatform`、`roku`、`unity`、`miniprogram`、`harmony`、`electron`。\n- `client_token` 由服务端生成，用于初始化 RUM SDK；之后也可通过 `POST /rum/application/info` 再次获取。\n- 传入 `tracing` 时，即使 `enabled` 为 `false`，也必须提供 `open_type`（`popup` 或 `tab`）和以 `http`/`https` 开头的 `endpoint`。\n- `links.systems[].url` 必须以 `http` 或 `https` 开头；每个系统都需要 `name` 和至少一个 `event_types`。\n- `alerting.delivery_mode` 为 `oncall`（Flashduty 云端默认值）时，服务端会创建或复用账户的 RUM 告警集成，并在 `alerting.integration_id` 中返回其 ID。\n- 服务端不校验 `team_id` 是否为调用者所在的团队。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/rum/applications/rum-application-write-create",
           "metadata": {
             "sidebarTitle": "创建应用"
@@ -4162,6 +4349,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -4174,7 +4364,7 @@
           "RUM/应用管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **应用管理**（`rum`） |\n\n## 使用说明\n\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **应用管理**（`rum`） |\n\n## 使用说明\n\n- 删除为软删除：应用会从列表、详情和批量详情中消失，之后使用该 ID 的调用会失败（返回 `InvalidParameter`，远程配置相关接口返回 `ResourceNotFound`）。没有恢复接口。\n- 应用的 `client_token` 会在约 5 分钟内被数据接入端拒绝；已采集的数据不会被删除。\n- 调用者须对该应用有编辑权：账户所有者、账户管理员、应用创建者或所属团队成员，否则返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/rum/applications/rum-application-write-delete",
           "metadata": {
             "sidebarTitle": "删除应用"
@@ -4211,7 +4401,8 @@
                         2490121812131
                       ],
                       "enabled": true,
-                      "integration_id": 4759595678131
+                      "integration_id": 4759595678131,
+                      "delivery_mode": "oncall"
                     },
                     "application_id": "WoyQQ3BohkdtPivubEvE8o",
                     "application_name": "flashcat-rum",
@@ -4247,7 +4438,13 @@
                     },
                     "type": "browser",
                     "updated_at": 1773398630657,
-                    "updated_by": 3790925372131
+                    "updated_by": 3790925372131,
+                    "repositories": [
+                      {
+                        "repo": "acme/web-app",
+                        "subdir": "apps/web"
+                      }
+                    ]
                   },
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 },
@@ -4276,6 +4473,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -4288,7 +4488,7 @@
           "RUM/应用管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- `application_id` 不存在或已删除时返回 `InvalidParameter`。\n- 私有应用（`is_private: true`）仅账户所有者、账户管理员、应用创建者和所属团队成员可读，其他人返回 `AccessDenied`。",
           "href": "/zh/api-reference/rum/applications/rum-application-read-info",
           "metadata": {
             "sidebarTitle": "查看应用详情"
@@ -4331,7 +4531,8 @@
                             5967875767131
                           ],
                           "enabled": true,
-                          "integration_id": 4759595678131
+                          "integration_id": 4759595678131,
+                          "delivery_mode": "oncall"
                         },
                         "application_id": "eWbr4xk3ZRnLabRa6unqwD",
                         "application_name": "Flashduty DEV",
@@ -4354,7 +4555,8 @@
                         },
                         "type": "browser",
                         "updated_at": 1772096392711,
-                        "updated_by": 3122470302131
+                        "updated_by": 3122470302131,
+                        "repositories": []
                       },
                       {
                         "account_id": 2451002751131,
@@ -4363,7 +4565,8 @@
                             2490121812131
                           ],
                           "enabled": true,
-                          "integration_id": 4759595678131
+                          "integration_id": 4759595678131,
+                          "delivery_mode": "oncall"
                         },
                         "application_id": "WoyQQ3BohkdtPivubEvE8o",
                         "application_name": "flashcat-rum",
@@ -4399,7 +4602,8 @@
                         },
                         "type": "browser",
                         "updated_at": 1773398630657,
-                        "updated_by": 3790925372131
+                        "updated_by": 3790925372131,
+                        "repositories": []
                       }
                     ]
                   },
@@ -4430,6 +4634,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -4442,7 +4649,7 @@
           "RUM/应用管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 每次请求最多传入 200 个 ID。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 重复的 ID 会被去重；不存在或已删除的 ID 会被直接跳过而不报错，因此 `items` 可能比 `application_ids` 短。\n- `items` 的顺序不保证与 `application_ids` 一致。",
           "href": "/zh/api-reference/rum/applications/rum-application-read-infos",
           "metadata": {
             "sidebarTitle": "批量查询应用详情"
@@ -4485,7 +4692,8 @@
                             2490121812131
                           ],
                           "enabled": true,
-                          "integration_id": 4759595678131
+                          "integration_id": 4759595678131,
+                          "delivery_mode": "oncall"
                         },
                         "application_id": "WoyQQ3BohkdtPivubEvE8o",
                         "application_name": "flashcat-rum",
@@ -4521,7 +4729,8 @@
                         },
                         "type": "browser",
                         "updated_at": 1773398630657,
-                        "updated_by": 3790925372131
+                        "updated_by": 3790925372131,
+                        "repositories": []
                       },
                       {
                         "account_id": 2451002751131,
@@ -4531,7 +4740,8 @@
                             5967875767131
                           ],
                           "enabled": true,
-                          "integration_id": 4759595678131
+                          "integration_id": 4759595678131,
+                          "delivery_mode": "oncall"
                         },
                         "application_id": "eWbr4xk3ZRnLabRa6unqwD",
                         "application_name": "Flashduty DEV",
@@ -4554,7 +4764,8 @@
                         },
                         "type": "browser",
                         "updated_at": 1772096392711,
-                        "updated_by": 3122470302131
+                        "updated_by": 3122470302131,
+                        "repositories": []
                       }
                     ],
                     "total": 7
@@ -4586,6 +4797,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -4598,7 +4812,7 @@
           "RUM/应用管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 使用 `is_my_team` 可过滤当前用户所在团队的应用。\n- 默认每页 20 条，最大 100 条。\n- `orderby` 支持 `created_at` 或 `updated_at`。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 调用者无权访问的私有应用不会出现在结果中；账户所有者和账户管理员可以看到全部应用。\n- `is_my_team: true` 只保留调用者所在团队拥有的应用；调用者不属于任何团队时，该过滤不生效。\n- `team_id`、`query`、`is_my_team` 之间是“与”关系。\n- 默认按 `updated_at` 倒序排列，可用 `orderby`/`asc` 调整。",
           "href": "/zh/api-reference/rum/applications/rum-application-read-list",
           "metadata": {
             "sidebarTitle": "查询应用列表"
@@ -4687,6 +4901,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -4699,7 +4916,7 @@
           "RUM/应用管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- `version` 为 `0` 表示该应用从未配置过远程配置，SDK 完全沿用初始化值。\n- 变更在客户端下一次会话开始时生效（`activation` 为 `immediate` 时立即生效）。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 首次发布前，`version` 和 `updated_at` 为 `0`，`config` 为 `null`；此时 SDK 完全使用初始化参数。\n- 除非 `activation` 为 `immediate`，变更在客户端下一个会话开始时生效。\n- `application_id` 不存在或已删除时返回 `ResourceNotFound`。私有应用（`is_private: true`）仅账户所有者、账户管理员、应用创建者和所属团队成员可读，其他人返回 `AccessDenied`。",
           "href": "/zh/api-reference/rum/applications/rum-application-remote-config-read-get",
           "metadata": {
             "sidebarTitle": "查看远程配置详情"
@@ -4765,12 +4982,13 @@
                             }
                           ]
                         },
-                        "content_hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
-                        "reason": "Tighten replay sampling for the Q4 launch",
+                        "content_hash": "9f86d081884c7d65",
+                        "reason": "Re-apply the v7 sampling after the test",
                         "updated_at": 1773398630657,
                         "updated_by": 4441703362131,
                         "updated_by_name": "Alice Zhang",
-                        "version": 8
+                        "version": 8,
+                        "equivalent_to": 7
                       },
                       {
                         "config": {
@@ -4801,7 +5019,7 @@
                             }
                           ]
                         },
-                        "content_hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
+                        "content_hash": "9f86d081884c7d65",
                         "reason": "",
                         "updated_at": 1772398630657,
                         "updated_by": 4441703362131,
@@ -4838,6 +5056,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -4850,7 +5071,7 @@
           "RUM/应用管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 默认按更新时间倒序（`orderby=updated_at`，`asc=false`）。\n- 内容相同的版本通过 `content_hash` 与 `equivalent_to` 标识，控制台据此提示\"这是某历史版本的相同内容\"。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 仅保留最近 50 个版本；发布新版本时更早的版本会被删除，之后无法再列出或回滚到这些版本。\n- 默认按最新在前排序（`orderby=updated_at`、`asc=false`）。无法识别的 `orderby` 会回退为 `updated_at`；时间相同则按 `version` 排序。\n- `content_hash` 和 `equivalent_to` 用于识别内容相同的版本，例如回滚后恢复的早期版本。",
           "href": "/zh/api-reference/rum/applications/rum-application-remote-config-read-history-list",
           "metadata": {
             "sidebarTitle": "查询远程配置历史列表"
@@ -4912,6 +5133,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -4924,7 +5148,7 @@
           "RUM/应用管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **应用管理**（`rum`） |\n\n## 使用说明\n\n- 回滚不会重写历史：旧版本内容会以新的版本号发布。\n- `reason` 留空时控制台会自动填入\"rolled back to vN\"。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **应用管理**（`rum`） |\n\n## 使用说明\n\n- 历史记录不会被改写：回滚会把早期版本的内容以新的版本号重新发布，并返回该版本号。\n- `version` 必须仍在保留的历史中（最近 50 个版本），否则返回 `InvalidParameter`（`version not found`）。\n- 恢复的内容会按当前规则重新校验，不再通过时返回 `InvalidParameter`。\n- 服务端不会自动生成 `reason`；未传时保存为空字符串。\n- 调用者须对该应用有编辑权：账户所有者、账户管理员、应用创建者或所属团队成员，否则返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/rum/applications/rum-application-remote-config-write-history-revert",
           "metadata": {
             "sidebarTitle": "回滚远程配置版本"
@@ -4992,6 +5216,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -5004,7 +5231,7 @@
           "RUM/应用管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 使用与引擎完全相同的匹配逻辑，结果与生产客户端实际获取一致。\n- 省略 `config` 时预览当前生效配置。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 使用与 SDK 配置下发端相同的规则匹配逻辑，不会发布任何内容。\n- 不传 `config` 则预览线上配置；传入的 `config` 会按更新接口的规则校验，不合法时返回 `InvalidParameter`。\n- 规则条件按字符串精确比较；请求中省略 `env`、`app_version` 或 `sdk` 时，依赖该字段的规则一定不命中。\n- 配置已关闭（`enabled: false`）或从未发布时，`values` 为空，`hit_rule_index` 为 `-1`。",
           "href": "/zh/api-reference/rum/applications/rum-application-remote-config-read-preview",
           "metadata": {
             "sidebarTitle": "预览远程配置"
@@ -5093,6 +5320,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -5105,7 +5335,7 @@
           "RUM/应用管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **应用管理**（`rum`） |\n\n## 使用说明\n\n- 必须提交完整配置对象而非增量补丁——规则顺序即优先级，部分更新没有无歧义的解释。\n- 每次调用都会分配新版本号，并在同一事务中写入历史记录。\n- 发布前可先调用 `POST /rum/application/remote-config/preview` 验证客户端将拿到的值。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **应用管理**（`rum`） |\n\n## 使用说明\n\n- 需提交完整配置而非增量补丁：规则顺序即优先级，部分更新没有明确含义。\n- 每次调用都会发布一个新版本，即使内容未变或 `enabled` 为 `false`；仅保留最近 50 个版本。\n- 发布前可先调用 `POST /rum/application/remote-config/preview` 检查客户端会拿到的值。\n- 调用者须对该应用有编辑权：账户所有者、账户管理员、应用创建者或所属团队成员，否则返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/rum/applications/rum-application-remote-config-write-update",
           "metadata": {
             "sidebarTitle": "更新远程配置"
@@ -5115,7 +5345,7 @@
     },
     "/rum/application/update": {
       "post": {
-        "description": "更新已有 RUM 应用，除 `application_id` 外均为可选，仅更新提供的字段。",
+        "description": "更新 RUM 应用的指定字段；请求中未出现的字段保持原值。",
         "operationId": "rum-application-write-update",
         "requestBody": {
           "content": {
@@ -5187,6 +5417,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -5199,7 +5432,7 @@
           "RUM/应用管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **应用管理**（`rum`） |\n\n## 使用说明\n\n- `links.systems[].url` 必须以 `http` 或 `https` 开头；`${var}` 变量会根据 RUM 事件上下文解析。\n- `links.systems[].event_types` 支持：`crash`、`error`、`view`、`action`、`resource`、`session`、`all`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **应用管理**（`rum`） |\n\n## 使用说明\n\n- 只修改请求中出现的字段。传入 `alerting`、`tracing`、`links` 时会整体替换已保存的对象；`repositories` 会整体替换列表。\n- 传入 `tracing` 时，即使 `enabled` 为 `false`，也必须提供 `open_type`（`popup` 或 `tab`）和以 `http`/`https` 开头的 `endpoint`。\n- `links.systems[].url` 必须以 `http` 或 `https` 开头；每个系统都需要 `name` 和至少一个 `event_types`。\n- 传入 `alerting` 且 `delivery_mode` 为 `oncall` 时，沿用已有的 `integration_id`（没有则分配一个），客户端传入的 `integration_id` 会被忽略。\n- `application_id` 不存在或已删除时返回 `InvalidParameter`。调用者须对该应用有编辑权：账户所有者、账户管理员、应用创建者或所属团队成员，否则返回 `AccessDenied`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/rum/applications/rum-application-write-update",
           "metadata": {
             "sidebarTitle": "更新应用"
@@ -5215,7 +5448,7 @@
           "content": {
             "application/json": {
               "example": {
-                "application_id": "rum-app-prod",
+                "application_id": "WoyQQ3BohkdtPivubEvE8o",
                 "webhook_url": "https://hooks.example.com/rum-alerts"
               },
               "schema": {
@@ -5277,7 +5510,7 @@
           "RUM/应用管理"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **应用管理**（`rum`） |\n\n## 使用说明\n\n- 接口会先校验 URL，再发送样例事件。\n- 投递失败时仍返回 HTTP 200，但 `ok=false`，错误原因在 `message` 中。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- URL 必须使用 `http` 或 `https`；在 Flashduty 云端，解析到私有、回环、链路本地或保留地址的主机会被拒绝并返回 `InvalidParameter`。\n- 样例请求体与真实告警事件结构相同：`account_id`、`data_source_type`（`rum.alert`）、`title`、`event_severity`、`event_status`、`description`、`alert_key`、`labels` 以及 `event_time`（Unix 秒）。\n- 每次尝试 10 秒超时；传输错误、5xx 和 429 响应最多重试 2 次。\n- 投递失败时仍返回 HTTP 200，`ok` 为 `false`，原因在 `message` 中。\n- 调用者须对该应用有编辑权：账户所有者、账户管理员、应用创建者或所属团队成员，否则返回 `AccessDenied`。",
           "href": "/zh/api-reference/rum/applications/rum-application-webhook-test",
           "metadata": {
             "sidebarTitle": "测试应用 Webhook"
@@ -5298,8 +5531,7 @@
                   {
                     "format": "table",
                     "id": "errors_by_type",
-                    "sql": "SELECT error.type, count(*) AS errors FROM error GROUP BY error.type ORDER BY errors DESC LIMIT 10",
-                    "time_zone": "Asia/Shanghai"
+                    "sql": "SELECT error_type, count(*) AS errors FROM errors GROUP BY error_type ORDER BY errors DESC LIMIT 10"
                   }
                 ],
                 "start_time": 1712620800000
@@ -5321,23 +5553,23 @@
                       "data": {
                         "fields": [
                           {
-                            "name": "error.type",
-                            "nullable": false,
-                            "type": "String"
+                            "name": "error_type",
+                            "nullable": true,
+                            "type": "VARCHAR"
                           },
                           {
                             "name": "errors",
                             "nullable": false,
-                            "type": "UInt64"
+                            "type": "BIGINT"
                           }
                         ],
                         "values": [
                           [
                             "TypeError",
-                            1523
+                            "ReferenceError"
                           ],
                           [
-                            "ReferenceError",
+                            1523,
                             342
                           ]
                         ]
@@ -5371,6 +5603,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -5383,7 +5618,7 @@
           "RUM/RUM 数据查询"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 单次请求可提交 1 到 10 个查询；每个查询的 `id` 会成为响应对象中的 key。\n- `start_time` 和 `end_time` 必填，均为 Unix 毫秒时间戳；最大时间范围为 31 天。\n- 使用 `format: table` 返回表格结果，使用 `format: time_series` 返回按时间桶聚合的时序结果。\n- 当 `format: time_series` 时，省略 `interval` 会默认使用 3600 秒，省略 `max_points` 会默认使用 1226。\n- 分页表格查询会返回 `search_after_ctx`，继续扫描时可原样传回。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 单次请求可提交 1 到 10 个查询；每个查询的 `id` 会成为响应对象中的 key。\n- `start_time`、`end_time` 为 Unix 毫秒时间戳，跨度不超过 31 天。服务端会自动追加时间范围与账户过滤条件，`sql` 中无需再写。\n- `FROM` 填写 RUM 数据表名：`sessions`、`views`、`actions`、`errors`、`resources`、`long_tasks`、`vitals`、`issues` 或 `sourcemaps`（也接受单数形式）。列名即 `POST /rum/field/list` 返回的 `field_key`。\n- 若查询在顶层 `AND` 条件中用 `=` 或 `IN` 限定了 `application_id`，调用者必须能读取这些应用：所属团队不包含调用者的私有应用会让整个请求返回 `AccessDenied`，不存在的应用返回 `ResourceNotFound`，单次请求最多涉及 50 个不同应用。未限定应用的查询会自动跳过调用者无权读取的私有应用。\n- SQL 语法错误、`time_zone` 无效或时间范围不合法时，整个请求返回 `InvalidParameter`。之后阶段才失败的查询（表或列不存在、`dql` 无效、`search_after_ctx` 无效、数据库报错）只在该查询自己的结果中返回 `error`，错误码为 `InternalError`，其他查询仍正常返回 `data`。\n- `values` 按列组织：`values[i]` 是列 `fields[i]` 在所有行上的取值。\n- `table` 查询最多返回 1,000 行；未写 `LIMIT` 或超过 1,000 时按 1,000 处理。不含聚合、带 `ORDER BY` 且没有 `OFFSET` 的查询在本页取满时会返回 `search_after_ctx`，用相同的 `sql` 带上它即可取下一页。\n- `time_series` 查询会在最前面插入 `ts` 列（时间桶起点，Unix 毫秒），并按它分组、排序。桶宽以毫秒在 `interval` 中返回，取值为固定档位（1、2、5、10、20、50、100、200、500 毫秒；1、2、5、10、15、30 秒；1、2、5、10、15、30 分钟；1、2、3、6、12 小时；1、2、3、7 天；30、60、90、180 天）中同时不小于 `interval` 和「时间跨度 ÷ `max_points`」的最小一档。\n- 时间跨度较大时，聚合查询可能基于抽样数据执行；此时响应带有 `sampling`，且 `COUNT`、`SUM`、`COUNT(DISTINCT)` 列已乘以 `scale_factor`。设置 `disable_sampling: true` 可始终查询全量数据。",
           "href": "/zh/api-reference/rum/data-query/rum-read-data-query",
           "metadata": {
             "sidebarTitle": "查询 RUM 数据"
@@ -5393,43 +5628,36 @@
     },
     "/rum/error-ingestion/rules/create": {
       "post": {
-        "description": "创建一条新的错误采集规则，用于过滤要存储的错误。",
+        "description": "创建一条错误采集规则：命中的错误不再归入任何问题（Issue），但仍会照常入库。",
         "operationId": "rum-error-ingestion-rules-create",
         "requestBody": {
           "content": {
             "application/json": {
               "example": {
                 "application_id": "WoyQQ3BohkdtPivubEvE8o",
-                "description": "Only ingest TypeError/ReferenceError from production, excluding Safari.",
+                "description": "Keep cross-origin script errors, ResizeObserver warnings, and debug pages out of issues.",
                 "filters": [
                   [
                     {
-                      "key": "error.env",
-                      "oper": "IN",
-                      "vals": [
-                        "production"
-                      ]
-                    },
-                    {
-                      "key": "error.error_type",
+                      "key": "error.error_message",
                       "oper": "IN",
                       "vals": [
-                        "TypeError",
-                        "ReferenceError"
+                        "Script error.",
+                        "ResizeObserver loop*"
                       ]
                     }
                   ],
                   [
                     {
-                      "key": "error.browser_name",
-                      "oper": "NOTIN",
+                      "key": "error.view_url",
+                      "oper": "IN",
                       "vals": [
-                        "Safari"
+                        "https://example.com/debug/*"
                       ]
                     }
                   ]
                 ],
-                "rule_name": "Production console errors"
+                "rule_name": "Ignore browser noise"
               },
               "schema": {
                 "$ref": "#/components/schemas/RumErrorIngestionCreateRequest"
@@ -5445,7 +5673,7 @@
                 "example": {
                   "data": {
                     "rule_id": "9spXEVoMeZWujjz25yrgTe",
-                    "rule_name": "Production console errors"
+                    "rule_name": "Ignore browser noise"
                   },
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 },
@@ -5474,6 +5702,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -5486,7 +5717,7 @@
           "RUM/错误采集规则"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 创建、更新、启用、禁用、删除都会先把应用当前的全部规则快照进历史记录，因此 `history/list` 会反映每一次变更。\n- `filters` 中的每个条件 key 必须是受支持的 `error.*` 字段或 `context.*` 路径，不支持的 key 会返回 `InvalidParameter`。\n- 新建规则的初始状态为 `enabled`；如需创建后即处于停用状态，需再调用一次 `disable`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 命中的错误仍会入库、可正常查询，只是不会被归入任何问题，且其 `issue_grouping_excluded` 字段为 `true`。\n- 规则匹配的是 SDK 上报的原始错误类型和错误信息，发生在服务端解析堆栈之前。\n- `filters` 中每个条件的 key 必须是受支持的 `error.*` 字段或 `context.*` 路径；key 不受支持、操作符无效、`vals` 为空，或正则/CIDR/数值模式无效时，返回 `InvalidParameter`。\n- 新建规则的初始状态为 `enabled`；如需创建后即处于停用状态，需再调用一次 `disable`。\n- 每次写操作都会先把应用变更前的完整规则集合保存为一个新的历史版本。\n- 采集端按应用缓存已启用的规则，缓存有效期 5 秒，因此变更最多约 5 秒后对新上报的错误生效。\n- 需要对该应用有编辑权限（账户所有者或管理员、应用创建者、应用所属团队的成员），否则返回 `AccessDenied`；`application_id` 不存在时返回 `ResourceNotFound`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/rum/error-ingestion-rules/rum-error-ingestion-rules-create",
           "metadata": {
             "sidebarTitle": "创建错误采集规则"
@@ -5545,6 +5776,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -5557,7 +5791,7 @@
           "RUM/错误采集规则"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 删除后规则会立即从 `list` 结果中消失；但用于过滤判定的启用规则集有最多 5 秒缓存，因此删除后数秒内上报的错误仍可能被该规则匹配。\n- 若 `rule_id` 在该 `application_id` 下不存在，返回 `ResourceNotFound`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 删除后规则会立即从 `list` 结果中消失，且无法再启用或更新；如需恢复，可回滚到仍包含该规则的历史版本。\n- 若 `rule_id` 在该 `application_id` 下不存在（或已删除），返回 `ResourceNotFound`。\n- 每次写操作都会先把应用变更前的完整规则集合保存为一个新的历史版本。\n- 采集端按应用缓存已启用的规则，缓存有效期 5 秒，因此变更最多约 5 秒后对新上报的错误生效。\n- 需要对该应用有编辑权限（账户所有者或管理员、应用创建者、应用所属团队的成员），否则返回 `AccessDenied`；`application_id` 不存在时返回 `ResourceNotFound`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/rum/error-ingestion-rules/rum-error-ingestion-rules-delete",
           "metadata": {
             "sidebarTitle": "删除错误采集规则"
@@ -5616,6 +5850,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -5628,7 +5865,7 @@
           "RUM/错误采集规则"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 禁用的规则会保留并仍出现在 `list` 结果中，但不再参与错误匹配。\n- 若 `rule_id` 在该 `application_id` 下不存在，返回 `ResourceNotFound`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 禁用的规则会保留并仍出现在 `list` 结果中，但不再参与错误匹配。\n- 若 `rule_id` 在该 `application_id` 下不存在（或已删除），返回 `ResourceNotFound`。\n- 每次写操作都会先把应用变更前的完整规则集合保存为一个新的历史版本。\n- 采集端按应用缓存已启用的规则，缓存有效期 5 秒，因此变更最多约 5 秒后对新上报的错误生效。\n- 需要对该应用有编辑权限（账户所有者或管理员、应用创建者、应用所属团队的成员），否则返回 `AccessDenied`；`application_id` 不存在时返回 `ResourceNotFound`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/rum/error-ingestion-rules/rum-error-ingestion-rules-disable",
           "metadata": {
             "sidebarTitle": "禁用错误采集规则"
@@ -5687,6 +5924,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -5699,7 +5939,7 @@
           "RUM/错误采集规则"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 若 `rule_id` 在该 `application_id` 下不存在，返回 `ResourceNotFound`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 对已启用的规则再次启用也会成功，并同样生成一个历史版本。\n- 若 `rule_id` 在该 `application_id` 下不存在（或已删除），返回 `ResourceNotFound`。\n- 每次写操作都会先把应用变更前的完整规则集合保存为一个新的历史版本。\n- 采集端按应用缓存已启用的规则，缓存有效期 5 秒，因此变更最多约 5 秒后对新上报的错误生效。\n- 需要对该应用有编辑权限（账户所有者或管理员、应用创建者、应用所属团队的成员），否则返回 `AccessDenied`；`application_id` 不存在时返回 `ResourceNotFound`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/rum/error-ingestion-rules/rum-error-ingestion-rules-enable",
           "metadata": {
             "sidebarTitle": "启用错误采集规则"
@@ -5744,38 +5984,31 @@
                             "created_at": 1786000000000,
                             "created_by": 1001,
                             "deleted_at": 0,
-                            "description": "Only ingest TypeError/ReferenceError from production, excluding Safari.",
+                            "description": "Keep cross-origin script errors, ResizeObserver warnings, and debug pages out of issues.",
                             "filters": [
                               [
                                 {
-                                  "key": "error.env",
-                                  "oper": "IN",
-                                  "vals": [
-                                    "production"
-                                  ]
-                                },
-                                {
-                                  "key": "error.error_type",
+                                  "key": "error.error_message",
                                   "oper": "IN",
                                   "vals": [
-                                    "TypeError",
-                                    "ReferenceError"
+                                    "Script error.",
+                                    "ResizeObserver loop*"
                                   ]
                                 }
                               ],
                               [
                                 {
-                                  "key": "error.browser_name",
-                                  "oper": "NOTIN",
+                                  "key": "error.view_url",
+                                  "oper": "IN",
                                   "vals": [
-                                    "Safari"
+                                    "https://example.com/debug/*"
                                   ]
                                 }
                               ]
                             ],
                             "id": 1044,
                             "rule_id": "9spXEVoMeZWujjz25yrgTe",
-                            "rule_name": "Production console errors",
+                            "rule_name": "Ignore browser noise",
                             "status": "enabled",
                             "updated_at": 1786000000000,
                             "updated_by": 1001
@@ -5823,6 +6056,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -5835,7 +6071,7 @@
           "RUM/错误采集规则"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 每条历史记录都是该应用在某一时刻全部规则的完整快照，而不是单条规则的差异。\n- `p` 是从 0 开始的页码，不是字节偏移量——服务端内部按 `offset = p * limit` 计算。\n- `orderby` 仅支持 `updated_at` 或 `version`；传入其他值会被静默回退为 `updated_at`。\n- `limit` 默认 20，服务端上限 100；超过 100 会被静默截断，小于等于 0 时回退为默认值。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 每次写操作都会先保存变更前的规则集合，因此版本 N 记录的是第 N 次变更之前的规则，其 `updated_by`/`updated_at` 对应的就是这第 N 次变更。当前生效的规则集合请用 `list` 查询，不在此返回。\n- 每条历史记录都是该应用全部未删除规则的完整快照，而不是单条规则的差异。\n- `p` 是从 0 开始的页码：服务端跳过 `p * limit` 条记录。\n- `limit` 默认 20，上限 100；超过 100 会被截断为 100，小于等于 0 时回退为默认值。\n- 公开应用任何成员都可读取；私有应用需要编辑权限（账户所有者或管理员、应用创建者、应用所属团队的成员），否则返回 `AccessDenied`；`application_id` 不存在时返回 `ResourceNotFound`。",
           "href": "/zh/api-reference/rum/error-ingestion-rules/rum-error-ingestion-rules-history-list",
           "metadata": {
             "sidebarTitle": "查询错误采集规则历史"
@@ -5894,6 +6130,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -5906,7 +6145,7 @@
           "RUM/错误采集规则"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 回滚会替换该应用的整个规则集合——目标版本之后新建的规则会被移除，而不是合并保留。\n- 回滚前会先把当前状态快照进历史记录，因此回滚操作本身也可以通过再次回滚来撤销。\n- 若 `version` 在该应用下不存在，返回的是 `InvalidParameter` 而不是 `ResourceNotFound`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 版本 N 记录的是第 N 次变更之前的规则，因此回滚到版本 N 会撤销第 N 次及之后的所有变更。\n- 回滚会替换该应用的整个规则集合：目标版本中没有的规则会被移除，而不是合并保留。\n- 恢复的规则保留原来的 `rule_id`、名称、描述、过滤条件和状态，`created_at` 与 `updated_at` 重置为回滚时间。\n- 回滚前会先把当前状态保存为一个新的历史版本，因此回滚操作本身也可以通过再次回滚来撤销。\n- 若 `version` 在该应用下不存在，返回的是 `InvalidParameter` 而不是 `ResourceNotFound`。\n- 采集端按应用缓存已启用的规则，缓存有效期 5 秒，因此变更最多约 5 秒后对新上报的错误生效。\n- 需要对该应用有编辑权限（账户所有者或管理员、应用创建者、应用所属团队的成员），否则返回 `AccessDenied`；`application_id` 不存在时返回 `ResourceNotFound`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/rum/error-ingestion-rules/rum-error-ingestion-rules-history-revert",
           "metadata": {
             "sidebarTitle": "回滚错误采集规则到历史版本"
@@ -5940,37 +6179,30 @@
                     "items": [
                       {
                         "created_at": 1786000000000,
-                        "description": "Only ingest TypeError/ReferenceError from production, excluding Safari.",
+                        "description": "Known browser noise and errors from internal debug pages.",
                         "filters": [
                           [
                             {
-                              "key": "error.env",
-                              "oper": "IN",
-                              "vals": [
-                                "production"
-                              ]
-                            },
-                            {
-                              "key": "error.error_type",
+                              "key": "error.error_message",
                               "oper": "IN",
                               "vals": [
-                                "TypeError",
-                                "ReferenceError"
+                                "Script error.",
+                                "ResizeObserver loop*"
                               ]
                             }
                           ],
                           [
                             {
-                              "key": "error.browser_name",
-                              "oper": "NOTIN",
+                              "key": "error.view_url",
+                              "oper": "IN",
                               "vals": [
-                                "Safari"
+                                "https://example.com/debug/*"
                               ]
                             }
                           ]
                         ],
                         "rule_id": "9spXEVoMeZWujjz25yrgTe",
-                        "rule_name": "Production console errors",
+                        "rule_name": "Ignore browser noise",
                         "status": "enabled",
                         "updated_at": 1786003600000
                       }
@@ -6003,6 +6235,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -6015,7 +6250,7 @@
           "RUM/错误采集规则"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 已删除的规则不会出现在结果中，仅返回状态为 `enabled` 或 `disabled` 的规则。\n- 结果按创建时间倒序排列。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 已删除的规则不会出现在结果中，仅返回状态为 `enabled` 或 `disabled` 的规则。\n- 结果按创建时间倒序排列，不分页。\n- 公开应用任何成员都可读取；私有应用需要编辑权限（账户所有者或管理员、应用创建者、应用所属团队的成员），否则返回 `AccessDenied`；`application_id` 不存在时返回 `ResourceNotFound`。",
           "href": "/zh/api-reference/rum/error-ingestion-rules/rum-error-ingestion-rules-list",
           "metadata": {
             "sidebarTitle": "查询错误采集规则列表"
@@ -6032,7 +6267,7 @@
             "application/json": {
               "example": {
                 "application_id": "WoyQQ3BohkdtPivubEvE8o",
-                "description": "Now also excludes staging traffic.",
+                "description": "Known browser noise and errors from internal debug pages.",
                 "rule_id": "9spXEVoMeZWujjz25yrgTe"
               },
               "schema": {
@@ -6075,6 +6310,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -6087,7 +6325,7 @@
           "RUM/错误采集规则"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 仅更新请求中出现的字段，未传入的字段保持原值不变。\n- 不传任何可更新字段时视为空操作，仍会返回成功。\n- 若 `rule_id` 在该 `application_id` 下不存在，返回 `ResourceNotFound`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 仅更新请求中出现的字段，未传入或传 `null` 的字段保持原值不变。\n- 不传任何可更新字段时不做任何修改、也不生成历史版本，但仍返回成功。\n- 新的 `filters` 与 `create` 采用同样的校验规则，无效时返回 `InvalidParameter`。\n- 若 `rule_id` 在该 `application_id` 下不存在（或已删除），返回 `ResourceNotFound`。\n- 每次写操作都会先把应用变更前的完整规则集合保存为一个新的历史版本。\n- 采集端按应用缓存已启用的规则，缓存有效期 5 秒，因此变更最多约 5 秒后对新上报的错误生效。\n- 需要对该应用有编辑权限（账户所有者或管理员、应用创建者、应用所属团队的成员），否则返回 `AccessDenied`；`application_id` 不存在时返回 `ResourceNotFound`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/rum/error-ingestion-rules/rum-error-ingestion-rules-update",
           "metadata": {
             "sidebarTitle": "更新错误采集规则"
@@ -6104,7 +6342,7 @@
             "application/json": {
               "example": {
                 "end_time": 1712707200000,
-                "facet_key": "error.type",
+                "facet_key": "error_type",
                 "limit": 10,
                 "scope": "error",
                 "start_time": 1712620800000
@@ -6164,6 +6402,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -6176,7 +6417,7 @@
           "RUM/RUM 自定义字段"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**100 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 使用 `POST /rum/field/list`（传 `is_facet: true`）发现每个 scope 下可用的 `facet_key` 值。\n- `scope` 必须是以下之一：`session`、`view`、`action`、`error`、`resource`、`long_task`、`vital`、`issue`、`sourcemap`。\n- 传入 `dql` 可在统计前进一步过滤事件，DQL 语法遵循 RUM 查询语言。\n- 传入 `sql` 可使用仅含 WHERE 子句（无 SELECT）的 SQL 风格过滤。\n- 默认 limit 为 100，最大 100。\n- 时间范围必填（`start_time` / `end_time` 为 Unix 毫秒时间戳），最大跨度 31 天。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**100 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 使用 `POST /rum/field/list`（传 `is_facet: true`）发现每个 scope 下可用的 `facet_key`。\n- `facet_key` 必须是所请求 `scope` 下的分面字段（`is_facet: true`），且 `show_type` 为 `list`、`value_type` 不是数组类型，否则返回 `InvalidParameter`。\n- `facet_key` 为 `null` 的事件不参与统计。传入 `facet_value` 时只统计取值等于它的事件，其 JSON 类型须与字段的 `value_type` 一致。\n- 传入 `dql` 可在统计前过滤事件。`sql` 只填 `WHERE` 条件本身；其中任意位置出现 `SELECT`（不区分大小写）都会被拒绝。\n- `limit` 默认 100，最大 100。\n- `start_time` / `end_time` 必填，为 Unix **毫秒**时间戳，跨度不超过 31 天。\n- `scope` 为 `sourcemap` 时，用 `type` 和 `kind` 选择统计哪个符号文件库。",
           "href": "/zh/api-reference/rum/facets/rum-read-facet-count",
           "metadata": {
             "sidebarTitle": "查询分值分布"
@@ -6213,19 +6454,20 @@
                     "items": [
                       {
                         "account_id": 0,
-                        "description": "The type of the error.",
+                        "description": "Error type or class depending on the language. Examples: `TypeError`, `NotFoundError`.",
                         "edit_able": false,
                         "enum_values": [],
-                        "field_key": "error.type",
-                        "field_name": "Error type",
-                        "group": "Error",
+                        "field_key": "error_type",
+                        "field_name": "Error Type",
+                        "group": "error",
                         "is_facet": true,
                         "queryable": true,
                         "scopes": [
-                          "error"
+                          "error",
+                          "issue"
                         ],
                         "show_type": "list",
-                        "status": "active",
+                        "status": "enabled",
                         "unit_family": "",
                         "unit_name": "",
                         "value_type": "string"
@@ -6259,6 +6501,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -6281,7 +6526,7 @@
     },
     "/rum/issue/export": {
       "post": {
-        "description": "将符合过滤条件的 RUM 异常追踪 Issue 导出为 CSV 文件。响应为 `text/csv` 流，通过 `Content-Disposition: attachment` 交付——不是 JSON 信封；非控制台调用方可通过 `X-Export-Total` 与 `X-Export-Truncated` 响应头获知匹配总数与截断情况。",
+        "description": "按 `POST /rum/issue/list` 的过滤条件导出 Issue，生成最多 100 行的 CSV 文件。",
         "operationId": "rum-issue-read-export",
         "requestBody": {
           "content": {
@@ -6349,6 +6594,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -6361,7 +6609,7 @@
           "RUM/RUM 问题跟踪"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **200 次/天**；**100 次/分钟**；**10 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 响应为 `text/csv` 流，通过 `Content-Disposition: attachment` 交付——不使用标准信封。文件名为 `rum-issues-<时间戳>.csv`，按请求的 `time_zone` 打时间戳。请通过 `X-Export-Total` 与 `X-Export-Truncated` 响应头获取总数与截断情况。\n- 导出读取前 100 条匹配记录（`ExportMaxRows`）；匹配数超过上限时 `X-Export-Truncated` 为 `true`。`p` 和 `limit` 被忽略。\n- 请求过滤条件与 `POST /rum/issue/list` 完全一致——导出就是“我正在看的列表，输出成文件”。\n- `export_fields` 按顺序指定 CSV 列；未知键会被拒绝；空数组使用默认列集。\n- `time_zone` 必须是合法的 IANA 时区名（如 `Asia/Shanghai`、`UTC`）；时间戳按该时区渲染，时间列表头携带时区。非法时区名会被拒绝。\n- `console_origin` 用于拼接 `issue_url` 列；服务无法自行推断（SaaS、私有化与 dev 环境地址不同）。\n- 每次调用都会记录到账户审计日志，包含调用者成员 ID、请求负载与最终错误（如有）。请勿在请求字段中放置敏感信息。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **200 次/天**；**100 次/分钟**；**10 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 成功时响应体是 `text/csv` 附件，文件名为 `rum-issues-<yyyyMMdd-HHmmss>.csv`（按 `time_zone` 取时间），不使用 JSON 信封；参数校验失败等错误仍返回 JSON 错误信封。\n- `X-Export-Total` 为匹配的 Issue 总数；匹配数超过 100 时 `X-Export-Truncated` 为 `true`，文件只包含按 `orderby` 排序后的前 100 条。`p` 和 `limit` 会被忽略。\n- 过滤条件与 `POST /rum/issue/list` 完全一致，同样会排除调用方无权访问的私有应用。\n- `export_fields` 按输出顺序列出列；未知键会被拒绝，重复键会被去掉，传空数组或不传时导出除 `sample_first_*` 外的全部列。\n- `sample_*` 列取该 Issue 在 `[start_time, end_time]` 内最近的一条错误事件，`sample_first_*` 列取最早的一条；时间窗内没有事件时这些列为空。\n- 表头默认英文，请求语言为中文时（`Accept-Language` 请求头，或 `locale` / `lang` 查询参数）输出中文表头。时间列按 `time_zone` 渲染为 `yyyy-MM-dd HH:mm:ss`，表头附带时区，时间未设置时为空。\n- 以 `=`、`+`、`-`、`@`、制表符或回车开头的单元格会加上前缀 `'`，防止表格软件把它当作公式执行。\n- 每次调用都会记录到账户审计日志，包含调用者成员 ID、请求负载与最终错误（如有）。请勿在请求字段中放置敏感信息。",
           "href": "/zh/api-reference/rum/issues/rum-issue-read-export",
           "metadata": {
             "sidebarTitle": "导出 Issue 列表"
@@ -6413,6 +6661,7 @@
                     },
                     "resolved_at": 0,
                     "resolved_by": 0,
+                    "resolve_mode": "version",
                     "service": "fd-console",
                     "session_count": 381,
                     "severity": "Info",
@@ -6456,6 +6705,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -6468,7 +6720,7 @@
           "RUM/RUM 问题跟踪"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- `team_id` 为所属应用**当前**的团队；`POST /rum/issue/list` 与 `POST /rum/issue/export` 返回 Issue 首次出现时记录的团队，应用转移到其他团队后两者不同。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- `team_id` 为所属应用**当前**的团队；`POST /rum/issue/list` 与 `POST /rum/issue/export` 返回 Issue 首次出现时记录的团队，应用转移到其他团队后两者不同。\n- `issue_id` 不存在或已删除时返回 `InvalidParameter`（\"The specified issue does not exist\"），而不是 `ResourceNotFound`。",
           "href": "/zh/api-reference/rum/issues/rum-issue-read-info",
           "metadata": {
             "sidebarTitle": "查看 Issue 详情"
@@ -6533,6 +6785,7 @@
                         },
                         "resolved_at": 0,
                         "resolved_by": 0,
+                        "resolve_mode": "version",
                         "service": "fd-console",
                         "session_count": 381,
                         "severity": "Info",
@@ -6571,6 +6824,7 @@
                         },
                         "resolved_at": 0,
                         "resolved_by": 0,
+                        "resolve_mode": "version",
                         "service": "fd-console",
                         "session_count": 1,
                         "severity": "Info",
@@ -6617,6 +6871,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -6629,7 +6886,7 @@
           "RUM/RUM 问题跟踪"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- `start_time` 和 `end_time` 为毫秒时间戳，最大范围 183 天。\n- `statuses` 按状态过滤，可选值：`for_review`、`reviewed`、`ignored`、`resolved`。\n- `orderby` 支持：`created_at`、`updated_at`、`session_count`、`error_count`。\n- 使用 `dql` 或 `sql` 进行高级过滤，两者不可同时使用。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- `start_time` 和 `end_time` 为毫秒时间戳，最大范围 183 天。\n- 默认只匹配在时间窗内创建的 Issue；`by_intersection=true` 时，只要 Issue 在 `end_time` 之前创建且最近出现时间不早于 `start_time` 即匹配。\n- 私有应用的 Issue 会被排除，除非调用方是账户所有者或管理员、应用创建者，或应用所属团队的成员。\n- `statuses` 按状态过滤，可选值：`for_review`、`reviewed`、`ignored`、`resolved`。\n- `orderby` 支持：`created_at`、`updated_at`（默认）、`session_count`、`error_count`、`severity`。按 `severity` 排序时，没有严重性的 Issue 总是排在最后。\n- 使用 `dql` 或 `sql` 进行高级过滤，两者不可同时使用。",
           "href": "/zh/api-reference/rum/issues/rum-issue-read-list",
           "metadata": {
             "sidebarTitle": "查询 Issue 列表"
@@ -6712,6 +6969,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -6724,7 +6984,7 @@
           "RUM/Issue 预设严重性规则"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- `filters.*.key` 仅支持固定的一组 Error 级别属性，传入其他键将返回 `InvalidParameter`。\n- 请至少传入一组条件：`filters` 传空数组虽然会被接受，但该规则永远不会命中。\n- 新规则创建后默认启用，并以最低优先级追加到末尾（`priority` = 当前最大值 + 1）；如需提前评估顺序，请调用 `reorder`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- `filters.*.key` 仅支持固定的一组 Error 级别属性，传入其他键将返回 `InvalidParameter`。\n- 请至少传入一组条件：`filters` 传空数组虽然会被接受，但该规则永远不会命中。\n- 新规则创建后默认启用，并以最低优先级追加到末尾（`priority` = 当前最大值 + 1）；如需提前评估顺序，请调用 `reorder`。\n- 需要对该应用有编辑权限（账户所有者或管理员、应用创建者，或应用所属团队的成员），否则返回 `AccessDenied`；`application_id` 不存在时返回 `ResourceNotFound`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/rum/issue-preset-severity-rules/rum-issue-preset-severity-rules-create",
           "metadata": {
             "sidebarTitle": "创建预设严重性规则"
@@ -6755,7 +7015,6 @@
             "content": {
               "application/json": {
                 "example": {
-                  "data": {},
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 },
                 "schema": {
@@ -6783,6 +7042,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -6795,7 +7057,7 @@
           "RUM/Issue 预设严重性规则"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 若 `rule_id` 在该应用下不存在，返回 `ResourceNotFound`。\n- 删除为软删除：规则会立即从列表中消失，但启用规则集有最多 5 秒缓存，因此删除后数秒内上报的错误仍可能被其评估。删除前的状态仍可通过历史接口查看。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 若 `rule_id` 在该应用下不存在，返回 `ResourceNotFound`。\n- 删除为软删除：规则会立即从列表中消失，但启用规则集有最多 5 秒缓存，因此删除后数秒内上报的错误仍可能被其评估。删除前的状态仍可通过历史接口查看。\n- 需要对该应用有编辑权限（账户所有者或管理员、应用创建者，或应用所属团队的成员），否则返回 `AccessDenied`；`application_id` 不存在时返回 `ResourceNotFound`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/rum/issue-preset-severity-rules/rum-issue-preset-severity-rules-delete",
           "metadata": {
             "sidebarTitle": "删除预设严重性规则"
@@ -6826,7 +7088,6 @@
             "content": {
               "application/json": {
                 "example": {
-                  "data": {},
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 },
                 "schema": {
@@ -6854,6 +7115,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -6866,7 +7130,7 @@
           "RUM/Issue 预设严重性规则"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 若 `rule_id` 在该应用下不存在，返回 `ResourceNotFound`。\n- 禁用的规则在评估时会被跳过，但仍保留其 `priority` 位置；缓存生效最多有 5 秒延迟。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 若 `rule_id` 在该应用下不存在，返回 `ResourceNotFound`。\n- 禁用的规则在评估时会被跳过，但仍保留其 `priority` 位置；缓存生效最多有 5 秒延迟。\n- 需要对该应用有编辑权限（账户所有者或管理员、应用创建者，或应用所属团队的成员），否则返回 `AccessDenied`；`application_id` 不存在时返回 `ResourceNotFound`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/rum/issue-preset-severity-rules/rum-issue-preset-severity-rules-disable",
           "metadata": {
             "sidebarTitle": "禁用预设严重性规则"
@@ -6897,7 +7161,6 @@
             "content": {
               "application/json": {
                 "example": {
-                  "data": {},
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 },
                 "schema": {
@@ -6925,6 +7188,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -6937,7 +7203,7 @@
           "RUM/Issue 预设严重性规则"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 若 `rule_id` 在该应用下不存在，返回 `ResourceNotFound`。\n- 已启用规则会被缓存最多 5 秒，因此对新采集错误生效可能有数秒延迟。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 若 `rule_id` 在该应用下不存在，返回 `ResourceNotFound`。\n- 已启用规则会被缓存最多 5 秒，因此对新采集错误生效可能有数秒延迟。\n- 需要对该应用有编辑权限（账户所有者或管理员、应用创建者，或应用所属团队的成员），否则返回 `AccessDenied`；`application_id` 不存在时返回 `ResourceNotFound`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/rum/issue-preset-severity-rules/rum-issue-preset-severity-rules-enable",
           "metadata": {
             "sidebarTitle": "启用预设严重性规则"
@@ -7113,6 +7379,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -7125,7 +7394,7 @@
           "RUM/Issue 预设严重性规则"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 每条记录是该应用下所有规则在触发本次变更**之前**那一刻的整体快照，而非增量差异。每次真正产生变更的 create/update/enable/disable/delete/reorder/revert 调用前都会写入一条新快照（若 `update` 请求未携带任何可改字段，会直接返回成功且不写快照），因此 `version=1` 通常是首次创建规则之前捕获到的空规则集。\n- `rules` 中的每一项都是完整的内部行结构（包含 `account_id`、`created_by`、`id`、`deleted_at`），比 `rules/list` 返回的结构更宽。\n- `limit` 默认 20，超过 100 会被静默截断为 100，而不会报错。\n- `orderby` 仅支持 `updated_at` 或 `version`，传入其他值（含缺省）会回退为 `updated_at`，不会报错。\n- 结果默认按降序排列，传入 `asc=true` 可改为升序。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 每条记录是该应用下所有规则在触发本次变更**之前**那一刻的整体快照，而非增量差异。每次成功的 create/update/enable/disable/delete/reorder/revert 调用前都会写入一条快照，即使规则实际没有变化（例如启用一条已启用的规则）；只有未携带任何可改字段的 `update` 请求不写快照。因此 `version=1` 通常是首次创建规则之前捕获到的空规则集。\n- `rules` 中的每一项都是完整的内部行结构（包含 `account_id`、`created_by`、`id`、`deleted_at`），比 `rules/list` 返回的结构更宽。\n- `limit` 默认 20，超过 100 会被静默截断为 100，而不会报错。\n- `orderby` 仅支持 `updated_at` 或 `version`，传入其他值（含缺省）会回退为 `updated_at`，不会报错。\n- 结果默认按降序排列，传入 `asc=true` 可改为升序。\n- 私有应用的规则仅对有编辑权限的调用方可见（账户所有者或管理员、应用创建者，或应用所属团队的成员），其他调用方返回 `AccessDenied`；`application_id` 不存在时返回 `ResourceNotFound`。",
           "href": "/zh/api-reference/rum/issue-preset-severity-rules/rum-issue-preset-severity-rules-history-list",
           "metadata": {
             "sidebarTitle": "查询预设严重性规则历史列表"
@@ -7156,7 +7425,6 @@
             "content": {
               "application/json": {
                 "example": {
-                  "data": {},
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 },
                 "schema": {
@@ -7184,6 +7452,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -7196,7 +7467,7 @@
           "RUM/Issue 预设严重性规则"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 会用该快照的行整体替换当前规则集：`rule_id`、`priority`、`filters`、`severity`、`status`、`created_by` 沿用快照中的值，但 `created_at`/`updated_at` 会重置为回滚发生的时间，`updated_by` 会设为执行回滚的用户。\n- 当 `version` 在该应用下不存在对应历史快照时，返回 `InvalidParameter`（而非 `ResourceNotFound`）。\n- 回滚操作本身也会先生成一条新的历史快照再执行，因此回滚也可以被再次回滚。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 会用该快照的行整体替换当前规则集：`rule_id`、`priority`、`filters`、`severity`、`status`、`created_by` 沿用快照中的值，但 `created_at`/`updated_at` 会重置为回滚发生的时间，`updated_by` 会设为执行回滚的用户。\n- 当 `version` 在该应用下不存在对应历史快照时，返回 `InvalidParameter`（而非 `ResourceNotFound`）。\n- 回滚操作本身也会先生成一条新的历史快照再执行，因此回滚也可以被再次回滚。\n- 需要对该应用有编辑权限（账户所有者或管理员、应用创建者，或应用所属团队的成员），否则返回 `AccessDenied`；`application_id` 不存在时返回 `ResourceNotFound`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/rum/issue-preset-severity-rules/rum-issue-preset-severity-rules-history-revert",
           "metadata": {
             "sidebarTitle": "回滚预设严重性规则到历史版本"
@@ -7306,6 +7577,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -7318,7 +7592,7 @@
           "RUM/Issue 预设严重性规则"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 返回结果按 `priority` 升序、`created_at` 升序排列，与实际评估顺序一致。\n- 仅已启用的规则参与对新错误的评估；按优先级顺序第一条过滤条件匹配的已启用规则生效并赋予其 `severity`。未命中任何已启用规则的错误保持默认严重级别。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 返回结果按 `priority` 升序、`created_at` 升序排列，与实际评估顺序一致。\n- 仅已启用的规则参与对新错误的评估；按优先级顺序第一条过滤条件匹配的已启用规则生效并赋予其 `severity`。未命中任何已启用规则的错误使用内置严重性：崩溃为 `Critical`，其他错误按环境与错误信息关键词打分。\n- 严重性只在错误创建新 Issue 时确定一次；规则变更只影响之后接收的错误（已启用规则最多缓存 5 秒），不会重新评定已有 Issue。\n- 私有应用的规则仅对有编辑权限的调用方可见（账户所有者或管理员、应用创建者，或应用所属团队的成员），其他调用方返回 `AccessDenied`；`application_id` 不存在时返回 `ResourceNotFound`。",
           "href": "/zh/api-reference/rum/issue-preset-severity-rules/rum-issue-preset-severity-rules-list",
           "metadata": {
             "sidebarTitle": "查询预设严重性规则列表"
@@ -7350,7 +7624,6 @@
             "content": {
               "application/json": {
                 "example": {
-                  "data": {},
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 },
                 "schema": {
@@ -7378,6 +7651,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -7390,7 +7666,7 @@
           "RUM/Issue 预设严重性规则"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 本接口每次只移动一条规则，而非整体重排：`drag_rule_id` 的 `priority` 被设为 `target_rule_id` 当前的 `priority`，两者原位置之间的规则（含 `target_rule_id` 自身）整体平移一位以填补空缺。\n- `priority` 数值越小越先评估；拖动到编号更小的目标会使该规则评估顺序提前，拖动到编号更大的目标则顺延。\n- 若 `drag_rule_id` 或 `target_rule_id` 任一在该应用下不存在，返回 `ResourceNotFound`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 本接口每次只移动一条规则，而非整体重排：`drag_rule_id` 的 `priority` 被设为 `target_rule_id` 当前的 `priority`，两者原位置之间的规则（含 `target_rule_id` 自身）整体平移一位以填补空缺。\n- `priority` 数值越小越先评估；拖动到编号更小的目标会使该规则评估顺序提前，拖动到编号更大的目标则顺延。\n- 若 `drag_rule_id` 或 `target_rule_id` 任一在该应用下不存在，返回 `ResourceNotFound`。\n- 需要对该应用有编辑权限（账户所有者或管理员、应用创建者，或应用所属团队的成员），否则返回 `AccessDenied`；`application_id` 不存在时返回 `ResourceNotFound`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/rum/issue-preset-severity-rules/rum-issue-preset-severity-rules-reorder",
           "metadata": {
             "sidebarTitle": "调整预设严重性规则顺序"
@@ -7423,7 +7699,6 @@
             "content": {
               "application/json": {
                 "example": {
-                  "data": {},
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 },
                 "schema": {
@@ -7451,6 +7726,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -7463,7 +7741,7 @@
           "RUM/Issue 预设严重性规则"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 仅更新请求中出现的字段，未传字段保持原值不变。\n- 若 `rule_id` 在该应用下不存在，返回 `ResourceNotFound`。\n- 若传入 `filters`，将整体替换原有过滤结构，并按与 `create` 相同的允许键集合重新校验。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 仅更新请求中出现的字段，未传字段保持原值不变。\n- 若 `rule_id` 在该应用下不存在，返回 `ResourceNotFound`。\n- 若传入 `filters`，将整体替换原有过滤结构，并按与 `create` 相同的允许键集合重新校验。\n- 需要对该应用有编辑权限（账户所有者或管理员、应用创建者，或应用所属团队的成员），否则返回 `AccessDenied`；`application_id` 不存在时返回 `ResourceNotFound`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/rum/issue-preset-severity-rules/rum-issue-preset-severity-rules-update",
           "metadata": {
             "sidebarTitle": "更新预设严重性规则"
@@ -7522,6 +7800,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -7534,7 +7815,7 @@
           "RUM/RUM 问题跟踪"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- `status` 可选值：`for_review`、`reviewed`、`ignored`、`resolved`。\n- `suspected_cause` 可选值：`api.failed_request`、`network.error`、`code.exception`、`code.invalid_object_access`、`code.invalid_argument`、`unknown`。\n- 将 `status` 设为 `resolved` 会同时记录 `resolved_at` 和 `resolved_by`；从 resolved 切回其他状态则会清空这两个字段。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 只应用请求中携带的字段；`status` 与当前状态相同时不会产生任何变化。\n- 将未解决的 Issue 的 `status` 设为 `resolved` 会记录 `resolved_at` 和 `resolved_by` 并清除 `regression`；把已解决的 Issue 改为其他状态会清空 `resolved_at` 和 `resolved_by`。\n- `resolve_mode` 只在同时传 `status: resolved` 时生效，此时不传默认为 `any`；对已解决的 Issue 传 `status: resolved` 加新的 `resolve_mode` 可以只修改解决方式。\n- 应用开启告警时，将 Issue 设为已解决会立即发送其恢复告警。\n- 设置 `suspected_cause` 会把根因标记为用户指定（`suspected_cause.source` 为 `user`，`person_id` 为调用者），之后自动分析不会再覆盖它。\n- `issue_id` 不存在时返回 `InvalidParameter`（\"The specified issue does not exist\"）。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
           "href": "/zh/api-reference/rum/issues/rum-issue-write-update",
           "metadata": {
             "sidebarTitle": "更新 Issue"
@@ -7618,6 +7899,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -7630,7 +7914,7 @@
           "RUM/资源"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 账户尚未开通 RUM 资源，或资源状态为 `deleted`/`destroyed` 时，返回 `ResourceNotFound`。\n- `no_cache=true` 跳过的是资源记录本身（套餐版本、配额、状态）的短时缓存；`used_cnt` 系列用量来自另一份小时级缓存，不受该参数影响，无论是否传该参数都可能有延迟。\n- 已用量字段反映当前 30 天计费窗口（`window_start_time` 至 `window_end_time`）内的用量，而非历史累计总量。\n- `expired_at` 仅私有化部署会返回，取自 License 到期时间；SaaS 账户该字段不会出现在响应中。\n- 对于 `version=free` 的账户，用量超过所有应用的免费额度合计（单应用免费额度 × 应用数）时 `session_limit_reached` 为 `true`；账户尚无任何应用时始终为 `false`。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 账户尚未开通 RUM 资源，或资源状态为 `deleted`/`destroyed` 时，返回 `ResourceNotFound`。\n- `no_cache=true` 跳过的是资源记录本身（套餐版本、配额、状态）的短时缓存；`used_cnt` 系列用量来自另一份小时级缓存，不受该参数影响，无论是否传该参数都可能有延迟。\n- 已用量字段反映当前 30 天计费窗口（`window_start_time` 至 `window_end_time`）内的用量，而非历史累计总量。\n- `free_cnt` 为负数表示该额度不限量。\n- `expired_at` 仅私有化部署会返回，取自 License 到期时间；SaaS 账户该字段不会出现在响应中。\n- 对于 `version=free` 的账户，investigate 或 replay 会话用量达到「单应用免费额度 × 应用数」时 `session_limit_reached` 为 `true`（measure 会话不计入）；账户尚无任何应用时始终为 `false`。",
           "href": "/zh/api-reference/rum/resources/rum-resource-read-info",
           "metadata": {
             "sidebarTitle": "查看 RUM 资源信息"
@@ -7677,8 +7961,6 @@
                     },
                     "views": [
                       {
-                        "container_source": "",
-                        "container_view_id": "",
                         "end": 1752480600000,
                         "is_active": false,
                         "loading_type": "initial_load",
@@ -7718,6 +8000,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -7730,7 +8015,7 @@
           "RUM/RUM 会话回放"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 若会话不存在，或该会话没有录制回放数据（`session_has_replay` 为 false），返回 `InvalidParameter`。\n- 若该会话时间窗口内未查询到任何视图，返回 `InvalidParameter`。\n- 当 `session_id` 在不同时间窗口内被复用时，可传入 `ts` 加以区分。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 若会话不存在，或该会话没有录制回放数据（`session_has_replay` 为 false），返回 `InvalidParameter`。\n- 若在会话开始至其记录结束时间后 4 小时内找不到带回放数据的视图，返回 `InvalidParameter`。\n- `ts` 必须与会话开始时间（Unix 毫秒）完全相等；其他取值会导致查不到会话并返回 `InvalidParameter`。\n- 所有时间戳均为客户端时间，不做时钟偏差校正（`server_time_delta` 恒为 `0`）。",
           "href": "/zh/api-reference/rum/session-replay/rum-session-replay-read-metadata",
           "metadata": {
             "sidebarTitle": "查看会话回放元数据"
@@ -7746,7 +8031,7 @@
           "content": {
             "application/json": {
               "example": {
-                "limit": 20,
+                "limit": 2,
                 "session_id": "0a4a2e64-8a4f-4b9a-9c1e-3a2f9e6d7c81",
                 "url_mode": true
               },
@@ -7764,8 +8049,8 @@
                 "example": {
                   "data": {
                     "items": [
-                      "https://rum-replay.flashcat.cloud/short-term/2451002751131/0a4a2e64-8a4f-4b9a-9c1e-3a2f9e6d7c81/segments/1752480001234?X-Amz-Signature=example",
-                      "https://rum-replay.flashcat.cloud/short-term/2451002751131/0a4a2e64-8a4f-4b9a-9c1e-3a2f9e6d7c81/segments/1752480032456?X-Amz-Signature=example"
+                      "https://replay-storage.example.com/short-term/2451002751131/0a4a2e64-8a4f-4b9a-9c1e-3a2f9e6d7c81/segments/1752480001234?X-Amz-Signature=example",
+                      "https://replay-storage.example.com/short-term/2451002751131/0a4a2e64-8a4f-4b9a-9c1e-3a2f9e6d7c81/segments/1752480032456?X-Amz-Signature=example"
                     ],
                     "search_after_ctx": "c2hvcnQtdGVybS8yNDUxMDAyNzUxMTMxLzBhNGEyZTY0LThhNGYtNGI5YS05YzFlLTNhMmY5ZTZkN2M4MS9zZWdtZW50cy8xNzUyNDgwMDMyNDU2"
                   },
@@ -7810,6 +8095,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -7822,7 +8110,7 @@
           "RUM/RUM 会话回放"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 当 `url_mode` 为 `false`（默认）时，响应以 `application/x-ndjson` 流式返回——每行是一条解压后的回放分段 JSON 记录——且**不会**包裹在标准信封中；下一页的分页游标改由响应头 `X-Search-After-Ctx` 返回，而非响应体字段。\n- 当 `url_mode` 为 `true` 时，响应为标准 JSON 信封，内含分段的预签名下载地址（1 小时内有效），而非原始字节流。\n- 传入 `ts` 可从该时间点之前最近的一个全量快照分段开始定位，而非从会话起始处分页。\n- `limit` 取值范围 1-99；传入 100 及以上将被拒绝。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 当 `url_mode` 为 `false`（默认）时，响应以 `application/x-ndjson` 流式返回——每行是一条解压后的回放分段 JSON 记录——且**不会**包裹在标准信封中；下一页的分页游标改由响应头 `X-Search-After-Ctx` 返回，而非响应体字段。读取失败的分段会被直接跳过。\n- 当 `url_mode` 为 `true` 时，响应为标准 JSON 信封，内含分段对象（zlib 压缩）的预签名下载地址，1 小时内有效。\n- 传入 `ts`（且不传 `search_after_ctx`）时，从该时间点及之前最近的全量快照分段开始，最多向前查找 4 小时；找不到时从头开始分页。\n- 只要本页取满 `limit` 个分段就会返回游标，因此最后一页可能为空。\n- `limit` 取值范围 1-99；传入 100 及以上将被拒绝。",
           "href": "/zh/api-reference/rum/session-replay/rum-session-replay-read-segments",
           "metadata": {
             "sidebarTitle": "查询会话回放分段"
@@ -7865,16 +8153,21 @@
                         "created_at": 1712700000,
                         "git_commit_sha": "abc1234def5678",
                         "git_repository_url": "https://github.com/example/my-web-app",
-                        "key": "browser/my-web-app/1.0.0/main.js.map",
-                        "metadata": {},
+                        "key": "3f9a1c2e7b8d4e6f9a0b1c2d3e4f5a6b",
+                        "metadata": {
+                          "minified_url": "https://cdn.example.com/static/js/main.js"
+                        },
+                        "minified_path": "/js_sourcemap/my-web-app/1.0.0/static/js/main.js",
+                        "minified_url": "https://cdn.example.com/static/js/main.js",
                         "service": "my-web-app",
                         "size": 204800,
+                        "sourcemap_path": "/js_sourcemap/my-web-app/1.0.0/static/js/main.js.map",
                         "type": "browser",
                         "updated_at": 1712700000,
                         "version": "1.0.0"
                       }
                     ],
-                    "total": 3
+                    "total": 1
                   },
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 },
@@ -7903,6 +8196,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -7915,7 +8211,7 @@
           "RUM/RUM Sourcemap"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- `start_time` 和 `end_time` 为必填字段，均使用 Unix 时间戳（**毫秒**），最大时间跨度 365 天。\n- `type` 字段用于选择平台：`browser`（JavaScript）、`android` 或 `ios`。省略时默认为 `browser`。\n- 默认每页 20 条，最大 100 条，默认按 `created_at` 倒序排列。\n- Android 平台可用 `build_id` 匹配 Gradle 插件的构建标识；iOS 平台可用 `uuid` 匹配 dSYM bundle UUID。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- `start_time` 和 `end_time` 为必填字段，均使用 Unix 时间戳（**毫秒**），按上传时间过滤，最大时间跨度 365 天。\n- `type` 选择平台符号文件库：`browser`、`android`、`ios`、`miniprogram`、`react-native`、`harmony`、`flutter` 或 `electron`。省略时默认为 `browser`；其他取值（包括 `web`）返回空结果。\n- `kind: native` 会把 `android` 和 `harmony` 切换到各自的 native `.so` 符号库。\n- 默认每页 20 条，最大 100 条，默认按 `created_at` 倒序排列。\n- `build_id`、`uuid`、`query` 均为子串匹配。`uuid` 以及 iOS 的 `query` 会先转为大写并去掉连字符再匹配。\n- 无匹配记录时 `items` 和 `total` 都不返回，`data` 为空对象。",
           "href": "/zh/api-reference/rum/sourcemaps/sourcemap-read-list",
           "metadata": {
             "sidebarTitle": "查询 Sourcemap 列表"
@@ -7925,7 +8221,7 @@
     },
     "/sourcemap/stack/enrich": {
       "post": {
-        "description": "对 Browser、Android、iOS、小程序或 HarmonyOS 错误栈进行符号化或反混淆。",
+        "description": "使用某服务版本已上传的 Sourcemap 或符号文件，对错误栈进行符号化或反混淆。",
         "operationId": "sourcemap-read-stack-enrich",
         "requestBody": {
           "content": {
@@ -8003,6 +8299,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -8015,7 +8314,7 @@
           "RUM/RUM Sourcemap"
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 为兼容旧调用，省略 `type` 时默认按 `browser` 处理。\n- 设置 1 到 20 之间的 `near` 可在转换后的栈帧附近返回源码片段。\n- Android NDK native 崩溃需传入 `arch` 和 `source_type: ndk`，后端会路由到 native 符号化逻辑。\n- iOS 崩溃栈需传入 `binary_images`，以便按上传的 dSYM 文件重定位地址。\n- `no_cache` 主要用于调试，会绕过已缓存的 enrich 结果。",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 省略 `type` 时默认按 `browser` 处理。\n- `service`、`version` 须与上传时一致；找不到对应符号的栈帧会以 `converted: false` 返回。\n- 设置 1 到 20 之间的 `near` 可在转换后的栈帧附近返回源码片段。\n- `source_type`（错误事件的 `error.source_type`）会改变路由：`type: android` 时，值中含 `ndk`，或值为空但传了 `arch`，按 NDK native 符号处理；`type` 为 `flutter` 或 `react-native` 时，`ios` 走 dSYM，`android`/`ndk` 走 Android 符号；`type: electron` 时，`macos`/`windows`/`linux` 按 Breakpad 符号解析 minidump 栈帧。\n- iOS 崩溃栈需传入 `binary_images`，以便按上传的 dSYM 文件重定位地址。\n- 结果按错误栈缓存；`no_cache: true` 会绕过缓存，主要用于调试。",
           "href": "/zh/api-reference/rum/sourcemaps/sourcemap-read-stack-enrich",
           "metadata": {
             "sidebarTitle": "丰富错误栈信息"
@@ -8073,4 +8372,4 @@
       "name": "RUM/资源"
     }
   ]
-}
\ No newline at end of file
+}
diff --git a/api-reference/safari.openapi.en.json b/api-reference/safari.openapi.en.json
index ad49ef08d..65024dc58 100644
--- a/api-reference/safari.openapi.en.json
+++ b/api-reference/safari.openapi.en.json
@@ -59,7 +59,7 @@
           }
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Agent Manage** (`ai-sre`) |\n\n## Usage\n\n- `instructions` is required; a deprecated `description` field is still accepted for legacy clients and, if both are sent, must exactly match `instructions`.\n- `card_url` must be an absolute `http`/`https` URL with a non-empty host (reachability is enforced by the execution environment, not here); `auth_type` accepts only `none`, `api_key`, or `bearer`.\n- `environments` restricts where the agent can run: a list of `cloud` and/or BYOC runner environment IDs; omitted or empty means all environments, and each runner must be visible to the caller.\n- Creating into a team (`team_id > 0`) requires the caller to actually belong to that team; only the account owner/admin may create at account scope (`team_id=0`).\n- Every call is recorded in the account audit log.\n",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Agent Manage** (`ai-sre`) |\n\n## Usage\n\n- `instructions` is required: a Markdown document with optional `summary` frontmatter and a non-empty body, at most 51,200 bytes. The deprecated `description` field is still accepted; if both are sent they must match exactly.\n- `agent_name` must not contain `@` or be `general` / `explore` (reserved by built-in agents), and must be unique within its scope (account-wide or one team); violations return `InvalidParameter`.\n- `card_url` must be an absolute `http`/`https` URL with a host. When an execution environment for the agent is online, the server fetches the agent card through it (a `card_url` with no path gets `/.well-known/agent-card.json` appended) and rejects a card that is not valid JSON or declares no A2A 1.x interface with protocol binding `JSONRPC` or `HTTP+JSON`; an unreachable card, a non-2xx response, or no online environment does not block the call.\n- `auth_type=bearer` sends `auth_config.token` as `Authorization: Bearer <token>`; `auth_type=api_key` sends `auth_config.api_key` in the header named by `auth_config.header`; with `none` or an empty value no shared credential header is sent.\n- Each `environments` entry must be `cloud` or the ID of a BYOC runner that is account-scoped or belongs to one of the caller's teams; duplicates are dropped and an empty string is rejected. Omitted or empty means all environments.\n- Creating into a team (`team_id > 0`) requires the caller to belong to that team; only the account owner or an admin may create at account scope (`team_id=0`).\n- A new agent starts with `status=enabled`.\n- Every call is recorded in the account audit log.\n",
           "href": "/en/api-reference/ai-sre/a2a-agents/remote-agent-write-create",
           "metadata": {
             "sidebarTitle": "Create A2A agent"
@@ -122,6 +122,9 @@
                 "instructions": "Inspect deployment pipelines and propose rollbacks when a canary fails health checks.",
                 "card_url": "https://agents.example.com/deploy-bot/card",
                 "auth_type": "bearer",
+                "auth_config": {
+                  "token": "sk-agent-token-example-9f2c"
+                },
                 "streaming": true,
                 "team_id": 0,
                 "environments": [
@@ -147,7 +150,7 @@
           }
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Agent Manage** (`ai-sre`) |\n\n## Usage\n\n- Delete is a soft delete; the agent stops appearing in list/get and can no longer be dispatched once removed.\n- Requires edit permission (`access.CanEdit`) on the agent's team.\n- Every call is recorded in the account audit log.\n",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Agent Manage** (`ai-sre`) |\n\n## Usage\n\n- Soft delete: the agent disappears from list and get immediately, can no longer be dispatched, and its name becomes free again in its scope.\n- Requires edit rights on the agent's current team: an account-scoped agent (`team_id=0`) can be changed only by the account owner or an admin, a team agent only by members of that team (owners and admins included only if they belong to it).\n- Returns `ResourceNotFound` if the agent does not exist or is already deleted.\n- Every call is recorded in the account audit log.\n",
           "href": "/en/api-reference/ai-sre/a2a-agents/remote-agent-write-delete",
           "metadata": {
             "sidebarTitle": "Delete A2A agent"
@@ -168,15 +171,14 @@
                       "properties": {
                         "data": {
                           "type": "null",
-                          "description": "Always null on success."
+                          "description": "Not returned on success; the body carries only `request_id`."
                         }
                       }
                     }
                   ]
                 },
                 "example": {
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
-                  "data": null
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
             }
@@ -226,7 +228,7 @@
           }
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Agent Manage** (`ai-sre`) |\n\n## Usage\n\n- Requires edit permission (`access.CanEdit`) on the agent's team.\n- Returns `InvalidParameter` if the agent is already disabled.\n- Every call is recorded in the account audit log.\n",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Agent Manage** (`ai-sre`) |\n\n## Usage\n\n- Requires edit rights on the agent's current team: an account-scoped agent (`team_id=0`) can be changed only by the account owner or an admin, a team agent only by members of that team (owners and admins included only if they belong to it).\n- Returns `InvalidParameter` if the agent is already disabled.\n- A disabled agent is no longer offered to AI SRE sessions; its configuration is kept.\n- Every call is recorded in the account audit log.\n",
           "href": "/en/api-reference/ai-sre/a2a-agents/remote-agent-write-disable",
           "metadata": {
             "sidebarTitle": "Disable A2A agent"
@@ -247,15 +249,14 @@
                       "properties": {
                         "data": {
                           "type": "null",
-                          "description": "Always null on success."
+                          "description": "Not returned on success; the body carries only `request_id`."
                         }
                       }
                     }
                   ]
                 },
                 "example": {
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
-                  "data": null
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
             }
@@ -305,7 +306,7 @@
           }
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Agent Manage** (`ai-sre`) |\n\n## Usage\n\n- Requires edit permission (`access.CanEdit`) on the agent's team, not just visibility into it.\n- Returns `InvalidParameter` if the agent is already enabled.\n- Every call is recorded in the account audit log.\n",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Agent Manage** (`ai-sre`) |\n\n## Usage\n\n- Requires edit rights on the agent's current team: an account-scoped agent (`team_id=0`) can be changed only by the account owner or an admin, a team agent only by members of that team (owners and admins included only if they belong to it).\n- Returns `InvalidParameter` if the agent is already enabled.\n- Once enabled, the agent is offered to AI SRE sessions again.\n- Every call is recorded in the account audit log.\n",
           "href": "/en/api-reference/ai-sre/a2a-agents/remote-agent-write-enable",
           "metadata": {
             "sidebarTitle": "Enable A2A agent"
@@ -326,15 +327,14 @@
                       "properties": {
                         "data": {
                           "type": "null",
-                          "description": "Always null on success."
+                          "description": "Not returned on success; the body carries only `request_id`."
                         }
                       }
                     }
                   ]
                 },
                 "example": {
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
-                  "data": null
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
             }
@@ -374,7 +374,7 @@
       "post": {
         "operationId": "remote-agent-read-get",
         "summary": "Get A2A agent detail",
-        "description": "Get one A2A agent by ID.",
+        "description": "Return one A2A agent's configuration by ID, with auth secrets masked.",
         "tags": [
           "AI SRE/A2A agents"
         ],
@@ -384,7 +384,7 @@
           }
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- `card_resolve_timeout` and `task_timeout` are always `0` today — the API does not yet expose a way to set them.\n",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Values of the `api_key`, `token`, and `client_secret` keys in `auth_config`, and of any other key whose value is stored encrypted, are masked: longer than 8 characters shows the first and last 4 characters around `****`, otherwise `****`.\n- `card_resolve_timeout` and `task_timeout` are always `0` today — the API does not yet expose a way to set them.\n- Returns `ResourceNotFound` if the agent does not exist or is deleted.\n",
           "href": "/en/api-reference/ai-sre/a2a-agents/remote-agent-read-get",
           "metadata": {
             "sidebarTitle": "Get A2A agent detail"
@@ -424,13 +424,11 @@
                     "instructions": "Inspect deployment pipelines and propose rollbacks when a canary fails health checks.",
                     "card_url": "https://agents.example.com/deploy-bot/card",
                     "auth_type": "bearer",
+                    "auth_config": {
+                      "token": "sk-a****9f2c"
+                    },
                     "streaming": true,
                     "status": "enabled",
-                    "agent_card_name": "Deploy Bot",
-                    "agent_card_skills": [
-                      "rollback",
-                      "diff"
-                    ],
                     "card_resolve_timeout": 0,
                     "task_timeout": 0,
                     "auth_mode": "shared",
@@ -448,6 +446,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -484,7 +485,7 @@
           }
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Pagination uses `offset`/`limit` (not `p`/`limit`).\n- `scope=account` restricts to account-scoped agents; `scope=team` restricts to the caller's visible teams; the default `all` combines both, subject to `include_account`.\n- `query` performs a case-insensitive substring search across agent name, instructions, card URL, agent ID, and the resolved card name.\n- `card_resolve_timeout` and `task_timeout` are always `0` today — the API does not yet expose a way to set them.\n",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Pagination uses `offset`/`limit` (not `p`/`limit`); `limit` of 0 or less falls back to 20. Results are ordered by creation time, newest first.\n- Visibility follows real team membership for every caller, owner and admins included: account-scoped rows plus rows of teams the caller belongs to; `team_ids` entries outside that set are ignored.\n- `scope=account` returns only account-scoped rows; `scope=team` returns only team rows; `all` (default) returns team rows plus account-scoped rows unless `include_account=false`.\n- `query` performs a case-insensitive substring search across agent name, instructions, card URL, agent ID, and card name.\n- `can_edit` on each row tells whether the caller may update, enable, disable, or delete that agent.\n",
           "href": "/en/api-reference/ai-sre/a2a-agents/remote-agent-read-list",
           "metadata": {
             "sidebarTitle": "List A2A agents"
@@ -526,13 +527,11 @@
                         "instructions": "Inspect deployment pipelines and propose rollbacks when a canary fails health checks.",
                         "card_url": "https://agents.example.com/deploy-bot/card",
                         "auth_type": "bearer",
+                        "auth_config": {
+                          "token": "sk-a****9f2c"
+                        },
                         "streaming": true,
                         "status": "enabled",
-                        "agent_card_name": "Deploy Bot",
-                        "agent_card_skills": [
-                          "rollback",
-                          "diff"
-                        ],
                         "card_resolve_timeout": 0,
                         "task_timeout": 0,
                         "auth_mode": "shared",
@@ -553,6 +552,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -591,7 +593,7 @@
           }
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Agent Manage** (`ai-sre`) |\n\n## Usage\n\n- Requires edit permission (`access.CanEdit`) on the agent's *current* team before any field may change.\n- Reassigning `team_id` requires rights on the destination team; if the team changes without also sending a new environment binding, the existing runner binding must remain selectable by the caller or the update is rejected.\n- Changing `auth_mode` always rewrites `secret_schema` together with it; omitting `oauth_metadata` alongside a new `auth_mode` clears it to empty.\n- Sending back a masked or empty value for a sensitive `auth_config` key (`api_key`, `token`, `client_secret`) keeps the stored secret instead of overwriting it.\n- Every call is recorded in the account audit log.\n",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Agent Manage** (`ai-sre`) |\n\n## Usage\n\n- Requires edit rights on the agent's current team: an account-scoped agent (`team_id=0`) can be changed only by the account owner or an admin, a team agent only by members of that team (owners and admins included only if they belong to it).\n- Moving to another team (`team_id > 0`) requires membership in the destination team; moving to account scope (`team_id=0`) requires the account owner or an admin. If `environments` is not sent with a team change, the current runner entries must still be selectable by the caller or the update is rejected.\n- `auth_config` replaces the whole map: keys left out are removed. For `api_key`, `token`, and `client_secret`, sending back the masked value from get keeps the stored secret, while an empty string clears it.\n- When `auth_mode` is sent, `secret_schema` is overwritten with the value sent alongside it (empty if omitted). `oauth_metadata` is cleared when `auth_mode` or `card_url` actually changes, unless a non-empty `oauth_metadata` is sent; an empty `oauth_metadata` alone leaves the stored value.\n- Changing `card_url` re-runs the agent card compatibility check described on create; changing `agent_name` re-applies its naming rules.\n- Every call is recorded in the account audit log.\n",
           "href": "/en/api-reference/ai-sre/a2a-agents/remote-agent-write-update",
           "metadata": {
             "sidebarTitle": "Update A2A agent"
@@ -612,15 +614,14 @@
                       "properties": {
                         "data": {
                           "type": "null",
-                          "description": "Always null on success."
+                          "description": "Not returned on success; the body carries only `request_id`."
                         }
                       }
                     }
                   ]
                 },
                 "example": {
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
-                  "data": null
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
             }
@@ -661,7 +662,7 @@
       "post": {
         "operationId": "automation-rule-write-create",
         "summary": "Create Automation rule",
-        "description": "Create an Automation rule with schedule, HTTP POST, and On-call incident triggers.",
+        "description": "Create an Automation rule with schedule, HTTP POST, On-call incident, and war room triggers.",
         "tags": [
           "AI SRE/Automations"
         ],
@@ -671,7 +672,7 @@
           }
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | Valid `app_key`; management operations require the caller to manage the target rule |\n\n## Usage\n\n- A caller may create personal rules and rules for any team in the current account; `team_id` can be reassigned later via update (converting a team rule to personal is owner-only; moving into a team requires the caller to belong to it).\n- `cron_expr` is evaluated in `timezone` if provided, else the caller's member timezone, else the account timezone, else the server default (Asia/Shanghai).\n- `http_post_trigger_enabled=true` creates and enables an HTTP POST trigger; the response's `http_post_token` is a one-time value returned only on creation — save it immediately.\n- `oncall_incident_trigger_enabled=true` requires at least one `oncall_incident_channel_ids` entry and one `oncall_incident_severities` value; matching incidents run with `trigger_kind=oncall_incident`.\n- Every call is recorded in the account audit log.\n",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Automation Manage** (`ai-sre`) |\n\n## Usage\n\n- Omit `team_id` or send `0` for a personal rule. A team rule requires the caller to be a member of that team; account owners and admins get no exemption.\n- A rule's scope is fixed at creation: Update Automation rule rejects any `team_id` that differs from the stored value. Create a new rule to run the same task under another scope.\n- `cron_expr` is required even when only other triggers are used; send a valid expression with `schedule_trigger_enabled=false`.\n- `cron_expr` is evaluated in `timezone` if provided, else the caller's member timezone, else the account timezone, else `Asia/Shanghai`.\n- `http_post_trigger_enabled=true` creates an enabled HTTP POST trigger. `http_post_token` is returned only in this response; save it. Fire the trigger with `POST` to `http_post_trigger_url` and the header `Authorization: Bearer <http_post_token>`; the optional JSON body `{\"text\": \"...\"}` is limited to 256 KB.\n- If any `oncall_incident_*` field is sent, both `oncall_incident_channel_ids` and `oncall_incident_severities` must be non-empty. Matching incidents start runs with `trigger_kind=oncall_incident`.\n- If `war_room_trigger_enabled=true` or `war_room_channel_ids` is sent, both `war_room_channel_ids` and `war_room_severities` must be non-empty. When a war room (IM group chat) is created for a matching incident, the agent runs inside that group chat and the run has `trigger_kind=war_room_created`.\n- Runs started through the API execute in the web console (`execution_place=web_console`); `run_in=current-chat` is accepted only from a live IM conversation with the AI SRE agent and is rejected here.\n- The response is the created rule; `can_edit` is always `true` for the creator.\n- Every call is recorded in the account audit log.\n",
           "href": "/en/api-reference/ai-sre/automations/automation-rule-write-create",
           "metadata": {
             "sidebarTitle": "Create Automation rule"
@@ -730,7 +731,16 @@
                     "oncall_incident_severities": [
                       "Critical",
                       "Warning"
-                    ]
+                    ],
+                    "oncall_incident_merge_similar": true,
+                    "war_room_trigger_enabled": false,
+                    "execution_place": "web_console",
+                    "execution_location": {
+                      "place": "web_console",
+                      "run_scope": "team",
+                      "team_id": 123,
+                      "description": "Web console"
+                    }
                   }
                 }
               }
@@ -786,7 +796,7 @@
       "post": {
         "operationId": "automation-rule-write-delete",
         "summary": "Delete Automation rule",
-        "description": "Delete an Automation rule.",
+        "description": "Delete an Automation rule together with all of its triggers and their subscriptions.",
         "tags": [
           "AI SRE/Automations"
         ],
@@ -796,7 +806,7 @@
           }
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | Valid `app_key`; management operations require the caller to manage the target rule |\n\n## Usage\n\n- Deleting a rule also removes its schedule, HTTP POST, and On-call incident triggers; a deleted HTTP POST trigger's token stops working immediately.\n- Every call is recorded in the account audit log.\n",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Automation Manage** (`ai-sre`) |\n\n## Usage\n\n- Deleting a rule also removes its schedule, HTTP POST, On-call incident, and war room triggers; the HTTP POST trigger token stops working.\n- Manage rights: a personal rule (`team_id=0`) can be managed only by its owner; a team rule only by members of that team. Account owners and admins get no exemption and must join the team. Others get `403`.\n- While another update, delete, or manual run of the same rule is in progress, the call fails with HTTP `423` and `code: \"RequestLocked\"`; retry later.\n- Every call is recorded in the account audit log.\n",
           "href": "/en/api-reference/ai-sre/automations/automation-rule-write-delete",
           "metadata": {
             "sidebarTitle": "Delete Automation rule"
@@ -817,15 +827,14 @@
                       "properties": {
                         "data": {
                           "type": "null",
-                          "description": "Always null on success."
+                          "description": "Not returned on success; the body carries only `request_id`."
                         }
                       }
                     }
                   ]
                 },
                 "example": {
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
-                  "data": null
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
             }
@@ -865,7 +874,7 @@
       "post": {
         "operationId": "automation-rule-read-get",
         "summary": "Get Automation rule",
-        "description": "Get one Automation rule by ID.",
+        "description": "Get one Automation rule by ID, including its trigger settings and execution destination.",
         "tags": [
           "AI SRE/Automations"
         ],
@@ -875,7 +884,7 @@
           }
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | Valid `app_key`; caller must manage the target rule |\n\n## Usage\n\n- Manage rights mean the personal rule owner; for team rules, an account admin or a member of the rule's team.\n",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Automation Read** (`ai-sre`) |\n\n## Usage\n\n- Manage rights: a personal rule (`team_id=0`) can be managed only by its owner; a team rule only by members of that team. Account owners and admins get no exemption and must join the team. Callers without manage rights get `403` even if the rule shows up in their list.\n- `last_run` is never set on this endpoint; use List Automation rules or List Automation runs for run status.\n- `http_post_token` is never returned here; it appears only when a token is issued (create, enabling a new HTTP POST trigger, or rotation).\n",
           "href": "/en/api-reference/ai-sre/automations/automation-rule-read-get",
           "metadata": {
             "sidebarTitle": "Get Automation rule"
@@ -933,7 +942,16 @@
                     "oncall_incident_severities": [
                       "Critical",
                       "Warning"
-                    ]
+                    ],
+                    "oncall_incident_merge_similar": true,
+                    "war_room_trigger_enabled": false,
+                    "execution_place": "web_console",
+                    "execution_location": {
+                      "place": "web_console",
+                      "run_scope": "team",
+                      "team_id": 123,
+                      "description": "Web console"
+                    }
                   }
                 }
               }
@@ -974,7 +992,7 @@
       "post": {
         "operationId": "automation-rule-read-list",
         "summary": "List Automation rules",
-        "description": "List Automation rules visible to the caller.",
+        "description": "List Automation rules visible to the caller, newest update first, with pagination and filters.",
         "tags": [
           "AI SRE/Automations"
         ],
@@ -984,7 +1002,7 @@
           }
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | Valid `app_key`; results are filtered to the caller's visible scope |\n\n## Usage\n\n- `all` returns your personal rules plus team rules you can access.\n- Account admins see all team rules in list results, but not other users' personal rules.\n- `team_ids` narrows the visible set and never expands access.\n",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Automation Read** (`ai-sre`) |\n\n## Usage\n\n- Visible rules: the caller's own personal rules plus rules of teams the caller belongs to. Account owners and admins see only the teams they belong to, never other people's personal rules.\n- `scope=personal` returns only the caller's personal rules; `scope=team` only rules of the caller's teams. `team_ids` narrows the result further and never expands access.\n- Results are sorted by `updated_at` descending. Each item carries `last_run` (the most recent run) when the rule has ever run.\n- `can_edit` on each item tells whether the caller can manage (get, update, delete, run) that rule.\n",
           "href": "/en/api-reference/ai-sre/automations/automation-rule-read-list",
           "metadata": {
             "sidebarTitle": "List Automation rules"
@@ -1045,7 +1063,21 @@
                         "oncall_incident_severities": [
                           "Critical",
                           "Warning"
-                        ]
+                        ],
+                        "oncall_incident_merge_similar": true,
+                        "war_room_trigger_enabled": false,
+                        "execution_place": "web_console",
+                        "execution_location": {
+                          "place": "web_console",
+                          "run_scope": "team",
+                          "team_id": 123,
+                          "description": "Web console"
+                        },
+                        "last_run": {
+                          "run_id": "trun_5oDvqiG64uur6sBNsTc4u",
+                          "status": "succeeded",
+                          "started_at": 1780630800000
+                        }
                       }
                     ]
                   }
@@ -1089,7 +1121,7 @@
       "post": {
         "operationId": "automation-rule-write-run",
         "summary": "Run Automation rule",
-        "description": "Manually run an Automation rule immediately, outside its schedule.",
+        "description": "Run an Automation rule once right now, regardless of its triggers or enabled state.",
         "tags": [
           "AI SRE/Automations"
         ],
@@ -1099,7 +1131,7 @@
           }
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **100 requests/minute**; **5 requests/second** per account |\n| Permissions | Valid `app_key`; caller must manage the target rule |\n\n## Usage\n\n- Rate-limited to at most once per minute per rule; a second call within that window returns `429` with `code: \"RequestTooFrequently\"`.\n- Only enabled rules can run manually; a disabled or misconfigured rule fails preflight with a `400` error before any run is created.\n- The call returns once the underlying agent session starts, not once the run finishes; the run continues asynchronously — use List Automation runs to check completion status.\n- `trigger_kind` is always `manual` for runs started this way, distinguishing them from `schedule`, `http_post`, and `oncall_incident` runs in run history.\n- Every call is recorded in the account audit log.\n",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **100 requests/minute**; **5 requests/second** per account |\n| Permissions | **Automation Manage** (`ai-sre`) |\n\n## Usage\n\n- A manual run does not require the rule to be enabled. It fails with `400` before any run is created if the rule's configuration is invalid (for example a BYOC runner the rule's scope may not use), or if the only enabled trigger is the war room trigger (such a rule has no web console run).\n- A personal rule whose owner has left the account is disabled automatically and the call returns `400`.\n- At most one manual run per rule per minute; a second call within that window returns `429` with `code: \"RequestTooFrequently\"`.\n- Manage rights: a personal rule (`team_id=0`) can be managed only by its owner; a team rule only by members of that team. Account owners and admins get no exemption and must join the team.\n- While another update, delete, or manual run of the same rule is in progress, the call fails with HTTP `423` and `code: \"RequestLocked\"`; retry later.\n- The call returns once the agent session has started, not when the run finishes. Track completion with List Automation runs (`trigger_kind=manual`).\n- `run.session_id` is omitted for rules that execute in an IM chat (`execution_place=im`).\n- Every call is recorded in the account audit log.\n",
           "href": "/en/api-reference/ai-sre/automations/automation-rule-write-run",
           "metadata": {
             "sidebarTitle": "Run Automation rule"
@@ -1188,7 +1220,7 @@
       "post": {
         "operationId": "automation-rule-write-update",
         "summary": "Update Automation rule",
-        "description": "Update mutable Automation rule fields, including HTTP POST and On-call incident trigger settings.",
+        "description": "Update an Automation rule's fields and trigger settings; omitted fields keep their current values.",
         "tags": [
           "AI SRE/Automations"
         ],
@@ -1198,7 +1230,7 @@
           }
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | Valid `app_key`; management operations require the caller to manage the target rule |\n\n## Usage\n\n- Omitted or `null` fields are left unchanged. `team_id` reassigns the rule's scope: `0` converts a team rule to personal (owner-only), `>0` moves it into a team the caller belongs to.\n- `cron_expr` and `timezone` can be updated independently — sending only one keeps the other at its current stored value.\n- `rotate_http_post_trigger_token=true` issues a fresh webhook token, returned only in this response.\n- To trigger from On-call incidents, send `oncall_incident_trigger_enabled`, `oncall_incident_channel_ids`, and `oncall_incident_severities`; matching events run with `trigger_kind=oncall_incident`.\n- Every call is recorded in the account audit log.\n",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Automation Manage** (`ai-sre`) |\n\n## Usage\n\n- Omitted or `null` fields are left unchanged. Empty arrays for `*_channel_ids` / `*_severities` also keep the stored lists.\n- `team_id` cannot change: sending a value different from the stored one returns `400`. Resending the current value is accepted.\n- `cron_expr` and `timezone` can be sent independently; the other keeps its stored value. Sending `timezone: \"\"` stores `UTC`.\n- Sending `environment_kind` without `environment_id` clears the stored `environment_id`.\n- `http_post_trigger_enabled=true` creates the HTTP POST trigger when the rule has none and returns its token. `rotate_http_post_trigger_token=true` issues a new token (the old one stops working) and requires the trigger to be enabled. A new token is returned only in this response.\n- Creating an On-call incident or war room trigger through update needs both its channel IDs and severities.\n- Manage rights: a personal rule (`team_id=0`) can be managed only by its owner; a team rule only by members of that team. Account owners and admins get no exemption and must join the team.\n- While another update, delete, or manual run of the same rule is in progress, the call fails with HTTP `423` and `code: \"RequestLocked\"`; retry later.\n- Every call is recorded in the account audit log.\n",
           "href": "/en/api-reference/ai-sre/automations/automation-rule-write-update",
           "metadata": {
             "sidebarTitle": "Update Automation rule"
@@ -1257,7 +1289,16 @@
                     "oncall_incident_severities": [
                       "Critical",
                       "Warning"
-                    ]
+                    ],
+                    "oncall_incident_merge_similar": true,
+                    "war_room_trigger_enabled": false,
+                    "execution_place": "web_console",
+                    "execution_location": {
+                      "place": "web_console",
+                      "run_scope": "team",
+                      "team_id": 123,
+                      "description": "Web console"
+                    }
                   }
                 }
               }
@@ -1309,7 +1350,7 @@
       "post": {
         "operationId": "automation-run-read-list",
         "summary": "List Automation runs",
-        "description": "List run history for a rule the caller can manage.",
+        "description": "List the run history of one Automation rule, newest first, with status, trigger, and time filters.",
         "tags": [
           "AI SRE/Automations"
         ],
@@ -1319,7 +1360,7 @@
           }
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | Valid `app_key`; caller must manage the target rule |\n\n## Usage\n\n- Run history is visible only when the caller can manage the rule: the personal rule owner; for team rules, an account admin or a member of the rule's team.\n",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Automation Read** (`ai-sre`) |\n\n## Usage\n\n- Manage rights: a personal rule (`team_id=0`) can be managed only by its owner; a team rule only by members of that team. Account owners and admins get no exemption and must join the team. Others get `403`.\n- Run history is kept for 180 days; earlier `started_after_ms` values are raised to that floor.\n- Results are sorted by `started_at` descending.\n- For runs that executed in an IM chat (`execution_place=im`), `session_id`, `joined_session_id`, and `result_json` are withheld.\n",
           "href": "/en/api-reference/ai-sre/automations/automation-run-read-list",
           "metadata": {
             "sidebarTitle": "List Automation runs"
@@ -1358,6 +1399,7 @@
                         "account_id": 10023,
                         "rule_id": "arule_7NnLzY2Qp8xS4kUaV3mR6b",
                         "trigger_kind": "schedule",
+                        "execution_place": "web_console",
                         "occurrence_key": "atrig_6aKp3wT9mQ2xVc8bR1nY7z:1780630800000",
                         "status": "succeeded",
                         "attempts": 1,
@@ -1416,7 +1458,7 @@
       "post": {
         "operationId": "automation-template-read-list",
         "summary": "List Automation templates",
-        "description": "List preset Automation templates for the requested locale.",
+        "description": "List built-in Automation templates that prefill the create-rule form, in Chinese or English.",
         "tags": [
           "AI SRE/Automations"
         ],
@@ -1426,7 +1468,7 @@
           }
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | Valid `app_key`; results are filtered to the caller's visible scope |\n",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Automation Read** (`ai-sre`) |\n\n## Usage\n\n- Templates are fixed by the platform and are the same for every account.\n- Language: a `locale` containing `zh` returns Chinese templates, one containing `en` returns English; any other non-empty value returns Chinese. When `locale` is omitted, the `locale`/`lang` query parameter or the `Accept-Language` header decides.\n- Each template is a partial create request: pass its fields to Create Automation rule and add what only you can supply (`cron_expr` when the template has none, `timezone`, channel IDs).\n",
           "href": "/en/api-reference/ai-sre/automations/automation-template-read-list",
           "metadata": {
             "sidebarTitle": "List Automation templates"
@@ -1460,8 +1502,14 @@
                         "name": "Weekly Insights",
                         "description": "Analyze incidents, alerts, response activity, notification load, and related changes from the past week.",
                         "icon": "chart-no-axes-combined",
+                        "category": "Insights",
                         "enabled": false,
-                        "prompt": "Generate a weekly insights report. Analyze incidents, alerts, response activity, notification load, and related changes from the past week. Focus on what happened this week, which signals deserve attention, and which improvement actions are most valuable. Do not modify any Flashduty business state.\n"
+                        "prompt": "Generate a weekly insights report. Analyze incidents, alerts, response activity, notification load, and related changes from the past week. Focus on what happened this week, which signals deserve attention, and which improvement actions are most valuable. Do not modify any Flashduty business state.\n",
+                        "schedule_trigger_enabled": true,
+                        "cron_expr": "0 9 * * 1",
+                        "http_post_trigger_enabled": false,
+                        "oncall_incident_trigger_enabled": false,
+                        "war_room_trigger_enabled": false
                       }
                     ]
                   }
@@ -1514,7 +1562,7 @@
           }
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **MCP Manage** (`ai-sre`) |\n\n## Usage\n\n- `command`/`args`/`env` apply to `stdio`; `url`/`headers` apply to `sse`/`streamable-http`.\n- Server name must start with a letter and contain only letters, digits, `-`, or `_`, and is unique within its scope (account-wide or one team), case-insensitive; violations return InvalidParameter.\n- `environments` restricts where the server can run: a list of `cloud` and/or BYOC runner environment IDs; omitted or empty means all environments.\n- `per_user_secret` auth mode requires `secret_schema` to be valid JSON with a non-empty `header_name`.\n- Every call is recorded in the account audit log.\n",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **MCP Manage** (`ai-sre`) |\n\n## Usage\n\n- `command`/`args`/`env` apply to `stdio`; `url`/`headers` apply to `sse`/`streamable-http`.\n- `server_name` must start with a letter and contain only letters, digits, `-`, or `_`, and must be unique within its scope (account-wide or one team); violations return `InvalidParameter`.\n- Without `source_template_name`, creating into a team (`team_id > 0`) requires the caller to belong to that team, and only the account owner or an admin may create at account scope (`team_id=0`).\n- Setting `source_template_name` installs a marketplace template: the template must exist (`ResourceNotFound` otherwise), `team_id` is ignored and the server is created at account scope, and the connection fields must equal the template's own except for its declared parameter values. Templates with per-user auth whose parameters let the installer choose the destination host can be installed only by the account owner or an admin.\n- Each `environments` entry must be `cloud` or the ID of a BYOC runner that is account-scoped or belongs to one of the caller's teams; duplicates are dropped and an empty string is rejected. Omitted or empty means all environments.\n- `per_user_secret` auth mode requires `secret_schema` to be valid JSON with a non-empty `header_name`.\n- `env` and `headers` values are masked when the key name contains `KEY`, `SECRET`, `TOKEN`, `PASSWORD`, `PASSWD`, `CREDENTIAL`, or `AUTHORIZATION` (case-insensitive), or has a `PWD` / `PASS` segment, or the value is encrypted at rest; such values are also encrypted at rest.\n- The response is the stored server. Its tool list is then fetched in the background through an already-online execution environment; the call does not wait for it.\n- Every call is recorded in the account audit log.\n",
           "href": "/en/api-reference/ai-sre/mcp-servers/mcp-write-server-create",
           "metadata": {
             "sidebarTitle": "Create MCP server"
@@ -1552,13 +1600,16 @@
                     "description": "Query Prometheus metrics and alerts.",
                     "transport": "streamable-http",
                     "url": "https://mcp.example.com/prometheus",
+                    "headers": {
+                      "Authorization": "Bear****f2c1"
+                    },
                     "status": "enabled",
-                    "connect_timeout": 10,
-                    "call_timeout": 60,
+                    "connect_timeout": 0,
+                    "call_timeout": 0,
                     "auth_mode": "shared",
                     "created_by": 80011,
                     "created_at": 1716960000000,
-                    "updated_at": 1717046400000
+                    "updated_at": 1716960000000
                   }
                 }
               }
@@ -1592,6 +1643,9 @@
                 "description": "Query Prometheus metrics and alerts.",
                 "transport": "streamable-http",
                 "url": "https://mcp.example.com/prometheus",
+                "headers": {
+                  "Authorization": "Bearer example-token-f2c1"
+                },
                 "status": "enabled"
               }
             }
@@ -1613,7 +1667,7 @@
           }
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **MCP Manage** (`ai-sre`) |\n\n## Usage\n\n- Every call is recorded in the account audit log.\n",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **MCP Manage** (`ai-sre`) |\n\n## Usage\n\n- Permanently removes the server and drops its cached tool list; it stops being offered to AI SRE sessions and its name can be reused.\n- Requires edit rights on the server's current team: an account-scoped server (`team_id=0`) can be changed only by the account owner or an admin, a team server only by members of that team (owners and admins included only if they belong to it).\n- Returns `ResourceNotFound` if the server does not exist.\n- Every call is recorded in the account audit log.\n",
           "href": "/en/api-reference/ai-sre/mcp-servers/mcp-write-server-delete",
           "metadata": {
             "sidebarTitle": "Delete MCP server"
@@ -1634,15 +1688,14 @@
                       "properties": {
                         "data": {
                           "type": "null",
-                          "description": "Always null on success."
+                          "description": "Not returned on success; the body carries only `request_id`."
                         }
                       }
                     }
                   ]
                 },
                 "example": {
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
-                  "data": null
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
             }
@@ -1692,7 +1745,7 @@
           }
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **MCP Manage** (`ai-sre`) |\n\n## Usage\n\n- Disabling an already-disabled server returns InvalidParameter instead of a silent no-op.\n- Requires edit permission on the server's current team: account-scope servers are owner/admin only; team-scope servers require the caller to belong to that team (or be owner/admin).\n- Every call is recorded in the account audit log.\n",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **MCP Manage** (`ai-sre`) |\n\n## Usage\n\n- Returns `InvalidParameter` if the server is already disabled.\n- Requires edit rights on the server's current team: an account-scoped server (`team_id=0`) can be changed only by the account owner or an admin, a team server only by members of that team (owners and admins included only if they belong to it).\n- A disabled server's tools are no longer offered to AI SRE sessions; its configuration is kept.\n- Every call is recorded in the account audit log.\n",
           "href": "/en/api-reference/ai-sre/mcp-servers/mcp-write-server-disable",
           "metadata": {
             "sidebarTitle": "Disable MCP server"
@@ -1713,15 +1766,14 @@
                       "properties": {
                         "data": {
                           "type": "null",
-                          "description": "Always null on success."
+                          "description": "Not returned on success; the body carries only `request_id`."
                         }
                       }
                     }
                   ]
                 },
                 "example": {
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
-                  "data": null
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
             }
@@ -1771,7 +1823,7 @@
           }
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **MCP Manage** (`ai-sre`) |\n\n## Usage\n\n- Enabling an already-enabled server returns InvalidParameter instead of a silent no-op.\n- Requires edit permission on the server's current team: account-scope servers are owner/admin only; team-scope servers require the caller to belong to that team (or be owner/admin).\n- Every call is recorded in the account audit log.\n",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **MCP Manage** (`ai-sre`) |\n\n## Usage\n\n- Returns `InvalidParameter` if the server is already enabled.\n- Requires edit rights on the server's current team: an account-scoped server (`team_id=0`) can be changed only by the account owner or an admin, a team server only by members of that team (owners and admins included only if they belong to it).\n- Once enabled, the server's tools are offered to AI SRE sessions again; the cached tool list is dropped and fetched again on next use.\n- Every call is recorded in the account audit log.\n",
           "href": "/en/api-reference/ai-sre/mcp-servers/mcp-write-server-enable",
           "metadata": {
             "sidebarTitle": "Enable MCP server"
@@ -1792,15 +1844,14 @@
                       "properties": {
                         "data": {
                           "type": "null",
-                          "description": "Always null on success."
+                          "description": "Not returned on success; the body carries only `request_id`."
                         }
                       }
                     }
                   ]
                 },
                 "example": {
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
-                  "data": null
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
             }
@@ -1850,7 +1901,7 @@
           }
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- A pure database read — it never probes the live server; the stored configuration (with secrets masked) and the cached `ai_description` are returned as-is.\n",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **60 requests/minute**; **3 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- A pure database read — it never probes the live server; the stored configuration and the cached `ai_description` are returned as-is.\n- `env` and `headers` values are masked when the key name contains `KEY`, `SECRET`, `TOKEN`, `PASSWORD`, `PASSWD`, `CREDENTIAL`, or `AUTHORIZATION` (case-insensitive), or has a `PWD` / `PASS` segment, or the value is encrypted at rest.\n- `test_error` and `tested_at` report the last connection test run from the console; they are omitted if the server has never been tested.\n- Returns `ResourceNotFound` if the server does not exist.\n",
           "href": "/en/api-reference/ai-sre/mcp-servers/mcp-read-server-get",
           "metadata": {
             "sidebarTitle": "Get MCP server detail"
@@ -1888,9 +1939,12 @@
                     "description": "Query Prometheus metrics and alerts.",
                     "transport": "streamable-http",
                     "url": "https://mcp.example.com/prometheus",
+                    "headers": {
+                      "Authorization": "Bear****f2c1"
+                    },
                     "status": "enabled",
-                    "connect_timeout": 10,
-                    "call_timeout": 60,
+                    "connect_timeout": 0,
+                    "call_timeout": 0,
                     "auth_mode": "shared",
                     "created_by": 80011,
                     "created_at": 1716960000000,
@@ -1906,6 +1960,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -1942,7 +1999,7 @@
           }
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- The response never includes a live tool list; tools are probed asynchronously on create/update and cached for runtime use.\n- `query` performs a case-insensitive substring search across name, description, AI-generated description, server ID, transport, URL, command, and source template name.\n",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Pagination uses `p`/`limit`: `p` below 1 is treated as 1 and `limit` below 1 as 20. Results are ordered by name, then server ID, ascending.\n- Visibility follows real team membership for every caller, owner and admins included: account-scoped rows plus rows of teams the caller belongs to; `team_ids` entries outside that set are ignored.\n- `scope=account` returns only account-scoped rows; `scope=team` returns only team rows; `all` (default) returns team rows plus account-scoped rows unless `include_account=false`.\n- `query` performs a case-insensitive substring search across name, description, AI-generated description, server ID, transport, URL, command, and source template name.\n- The response never includes a live tool list; `can_edit` on each row tells whether the caller may change that server.\n",
           "href": "/en/api-reference/ai-sre/mcp-servers/mcp-read-server-list",
           "metadata": {
             "sidebarTitle": "List MCP servers"
@@ -1983,9 +2040,12 @@
                         "description": "Query Prometheus metrics and alerts.",
                         "transport": "streamable-http",
                         "url": "https://mcp.example.com/prometheus",
+                        "headers": {
+                          "Authorization": "Bear****f2c1"
+                        },
                         "status": "enabled",
-                        "connect_timeout": 10,
-                        "call_timeout": 60,
+                        "connect_timeout": 0,
+                        "call_timeout": 0,
                         "auth_mode": "shared",
                         "created_by": 80011,
                         "created_at": 1716960000000,
@@ -2003,6 +2063,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -2041,7 +2104,7 @@
           }
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **MCP Manage** (`ai-sre`) |\n\n## Usage\n\n- Masked secret values in `env`/`headers` are preserved — sending the masked value back does not overwrite the stored secret.\n- `environments` is a tri-state partial-update field: omit (null) to leave it unchanged; send a list to set it — an empty list clears the restriction back to all environments.\n- Changing `team_id` requires reassignment permission on the destination team; if `environments` is left unchanged, the current environments must still be selectable by the caller under the new team or the update is rejected.\n- Every call is recorded in the account audit log.\n",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **MCP Manage** (`ai-sre`) |\n\n## Usage\n\n- Requires edit rights on the server's current team: an account-scoped server (`team_id=0`) can be changed only by the account owner or an admin, a team server only by members of that team (owners and admins included only if they belong to it).\n- `server_name`, `description`, `transport`, `command`, `url`, and `auth_mode` change only when non-empty, and `connect_timeout` / `call_timeout` only when non-zero, so these cannot be cleared through this endpoint.\n- `args`, `env`, and `headers` replace the whole value when sent: a key left out of `env`/`headers` is removed. For a protected `env`/`headers` key, sending the masked value or an empty string keeps the stored secret.\n- When `auth_mode` is sent, `secret_schema` is overwritten with the value sent alongside it (empty if omitted). `oauth_metadata` is cleared when `auth_mode` or `url` actually changes, unless a non-empty `oauth_metadata` is sent.\n- Moving to another team (`team_id > 0`) requires membership in the destination team and is refused for servers installed from the marketplace; moving to account scope (`team_id=0`) requires the account owner or an admin. If `environments` is not sent with a team change, the current runner entries must still be selectable by the caller or the update is rejected.\n- `environments`: omit (or `null`) to leave unchanged; send a list to replace it — an empty list clears the restriction back to all environments.\n- The response is the updated server. If a connection field changed, the cached tool list is dropped and fetched again in the background.\n- Every call is recorded in the account audit log.\n",
           "href": "/en/api-reference/ai-sre/mcp-servers/mcp-write-server-update",
           "metadata": {
             "sidebarTitle": "Update MCP server"
@@ -2079,9 +2142,12 @@
                     "description": "Query Prometheus metrics, alerts, and rules.",
                     "transport": "streamable-http",
                     "url": "https://mcp.example.com/prometheus",
+                    "headers": {
+                      "Authorization": "Bear****f2c1"
+                    },
                     "status": "enabled",
-                    "connect_timeout": 10,
-                    "call_timeout": 60,
+                    "connect_timeout": 0,
+                    "call_timeout": 0,
                     "auth_mode": "shared",
                     "created_by": 80011,
                     "created_at": 1716960000000,
@@ -2127,7 +2193,7 @@
       "post": {
         "operationId": "session-write-delete",
         "summary": "Delete session",
-        "description": "Delete a session by ID.",
+        "description": "Soft-delete a session together with its subagent sessions and the files it presented.",
         "tags": [
           "AI SRE/Sessions"
         ],
@@ -2137,7 +2203,7 @@
           }
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Personal sessions can be deleted only by their creator; team sessions can be deleted by the creator, an account admin, or a member of the owning team.\n- This is a soft delete: it also cascades to delete child subagent sessions and any presented files; the underlying S3/MinIO blobs are removed best-effort after the transaction commits, so an orphaned blob is possible on partial failure.\n",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Requires manage rights on the session: a personal session (`team_id` = 0) can be deleted only by its creator; a team session by its creator or a member of the owning team. Account owners and admins get no exemption; anyone else receives `AccessDenied`.\n- An unknown or already-deleted `session_id` returns `ResourceNotFound`.\n- Background processes the session still runs (background shell commands, monitors) are stopped first on a best-effort basis; a failed stop does not block the delete.\n- Child subagent sessions and the files the session presented are deleted in the same transaction; the stored file contents are removed afterwards on a best-effort basis.\n",
           "href": "/en/api-reference/ai-sre/sessions/session-write-delete",
           "metadata": {
             "sidebarTitle": "Delete session"
@@ -2158,15 +2224,14 @@
                       "properties": {
                         "data": {
                           "type": "null",
-                          "description": "Always null on success."
+                          "description": "Not returned on success; the body carries only `request_id`."
                         }
                       }
                     }
                   ]
                 },
                 "example": {
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
-                  "data": null
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
             }
@@ -2216,7 +2281,7 @@
           }
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/day**; **200 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Personal sessions are exportable only by their creator; team sessions can be exported by same-account callers with the `session_id`.\n- The response is `application/x-ndjson` — parse line-by-line and write to a file; do not buffer the whole body in memory.\n- The first line is always a `session_meta` envelope; `include_subagents=true` inlines each child session's stream after its dispatch line.\n- Requests are capped at a 60-second execution timeout; very large sessions may not finish exporting within that window.\n- If the stream fails partway through, the response ends with a JSON error line instead of a proper error envelope (headers are already sent) — check for this trailing line to detect truncation.\n",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/day**; **200 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- A personal session can be exported only by its creator; a team session by any member of the same account. Share links do not grant export. Missing or deleted sessions return `ResourceNotFound`.\n- The response is `application/x-ndjson` — parse it line by line and write it to a file instead of buffering the whole body.\n- The first line is always a `session_meta` object. Following lines carry a `type` of `user_message`, `system_reminder`, `agent_text`, `tool_call`, `subagent_dispatch`, `llm_call`, `final_answer`, or `session_fork`.\n- With `include_subagents=true`, each `subagent_dispatch` line is followed by the child session's own stream, starting with its own `session_meta`.\n- The request times out after 60 seconds; a very large session may not finish exporting within that window.\n- If export fails after streaming has started, the body ends with a `{\"type\":\"error\",\"content\":\"...\"}` line instead of an error envelope — check the last line to detect truncation.\n",
           "href": "/en/api-reference/ai-sre/sessions/session-read-export",
           "metadata": {
             "sidebarTitle": "Export session transcript"
@@ -2280,7 +2345,7 @@
           }
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Personal sessions are readable only by their creator; team sessions can be read by same-account callers with the `session_id`.\n- Page older history with `search_after_ctx` from the previous response.\n- `limit` (or legacy `num_recent_events`) caps the event page; default 100, max 1000.\n- A malformed `search_after_ctx` returns 400 immediately, before any DB work.\n- `current_turn_*` fields are populated only while the session `is_running`; `suggest_init` is the same account-wide onboarding flag as `session/list`.\n",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- A personal session is readable only by its creator, or by anyone holding a valid `share_token` (view only). A team session is readable by any member of the same account. A missing, deleted, or unreadable session returns `ResourceNotFound`.\n- `events` holds the newest page in ascending order. To read older history, pass the returned `search_after_ctx` back; a malformed cursor returns `InvalidParameter`.\n- Page size is `limit`, else `num_recent_events`, else 100 (max 1000). Internal control events are left out, so a page can hold fewer events than requested.\n- The `current_turn_*` fields are filled only while `is_running` is true. `has_unread` is always `false` and `pinned_at` always `0` here; use `POST /safari/session/list` for those.\n- `pending_messages` lists messages queued behind the running turn; it is an empty array when nothing is queued.\n",
           "href": "/en/api-reference/ai-sre/sessions/session-read-info",
           "metadata": {
             "sidebarTitle": "Get session detail"
@@ -2316,12 +2381,12 @@
                       "entry_kind": "web",
                       "person_id": "3790925372131",
                       "team_id": 0,
-                      "is_mine": false,
+                      "is_mine": true,
                       "can_view": true,
                       "can_continue": true,
                       "can_manage": true,
                       "can_fork": true,
-                      "access_source": "manager",
+                      "access_source": "owner",
                       "share_enabled": true,
                       "share_version": 3,
                       "shared_at": 1780367971000,
@@ -2337,14 +2402,15 @@
                         "reasoning_tokens": 351
                       },
                       "current_context_tokens": 14948,
-                      "context_window": 0,
+                      "context_window": 131072,
                       "archived_at": 0,
                       "pinned_at": 0,
                       "last_event_at": 1780367992649,
                       "is_running": false,
-                      "has_unread": true,
-                      "current_turn_started_at": 0,
-                      "current_turn_active_ms": 0,
+                      "standing_tasks": 0,
+                      "has_unread": false,
+                      "current_turn_started_at": 1780367971241,
+                      "current_turn_active_ms": 21408,
                       "current_turn_wait_ms": 0,
                       "current_turn_tokens": 0
                     },
@@ -2377,7 +2443,7 @@
                       }
                     ],
                     "has_more_older": false,
-                    "suggest_init": false
+                    "pending_messages": []
                   }
                 }
               }
@@ -2419,7 +2485,7 @@
       "post": {
         "operationId": "session-read-list",
         "summary": "List sessions",
-        "description": "List agent sessions visible to the caller, filtered by app, surface, archive status, and team.",
+        "description": "List agent sessions visible to the caller, filtered by app, entry surface, archive status, and team.",
         "tags": [
           "AI SRE/Sessions"
         ],
@@ -2429,7 +2495,7 @@
           }
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Pagination uses `p`/`limit` (max 100); `scope` defaults to `all`.\n- `all` returns your personal sessions plus team sessions you can access; account admins see all team sessions, but not other users' personal sessions.\n- `team_ids` narrows the visible set and never expands access.\n- `is_running` reflects the live run-set; `has_unread` is computed per calling user; the `current_turn_*` fields are always zero here — only `session/get` computes them while a session is running.\n- `suggest_init` is an account-wide onboarding flag (true only when the account has no knowledge in any scope) — it doesn't depend on the list filters.\n",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Pagination uses `p`/`limit` (default 20, max 100). The caller's pinned sessions that match the filters are prepended on page 1 in addition to `limit` rows, never appear on later pages, and are not counted in `total`.\n- `scope=all` returns sessions the caller created plus sessions bound to teams the caller belongs to. Membership is real team membership for every role; account owners and admins do not see other teams' sessions here.\n- `team_ids`, `person_ids`, and `entry_kinds` only narrow the visible set. Incognito sessions are never listed; subagent sessions appear only with `include_subagent_sessions=true`.\n- For `app_name=ai-sre` the calling member must hold an AI SRE license seat; otherwise the request fails with a no-license error.\n- `creator_name`, `has_unread`, and `pinned_at` are computed per caller. The `current_turn_*` fields and `context_window` are always `0`, and `state`, `bound_environment`, `context_resolved`, `automation`, and `has_open_tasks` are not returned; use `POST /safari/session/get` for them.\n",
           "href": "/en/api-reference/ai-sre/sessions/session-read-list",
           "metadata": {
             "sidebarTitle": "List sessions"
@@ -2466,13 +2532,14 @@
                         "app_name": "ai-sre",
                         "entry_kind": "web",
                         "person_id": "3790925372131",
+                        "creator_name": "Alice Chen",
                         "team_id": 0,
-                        "is_mine": false,
+                        "is_mine": true,
                         "can_view": true,
                         "can_continue": true,
                         "can_manage": true,
                         "can_fork": true,
-                        "access_source": "manager",
+                        "access_source": "owner",
                         "share_enabled": true,
                         "share_version": 3,
                         "shared_at": 1780367971000,
@@ -2493,14 +2560,14 @@
                         "pinned_at": 0,
                         "last_event_at": 1780367992649,
                         "is_running": false,
+                        "standing_tasks": 0,
                         "has_unread": true,
                         "current_turn_started_at": 0,
                         "current_turn_active_ms": 0,
                         "current_turn_wait_ms": 0,
                         "current_turn_tokens": 0
                       }
-                    ],
-                    "suggest_init": false
+                    ]
                   }
                 }
               }
@@ -2544,7 +2611,7 @@
       "post": {
         "operationId": "skill-write-delete",
         "summary": "Delete skill",
-        "description": "Delete a skill by ID.",
+        "description": "Soft-delete a skill so agents stop loading it and its name can be reused.",
         "tags": [
           "AI SRE/Skills"
         ],
@@ -2554,7 +2621,7 @@
           }
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Skill Manage** (`ai-sre`) |\n\n## Usage\n\n- Soft delete only: sets `status` to `deleted` and renames the row to free its name for reuse; the skill's zip archive is not removed from object storage.\n- Deleting an already-deleted or nonexistent `skill_id` returns `ResourceNotFound`, since the lookup excludes deleted rows before the delete itself runs.\n- Every call is recorded in the account audit log.\n",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Skill Manage** (`ai-sre`) |\n\n## Usage\n\n- Requires edit rights on the skill: account-scope skills (`team_id` = 0) are editable by account owners and admins; team skills only by members of that team (no owner or admin exemption). Otherwise the call returns `AccessDenied`.\n- Soft delete: the skill is renamed and hidden from every endpoint, freeing its name in its scope for reuse; the stored archive is not removed.\n- An unknown or already-deleted `skill_id` returns `ResourceNotFound`.\n- Every call is recorded in the account audit log.\n",
           "href": "/en/api-reference/ai-sre/skills/skill-write-delete",
           "metadata": {
             "sidebarTitle": "Delete skill"
@@ -2575,15 +2642,14 @@
                       "properties": {
                         "data": {
                           "type": "null",
-                          "description": "Always null on success."
+                          "description": "Not returned on success; the body carries only `request_id`."
                         }
                       }
                     }
                   ]
                 },
                 "example": {
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
-                  "data": null
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
             }
@@ -2633,7 +2699,7 @@
           }
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Skill Manage** (`ai-sre`) |\n\n## Usage\n\n- Only an `enabled` skill can be disabled; an already-disabled skill returns `InvalidParameter`.\n- Every call is recorded in the account audit log.\n",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Skill Manage** (`ai-sre`) |\n\n## Usage\n\n- Requires edit rights on the skill: account-scope skills (`team_id` = 0) are editable by account owners and admins; team skills only by members of that team (no owner or admin exemption). Otherwise the call returns `AccessDenied`.\n- Only an `enabled` skill can be disabled; disabling an already-disabled skill returns `InvalidParameter`.\n- Every call is recorded in the account audit log.\n",
           "href": "/en/api-reference/ai-sre/skills/skill-write-disable",
           "metadata": {
             "sidebarTitle": "Disable skill"
@@ -2654,15 +2720,14 @@
                       "properties": {
                         "data": {
                           "type": "null",
-                          "description": "Always null on success."
+                          "description": "Not returned on success; the body carries only `request_id`."
                         }
                       }
                     }
                   ]
                 },
                 "example": {
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
-                  "data": null
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
             }
@@ -2712,7 +2777,7 @@
           }
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Skill Manage** (`ai-sre`) |\n\n## Usage\n\n- Only a `disabled` skill can be enabled; an already-enabled skill returns `InvalidParameter`.\n- Every call is recorded in the account audit log.\n",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Skill Manage** (`ai-sre`) |\n\n## Usage\n\n- Requires edit rights on the skill: account-scope skills (`team_id` = 0) are editable by account owners and admins; team skills only by members of that team (no owner or admin exemption). Otherwise the call returns `AccessDenied`.\n- Only a `disabled` skill can be enabled; enabling an already-enabled skill returns `InvalidParameter`.\n- Every call is recorded in the account audit log.\n",
           "href": "/en/api-reference/ai-sre/skills/skill-read-enable",
           "metadata": {
             "sidebarTitle": "Enable skill"
@@ -2733,15 +2798,14 @@
                       "properties": {
                         "data": {
                           "type": "null",
-                          "description": "Always null on success."
+                          "description": "Not returned on success; the body carries only `request_id`."
                         }
                       }
                     }
                   ]
                 },
                 "example": {
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
-                  "data": null
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
             }
@@ -2791,7 +2855,7 @@
           }
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Returns `ResourceNotFound` if the skill does not exist or has already been deleted.\n- `can_edit` reflects team membership, but read access itself is open to any caller regardless of team.\n",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Any account member can read any skill in the account by ID, including skills of teams they do not belong to; `can_edit` tells whether the caller may change it.\n- An unknown or deleted `skill_id` returns `ResourceNotFound`.\n- `update_available` is not computed here and is always `false`; use `POST /safari/skill/list` to see marketplace update availability.\n",
           "href": "/en/api-reference/ai-sre/skills/skill-read-get",
           "metadata": {
             "sidebarTitle": "Get skill detail"
@@ -2855,6 +2919,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -2891,7 +2958,7 @@
           }
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- The `content` field is omitted in list rows; fetch a single skill to read its body.\n- `scope` selects `all` (default), `account`-only, or `team`-only, overriding `include_account`; non-admins requesting specific `team_ids` are silently filtered down to the teams they belong to.\n- `update_available` compares against the marketplace catalog once per call; if the catalog fails to load, the badge is simply suppressed rather than the request failing.\n",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Returns account-scope skills plus skills of teams the caller belongs to, sorted by `skill_name` ascending. Team membership is real membership for every role; `team_ids` outside the caller's teams are silently dropped.\n- `scope` overrides `include_account`: `account` returns only account-scope skills, `team` only the caller's team skills.\n- `content` is omitted in list rows; call `POST /safari/skill/get` for the body.\n- `update_available` compares each marketplace-installed skill with the current catalog; if the catalog cannot be loaded, it is `false` for every row instead of failing the request.\n",
           "href": "/en/api-reference/ai-sre/skills/skill-read-list",
           "metadata": {
             "sidebarTitle": "List skills"
@@ -2958,6 +3025,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -2996,7 +3066,7 @@
           }
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Skill Manage** (`ai-sre`) |\n\n## Usage\n\n- Only `description`, `description_en`, and `team_id` are editable; the skill body is changed by re-uploading.\n- `description` only updates when non-empty — there is no way to clear it via this field; `description_en` is nilable, so send an empty string to explicitly clear it.\n- Reassigning `team_id` to a different team runs a second authorization check beyond edit access, verifying the caller may target the destination team.\n- Every call is recorded in the account audit log.\n",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Skill Manage** (`ai-sre`) |\n\n## Usage\n\n- Requires edit rights on the skill: account-scope skills (`team_id` = 0) are editable by account owners and admins; team skills only by members of that team (no owner or admin exemption). Otherwise the call returns `AccessDenied`.\n- Only `description`, `description_en`, and `team_id` can be changed; change the skill body by uploading a new archive.\n- `description` changes only when non-empty, so it cannot be cleared. `description_en` changes whenever sent; an empty string clears it.\n- Moving to a team (`team_id` > 0) requires membership in the target team; moving to account scope (`team_id` = 0) requires an account owner or admin. Marketplace-installed skills can only move to account scope. A name clash in the target scope returns `InvalidParameter`.\n- Every call is recorded in the account audit log.\n",
           "href": "/en/api-reference/ai-sre/skills/skill-write-update",
           "metadata": {
             "sidebarTitle": "Update skill"
@@ -3098,7 +3168,7 @@
           }
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **30 requests/minute**; **3 requests/second** per account |\n| Permissions | **Skill Manage** (`ai-sre`) |\n\n## Usage\n\n- Send as `multipart/form-data` with a `file` part; accepted archive types are `.skill`, `.zip`, `.tar.gz`, `.tgz`, capped at 100MB (oversized files are rejected before the body is read).\n- `skill_id` + `replace=true` targets and overwrites that specific skill, skipping the team-authorship check since the caller already owns the row.\n- `replace=true` without `skill_id` upserts by matching skill name; omitting `replace` always creates a new skill — both paths require the caller to be allowed to author into the target `team_id`.\n- The response always stamps `can_edit: true`.\n- Every call is recorded in the account audit log.\n",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **30 requests/minute**; **3 requests/second** per account |\n| Permissions | **Skill Manage** (`ai-sre`) |\n\n## Usage\n\n- Send `multipart/form-data` with a `file` part. Accepted archives: `.skill`, `.zip`, `.tar.gz`, `.tgz`, up to 100 MB; the archive must contain `SKILL.md` with valid frontmatter, and every declared tool must exist.\n- Without `replace`, a new skill is created in `team_id`; a skill with the same name in that scope returns `InvalidParameter`.\n- `replace=true` without `skill_id` overwrites the same-named skill in `team_id` (creating it if absent). `replace=true` with `skill_id` overwrites that skill; the archive's skill name must match it, otherwise `InvalidParameter`.\n- Creating into `team_id` requires membership in that team (`team_id` = 0 requires an account owner or admin). Overwriting requires edit rights on the existing skill.\n- An overwrite keeps `skill_id` and scope, sets `status` back to `enabled`, and sets `is_modified` to `true`. The response always has `can_edit: true`.\n- Every call is recorded in the account audit log.\n",
           "href": "/en/api-reference/ai-sre/skills/skill-write-upload",
           "metadata": {
             "sidebarTitle": "Upload skill"
@@ -3200,7 +3270,7 @@
           }
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Always targets the caller's account-scope knowledge — there is no `pack_id` parameter; use `POST /safari/knowledge/pack/list` to discover team knowledge.\n- The account knowledge is created lazily on first access, so a valid account never gets not-found here.\n",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Always targets the caller's account knowledge; there is no `pack_id` parameter. Use `POST /safari/knowledge/pack/list` to find team knowledge and `POST /safari/knowledge/file/list` to list its files.\n- If the account has no knowledge yet, an empty one is created on this call, so a valid account never gets not-found here.\n- Any member of the account can read it; `pack.can_edit` tells whether the caller may change it.\n",
           "href": "/en/api-reference/ai-sre/knowledge/knowledge-pack-read-get",
           "metadata": {
             "sidebarTitle": "Get account knowledge"
@@ -3234,8 +3304,8 @@
                       "account_id": 2451002751131,
                       "scope": "account",
                       "scope_id": 2451002751131,
-                      "file_count": 17,
-                      "total_bytes": 41010,
+                      "file_count": 2,
+                      "total_bytes": 2737,
                       "version": 134,
                       "duty_version": 130,
                       "created_by": 2476444212131,
@@ -3276,6 +3346,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -3310,7 +3383,7 @@
           }
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Visibility matches the console: admins see the account knowledge plus every team's knowledge; non-admins see the account knowledge plus their own teams' knowledge, and requested `team_ids` are silently intersected with their teams.\n- `scope` selects `all` (default), `account`-only, or `team`-only, overriding `include_account`.\n- `query` applies a case-insensitive substring filter over knowledge ID, scope, and team name; `p`/`limit` paginate the filtered result.\n",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Returns the account knowledge plus the knowledge of teams the caller belongs to. This applies to every caller — owners and admins do not see knowledge of teams they have not joined.\n- The account knowledge appears only after it has been created (by `POST /safari/knowledge/get`, a file call without `pack_id`, or `POST /safari/knowledge/pack/ensure`); this endpoint does not create it.\n- `query` filters first, then `p`/`limit` page the filtered result; `total` is the count after filtering. Omit both `p` and `limit` to get everything.\n",
           "href": "/en/api-reference/ai-sre/knowledge/knowledge-pack-read-list",
           "metadata": {
             "sidebarTitle": "List knowledge"
@@ -3345,8 +3418,8 @@
                         "account_id": 2451002751131,
                         "scope": "account",
                         "scope_id": 2451002751131,
-                        "file_count": 17,
-                        "total_bytes": 41010,
+                        "file_count": 2,
+                        "total_bytes": 2737,
                         "version": 134,
                         "duty_version": 130,
                         "created_by": 2476444212131,
@@ -3359,7 +3432,7 @@
                         "account_id": 2451002751131,
                         "scope": "team",
                         "scope_id": 2477033058131,
-                        "team_name": "研发团队",
+                        "team_name": "SRE Team",
                         "file_count": 4,
                         "total_bytes": 11159,
                         "version": 15,
@@ -3370,7 +3443,7 @@
                         "can_edit": true
                       }
                     ],
-                    "total": 3
+                    "total": 2
                   }
                 }
               }
@@ -3382,6 +3455,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -3421,7 +3497,7 @@
           }
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Knowledge Manage** (`ai-sre`) |\n\n## Usage\n\n- Idempotent: if knowledge already exists at (`scope`, `scope_id`), it is returned unchanged.\n- For `account` scope, `scope_id` is ignored (the account ID is used) and a default `DUTY.md` is seeded on first creation.\n- Creating the account-scope knowledge requires account owner/admin; creating into a team requires membership of that team.\n- Every call is recorded in the account audit log.\n",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Knowledge Manage** (`ai-sre`) |\n\n## Usage\n\n- Idempotent: if knowledge already exists at (`scope`, `scope_id`), it is returned; otherwise it is created empty.\n- For `account` scope, `scope_id` is ignored and a default `DUTY.md` is written whenever the knowledge has none (including after it was deleted). The returned `file_count`/`version` are read before that write and may not include it yet.\n- `account` scope requires the account owner or an admin; `team` scope requires membership of that team — owners and admins are not exempt.\n- Every call is recorded in the account audit log.\n",
           "href": "/en/api-reference/ai-sre/knowledge/knowledge-pack-write-ensure",
           "metadata": {
             "sidebarTitle": "Ensure knowledge"
@@ -3450,17 +3526,18 @@
                 "example": {
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
-                    "pack_id": "kpk_kE49k3FhecfJBwutbshEEc",
+                    "pack_id": "kpk_5qRL34nKtoWM4nQVT2kHzy",
                     "account_id": 2451002751131,
-                    "scope": "account",
-                    "scope_id": 2451002751131,
-                    "file_count": 17,
-                    "total_bytes": 41010,
-                    "version": 138,
-                    "duty_version": 130,
+                    "scope": "team",
+                    "scope_id": 2477033058131,
+                    "team_name": "SRE Team",
+                    "file_count": 4,
+                    "total_bytes": 11159,
+                    "version": 15,
+                    "duty_version": 15,
                     "created_by": 2476444212131,
-                    "created_at_ms": 1778768680053,
-                    "updated_at_ms": 1786458765182,
+                    "created_at_ms": 1782201586089,
+                    "updated_at_ms": 1785462092702,
                     "can_edit": true
                   }
                 }
@@ -3513,7 +3590,7 @@
           }
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Knowledge Manage** (`ai-sre`) |\n\n## Usage\n\n- `scope` is the only mutable field; omitting it is a no-op that returns the current knowledge.\n- For `team` scope, `scope_id` is required; for `account` scope it is set to the account ID automatically.\n- The move fails with `ReferenceExist` when the destination scope already has knowledge — knowledge is never merged.\n- Every call is recorded in the account audit log.\n",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Knowledge Manage** (`ai-sre`) |\n\n## Usage\n\n- `scope` is the only mutable field; omitting it, or passing the knowledge's current scope, changes nothing and returns the current knowledge.\n- The caller must be able to edit the knowledge where it is now (`can_edit`) and must be allowed at the destination: a team the caller belongs to, or `account` for the owner and admins.\n- The move fails with `ReferenceExist` when the destination already has knowledge; knowledge is never merged. Files and `version` move with it unchanged.\n- Every call is recorded in the account audit log.\n",
           "href": "/en/api-reference/ai-sre/knowledge/knowledge-pack-write-update",
           "metadata": {
             "sidebarTitle": "Update knowledge"
@@ -3546,7 +3623,7 @@
                     "account_id": 2451002751131,
                     "scope": "team",
                     "scope_id": 2477033058131,
-                    "team_name": "研发团队",
+                    "team_name": "SRE Team",
                     "file_count": 4,
                     "total_bytes": 11159,
                     "version": 15,
@@ -3607,7 +3684,7 @@
           }
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Knowledge Manage** (`ai-sre`) |\n\n## Usage\n\n- Deleting knowledge removes every file it contains; the operation cannot be undone.\n- Deleting the account-scope knowledge is allowed; it is re-created empty on next access.\n- Every call is recorded in the account audit log.\n",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Knowledge Manage** (`ai-sre`) |\n\n## Usage\n\n- Removes the knowledge and every file it contains; there is no API to restore it.\n- Requires `can_edit` on the knowledge: the account owner or an admin for account knowledge, membership of the team for team knowledge.\n- Deleting the account knowledge is allowed; the next `POST /safari/knowledge/get` (or file call without `pack_id`) creates a new empty one.\n- Every call is recorded in the account audit log.\n",
           "href": "/en/api-reference/ai-sre/knowledge/knowledge-pack-write-delete",
           "metadata": {
             "sidebarTitle": "Delete knowledge"
@@ -3687,7 +3764,7 @@
           }
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Omitting `pack_id` targets the caller's account-scope knowledge (created lazily if absent).\n- Reading team-scope knowledge requires membership of that team.\n- `p`/`limit` are accepted but the current implementation always returns the full file list.\n",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Omitting `pack_id` targets the caller's account knowledge (created empty if absent). An unknown `pack_id` returns `ResourceNotFound`.\n- Account knowledge is readable by every member; team knowledge only by members of that team.\n- `p`/`limit` are accepted but ignored: the response always contains every file. Use `POST /safari/knowledge/file/get` to read a file's content.\n",
           "href": "/en/api-reference/ai-sre/knowledge/knowledge-file-read-list",
           "metadata": {
             "sidebarTitle": "List knowledge files"
@@ -3738,7 +3815,8 @@
                         "updated_at_ms": 1784800003394
                       }
                     ],
-                    "total": 17
+                    "total": 2,
+                    "version": 134
                   }
                 }
               }
@@ -3750,6 +3828,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -3786,7 +3867,7 @@
           }
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Content is returned in `content_b64` (base64); knowledge files are guaranteed UTF-8 text.\n- Omitting `pack_id` targets the account-scope knowledge; reading team-scope knowledge requires team membership.\n- A missing file returns `ResourceNotFound` (HTTP 400).\n",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Content is returned base64-encoded in `content_b64`.\n- A path with no file is not an error: the response has `file` = `null`, an empty `content_b64`, and the current `version`. An unknown `pack_id` returns `ResourceNotFound`.\n- Omitting `pack_id` targets the account knowledge (readable by every member); team knowledge is readable only by members of that team.\n- Keep the returned `version` and pass it as `expected_version` when writing the file back, to avoid overwriting someone else's change.\n",
           "href": "/en/api-reference/ai-sre/knowledge/knowledge-file-read-get",
           "metadata": {
             "sidebarTitle": "Get knowledge file"
@@ -3825,7 +3906,8 @@
                       "updated_by": 2476444212131,
                       "updated_at_ms": 1786458764961
                     },
-                    "content_b64": "IyBPcGVuQVBJIGV4YW1wbGUKVGVtcCBmaWxlIGZvciBBUEkgZG9jcyBleGFtcGxlLgo="
+                    "content_b64": "IyBPcGVuQVBJIGV4YW1wbGUKVGVtcCBmaWxlIGZvciBBUEkgZG9jcyBleGFtcGxlLgo=",
+                    "version": 135
                   }
                 }
               }
@@ -3837,6 +3919,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -3873,7 +3958,7 @@
           }
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Knowledge Manage** (`ai-sre`) |\n\n## Usage\n\n- The file body is sent as base64 text in the JSON field `content_b64` — this is not a multipart upload.\n- Writing an existing `rel_path` overwrites it; `content_type` is inferred from the extension when omitted (`.md` → `text/markdown`).\n- Content must decode to valid UTF-8 text; binary payloads are rejected with `InvalidParameter`.\n- Editing the account-scope knowledge requires account owner/admin; editing team knowledge requires team membership.\n- Every call is recorded in the account audit log.\n",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Knowledge Manage** (`ai-sre`) |\n\n## Usage\n\n- The file body is sent as base64 text in `content_b64` — this is not a multipart upload. Writing an existing `rel_path` overwrites it.\n- Limits: each file at most 1 MiB (`DUTY.md` at most 32 KiB), at most 100 files and 5 MiB in total per knowledge. Content must be UTF-8 text without NUL bytes. Violations, as well as invalid `rel_path` values, return `InvalidParameter`.\n- Pass `expected_version` (from a previous read or write) to write only if nobody changed the knowledge since; on mismatch the call returns HTTP 200 with `status` = `conflict` and writes nothing.\n- Every successful write increases the knowledge `version` by 1; writing `DUTY.md` also updates `duty_version`.\n- Editing account knowledge requires the account owner or an admin; editing team knowledge requires membership of that team.\n- Every call is recorded in the account audit log.\n",
           "href": "/en/api-reference/ai-sre/knowledge/knowledge-file-write-put",
           "metadata": {
             "sidebarTitle": "Upload knowledge file"
@@ -3902,6 +3987,7 @@
                 "example": {
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
+                    "status": "ok",
                     "file": {
                       "file_id": "kfl_gctXKRG45aFQGgxSFr59WY",
                       "pack_id": "kpk_kE49k3FhecfJBwutbshEEc",
@@ -3911,7 +3997,8 @@
                       "checksum": "a0775f9b3f392cd0560b21ad2f579ae4a5d6b1282b9eb145688ba2de717a816d",
                       "updated_by": 2476444212131,
                       "updated_at_ms": 1786458764961
-                    }
+                    },
+                    "version": 135
                   }
                 }
               }
@@ -3943,7 +4030,8 @@
               "example": {
                 "rel_path": "tmp/openapi-example.md",
                 "content_b64": "IyBPcGVuQVBJIGV4YW1wbGUKVGVtcCBmaWxlIGZvciBBUEkgZG9jcyBleGFtcGxlLgo=",
-                "content_type": "text/markdown"
+                "content_type": "text/markdown",
+                "expected_version": 134
               }
             }
           }
@@ -3964,7 +4052,7 @@
           }
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Knowledge Manage** (`ai-sre`) |\n\n## Usage\n\n- Deleting is idempotent — removing a file that does not exist succeeds.\n- When other knowledge files still reference the target, the delete fails with `ReferenceExist` listing the referrers; set `force` to proceed (the referrers are returned as warnings).\n- Omitting `pack_id` targets the account-scope knowledge; editing the account knowledge requires account owner/admin, editing team knowledge requires team membership.\n- Every call is recorded in the account audit log.\n",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | **Knowledge Manage** (`ai-sre`) |\n\n## Usage\n\n- Deleting a file that does not exist succeeds with `status` = `ok`.\n- When other files in the knowledge still reference the target via @ref, the delete fails with `ReferenceExist` naming the referrers; set `force` to delete anyway (the referrers are then returned in `warnings`).\n- Pass `expected_version` to delete only if nobody changed the knowledge since your last read; on mismatch the call returns HTTP 200 with `status` = `conflict`.\n- Omitting `pack_id` targets the account knowledge; editing account knowledge requires the account owner or an admin, editing team knowledge requires membership of that team.\n- Every call is recorded in the account audit log.\n",
           "href": "/en/api-reference/ai-sre/knowledge/knowledge-file-write-delete",
           "metadata": {
             "sidebarTitle": "Delete knowledge file"
@@ -3992,7 +4080,10 @@
                 },
                 "example": {
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
-                  "data": {}
+                  "data": {
+                    "status": "ok",
+                    "version": 136
+                  }
                 }
               }
             }
@@ -4042,7 +4133,7 @@
           }
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- `scope` selects `all` (default — the caller's own personal artifacts plus every team the caller belongs to), `personal` (only the caller's own), or `team` (only team-owned artifacts of the caller's teams).\n- `team_ids` narrows further to specific teams, intersected with the caller's visibility — teams the caller does not belong to return nothing.\n- Default sort is `updated_at` descending; set `orderby` to `created_at` to change the field and `asc: true` to flip direction.\n- For an `app_key` call, visibility is evaluated against the key owner's identity — the list shows that member's personal artifacts and their teams' artifacts.\n",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- `scope` selects `all` (default: the caller's own personal artifacts plus artifacts of every team the caller belongs to), `personal` (only the caller's own personal artifacts), or `team` (only artifacts owned by the caller's teams). An unknown value is treated as `all`.\n- Visibility uses the `app_key` owner's identity and real team membership; account owners and admins see no extra artifacts here. To open any artifact in the account by ID, use `/safari/artifact/gallery/get`.\n- The caller's pinned artifacts always come first; the rest are sorted by `updated_at` descending unless `orderby`/`asc` say otherwise.\n",
           "href": "/en/api-reference/ai-sre/artifacts/artifact-read-list",
           "metadata": {
             "sidebarTitle": "List artifacts"
@@ -4089,40 +4180,41 @@
                     "items": [
                       {
                         "artifact_id": "art_VnfrWic8UbB9q3EfYR4Gmg",
-                        "title": "SK 海力士 2026 Q2 财报深度分析",
-                        "team_id": 2477033058131,
-                        "team_name": "研发团队",
-                        "person_id": 2476444212131,
-                        "creator_name": "yushuangyu",
+                        "title": "Checkout API latency postmortem",
+                        "team_id": 4012,
+                        "team_name": "SRE",
+                        "person_id": 2476001,
+                        "creator_name": "Alice",
                         "is_mine": true,
                         "can_edit": true,
                         "session_id": "sess_VCbVPZrq9YoyBu8sNCmqUy",
-                        "session_title": "分析海力士财报并发布报告",
+                        "session_title": "Investigate checkout API latency spike",
                         "file_id": "pf_SdhEA5fbZJGnHzwrNJMMSB",
-                        "name": "sk-hynix-q2-2026-report.html",
+                        "name": "checkout-latency-postmortem.html",
                         "size": 18996,
                         "content_type": "text/html",
                         "created_at": 1785293373899,
                         "updated_at": 1785747910219,
+                        "pinned_at": 1785750000000,
                         "share_enabled": true,
                         "public_url": "https://console.flashcat.cloud/share/artifact/art_VnfrWic8UbB9q3EfYR4Gmg",
-                        "shared_by": 3790925372131,
+                        "shared_by": 2476001,
                         "shared_at": 1785747928665,
                         "share_file_id": "pf_SdhEA5fbZJGnHzwrNJMMSB"
                       },
                       {
                         "artifact_id": "art_CWQzDU2PXSRJvKDhQbuMKu",
-                        "title": "rum_recommendation",
-                        "team_id": 2477033058131,
-                        "team_name": "研发团队",
-                        "person_id": 3790925372131,
-                        "creator_name": "牛伟利",
+                        "title": "Weekly alert noise report",
+                        "team_id": 4012,
+                        "team_name": "SRE",
+                        "person_id": 2476002,
+                        "creator_name": "Bob",
                         "is_mine": false,
                         "can_edit": true,
                         "session_id": "sess_QXUC9C2PYWP5EE7vETR3UD",
-                        "session_title": "生成 RUM 文档多格式",
+                        "session_title": "Summarize last week's alert noise",
                         "file_id": "pf_Jnc4E5YBcWLGzunB4ntP9s",
-                        "name": "rum_recommendation.pdf",
+                        "name": "alert-noise-weekly.pdf",
                         "size": 137107,
                         "content_type": "application/pdf",
                         "created_at": 1785229432881,
@@ -4141,6 +4233,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -4154,7 +4249,7 @@
       "post": {
         "operationId": "artifact-read-get",
         "summary": "Get artifact detail",
-        "description": "Get a single published artifact by ID.",
+        "description": "Get one published artifact by ID, including its source file, owner and public-share state.",
         "tags": [
           "AI SRE/Artifacts"
         ],
@@ -4164,7 +4259,7 @@
           }
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Visibility is account-wide: any valid `app_key` can read any artifact in the account. `is_mine` and `can_edit` are computed relative to the key owner.\n- When `share_enabled` is true and `file_id` differs from `share_file_id`, the public snapshot is stale — refresh it with `/safari/artifact/gallery/share/sync`.\n",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Any member of the account can read any artifact by ID, including personal artifacts of other members; `is_mine` and `can_edit` are computed for the `app_key` owner.\n- An unknown or removed artifact fails with `ResourceNotFound`.\n- When `share_enabled` is true and `file_id` differs from `share_file_id`, the public snapshot is stale; refresh it with `/safari/artifact/gallery/share/sync`.\n",
           "href": "/en/api-reference/ai-sre/artifacts/artifact-read-get",
           "metadata": {
             "sidebarTitle": "Get artifact detail"
@@ -4207,24 +4302,25 @@
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "artifact_id": "art_VnfrWic8UbB9q3EfYR4Gmg",
-                    "title": "SK 海力士 2026 Q2 财报深度分析",
-                    "team_id": 2477033058131,
-                    "team_name": "研发团队",
-                    "person_id": 2476444212131,
-                    "creator_name": "yushuangyu",
+                    "title": "Checkout API latency postmortem",
+                    "team_id": 4012,
+                    "team_name": "SRE",
+                    "person_id": 2476001,
+                    "creator_name": "Alice",
                     "is_mine": true,
                     "can_edit": true,
                     "session_id": "sess_VCbVPZrq9YoyBu8sNCmqUy",
-                    "session_title": "分析海力士财报并发布报告",
+                    "session_title": "Investigate checkout API latency spike",
                     "file_id": "pf_SdhEA5fbZJGnHzwrNJMMSB",
-                    "name": "sk-hynix-q2-2026-report.html",
+                    "name": "checkout-latency-postmortem.html",
                     "size": 18996,
                     "content_type": "text/html",
                     "created_at": 1785293373899,
                     "updated_at": 1785747910219,
+                    "pinned_at": 1785750000000,
                     "share_enabled": true,
                     "public_url": "https://console.flashcat.cloud/share/artifact/art_VnfrWic8UbB9q3EfYR4Gmg",
-                    "shared_by": 3790925372131,
+                    "shared_by": 2476001,
                     "shared_at": 1785747928665,
                     "share_file_id": "pf_SdhEA5fbZJGnHzwrNJMMSB"
                   }
@@ -4238,6 +4334,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -4261,7 +4360,7 @@
           }
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- At most 50 `file_ids` per call; duplicates and empty strings are ignored.\n- Files with no live published artifact are simply absent from `items` — match results by the echoed `file_id`.\n",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Use it to find out whether files produced in a session are already in the gallery, e.g. before calling `/safari/artifact/gallery/publish-from-file`.\n- Matching is by the file's session and workspace path, not by the exact `file_id`: an older version of a republished file still reports the live artifact.\n- Files with no live artifact, and IDs that do not exist in the account, are simply absent from `items`; match results by the echoed `file_id`.\n",
           "href": "/en/api-reference/ai-sre/artifacts/artifact-read-get-file-state",
           "metadata": {
             "sidebarTitle": "Get file publish state"
@@ -4310,7 +4409,7 @@
                       {
                         "file_id": "pf_SdhEA5fbZJGnHzwrNJMMSB",
                         "artifact_id": "art_VnfrWic8UbB9q3EfYR4Gmg",
-                        "title": "SK 海力士 2026 Q2 财报深度分析",
+                        "title": "Checkout API latency postmortem",
                         "gallery_path": "/ai-sre/artifacts/art_VnfrWic8UbB9q3EfYR4Gmg"
                       }
                     ]
@@ -4325,6 +4424,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -4348,7 +4450,7 @@
           }
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Both URLs expire after `expires_in` seconds (300). Sign again to get fresh URLs.\n- Returned URLs are relative — prepend `https://api.flashcat.cloud` before use, then follow them with `GET /safari/artifact/stream`.\n- The signed token is bound to the calling account and the app_key owner's identity, so a leaked URL does not work for another account or member.\n",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Works for any file of a live gallery artifact in the account; for other session files the caller needs access to the source session (or a valid `share_token`). A missing file and a file the caller cannot reach both fail with `ResourceNotFound`.\n- Both URLs expire after `expires_in` seconds (300). Sign again to get fresh URLs.\n- The URLs are relative: prepend `https://api.flashcat.cloud` and call them with `GET /safari/artifact/stream`, authenticated as the same member that signed them. The token is bound to the account and that member, so it does not work for anyone else.\n",
           "href": "/en/api-reference/ai-sre/artifacts/artifact-read-sign",
           "metadata": {
             "sidebarTitle": "Create signed file URLs"
@@ -4390,10 +4492,10 @@
                 "example": {
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
-                    "download_url": "/safari/artifact/stream?mode=download&t=cGZfU2RoRUE1ZmJaSkduSHp3ck5KTU1TQnxzZXNzX1ZDYlZQWnJxOVlveUJ1OHNOQ21xVXl8MjQ1MTAwMjc1MTEzMXwyNDc2NDQ0MjEyMTMxfDB8MHwxNzg4NTI5NjI2NTU0.hPQHab0MBNbnrHYwc6VwDJbGonIamfWUr0yeSmLHYAs",
-                    "preview_url": "/safari/artifact/stream?mode=preview&t=cGZfU2RoRUE1ZmJaSkduSHp3ck5KTU1TQnxzZXNzX1ZDYlZQWnJxOVlveUJ1OHNOQ21xVXl8MjQ1MTAwMjc1MTEzMXwyNDc2NDQ0MjEyMTMxfDB8MHwxNzg4NTI5NjI2NTU0.hPQHab0MBNbnrHYwc6VwDJbGonIamfWUr0yeSmLHYAs",
+                    "download_url": "/safari/artifact/stream?mode=download&t=eyJmaWxlX2lkIjoicGZfU2RoRUE1ZmJaSkduSHp3ck5KTU1TQiJ9.c2lnbmF0dXJl",
+                    "preview_url": "/safari/artifact/stream?mode=preview&t=eyJmaWxlX2lkIjoicGZfU2RoRUE1ZmJaSkduSHp3ck5KTU1TQiJ9.c2lnbmF0dXJl",
                     "expires_in": 300,
-                    "name": "sk-hynix-q2-2026-report.html",
+                    "name": "checkout-latency-postmortem.html",
                     "size": 18996,
                     "content_type": "text/html"
                   }
@@ -4407,6 +4509,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -4430,7 +4535,7 @@
           }
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **100 requests/minute**; **10 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Success has two forms: a `302` redirect to a short-lived presigned object-storage URL (files stored in S3-compatible storage), or a `200` binary stream (files hosted on a self-hosted runner). Follow redirects.\n- Responses carry `Cache-Control: private, no-store` — they are never cached by the gateway.\n",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Take the full URL from `/safari/artifact/sign`; authenticate with an `app_key` of the same member that signed it. An expired or foreign token fails with `ResourceNotFound`.\n- Files in object storage return `302` to a presigned URL valid for 5 minutes; follow redirects. CSV files in `download` mode, and files kept on a runner, are streamed directly with `200`.\n- `download` mode of a CSV file prepends a UTF-8 byte order mark (if missing) and sets `Content-Type: text/csv; charset=utf-8` so spreadsheet apps open it correctly.\n- A file kept on a runner that is no longer reachable returns `410` with a plain-text message; re-run the task to regenerate the file.\n- Responses carry `Cache-Control: private, no-store`.\n",
           "href": "/en/api-reference/ai-sre/artifacts/artifact-read-stream",
           "metadata": {
             "sidebarTitle": "Download or preview a file"
@@ -4463,7 +4568,7 @@
         ],
         "responses": {
           "200": {
-            "description": "File bytes, proxied, when the file is hosted on a self-hosted runner. Content-Disposition follows `mode`.",
+            "description": "File bytes, returned directly for files kept on a runner and for CSV files in `download` mode. `Content-Disposition` is `attachment` or `inline` according to `mode`.",
             "content": {
               "application/octet-stream": {
                 "schema": {
@@ -4474,7 +4579,28 @@
             }
           },
           "302": {
-            "description": "Redirect to a short-lived presigned object-storage URL when the file lives in S3-compatible storage. Follow the `Location` header; no body."
+            "description": "Redirect to a presigned object-storage URL valid for 5 minutes (files in object storage). The `Location` header carries the URL.",
+            "headers": {
+              "Location": {
+                "description": "Presigned object-storage URL.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            }
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "410": {
+            "description": "The runner holding the file is no longer available; the body is a plain-text message. Re-run the task to regenerate the file.",
+            "content": {
+              "text/plain": {
+                "schema": {
+                  "type": "string"
+                }
+              }
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -4505,7 +4631,7 @@
           }
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Allowed file types: HTML/Markdown, images, PDF, text/data/code files, and zip/tar archives, matched by extension. Files over 16 MiB are rejected.\n- Publishing is an upsert keyed by the source session and workspace path — republishing the same file replaces the artifact's bytes under a fresh `file_id`, which makes an existing public snapshot stale until synced.\n- The artifact inherits personal/team scope from the source session; move it afterwards with `/safari/artifact/gallery/update` if needed.\n- Every call is recorded in the account audit log.\n",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Any account member who can see the file may publish it. Republishing a file whose path already has a live artifact replaces that artifact and requires `can_edit` on it.\n- Allowed file types: HTML/Markdown, images, PDF, text/data/code files, and zip/tar archives, matched by extension. Other types, files over 16 MiB, and files no longer retrievable (runner offline or file expired) fail with `InvalidParameter`.\n- Publishing is an upsert keyed by the source session and workspace path: republishing replaces the title and bytes under a fresh `file_id` and keeps the `artifact_id`, which makes an existing public snapshot stale until synced. Republishing a removed artifact restores it with the same `artifact_id`, with sharing off.\n- A new artifact takes its creator and personal/team scope from the source session (its owner and team); move it afterwards with `/safari/artifact/gallery/update` if needed.\n- Every call is recorded in the account audit log.\n",
           "href": "/en/api-reference/ai-sre/artifacts/artifact-write-publish",
           "metadata": {
             "sidebarTitle": "Publish file as artifact"
@@ -4520,7 +4646,7 @@
               },
               "example": {
                 "file_id": "pf_SdhEA5fbZJGnHzwrNJMMSB",
-                "title": "SK 海力士 2026 Q2 财报深度分析"
+                "title": "Checkout API latency postmortem"
               }
             }
           }
@@ -4549,7 +4675,7 @@
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "artifact_id": "art_VnfrWic8UbB9q3EfYR4Gmg",
-                    "title": "SK 海力士 2026 Q2 财报深度分析",
+                    "title": "Checkout API latency postmortem",
                     "gallery_path": "/ai-sre/artifacts/art_VnfrWic8UbB9q3EfYR4Gmg"
                   }
                 }
@@ -4562,6 +4688,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -4585,7 +4714,7 @@
           }
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Only the provided fields change — omit `title` or `team_id` to leave them unchanged.\n- `team_id: 0` moves the artifact to personal scope (only the creator can manage it); a positive `team_id` requires the caller (for `app_key` calls, the key owner) to be a member of that team.\n- Returns the full artifact after the update.\n- Every call is recorded in the account audit log.\n",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Only the provided fields change; omit `title` or `team_id` to keep them.\n- Requires `can_edit` on the artifact (the creator, any member of its owning team, or anyone who can manage its source session); otherwise the call fails with `AccessDenied`.\n- `team_id: 0` (move to personal) is allowed only for the creator; a positive `team_id` requires the caller (for `app_key` calls, the key owner) to be a member of that team.\n- Returns the full artifact after the update.\n- Every call is recorded in the account audit log.\n",
           "href": "/en/api-reference/ai-sre/artifacts/artifact-write-update",
           "metadata": {
             "sidebarTitle": "Update artifact"
@@ -4600,7 +4729,7 @@
               },
               "example": {
                 "artifact_id": "art_VnfrWic8UbB9q3EfYR4Gmg",
-                "title": "SK 海力士 2026 Q2 财报深度分析（终稿）"
+                "title": "Checkout API latency postmortem (final)"
               }
             }
           }
@@ -4629,24 +4758,25 @@
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "artifact_id": "art_VnfrWic8UbB9q3EfYR4Gmg",
-                    "title": "SK 海力士 2026 Q2 财报深度分析（终稿）",
-                    "team_id": 2477033058131,
-                    "team_name": "研发团队",
-                    "person_id": 2476444212131,
-                    "creator_name": "yushuangyu",
+                    "title": "Checkout API latency postmortem (final)",
+                    "team_id": 4012,
+                    "team_name": "SRE",
+                    "person_id": 2476001,
+                    "creator_name": "Alice",
                     "is_mine": true,
                     "can_edit": true,
                     "session_id": "sess_VCbVPZrq9YoyBu8sNCmqUy",
-                    "session_title": "分析海力士财报并发布报告",
+                    "session_title": "Investigate checkout API latency spike",
                     "file_id": "pf_SdhEA5fbZJGnHzwrNJMMSB",
-                    "name": "sk-hynix-q2-2026-report.html",
+                    "name": "checkout-latency-postmortem.html",
                     "size": 18996,
                     "content_type": "text/html",
                     "created_at": 1785293373899,
                     "updated_at": 1785829000000,
+                    "pinned_at": 1785750000000,
                     "share_enabled": true,
                     "public_url": "https://console.flashcat.cloud/share/artifact/art_VnfrWic8UbB9q3EfYR4Gmg",
-                    "shared_by": 3790925372131,
+                    "shared_by": 2476001,
                     "shared_at": 1785747928665,
                     "share_file_id": "pf_SdhEA5fbZJGnHzwrNJMMSB"
                   }
@@ -4660,6 +4790,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -4683,7 +4816,7 @@
           }
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- This is a detach, not a byte delete: the underlying presented file stays with the source session and can be published again.\n- If public sharing was enabled, the public objects are destroyed in the same operation and the link stops resolving.\n- Every call is recorded in the account audit log.\n",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- This removes the artifact from the gallery; it does not delete the file. The file stays with its source session and can be published again, which restores the same `artifact_id`.\n- Requires `can_edit` on the artifact (the creator, any member of its owning team, or anyone who can manage its source session); otherwise the call fails with `AccessDenied`.\n- If public sharing was on, the public objects are deleted in the same operation and the link stops resolving. All members' pins on the artifact are removed.\n- If the source session has been deleted, the file itself is permanently removed 30 days after the artifact is removed from the gallery.\n- Every call is recorded in the account audit log.\n",
           "href": "/en/api-reference/ai-sre/artifacts/artifact-write-delete",
           "metadata": {
             "sidebarTitle": "Remove artifact from gallery"
@@ -4717,15 +4850,14 @@
                       "properties": {
                         "data": {
                           "type": "null",
-                          "description": "Always null on success."
+                          "description": "Not returned on success; the body carries only `request_id`."
                         }
                       }
                     }
                   ]
                 },
                 "example": {
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
-                  "data": null
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
             }
@@ -4736,6 +4868,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -4759,7 +4894,7 @@
           }
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- The public link is anonymous — anyone with it can view the content, and the link may be forwarded. Content is copied to public CDN objects; the gallery API is not involved when the link is viewed.\n- Idempotent: enabling an already-shared artifact returns the existing link unchanged, and re-enabling after a revoke brings the same link back — the link is keyed by artifact ID.\n- Artifacts over 16 MiB cannot be shared; the call fails with `InvalidParameter`.\n- Sharing is a snapshot: later republishes do not update the public content until you call `/safari/artifact/gallery/share/sync`.\n- Every call is recorded in the account audit log.\n",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- The public link is anonymous: anyone with it can view the content, and the link may be forwarded. The content is copied to public CDN objects, so viewing the link does not go through this API.\n- Requires `can_edit` on the artifact (the creator, any member of its owning team, or anyone who can manage its source session); otherwise the call fails with `AccessDenied`.\n- Idempotent: enabling an already-shared artifact returns the existing state unchanged, and re-enabling after a revoke brings the same link back, because the link is keyed by artifact ID.\n- Artifacts over 16 MiB cannot be shared; the call fails with `InvalidParameter`. On deployments where public sharing is not configured, the call fails with `InternalError`.\n- Sharing is a snapshot: later republishes do not update the public content until you call `/safari/artifact/gallery/share/sync`.\n- Every call is recorded in the account audit log.\n",
           "href": "/en/api-reference/ai-sre/artifacts/artifact-write-share-enable",
           "metadata": {
             "sidebarTitle": "Enable public sharing"
@@ -4804,7 +4939,7 @@
                     "artifact_id": "art_VnfrWic8UbB9q3EfYR4Gmg",
                     "share_enabled": true,
                     "public_url": "https://console.flashcat.cloud/share/artifact/art_VnfrWic8UbB9q3EfYR4Gmg",
-                    "shared_by": 2476444212131,
+                    "shared_by": 2476001,
                     "shared_at": 1785747928665
                   }
                 }
@@ -4817,6 +4952,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -4840,7 +4978,7 @@
           }
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Fails with `InvalidParameter` when sharing is not enabled — enable it first.\n- The link never changes; only the snapshot bytes and `shared_at` are refreshed.\n- Use `share_file_id != file_id` on the artifact detail to detect a stale snapshot before syncing.\n- Every call is recorded in the account audit log.\n",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- Fails with `InvalidParameter` when sharing is not enabled; enable it first. On deployments where public sharing is not configured, the call fails with `InternalError`.\n- Requires `can_edit` on the artifact (the creator, any member of its owning team, or anyone who can manage its source session); otherwise the call fails with `AccessDenied`.\n- The link never changes; only the snapshot content and `shared_at` are refreshed, and `shared_by` keeps the member who enabled sharing.\n- Check `share_file_id != file_id` on the artifact detail to detect a stale snapshot before syncing.\n- Every call is recorded in the account audit log.\n",
           "href": "/en/api-reference/ai-sre/artifacts/artifact-write-share-sync",
           "metadata": {
             "sidebarTitle": "Update shared snapshot"
@@ -4885,7 +5023,7 @@
                     "artifact_id": "art_VnfrWic8UbB9q3EfYR4Gmg",
                     "share_enabled": true,
                     "public_url": "https://console.flashcat.cloud/share/artifact/art_VnfrWic8UbB9q3EfYR4Gmg",
-                    "shared_by": 2476444212131,
+                    "shared_by": 2476001,
                     "shared_at": 1785829900000
                   }
                 }
@@ -4898,6 +5036,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -4921,7 +5062,7 @@
           }
         ],
         "x-mint": {
-          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- The public CDN objects are deleted, so the link stops resolving; this is a no-op when the artifact is not shared.\n- Re-enabling later returns the same `public_url` — the link is keyed by artifact ID, so revoke is not a way to rotate the link.\n- Every call is recorded in the account audit log.\n",
+          "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **300 requests/minute**; **20 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- The public CDN objects are deleted and the link stops resolving. Succeeds without changes when the artifact is not shared.\n- Requires `can_edit` on the artifact (the creator, any member of its owning team, or anyone who can manage its source session); otherwise the call fails with `AccessDenied`.\n- Re-enabling later returns the same `public_url`: the link is keyed by artifact ID, so revoking does not rotate the link.\n- Every call is recorded in the account audit log.\n",
           "href": "/en/api-reference/ai-sre/artifacts/artifact-write-share-revoke",
           "metadata": {
             "sidebarTitle": "Revoke public sharing"
@@ -4955,15 +5096,14 @@
                       "properties": {
                         "data": {
                           "type": "null",
-                          "description": "Always null on success."
+                          "description": "Not returned on success; the body carries only `request_id`."
                         }
                       }
                     }
                   ]
                 },
                 "example": {
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
-                  "data": null
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
             }
@@ -4974,6 +5114,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -4990,7 +5133,7 @@
         "type": "apiKey",
         "in": "query",
         "name": "app_key",
-        "description": "App key issued from the Flashduty console. Required on every public API call. Keep it secret — it grants the same access as the owning account."
+        "description": "APP Key created in the Flashduty console under My → APP Key. Send it as the `app_key` query parameter or in the `Fd-App-Key` request header. Its effective access is the intersection of the key's permission scope and the creator's current role permissions. Keep it secret."
       },
       "AutomationTriggerBearerAuth": {
         "type": "http",
@@ -5043,7 +5186,7 @@
         }
       },
       "Forbidden": {
-        "description": "The app_key is valid but lacks permission for this operation.",
+        "description": "The app_key is valid, but its permission scope or the creator's role does not allow this operation or object.",
         "content": {
           "application/json": {
             "schema": {
@@ -5064,7 +5207,7 @@
         }
       },
       "TooManyRequests": {
-        "description": "Rate limit hit. Either the global API limit or a per-account limit.",
+        "description": "Rate limit hit (per-account limit or the operation's platform-wide limit). Wait for the number of seconds in `Flashcat-Request-Rate-Limit-Delay`, then retry.",
         "content": {
           "application/json": {
             "schema": {
@@ -5082,6 +5225,15 @@
               }
             }
           }
+        },
+        "headers": {
+          "Flashcat-Request-Rate-Limit-Delay": {
+            "description": "Seconds until the current rate-limit window resets. Absent when the request was rejected by the gateway's global protection limit.",
+            "schema": {
+              "type": "integer",
+              "minimum": 0
+            }
+          }
         }
       },
       "ServerError": {
@@ -5113,7 +5265,7 @@
         "properties": {
           "agent_name": {
             "type": "string",
-            "description": "Agent display name.",
+            "description": "Agent display name, used to address the agent in sessions. Must not contain `@`, must not be `general` or `explore`, and must be unique within its scope (account-wide or one team).",
             "maxLength": 128
           },
           "instructions": {
@@ -5123,11 +5275,11 @@
           },
           "card_url": {
             "type": "string",
-            "description": "URL of the remote agent card. Must be an absolute `http` or `https` URL with a non-empty host; reachability is enforced by the execution environment, not at creation time."
+            "description": "URL of the remote agent card. Must be an absolute `http` or `https` URL with a non-empty host; a URL with no path is resolved to `/.well-known/agent-card.json`. If an execution environment is online, the card is fetched and must declare an A2A 1.x `JSONRPC` or `HTTP+JSON` interface."
           },
           "auth_type": {
             "type": "string",
-            "description": "Authentication type for reaching the remote agent: `none` (default when omitted), `api_key`, or `bearer`.",
+            "description": "Authentication used to reach the remote agent with a shared credential:\n- `none`: no credential header.\n- `api_key`: sends `auth_config.api_key` in the header named by `auth_config.header`.\n- `bearer`: sends `Authorization: Bearer <auth_config.token>`.\n\nWhen omitted the value is stored as an empty string, which behaves like `none`.",
             "enum": [
               "none",
               "api_key",
@@ -5139,7 +5291,7 @@
             "additionalProperties": {
               "type": "string"
             },
-            "description": "Authentication config key-values, e.g. the API key or bearer token. Values under credential-looking keys (name containing KEY, SECRET, TOKEN, PASSWORD, etc.) are masked back in responses."
+            "description": "Shared credential key-values: `header` and `api_key` for `auth_type=api_key`, `token` for `auth_type=bearer`. Values of `api_key`, `token`, and `client_secret` are encrypted at rest and masked in responses."
           },
           "streaming": {
             "type": "boolean",
@@ -5159,7 +5311,13 @@
           },
           "auth_mode": {
             "type": "string",
-            "description": "Authentication mode: `shared` (default) shares one credential across all users; `per_user_secret` requires `secret_schema.header_name`; `per_user_oauth` runs per-user OAuth."
+            "description": "Who supplies the credential:\n- `shared` (default; an empty value behaves the same): one credential stored on the agent (`auth_type` + `auth_config`) is used for every caller.\n- `per_user_secret`: each user stores their own secret, sent in the header named by `secret_schema.header_name`.\n- `per_user_oauth`: each user completes their own OAuth authorization; discovery and client registration run on first use.\n\n`per_user_secret` requires `secret_schema` with a non-empty `header_name`; any other value returns `InvalidParameter`.",
+            "enum": [
+              "shared",
+              "per_user_secret",
+              "per_user_oauth"
+            ],
+            "default": "shared"
           },
           "secret_schema": {
             "type": "string",
@@ -5230,7 +5388,7 @@
           },
           "can_edit": {
             "type": "boolean",
-            "description": "Whether the caller may edit this agent."
+            "description": "Whether the caller may update, enable, disable, or delete this agent: `true` for an account-scoped agent only for the account owner or an admin, for a team agent only for members of that team."
           },
           "environments": {
             "type": "array",
@@ -5254,7 +5412,7 @@
           },
           "auth_type": {
             "type": "string",
-            "description": "Authentication type for reaching the remote agent: `none`, `api_key`, or `bearer`. Rows created before validation was tightened may return an empty string, equivalent to `none`.",
+            "description": "Authentication used to reach the remote agent with a shared credential:\n- `none`: no credential header.\n- `api_key`: sends `auth_config.api_key` in the header named by `auth_config.header`.\n- `bearer`: sends `Authorization: Bearer <auth_config.token>`.\n\nAn empty string means `auth_type` was omitted at creation and behaves like `none`.",
             "enum": [
               "",
               "none",
@@ -5267,7 +5425,7 @@
             "additionalProperties": {
               "type": "string"
             },
-            "description": "Authentication config key-values. Values under credential-looking keys (name containing KEY, SECRET, TOKEN, PASSWORD, etc.) are masked. Omitted when empty."
+            "description": "Shared credential key-values (`header`, `api_key`, `token`, …). Values of `api_key`, `token`, `client_secret`, and any other value stored encrypted are masked: longer than 8 characters shows the first and last 4 characters around `****`, otherwise `****`. Omitted when empty."
           },
           "streaming": {
             "type": "boolean",
@@ -5275,7 +5433,7 @@
           },
           "status": {
             "type": "string",
-            "description": "Agent status.",
+            "description": "Whether the agent is offered to AI SRE sessions:\n- `enabled`: available for dispatch (the state after create).\n- `disabled`: kept but not offered; re-enable with `POST /safari/a2a-agent/enable`.",
             "enum": [
               "enabled",
               "disabled"
@@ -5283,14 +5441,14 @@
           },
           "agent_card_name": {
             "type": "string",
-            "description": "Agent name resolved from the remote card. Omitted until the card has been fetched."
+            "description": "Agent name read from the remote card on older records. The server no longer fills this in, so it is omitted for new agents."
           },
           "agent_card_skills": {
             "type": "array",
             "items": {
               "type": "string"
             },
-            "description": "Skills advertised by the remote card. Omitted until the card has been fetched."
+            "description": "Skill names read from the remote card on older records. The server no longer fills this in, so it is omitted for new agents."
           },
           "card_resolve_timeout": {
             "type": "integer",
@@ -5302,7 +5460,7 @@
           },
           "auth_mode": {
             "type": "string",
-            "description": "Authentication mode. One of: `shared` (a single static credential saved on the resource and shared by all callers in the account; the default — an empty value behaves the same), `per_user_secret` (each user stores their own secret per `secret_schema`, injected per user at runtime), `per_user_oauth` (each user completes their own OAuth grant; discovery and registration run lazily on first use).",
+            "description": "Who supplies the credential; omitted when empty, which behaves like `shared`:\n- `shared`: one credential stored on the agent (`auth_type` + `auth_config`) is used for every caller.\n- `per_user_secret`: each user stores their own secret, sent in the header named by `secret_schema.header_name`.\n- `per_user_oauth`: each user completes their own OAuth authorization; discovery and client registration run on first use.",
             "enum": [
               "shared",
               "per_user_secret",
@@ -5371,7 +5529,7 @@
           },
           "limit": {
             "type": "integer",
-            "description": "Page size.",
+            "description": "Page size; 0 or less falls back to 20. No upper bound is enforced.",
             "default": 20
           },
           "scope": {
@@ -5395,14 +5553,14 @@
               "type": "integer",
               "format": "int64"
             },
-            "description": "Filter to these team IDs; empty = the caller's visible set."
+            "description": "Restrict to these team IDs. IDs of teams the caller does not belong to are ignored; empty means all of the caller's teams."
           },
           "include_account": {
             "type": [
               "boolean",
               "null"
             ],
-            "description": "Include account-scoped (team_id=0) rows. Defaults to true."
+            "description": "Include account-scoped (`team_id=0`) rows. Defaults to `true`; ignored when `scope` is `account` (always included) or `team` (never included)."
           }
         }
       },
@@ -5441,7 +5599,7 @@
               "string",
               "null"
             ],
-            "description": "New display name. Omit to leave unchanged.",
+            "description": "New display name; omit to leave unchanged. Same rules as create: no `@`, not `general` / `explore`, unique within the scope.",
             "maxLength": 128
           },
           "instructions": {
@@ -5457,14 +5615,14 @@
               "string",
               "null"
             ],
-            "description": "New card URL. Omit to leave unchanged."
+            "description": "New card URL; omit to leave unchanged. Validated and compatibility-checked the same way as on create; a real change also clears `oauth_metadata` unless a new one is sent."
           },
           "auth_type": {
             "type": [
               "string",
               "null"
             ],
-            "description": "New auth type: `none`, `api_key`, or `bearer`. Omit to leave unchanged.",
+            "description": "New auth type; omit to leave unchanged.\n- `none`: no credential header.\n- `api_key`: sends `auth_config.api_key` in the header named by `auth_config.header`.\n- `bearer`: sends `Authorization: Bearer <auth_config.token>`.",
             "enum": [
               "none",
               "api_key",
@@ -5490,7 +5648,7 @@
               "integer",
               "null"
             ],
-            "description": "Reassign team scope. Omit to leave unchanged. Reassigning requires rights on the destination team; if the team changes without also sending a new environment binding, the existing runner binding must remain selectable by the caller or the update is rejected.",
+            "description": "Reassign team scope; omit to leave unchanged. Moving to a team requires membership in it; moving to account scope (`0`) requires the account owner or an admin. If the team changes without `environments` in the same request, the current runner entries must stay selectable by the caller or the update is rejected.",
             "format": "int64"
           },
           "environments": {
@@ -5508,21 +5666,26 @@
               "string",
               "null"
             ],
-            "description": "New auth mode: shared, per_user_secret, or per_user_oauth. Changing it always rewrites secret_schema together with it."
+            "description": "New auth mode; omit to leave unchanged. Values (who supplies the credential):\n- `shared` (default; an empty value behaves the same): one credential stored on the agent (`auth_type` + `auth_config`) is used for every caller.\n- `per_user_secret`: each user stores their own secret, sent in the header named by `secret_schema.header_name`.\n- `per_user_oauth`: each user completes their own OAuth authorization; discovery and client registration run on first use.\n\nWhen sent, `secret_schema` is overwritten with the value in the same request.",
+            "enum": [
+              "shared",
+              "per_user_secret",
+              "per_user_oauth"
+            ]
           },
           "secret_schema": {
             "type": [
               "string",
               "null"
             ],
-            "description": "New JSON secret schema."
+            "description": "New JSON secret schema, e.g. `{\"header_name\":\"X-Api-Key\"}`. Applied only together with `auth_mode`; sent alone it is ignored."
           },
           "oauth_metadata": {
             "type": [
               "string",
               "null"
             ],
-            "description": "New JSON OAuth metadata. If omitted while auth_mode changes, it is cleared to empty."
+            "description": "New JSON OAuth metadata. A non-empty value is stored as sent. When omitted or empty, the stored value is kept unless `auth_mode` or `card_url` changes, in which case it is cleared."
           },
           "allow_insecure_oauth_http": {
             "type": [
@@ -5551,38 +5714,46 @@
             "type": "string",
             "minLength": 1,
             "maxLength": 255,
-            "description": "Rule name."
+            "description": "Display name of the rule, 1–255 characters; leading and trailing spaces are trimmed."
           },
           "team_id": {
             "type": "integer",
             "format": "int64",
             "minimum": 0,
-            "description": "Scope team ID. 0 or omitted means a personal rule; >0 means a team in the account. Can be reassigned later via update (converting a team rule to personal is owner-only; moving into a team requires the caller to belong to it)."
+            "description": "Scope of the rule. `0` or omitted: a personal rule owned by the caller. `>0`: a team rule; the caller must be a member of that team. The scope cannot be changed after creation."
+          },
+          "run_in": {
+            "type": "string",
+            "enum": [
+              "web",
+              "current-chat"
+            ],
+            "description": "Where the rule's runs execute. `web` (default): in a web console session. `current-chat`: in the IM chat the rule is created from; accepted only from a live IM conversation with the AI SRE agent, so API calls that send it get `400`."
           },
           "enabled": {
             "type": "boolean",
-            "description": "Whether the rule is enabled after creation. Omitted API value is false; Chat/CLI create sends true by default unless the user asks for disabled."
+            "description": "Whether the rule's automatic triggers (schedule, HTTP POST, On-call incident, war room) are armed after creation. Defaults to `false`. Manual runs work either way."
           },
           "cron_expr": {
             "type": "string",
-            "description": "Run cadence. Supports 4 fields (`hour day month weekday`, minute defaults to 0) and 5 fields (`minute hour day month weekday`). The minute must be one fixed integer; 6-field seconds are not supported. A cron that sets both day-of-month and day-of-week is rejected. The create API currently requires this field even for HTTP-POST-only rules; send a valid cron and set `schedule_trigger_enabled=false`.",
+            "description": "Schedule in local time of `timezone`. Accepts 4 fields (`hour day month weekday`, minute defaults to 0) or 5 fields (`minute hour day month weekday`). The minute must be one fixed integer; seconds (6 fields) are not supported; setting both day-of-month and day-of-week is rejected. Required even for rules that use only other triggers: send a valid expression with `schedule_trigger_enabled=false`.",
             "example": "15 9 * * *"
           },
           "timezone": {
             "type": "string",
-            "description": "IANA timezone `cron_expr` is evaluated in, e.g. `Asia/Shanghai`. Must be a timezone name loadable by the server; an invalid value is rejected. Defaults to the caller's member timezone, then the account timezone, then the server default (Asia/Shanghai) when omitted."
+            "description": "IANA time zone name used to evaluate `cron_expr`, e.g. `Asia/Shanghai`. Ambiguous names such as `Local`, `CST`, `UTC+8`, and `GMT+8` are rejected. When omitted: the caller's member time zone, then the account time zone, then `Asia/Shanghai`."
           },
           "schedule_trigger_enabled": {
             "type": [
               "boolean",
               "null"
             ],
-            "description": "Whether the schedule trigger is enabled. Defaults to true when omitted; HTTP-POST-only rules should send false."
+            "description": "Whether the schedule trigger is enabled. Defaults to `true` when omitted; send `false` for rules that should fire only from other triggers."
           },
           "prompt": {
             "type": "string",
             "minLength": 1,
-            "description": "Task prompt sent to the AI SRE agent on each run."
+            "description": "Task instruction sent to the AI SRE agent on every run. Must not be empty after trimming spaces."
           },
           "environment_kind": {
             "type": "string",
@@ -5595,15 +5766,15 @@
           },
           "environment_id": {
             "type": "string",
-            "description": "BYOC Runner ID. Used only when `environment_kind=byoc`."
+            "description": "BYOC runner ID. Required when `environment_kind=byoc` and rejected for other kinds. A personal rule can only use account-scope runners; a team rule can use account-scope runners or runners of its own team."
           },
           "http_post_trigger_enabled": {
             "type": "boolean",
-            "description": "Whether to create and enable an HTTP POST trigger. When enabled, the response includes a one-time token."
+            "description": "Whether to create an enabled HTTP POST trigger. When `true`, the response carries `http_post_trigger_url` and the one-time `http_post_token`."
           },
           "oncall_incident_trigger_enabled": {
             "type": "boolean",
-            "description": "Whether the On-call incident trigger is enabled."
+            "description": "Whether the On-call incident trigger is enabled. When the trigger is created (this is `true`, or channel IDs or severities are sent), both `oncall_incident_channel_ids` and `oncall_incident_severities` must be non-empty."
           },
           "oncall_incident_channel_ids": {
             "type": "array",
@@ -5612,7 +5783,7 @@
               "format": "int64",
               "minimum": 1
             },
-            "description": "On-call integration IDs to watch. Creating or enabling this trigger requires at least one valid ID."
+            "description": "Channel IDs to watch; incidents in these channels can start a run. Each ID must be positive."
           },
           "oncall_incident_severities": {
             "type": "array",
@@ -5624,7 +5795,39 @@
                 "Info"
               ]
             },
-            "description": "Incident severities to watch. Supported values are Critical, Warning, and Info; creating or enabling this trigger requires at least one value."
+            "description": "Incident severities to watch: `Critical` (most severe), `Warning`, or `Info` (least severe) — the On-call incident severity levels."
+          },
+          "oncall_incident_merge_similar": {
+            "type": [
+              "boolean",
+              "null"
+            ],
+            "description": "Whether to merge similar incidents into one analysis. When `true` (default), an incident that closely resembles one already being analyzed by this rule (a run in progress or finished within the last 10 minutes) joins that run's session instead of starting a new one; its own run is recorded as `skipped` with `joined_session_id` set. When `false`, every matching incident starts its own run."
+          },
+          "war_room_trigger_enabled": {
+            "type": "boolean",
+            "description": "Whether the war room trigger is enabled. It fires when a war room (IM group chat) is created for an incident in one of `war_room_channel_ids` with a severity in `war_room_severities`; the agent then runs inside that group chat. When the trigger is created (this is `true`, or `war_room_channel_ids` is sent), both lists must be non-empty."
+          },
+          "war_room_channel_ids": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "int64",
+              "minimum": 1
+            },
+            "description": "Channel IDs whose war rooms start a run. Each ID must be positive."
+          },
+          "war_room_severities": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "enum": [
+                "Critical",
+                "Warning",
+                "Info"
+              ]
+            },
+            "description": "Incident severities that start a run when their war room is created: `Critical` (most severe), `Warning`, or `Info` (least severe) — the On-call incident severity levels."
           }
         },
         "required": [
@@ -5651,30 +5854,30 @@
         "properties": {
           "rule_id": {
             "type": "string",
-            "description": "Rule ID."
+            "description": "Rule ID (prefix `arule_`). Pass it as `rule_id` to get, update, delete, run, and list-runs calls."
           },
           "account_id": {
             "type": "integer",
             "format": "int64",
-            "description": "Account ID."
+            "description": "ID of the account that owns the rule."
           },
           "team_id": {
             "type": "integer",
             "format": "int64",
-            "description": "Scope team ID; 0 means personal rule."
+            "description": "Scope team ID; `0` means a personal rule. Fixed at creation."
           },
           "owner_id": {
             "type": "integer",
             "format": "int64",
-            "description": "Creator person ID."
+            "description": "Person ID of the member who created the rule. For a personal rule, the only person who can manage it."
           },
           "name": {
             "type": "string",
-            "description": "Rule name."
+            "description": "Display name of the rule."
           },
           "enabled": {
             "type": "boolean",
-            "description": "Whether the rule is enabled."
+            "description": "Whether the rule's automatic triggers are armed. A disabled rule can still be run manually. A personal rule is disabled automatically when its owner leaves the account."
           },
           "run_scope": {
             "type": "string",
@@ -5686,7 +5889,7 @@
           },
           "cron_expr": {
             "type": "string",
-            "description": "Normalized 5-field cron expression."
+            "description": "Normalized 5-field cron expression (`minute hour day month weekday`), evaluated in `timezone`."
           },
           "timezone": {
             "type": "string",
@@ -5694,7 +5897,7 @@
           },
           "prompt": {
             "type": "string",
-            "description": "Task prompt."
+            "description": "Task instruction sent to the AI SRE agent on every run."
           },
           "environment_kind": {
             "type": "string",
@@ -5707,7 +5910,7 @@
           },
           "environment_id": {
             "type": "string",
-            "description": "BYOC Runner ID."
+            "description": "BYOC runner ID when `environment_kind=byoc`; empty string otherwise."
           },
           "schedule_trigger_id": {
             "type": "string",
@@ -5723,7 +5926,7 @@
           },
           "http_post_trigger_url": {
             "type": "string",
-            "description": "HTTP POST trigger path. Omitted when the rule has no HTTP POST trigger."
+            "description": "Path to fire the HTTP POST trigger, `/safari/automation/triggers/{trigger_id}/fire`, relative to the API base URL. Send `POST` with `Authorization: Bearer <http_post_token>`. Omitted when the rule has no HTTP POST trigger."
           },
           "http_post_trigger_enabled": {
             "type": "boolean",
@@ -5744,7 +5947,7 @@
               "format": "int64",
               "minimum": 1
             },
-            "description": "On-call integration IDs to watch. Creating or enabling this trigger requires at least one valid ID. Omitted when no On-call incident trigger is configured."
+            "description": "Channel IDs the On-call incident trigger watches. Omitted when the rule has no such trigger."
           },
           "oncall_incident_severities": {
             "type": "array",
@@ -5756,15 +5959,153 @@
                 "Info"
               ]
             },
-            "description": "Incident severities to watch. Supported values are Critical, Warning, and Info; creating or enabling this trigger requires at least one value. Omitted when no On-call incident trigger is configured."
+            "description": "Incident severities the On-call incident trigger watches: `Critical` (most severe), `Warning`, or `Info` (least severe) — the On-call incident severity levels. Omitted when the rule has no such trigger."
+          },
+          "oncall_incident_merge_similar": {
+            "type": "boolean",
+            "description": "Whether similar incidents are merged into one analysis (see the create request). `true` when the rule has no On-call incident trigger."
+          },
+          "war_room_trigger_id": {
+            "type": "string",
+            "description": "War room trigger ID. Omitted when the rule has no war room trigger."
+          },
+          "war_room_trigger_enabled": {
+            "type": "boolean",
+            "description": "Whether the war room trigger is enabled."
+          },
+          "war_room_channel_ids": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "int64",
+              "minimum": 1
+            },
+            "description": "Channel IDs whose war rooms start a run. Omitted when the rule has no war room trigger."
+          },
+          "war_room_severities": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "enum": [
+                "Critical",
+                "Warning",
+                "Info"
+              ]
+            },
+            "description": "Incident severities whose war rooms start a run: `Critical` (most severe), `Warning`, or `Info` (least severe) — the On-call incident severity levels. Omitted when the rule has no war room trigger."
+          },
+          "execution_place": {
+            "type": "string",
+            "enum": [
+              "web_console",
+              "im"
+            ],
+            "description": "Where runs started by the schedule, HTTP POST, On-call incident, and manual triggers execute: `web_console` (a web console session) or `im` (the IM chat the rule was created from). War room runs always execute in the war room's group chat. Fixed at creation."
+          },
+          "execution_location": {
+            "type": "object",
+            "description": "Read-only description of where the rule runs.",
+            "properties": {
+              "place": {
+                "type": "string",
+                "enum": [
+                  "web_console",
+                  "im"
+                ],
+                "description": "Same as the rule's `execution_place`: `web_console` runs in a web console session, `im` runs in the bound IM chat."
+              },
+              "run_scope": {
+                "type": "string",
+                "enum": [
+                  "person",
+                  "team"
+                ],
+                "description": "`person`: runs as the owner; `team`: runs under the team in `team_id`."
+              },
+              "team_id": {
+                "type": "integer",
+                "format": "int64",
+                "description": "Team the runs belong to; `0` for a personal rule."
+              },
+              "platform": {
+                "type": "string",
+                "enum": [
+                  "feishu",
+                  "dingtalk",
+                  "wecom",
+                  "slack",
+                  "teams"
+                ],
+                "description": "IM platform of the bound chat: `feishu` (Feishu/Lark), `dingtalk` (DingTalk), `wecom` (WeCom), `slack` (Slack), `teams` (Microsoft Teams). Present only when `place=im`."
+              },
+              "conversation_mode": {
+                "type": "string",
+                "enum": [
+                  "direct",
+                  "group_chat",
+                  "group_thread",
+                  "war_room_chat"
+                ],
+                "description": "Conversation type of the bound chat: `direct` (one-to-one chat with the bot), `group_chat` (a group chat), `group_thread` (a thread in a group chat), `war_room_chat` (an incident war room). Present only when `place=im`."
+              },
+              "chat_name": {
+                "type": "string",
+                "description": "Name of the bound chat. Present only when `place=im` and the name is known."
+              },
+              "description": {
+                "type": "string",
+                "description": "Human-readable destination label: `Web console` for web console rules, otherwise the chat name or platform and conversation type."
+              }
+            },
+            "required": [
+              "place",
+              "run_scope",
+              "team_id",
+              "description"
+            ]
+          },
+          "last_run": {
+            "type": "object",
+            "description": "The rule's most recent run. Returned only by List Automation rules, and only when the rule has run at least once.",
+            "properties": {
+              "run_id": {
+                "type": "string",
+                "description": "Run ID, as in List Automation runs."
+              },
+              "status": {
+                "type": "string",
+                "enum": [
+                  "queued",
+                  "running",
+                  "retrying",
+                  "succeeded",
+                  "partial",
+                  "failed",
+                  "skipped",
+                  "abandoned",
+                  "blocked"
+                ],
+                "description": "Run status, same meanings as `status` in List Automation runs: `queued`, `running`, `retrying` (in progress); `succeeded`, `partial`, `failed`, `skipped` (did not execute or merged into another run), `abandoned` (never completed), `blocked` (ended waiting on a connector authorization)."
+              },
+              "started_at": {
+                "type": "integer",
+                "format": "int64",
+                "description": "Start time, Unix milliseconds."
+              }
+            },
+            "required": [
+              "run_id",
+              "status",
+              "started_at"
+            ]
           },
           "http_post_token": {
             "type": "string",
-            "description": "HTTP POST trigger token. Returned only on create or token rotation; save it immediately."
+            "description": "HTTP POST trigger token. Returned only in the response that issues it: create with `http_post_trigger_enabled=true`, an update that creates the trigger, or an update with `rotate_http_post_trigger_token=true`. Save it; it cannot be read again."
           },
           "can_edit": {
             "type": "boolean",
-            "description": "True when the caller can manage this rule: the personal rule owner; for team rules, an account admin or a member of the rule's team."
+            "description": "`true` when the caller can manage (get, update, delete, run) this rule: the owner of a personal rule, or a member of a team rule's team. Account owners and admins get no exemption."
           },
           "created_at": {
             "type": "integer",
@@ -5801,12 +6142,15 @@
           "created_at",
           "updated_at",
           "schedule_next_fire_at_ms",
-          "oncall_incident_trigger_enabled"
+          "oncall_incident_trigger_enabled",
+          "oncall_incident_merge_similar",
+          "war_room_trigger_enabled",
+          "execution_place"
         ]
       },
       "AutomationRuleListRequest": {
         "type": "object",
-        "description": "List Automation rules visible to the caller. `all` includes the caller's personal rules plus accessible team rules; account admins do not see other users' personal rules in list results.",
+        "description": "List Automation rules visible to the caller: their own personal rules plus rules of teams they belong to. Account owners and admins are bounded the same way.",
         "properties": {
           "p": {
             "type": "integer",
@@ -5826,7 +6170,7 @@
               "personal",
               "team"
             ],
-            "description": "Scope filter: `all` (own personal + accessible team rules), `personal`, or `team`; default `all`."
+            "description": "Scope filter: `all` (default) your personal rules plus rules of your teams; `personal` only your personal rules; `team` only rules of your teams."
           },
           "team_ids": {
             "type": "array",
@@ -5841,7 +6185,7 @@
               "boolean",
               "null"
             ],
-            "description": "Compatibility field; when scope is empty and this is false, behaves like team scope."
+            "description": "Legacy switch. Only read when `scope` is empty: `false` behaves like `scope=team`; otherwise ignored."
           },
           "enabled": {
             "type": [
@@ -5853,7 +6197,7 @@
           "keyword": {
             "type": "string",
             "maxLength": 64,
-            "description": "Filter by name keyword."
+            "description": "Returns rules whose name contains this text. At most 64 characters."
           }
         }
       },
@@ -5863,7 +6207,7 @@
           "total": {
             "type": "integer",
             "format": "int64",
-            "description": "Total count."
+            "description": "Number of rules matching the filters across all pages."
           },
           "rules": {
             "type": "array",
@@ -5892,7 +6236,7 @@
               "null"
             ],
             "maxLength": 255,
-            "description": "New rule name."
+            "description": "New display name, at most 255 characters. An empty string after trimming is rejected."
           },
           "team_id": {
             "type": [
@@ -5901,21 +6245,21 @@
             ],
             "format": "int64",
             "minimum": 0,
-            "description": "Reassign the rule's scope: 0 converts to a personal rule (only the rule owner may convert a team rule); >0 moves it into a team the caller belongs to. Omit to leave unchanged."
+            "description": "The rule's scope cannot be changed. Omit this field, or send the current value; any other value returns `400`."
           },
           "enabled": {
             "type": [
               "boolean",
               "null"
             ],
-            "description": "Whether the rule is enabled."
+            "description": "Whether the rule's automatic triggers are armed. Omit to keep the current value."
           },
           "cron_expr": {
             "type": [
               "string",
               "null"
             ],
-            "description": "Run cadence. Supports 4 fields (`hour day month weekday`, minute defaults to 0) and 5 fields (`minute hour day month weekday`). The minute must be one fixed integer; 6-field seconds are not supported.",
+            "description": "New schedule, same format as on create: 4 fields (`hour day month weekday`) or 5 fields (`minute hour day month weekday`), fixed-integer minute, no seconds, not both day-of-month and day-of-week. Omit to keep the current expression.",
             "example": "15 9 * * *"
           },
           "timezone": {
@@ -5923,28 +6267,28 @@
               "string",
               "null"
             ],
-            "description": "New IANA timezone for evaluating `cron_expr`. Omit or send null to leave the current timezone unchanged."
+            "description": "New IANA time zone for `cron_expr`. An empty string stores `UTC`. Omit or send `null` to keep the current time zone."
           },
           "schedule_trigger_enabled": {
             "type": [
               "boolean",
               "null"
             ],
-            "description": "Whether the schedule trigger is enabled."
+            "description": "Whether the schedule trigger is enabled. Omit to keep the current value."
           },
           "prompt": {
             "type": [
               "string",
               "null"
             ],
-            "description": "New task prompt."
+            "description": "New task instruction for the agent. Omit to keep the current one."
           },
           "environment_kind": {
             "type": [
               "string",
               "null"
             ],
-            "description": "Runtime environment kind. Omit or send an empty value for automatic selection.",
+            "description": "New runtime environment: `\"\"` automatic selection (prefers an online BYOC runner, falls back to the cloud sandbox), `cloud` platform-hosted cloud sandbox, `byoc` the runner in `environment_id`. Sending this without `environment_id` clears the stored `environment_id`.",
             "enum": [
               "",
               "cloud",
@@ -5956,21 +6300,21 @@
               "string",
               "null"
             ],
-            "description": "BYOC Runner ID."
+            "description": "BYOC runner ID; required when the resulting `environment_kind` is `byoc`, rejected otherwise."
           },
           "http_post_trigger_enabled": {
             "type": [
               "boolean",
               "null"
             ],
-            "description": "Whether the HTTP POST trigger is enabled. Sending true creates one when missing."
+            "description": "Enable or disable the HTTP POST trigger. `true` on a rule without one creates it and returns its token in this response."
           },
           "oncall_incident_trigger_enabled": {
             "type": [
               "boolean",
               "null"
             ],
-            "description": "Whether the On-call incident trigger is enabled."
+            "description": "Enable or disable the On-call incident trigger. Creating it on a rule that has none also needs `oncall_incident_channel_ids` and `oncall_incident_severities`."
           },
           "oncall_incident_channel_ids": {
             "type": "array",
@@ -5979,7 +6323,7 @@
               "format": "int64",
               "minimum": 1
             },
-            "description": "On-call integration IDs to watch. Creating or enabling this trigger requires at least one valid ID."
+            "description": "Replaces the watched channel IDs when non-empty; an empty or omitted list keeps the stored IDs."
           },
           "oncall_incident_severities": {
             "type": "array",
@@ -5991,11 +6335,46 @@
                 "Info"
               ]
             },
-            "description": "Incident severities to watch. Supported values are Critical, Warning, and Info; creating or enabling this trigger requires at least one value."
+            "description": "Replaces the watched severities when non-empty (`Critical` (most severe), `Warning`, or `Info` (least severe) — the On-call incident severity levels); an empty or omitted list keeps the stored values."
+          },
+          "oncall_incident_merge_similar": {
+            "type": [
+              "boolean",
+              "null"
+            ],
+            "description": "Whether to merge similar incidents into one analysis (see the create request). Omit to keep the current value."
+          },
+          "war_room_trigger_enabled": {
+            "type": [
+              "boolean",
+              "null"
+            ],
+            "description": "Enable or disable the war room trigger. Creating it on a rule that has none also needs `war_room_channel_ids` and `war_room_severities`. Omit to keep the current value."
+          },
+          "war_room_channel_ids": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "int64",
+              "minimum": 1
+            },
+            "description": "Replaces the channel IDs whose war rooms start a run when non-empty; an empty or omitted list keeps the stored IDs."
+          },
+          "war_room_severities": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "enum": [
+                "Critical",
+                "Warning",
+                "Info"
+              ]
+            },
+            "description": "Replaces the war room severities when non-empty (`Critical` (most severe), `Warning`, or `Info` (least severe) — the On-call incident severity levels); an empty or omitted list keeps the stored values."
           },
           "rotate_http_post_trigger_token": {
             "type": "boolean",
-            "description": "Whether to rotate the HTTP POST trigger token. The new token is returned only in this response."
+            "description": "When `true`, issues a new HTTP POST trigger token and invalidates the old one. The trigger must exist and be enabled. The new token is returned only in this response."
           }
         },
         "required": [
@@ -6007,16 +6386,24 @@
         "properties": {
           "run_id": {
             "type": "string",
-            "description": "Run ID."
+            "description": "Run ID (prefix `trun_`)."
           },
           "session_id": {
             "type": "string",
-            "description": "Session created for this run, extracted from `result_json`. Omitted when the run has not (yet) started a session."
+            "description": "AI SRE session the run executed in. Omitted when the run has not started a session, when it joined another run (see `joined_session_id`), or when it executed in an IM chat."
           },
           "session_name": {
             "type": "string",
             "description": "Display name of the run's session, stamped via a batch lookup. Omitted when empty or when the lookup fails."
           },
+          "joined_session_id": {
+            "type": "string",
+            "description": "For an On-call incident run merged into a similar incident's analysis (`status=skipped`): the session it joined. Omitted otherwise."
+          },
+          "joined_session_name": {
+            "type": "string",
+            "description": "Display name of `joined_session_id`. Omitted when empty or when the name lookup fails."
+          },
           "kind": {
             "type": "string",
             "description": "Run kind; runs listed for a rule are always `automation_rule`.",
@@ -6027,11 +6414,11 @@
           "account_id": {
             "type": "integer",
             "format": "int64",
-            "description": "Account ID."
+            "description": "ID of the account that owns the run."
           },
           "rule_id": {
             "type": "string",
-            "description": "Rule ID."
+            "description": "ID of the rule this run belongs to."
           },
           "trigger_kind": {
             "type": "string",
@@ -6040,13 +6427,22 @@
               "debug",
               "manual",
               "http_post",
-              "oncall_incident"
+              "oncall_incident",
+              "war_room_created"
+            ],
+            "description": "Trigger kind. One of:\n| Value | Meaning |\n| --- | --- |\n| `schedule` | Fired by the rule's schedule trigger |\n| `debug` | Debug run (reserved; current rule runs never carry this kind) |\n| `manual` | Started with Run Automation rule |\n| `http_post` | Fired via the rule's HTTP POST trigger |\n| `oncall_incident` | Fired by a matching On-call incident |\n| `war_room_created` | Fired when a war room was created for a matching incident; runs in that group chat |"
+          },
+          "execution_place": {
+            "type": "string",
+            "enum": [
+              "web_console",
+              "im"
             ],
-            "description": "Trigger kind. One of:\n| Value | Meaning |\n| --- | --- |\n| `schedule` | Fired by the rule's schedule trigger |\n| `debug` | Debug run (reserved; current rule runs never carry this kind) |\n| `manual` | Triggered manually by a user |\n| `http_post` | Fired via the rule's HTTP POST webhook |\n| `oncall_incident` | Fired by an on-call incident event |"
+            "description": "Where this run executed: `web_console` (a web console session; `session_id` links to it) or `im` (an IM chat; session details are withheld). `war_room_created` runs are always `im`."
           },
           "occurrence_key": {
             "type": "string",
-            "description": "Idempotency key for this occurrence."
+            "description": "Idempotency key of this occurrence: `manual:<run_id>` for manual runs, `<trigger_id>:<scheduled fire time in Unix ms>` for schedule runs, `oncall_incident:<trigger_id>:<incident_id>` for On-call incident runs."
           },
           "status": {
             "type": "string",
@@ -6061,11 +6457,11 @@
               "abandoned",
               "blocked"
             ],
-            "description": "Run status. One of (the first three are in-flight, the rest terminal):\n| Value | Meaning |\n| --- | --- |\n| `queued` | Enqueued, waiting for a worker |\n| `running` | Executing |\n| `retrying` | An attempt failed and a retry is scheduled |\n| `succeeded` | Completed successfully |\n| `partial` | Partially succeeded (currently only produced by memory-consolidation runs; rule runs never reach it) |\n| `failed` | Terminal failure, no further retries |\n| `skipped` | Not executed (e.g. grace period expired, trigger or rule invalid); the reason is kept on the run record |\n| `abandoned` | Still in-flight past the stale threshold and swept as never-completed (e.g. worker died) |\n| `blocked` | Terminal: the run produced output but ended with a connector waiting on a human to complete authorization (distinct from `failed`) |"
+            "description": "Run status. One of (the first three are in-flight, the rest terminal):\n| Value | Meaning |\n| --- | --- |\n| `queued` | Enqueued, waiting for a worker |\n| `running` | Executing |\n| `retrying` | An attempt failed and a retry is scheduled |\n| `succeeded` | Completed successfully |\n| `partial` | Partially succeeded (currently only produced by memory-consolidation runs; rule runs never reach it) |\n| `failed` | Terminal failure, no further retries |\n| `skipped` | Not executed (e.g. grace period expired, trigger or rule invalid); the reason is kept on the run record. Also used for an On-call incident run merged into a similar incident's analysis (see `joined_session_id`) |\n| `abandoned` | Still in-flight past the stale threshold and swept as never-completed (e.g. worker died) |\n| `blocked` | Terminal: the run produced output but ended with a connector waiting on a human to complete authorization (distinct from `failed`) |"
           },
           "attempts": {
             "type": "integer",
-            "description": "Attempt count."
+            "description": "Number of execution attempts made for this run."
           },
           "started_at": {
             "type": "integer",
@@ -6104,7 +6500,7 @@
               "null"
             ],
             "additionalProperties": true,
-            "description": "Raw run result JSON (carries the run's `session_id` once started); null when empty."
+            "description": "Raw run result JSON (carries `session_id` once a session started). `null` when empty or when the run executed in an IM chat."
           },
           "created_at": {
             "type": "integer",
@@ -6123,6 +6519,7 @@
           "account_id",
           "rule_id",
           "trigger_kind",
+          "execution_place",
           "occurrence_key",
           "status",
           "attempts",
@@ -6152,7 +6549,7 @@
           "limit": {
             "type": "integer",
             "default": 20,
-            "description": "Page size."
+            "description": "Page size. Values below 1 fall back to 20."
           },
           "status": {
             "type": "string",
@@ -6176,9 +6573,10 @@
               "debug",
               "manual",
               "http_post",
-              "oncall_incident"
+              "oncall_incident",
+              "war_room_created"
             ],
-            "description": "Trigger source filter: `schedule` cron trigger, `debug` debug run, `manual` manual run, `http_post` HTTP POST trigger, `oncall_incident` on-call incident trigger; omit for no filter."
+            "description": "Trigger filter: `schedule` schedule trigger, `debug` debug run, `manual` manual run, `http_post` HTTP POST trigger, `oncall_incident` On-call incident trigger, `war_room_created` war room trigger; omit for no filter."
           },
           "started_after_ms": {
             "type": "integer",
@@ -6203,7 +6601,7 @@
           "total": {
             "type": "integer",
             "format": "int64",
-            "description": "Total count."
+            "description": "Number of runs matching the filters across all pages."
           },
           "runs": {
             "type": "array",
@@ -6228,7 +6626,7 @@
           },
           "session_id": {
             "type": "string",
-            "description": "AI SRE session ID for this run. Always populated in a 200 response, since the call only returns after the session has started."
+            "description": "AI SRE session started for this run. Omitted when the rule executes in an IM chat (`execution_place=im`)."
           }
         },
         "required": [
@@ -6240,31 +6638,88 @@
         "properties": {
           "name": {
             "type": "string",
-            "description": "Template name."
+            "description": "Localized template name; use it as the rule `name`."
+          },
+          "key": {
+            "type": "string",
+            "description": "Stable, locale-independent template ID (lowercase letters, digits, underscores). Present only on templates that other console pages link to directly; omitted otherwise."
           },
           "description": {
             "type": "string",
-            "description": "Template description."
+            "description": "Localized explanation of what a rule created from this template does."
           },
           "icon": {
             "type": "string",
-            "description": "Icon identifier."
+            "description": "Icon identifier the console displays for the template, e.g. `siren`."
+          },
+          "category": {
+            "type": "string",
+            "description": "Free-text, localized name of the group the template is shown under in the console, e.g. `Incident Response`. Groups appear in the order of their first template."
           },
           "enabled": {
             "type": "boolean",
-            "description": "Whether a rule created from this template starts out enabled (prefill value)."
+            "description": "Prefill for the create request's `enabled`."
           },
           "prompt": {
             "type": "string",
-            "description": "Template prompt."
+            "description": "Prefill for the create request's `prompt`."
+          },
+          "schedule_trigger_enabled": {
+            "type": "boolean",
+            "description": "Prefill for `schedule_trigger_enabled`; `true` exactly when `cron_expr` is present."
+          },
+          "cron_expr": {
+            "type": "string",
+            "description": "Prefill for `cron_expr`. Omitted when the template does not use the schedule trigger; the create request still needs a valid `cron_expr`."
+          },
+          "http_post_trigger_enabled": {
+            "type": "boolean",
+            "description": "Prefill for `http_post_trigger_enabled`."
+          },
+          "oncall_incident_trigger_enabled": {
+            "type": "boolean",
+            "description": "Prefill for `oncall_incident_trigger_enabled`; when `true`, add `oncall_incident_channel_ids` before creating."
+          },
+          "oncall_incident_severities": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "enum": [
+                "Critical",
+                "Warning",
+                "Info"
+              ]
+            },
+            "description": "Prefill for `oncall_incident_severities` (`Critical` (most severe), `Warning`, or `Info` (least severe) — the On-call incident severity levels). Omitted when the template does not use the On-call incident trigger."
+          },
+          "war_room_trigger_enabled": {
+            "type": "boolean",
+            "description": "Prefill for `war_room_trigger_enabled`; when `true`, add `war_room_channel_ids` before creating."
+          },
+          "war_room_severities": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "enum": [
+                "Critical",
+                "Warning",
+                "Info"
+              ]
+            },
+            "description": "Prefill for `war_room_severities` (`Critical` (most severe), `Warning`, or `Info` (least severe) — the On-call incident severity levels). Omitted when the template does not use the war room trigger."
           }
         },
         "required": [
           "name",
           "description",
           "icon",
+          "category",
           "enabled",
-          "prompt"
+          "prompt",
+          "schedule_trigger_enabled",
+          "http_post_trigger_enabled",
+          "oncall_incident_trigger_enabled",
+          "war_room_trigger_enabled"
         ]
       },
       "AutomationTemplateListRequest": {
@@ -6273,7 +6728,7 @@
           "locale": {
             "type": "string",
             "maxLength": 16,
-            "description": "Template locale such as zh-CN or en-US. Omit to detect from the request locale."
+            "description": "Template language. A value containing `zh` returns Chinese, one containing `en` returns English, any other non-empty value returns Chinese. When omitted, the `locale`/`lang` query parameter or the `Accept-Language` header decides, defaulting to Chinese."
           }
         }
       },
@@ -6285,7 +6740,7 @@
             "items": {
               "$ref": "#/components/schemas/AutomationTemplateItem"
             },
-            "description": "Array of built-in automation templates, with display text localized by the request `locale` (falling back to request headers)."
+            "description": "Built-in templates in the resolved language, in display order."
           }
         },
         "required": [
@@ -6294,7 +6749,7 @@
       },
       "ContextResolvedItem": {
         "type": "object",
-        "description": "Snapshot of the three-tier knowledge resolution for this session.",
+        "description": "Knowledge versions the session's context resolved. In `POST /safari/session/get` only `versions` is filled (with `resolved_at_ms` = 0); the object is omitted until the agent has resolved knowledge at least once.",
         "properties": {
           "account_pack_id": {
             "type": "string",
@@ -6318,7 +6773,7 @@
             "additionalProperties": {
               "type": "integer"
             },
-            "description": "Resolved version map, one entry per knowledge."
+            "description": "Map from knowledge ID to the version the agent last loaded."
           }
         },
         "required": [
@@ -6334,7 +6789,7 @@
           },
           "message": {
             "type": "string",
-            "description": "Human-readable error message, localized by the caller's Accept-Language. May contain field names, IDs, or other context from the failing request.",
+            "description": "Human-readable error message in the response language (`locale` / `lang` query parameter or `Accept-Language` header). May name the offending field; do not parse it.",
             "example": "The specified parameter template_id is not valid."
           }
         },
@@ -6345,7 +6800,7 @@
       },
       "EnvironmentBinding": {
         "type": "object",
-        "description": "The runner or cloud sandbox the session is bound to. Null until the first message.",
+        "description": "The runner or cloud sandbox the session is bound to. Returned by `POST /safari/session/get` only; omitted until the session has been bound (after its first message).",
         "properties": {
           "kind": {
             "type": "string",
@@ -6363,11 +6818,17 @@
             "type": "string",
             "description": "Human-readable environment name; empty for cloud bindings using the default allowlist."
           },
+          "team_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Team that owns the bound environment; 0 for account-scope environments."
+          },
           "status": {
             "type": "string",
-            "description": "Live binding health, namespaced by kind: BYOC uses online/pending/offline/deleted; cloud uses available/rebuilding/expired.",
+            "description": "Live health of the binding. Omitted when unknown.\n\nFor `byoc`:\n- `online`: runner connected and ready\n- `degraded`: runner connected but its executor is unhealthy; messages are still accepted\n- `pending`: runner has never connected\n- `offline`: runner heartbeat lost; messages cannot be served\n- `deleted`: the environment no longer exists; choose another\n\nFor `cloud`:\n- `available`: the sandbox can serve the next message (paused or starting sandboxes resume automatically)\n- `rebuilding`: the sandbox is being resumed or recreated\n- `expired`: the sandbox failed permanently and cannot recover by itself\n- `deleted`: the selected cloud environment template was deleted",
             "enum": [
               "online",
+              "degraded",
               "pending",
               "offline",
               "deleted",
@@ -6384,7 +6845,7 @@
       },
       "ErrorCode": {
         "type": "string",
-        "description": "Flashduty error code enum. Every failed API response sets `error.code` to one of these stable wire strings. HTTP status is informational — the authoritative signal is the enum value.\n\n| Code | HTTP | Meaning |\n|---|---|---|\n| `OK` | 200 | Reserved — not returned on real errors. |\n| `InvalidParameter` | 400 | A required parameter is missing or failed validation. |\n| `BadRequest` | 400 | Generic 400 used when no more specific code fits. |\n| `InvalidContentType` | 400 | The `Content-Type` header is not `application/json`. |\n| `ResourceNotFound` | 400 | The referenced resource does not exist. Note: returned as HTTP 400, not 404 (historical choice). |\n| `NoLicense` | 400 | The feature is license-gated and no active license was found. |\n| `ReferenceExist` | 400 | Deletion blocked — other entities still reference this resource. |\n| `Unauthorized` | 401 | `app_key` is missing, invalid, or expired. |\n| `BalanceNotEnough` | 402 | Billing-gated operation with insufficient account balance. |\n| `AccessDenied` | 403 | Authenticated but lacking the permission required for this operation. |\n| `RouteNotFound` | 404 | The request URL path is not a known route. |\n| `MethodNotAllowed` | 405 | The HTTP method is not allowed on this otherwise-known path. |\n| `UndonedOrderExist` | 409 | An outstanding billing order blocks this new one. Wait and retry. |\n| `RequestLocked` | 423 | Operation temporarily locked due to repeated failures. |\n| `EntityTooLarge` | 413 | Request body exceeds the configured max size. |\n| `RequestTooFrequently` | 429 | Rate limit hit — API-global, per-account, or per-integration. |\n| `RequestVerifyRequired` | 428 | Second-factor verification required but not supplied. |\n| `DangerousOperation` | 428 | High-risk operation requires MFA verification. |\n| `InternalError` | 500 | Unhandled server-side error. Include `request_id` in the bug report. |\n| `ServiceUnavailable` | 503 | A backend dependency is unavailable. Try again later. |",
+        "description": "Error code. Every failed response sets `error.code` to one of these stable strings; branch on it rather than on the HTTP status.\n\n| Code | HTTP | Meaning |\n|---|---|---|\n| `OK` | 200 | Reserved; never returned on a failed request. |\n| `InvalidParameter` | 400 | A parameter is missing, has the wrong type, or failed validation; `message` usually names the field. |\n| `BadRequest` | 400 | The request breaks a business rule or conflicts with the current state of an object; `message` says which. |\n| `InvalidContentType` | 400 | The body is not sent as `application/json`. |\n| `ResourceNotFound` | 400 | The referenced object does not exist in this account or was deleted. Returned as HTTP 400, not 404. |\n| `NoLicense` | 400 | The account's plan does not include the feature, a plan quota is used up, the plan has expired, or credits are insufficient. |\n| `ReferenceExist` | 400 | The object is still referenced by other objects, so it cannot be deleted. |\n| `Unauthorized` | 401 | The APP Key is missing, invalid, or deleted. |\n| `BalanceNotEnough` | 402 | Console-only (billing); not returned by Open API operations. |\n| `AccessDenied` | 403 | The APP Key's permission scope or the creator's role does not allow this operation or object. |\n| `RouteNotFound` | 404 | No operation matches the HTTP method and path. |\n| `MethodNotAllowed` | 405 | The path exists but not for this HTTP method. |\n| `UndonedOrderExist` | 409 | Console-only (billing); not returned by Open API operations. |\n| `EntityTooLarge` | 413 | The request body exceeds the size limit. |\n| `RequestLocked` | 423 | Console-only (sign-in protection); not returned by Open API operations. |\n| `RequestVerifyRequired` | 428 | Console-only (verification code); not returned by Open API operations. |\n| `DangerousOperation` | 428 | Console-only (MFA for high-risk actions); not returned by Open API operations. |\n| `RequestTooFrequently` | 429 | A rate limit was hit; wait for the `Flashcat-Request-Rate-Limit-Delay` response header (seconds) before retrying. |\n| `InternalError` | 500 | Unexpected server error; retry with backoff and include `request_id` when reporting. |\n| `ServiceUnavailable` | 503 | A backend dependency is overloaded or unavailable; retry with backoff. |",
         "enum": [
           "OK",
           "InvalidParameter",
@@ -6399,35 +6860,35 @@
           "RouteNotFound",
           "MethodNotAllowed",
           "UndonedOrderExist",
-          "RequestLocked",
           "EntityTooLarge",
-          "RequestTooFrequently",
+          "RequestLocked",
           "RequestVerifyRequired",
           "DangerousOperation",
+          "RequestTooFrequently",
           "InternalError",
           "ServiceUnavailable"
         ],
         "x-enumDescriptions": {
-          "OK": "Reserved — not returned on real errors.",
-          "InvalidParameter": "A required parameter is missing or failed validation.",
-          "BadRequest": "Generic 400 used when no more specific code fits.",
-          "InvalidContentType": "The `Content-Type` header is not `application/json`.",
-          "ResourceNotFound": "The referenced resource does not exist. Note: returned as HTTP 400, not 404 (historical choice).",
-          "NoLicense": "The feature is license-gated and no active license was found.",
-          "ReferenceExist": "Deletion blocked — other entities still reference this resource.",
-          "Unauthorized": "`app_key` is missing, invalid, or expired.",
-          "BalanceNotEnough": "Billing-gated operation with insufficient account balance.",
-          "AccessDenied": "Authenticated but lacking the permission required for this operation.",
-          "RouteNotFound": "The request URL path is not a known route.",
-          "MethodNotAllowed": "The HTTP method is not allowed on this otherwise-known path.",
-          "UndonedOrderExist": "An outstanding billing order blocks this new one. Wait and retry.",
-          "RequestLocked": "Operation temporarily locked due to repeated failures.",
-          "EntityTooLarge": "Request body exceeds the configured max size.",
-          "RequestTooFrequently": "Rate limit hit — API-global, per-account, or per-integration.",
-          "RequestVerifyRequired": "Second-factor verification required but not supplied.",
-          "DangerousOperation": "High-risk operation requires MFA verification.",
-          "InternalError": "Unhandled server-side error. Include `request_id` in the bug report.",
-          "ServiceUnavailable": "A backend dependency is unavailable. Try again later."
+          "OK": "Reserved; never returned on a failed request.",
+          "InvalidParameter": "A parameter is missing, has the wrong type, or failed validation; `message` usually names the field.",
+          "BadRequest": "The request breaks a business rule or conflicts with the current state of an object; `message` says which.",
+          "InvalidContentType": "The body is not sent as `application/json`.",
+          "ResourceNotFound": "The referenced object does not exist in this account or was deleted. Returned as HTTP 400, not 404.",
+          "NoLicense": "The account's plan does not include the feature, a plan quota is used up, the plan has expired, or credits are insufficient.",
+          "ReferenceExist": "The object is still referenced by other objects, so it cannot be deleted.",
+          "Unauthorized": "The APP Key is missing, invalid, or deleted.",
+          "BalanceNotEnough": "Console-only (billing); not returned by Open API operations.",
+          "AccessDenied": "The APP Key's permission scope or the creator's role does not allow this operation or object.",
+          "RouteNotFound": "No operation matches the HTTP method and path.",
+          "MethodNotAllowed": "The path exists but not for this HTTP method.",
+          "UndonedOrderExist": "Console-only (billing); not returned by Open API operations.",
+          "EntityTooLarge": "The request body exceeds the size limit.",
+          "RequestLocked": "Console-only (sign-in protection); not returned by Open API operations.",
+          "RequestVerifyRequired": "Console-only (verification code); not returned by Open API operations.",
+          "DangerousOperation": "Console-only (MFA for high-risk actions); not returned by Open API operations.",
+          "RequestTooFrequently": "A rate limit was hit; wait for the `Flashcat-Request-Rate-Limit-Delay` response header (seconds) before retrying.",
+          "InternalError": "Unexpected server error; retry with backoff and include `request_id` when reporting.",
+          "ServiceUnavailable": "A backend dependency is overloaded or unavailable; retry with backoff."
         },
         "example": "InvalidParameter"
       },
@@ -6463,12 +6924,32 @@
           },
           "invocation_id": {
             "type": "string",
-            "description": "ADK invocation id grouping a turn."
+            "description": "ID of the invocation (one agent turn) that wrote this event. Omitted when empty."
+          },
+          "root_invocation_id": {
+            "type": "string",
+            "description": "Invocation ID of the top-level user turn this event belongs to, linking events written by nested subagent invocations back to it. Omitted when empty."
+          },
+          "delivery_mode": {
+            "type": "string",
+            "enum": [
+              "reply_only"
+            ],
+            "description": "Delivery mode negotiated for the IM request that produced this event. `reply_only`: the IM client shows only explicit replies, not the agent's final text. Omitted for normal delivery."
+          },
+          "is_error": {
+            "type": "boolean",
+            "description": "True when this is an assistant event recording a runtime failure whose message is safe to show to users. Omitted when false."
           },
           "author": {
             "type": "string",
             "description": "Event author (e.g. user, the agent name)."
           },
+          "person_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Member ID of the person who sent this user message. Omitted on assistant and tool events and when no member is recorded (automation runs, some IM turns)."
+          },
           "branch": {
             "type": "string",
             "description": "ADK branch path for nested agents."
@@ -6532,7 +7013,7 @@
         "properties": {
           "server_name": {
             "type": "string",
-            "description": "MCP server name: must start with a letter and contain only letters, digits, `-`, or `_` (`@` is reserved); unique within its scope (account-wide or one team), case-insensitive.",
+            "description": "MCP server name: must start with a letter and contain only letters, digits, `-`, or `_` (`@` is reserved); unique within its scope (account-wide or one team).",
             "minLength": 1,
             "maxLength": 255
           },
@@ -6567,7 +7048,7 @@
             "additionalProperties": {
               "type": "string"
             },
-            "description": "Environment variables (stdio transport)."
+            "description": "Environment variables (`stdio` transport). Values under credential-looking names (containing `KEY`, `SECRET`, `TOKEN`, `PASSWORD`, …) are encrypted at rest and masked in responses."
           },
           "url": {
             "type": "string",
@@ -6578,19 +7059,25 @@
             "additionalProperties": {
               "type": "string"
             },
-            "description": "HTTP headers (sse / streamable-http)."
+            "description": "HTTP headers (`sse` / `streamable-http` transport). Values under credential-looking names (containing `KEY`, `TOKEN`, `AUTHORIZATION`, …) are encrypted at rest and masked in responses."
           },
           "connect_timeout": {
             "type": "integer",
-            "description": "Connection timeout in seconds. 0 = default (10s)."
+            "description": "Connection timeout in seconds. Omitted or `0` is stored as `0` and means the 10-second default."
           },
           "call_timeout": {
             "type": "integer",
-            "description": "Tool-call timeout in seconds. 0 = default (60s)."
+            "description": "Tool-call timeout in seconds. Omitted or `0` is stored as `0` and means the 60-second default."
           },
           "auth_mode": {
             "type": "string",
-            "description": "Authentication mode: shared (default), per_user_secret, or per_user_oauth."
+            "description": "Who supplies the credential:\n- `shared` (default; an empty value behaves the same): one credential stored on the server (`env` / `headers`) is used for every caller.\n- `per_user_secret`: each user stores their own secret, sent in the header named by `secret_schema.header_name`.\n- `per_user_oauth`: each user completes their own OAuth authorization; discovery and client registration run on first use.\n\n`per_user_secret` requires `secret_schema` with a non-empty `header_name`; any other value returns `InvalidParameter`.",
+            "enum": [
+              "shared",
+              "per_user_secret",
+              "per_user_oauth"
+            ],
+            "default": "shared"
           },
           "secret_schema": {
             "type": "string",
@@ -6611,7 +7098,7 @@
           },
           "team_id": {
             "type": "integer",
-            "description": "Team scope: 0 = account-wide; >0 = team.",
+            "description": "Team scope: `0` = account-wide (account owner or admin only); `>0` = a team the caller belongs to. Ignored when `source_template_name` is set — marketplace installs are always account-wide.",
             "format": "int64"
           },
           "environments": {
@@ -6631,7 +7118,7 @@
           },
           "source_template_name": {
             "type": "string",
-            "description": "Marketplace template name when created from a connector template."
+            "description": "Name of the marketplace template to install. When set, the template must exist, the server is created at account scope, and the connection fields must match the template except for its declared parameter values. Cannot be changed later."
           }
         },
         "required": [
@@ -6686,7 +7173,7 @@
           },
           "can_edit": {
             "type": "boolean",
-            "description": "Whether the caller may edit this server."
+            "description": "Whether the caller may update, enable, disable, or delete this server: `true` for an account-scoped server only for the account owner or an admin, for a team server only for members of that team. Create and update responses always return `true`."
           },
           "environments": {
             "type": "array",
@@ -6697,7 +7184,7 @@
           },
           "server_name": {
             "type": "string",
-            "description": "MCP server name, unique within its scope (account-wide or one team), case-insensitive."
+            "description": "MCP server name, unique within its scope (account-wide or one team)."
           },
           "description": {
             "type": "string",
@@ -6732,7 +7219,7 @@
             "additionalProperties": {
               "type": "string"
             },
-            "description": "Environment variables (stdio transport). Secret values are masked."
+            "description": "Environment variables (`stdio` transport). Values under credential-looking names, or encrypted at rest, are masked: longer than 8 characters shows the first and last 4 characters around `****`, otherwise `****`. Omitted when empty."
           },
           "url": {
             "type": "string",
@@ -6743,15 +7230,15 @@
             "additionalProperties": {
               "type": "string"
             },
-            "description": "HTTP headers (sse / streamable-http). Secret values are masked."
+            "description": "HTTP headers (`sse` / `streamable-http` transport), masked by the same rule as `env`. Omitted when empty."
           },
           "proxy_url": {
             "type": "string",
-            "description": "Outbound proxy URL used to reach the server."
+            "description": "Outbound proxy URL used to reach the server. Not settable through the public API; omitted when empty."
           },
           "status": {
             "type": "string",
-            "description": "Server status.",
+            "description": "Whether the server's tools are offered to AI SRE sessions:\n- `enabled`: available (default on create).\n- `disabled`: kept but not offered; re-enable with `POST /safari/mcp/server/enable`.",
             "enum": [
               "enabled",
               "disabled"
@@ -6759,11 +7246,11 @@
           },
           "connect_timeout": {
             "type": "integer",
-            "description": "Connection timeout in seconds (0 = server default, 10s)."
+            "description": "Connection timeout in seconds as stored; `0` means the 10-second default is used."
           },
           "call_timeout": {
             "type": "integer",
-            "description": "Tool-call timeout in seconds (0 = server default, 60s)."
+            "description": "Tool-call timeout in seconds as stored; `0` means the 60-second default is used."
           },
           "allow_insecure_oauth_http": {
             "type": "boolean",
@@ -6775,7 +7262,7 @@
           },
           "auth_mode": {
             "type": "string",
-            "description": "Authentication mode. One of: `shared` (a single static credential saved on the resource and shared by all callers in the account; the default — an empty value behaves the same), `per_user_secret` (each user stores their own secret per `secret_schema`, injected per user at runtime), `per_user_oauth` (each user completes their own OAuth grant; discovery and registration run lazily on first use).",
+            "description": "Who supplies the credential; omitted when empty, which behaves like `shared`:\n- `shared`: one credential stored on the server (`env` / `headers`) is used for every caller.\n- `per_user_secret`: each user stores their own secret, sent in the header named by `secret_schema.header_name`.\n- `per_user_oauth`: each user completes their own OAuth authorization; discovery and client registration run on first use.",
             "enum": [
               "shared",
               "per_user_secret",
@@ -6792,7 +7279,16 @@
           },
           "source_template_name": {
             "type": "string",
-            "description": "Marketplace template this connector was installed from; empty for user-authored."
+            "description": "Marketplace template this server was installed from; omitted for servers created by hand."
+          },
+          "test_error": {
+            "type": "string",
+            "description": "Error message from the last connection test; omitted when the last test succeeded or the server was never tested."
+          },
+          "tested_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Time of the last connection test, Unix timestamp in milliseconds; omitted if the server was never tested."
           },
           "created_by": {
             "type": "integer",
@@ -6833,12 +7329,12 @@
         "properties": {
           "p": {
             "type": "integer",
-            "description": "Page number, 1-based.",
+            "description": "Page number, 1-based; values below 1 are treated as 1.",
             "default": 1
           },
           "limit": {
             "type": "integer",
-            "description": "Page size.",
+            "description": "Page size; values below 1 fall back to 20. No upper bound is enforced.",
             "default": 20
           },
           "scope": {
@@ -6848,7 +7344,8 @@
               "all",
               "account",
               "team"
-            ]
+            ],
+            "default": "all"
           },
           "query": {
             "type": "string",
@@ -6861,14 +7358,14 @@
               "type": "integer",
               "format": "int64"
             },
-            "description": "Filter to these team IDs; empty = the caller's visible set."
+            "description": "Restrict to these team IDs. IDs of teams the caller does not belong to are ignored; empty means all of the caller's teams."
           },
           "include_account": {
             "type": [
               "boolean",
               "null"
             ],
-            "description": "Include account-scoped (team_id=0) rows. Defaults to true."
+            "description": "Include account-scoped (`team_id=0`) rows. Defaults to `true`; ignored when `scope` is `account` (always included) or `team` (never included)."
           }
         }
       },
@@ -6938,7 +7435,7 @@
           },
           "command": {
             "type": "string",
-            "description": "Executable command (stdio transport)."
+            "description": "New executable command (`stdio` transport); omitted or empty leaves it unchanged."
           },
           "args": {
             "type": "array",
@@ -6952,11 +7449,11 @@
             "additionalProperties": {
               "type": "string"
             },
-            "description": "Environment variables (`stdio` transport); replaces the whole map, but a sensitive key sent back masked or as an empty string keeps its stored value; omit to leave unchanged."
+            "description": "Environment variables (`stdio` transport); replaces the whole map, so keys left out are removed. For a protected key (see the masking rule on get), sending the masked value or an empty string keeps the stored value. Omit to leave unchanged."
           },
           "url": {
             "type": "string",
-            "description": "Server URL (sse / streamable-http transport)."
+            "description": "New server URL (`sse` / `streamable-http` transport); omitted or empty leaves it unchanged. A real change also clears `oauth_metadata` unless a new one is sent."
           },
           "headers": {
             "type": "object",
@@ -6967,30 +7464,35 @@
           },
           "connect_timeout": {
             "type": "integer",
-            "description": "Connection timeout in seconds. 0 = default (10s)."
+            "description": "New connection timeout in seconds; omitted or `0` leaves it unchanged (a stored `0` means the 10-second default)."
           },
           "call_timeout": {
             "type": "integer",
-            "description": "Tool-call timeout in seconds. 0 = default (60s)."
+            "description": "New tool-call timeout in seconds; omitted or `0` leaves it unchanged (a stored `0` means the 60-second default)."
           },
           "auth_mode": {
             "type": "string",
-            "description": "Authentication mode: shared (default), per_user_secret, or per_user_oauth."
+            "description": "New auth mode; omitted or empty leaves it unchanged. Who supplies the credential:\n- `shared` (default; an empty value behaves the same): one credential stored on the server (`env` / `headers`) is used for every caller.\n- `per_user_secret`: each user stores their own secret, sent in the header named by `secret_schema.header_name`.\n- `per_user_oauth`: each user completes their own OAuth authorization; discovery and client registration run on first use.\n\n`per_user_secret` requires `secret_schema` with a non-empty `header_name`; any other value returns `InvalidParameter`.",
+            "enum": [
+              "shared",
+              "per_user_secret",
+              "per_user_oauth"
+            ]
           },
           "secret_schema": {
             "type": "string",
-            "description": "JSON secret schema; required when auth_mode=per_user_secret."
+            "description": "New JSON secret schema, e.g. `{\"header_name\":\"X-Api-Key\"}`. Applied only together with a non-empty `auth_mode`; sent alone it is ignored."
           },
           "oauth_metadata": {
             "type": "string",
-            "description": "JSON OAuth metadata; reserved for per_user_oauth."
+            "description": "New JSON OAuth metadata. A non-empty value is stored as sent. When omitted or empty, the stored value is kept unless `auth_mode` or `url` changes, in which case it is cleared."
           },
           "team_id": {
             "type": [
               "integer",
               "null"
             ],
-            "description": "Reassign team scope: 0 = account-wide; >0 = team. Omit to leave unchanged.",
+            "description": "Reassign team scope: `0` = account-wide (account owner or admin only); `>0` = a team the caller belongs to. Servers installed from the marketplace can only move to `0`. Omit to leave unchanged.",
             "format": "int64"
           },
           "environments": {
@@ -7096,7 +7598,7 @@
         "properties": {
           "ok": {
             "type": "boolean",
-            "description": "Whether all readiness checks passed. Always true in a response that reaches the caller — a failed preflight returns a 400/403 error instead of a payload with ok=false."
+            "description": "Whether all readiness checks passed. Always `true` in a 200 response; a failed preflight returns an error instead."
           },
           "checks": {
             "type": "array",
@@ -7132,7 +7634,7 @@
             "items": {
               "type": "string"
             },
-            "description": "Non-fatal warnings surfaced during preflight. Omitted or empty when there are none."
+            "description": "Non-fatal warnings from preflight. Currently never populated, so the field is omitted."
           }
         },
         "required": [
@@ -7157,7 +7659,7 @@
             "$ref": "#/components/schemas/DutyError"
           },
           "data": {
-            "description": "Endpoint-specific payload. See each operation's 200 response schema."
+            "description": "Operation-specific payload, documented in each operation's 200 response. Operations without a payload return `{}` or omit `data` entirely."
           }
         },
         "required": [
@@ -7243,7 +7745,7 @@
             "items": {
               "$ref": "#/components/schemas/EventItem"
             },
-            "description": "Recent events, ascending by (created_at, event_id)."
+            "description": "The newest page of events (older pages via `search_after_ctx`), ascending by (`created_at`, `event_id`). Internal control events are excluded. Always an array."
           },
           "has_more_older": {
             "type": "boolean",
@@ -7253,10 +7755,6 @@
             "type": "string",
             "description": "Opaque keyset cursor; pass back as search_after_ctx to fetch the next older page. Omitted when has_more_older is false."
           },
-          "suggest_init": {
-            "type": "boolean",
-            "description": "Account-wide onboarding flag: true when the account has no knowledge in any scope; not specific to this session."
-          },
           "pending_messages": {
             "type": "array",
             "items": {
@@ -7269,7 +7767,6 @@
           "session",
           "events",
           "has_more_older",
-          "suggest_init",
           "pending_messages"
         ]
       },
@@ -7295,22 +7792,25 @@
           },
           "entry_kind": {
             "type": "string",
-            "description": "Surface that created the session. One of:\n| Value | Meaning |\n| --- | --- |\n| `web` | Created from the web console |\n| `im` | Created from an IM client (IM bot / IM H5) |\n| `api` | Created via the public API |\n| `automation` | Created by an automation rule (unattended run) |\n| `subagent` | Child session spawned by a parent's agent_dispatch (audit label; at runtime it executes on the web tool surface) |",
+            "description": "Surface that created the session:\n- `web`: web console (also returned for subagent child sessions and for sessions that predate this field)\n- `im`: IM bot or IM H5 client\n- `api`: public API\n- `automation`: automation rule (unattended run)",
             "enum": [
               "web",
               "im",
               "api",
-              "automation",
-              "subagent"
+              "automation"
             ]
           },
           "person_id": {
             "type": "string",
             "description": "Creator person id."
           },
+          "ref": {
+            "type": "string",
+            "description": "Business object the session is about, as a prefixed reference (for example an incident reference). Omitted when the session is not bound to one."
+          },
           "creator_name": {
             "type": "string",
-            "description": "Display name of the session creator, resolved when the response is rendered. Omitted when the member lookup fails."
+            "description": "Display name of the session creator. Returned by `POST /safari/session/list` only; omitted when the name lookup fails."
           },
           "team_id": {
             "type": "integer",
@@ -7321,13 +7821,49 @@
             "type": "string",
             "description": "Resolved team name; empty for unbound rows or deleted teams."
           },
+          "automation": {
+            "type": "object",
+            "description": "Automation rule that produced this session. Returned by `POST /safari/session/get` only, for sessions started by an automation rule.",
+            "properties": {
+              "rule_id": {
+                "type": "string",
+                "description": "ID of the automation rule."
+              },
+              "rule_name": {
+                "type": "string",
+                "description": "Rule name; empty when the rule has since been deleted."
+              },
+              "trigger_kind": {
+                "type": "string",
+                "enum": [
+                  "schedule",
+                  "manual",
+                  "http_post",
+                  "oncall_incident",
+                  "war_room_created",
+                  ""
+                ],
+                "description": "How this run was triggered:\n- `schedule`: the rule's schedule fired\n- `manual`: run on demand (console or `POST /safari/automation/rule/run`)\n- `http_post`: the rule's HTTP trigger URL was called\n- `oncall_incident`: an On-call incident event matched the rule\n- `war_room_created`: a war room was created\n- `\"\"`: the run record no longer exists"
+              },
+              "can_edit": {
+                "type": "boolean",
+                "description": "True when the caller may open and manage the rule; false when the rule has been deleted."
+              }
+            },
+            "required": [
+              "rule_id",
+              "rule_name",
+              "trigger_kind",
+              "can_edit"
+            ]
+          },
           "is_mine": {
             "type": "boolean",
             "description": "True when the caller created this session."
           },
           "can_view": {
             "type": "boolean",
-            "description": "True when the caller can view this session."
+            "description": "True when the caller can read this session: always true for the creator, team members, and other members of the same account on a team session; true through a valid share link otherwise."
           },
           "can_continue": {
             "type": "boolean",
@@ -7335,7 +7871,7 @@
           },
           "can_manage": {
             "type": "boolean",
-            "description": "True when the caller may rename/archive/delete the session; personal sessions are creator-only, team sessions allow the creator, account admin, or team member."
+            "description": "True when the caller may rename, archive, or delete the session: the creator of a personal session, or the creator or a member of the owning team for a team session. Account owners and admins get no exemption."
           },
           "can_fork": {
             "type": "boolean",
@@ -7343,7 +7879,7 @@
           },
           "access_source": {
             "type": "string",
-            "description": "How the caller received access to this session. Omitted when no access source is resolved. One of:\n| Value | Meaning |\n| --- | --- |\n| `owner` | Caller is the session creator (full access) |\n| `team_member` | Caller belongs to the session's bound team (full access) |\n| `manager` | Manager grant (reserved; never produced by the current version) |\n| `share_link` | Granted via a valid share link (view/fork only; cannot continue or manage) |\n| `participant` | Same-account non-member granted via a participable team session (view/continue/fork only) |",
+            "description": "How the caller obtained access. Omitted when the caller has no access. One of:\n| Value | Meaning |\n| --- | --- |\n| `owner` | Caller created the session (full access) |\n| `team_member` | Caller belongs to the session's team (full access) |\n| `manager` | Reserved; not produced by the current version |\n| `share_link` | Granted by a valid share link (view and fork only; view only for subagent child sessions) |\n| `participant` | Another member of the same account on a team session (view, continue, fork; no manage) |",
             "enum": [
               "owner",
               "team_member",
@@ -7373,10 +7909,9 @@
           },
           "status": {
             "type": "string",
-            "description": "Lifecycle status. One of: `enabled` (active), `deleted` (soft-deleted, no longer accessible).",
+            "description": "Lifecycle status. Always `enabled` in responses: deleted sessions are never returned.",
             "enum": [
-              "enabled",
-              "deleted"
+              "enabled"
             ]
           },
           "incognito": {
@@ -7400,7 +7935,7 @@
           "state": {
             "type": "object",
             "additionalProperties": true,
-            "description": "Raw session-state bag (session-scoped keys). Omitted when empty."
+            "description": "Raw session-state key/value map. Returned by `POST /safari/session/get` only; omitted when empty."
           },
           "bound_environment": {
             "$ref": "#/components/schemas/EnvironmentBinding"
@@ -7419,7 +7954,7 @@
           "context_window": {
             "type": "integer",
             "format": "int64",
-            "description": "The bound model's max context size in tokens. 0 means unknown."
+            "description": "Maximum context size of the session's model, in tokens. Computed by `POST /safari/session/get` only; always 0 in list responses and when the lookup fails."
           },
           "archived_at": {
             "type": "integer",
@@ -7429,12 +7964,12 @@
           "pinned_at": {
             "type": "integer",
             "format": "int64",
-            "description": "Caller's per-user pin time as a Unix timestamp in milliseconds; 0 means not pinned."
+            "description": "When the caller pinned this session, as a Unix timestamp in milliseconds; 0 when not pinned. Pins are per user. Filled by `POST /safari/session/list` only; always 0 in `POST /safari/session/get`."
           },
           "last_event_at": {
             "type": "integer",
             "format": "int64",
-            "description": "Unix timestamp in milliseconds of the most recent assistant-side event."
+            "description": "Unix timestamp in milliseconds of the latest assistant-side event; user messages alone do not advance it. Omitted when 0."
           },
           "is_running": {
             "type": "boolean",
@@ -7442,15 +7977,15 @@
           },
           "standing_tasks": {
             "type": "integer",
-            "description": "Number of process-type tasks (background shell or monitor) still alive when the response was rendered."
+            "description": "Number of the session's process-type tasks (background shell commands or monitors) still alive when the response was built; 0 when none or when the count cannot be read."
           },
           "has_unread": {
             "type": "boolean",
-            "description": "True when there is assistant output the caller has not yet viewed."
+            "description": "True when assistant output exists that the caller has not viewed yet; always false while `is_running` is true. Computed by `POST /safari/session/list` only; always false in `POST /safari/session/get`."
           },
           "has_open_tasks": {
             "type": "boolean",
-            "description": "Whether the session still has open tasks, used to tell a handed-off turn from a settled session. Best-effort: when the read fails the field is absent (`omitempty`), which callers must treat as \"unknown\", never as proof the session is idle."
+            "description": "True when the session still has open tasks (for example running subagents or background processes), which tells a handed-off turn apart from a settled session. Returned by `POST /safari/session/get` only; omitted when false or when the lookup fails, so treat absence as unknown rather than idle."
           },
           "current_turn_started_at": {
             "type": "integer",
@@ -7477,6 +8012,7 @@
           "session_id",
           "session_name",
           "app_name",
+          "entry_kind",
           "person_id",
           "team_id",
           "is_mine",
@@ -7511,7 +8047,7 @@
         "properties": {
           "app_name": {
             "type": "string",
-            "description": "Agent app whose sessions to list. One of:\n| Value | Meaning |\n| --- | --- |\n| `ask-ai` | Ask AI assistant |\n| `support` | Customer-support agent |\n| `support-website` | Website support agent (exposed over A2A, not built into the console) |\n| `support-flashcat` | Flashcat-site support agent (exposed over A2A) |\n| `ai-sre` | The AI SRE main app |\n| `template-assistant` | Notification-template assistant (template editing/validation) |\n| `swe` | Internal benchmarking app (not customer-facing) |",
+            "description": "Agent app whose sessions to list. One of:\n| Value | Meaning |\n| --- | --- |\n| `ask-ai` | Ask AI assistant |\n| `support` | Customer-support agent |\n| `support-website` | Website support agent (exposed over A2A, not built into the console) |\n| `support-flashcat` | Flashcat-site support agent (exposed over A2A) |\n| `ai-sre` | The AI SRE main app |\n| `template-assistant` | Notification-template assistant (template editing/validation) |\n| `query-assistant` | Monitors query-writing assistant |\n| `swe` | Software-engineering agent app (not offered in the console) |",
             "enum": [
               "ask-ai",
               "support",
@@ -7519,6 +8055,7 @@
               "support-flashcat",
               "ai-sre",
               "template-assistant",
+              "query-assistant",
               "swe"
             ]
           },
@@ -7549,16 +8086,16 @@
           },
           "include_subagent_sessions": {
             "type": "boolean",
-            "description": "Include subagent-dispatched sessions in the list."
+            "description": "When true, also list child sessions spawned by subagent dispatch. Defaults to false (top-level sessions only)."
           },
           "keyword": {
             "type": "string",
-            "description": "Filter by session-name keyword.",
+            "description": "Return only sessions whose `session_name` contains this text; leading and trailing spaces are ignored.",
             "maxLength": 64
           },
           "scope": {
             "type": "string",
-            "description": "Visibility scope: `all` (own personal + accessible team sessions), `personal`, or `team`; default `all`.",
+            "description": "Visibility scope:\n- `all` (default): sessions the caller created plus sessions bound to teams the caller belongs to\n- `personal`: the caller's own sessions with no team (`team_id` = 0)\n- `team`: sessions bound to teams the caller belongs to; empty when the caller is in no team",
             "enum": [
               "all",
               "personal",
@@ -7592,11 +8129,11 @@
                 "automation"
               ]
             },
-            "description": "Restrict to sessions produced by these surfaces; empty returns every kind."
+            "description": "Restrict to sessions created from these surfaces: `web` (console), `im` (IM bot or IM H5), `api` (public API), `automation` (automation rule). Empty returns every kind."
           },
           "status": {
             "type": "string",
-            "description": "Archive bucket: active (default) returns un-archived, archived returns archived, all returns both.",
+            "description": "Archive filter:\n- `active` (default): sessions that are not archived\n- `archived`: archived sessions only\n- `all`: both",
             "enum": [
               "active",
               "archived",
@@ -7615,24 +8152,19 @@
           "total": {
             "type": "integer",
             "format": "int64",
-            "description": "Total number of sessions matching the filter (ignoring pagination)."
+            "description": "Number of matching sessions, ignoring pagination. Pinned sessions prepended on page 1 are not counted."
           },
           "sessions": {
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/SessionItem"
             },
-            "description": "The page of sessions."
-          },
-          "suggest_init": {
-            "type": "boolean",
-            "description": "Account-wide onboarding flag: true when the account has no knowledge in any scope; not dependent on this call's filters."
+            "description": "The page of sessions: on page 1, the caller's matching pinned sessions (newest pin first) followed by up to `limit` other sessions in the requested order."
           }
         },
         "required": [
           "total",
-          "sessions",
-          "suggest_init"
+          "sessions"
         ]
       },
       "SessionTokenUsage": {
@@ -7756,9 +8288,13 @@
           "venues": {
             "type": "array",
             "items": {
-              "type": "string"
+              "type": "string",
+              "enum": [
+                "cloud",
+                "byoc"
+              ]
             },
-            "description": "Execution-environment kinds (EnvironmentKind strings, e.g. `byoc`) the skill is restricted to. Omitted when empty, which means the skill is available in all venues."
+            "description": "Execution environments the skill is restricted to: `cloud` (managed sandbox) and/or `byoc` (self-hosted runner). Omitted when empty, which means every environment."
           },
           "s3_key": {
             "type": "string",
@@ -7770,7 +8306,7 @@
           },
           "status": {
             "type": "string",
-            "description": "Skill status. Deleted skills are excluded from every API response, so only these two values are ever returned.",
+            "description": "Skill status: `enabled` (agents load it) or `disabled` (kept but not loaded). Deleted skills never appear in responses.",
             "enum": [
               "enabled",
               "disabled"
@@ -7793,7 +8329,7 @@
           },
           "can_edit": {
             "type": "boolean",
-            "description": "Whether the caller may edit this skill."
+            "description": "True when the caller may change this skill: account owners and admins for account-scope skills, team members for team skills."
           },
           "source_template_name": {
             "type": "string",
@@ -7805,15 +8341,36 @@
           },
           "update_available": {
             "type": "boolean",
-            "description": "True when the marketplace has a newer template version."
+            "description": "True when the marketplace template this skill was installed from has a newer version. Computed by `POST /safari/skill/list` only; always false in other responses."
           },
           "is_modified": {
             "type": "boolean",
-            "description": "True when a marketplace-sourced skill was edited locally (auto-update skips it)."
+            "description": "True when a marketplace-installed skill was changed locally (for example by uploading a new archive); automatic marketplace updates skip it."
           },
           "created": {
             "type": "boolean",
-            "description": "Set only on install-from-session responses: true = fresh install, false = in-place update."
+            "description": "Not returned by these endpoints; it is set only by the install-from-session flow."
+          },
+          "examples": {
+            "type": "array",
+            "description": "Example prompts declared in the SKILL.md frontmatter (up to 10), shown as suggested questions. Omitted when none.",
+            "items": {
+              "type": "object",
+              "properties": {
+                "zh": {
+                  "type": "string",
+                  "description": "Chinese prompt text."
+                },
+                "en": {
+                  "type": "string",
+                  "description": "English prompt text."
+                }
+              },
+              "required": [
+                "zh",
+                "en"
+              ]
+            }
           }
         },
         "required": [
@@ -7837,17 +8394,17 @@
         "properties": {
           "p": {
             "type": "integer",
-            "description": "Page number, 1-based.",
+            "description": "Page number, 1-based; values below 1 fall back to 1.",
             "default": 1
           },
           "limit": {
             "type": "integer",
-            "description": "Page size.",
+            "description": "Page size; values below 1 fall back to 20.",
             "default": 20
           },
           "scope": {
             "type": "string",
-            "description": "Restrict results to `all` (default), `account`-only (team_id=0), or `team`-only (excludes account-scoped rows). Overrides `include_account` when set.",
+            "description": "Which skills to return; overrides `include_account` when set:\n- `all` (default): account-scope skills (unless `include_account` is false) plus the caller's team skills\n- `account`: account-scope skills only (`team_id` = 0)\n- `team`: the caller's team skills only",
             "enum": [
               "all",
               "account",
@@ -7865,7 +8422,7 @@
               "type": "integer",
               "format": "int64"
             },
-            "description": "Filter to these team IDs; empty = the caller's visible set."
+            "description": "Limit team-scope results to these team IDs; IDs of teams the caller does not belong to are dropped. Empty = all of the caller's teams."
           },
           "include_account": {
             "type": [
@@ -7952,20 +8509,20 @@
           "file": {
             "type": "string",
             "format": "binary",
-            "description": "Skill archive (.skill / .zip / .tar.gz / .tgz). Max 100MB; oversized files are rejected before the body is read."
+            "description": "Skill archive (`.skill`, `.zip`, `.tar.gz`, or `.tgz`), up to 100 MB, containing `SKILL.md` at its root or inside a single top-level folder."
           },
           "team_id": {
             "type": "integer",
-            "description": "Team scope for the created/upserted skill: 0 = account-wide. Ignored when replacing a specific skill via `skill_id`.",
+            "description": "Scope for the created or overwritten-by-name skill: 0 = account scope (default), >0 = that team. Ignored when `replace=true` and `skill_id` are both set.",
             "format": "int64"
           },
           "replace": {
             "type": "boolean",
-            "description": "When true, overwrite an existing skill instead of failing on a name collision — matched by `skill_id` if provided, otherwise by skill name."
+            "description": "When true, overwrite an existing skill instead of failing on a name clash: the skill given by `skill_id`, or else the same-named skill in `team_id`. Accepts `true`, `1`, `yes`, `on` (case-insensitive); anything else is false."
           },
           "skill_id": {
             "type": "string",
-            "description": "Existing skill ID to target when replacing a specific skill (requires `replace=true`)."
+            "description": "ID of the skill to overwrite, from `POST /safari/skill/list`. Used only together with `replace=true`; ignored otherwise."
           }
         },
         "required": [
@@ -7987,7 +8544,7 @@
           },
           "scope": {
             "type": "string",
-            "description": "Knowledge scope. `channel` is a legacy scope; new knowledge is `account` or `team` scope.",
+            "description": "Knowledge scope.\n- `account`: account-level knowledge shared by the whole account; `scope_id` is the account ID.\n- `team`: knowledge owned by one team; `scope_id` is the team ID.\n- `channel`: legacy scope. It cannot be created or moved into through this API and is never returned by `POST /safari/knowledge/pack/list`; it can only appear when such knowledge is addressed directly by `pack_id`.",
             "enum": [
               "account",
               "team",
@@ -8005,24 +8562,24 @@
           },
           "file_count": {
             "type": "integer",
-            "description": "Number of files in the knowledge."
+            "description": "Number of files currently in the knowledge."
           },
           "total_bytes": {
             "type": "integer",
-            "description": "Total size of all files in bytes.",
+            "description": "Total size of all files in bytes. Capped at 5 MiB per knowledge.",
             "format": "int64"
           },
           "version": {
             "type": "integer",
-            "description": "Knowledge version, incremented on every file change."
+            "description": "Knowledge version. Starts at 0 and increases by 1 on every file write or file deletion. Moving the knowledge to another scope does not change it."
           },
           "duty_version": {
             "type": "integer",
-            "description": "Knowledge version at which DUTY.md was last authored or re-affirmed. When `version` is greater, DUTY.md no longer reflects every file in the knowledge."
+            "description": "The `version` at which `DUTY.md` was last written. Writing `DUTY.md` sets it to the new `version`; when `version` is greater, files were added, changed or deleted after `DUTY.md` was last updated, so `DUTY.md` may no longer index every file."
           },
           "created_by": {
             "type": "integer",
-            "description": "Person ID of the member who created the knowledge.",
+            "description": "Person ID of the member whose request created the knowledge. Account knowledge is created automatically by the first request that needs it, so this can be any member of the account.",
             "format": "int64"
           },
           "created_at_ms": {
@@ -8037,7 +8594,7 @@
           },
           "can_edit": {
             "type": "boolean",
-            "description": "Whether the caller can edit this knowledge."
+            "description": "Whether the caller can change this knowledge and its files: for `account` scope, `true` only for the account owner and admins; for `team` scope, `true` only when the caller is a member of that team (owners and admins are not exempt)."
           }
         },
         "required": [
@@ -8069,11 +8626,11 @@
           },
           "rel_path": {
             "type": "string",
-            "description": "Path relative to the knowledge root, e.g. `runbooks/restart.md`."
+            "description": "Path relative to the knowledge root, using `/` separators, e.g. `runbooks/restart.md`. Unique within the knowledge."
           },
           "content_type": {
             "type": "string",
-            "description": "MIME type; inferred from the file extension when not set on upload."
+            "description": "MIME type stored with the file. Open set: when `content_type` is omitted on write it is derived from the extension of `rel_path` — `.md` → `text/markdown`, `.yaml`/`.yml` → `text/yaml`, `.json` → `application/json`, `.sh` → `text/x-sh`, anything else → `text/plain`; a value passed explicitly is stored as given."
           },
           "size_bytes": {
             "type": "integer",
@@ -8120,11 +8677,11 @@
           },
           "ref": {
             "type": "string",
-            "description": "Single reference related to the warning."
+            "description": "Set only for `unresolved_reference`: the referenced path that does not exist in the knowledge."
           },
           "refs": {
             "type": "array",
-            "description": "Multiple references related to the warning.",
+            "description": "Set only for `still_referenced_by`: `rel_path` of every other file that still references the deleted file.",
             "items": {
               "type": "string"
             }
@@ -8145,15 +8702,15 @@
         "properties": {
           "p": {
             "type": "integer",
-            "description": "Page number, 1-based; returns all results when both `p` and `limit` are unset."
+            "description": "Page number, 1-based. When both `p` and `limit` are omitted (or ≤ 0), all matching knowledge is returned without paging; when only `limit` is set, `p` defaults to 1."
           },
           "limit": {
             "type": "integer",
-            "description": "Page size."
+            "description": "Page size. Defaults to 20 when `p` is set and `limit` is omitted; no upper bound is enforced."
           },
           "scope": {
             "type": "string",
-            "description": "Restrict to one scope; `all` (default) overrides `include_account`. One of: `all` (account scope plus visible team scopes), `account` (account-level knowledge only), `team` (team-level knowledge only, can be combined with `team_ids`).",
+            "description": "Which scopes to return:\n- `all` (default): account knowledge (unless `include_account` is `false`) plus the visible team knowledge.\n- `account`: only the account knowledge; `include_account` and `team_ids` are ignored.\n- `team`: only team knowledge, optionally narrowed by `team_ids`; `include_account` is ignored.",
             "enum": [
               "all",
               "account",
@@ -8162,12 +8719,12 @@
           },
           "query": {
             "type": "string",
-            "description": "Case-insensitive substring filter over knowledge ID, scope, scope ID/account ID, and team name.",
+            "description": "Case-insensitive substring filter over knowledge ID, scope, scope ID, account ID and team name. Account knowledge also matches `账户`/`账号` and team knowledge also matches `团队`. Leading and trailing spaces are ignored.",
             "maxLength": 128
           },
           "team_ids": {
             "type": "array",
-            "description": "Restrict to these team IDs; for non-admins the list is intersected with their own teams.",
+            "description": "Restrict team knowledge to these team IDs. IDs of teams the caller does not belong to are silently dropped — this applies to every caller, including owners and admins.",
             "items": {
               "type": "integer",
               "format": "int64"
@@ -8178,7 +8735,7 @@
               "boolean",
               "null"
             ],
-            "description": "Include the account-scope knowledge; defaults to true."
+            "description": "Whether to include the account knowledge when `scope` is `all` or omitted. Defaults to `true`."
           }
         }
       },
@@ -8188,7 +8745,7 @@
         "properties": {
           "scope": {
             "type": "string",
-            "description": "Scope of the knowledge to ensure. One of: `account` (account-level knowledge; scope_id is forced to the caller's account ID and only account admins may create it; first creation seeds a default DUTY.md), `team` (team-level knowledge; the `scope_id` team ID is required and the caller must belong to that team).",
+            "description": "Scope of the knowledge to ensure.\n- `account`: the account knowledge. `scope_id` is replaced by the caller's account ID; only the account owner and admins may call this, even when the knowledge already exists. If the knowledge has no `DUTY.md`, a default one is written.\n- `team`: the knowledge of the team in `scope_id`. `scope_id` is required and the caller must be a member of that team.",
             "enum": [
               "account",
               "team"
@@ -8196,7 +8753,7 @@
           },
           "scope_id": {
             "type": "integer",
-            "description": "Team ID; required for `team` scope, ignored for `account` scope.",
+            "description": "Team ID. Required (non-zero) for `team` scope, otherwise the request fails with `InvalidParameter`; ignored for `account` scope.",
             "format": "int64"
           }
         },
@@ -8217,7 +8774,7 @@
               "string",
               "null"
             ],
-            "description": "Destination scope; omit for a no-op that returns the current knowledge.",
+            "description": "Destination scope. Omit to leave the knowledge unchanged and get it back.\n- `account`: make it the account knowledge (only the account owner and admins).\n- `team`: move it to the team in `scope_id` (the caller must be a member of that team).\nAny other value returns `InvalidParameter`. If the destination already has knowledge, the request fails with `ReferenceExist`.",
             "enum": [
               "account",
               "team"
@@ -8228,7 +8785,7 @@
               "integer",
               "null"
             ],
-            "description": "Destination team ID; required when `scope` is `team`, set automatically for `account`.",
+            "description": "Destination team ID. Required (non-zero) when `scope` is `team`; ignored when `scope` is `account` (the account ID is used).",
             "format": "int64"
           }
         },
@@ -8255,7 +8812,7 @@
         "properties": {
           "ok": {
             "type": "boolean",
-            "description": "True when the knowledge was deleted."
+            "description": "Always `true` on success; a failed delete returns an error instead."
           }
         },
         "required": [
@@ -8290,7 +8847,7 @@
           },
           "rel_path": {
             "type": "string",
-            "description": "Path of the file relative to the knowledge root."
+            "description": "Path of the file relative to the knowledge root. If no file exists at this path, the call still succeeds with `file` set to `null` and an empty `content_b64`."
           }
         },
         "required": [
@@ -8307,15 +8864,21 @@
           },
           "rel_path": {
             "type": "string",
-            "description": "Destination path relative to the knowledge root; existing files are overwritten."
+            "description": "Destination path relative to the knowledge root; an existing file at this path is overwritten. Must use `/` separators, must not start with `/`, must already be in normalized form, and no segment may be empty, `.`, `..`, or start with `.` (dotfiles are rejected)."
           },
           "content_b64": {
             "type": "string",
-            "description": "Base64-encoded file content; must decode to valid UTF-8 text (binary is rejected). Per-file limit 1 MiB."
+            "description": "Base64-encoded (standard alphabet) file content. The decoded bytes must be UTF-8 text with no NUL bytes and at most 1 MiB (`DUTY.md`: at most 32 KiB). Omit or send an empty string to write an empty file."
           },
           "content_type": {
             "type": "string",
-            "description": "MIME type; inferred from the file extension when omitted."
+            "description": "MIME type to store with the file. Optional: when omitted it is derived from the extension of `rel_path` (`.md` → `text/markdown`, `.yaml`/`.yml` → `text/yaml`, `.json` → `application/json`, `.sh` → `text/x-sh`, otherwise `text/plain`). Any value passed is stored as given."
+          },
+          "expected_version": {
+            "type": "integer",
+            "minimum": 0,
+            "default": 0,
+            "description": "Optimistic-concurrency guard. `0` or omitted: write unconditionally. A positive value: write only if the knowledge's current `version` equals it; otherwise nothing is written and the call returns HTTP 200 with `status` = `conflict` and the current `version`."
           }
         },
         "required": [
@@ -8366,7 +8929,7 @@
       },
       "KnowledgeFileListResponse": {
         "type": "object",
-        "description": "Files in the knowledge.",
+        "description": "All files in the knowledge plus the current knowledge version.",
         "properties": {
           "files": {
             "type": "array",
@@ -8377,49 +8940,85 @@
           },
           "total": {
             "type": "integer",
-            "description": "Total number of files in the knowledge.",
+            "description": "Number of files in `files` — always the full file count of the knowledge, since this endpoint does not paginate.",
             "format": "int64"
+          },
+          "version": {
+            "type": "integer",
+            "description": "Current `version` of the knowledge; usable as `expected_version` for file writes."
           }
         },
         "required": [
           "files",
-          "total"
+          "total",
+          "version"
         ]
       },
       "KnowledgeFileGetResponse": {
         "type": "object",
-        "description": "File metadata plus its base64-encoded content.",
+        "description": "File metadata, its base64-encoded content, and the current knowledge version.",
         "properties": {
           "file": {
-            "$ref": "#/components/schemas/KnowledgeFileItem"
+            "description": "Metadata of the file; `null` when no file exists at `rel_path`.",
+            "oneOf": [
+              {
+                "$ref": "#/components/schemas/KnowledgeFileItem"
+              },
+              {
+                "type": "null"
+              }
+            ]
           },
           "content_b64": {
             "type": "string",
-            "description": "Base64-encoded file content; decodes to UTF-8 text."
+            "description": "Base64-encoded file content. Empty string when the file does not exist (or is empty)."
+          },
+          "version": {
+            "type": "integer",
+            "description": "Current `version` of the knowledge. Pass it as `expected_version` to `POST /safari/knowledge/file/put` or `POST /safari/knowledge/file/delete` to reject the write if someone else changed the knowledge in between."
           }
         },
         "required": [
           "file",
-          "content_b64"
+          "content_b64",
+          "version"
         ]
       },
       "KnowledgeFilePutResponse": {
         "type": "object",
-        "description": "The written file plus any non-blocking warnings.",
+        "description": "Write result. On success carries the written file; on a version conflict carries only `status`, `version` and `message`.",
         "properties": {
+          "status": {
+            "type": "string",
+            "enum": [
+              "ok",
+              "conflict"
+            ],
+            "description": "Outcome of the write.\n- `ok`: the change was committed.\n- `conflict`: `expected_version` did not match the current knowledge version, so nothing was changed; re-read the file and retry with the returned `version`."
+          },
           "file": {
-            "$ref": "#/components/schemas/KnowledgeFileItem"
+            "$ref": "#/components/schemas/KnowledgeFileItem",
+            "description": "The file as stored after the write. Omitted when `status` is `conflict`."
           },
           "warnings": {
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/KnowledgeWarning"
             },
-            "description": "Non-blocking warnings after a successful write; `code=unresolved_reference` means an @ref in the file content points to a file that does not exist in the knowledge. Absent when there are no warnings (omitempty)."
+            "description": "Non-blocking warnings; `unresolved_reference` means an @ref in the written content points to a path that does not exist in the knowledge. Omitted when there are no warnings."
+          },
+          "version": {
+            "type": "integer",
+            "description": "Knowledge `version` produced by this write when `status` is `ok`; the current version when `status` is `conflict`. Use it as `expected_version` for the next write."
+          },
+          "message": {
+            "type": "string",
+            "description": "Explanation of the conflict (`this knowledge was updated by someone else`). Present only when `status` is `conflict`."
           }
         },
         "required": [
-          "file"
+          "status",
+          "version"
         ]
       },
       "KnowledgeFileDeleteRequest": {
@@ -8432,11 +9031,17 @@
           },
           "rel_path": {
             "type": "string",
-            "description": "Path of the file relative to the knowledge root."
+            "description": "Path of the file relative to the knowledge root. Same path rules as `POST /safari/knowledge/file/put`."
           },
           "force": {
             "type": "boolean",
             "description": "Delete even when other knowledge files reference this file; the referrers are then returned as warnings instead of blocking the delete."
+          },
+          "expected_version": {
+            "type": "integer",
+            "minimum": 0,
+            "default": 0,
+            "description": "Optimistic-concurrency guard. `0` or omitted: delete unconditionally. A positive value: delete only if the knowledge's current `version` equals it; otherwise nothing is deleted and the call returns HTTP 200 with `status` = `conflict` and the current `version`."
           }
         },
         "required": [
@@ -8445,16 +9050,36 @@
       },
       "KnowledgeFileDeleteResponse": {
         "type": "object",
-        "description": "Deletion result; empty unless warnings were raised.",
+        "description": "Delete result.",
         "properties": {
+          "status": {
+            "type": "string",
+            "enum": [
+              "ok",
+              "conflict"
+            ],
+            "description": "Outcome of the delete.\n- `ok`: the file was deleted, or did not exist.\n- `conflict`: `expected_version` did not match the current knowledge version, so nothing was deleted."
+          },
           "warnings": {
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/KnowledgeWarning"
             },
-            "description": "Non-blocking warnings after deletion; `code=still_referenced_by` means the (force-)deleted file is still @ref-referenced by other files in the knowledge (`refs` lists the referrers). Absent when there are no warnings (omitempty)."
+            "description": "Non-blocking warnings; `still_referenced_by` means `force` deleted a file that other files still reference (`refs` lists them). Omitted when there are no warnings."
+          },
+          "version": {
+            "type": "integer",
+            "description": "Knowledge `version` after the delete (unchanged if the file did not exist). When the file did not exist and `expected_version` was not sent, this is `0`. On `conflict`, the current version."
+          },
+          "message": {
+            "type": "string",
+            "description": "Explanation of the conflict. Present only when `status` is `conflict`."
           }
-        }
+        },
+        "required": [
+          "status",
+          "version"
+        ]
       },
       "ArtifactIdRequest": {
         "type": "object",
@@ -8489,7 +9114,7 @@
               "type": "integer",
               "format": "int64"
             },
-            "description": "Restrict to artifacts owned by these team IDs, intersected with the caller's visibility — teams the caller does not belong to silently return nothing."
+            "description": "Restrict to artifacts owned by these team IDs, intersected with the `scope` filter. Non-positive IDs are ignored; teams the caller does not belong to return nothing, and personal artifacts are excluded whenever this is set."
           },
           "query": {
             "type": "string",
@@ -8498,14 +9123,12 @@
           "page": {
             "type": "integer",
             "default": 1,
-            "minimum": 1,
-            "description": "Page number, 1-based."
+            "description": "Page number, 1-based. Values below 1 are treated as 1."
           },
           "limit": {
             "type": "integer",
             "default": 20,
-            "maximum": 100,
-            "description": "Page size. Defaults to 20; capped at 100."
+            "description": "Number of artifacts per page. Values below 1 fall back to 20; values above 100 are capped at 100 (not rejected)."
           },
           "orderby": {
             "type": "string",
@@ -8513,7 +9136,7 @@
               "created_at",
               "updated_at"
             ],
-            "description": "Sort field: `created_at` or `updated_at`. Empty means `updated_at` descending."
+            "description": "Sort field: `created_at` (publish time) or `updated_at` (last change). Empty sorts by `updated_at` descending. In every case the caller's pinned artifacts come first, and `artifact_id` breaks ties."
           },
           "asc": {
             "type": "boolean",
@@ -8530,14 +9153,18 @@
             "items": {
               "$ref": "#/components/schemas/PublishedArtifactItem"
             },
-            "description": "Artifacts on this page."
+            "description": "Artifacts on this page; the caller's pinned artifacts come first. An empty array when nothing matches."
           },
           "total": {
             "type": "integer",
             "format": "int64",
             "description": "Total number of artifacts matching the filter across all pages."
           }
-        }
+        },
+        "required": [
+          "items",
+          "total"
+        ]
       },
       "PublishedArtifactItem": {
         "type": "object",
@@ -8554,7 +9181,7 @@
           "team_id": {
             "type": "integer",
             "format": "int64",
-            "description": "Owning team ID. `0` means a personal artifact (creator-only management); a positive value means team-owned."
+            "description": "Owning scope. `0` means a personal artifact: it appears only in its creator's list, and can be managed by the creator or by anyone who can manage the source session. A positive value is the owning team ID: the artifact appears in that team's members' lists and any team member can manage it. Set from the source session at first publish; change it with `/safari/artifact/gallery/update`."
           },
           "team_name": {
             "type": "string",
@@ -8563,7 +9190,7 @@
           "person_id": {
             "type": "integer",
             "format": "int64",
-            "description": "Person (member) ID of the creator."
+            "description": "Person ID of the artifact's creator: the owner of the source session at first publish. It never changes on republish or scope transfer."
           },
           "creator_name": {
             "type": "string",
@@ -8571,7 +9198,7 @@
           },
           "is_mine": {
             "type": "boolean",
-            "description": "Whether the caller is the creator."
+            "description": "`true` when the caller (for an `app_key` call, the key owner) is the creator, i.e. `person_id` equals the caller's person ID."
           },
           "can_edit": {
             "type": "boolean",
@@ -8591,7 +9218,7 @@
           },
           "name": {
             "type": "string",
-            "description": "Underlying file name including extension."
+            "description": "Underlying file name including extension. Empty when the underlying file record is missing."
           },
           "size": {
             "type": "integer",
@@ -8600,7 +9227,7 @@
           },
           "content_type": {
             "type": "string",
-            "description": "MIME type of the file."
+            "description": "MIME type, derived from the file-name extension when the file was produced: `text/html` (.html/.htm), `text/markdown` (.md), `text/plain` (.txt/.log), `text/csv`, `text/yaml` (.yaml/.yml), `text/x-python`, `text/x-go`, `text/x-sh`, `application/json`, `application/xml`, `application/pdf`, `image/png`, `image/jpeg`, `image/gif`, `image/svg+xml`, `image/webp`, `application/zip`, `application/gzip` (.tar/.gz/.tgz); any other extension is `application/octet-stream`. Empty when the underlying file record is missing."
           },
           "created_at": {
             "type": "integer",
@@ -8610,7 +9237,12 @@
           "updated_at": {
             "type": "integer",
             "format": "int64",
-            "description": "Unix timestamp in milliseconds when the artifact was last updated (rename, transfer, or republish)."
+            "description": "Unix timestamp in milliseconds of the last change to the artifact row (rename, transfer, republish, or share state change)."
+          },
+          "pinned_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Unix timestamp in milliseconds when the caller pinned this artifact in the console gallery. Pins are per member; omitted when the caller has not pinned it. Pinned artifacts are listed first by `/safari/artifact/gallery/list`."
           },
           "share_enabled": {
             "type": "boolean",
@@ -8623,7 +9255,7 @@
           "shared_by": {
             "type": "integer",
             "format": "int64",
-            "description": "Person ID of the member who enabled sharing. Present only while shared."
+            "description": "Person ID of the member who enabled sharing; a later snapshot sync does not change it. Present only while shared."
           },
           "shared_at": {
             "type": "integer",
@@ -8665,7 +9297,7 @@
               "string",
               "null"
             ],
-            "description": "New title. Trimmed; must be non-empty when provided. Omit to leave unchanged."
+            "description": "New title. Leading and trailing spaces are trimmed; a blank value fails with `InvalidParameter`. Omit or send `null` to keep the current title."
           },
           "team_id": {
             "type": [
@@ -8673,7 +9305,7 @@
               "null"
             ],
             "format": "int64",
-            "description": "Transfer target scope. `0` moves the artifact to personal scope (only the creator can manage it); a positive value moves it to a team the caller must belong to. Omit to leave unchanged."
+            "description": "Transfer target. `0` moves the artifact to personal scope and only its creator may do that; a positive value moves it to that team, and the caller must be a member of the team; a negative value fails with `InvalidParameter`. Omit or send `null` to keep the current scope. The creator (`person_id`) never changes."
           }
         },
         "required": [
@@ -8732,7 +9364,7 @@
             },
             "maxItems": 50,
             "minItems": 1,
-            "description": "Presented-file IDs (`pf_` prefix) to probe. At most 50 per call; duplicates and empty strings are ignored."
+            "description": "Presented-file IDs (`pf_` prefix) to check. At most 50 entries per call, counted before duplicates and empty strings are removed; more fails with `InvalidParameter`."
           }
         },
         "required": [
@@ -8741,11 +9373,11 @@
       },
       "ArtifactFileStateItem": {
         "type": "object",
-        "description": "Live publish state of one presented file. Returned only for files that have a live published artifact.",
+        "description": "Live gallery state of one presented file. Matched by the file's source session and workspace path, so an older version of a republished file also reports the current artifact.",
         "properties": {
           "file_id": {
             "type": "string",
-            "description": "Echoes the requested presented-file ID."
+            "description": "The requested presented-file ID this entry answers for."
           },
           "artifact_id": {
             "type": "string",
@@ -8776,7 +9408,7 @@
             "items": {
               "$ref": "#/components/schemas/ArtifactFileStateItem"
             },
-            "description": "One entry per requested file that has a live published artifact; files without one are omitted."
+            "description": "One entry per requested file whose session file path currently has a live gallery artifact; files without one, and unknown IDs, are omitted. An empty array when none match."
           }
         },
         "required": [
@@ -8797,12 +9429,12 @@
           },
           "public_url": {
             "type": "string",
-            "description": "Anonymous public link served entirely from CDN. Anyone with the link can view the content, no login required."
+            "description": "Anonymous public link, `<console origin>/share/artifact/<artifact_id>`. Anyone with the link can view the content without signing in. The link is the same on every enable."
           },
           "shared_by": {
             "type": "integer",
             "format": "int64",
-            "description": "Person ID of the member who enabled sharing."
+            "description": "Person ID of the member who enabled sharing. A snapshot sync keeps the original value."
           },
           "shared_at": {
             "type": "integer",
@@ -8849,7 +9481,7 @@
           },
           "expires_in": {
             "type": "integer",
-            "description": "Validity of both URLs in seconds (300)."
+            "description": "Validity of both URLs in seconds. Always `300`."
           },
           "name": {
             "type": "string",
@@ -8862,7 +9494,7 @@
           },
           "content_type": {
             "type": "string",
-            "description": "MIME type of the file."
+            "description": "MIME type, derived from the file-name extension when the file was produced: `text/html` (.html/.htm), `text/markdown` (.md), `text/plain` (.txt/.log), `text/csv`, `text/yaml` (.yaml/.yml), `text/x-python`, `text/x-go`, `text/x-sh`, `application/json`, `application/xml`, `application/pdf`, `image/png`, `image/jpeg`, `image/gif`, `image/svg+xml`, `image/webp`, `application/zip`, `application/gzip` (.tar/.gz/.tgz); any other extension is `application/octet-stream`."
           }
         },
         "required": [
diff --git a/api-reference/safari.openapi.zh.json b/api-reference/safari.openapi.zh.json
index c17d82529..2c2f283cc 100644
--- a/api-reference/safari.openapi.zh.json
+++ b/api-reference/safari.openapi.zh.json
@@ -59,7 +59,7 @@
           }
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **Agent 管理**（`ai-sre`） |\n\n## 使用说明\n\n- `instructions` 为必填项；已弃用的 `description` 字段仍保留以兼容旧客户端，若两者同时传入则必须与 `instructions` 完全一致。\n- `card_url` 必须是 host 非空的绝对 `http`/`https` URL（可达性由执行环境验证，此处不检查）；`auth_type` 仅接受 `none`、`api_key` 或 `bearer`。\n- `environments` 限定智能体可运行的环境：`cloud` 和/或 BYOC Runner 的环境 ID 列表；省略或为空表示所有环境，且每个 Runner 必须对调用者可见。\n- 创建到某个团队（`team_id > 0`）需要调用者真实属于该团队；只有账户 owner/admin 可以在账户级（`team_id=0`）创建。\n- 每次调用都会记录到账户审计日志。\n",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **Agent 管理**（`ai-sre`） |\n\n## 使用说明\n\n- `instructions` 为必填：Markdown 文档，可带 `summary` frontmatter，正文不能为空，最多 51,200 字节。已弃用的 `description` 字段仍可传入，若与 `instructions` 同时传入，两者必须完全一致。\n- `agent_name` 不能包含 `@`，也不能是内置智能体保留的 `general` / `explore`，且在其作用域（账户级或单个团队）内必须唯一；违反时返回 `InvalidParameter`。\n- `card_url` 必须是带 host 的绝对 `http`/`https` URL。若该智能体有在线的执行环境，服务端会通过该环境拉取智能体卡片（`card_url` 不带路径时自动补 `/.well-known/agent-card.json`），卡片不是合法 JSON、或未声明协议绑定为 `JSONRPC` / `HTTP+JSON` 的 A2A 1.x 接口时拒绝；卡片不可达、返回非 2xx 或没有在线环境时不阻断调用。\n- `auth_type=bearer` 时以 `Authorization: Bearer <token>` 发送 `auth_config.token`；`auth_type=api_key` 时把 `auth_config.api_key` 放进 `auth_config.header` 指定名称的请求头；为 `none` 或空值时不发送共享凭据请求头。\n- `environments` 的每一项必须是 `cloud`，或某个账户级 BYOC Runner、调用者所属团队的 BYOC Runner 的环境 ID；重复项会被去除，空字符串会被拒绝。省略或为空表示所有环境。\n- 创建到团队（`team_id > 0`）要求调用者属于该团队；只有账户 owner 或管理员可以在账户级（`team_id=0`）创建。\n- 新建的智能体 `status` 为 `enabled`。\n- 每次调用都会记录到账户审计日志。\n",
           "href": "/zh/api-reference/ai-sre/a2a-agents/remote-agent-write-create",
           "metadata": {
             "sidebarTitle": "创建 A2A 智能体"
@@ -122,6 +122,9 @@
                 "instructions": "Inspect deployment pipelines and propose rollbacks when a canary fails health checks.",
                 "card_url": "https://agents.example.com/deploy-bot/card",
                 "auth_type": "bearer",
+                "auth_config": {
+                  "token": "sk-agent-token-example-9f2c"
+                },
                 "streaming": true,
                 "team_id": 0,
                 "environments": [
@@ -147,7 +150,7 @@
           }
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **Agent 管理**（`ai-sre`） |\n\n## 使用说明\n\n- 删除为软删除；删除后该智能体不再出现在列表/详情中，也无法再被调度。\n- 需要对智能体所属团队具备编辑权限（`access.CanEdit`）。\n- 每次调用都会记录到账户审计日志。\n",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **Agent 管理**（`ai-sre`） |\n\n## 使用说明\n\n- 软删除：智能体立即从列表和详情中消失，不能再被调用，其名称在原作用域内可以重新使用。\n- 需要对智能体当前所属团队有编辑权限：账户级智能体（`team_id=0`）仅账户 owner 或管理员可改；团队智能体仅该团队成员可改（owner/管理员也必须是该团队成员）。\n- 智能体不存在或已删除时返回 `ResourceNotFound`。\n- 每次调用都会记录到账户审计日志。\n",
           "href": "/zh/api-reference/ai-sre/a2a-agents/remote-agent-write-delete",
           "metadata": {
             "sidebarTitle": "删除 A2A 智能体"
@@ -168,15 +171,14 @@
                       "properties": {
                         "data": {
                           "type": "null",
-                          "description": "成功时恒为 null。"
+                          "description": "成功时不返回该字段，响应体只有 `request_id`。"
                         }
                       }
                     }
                   ]
                 },
                 "example": {
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
-                  "data": null
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
             }
@@ -226,7 +228,7 @@
           }
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **Agent 管理**（`ai-sre`） |\n\n## 使用说明\n\n- 需要对智能体所属团队具备编辑权限（`access.CanEdit`）。\n- 若智能体已处于禁用状态，返回 `InvalidParameter`。\n- 每次调用都会记录到账户审计日志。\n",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **Agent 管理**（`ai-sre`） |\n\n## 使用说明\n\n- 需要对智能体当前所属团队有编辑权限：账户级智能体（`team_id=0`）仅账户 owner 或管理员可改；团队智能体仅该团队成员可改（owner/管理员也必须是该团队成员）。\n- 智能体已处于停用状态时返回 `InvalidParameter`。\n- 停用后，该智能体不再提供给 AI SRE 会话使用，配置保留。\n- 每次调用都会记录到账户审计日志。\n",
           "href": "/zh/api-reference/ai-sre/a2a-agents/remote-agent-write-disable",
           "metadata": {
             "sidebarTitle": "禁用 A2A 智能体"
@@ -247,15 +249,14 @@
                       "properties": {
                         "data": {
                           "type": "null",
-                          "description": "成功时恒为 null。"
+                          "description": "成功时不返回该字段，响应体只有 `request_id`。"
                         }
                       }
                     }
                   ]
                 },
                 "example": {
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
-                  "data": null
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
             }
@@ -305,7 +306,7 @@
           }
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **Agent 管理**（`ai-sre`） |\n\n## 使用说明\n\n- 需要对智能体所属团队具备编辑权限（`access.CanEdit`），仅可见不足以调用。\n- 若智能体已处于启用状态，返回 `InvalidParameter`。\n- 每次调用都会记录到账户审计日志。\n",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **Agent 管理**（`ai-sre`） |\n\n## 使用说明\n\n- 需要对智能体当前所属团队有编辑权限：账户级智能体（`team_id=0`）仅账户 owner 或管理员可改；团队智能体仅该团队成员可改（owner/管理员也必须是该团队成员）。\n- 智能体已处于启用状态时返回 `InvalidParameter`。\n- 启用后，该智能体会重新提供给 AI SRE 会话使用。\n- 每次调用都会记录到账户审计日志。\n",
           "href": "/zh/api-reference/ai-sre/a2a-agents/remote-agent-write-enable",
           "metadata": {
             "sidebarTitle": "启用 A2A 智能体"
@@ -326,15 +327,14 @@
                       "properties": {
                         "data": {
                           "type": "null",
-                          "description": "成功时恒为 null。"
+                          "description": "成功时不返回该字段，响应体只有 `request_id`。"
                         }
                       }
                     }
                   ]
                 },
                 "example": {
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
-                  "data": null
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
             }
@@ -374,7 +374,7 @@
       "post": {
         "operationId": "remote-agent-read-get",
         "summary": "查看 A2A 智能体详情",
-        "description": "按 ID 查看单个 A2A 智能体。",
+        "description": "按 ID 返回单个 A2A 智能体的配置，认证密钥已脱敏。",
         "tags": [
           "AI SRE/A2A 智能体"
         ],
@@ -384,7 +384,7 @@
           }
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- `card_resolve_timeout` 与 `task_timeout` 目前恒为 `0` —— API 尚未提供设置方式。\n",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- `auth_config` 中 `api_key`、`token`、`client_secret` 以及其他加密存储的值会脱敏：超过 8 个字符时只显示首尾各 4 个字符，中间为 `****`，否则显示 `****`。\n- `card_resolve_timeout` 与 `task_timeout` 目前恒为 `0` —— API 尚未提供设置方式。\n- 智能体不存在或已删除时返回 `ResourceNotFound`。\n",
           "href": "/zh/api-reference/ai-sre/a2a-agents/remote-agent-read-get",
           "metadata": {
             "sidebarTitle": "查看 A2A 智能体详情"
@@ -424,13 +424,11 @@
                     "instructions": "Inspect deployment pipelines and propose rollbacks when a canary fails health checks.",
                     "card_url": "https://agents.example.com/deploy-bot/card",
                     "auth_type": "bearer",
+                    "auth_config": {
+                      "token": "sk-a****9f2c"
+                    },
                     "streaming": true,
                     "status": "enabled",
-                    "agent_card_name": "Deploy Bot",
-                    "agent_card_skills": [
-                      "rollback",
-                      "diff"
-                    ],
                     "card_resolve_timeout": 0,
                     "task_timeout": 0,
                     "auth_mode": "shared",
@@ -448,6 +446,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -484,7 +485,7 @@
           }
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 分页使用 `offset`/`limit`（而非 `p`/`limit`）。\n- `scope=account` 仅返回账户级智能体；`scope=team` 仅返回调用者可见团队中的智能体；默认 `all` 两者兼含，受 `include_account` 影响。\n- `query` 会在智能体名称、指令、卡片 URL、智能体 ID 以及解析得到的卡片名称中执行不区分大小写的子串搜索。\n- `card_resolve_timeout` 与 `task_timeout` 目前恒为 `0` —— API 尚未提供设置方式。\n",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 分页使用 `offset`/`limit`（而非 `p`/`limit`）；`limit` 小于等于 0 时按 20 处理。结果按创建时间倒序排列。\n- 可见范围对所有调用者（含 owner 和管理员）都按真实团队成员关系计算：账户级记录，加上调用者所属团队的记录；`team_ids` 中不在此范围内的团队 ID 会被忽略。\n- `scope=account` 只返回账户级记录；`scope=team` 只返回团队记录；`all`（默认）返回团队记录，并在 `include_account` 不为 `false` 时一并返回账户级记录。\n- `query` 会在智能体名称、指令、卡片 URL、智能体 ID 和卡片名称中执行不区分大小写的子串搜索。\n- 每条记录的 `can_edit` 表示调用者能否更新、启用、停用或删除该智能体。\n",
           "href": "/zh/api-reference/ai-sre/a2a-agents/remote-agent-read-list",
           "metadata": {
             "sidebarTitle": "查询 A2A 智能体列表"
@@ -526,13 +527,11 @@
                         "instructions": "Inspect deployment pipelines and propose rollbacks when a canary fails health checks.",
                         "card_url": "https://agents.example.com/deploy-bot/card",
                         "auth_type": "bearer",
+                        "auth_config": {
+                          "token": "sk-a****9f2c"
+                        },
                         "streaming": true,
                         "status": "enabled",
-                        "agent_card_name": "Deploy Bot",
-                        "agent_card_skills": [
-                          "rollback",
-                          "diff"
-                        ],
                         "card_resolve_timeout": 0,
                         "task_timeout": 0,
                         "auth_mode": "shared",
@@ -553,6 +552,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -591,7 +593,7 @@
           }
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **Agent 管理**（`ai-sre`） |\n\n## 使用说明\n\n- 任何字段变更前都需要对智能体*当前*所属团队具备编辑权限（`access.CanEdit`）。\n- 重新分配 `team_id` 需要对目标团队的权限；若团队变更且未同时传入新的环境绑定，则现有 Runner 绑定必须对调用者仍可选，否则更新将被拒绝。\n- 变更 `auth_mode` 时会始终一并重写 `secret_schema`；若变更 `auth_mode` 时未传入 `oauth_metadata`，则将其清空。\n- 对敏感的 `auth_config` 键（`api_key`、`token`、`client_secret`）回传挖码值或空字符串将保留已存储的密钥，而不会覆盖。\n- 每次调用都会记录到账户审计日志。\n",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **Agent 管理**（`ai-sre`） |\n\n## 使用说明\n\n- 需要对智能体当前所属团队有编辑权限：账户级智能体（`team_id=0`）仅账户 owner 或管理员可改；团队智能体仅该团队成员可改（owner/管理员也必须是该团队成员）。\n- 改到其他团队（`team_id > 0`）要求调用者属于目标团队；改为账户级（`team_id=0`）仅限账户 owner 或管理员。变更团队但未同时传 `environments` 时，现有 Runner 条目必须对调用者仍可选，否则更新被拒绝。\n- `auth_config` 整体替换：未传入的键会被删除。对 `api_key`、`token`、`client_secret`，回传详情接口返回的脱敏值会保留已存储的密钥，传空字符串则清除该密钥。\n- 传入 `auth_mode` 时，`secret_schema` 会被同一请求中的值覆盖（未传则置空）。`auth_mode` 或 `card_url` 实际发生变化时会清空 `oauth_metadata`，除非同时传入非空的 `oauth_metadata`；只传空的 `oauth_metadata` 不会改动已存储的值。\n- 修改 `card_url` 会重新执行创建时的智能体卡片兼容性检查；修改 `agent_name` 会重新校验命名规则。\n- 每次调用都会记录到账户审计日志。\n",
           "href": "/zh/api-reference/ai-sre/a2a-agents/remote-agent-write-update",
           "metadata": {
             "sidebarTitle": "更新 A2A 智能体"
@@ -612,15 +614,14 @@
                       "properties": {
                         "data": {
                           "type": "null",
-                          "description": "成功时恒为 null。"
+                          "description": "成功时不返回该字段，响应体只有 `request_id`。"
                         }
                       }
                     }
                   ]
                 },
                 "example": {
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
-                  "data": null
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
             }
@@ -661,7 +662,7 @@
       "post": {
         "operationId": "automation-rule-write-create",
         "summary": "创建自动化规则",
-        "description": "创建自动化规则，支持 schedule、HTTP POST 和 On-call 故障触发器。",
+        "description": "创建自动化规则，可配置定时、HTTP POST、On-call 故障和作战室触发器。",
         "tags": [
           "AI SRE/自动化"
         ],
@@ -671,7 +672,7 @@
           }
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 有效 `app_key`；管理操作要求调用者可管理目标规则 |\n\n## 使用说明\n\n- 可以创建个人规则，也可以创建当前账户下任意团队的规则；`team_id` 之后可通过 update 改派（团队规则转个人仅 owner 可操作；转入团队要求调用者属于该团队）。\n- `cron_expr` 按 `timezone`（如提供）计算；未提供时依次回退到调用者的成员时区、账户时区，最后是服务端默认时区（Asia/Shanghai）。\n- `http_post_trigger_enabled=true` 会创建并启用 HTTP POST 触发器；响应中的 `http_post_token` 是仅在创建时返回的一次性值，请立即保存。\n- `oncall_incident_trigger_enabled=true` 时，`oncall_incident_channel_ids` 和 `oncall_incident_severities` 至少各需一项；匹配的故障会以 `trigger_kind=oncall_incident` 运行。\n- 每次调用都会记录到账户审计日志。\n",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **Automation 管理**（`ai-sre`） |\n\n## 使用说明\n\n- 省略 `team_id` 或传 `0` 创建个人规则。创建团队规则要求调用者是该团队成员，账户所有者和管理员也不例外。\n- 规则的作用域在创建时确定：更新自动化规则时，`team_id` 与已存值不同会被拒绝。如需在其他作用域运行同一任务，请新建规则。\n- 即使只使用其他触发器，`cron_expr` 也必填；请传一个合法表达式并将 `schedule_trigger_enabled` 设为 `false`。\n- `cron_expr` 按 `timezone` 计算；未提供时依次使用调用者的成员时区、账户时区，最后为 `Asia/Shanghai`。\n- `http_post_trigger_enabled=true` 会创建并启用 HTTP POST 触发器。`http_post_token` 只在本次响应中返回，请妥善保存。触发方式：向 `http_post_trigger_url` 发送 `POST`，并带请求头 `Authorization: Bearer <http_post_token>`；可选的 JSON 请求体 `{\"text\": \"...\"}` 不超过 256 KB。\n- 只要传了任一 `oncall_incident_*` 字段，`oncall_incident_channel_ids` 与 `oncall_incident_severities` 都必须非空。命中条件的故障会以 `trigger_kind=oncall_incident` 发起运行。\n- 当 `war_room_trigger_enabled=true` 或传了 `war_room_channel_ids` 时，`war_room_channel_ids` 与 `war_room_severities` 都必须非空。命中条件的故障创建作战室（IM 群聊）后，Agent 会直接在该群聊中运行，运行记录的 `trigger_kind` 为 `war_room_created`。\n- 通过 API 创建的规则在 Web 控制台中运行（`execution_place=web_console`）；`run_in=current-chat` 仅在与 AI SRE Agent 的实时 IM 会话中可用，通过 API 传入会被拒绝。\n- 响应为新建的规则；对创建者而言 `can_edit` 恒为 `true`。\n- 每次调用都会记录到账户审计日志。\n",
           "href": "/zh/api-reference/ai-sre/automations/automation-rule-write-create",
           "metadata": {
             "sidebarTitle": "创建自动化规则"
@@ -730,7 +731,16 @@
                     "oncall_incident_severities": [
                       "Critical",
                       "Warning"
-                    ]
+                    ],
+                    "oncall_incident_merge_similar": true,
+                    "war_room_trigger_enabled": false,
+                    "execution_place": "web_console",
+                    "execution_location": {
+                      "place": "web_console",
+                      "run_scope": "team",
+                      "team_id": 123,
+                      "description": "Web console"
+                    }
                   }
                 }
               }
@@ -786,7 +796,7 @@
       "post": {
         "operationId": "automation-rule-write-delete",
         "summary": "删除自动化规则",
-        "description": "删除一条自动化规则。",
+        "description": "删除一条自动化规则，并同时删除其全部触发器及订阅。",
         "tags": [
           "AI SRE/自动化"
         ],
@@ -796,7 +806,7 @@
           }
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 有效 `app_key`；管理操作要求调用者可管理目标规则 |\n\n## 使用说明\n\n- 删除规则会同时移除其 schedule、HTTP POST 和 On-call 故障触发器；被删除的 HTTP POST 触发器 token 会立即失效。\n- 每次调用都会记录到账户审计日志。\n",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **Automation 管理**（`ai-sre`） |\n\n## 使用说明\n\n- 删除规则会同时移除其定时、HTTP POST、On-call 故障和作战室触发器；HTTP POST 触发器的 token 随之失效。\n- 管理权限：个人规则（`team_id=0`）仅创建者可管理；团队规则仅该团队成员可管理。账户所有者和管理员没有例外，需加入该团队。其他调用者会收到 `403`。\n- 同一规则正在执行另一次更新、删除或手动运行时，本调用返回 HTTP `423`，`code` 为 `\"RequestLocked\"`，请稍后重试。\n- 每次调用都会记录到账户审计日志。\n",
           "href": "/zh/api-reference/ai-sre/automations/automation-rule-write-delete",
           "metadata": {
             "sidebarTitle": "删除自动化规则"
@@ -817,15 +827,14 @@
                       "properties": {
                         "data": {
                           "type": "null",
-                          "description": "成功时固定为 null。"
+                          "description": "成功时不返回该字段，响应体只有 `request_id`。"
                         }
                       }
                     }
                   ]
                 },
                 "example": {
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
-                  "data": null
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
             }
@@ -865,7 +874,7 @@
       "post": {
         "operationId": "automation-rule-read-get",
         "summary": "查看自动化规则",
-        "description": "按 ID 查看一条自动化规则。",
+        "description": "按 ID 获取一条自动化规则，包括触发器配置和运行位置。",
         "tags": [
           "AI SRE/自动化"
         ],
@@ -875,7 +884,7 @@
           }
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 有效 `app_key`；调用者必须可管理目标规则 |\n\n## 使用说明\n\n- 管理权限指：个人规则仅限创建者；团队规则限账户管理员或规则所属团队成员。\n",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **Automation 查看**（`ai-sre`） |\n\n## 使用说明\n\n- 管理权限：个人规则（`team_id=0`）仅创建者可管理；团队规则仅该团队成员可管理。账户所有者和管理员没有例外，需加入该团队。没有管理权限的调用者会收到 `403`。\n- 本接口不返回 `last_run`；运行状态请用列出自动化规则或列出自动化运行记录查询。\n- 本接口从不返回 `http_post_token`；它只在签发 token 时（创建、首次启用 HTTP POST 触发器或轮换）返回。\n",
           "href": "/zh/api-reference/ai-sre/automations/automation-rule-read-get",
           "metadata": {
             "sidebarTitle": "查看自动化规则"
@@ -933,7 +942,16 @@
                     "oncall_incident_severities": [
                       "Critical",
                       "Warning"
-                    ]
+                    ],
+                    "oncall_incident_merge_similar": true,
+                    "war_room_trigger_enabled": false,
+                    "execution_place": "web_console",
+                    "execution_location": {
+                      "place": "web_console",
+                      "run_scope": "team",
+                      "team_id": 123,
+                      "description": "Web console"
+                    }
                   }
                 }
               }
@@ -974,7 +992,7 @@
       "post": {
         "operationId": "automation-rule-read-list",
         "summary": "列出自动化规则",
-        "description": "列出当前调用者可见的自动化规则。",
+        "description": "列出调用者可见的自动化规则，按更新时间倒序，支持分页和过滤。",
         "tags": [
           "AI SRE/自动化"
         ],
@@ -984,7 +1002,7 @@
           }
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 有效 `app_key`；结果按调用者可见范围过滤 |\n\n## 使用说明\n\n- `all` 返回调用者自己的个人规则，以及调用者可访问团队的团队规则。\n- 账户管理员在列表中可见所有团队规则，但不可见他人的个人规则。\n- `team_ids` 只会收窄可见集合，不会扩大访问范围。\n",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **Automation 查看**（`ai-sre`） |\n\n## 使用说明\n\n- 可见范围：调用者自己的个人规则，加上调用者所属团队的团队规则。账户所有者和管理员同样只能看到自己所属团队的规则，看不到他人的个人规则。\n- `scope=personal` 只返回调用者的个人规则；`scope=team` 只返回调用者所属团队的规则。`team_ids` 只会进一步收窄结果，不会扩大访问范围。\n- 结果按 `updated_at` 倒序排列。规则运行过时，列表项会带上 `last_run`（最近一次运行）。\n- 列表项的 `can_edit` 表示调用者能否管理（获取、更新、删除、运行）该规则。\n",
           "href": "/zh/api-reference/ai-sre/automations/automation-rule-read-list",
           "metadata": {
             "sidebarTitle": "列出自动化规则"
@@ -1045,7 +1063,21 @@
                         "oncall_incident_severities": [
                           "Critical",
                           "Warning"
-                        ]
+                        ],
+                        "oncall_incident_merge_similar": true,
+                        "war_room_trigger_enabled": false,
+                        "execution_place": "web_console",
+                        "execution_location": {
+                          "place": "web_console",
+                          "run_scope": "team",
+                          "team_id": 123,
+                          "description": "Web console"
+                        },
+                        "last_run": {
+                          "run_id": "trun_5oDvqiG64uur6sBNsTc4u",
+                          "status": "succeeded",
+                          "started_at": 1780630800000
+                        }
                       }
                     ]
                   }
@@ -1089,7 +1121,7 @@
       "post": {
         "operationId": "automation-rule-write-run",
         "summary": "运行自动化规则",
-        "description": "立即手动运行一次自动化规则，不受其计划触发时间限制。",
+        "description": "立即运行一次自动化规则，不受其触发器和启用状态限制。",
         "tags": [
           "AI SRE/自动化"
         ],
@@ -1099,7 +1131,7 @@
           }
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **100 次/分钟**；**5 次/秒** |\n| 权限要求 | 有效 `app_key`；调用者必须可管理目标规则 |\n\n## 使用说明\n\n- 同一规则的手动运行限速为每分钟最多一次；在此窗口内的第二次调用会返回 `429`，`code` 为 `\"RequestTooFrequently\"`。\n- 只有已启用的规则才能手动运行；已禁用或配置无效的规则会在创建运行前以 `400` 错误未通过预检。\n- 调用在底层 Agent 会话启动后即返回，而非等待运行结束；运行会继续异步执行——可使用列出自动化运行历史查询完成状态。\n- 以此方式发起的运行，`trigger_kind` 固定为 `manual`，在运行历史中与 `schedule`、`http_post`、`oncall_incident` 区分开来。\n- 每次调用都会记录到账户审计日志。\n",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **100 次/分钟**；**5 次/秒** |\n| 权限要求 | **Automation 管理**（`ai-sre`） |\n\n## 使用说明\n\n- 手动运行不要求规则处于启用状态。规则配置无效（例如使用了规则作用域不允许的 BYOC 运行器），或唯一启用的触发器是作战室触发器（这类规则没有 Web 控制台运行）时，会在创建运行前返回 `400`。\n- 创建者已离开账户的个人规则会被自动停用，本调用返回 `400`。\n- 同一规则每分钟最多手动运行一次；窗口内的第二次调用返回 `429`，`code` 为 `\"RequestTooFrequently\"`。\n- 管理权限：个人规则（`team_id=0`）仅创建者可管理；团队规则仅该团队成员可管理。账户所有者和管理员没有例外，需加入该团队。\n- 同一规则正在执行另一次更新、删除或手动运行时，本调用返回 HTTP `423`，`code` 为 `\"RequestLocked\"`，请稍后重试。\n- 调用在 Agent 会话启动后即返回，不等待运行结束。可用列出自动化运行记录（`trigger_kind=manual`）查询完成情况。\n- 对在 IM 群聊中运行的规则（`execution_place=im`），响应不包含 `run.session_id`。\n- 每次调用都会记录到账户审计日志。\n",
           "href": "/zh/api-reference/ai-sre/automations/automation-rule-write-run",
           "metadata": {
             "sidebarTitle": "运行自动化规则"
@@ -1188,7 +1220,7 @@
       "post": {
         "operationId": "automation-rule-write-update",
         "summary": "更新自动化规则",
-        "description": "更新自动化规则的可变字段，包括 HTTP POST 与 On-call 故障触发器配置。",
+        "description": "更新自动化规则的字段和触发器配置；省略的字段保持不变。",
         "tags": [
           "AI SRE/自动化"
         ],
@@ -1198,7 +1230,7 @@
           }
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 有效 `app_key`；管理操作要求调用者可管理目标规则 |\n\n## 使用说明\n\n- 省略或传 `null` 的字段保持不变。`team_id` 用于改派规则作用域：`0` 将团队规则转为个人规则（仅 owner 可操作），`>0` 转入调用者所属的团队。\n- `cron_expr` 与 `timezone` 可以分别更新——只传其中一个时，另一个保持当前已存储的值。\n- `rotate_http_post_trigger_token=true` 会签发新的 webhook token，且仅在本次响应中返回。\n- 如需由 On-call 故障触发，传入 `oncall_incident_trigger_enabled`、`oncall_incident_channel_ids` 与 `oncall_incident_severities`；匹配事件会以 `trigger_kind=oncall_incident` 运行。\n- 每次调用都会记录到账户审计日志。\n",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **Automation 管理**（`ai-sre`） |\n\n## 使用说明\n\n- 省略或传 `null` 的字段保持不变。`*_channel_ids` / `*_severities` 传空数组时也保留已存的列表。\n- `team_id` 不可修改：传入与已存值不同的值会返回 `400`；重复传入当前值是允许的。\n- `cron_expr` 与 `timezone` 可以单独传，另一个保持已存值。传 `timezone: \"\"` 会存为 `UTC`。\n- 只传 `environment_kind` 不传 `environment_id` 时，会清空已存的 `environment_id`。\n- 规则没有 HTTP POST 触发器时，`http_post_trigger_enabled=true` 会创建一个并返回其 token。`rotate_http_post_trigger_token=true` 会签发新 token（旧 token 立即失效），要求该触发器处于启用状态。新 token 只在本次响应中返回。\n- 通过更新新建 On-call 故障或作战室触发器时，必须同时提供对应的协作空间 ID 和严重程度。\n- 管理权限：个人规则（`team_id=0`）仅创建者可管理；团队规则仅该团队成员可管理。账户所有者和管理员没有例外，需加入该团队。\n- 同一规则正在执行另一次更新、删除或手动运行时，本调用返回 HTTP `423`，`code` 为 `\"RequestLocked\"`，请稍后重试。\n- 每次调用都会记录到账户审计日志。\n",
           "href": "/zh/api-reference/ai-sre/automations/automation-rule-write-update",
           "metadata": {
             "sidebarTitle": "更新自动化规则"
@@ -1257,7 +1289,16 @@
                     "oncall_incident_severities": [
                       "Critical",
                       "Warning"
-                    ]
+                    ],
+                    "oncall_incident_merge_similar": true,
+                    "war_room_trigger_enabled": false,
+                    "execution_place": "web_console",
+                    "execution_location": {
+                      "place": "web_console",
+                      "run_scope": "team",
+                      "team_id": 123,
+                      "description": "Web console"
+                    }
                   }
                 }
               }
@@ -1309,7 +1350,7 @@
       "post": {
         "operationId": "automation-run-read-list",
         "summary": "列出自动化运行历史",
-        "description": "列出调用者可管理规则的运行历史。",
+        "description": "列出一条自动化规则的运行记录，按开始时间倒序，支持按状态、触发来源和时间过滤。",
         "tags": [
           "AI SRE/自动化"
         ],
@@ -1319,7 +1360,7 @@
           }
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 有效 `app_key`；调用者必须可管理目标规则 |\n\n## 使用说明\n\n- 仅当调用者可管理规则时才可查看运行历史：个人规则仅限创建者；团队规则限账户管理员或规则所属团队成员。\n",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **Automation 查看**（`ai-sre`） |\n\n## 使用说明\n\n- 管理权限：个人规则（`team_id=0`）仅创建者可管理；团队规则仅该团队成员可管理。账户所有者和管理员没有例外，需加入该团队。其他调用者会收到 `403`。\n- 运行记录保留 180 天；更早的 `started_after_ms` 会被提升到该下限。\n- 结果按 `started_at` 倒序排列。\n- 在 IM 群聊中执行的运行（`execution_place=im`）不返回 `session_id`、`joined_session_id` 和 `result_json`。\n",
           "href": "/zh/api-reference/ai-sre/automations/automation-run-read-list",
           "metadata": {
             "sidebarTitle": "列出自动化运行历史"
@@ -1358,6 +1399,7 @@
                         "account_id": 10023,
                         "rule_id": "arule_7NnLzY2Qp8xS4kUaV3mR6b",
                         "trigger_kind": "schedule",
+                        "execution_place": "web_console",
                         "occurrence_key": "atrig_6aKp3wT9mQ2xVc8bR1nY7z:1780630800000",
                         "status": "succeeded",
                         "attempts": 1,
@@ -1416,7 +1458,7 @@
       "post": {
         "operationId": "automation-template-read-list",
         "summary": "列出自动化模板",
-        "description": "按语言列出自动化预设模板。",
+        "description": "列出用于预填创建规则表单的内置自动化模板，支持中文或英文。",
         "tags": [
           "AI SRE/自动化"
         ],
@@ -1426,7 +1468,7 @@
           }
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 有效 `app_key`；结果按调用者可见范围过滤 |\n",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **Automation 查看**（`ai-sre`） |\n\n## 使用说明\n\n- 模板由平台内置，所有账户相同。\n- 语言规则：`locale` 含 `zh` 时返回中文模板，含 `en` 时返回英文模板，其他非空值返回中文。省略 `locale` 时，由查询参数 `locale`/`lang` 或请求头 `Accept-Language` 决定。\n- 每个模板相当于一份不完整的创建请求：将其字段传给创建自动化规则，并补上只有调用方能提供的内容（模板未提供时的 `cron_expr`、`timezone`、协作空间 ID）。\n",
           "href": "/zh/api-reference/ai-sre/automations/automation-template-read-list",
           "metadata": {
             "sidebarTitle": "列出自动化模板"
@@ -1460,8 +1502,14 @@
                         "name": "Weekly Insights",
                         "description": "Analyze incidents, alerts, response activity, notification load, and related changes from the past week.",
                         "icon": "chart-no-axes-combined",
+                        "category": "Insights",
                         "enabled": false,
-                        "prompt": "Generate a weekly insights report. Analyze incidents, alerts, response activity, notification load, and related changes from the past week. Focus on what happened this week, which signals deserve attention, and which improvement actions are most valuable. Do not modify any Flashduty business state.\n"
+                        "prompt": "Generate a weekly insights report. Analyze incidents, alerts, response activity, notification load, and related changes from the past week. Focus on what happened this week, which signals deserve attention, and which improvement actions are most valuable. Do not modify any Flashduty business state.\n",
+                        "schedule_trigger_enabled": true,
+                        "cron_expr": "0 9 * * 1",
+                        "http_post_trigger_enabled": false,
+                        "oncall_incident_trigger_enabled": false,
+                        "war_room_trigger_enabled": false
                       }
                     ]
                   }
@@ -1514,7 +1562,7 @@
           }
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **MCP 管理**（`ai-sre`） |\n\n## 使用说明\n\n- `command`/`args`/`env` 用于 `stdio`；`url`/`headers` 用于 `sse`/`streamable-http`。\n- 服务器名称必须以字母开头，且只能包含字母、数字、`-` 或 `_`，在其作用域（账户范围或单个团队）内不区分大小写唯一；不满足则返回 InvalidParameter。\n- `environments` 限定服务器可运行的环境：`cloud` 和/或 BYOC Runner 的环境 ID 列表；省略或为空表示所有环境。\n- `per_user_secret` 认证模式要求 `secret_schema` 为合法 JSON 且包含非空的 `header_name`。\n- 每次调用都会记录到账户审计日志。\n",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **MCP 管理**（`ai-sre`） |\n\n## 使用说明\n\n- `command`/`args`/`env` 用于 `stdio`；`url`/`headers` 用于 `sse`/`streamable-http`。\n- `server_name` 必须以字母开头，只能包含字母、数字、`-` 或 `_`，且在其作用域（账户级或单个团队）内唯一；违反时返回 `InvalidParameter`。\n- 未传 `source_template_name` 时，创建到团队（`team_id > 0`）要求调用者属于该团队，只有账户 owner 或管理员可以在账户级（`team_id=0`）创建。\n- 传入 `source_template_name` 表示安装市场模板：模板必须存在（否则返回 `ResourceNotFound`），`team_id` 被忽略、服务器一律建在账户级，且连接字段必须与模板一致，只能填写模板声明的参数值。若模板为按人认证、且其参数允许安装者决定目标主机，则仅账户 owner 或管理员可安装。\n- `environments` 的每一项必须是 `cloud`，或某个账户级 BYOC Runner、调用者所属团队的 BYOC Runner 的环境 ID；重复项会被去除，空字符串会被拒绝。省略或为空表示所有环境。\n- `per_user_secret` 认证模式要求 `secret_schema` 为合法 JSON 且包含非空的 `header_name`。\n- `env` 与 `headers` 中，键名包含 `KEY`、`SECRET`、`TOKEN`、`PASSWORD`、`PASSWD`、`CREDENTIAL` 或 `AUTHORIZATION`（不区分大小写）、或含 `PWD` / `PASS` 分段的值，以及已加密存储的值，会加密存储并在响应中脱敏。\n- 响应为已保存的服务器。之后服务端会通过已在线的执行环境在后台拉取其工具列表，调用不会等待该过程。\n- 每次调用都会记录到账户审计日志。\n",
           "href": "/zh/api-reference/ai-sre/mcp-servers/mcp-write-server-create",
           "metadata": {
             "sidebarTitle": "创建 MCP 服务器"
@@ -1552,13 +1600,16 @@
                     "description": "Query Prometheus metrics and alerts.",
                     "transport": "streamable-http",
                     "url": "https://mcp.example.com/prometheus",
+                    "headers": {
+                      "Authorization": "Bear****f2c1"
+                    },
                     "status": "enabled",
-                    "connect_timeout": 10,
-                    "call_timeout": 60,
+                    "connect_timeout": 0,
+                    "call_timeout": 0,
                     "auth_mode": "shared",
                     "created_by": 80011,
                     "created_at": 1716960000000,
-                    "updated_at": 1717046400000
+                    "updated_at": 1716960000000
                   }
                 }
               }
@@ -1592,6 +1643,9 @@
                 "description": "Query Prometheus metrics and alerts.",
                 "transport": "streamable-http",
                 "url": "https://mcp.example.com/prometheus",
+                "headers": {
+                  "Authorization": "Bearer example-token-f2c1"
+                },
                 "status": "enabled"
               }
             }
@@ -1613,7 +1667,7 @@
           }
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **MCP 管理**（`ai-sre`） |\n\n## 使用说明\n\n- 每次调用都会记录到账户审计日志。\n",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **MCP 管理**（`ai-sre`） |\n\n## 使用说明\n\n- 永久删除该服务器并清除其工具列表缓存；该服务器不再提供给 AI SRE 会话使用，名称可以重新使用。\n- 需要对服务器当前所属团队有编辑权限：账户级服务器（`team_id=0`）仅账户 owner 或管理员可改；团队服务器仅该团队成员可改（owner/管理员也必须是该团队成员）。\n- 服务器不存在时返回 `ResourceNotFound`。\n- 每次调用都会记录到账户审计日志。\n",
           "href": "/zh/api-reference/ai-sre/mcp-servers/mcp-write-server-delete",
           "metadata": {
             "sidebarTitle": "删除 MCP 服务器"
@@ -1634,15 +1688,14 @@
                       "properties": {
                         "data": {
                           "type": "null",
-                          "description": "成功时恒为 null。"
+                          "description": "成功时不返回该字段，响应体只有 `request_id`。"
                         }
                       }
                     }
                   ]
                 },
                 "example": {
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
-                  "data": null
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
             }
@@ -1692,7 +1745,7 @@
           }
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **MCP 管理**（`ai-sre`） |\n\n## 使用说明\n\n- 对已禁用的服务器再次禁用会返回 InvalidParameter，而不是静默忽略。\n- 需要对服务器当前所属团队具有编辑权限：账户级服务器仅限所有者/管理员；团队级服务器要求调用者属于该团队（或为所有者/管理员）。\n- 每次调用都会记录到账户审计日志。\n",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **MCP 管理**（`ai-sre`） |\n\n## 使用说明\n\n- 服务器已处于停用状态时返回 `InvalidParameter`。\n- 需要对服务器当前所属团队有编辑权限：账户级服务器（`team_id=0`）仅账户 owner 或管理员可改；团队服务器仅该团队成员可改（owner/管理员也必须是该团队成员）。\n- 停用后，该服务器的工具不再提供给 AI SRE 会话，配置保留。\n- 每次调用都会记录到账户审计日志。\n",
           "href": "/zh/api-reference/ai-sre/mcp-servers/mcp-write-server-disable",
           "metadata": {
             "sidebarTitle": "禁用 MCP 服务器"
@@ -1713,15 +1766,14 @@
                       "properties": {
                         "data": {
                           "type": "null",
-                          "description": "成功时恒为 null。"
+                          "description": "成功时不返回该字段，响应体只有 `request_id`。"
                         }
                       }
                     }
                   ]
                 },
                 "example": {
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
-                  "data": null
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
             }
@@ -1771,7 +1823,7 @@
           }
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **MCP 管理**（`ai-sre`） |\n\n## 使用说明\n\n- 对已启用的服务器再次启用会返回 InvalidParameter，而不是静默忽略。\n- 需要对服务器当前所属团队具有编辑权限：账户级服务器仅限所有者/管理员；团队级服务器要求调用者属于该团队（或为所有者/管理员）。\n- 每次调用都会记录到账户审计日志。\n",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **MCP 管理**（`ai-sre`） |\n\n## 使用说明\n\n- 服务器已处于启用状态时返回 `InvalidParameter`。\n- 需要对服务器当前所属团队有编辑权限：账户级服务器（`team_id=0`）仅账户 owner 或管理员可改；团队服务器仅该团队成员可改（owner/管理员也必须是该团队成员）。\n- 启用后，该服务器的工具会重新提供给 AI SRE 会话；工具列表缓存被清除，下次使用时重新拉取。\n- 每次调用都会记录到账户审计日志。\n",
           "href": "/zh/api-reference/ai-sre/mcp-servers/mcp-write-server-enable",
           "metadata": {
             "sidebarTitle": "启用 MCP 服务器"
@@ -1792,15 +1844,14 @@
                       "properties": {
                         "data": {
                           "type": "null",
-                          "description": "成功时恒为 null。"
+                          "description": "成功时不返回该字段，响应体只有 `request_id`。"
                         }
                       }
                     }
                   ]
                 },
                 "example": {
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
-                  "data": null
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
             }
@@ -1850,7 +1901,7 @@
           }
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 纯数据库读取——不会实时探测远端服务器；返回存储的配置（敏感值已脱敏）与缓存的 `ai_description`。\n",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **60 次/分钟**；**3 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 纯数据库读取——不会实时探测远端服务器；返回存储的配置与缓存的 `ai_description`。\n- `env` 与 `headers` 中，键名包含 `KEY`、`SECRET`、`TOKEN`、`PASSWORD`、`PASSWD`、`CREDENTIAL` 或 `AUTHORIZATION`（不区分大小写）、或含 `PWD` / `PASS` 分段的值，以及已加密存储的值，会在响应中脱敏。\n- `test_error` 与 `tested_at` 反映最近一次在控制台发起的连接测试；从未测试过时不返回。\n- 服务器不存在时返回 `ResourceNotFound`。\n",
           "href": "/zh/api-reference/ai-sre/mcp-servers/mcp-read-server-get",
           "metadata": {
             "sidebarTitle": "查看 MCP 服务器详情"
@@ -1888,9 +1939,12 @@
                     "description": "Query Prometheus metrics and alerts.",
                     "transport": "streamable-http",
                     "url": "https://mcp.example.com/prometheus",
+                    "headers": {
+                      "Authorization": "Bear****f2c1"
+                    },
                     "status": "enabled",
-                    "connect_timeout": 10,
-                    "call_timeout": 60,
+                    "connect_timeout": 0,
+                    "call_timeout": 0,
                     "auth_mode": "shared",
                     "created_by": 80011,
                     "created_at": 1716960000000,
@@ -1906,6 +1960,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -1942,7 +1999,7 @@
           }
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 响应不包含实时工具列表；工具列表在创建/更新后异步探测并缓存供运行时使用。\n- `query` 会对名称、描述、AI 生成描述、服务器 ID、传输协议、URL、命令及市场模板名称进行不区分大小写的子串匹配。\n",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 分页使用 `p`/`limit`：`p` 小于 1 时按 1 处理，`limit` 小于 1 时按 20 处理。结果按名称、再按服务器 ID 升序排列。\n- 可见范围对所有调用者（含 owner 和管理员）都按真实团队成员关系计算：账户级记录，加上调用者所属团队的记录；`team_ids` 中不在此范围内的团队 ID 会被忽略。\n- `scope=account` 只返回账户级记录；`scope=team` 只返回团队记录；`all`（默认）返回团队记录，并在 `include_account` 不为 `false` 时一并返回账户级记录。\n- `query` 会对名称、描述、AI 生成描述、服务器 ID、传输协议、URL、命令及市场模板名称进行不区分大小写的子串匹配。\n- 响应不包含实时工具列表；每条记录的 `can_edit` 表示调用者能否修改该服务器。\n",
           "href": "/zh/api-reference/ai-sre/mcp-servers/mcp-read-server-list",
           "metadata": {
             "sidebarTitle": "查询 MCP 服务器列表"
@@ -1983,9 +2040,12 @@
                         "description": "Query Prometheus metrics and alerts.",
                         "transport": "streamable-http",
                         "url": "https://mcp.example.com/prometheus",
+                        "headers": {
+                          "Authorization": "Bear****f2c1"
+                        },
                         "status": "enabled",
-                        "connect_timeout": 10,
-                        "call_timeout": 60,
+                        "connect_timeout": 0,
+                        "call_timeout": 0,
                         "auth_mode": "shared",
                         "created_by": 80011,
                         "created_at": 1716960000000,
@@ -2003,6 +2063,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -2041,7 +2104,7 @@
           }
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **MCP 管理**（`ai-sre`） |\n\n## 使用说明\n\n- `env`/`headers` 中的脱敏密钥会被保留——回传脱敏值不会覆盖已存储的真实密钥。\n- `environments` 是三态部分更新字段：省略（null）表示保持不变；传入列表即整体设置——空列表表示清除限制、恢复为所有环境。\n- 变更 `team_id` 需要对目标团队具有重新分配权限；若 `environments` 未随之修改，则当前环境列表在新团队下仍须对调用者可选，否则更新会被拒绝。\n- 每次调用都会记录到账户审计日志。\n",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **MCP 管理**（`ai-sre`） |\n\n## 使用说明\n\n- 需要对服务器当前所属团队有编辑权限：账户级服务器（`team_id=0`）仅账户 owner 或管理员可改；团队服务器仅该团队成员可改（owner/管理员也必须是该团队成员）。\n- `server_name`、`description`、`transport`、`command`、`url`、`auth_mode` 仅在非空时修改，`connect_timeout` / `call_timeout` 仅在非零时修改，因此无法通过本接口清空这些字段。\n- `args`、`env`、`headers` 传入即整体替换：`env`/`headers` 中未传入的键会被删除。对受保护的 `env`/`headers` 键，回传脱敏值或空字符串会保留已存储的密钥。\n- 传入 `auth_mode` 时，`secret_schema` 会被同一请求中的值覆盖（未传则置空）。`auth_mode` 或 `url` 实际发生变化时会清空 `oauth_metadata`，除非同时传入非空的 `oauth_metadata`。\n- 改到其他团队（`team_id > 0`）要求调用者属于目标团队，且从市场安装的服务器不允许改到团队；改为账户级（`team_id=0`）仅限账户 owner 或管理员。变更团队但未同时传 `environments` 时，现有 Runner 条目必须对调用者仍可选，否则更新被拒绝。\n- `environments`：省略（或传 `null`）表示不变；传入列表即整体替换——空列表表示清除限制、恢复为所有环境。\n- 响应为更新后的服务器。若修改了连接相关字段，会清除工具列表缓存并在后台重新拉取。\n- 每次调用都会记录到账户审计日志。\n",
           "href": "/zh/api-reference/ai-sre/mcp-servers/mcp-write-server-update",
           "metadata": {
             "sidebarTitle": "更新 MCP 服务器"
@@ -2079,9 +2142,12 @@
                     "description": "Query Prometheus metrics, alerts, and rules.",
                     "transport": "streamable-http",
                     "url": "https://mcp.example.com/prometheus",
+                    "headers": {
+                      "Authorization": "Bear****f2c1"
+                    },
                     "status": "enabled",
-                    "connect_timeout": 10,
-                    "call_timeout": 60,
+                    "connect_timeout": 0,
+                    "call_timeout": 0,
                     "auth_mode": "shared",
                     "created_by": 80011,
                     "created_at": 1716960000000,
@@ -2127,7 +2193,7 @@
       "post": {
         "operationId": "session-write-delete",
         "summary": "删除会话",
-        "description": "按 ID 删除会话。",
+        "description": "软删除会话，并一并删除其子智能体会话和会话中展示过的文件。",
         "tags": [
           "AI SRE/会话"
         ],
@@ -2137,7 +2203,7 @@
           }
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 个人会话仅创建者可删除；团队会话可由创建者、账户管理员或所属团队成员删除。\n- 这是软删除：会级联删除子智能体会话及其已展示的文件；底层 S3/MinIO 对象在事务提交后尽力清理，部分失败时可能残留孤立对象。\n",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 需要会话的管理权限：个人会话（`team_id` = 0）仅创建者可删除；团队会话由创建者或所属团队成员删除。账户所有者和管理员没有豁免，其他调用者会收到 `AccessDenied`。\n- `session_id` 不存在或已删除时返回 `ResourceNotFound`。\n- 删除前会尽力停止该会话仍在运行的后台进程（后台命令、monitor）；停止失败不会阻止删除。\n- 子智能体会话和会话中展示过的文件在同一事务内删除；存储中的文件内容随后尽力清理。\n",
           "href": "/zh/api-reference/ai-sre/sessions/session-write-delete",
           "metadata": {
             "sidebarTitle": "删除会话"
@@ -2158,15 +2224,14 @@
                       "properties": {
                         "data": {
                           "type": "null",
-                          "description": "成功时恒为 null。"
+                          "description": "成功时不返回该字段，响应体只有 `request_id`。"
                         }
                       }
                     }
                   ]
                 },
                 "example": {
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
-                  "data": null
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
             }
@@ -2216,7 +2281,7 @@
           }
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/天**；**200 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 个人会话仅创建者可导出；团队会话允许同一账户内持有 `session_id` 的调用者导出。\n- 响应为 `application/x-ndjson`——请逐行解析并写入文件，切勿将整段记录读入内存。\n- 第一行始终为 `session_meta` 信封；`include_subagents=true` 会在派发行后内联各子会话的事件流。\n- 请求存在 60 秒的执行超时上限；非常大的会话可能无法在该时间内导出完成。\n- 若流在中途失败，响应会以一行 JSON 错误行结束，而非规范的错误信封（响应头已发出）——可通过检测该结尾行判断记录是否被截断。\n",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/天**；**200 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 个人会话仅创建者可导出；团队会话同一账户内的任何成员都可导出。分享链接不授予导出权限。会话不存在或已删除时返回 `ResourceNotFound`。\n- 响应为 `application/x-ndjson`，请逐行解析并写入文件，不要把整个响应体读进内存。\n- 第一行始终是 `session_meta` 对象。之后每行的 `type` 为 `user_message`、`system_reminder`、`agent_text`、`tool_call`、`subagent_dispatch`、`llm_call`、`final_answer` 或 `session_fork` 之一。\n- `include_subagents=true` 时，每条 `subagent_dispatch` 行之后紧跟对应子会话的事件流，以子会话自己的 `session_meta` 开头。\n- 请求 60 秒超时；非常大的会话可能无法在此时间内导出完毕。\n- 若开始输出后导出失败，响应体以一行 `{\"type\":\"error\",\"content\":\"...\"}` 结束，而不是错误信封——检查最后一行即可判断是否被截断。\n",
           "href": "/zh/api-reference/ai-sre/sessions/session-read-export",
           "metadata": {
             "sidebarTitle": "导出会话记录"
@@ -2280,7 +2345,7 @@
           }
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 个人会话仅创建者可读；团队会话允许同一账户内持有 `session_id` 的调用者读取。\n- 使用上一次响应的 `search_after_ctx` 翻阅更早的历史。\n- `limit`（或旧版 `num_recent_events`）限制事件页大小；默认 100，最大 1000。\n- 格式错误的 `search_after_ctx` 会在触发任何数据库查询前立即返回 400。\n- `current_turn_*` 字段仅在会话 `is_running` 时才会填充；`suggest_init` 与 `session/list` 使用同一个账户级引导提示。\n",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 个人会话仅创建者可读，或持有有效 `share_token` 的调用者只读访问。团队会话同一账户内的任何成员都可读。会话不存在、已删除或无权读取时返回 `ResourceNotFound`。\n- `events` 为最新的一页，按时间升序排列。如需更早的历史，把返回的 `search_after_ctx` 传回；游标格式错误返回 `InvalidParameter`。\n- 每页条数取 `limit`，其次 `num_recent_events`，都未设置时为 100（最大 1000）。内部控制事件不会返回，因此一页可能少于请求的条数。\n- `current_turn_*` 字段仅在 `is_running` 为 true 时填充。本接口中 `has_unread` 恒为 `false`、`pinned_at` 恒为 `0`；如需这两项请使用 `POST /safari/session/list`。\n- `pending_messages` 列出排在当前运行轮次之后的消息；没有排队消息时为空数组。\n",
           "href": "/zh/api-reference/ai-sre/sessions/session-read-info",
           "metadata": {
             "sidebarTitle": "查看会话详情"
@@ -2316,12 +2381,12 @@
                       "entry_kind": "web",
                       "person_id": "3790925372131",
                       "team_id": 0,
-                      "is_mine": false,
+                      "is_mine": true,
                       "can_view": true,
                       "can_continue": true,
                       "can_manage": true,
                       "can_fork": true,
-                      "access_source": "manager",
+                      "access_source": "owner",
                       "share_enabled": true,
                       "share_version": 3,
                       "shared_at": 1780367971000,
@@ -2337,14 +2402,15 @@
                         "reasoning_tokens": 351
                       },
                       "current_context_tokens": 14948,
-                      "context_window": 0,
+                      "context_window": 131072,
                       "archived_at": 0,
                       "pinned_at": 0,
                       "last_event_at": 1780367992649,
                       "is_running": false,
-                      "has_unread": true,
-                      "current_turn_started_at": 0,
-                      "current_turn_active_ms": 0,
+                      "standing_tasks": 0,
+                      "has_unread": false,
+                      "current_turn_started_at": 1780367971241,
+                      "current_turn_active_ms": 21408,
                       "current_turn_wait_ms": 0,
                       "current_turn_tokens": 0
                     },
@@ -2377,7 +2443,7 @@
                       }
                     ],
                     "has_more_older": false,
-                    "suggest_init": false
+                    "pending_messages": []
                   }
                 }
               }
@@ -2429,7 +2495,7 @@
           }
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 分页使用 `p`/`limit`（最大 100）；`scope` 默认 `all`。\n- `all` 返回调用者自己的个人会话，以及调用者可访问团队的团队会话；账户管理员可见所有团队会话，但不可见他人的个人会话。\n- `team_ids` 只会收窄可见集合，不会扩大访问范围。\n- `is_running` 反映实时运行集合；`has_unread` 按调用者各自计算；`current_turn_*` 字段在此接口恒为 0 —— 仅 `session/get` 会在会话运行时计算它们。\n- `suggest_init` 是账户级的引导提示（仅当账户在任何范围内都没有知识时为 true），与列表过滤条件无关。\n",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 分页使用 `p`/`limit`（默认 20，最大 100）。调用者置顶且符合过滤条件的会话会额外插在第 1 页最前面（不占 `limit`），不会出现在后续页，也不计入 `total`。\n- `scope=all` 返回调用者创建的会话，以及绑定到调用者所在团队的会话。团队以实际成员关系为准，对所有角色一致；账户所有者和管理员在此看不到其他团队的会话。\n- `team_ids`、`person_ids`、`entry_kinds` 只会收窄可见范围。无痕会话永不列出；子智能体会话仅在 `include_subagent_sessions=true` 时返回。\n- `app_name=ai-sre` 时调用成员必须持有 AI SRE 席位，否则请求返回无许可证错误。\n- `creator_name`、`has_unread`、`pinned_at` 按调用者计算。`current_turn_*` 字段与 `context_window` 恒为 `0`，且不返回 `state`、`bound_environment`、`context_resolved`、`automation`、`has_open_tasks`；如需这些字段请使用 `POST /safari/session/get`。\n",
           "href": "/zh/api-reference/ai-sre/sessions/session-read-list",
           "metadata": {
             "sidebarTitle": "查询会话列表"
@@ -2466,13 +2532,14 @@
                         "app_name": "ai-sre",
                         "entry_kind": "web",
                         "person_id": "3790925372131",
+                        "creator_name": "Alice Chen",
                         "team_id": 0,
-                        "is_mine": false,
+                        "is_mine": true,
                         "can_view": true,
                         "can_continue": true,
                         "can_manage": true,
                         "can_fork": true,
-                        "access_source": "manager",
+                        "access_source": "owner",
                         "share_enabled": true,
                         "share_version": 3,
                         "shared_at": 1780367971000,
@@ -2493,14 +2560,14 @@
                         "pinned_at": 0,
                         "last_event_at": 1780367992649,
                         "is_running": false,
+                        "standing_tasks": 0,
                         "has_unread": true,
                         "current_turn_started_at": 0,
                         "current_turn_active_ms": 0,
                         "current_turn_wait_ms": 0,
                         "current_turn_tokens": 0
                       }
-                    ],
-                    "suggest_init": false
+                    ]
                   }
                 }
               }
@@ -2544,7 +2611,7 @@
       "post": {
         "operationId": "skill-write-delete",
         "summary": "删除技能",
-        "description": "按 ID 删除技能。",
+        "description": "软删除技能，智能体不再加载它，其名称可被重新使用。",
         "tags": [
           "AI SRE/技能"
         ],
@@ -2554,7 +2621,7 @@
           }
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **Skill 管理**（`ai-sre`） |\n\n## 使用说明\n\n- 仅为软删除：将 `status` 置为 `deleted` 并重命名该行以释放原名称供复用；技能的压缩包不会从对象存储中删除。\n- 对已删除或不存在的 `skill_id` 再次删除会返回 `ResourceNotFound`，因为查找逻辑在执行删除前就已排除已删除的行。\n- 每次调用都会记录到账户审计日志。\n",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **Skill 管理**（`ai-sre`） |\n\n## 使用说明\n\n- 需要技能的编辑权限：账户级技能（`team_id` = 0）仅账户所有者和管理员可编辑；团队技能仅该团队成员可编辑（所有者和管理员没有豁免）。否则返回 `AccessDenied`。\n- 软删除：技能被改名并从所有接口中隐藏，原名称在其作用域内可被重新使用；已存储的压缩包不会删除。\n- `skill_id` 不存在或已删除时返回 `ResourceNotFound`。\n- 每次调用都会记录到账户审计日志。\n",
           "href": "/zh/api-reference/ai-sre/skills/skill-write-delete",
           "metadata": {
             "sidebarTitle": "删除技能"
@@ -2575,15 +2642,14 @@
                       "properties": {
                         "data": {
                           "type": "null",
-                          "description": "成功时恒为 null。"
+                          "description": "成功时不返回该字段，响应体只有 `request_id`。"
                         }
                       }
                     }
                   ]
                 },
                 "example": {
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
-                  "data": null
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
             }
@@ -2633,7 +2699,7 @@
           }
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **Skill 管理**（`ai-sre`） |\n\n## 使用说明\n\n- 仅可禁用 `enabled` 状态的技能；已禁用的技能会返回 `InvalidParameter`。\n- 每次调用都会记录到账户审计日志。\n",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **Skill 管理**（`ai-sre`） |\n\n## 使用说明\n\n- 需要技能的编辑权限：账户级技能（`team_id` = 0）仅账户所有者和管理员可编辑；团队技能仅该团队成员可编辑（所有者和管理员没有豁免）。否则返回 `AccessDenied`。\n- 仅可禁用 `enabled` 状态的技能；对已禁用的技能再次禁用返回 `InvalidParameter`。\n- 每次调用都会记录到账户审计日志。\n",
           "href": "/zh/api-reference/ai-sre/skills/skill-write-disable",
           "metadata": {
             "sidebarTitle": "禁用技能"
@@ -2654,15 +2720,14 @@
                       "properties": {
                         "data": {
                           "type": "null",
-                          "description": "成功时恒为 null。"
+                          "description": "成功时不返回该字段，响应体只有 `request_id`。"
                         }
                       }
                     }
                   ]
                 },
                 "example": {
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
-                  "data": null
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
             }
@@ -2712,7 +2777,7 @@
           }
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **Skill 管理**（`ai-sre`） |\n\n## 使用说明\n\n- 仅可启用 `disabled` 状态的技能；已启用的技能会返回 `InvalidParameter`。\n- 每次调用都会记录到账户审计日志。\n",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **Skill 管理**（`ai-sre`） |\n\n## 使用说明\n\n- 需要技能的编辑权限：账户级技能（`team_id` = 0）仅账户所有者和管理员可编辑；团队技能仅该团队成员可编辑（所有者和管理员没有豁免）。否则返回 `AccessDenied`。\n- 仅可启用 `disabled` 状态的技能；对已启用的技能再次启用返回 `InvalidParameter`。\n- 每次调用都会记录到账户审计日志。\n",
           "href": "/zh/api-reference/ai-sre/skills/skill-read-enable",
           "metadata": {
             "sidebarTitle": "启用技能"
@@ -2733,15 +2798,14 @@
                       "properties": {
                         "data": {
                           "type": "null",
-                          "description": "成功时恒为 null。"
+                          "description": "成功时不返回该字段，响应体只有 `request_id`。"
                         }
                       }
                     }
                   ]
                 },
                 "example": {
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
-                  "data": null
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
             }
@@ -2791,7 +2855,7 @@
           }
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 若技能不存在或已被删除，返回 `ResourceNotFound`。\n- `can_edit` 反映团队成员关系，但读取本身不受团队限制，任意调用者均可访问。\n",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 账户内任何成员都可以按 ID 读取账户中的任意技能，包括自己不在的团队的技能；`can_edit` 表示调用者能否修改它。\n- `skill_id` 不存在或已删除时返回 `ResourceNotFound`。\n- 本接口不计算 `update_available`，恒为 `false`；如需查看市场更新请使用 `POST /safari/skill/list`。\n",
           "href": "/zh/api-reference/ai-sre/skills/skill-read-get",
           "metadata": {
             "sidebarTitle": "查看技能详情"
@@ -2855,6 +2919,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -2891,7 +2958,7 @@
           }
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 列表行中省略 `content` 字段；如需正文请单独查询某个技能。\n- `scope` 用于选择 `all`（默认）、仅 `account`、或仅 `team`，会覆盖 `include_account`；非管理员请求特定 `team_ids` 时会被静默过滤为其所属的团队。\n- `update_available` 每次调用会与市场目录比对一次；若目录加载失败，仅会隐藏该徽标，不会导致请求失败。\n",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 返回账户级技能，以及调用者所在团队的技能，按 `skill_name` 升序排列。团队以实际成员关系为准，对所有角色一致；不属于调用者的 `team_ids` 会被静默忽略。\n- `scope` 会覆盖 `include_account`：`account` 只返回账户级技能，`team` 只返回调用者所在团队的技能。\n- 列表行不返回 `content`；如需正文请调用 `POST /safari/skill/get`。\n- `update_available` 将每个市场安装的技能与当前目录比对；目录加载失败时所有行均为 `false`，请求本身不会失败。\n",
           "href": "/zh/api-reference/ai-sre/skills/skill-read-list",
           "metadata": {
             "sidebarTitle": "查询技能列表"
@@ -2958,6 +3025,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -2996,7 +3066,7 @@
           }
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **Skill 管理**（`ai-sre`） |\n\n## 使用说明\n\n- 仅 `description`、`description_en` 与 `team_id` 可编辑；技能正文需通过重新上传修改。\n- `description` 仅在非空时更新 —— 无法通过该字段清空；`description_en` 可为 null，传入空字符串即可显式清空。\n- 将 `team_id` 重新分配到不同团队时，除编辑权限外还会触发第二重授权检查，验证调用者是否可将资源指派到目标团队。\n- 每次调用都会记录到账户审计日志。\n",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **Skill 管理**（`ai-sre`） |\n\n## 使用说明\n\n- 需要技能的编辑权限：账户级技能（`team_id` = 0）仅账户所有者和管理员可编辑；团队技能仅该团队成员可编辑（所有者和管理员没有豁免）。否则返回 `AccessDenied`。\n- 只能修改 `description`、`description_en` 和 `team_id`；技能正文需上传新的压缩包修改。\n- `description` 仅在非空时修改，因此无法清空。`description_en` 只要传入就会修改；传空字符串即清空。\n- 移到团队（`team_id` > 0）要求调用者属于目标团队；移到账户级（`team_id` = 0）要求账户所有者或管理员。从市场安装的技能只能移到账户级。目标作用域内名称冲突时返回 `InvalidParameter`。\n- 每次调用都会记录到账户审计日志。\n",
           "href": "/zh/api-reference/ai-sre/skills/skill-write-update",
           "metadata": {
             "sidebarTitle": "更新技能"
@@ -3098,7 +3168,7 @@
           }
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **30 次/分钟**；**3 次/秒** |\n| 权限要求 | **Skill 管理**（`ai-sre`） |\n\n## 使用说明\n\n- 以 `multipart/form-data` 提交，包含 `file` 部分；支持的压缩包类型为 `.skill`、`.zip`、`.tar.gz`、`.tgz`，最大 100MB（超限文件会在读取正文前即被拒绝）。\n- `skill_id` + `replace=true` 会定向覆盖该指定技能，且跳过团队归属校验，因为调用者本就拥有该行。\n- 仅 `replace=true`（不带 `skill_id`）会按技能名称做 upsert；不设置 `replace` 则始终创建新技能 —— 这两条路径都要求调用者被允许向目标 `team_id` 创建资源。\n- 响应始终将 `can_edit` 标记为 `true`。\n- 每次调用都会记录到账户审计日志。\n",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **30 次/分钟**；**3 次/秒** |\n| 权限要求 | **Skill 管理**（`ai-sre`） |\n\n## 使用说明\n\n- 以 `multipart/form-data` 提交，包含 `file` 部分。支持 `.skill`、`.zip`、`.tar.gz`、`.tgz`，最大 100 MB；压缩包必须包含 frontmatter 合法的 `SKILL.md`，且声明的每个工具都必须存在。\n- 不设置 `replace` 时在 `team_id` 中新建技能；该作用域内已有同名技能时返回 `InvalidParameter`。\n- `replace=true` 且不带 `skill_id` 时覆盖 `team_id` 中的同名技能（不存在则新建）。`replace=true` 且带 `skill_id` 时覆盖该技能；压缩包中的技能名称必须与之一致，否则返回 `InvalidParameter`。\n- 在 `team_id` 中新建要求调用者属于该团队（`team_id` = 0 要求账户所有者或管理员）。覆盖要求对已有技能有编辑权限。\n- 覆盖时保留 `skill_id` 和作用域，把 `status` 重置为 `enabled`，并把 `is_modified` 置为 `true`。响应中 `can_edit` 恒为 `true`。\n- 每次调用都会记录到账户审计日志。\n",
           "href": "/zh/api-reference/ai-sre/skills/skill-write-upload",
           "metadata": {
             "sidebarTitle": "上传技能"
@@ -3200,7 +3270,7 @@
           }
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 固定返回调用者的账户范围知识——没有 `pack_id` 参数；如需团队知识请使用 `POST /safari/knowledge/pack/list`。\n- 账户知识在首次访问时惰性创建，因此有效账户调用不会返回 not-found。\n",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 固定返回调用者的账户知识，没有 `pack_id` 参数。团队知识请先用 `POST /safari/knowledge/pack/list` 查到，再用 `POST /safari/knowledge/file/list` 列出文件。\n- 账户还没有知识时，本次调用会创建一份空知识，因此有效账户调用不会返回 not-found。\n- 账户内任何成员都能读取；`pack.can_edit` 表示调用者能否修改。\n",
           "href": "/zh/api-reference/ai-sre/knowledge/knowledge-pack-read-get",
           "metadata": {
             "sidebarTitle": "查看账户知识"
@@ -3234,8 +3304,8 @@
                       "account_id": 2451002751131,
                       "scope": "account",
                       "scope_id": 2451002751131,
-                      "file_count": 17,
-                      "total_bytes": 41010,
+                      "file_count": 2,
+                      "total_bytes": 2737,
                       "version": 134,
                       "duty_version": 130,
                       "created_by": 2476444212131,
@@ -3276,6 +3346,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -3310,7 +3383,7 @@
           }
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 可见性与控制台一致：管理员可见账户知识及全部团队知识；非管理员可见账户知识及所属团队的知识，传入的 `team_ids` 会被静默过滤为其所属团队。\n- `scope` 用于选择 `all`（默认）、仅 `account` 或仅 `team`，会覆盖 `include_account`。\n- `query` 对知识 ID、范围和团队名称做大小写不敏感的子串过滤；`p`/`limit` 对过滤结果分页。\n",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 返回账户知识，以及调用者所属团队的知识。对所有调用者都一样——Owner 和管理员也看不到自己未加入团队的知识。\n- 账户知识只有在被创建后才会出现（通过 `POST /safari/knowledge/get`、不带 `pack_id` 的文件接口或 `POST /safari/knowledge/pack/ensure`）；本接口不会创建它。\n- 先按 `query` 过滤，再用 `p`/`limit` 对过滤结果分页；`total` 为过滤后的总数。`p` 与 `limit` 都不传则返回全部。\n",
           "href": "/zh/api-reference/ai-sre/knowledge/knowledge-pack-read-list",
           "metadata": {
             "sidebarTitle": "查询知识列表"
@@ -3345,8 +3418,8 @@
                         "account_id": 2451002751131,
                         "scope": "account",
                         "scope_id": 2451002751131,
-                        "file_count": 17,
-                        "total_bytes": 41010,
+                        "file_count": 2,
+                        "total_bytes": 2737,
                         "version": 134,
                         "duty_version": 130,
                         "created_by": 2476444212131,
@@ -3359,7 +3432,7 @@
                         "account_id": 2451002751131,
                         "scope": "team",
                         "scope_id": 2477033058131,
-                        "team_name": "研发团队",
+                        "team_name": "SRE Team",
                         "file_count": 4,
                         "total_bytes": 11159,
                         "version": 15,
@@ -3370,7 +3443,7 @@
                         "can_edit": true
                       }
                     ],
-                    "total": 3
+                    "total": 2
                   }
                 }
               }
@@ -3382,6 +3455,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -3421,7 +3497,7 @@
           }
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **知识管理**（`ai-sre`） |\n\n## 使用说明\n\n- 幂等：若（`scope`, `scope_id`）已存在知识，则原样返回。\n- 账户范围忽略 `scope_id`（使用账户 ID），首次创建时会自动写入默认 `DUTY.md`。\n- 创建账户范围知识需要账户 Owner/Admin 权限；在团队下创建需要是该团队成员。\n- 每次调用都会记录到账户审计日志。\n",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **知识管理**（`ai-sre`） |\n\n## 使用说明\n\n- 幂等：若（`scope`, `scope_id`）已有知识则直接返回，否则创建一份空知识。\n- `account` 范围忽略 `scope_id`；只要该知识中没有 `DUTY.md`（包括被删除后），就会写入一份默认 `DUTY.md`。返回的 `file_count`/`version` 是写入前读取的，可能尚未包含该文件。\n- `account` 范围需要账户 Owner 或管理员；`team` 范围需要是该团队成员——Owner 和管理员也不例外。\n- 每次调用都会记录到账户审计日志。\n",
           "href": "/zh/api-reference/ai-sre/knowledge/knowledge-pack-write-ensure",
           "metadata": {
             "sidebarTitle": "确保知识存在"
@@ -3450,17 +3526,18 @@
                 "example": {
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
-                    "pack_id": "kpk_kE49k3FhecfJBwutbshEEc",
+                    "pack_id": "kpk_5qRL34nKtoWM4nQVT2kHzy",
                     "account_id": 2451002751131,
-                    "scope": "account",
-                    "scope_id": 2451002751131,
-                    "file_count": 17,
-                    "total_bytes": 41010,
-                    "version": 138,
-                    "duty_version": 130,
+                    "scope": "team",
+                    "scope_id": 2477033058131,
+                    "team_name": "SRE Team",
+                    "file_count": 4,
+                    "total_bytes": 11159,
+                    "version": 15,
+                    "duty_version": 15,
                     "created_by": 2476444212131,
-                    "created_at_ms": 1778768680053,
-                    "updated_at_ms": 1786458765182,
+                    "created_at_ms": 1782201586089,
+                    "updated_at_ms": 1785462092702,
                     "can_edit": true
                   }
                 }
@@ -3513,7 +3590,7 @@
           }
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **知识管理**（`ai-sre`） |\n\n## 使用说明\n\n- `scope` 是唯一可修改的字段；不传则为空操作，返回当前知识。\n- 团队范围必须传 `scope_id`；账户范围自动使用账户 ID。\n- 目标范围已存在知识时返回 `ReferenceExist`——两份知识不会被合并。\n- 每次调用都会记录到账户审计日志。\n",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **知识管理**（`ai-sre`） |\n\n## 使用说明\n\n- `scope` 是唯一可修改的字段；不传或传入当前范围时不做修改，直接返回当前知识。\n- 调用者须能编辑知识当前所在范围（`can_edit`），并对目标范围有权限：自己所属的团队，或仅 Owner/管理员可设为 `account`。\n- 目标范围已有知识时返回 `ReferenceExist`，两份知识不会合并。文件和 `version` 随之移动，保持不变。\n- 每次调用都会记录到账户审计日志。\n",
           "href": "/zh/api-reference/ai-sre/knowledge/knowledge-pack-write-update",
           "metadata": {
             "sidebarTitle": "更新知识"
@@ -3546,7 +3623,7 @@
                     "account_id": 2451002751131,
                     "scope": "team",
                     "scope_id": 2477033058131,
-                    "team_name": "研发团队",
+                    "team_name": "SRE Team",
                     "file_count": 4,
                     "total_bytes": 11159,
                     "version": 15,
@@ -3607,7 +3684,7 @@
           }
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **知识管理**（`ai-sre`） |\n\n## 使用说明\n\n- 删除知识会同时删除其中所有文件，且不可恢复。\n- 允许删除账户范围知识；下次访问时会重新创建一份空知识。\n- 每次调用都会记录到账户审计日志。\n",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **知识管理**（`ai-sre`） |\n\n## 使用说明\n\n- 删除知识及其包含的所有文件，没有恢复接口。\n- 需要对该知识有 `can_edit` 权限：账户知识需账户 Owner 或管理员，团队知识需是该团队成员。\n- 允许删除账户知识；下一次调用 `POST /safari/knowledge/get`（或不带 `pack_id` 的文件接口）会重新创建一份空知识。\n- 每次调用都会记录到账户审计日志。\n",
           "href": "/zh/api-reference/ai-sre/knowledge/knowledge-pack-write-delete",
           "metadata": {
             "sidebarTitle": "删除知识"
@@ -3687,7 +3764,7 @@
           }
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 不传 `pack_id` 时默认查询调用者的账户范围知识（不存在时惰性创建）。\n- 读取团队范围知识需要是该团队成员。\n- `p`/`limit` 参数会被接受，但当前实现始终返回完整文件列表。\n",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 不传 `pack_id` 时查询调用者的账户知识（不存在时创建一份空知识）。`pack_id` 不存在时返回 `ResourceNotFound`。\n- 账户知识所有成员可读；团队知识仅该团队成员可读。\n- `p`/`limit` 会被接受但不生效：始终返回全部文件。读取文件内容请用 `POST /safari/knowledge/file/get`。\n",
           "href": "/zh/api-reference/ai-sre/knowledge/knowledge-file-read-list",
           "metadata": {
             "sidebarTitle": "查询知识文件列表"
@@ -3738,7 +3815,8 @@
                         "updated_at_ms": 1784800003394
                       }
                     ],
-                    "total": 17
+                    "total": 2,
+                    "version": 134
                   }
                 }
               }
@@ -3750,6 +3828,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -3786,7 +3867,7 @@
           }
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 文件内容通过 `content_b64`（Base64）返回；知识文件保证为 UTF-8 文本。\n- 不传 `pack_id` 时默认账户范围知识；读取团队范围知识需要是该团队成员。\n- 文件不存在时返回 `ResourceNotFound`（HTTP 400）。\n",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 文件内容以 Base64 编码放在 `content_b64` 中返回。\n- 路径下没有文件不算错误：响应中 `file` 为 `null`、`content_b64` 为空，并带上当前 `version`。`pack_id` 不存在时返回 `ResourceNotFound`。\n- 不传 `pack_id` 时读取账户知识（所有成员可读）；团队知识仅该团队成员可读。\n- 保留返回的 `version`，写回文件时作为 `expected_version` 传入，可避免覆盖他人的修改。\n",
           "href": "/zh/api-reference/ai-sre/knowledge/knowledge-file-read-get",
           "metadata": {
             "sidebarTitle": "获取知识文件"
@@ -3825,7 +3906,8 @@
                       "updated_by": 2476444212131,
                       "updated_at_ms": 1786458764961
                     },
-                    "content_b64": "IyBPcGVuQVBJIGV4YW1wbGUKVGVtcCBmaWxlIGZvciBBUEkgZG9jcyBleGFtcGxlLgo="
+                    "content_b64": "IyBPcGVuQVBJIGV4YW1wbGUKVGVtcCBmaWxlIGZvciBBUEkgZG9jcyBleGFtcGxlLgo=",
+                    "version": 135
                   }
                 }
               }
@@ -3837,6 +3919,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -3873,7 +3958,7 @@
           }
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **知识管理**（`ai-sre`） |\n\n## 使用说明\n\n- 文件内容以 JSON 字段 `content_b64` 中的 Base64 文本上传——不是 multipart 上传。\n- 写入已存在的 `rel_path` 会覆盖原文件；`content_type` 留空时按扩展名推断（`.md` → `text/markdown`）。\n- 内容解码后必须是合法的 UTF-8 文本，二进制内容会被拒绝并返回 `InvalidParameter`。\n- 编辑账户范围知识需要账户 Owner/Admin 权限；编辑团队知识需要是该团队成员。\n- 每次调用都会记录到账户审计日志。\n",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **知识管理**（`ai-sre`） |\n\n## 使用说明\n\n- 文件内容以 Base64 文本放在 JSON 字段 `content_b64` 中——不是 multipart 上传。写入已存在的 `rel_path` 会覆盖原文件。\n- 限制：单个文件不超过 1 MiB（`DUTY.md` 不超过 32 KiB），每份知识最多 100 个文件、总计 5 MiB。内容必须是不含 NUL 字节的 UTF-8 文本。超出限制或 `rel_path` 不合法时返回 `InvalidParameter`。\n- 传入 `expected_version`（来自上一次读取或写入）可确保期间无人修改知识时才写入；不一致时返回 HTTP 200，`status` 为 `conflict`，不写入任何内容。\n- 每次成功写入都会让知识 `version` 加 1；写入 `DUTY.md` 还会更新 `duty_version`。\n- 编辑账户知识需要账户 Owner 或管理员；编辑团队知识需要是该团队成员。\n- 每次调用都会记录到账户审计日志。\n",
           "href": "/zh/api-reference/ai-sre/knowledge/knowledge-file-write-put",
           "metadata": {
             "sidebarTitle": "上传知识文件"
@@ -3902,6 +3987,7 @@
                 "example": {
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
+                    "status": "ok",
                     "file": {
                       "file_id": "kfl_gctXKRG45aFQGgxSFr59WY",
                       "pack_id": "kpk_kE49k3FhecfJBwutbshEEc",
@@ -3911,7 +3997,8 @@
                       "checksum": "a0775f9b3f392cd0560b21ad2f579ae4a5d6b1282b9eb145688ba2de717a816d",
                       "updated_by": 2476444212131,
                       "updated_at_ms": 1786458764961
-                    }
+                    },
+                    "version": 135
                   }
                 }
               }
@@ -3943,7 +4030,8 @@
               "example": {
                 "rel_path": "tmp/openapi-example.md",
                 "content_b64": "IyBPcGVuQVBJIGV4YW1wbGUKVGVtcCBmaWxlIGZvciBBUEkgZG9jcyBleGFtcGxlLgo=",
-                "content_type": "text/markdown"
+                "content_type": "text/markdown",
+                "expected_version": 134
               }
             }
           }
@@ -3964,7 +4052,7 @@
           }
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **知识管理**（`ai-sre`） |\n\n## 使用说明\n\n- 删除是幂等的——删除不存在的文件也会成功。\n- 当其他知识文件仍引用目标文件时，删除失败并返回 `ReferenceExist`（附带引用方列表）；设置 `force` 可强制删除（引用方以警告形式返回）。\n- 不传 `pack_id` 时默认账户范围知识；编辑账户知识需要账户 Owner/Admin 权限，编辑团队知识需要是该团队成员。\n- 每次调用都会记录到账户审计日志。\n",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **知识管理**（`ai-sre`） |\n\n## 使用说明\n\n- 删除不存在的文件也会成功，`status` 为 `ok`。\n- 知识中其他文件仍通过 @ref 引用目标文件时，删除失败并返回 `ReferenceExist`（列出引用方）；设置 `force` 可强制删除（引用方放在 `warnings` 中返回）。\n- 传入 `expected_version` 可确保自上次读取后无人修改知识时才删除；不一致时返回 HTTP 200，`status` 为 `conflict`。\n- 不传 `pack_id` 时操作账户知识；编辑账户知识需要账户 Owner 或管理员，编辑团队知识需要是该团队成员。\n- 每次调用都会记录到账户审计日志。\n",
           "href": "/zh/api-reference/ai-sre/knowledge/knowledge-file-write-delete",
           "metadata": {
             "sidebarTitle": "删除知识文件"
@@ -3992,7 +4080,10 @@
                 },
                 "example": {
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
-                  "data": {}
+                  "data": {
+                    "status": "ok",
+                    "version": 136
+                  }
                 }
               }
             }
@@ -4042,7 +4133,7 @@
           }
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- `scope` 可选 `all`（默认 —— 调用者自己的个人产物 + 其所属全部团队的产物）、`personal`（仅自己创建的）、`team`（仅所属团队的团队产物）。\n- `team_ids` 可在可见范围内进一步限定团队 —— 调用者不属于的团队不会有任何返回。\n- 默认按 `updated_at` 倒序；设置 `orderby` 为 `created_at` 可更换排序字段，`asc: true` 改为升序。\n- 使用 `app_key` 调用时，可见范围按 key 所属成员的身份计算 —— 返回该成员的个人产物及其所在团队的产物。\n",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- `scope` 可选 `all`（默认：调用者自己的个人产物加上其所属全部团队的产物）、`personal`（仅调用者自己的个人产物）、`team`（仅调用者所属团队拥有的产物）。未知取值按 `all` 处理。\n- 可见范围按 `app_key` 所属成员的身份和实际团队成员关系计算，账户所有者和管理员在此也不会多看到产物。要按 ID 打开账户内任意产物，请用 `/safari/artifact/gallery/get`。\n- 调用者置顶的产物总排在最前；其余默认按 `updated_at` 倒序，可通过 `orderby`/`asc` 调整。\n",
           "href": "/zh/api-reference/ai-sre/artifacts/artifact-read-list",
           "metadata": {
             "sidebarTitle": "查询产物列表"
@@ -4089,40 +4180,41 @@
                     "items": [
                       {
                         "artifact_id": "art_VnfrWic8UbB9q3EfYR4Gmg",
-                        "title": "SK 海力士 2026 Q2 财报深度分析",
-                        "team_id": 2477033058131,
-                        "team_name": "研发团队",
-                        "person_id": 2476444212131,
-                        "creator_name": "yushuangyu",
+                        "title": "支付接口延迟复盘报告",
+                        "team_id": 4012,
+                        "team_name": "SRE 团队",
+                        "person_id": 2476001,
+                        "creator_name": "张伟",
                         "is_mine": true,
                         "can_edit": true,
                         "session_id": "sess_VCbVPZrq9YoyBu8sNCmqUy",
-                        "session_title": "分析海力士财报并发布报告",
+                        "session_title": "排查支付接口延迟突增",
                         "file_id": "pf_SdhEA5fbZJGnHzwrNJMMSB",
-                        "name": "sk-hynix-q2-2026-report.html",
+                        "name": "checkout-latency-postmortem.html",
                         "size": 18996,
                         "content_type": "text/html",
                         "created_at": 1785293373899,
                         "updated_at": 1785747910219,
+                        "pinned_at": 1785750000000,
                         "share_enabled": true,
                         "public_url": "https://console.flashcat.cloud/share/artifact/art_VnfrWic8UbB9q3EfYR4Gmg",
-                        "shared_by": 3790925372131,
+                        "shared_by": 2476001,
                         "shared_at": 1785747928665,
                         "share_file_id": "pf_SdhEA5fbZJGnHzwrNJMMSB"
                       },
                       {
                         "artifact_id": "art_CWQzDU2PXSRJvKDhQbuMKu",
-                        "title": "rum_recommendation",
-                        "team_id": 2477033058131,
-                        "team_name": "研发团队",
-                        "person_id": 3790925372131,
-                        "creator_name": "牛伟利",
+                        "title": "告警降噪周报",
+                        "team_id": 4012,
+                        "team_name": "SRE 团队",
+                        "person_id": 2476002,
+                        "creator_name": "李娜",
                         "is_mine": false,
                         "can_edit": true,
                         "session_id": "sess_QXUC9C2PYWP5EE7vETR3UD",
-                        "session_title": "生成 RUM 文档多格式",
+                        "session_title": "汇总上周告警噪声",
                         "file_id": "pf_Jnc4E5YBcWLGzunB4ntP9s",
-                        "name": "rum_recommendation.pdf",
+                        "name": "alert-noise-weekly.pdf",
                         "size": 137107,
                         "content_type": "application/pdf",
                         "created_at": 1785229432881,
@@ -4141,6 +4233,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -4154,7 +4249,7 @@
       "post": {
         "operationId": "artifact-read-get",
         "summary": "获取产物详情",
-        "description": "根据产物 ID 获取产物详情。",
+        "description": "按 ID 获取单个已发布产物，包括来源文件、归属和公开分享状态。",
         "tags": [
           "AI SRE/产物"
         ],
@@ -4164,7 +4259,7 @@
           }
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 可见范围为整个账号：任何有效 `app_key` 都能读取账号内任意产物。`is_mine` 和 `can_edit` 相对于 key 所属成员计算。\n- 当 `share_enabled` 为 true 且 `file_id` 与 `share_file_id` 不一致时，公开快照已过期 —— 调用 `/safari/artifact/gallery/share/sync` 刷新。\n",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 账户内任何成员都可按 ID 读取任意产物，包括其他成员的个人产物；`is_mine` 和 `can_edit` 按 `app_key` 所属成员计算。\n- 产物不存在或已移除时返回 `ResourceNotFound`。\n- 当 `share_enabled` 为 true 且 `file_id` 与 `share_file_id` 不一致时，公开快照已过期，可调用 `/safari/artifact/gallery/share/sync` 刷新。\n",
           "href": "/zh/api-reference/ai-sre/artifacts/artifact-read-get",
           "metadata": {
             "sidebarTitle": "获取产物详情"
@@ -4207,24 +4302,25 @@
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "artifact_id": "art_VnfrWic8UbB9q3EfYR4Gmg",
-                    "title": "SK 海力士 2026 Q2 财报深度分析",
-                    "team_id": 2477033058131,
-                    "team_name": "研发团队",
-                    "person_id": 2476444212131,
-                    "creator_name": "yushuangyu",
+                    "title": "支付接口延迟复盘报告",
+                    "team_id": 4012,
+                    "team_name": "SRE 团队",
+                    "person_id": 2476001,
+                    "creator_name": "张伟",
                     "is_mine": true,
                     "can_edit": true,
                     "session_id": "sess_VCbVPZrq9YoyBu8sNCmqUy",
-                    "session_title": "分析海力士财报并发布报告",
+                    "session_title": "排查支付接口延迟突增",
                     "file_id": "pf_SdhEA5fbZJGnHzwrNJMMSB",
-                    "name": "sk-hynix-q2-2026-report.html",
+                    "name": "checkout-latency-postmortem.html",
                     "size": 18996,
                     "content_type": "text/html",
                     "created_at": 1785293373899,
                     "updated_at": 1785747910219,
+                    "pinned_at": 1785750000000,
                     "share_enabled": true,
                     "public_url": "https://console.flashcat.cloud/share/artifact/art_VnfrWic8UbB9q3EfYR4Gmg",
-                    "shared_by": 3790925372131,
+                    "shared_by": 2476001,
                     "shared_at": 1785747928665,
                     "share_file_id": "pf_SdhEA5fbZJGnHzwrNJMMSB"
                   }
@@ -4238,6 +4334,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -4261,7 +4360,7 @@
           }
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 单次最多传入 50 个 `file_ids`；重复和空字符串会被忽略。\n- 没有已发布产物的文件不会出现在 `items` 中 —— 按回显的 `file_id` 对应结果。\n",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 用于判断会话中产出的文件是否已在产物库中，例如在调用 `/safari/artifact/gallery/publish-from-file` 之前。\n- 按文件所属会话和工作区路径匹配，而不是按精确的 `file_id`：已被重新发布的文件的旧版本也会返回当前产物。\n- 没有已发布产物的文件、以及账户内不存在的 ID 不会出现在 `items` 中；请按回显的 `file_id` 对应结果。\n",
           "href": "/zh/api-reference/ai-sre/artifacts/artifact-read-get-file-state",
           "metadata": {
             "sidebarTitle": "查询文件发布状态"
@@ -4310,7 +4409,7 @@
                       {
                         "file_id": "pf_SdhEA5fbZJGnHzwrNJMMSB",
                         "artifact_id": "art_VnfrWic8UbB9q3EfYR4Gmg",
-                        "title": "SK 海力士 2026 Q2 财报深度分析",
+                        "title": "支付接口延迟复盘报告",
                         "gallery_path": "/ai-sre/artifacts/art_VnfrWic8UbB9q3EfYR4Gmg"
                       }
                     ]
@@ -4325,6 +4424,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -4348,7 +4450,7 @@
           }
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 两个链接在 `expires_in` 秒（300 秒）后过期，需重新签发获取新链接。\n- 返回的是相对链接 —— 使用前拼接 `https://api.flashcat.cloud`，然后以 `GET /safari/artifact/stream` 访问。\n- 签名令牌与调用账号及 app_key 所属成员身份绑定 —— 链接泄露给其他账号或成员不可用。\n",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 账户内已发布产物的文件都可签发；其他会话文件需要调用者能访问来源会话（或提供有效的 `share_token`）。文件不存在和无权访问都返回 `ResourceNotFound`。\n- 两个链接在 `expires_in` 秒（300 秒）后过期，需重新签发获取新链接。\n- 返回的是相对链接：拼接 `https://api.flashcat.cloud` 后通过 `GET /safari/artifact/stream` 访问，且须以签发时的同一成员身份认证。令牌与账户和该成员绑定，其他人无法使用。\n",
           "href": "/zh/api-reference/ai-sre/artifacts/artifact-read-sign",
           "metadata": {
             "sidebarTitle": "签发文件访问链接"
@@ -4390,10 +4492,10 @@
                 "example": {
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
-                    "download_url": "/safari/artifact/stream?mode=download&t=cGZfU2RoRUE1ZmJaSkduSHp3ck5KTU1TQnxzZXNzX1ZDYlZQWnJxOVlveUJ1OHNOQ21xVXl8MjQ1MTAwMjc1MTEzMXwyNDc2NDQ0MjEyMTMxfDB8MHwxNzg4NTI5NjI2NTU0.hPQHab0MBNbnrHYwc6VwDJbGonIamfWUr0yeSmLHYAs",
-                    "preview_url": "/safari/artifact/stream?mode=preview&t=cGZfU2RoRUE1ZmJaSkduSHp3ck5KTU1TQnxzZXNzX1ZDYlZQWnJxOVlveUJ1OHNOQ21xVXl8MjQ1MTAwMjc1MTEzMXwyNDc2NDQ0MjEyMTMxfDB8MHwxNzg4NTI5NjI2NTU0.hPQHab0MBNbnrHYwc6VwDJbGonIamfWUr0yeSmLHYAs",
+                    "download_url": "/safari/artifact/stream?mode=download&t=eyJmaWxlX2lkIjoicGZfU2RoRUE1ZmJaSkduSHp3ck5KTU1TQiJ9.c2lnbmF0dXJl",
+                    "preview_url": "/safari/artifact/stream?mode=preview&t=eyJmaWxlX2lkIjoicGZfU2RoRUE1ZmJaSkduSHp3ck5KTU1TQiJ9.c2lnbmF0dXJl",
                     "expires_in": 300,
-                    "name": "sk-hynix-q2-2026-report.html",
+                    "name": "checkout-latency-postmortem.html",
                     "size": 18996,
                     "content_type": "text/html"
                   }
@@ -4407,6 +4509,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -4430,7 +4535,7 @@
           }
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **100 次/分钟**；**10 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 成功响应有两种形式：302 重定向到短期有效的对象存储预签名 URL（存储在 S3 兼容存储中的文件），或 200 二进制流（托管在自托管 runner 上的文件）。请跟随重定向。\n- 响应携带 `Cache-Control: private, no-store` —— 网关不会缓存。\n",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 使用 `/safari/artifact/sign` 返回的完整链接，并以签发时同一成员的 `app_key` 认证。令牌过期或不属于当前成员时返回 `ResourceNotFound`。\n- 存放在对象存储中的文件返回 `302`，跳转到 5 分钟内有效的预签名 URL，请跟随重定向。`download` 模式下的 CSV 文件，以及存放在 runner 上的文件，直接以 `200` 返回内容。\n- CSV 文件在 `download` 模式下会补上 UTF-8 BOM（原本没有时）并设置 `Content-Type: text/csv; charset=utf-8`，以便表格软件正确打开。\n- 存放在 runner 上的文件，若 runner 已不可用则返回 `410` 和纯文本提示；需重新运行任务生成文件。\n- 响应携带 `Cache-Control: private, no-store`。\n",
           "href": "/zh/api-reference/ai-sre/artifacts/artifact-read-stream",
           "metadata": {
             "sidebarTitle": "下载或预览文件"
@@ -4463,7 +4568,7 @@
         ],
         "responses": {
           "200": {
-            "description": "文件内容流。当文件托管在自托管 runner 上时由服务端代理返回，Content-Disposition 随 `mode` 变化。",
+            "description": "文件内容。存放在 runner 上的文件和 `download` 模式下的 CSV 文件直接返回内容。`Content-Disposition` 按 `mode` 为 `attachment` 或 `inline`。",
             "content": {
               "application/octet-stream": {
                 "schema": {
@@ -4474,7 +4579,28 @@
             }
           },
           "302": {
-            "description": "当文件存储在 S3 兼容存储中时，302 重定向到短期有效的预签名 URL。请跟随 `Location` 头，无响应体。"
+            "description": "重定向到 5 分钟内有效的对象存储预签名 URL（存放在对象存储中的文件）。URL 在 `Location` 响应头中。",
+            "headers": {
+              "Location": {
+                "description": "对象存储预签名 URL。",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            }
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "410": {
+            "description": "存放该文件的 runner 已不可用，响应体为纯文本提示。需重新运行任务生成文件。",
+            "content": {
+              "text/plain": {
+                "schema": {
+                  "type": "string"
+                }
+              }
+            }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
@@ -4505,7 +4631,7 @@
           }
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 允许的文件类型：HTML/Markdown、图片、PDF、文本/数据/代码文件以及 zip/tar 压缩包（按扩展名判断）。超过 16 MiB 的文件会被拒绝。\n- 发布按（来源会话 + 工作区路径）做 upsert —— 重复发布同一文件会替换产物内容并使用新的 `file_id`，已有的公开快照会因此过期，需执行分享同步刷新。\n- 产物继承来源会话的个人/团队空间；如需调整，发布后调用 `/safari/artifact/gallery/update` 转移。\n- 每次调用都会记录到账户审计日志。\n",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 能看到该文件的账户成员都可以发布。若该文件路径已有已发布产物，再次发布会替换该产物，需要对其有 `can_edit` 权限。\n- 允许的文件类型：HTML/Markdown、图片、PDF、文本/数据/代码文件以及 zip/tar 压缩包（按扩展名判断）。其他类型、超过 16 MiB 的文件、以及已无法取回的文件（runner 离线或文件过期）返回 `InvalidParameter`。\n- 发布按（来源会话 + 工作区路径）做 upsert：再次发布会以新的 `file_id` 替换标题和内容，`artifact_id` 不变，已有的公开快照因此过期，需同步刷新。再次发布已移除的产物会以同一 `artifact_id` 恢复，且分享处于关闭状态。\n- 新产物的创建者和个人/团队空间取自来源会话（会话所有者及其团队）；如需调整，发布后调用 `/safari/artifact/gallery/update`。\n- 每次调用都会记录到账户审计日志。\n",
           "href": "/zh/api-reference/ai-sre/artifacts/artifact-write-publish",
           "metadata": {
             "sidebarTitle": "发布文件为产物"
@@ -4520,7 +4646,7 @@
               },
               "example": {
                 "file_id": "pf_SdhEA5fbZJGnHzwrNJMMSB",
-                "title": "SK 海力士 2026 Q2 财报深度分析"
+                "title": "支付接口延迟复盘报告"
               }
             }
           }
@@ -4549,7 +4675,7 @@
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "artifact_id": "art_VnfrWic8UbB9q3EfYR4Gmg",
-                    "title": "SK 海力士 2026 Q2 财报深度分析",
+                    "title": "支付接口延迟复盘报告",
                     "gallery_path": "/ai-sre/artifacts/art_VnfrWic8UbB9q3EfYR4Gmg"
                   }
                 }
@@ -4562,6 +4688,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -4585,7 +4714,7 @@
           }
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 仅更新传入的字段 —— 不传 `title` 或 `team_id` 则对应字段保持不变。\n- `team_id: 0` 表示转为个人产物（仅创建者可管理）；传入大于 0 的 `team_id` 时，调用者（`app_key` 调用时为 key 所属成员）必须是该团队成员。\n- 返回更新后的完整产物。\n- 每次调用都会记录到账户审计日志。\n",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 仅更新传入的字段；不传 `title` 或 `team_id` 则保持不变。\n- 需要对该产物有 `can_edit` 权限（创建者、归属团队的任一成员，或能管理来源会话的成员），否则返回 `AccessDenied`。\n- `team_id: 0`（转为个人产物）仅创建者本人可执行；传入大于 0 的 `team_id` 时，调用者（`app_key` 调用时为 key 所属成员）必须是该团队成员。\n- 返回更新后的完整产物。\n- 每次调用都会记录到账户审计日志。\n",
           "href": "/zh/api-reference/ai-sre/artifacts/artifact-write-update",
           "metadata": {
             "sidebarTitle": "更新产物"
@@ -4600,7 +4729,7 @@
               },
               "example": {
                 "artifact_id": "art_VnfrWic8UbB9q3EfYR4Gmg",
-                "title": "SK 海力士 2026 Q2 财报深度分析（终稿）"
+                "title": "支付接口延迟复盘报告（终稿）"
               }
             }
           }
@@ -4629,24 +4758,25 @@
                   "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                   "data": {
                     "artifact_id": "art_VnfrWic8UbB9q3EfYR4Gmg",
-                    "title": "SK 海力士 2026 Q2 财报深度分析（终稿）",
-                    "team_id": 2477033058131,
-                    "team_name": "研发团队",
-                    "person_id": 2476444212131,
-                    "creator_name": "yushuangyu",
+                    "title": "支付接口延迟复盘报告（终稿）",
+                    "team_id": 4012,
+                    "team_name": "SRE 团队",
+                    "person_id": 2476001,
+                    "creator_name": "张伟",
                     "is_mine": true,
                     "can_edit": true,
                     "session_id": "sess_VCbVPZrq9YoyBu8sNCmqUy",
-                    "session_title": "分析海力士财报并发布报告",
+                    "session_title": "排查支付接口延迟突增",
                     "file_id": "pf_SdhEA5fbZJGnHzwrNJMMSB",
-                    "name": "sk-hynix-q2-2026-report.html",
+                    "name": "checkout-latency-postmortem.html",
                     "size": 18996,
                     "content_type": "text/html",
                     "created_at": 1785293373899,
                     "updated_at": 1785829000000,
+                    "pinned_at": 1785750000000,
                     "share_enabled": true,
                     "public_url": "https://console.flashcat.cloud/share/artifact/art_VnfrWic8UbB9q3EfYR4Gmg",
-                    "shared_by": 3790925372131,
+                    "shared_by": 2476001,
                     "shared_at": 1785747928665,
                     "share_file_id": "pf_SdhEA5fbZJGnHzwrNJMMSB"
                   }
@@ -4660,6 +4790,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -4683,7 +4816,7 @@
           }
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 该操作只是从产物库移除，不会删除文件本身 —— 来源文件仍保留在会话中，可再次发布。\n- 如果产物已开启公开分享，公开内容会在同一操作中被销毁，公开链接立即失效。\n- 每次调用都会记录到账户审计日志。\n",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 该操作只是从产物库移除，不删除文件本身。文件仍保留在来源会话中，可再次发布，再次发布会恢复同一个 `artifact_id`。\n- 需要对该产物有 `can_edit` 权限（创建者、归属团队的任一成员，或能管理来源会话的成员），否则返回 `AccessDenied`。\n- 如果已开启公开分享，公开内容会在同一操作中删除，链接随即失效。所有成员对该产物的置顶也会被清除。\n- 若来源会话已被删除，文件本身会在产物移除 30 天后被永久删除。\n- 每次调用都会记录到账户审计日志。\n",
           "href": "/zh/api-reference/ai-sre/artifacts/artifact-write-delete",
           "metadata": {
             "sidebarTitle": "从产物库移除产物"
@@ -4717,15 +4850,14 @@
                       "properties": {
                         "data": {
                           "type": "null",
-                          "description": "成功时恒为 null。"
+                          "description": "成功时不返回该字段，响应体只有 `request_id`。"
                         }
                       }
                     }
                   ]
                 },
                 "example": {
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
-                  "data": null
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
             }
@@ -4736,6 +4868,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -4759,7 +4894,7 @@
           }
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 公开链接是匿名的 —— 任何拿到链接的人都可以查看内容，链接也可能被继续转发。内容会被复制到公开 CDN 对象上，访问链接时不经过本 API。\n- 幂等：对已分享的产物重复开启会原样返回已有链接；撤销后重新开启也会得到同一个链接 —— 链接以产物 ID 为标识。\n- 超过 16 MiB 的产物无法分享，调用返回 `InvalidParameter`。\n- 分享是内容快照：之后重新发布产物不会自动更新公开内容，需调用 `/safari/artifact/gallery/share/sync` 同步。\n- 每次调用都会记录到账户审计日志。\n",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 公开链接是匿名的：任何拿到链接的人都可以查看内容，链接也可能被继续转发。内容会被复制到公开 CDN 对象上，访问链接时不经过本 API。\n- 需要对该产物有 `can_edit` 权限（创建者、归属团队的任一成员，或能管理来源会话的成员），否则返回 `AccessDenied`。\n- 幂等：对已分享的产物重复开启会原样返回当前状态；撤销后重新开启会得到同一个链接，因为链接以产物 ID 为标识。\n- 超过 16 MiB 的产物无法分享，调用返回 `InvalidParameter`。未配置公开分享的部署环境中，调用返回 `InternalError`。\n- 分享是内容快照：之后重新发布产物不会自动更新公开内容，需调用 `/safari/artifact/gallery/share/sync` 同步。\n- 每次调用都会记录到账户审计日志。\n",
           "href": "/zh/api-reference/ai-sre/artifacts/artifact-write-share-enable",
           "metadata": {
             "sidebarTitle": "开启公开分享"
@@ -4804,7 +4939,7 @@
                     "artifact_id": "art_VnfrWic8UbB9q3EfYR4Gmg",
                     "share_enabled": true,
                     "public_url": "https://console.flashcat.cloud/share/artifact/art_VnfrWic8UbB9q3EfYR4Gmg",
-                    "shared_by": 2476444212131,
+                    "shared_by": 2476001,
                     "shared_at": 1785747928665
                   }
                 }
@@ -4817,6 +4952,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -4840,7 +4978,7 @@
           }
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 未开启分享时调用返回 `InvalidParameter` —— 请先开启分享。\n- 公开链接不变，仅更新快照内容和 `shared_at`。\n- 可通过产物详情中 `share_file_id != file_id` 判断快照是否过期，再决定是否同步。\n- 每次调用都会记录到账户审计日志。\n",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 未开启分享时返回 `InvalidParameter`，请先开启分享。未配置公开分享的部署环境中，调用返回 `InternalError`。\n- 需要对该产物有 `can_edit` 权限（创建者、归属团队的任一成员，或能管理来源会话的成员），否则返回 `AccessDenied`。\n- 公开链接不变，只刷新快照内容和 `shared_at`；`shared_by` 仍为开启分享的成员。\n- 可通过产物详情中 `share_file_id != file_id` 判断快照是否过期，再决定是否同步。\n- 每次调用都会记录到账户审计日志。\n",
           "href": "/zh/api-reference/ai-sre/artifacts/artifact-write-share-sync",
           "metadata": {
             "sidebarTitle": "更新公开分享快照"
@@ -4885,7 +5023,7 @@
                     "artifact_id": "art_VnfrWic8UbB9q3EfYR4Gmg",
                     "share_enabled": true,
                     "public_url": "https://console.flashcat.cloud/share/artifact/art_VnfrWic8UbB9q3EfYR4Gmg",
-                    "shared_by": 2476444212131,
+                    "shared_by": 2476001,
                     "shared_at": 1785829900000
                   }
                 }
@@ -4898,6 +5036,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -4921,7 +5062,7 @@
           }
         ],
         "x-mint": {
-          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 公开 CDN 对象会被删除，链接随即失效；产物未开启分享时该操作为空操作。\n- 之后重新开启分享会返回同一个 `public_url` —— 链接以产物 ID 为标识，撤销并不能用于更换链接。\n- 每次调用都会记录到账户审计日志。\n",
+          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 公开 CDN 对象会被删除，链接随即失效。产物未开启分享时直接成功，不做任何变更。\n- 需要对该产物有 `can_edit` 权限（创建者、归属团队的任一成员，或能管理来源会话的成员），否则返回 `AccessDenied`。\n- 之后重新开启分享会返回同一个 `public_url`：链接以产物 ID 为标识，撤销并不能更换链接。\n- 每次调用都会记录到账户审计日志。\n",
           "href": "/zh/api-reference/ai-sre/artifacts/artifact-write-share-revoke",
           "metadata": {
             "sidebarTitle": "撤销公开分享"
@@ -4955,15 +5096,14 @@
                       "properties": {
                         "data": {
                           "type": "null",
-                          "description": "成功时恒为 null。"
+                          "description": "成功时不返回该字段，响应体只有 `request_id`。"
                         }
                       }
                     }
                   ]
                 },
                 "example": {
-                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
-                  "data": null
+                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
                 }
               }
             }
@@ -4974,6 +5114,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
           "429": {
             "$ref": "#/components/responses/TooManyRequests"
           },
@@ -4990,7 +5133,7 @@
         "type": "apiKey",
         "in": "query",
         "name": "app_key",
-        "description": "在 Flashduty 控制台 账户 → APP Key 中签发的 app_key。调用任何公开 API 时都必须携带。它等同于所属账户的身份凭证，请妥善保管。"
+        "description": "在 Flashduty 控制台 我的 → APP Key 中创建的 APP Key。可通过 query 参数 `app_key` 或请求头 `Fd-App-Key` 传入。实际可访问范围是该 APP Key 的权限范围与创建者当前角色权限的交集，请妥善保管。"
       },
       "AutomationTriggerBearerAuth": {
         "type": "http",
@@ -5043,7 +5186,7 @@
         }
       },
       "Forbidden": {
-        "description": "app_key 有效但没有执行该操作的权限。",
+        "description": "app_key 有效，但其权限范围或创建者角色不允许该操作或该对象。",
         "content": {
           "application/json": {
             "schema": {
@@ -5064,7 +5207,7 @@
         }
       },
       "TooManyRequests": {
-        "description": "命中限流。可能是全局 API 限流或账户级限流。",
+        "description": "触发频率限制（账户级限制或该接口的平台级上限）。请等待响应头 `Flashcat-Request-Rate-Limit-Delay` 给出的秒数后重试。",
         "content": {
           "application/json": {
             "schema": {
@@ -5082,6 +5225,15 @@
               }
             }
           }
+        },
+        "headers": {
+          "Flashcat-Request-Rate-Limit-Delay": {
+            "description": "距当前限流窗口重置的秒数。请求被网关全局保护限流拒绝时不返回该响应头。",
+            "schema": {
+              "type": "integer",
+              "minimum": 0
+            }
+          }
         }
       },
       "ServerError": {
@@ -5113,7 +5265,7 @@
         "properties": {
           "agent_name": {
             "type": "string",
-            "description": "智能体显示名称。",
+            "description": "智能体显示名称，会话中按此名称调用智能体。不能包含 `@`，不能是 `general` 或 `explore`，且在其作用域（账户级或单个团队）内唯一。",
             "maxLength": 128
           },
           "instructions": {
@@ -5123,11 +5275,11 @@
           },
           "card_url": {
             "type": "string",
-            "description": "远程智能体卡片的 URL。必须是 host 非空的绝对 `http` 或 `https` URL；可达性由执行环境在运行时验证，创建时不检查。"
+            "description": "远程智能体卡片的 URL。必须是 host 非空的绝对 `http` 或 `https` URL；不带路径时解析为 `/.well-known/agent-card.json`。若有在线执行环境，会拉取卡片并要求其声明 A2A 1.x 的 `JSONRPC` 或 `HTTP+JSON` 接口。"
           },
           "auth_type": {
             "type": "string",
-            "description": "访问远程智能体的认证类型：`none`（省略时默认）、`api_key` 或 `bearer`。",
+            "description": "使用共享凭据访问远程智能体时的认证方式：\n- `none`：不发送凭据请求头。\n- `api_key`：把 `auth_config.api_key` 放进 `auth_config.header` 指定名称的请求头。\n- `bearer`：发送 `Authorization: Bearer <auth_config.token>`。\n\n省略时存为空字符串，效果同 `none`。",
             "enum": [
               "none",
               "api_key",
@@ -5139,7 +5291,7 @@
             "additionalProperties": {
               "type": "string"
             },
-            "description": "认证配置键值，例如 API key 或 bearer token。键名疑似凭据（包含 KEY、SECRET、TOKEN、PASSWORD 等）的值在响应中会被脱敏。"
+            "description": "共享凭据键值：`auth_type=api_key` 时使用 `header` 和 `api_key`，`auth_type=bearer` 时使用 `token`。`api_key`、`token`、`client_secret` 的值加密存储，响应中脱敏。"
           },
           "streaming": {
             "type": "boolean",
@@ -5159,7 +5311,13 @@
           },
           "auth_mode": {
             "type": "string",
-            "description": "认证模式：`shared`（默认）所有用户共享一份凭证；`per_user_secret` 需要 `secret_schema.header_name`；`per_user_oauth` 为每个用户单独进行 OAuth。"
+            "description": "凭据由谁提供：\n- `shared`（默认，空值等同）：使用保存在智能体上的一份凭据（`auth_type` + `auth_config`），所有调用者共用。\n- `per_user_secret`：每位用户各自保存密钥，放在 `secret_schema.header_name` 指定的请求头中发送。\n- `per_user_oauth`：每位用户各自完成 OAuth 授权，首次使用时完成发现与客户端注册。\n\n`per_user_secret` 要求 `secret_schema` 带非空的 `header_name`；其他取值返回 `InvalidParameter`。",
+            "enum": [
+              "shared",
+              "per_user_secret",
+              "per_user_oauth"
+            ],
+            "default": "shared"
           },
           "secret_schema": {
             "type": "string",
@@ -5230,7 +5388,7 @@
           },
           "can_edit": {
             "type": "boolean",
-            "description": "调用者是否可以编辑该智能体。"
+            "description": "调用者能否更新、启用、停用或删除该智能体：账户级智能体仅账户 owner 或管理员为 `true`，团队智能体仅该团队成员为 `true`。"
           },
           "environments": {
             "type": "array",
@@ -5254,7 +5412,7 @@
           },
           "auth_type": {
             "type": "string",
-            "description": "访问远程智能体的认证类型：`none`、`api_key` 或 `bearer`。校验收紧前创建的历史数据可能返回空字符串，等价于 `none`。",
+            "description": "使用共享凭据访问远程智能体时的认证方式：\n- `none`：不发送凭据请求头。\n- `api_key`：把 `auth_config.api_key` 放进 `auth_config.header` 指定名称的请求头。\n- `bearer`：发送 `Authorization: Bearer <auth_config.token>`。\n\n空字符串表示创建时未传 `auth_type`，效果同 `none`。",
             "enum": [
               "",
               "none",
@@ -5267,7 +5425,7 @@
             "additionalProperties": {
               "type": "string"
             },
-            "description": "认证配置键值。键名疑似凭据（包含 KEY、SECRET、TOKEN、PASSWORD 等）的值会被脱敏；为空时省略。"
+            "description": "共享凭据键值（`header`、`api_key`、`token` 等）。`api_key`、`token`、`client_secret` 以及其他加密存储的值会脱敏：超过 8 个字符时只显示首尾各 4 个字符、中间为 `****`，否则显示 `****`。为空时省略。"
           },
           "streaming": {
             "type": "boolean",
@@ -5275,7 +5433,7 @@
           },
           "status": {
             "type": "string",
-            "description": "智能体状态。",
+            "description": "智能体是否提供给 AI SRE 会话使用：\n- `enabled`：可被调用（创建后的状态）。\n- `disabled`：保留配置但不提供使用；可通过 `POST /safari/a2a-agent/enable` 重新启用。",
             "enum": [
               "enabled",
               "disabled"
@@ -5283,14 +5441,14 @@
           },
           "agent_card_name": {
             "type": "string",
-            "description": "从远程卡片解析得到的智能体名称；卡片尚未拉取时省略。"
+            "description": "旧记录中从远程卡片读取的智能体名称。服务端已不再写入该字段，新建智能体不返回。"
           },
           "agent_card_skills": {
             "type": "array",
             "items": {
               "type": "string"
             },
-            "description": "远程卡片宣告的技能；卡片尚未拉取时省略。"
+            "description": "旧记录中从远程卡片读取的技能名称。服务端已不再写入该字段，新建智能体不返回。"
           },
           "card_resolve_timeout": {
             "type": "integer",
@@ -5302,7 +5460,7 @@
           },
           "auth_mode": {
             "type": "string",
-            "description": "认证模式。可选值：`shared`（共享凭据：配置资源时保存一份静态凭据，账户内所有调用方共用；缺省及空字符串等同于此值）、`per_user_secret`（按人密钥：每位使用者按 `secret_schema` 各自保存密钥，运行时按人注入）、`per_user_oauth`（按人 OAuth：每位使用者各自完成 OAuth 授权，首次调用时按需完成发现与注册）。",
+            "description": "凭据由谁提供；为空时省略，效果同 `shared`：\n- `shared`：使用保存在智能体上的一份凭据（`auth_type` + `auth_config`），所有调用者共用。\n- `per_user_secret`：每位用户各自保存密钥，放在 `secret_schema.header_name` 指定的请求头中发送。\n- `per_user_oauth`：每位用户各自完成 OAuth 授权，首次使用时完成发现与客户端注册。",
             "enum": [
               "shared",
               "per_user_secret",
@@ -5371,7 +5529,7 @@
           },
           "limit": {
             "type": "integer",
-            "description": "页面大小。",
+            "description": "每页条数；小于等于 0 时按 20 处理。服务端不设上限。",
             "default": 20
           },
           "scope": {
@@ -5395,14 +5553,14 @@
               "type": "integer",
               "format": "int64"
             },
-            "description": "限定在这些团队 ID 内；留空表示使用调用者可见的团队集合。"
+            "description": "只返回这些团队的记录。调用者不属于的团队 ID 会被忽略；为空表示调用者所属的全部团队。"
           },
           "include_account": {
             "type": [
               "boolean",
               "null"
             ],
-            "description": "是否包含账户级（team_id=0）记录。默认为 true。"
+            "description": "是否包含账户级（`team_id=0`）记录。默认 `true`；`scope` 为 `account` 时始终包含、为 `team` 时始终不包含，此时忽略该字段。"
           }
         }
       },
@@ -5441,7 +5599,7 @@
               "string",
               "null"
             ],
-            "description": "新的显示名称。省略则保持不变。",
+            "description": "新的显示名称，省略表示不变。规则同创建：不能含 `@`，不能是 `general` / `explore`，在作用域内唯一。",
             "maxLength": 128
           },
           "instructions": {
@@ -5457,14 +5615,14 @@
               "string",
               "null"
             ],
-            "description": "新的卡片 URL。省略则保持不变。"
+            "description": "新的卡片 URL，省略表示不变。校验与兼容性检查同创建；实际变更时，若未传新的 `oauth_metadata`，会将其清空。"
           },
           "auth_type": {
             "type": [
               "string",
               "null"
             ],
-            "description": "新的认证类型：`none`、`api_key` 或 `bearer`。省略则保持不变。",
+            "description": "新的认证方式，省略表示不变。\n- `none`：不发送凭据请求头。\n- `api_key`：把 `auth_config.api_key` 放进 `auth_config.header` 指定名称的请求头。\n- `bearer`：发送 `Authorization: Bearer <auth_config.token>`。",
             "enum": [
               "none",
               "api_key",
@@ -5490,7 +5648,7 @@
               "integer",
               "null"
             ],
-            "description": "重新分配团队范围。省略则保持不变。重新分配需要对目标团队的权限；若团队变更且未同时传入新的环境绑定，则现有 Runner 绑定必须对调用者仍可选，否则更新将被拒绝。",
+            "description": "重新分配团队范围，省略表示不变。改到团队需是该团队成员；改为账户级（`0`）仅限账户 owner 或管理员。若变更团队但同一请求未传 `environments`，现有 Runner 条目必须对调用者仍可选，否则更新被拒绝。",
             "format": "int64"
           },
           "environments": {
@@ -5508,21 +5666,26 @@
               "string",
               "null"
             ],
-            "description": "新的认证模式：shared、per_user_secret 或 per_user_oauth。变更时会一并重写 secret_schema。"
+            "description": "新的认证模式，省略表示不变。取值（凭据由谁提供）：\n- `shared`（默认，空值等同）：使用保存在智能体上的一份凭据（`auth_type` + `auth_config`），所有调用者共用。\n- `per_user_secret`：每位用户各自保存密钥，放在 `secret_schema.header_name` 指定的请求头中发送。\n- `per_user_oauth`：每位用户各自完成 OAuth 授权，首次使用时完成发现与客户端注册。\n\n传入时，`secret_schema` 会被同一请求中的值覆盖。",
+            "enum": [
+              "shared",
+              "per_user_secret",
+              "per_user_oauth"
+            ]
           },
           "secret_schema": {
             "type": [
               "string",
               "null"
             ],
-            "description": "新的 JSON 密钥 schema。"
+            "description": "新的 JSON 密钥 schema，例如 `{\"header_name\":\"X-Api-Key\"}`。仅在同时传入 `auth_mode` 时生效，单独传入会被忽略。"
           },
           "oauth_metadata": {
             "type": [
               "string",
               "null"
             ],
-            "description": "新的 JSON OAuth 元数据。若 auth_mode 变更但未传入此字段，将被清空。"
+            "description": "新的 JSON OAuth 元数据。非空值按原样保存。省略或为空时保留原值；若 `auth_mode` 或 `card_url` 发生变化，则清空。"
           },
           "allow_insecure_oauth_http": {
             "type": [
@@ -5551,38 +5714,46 @@
             "type": "string",
             "minLength": 1,
             "maxLength": 255,
-            "description": "规则名称。"
+            "description": "规则显示名称，1–255 个字符；首尾空格会被去除。"
           },
           "team_id": {
             "type": "integer",
             "format": "int64",
             "minimum": 0,
-            "description": "作用域团队 ID。0 或省略表示个人规则；>0 表示账户下某团队。之后可通过 update 改派（团队规则转个人仅规则 owner 可操作；转入团队要求调用者属于该团队）。"
+            "description": "规则作用域。`0` 或省略：调用者的个人规则。`>0`：团队规则，调用者必须是该团队成员。作用域创建后不可修改。"
+          },
+          "run_in": {
+            "type": "string",
+            "enum": [
+              "web",
+              "current-chat"
+            ],
+            "description": "规则运行的位置。`web`（默认）：在 Web 控制台会话中运行。`current-chat`：在创建规则时所在的 IM 群聊中运行；仅在与 AI SRE Agent 的实时 IM 会话中可用，API 调用传入会返回 `400`。"
           },
           "enabled": {
             "type": "boolean",
-            "description": "规则创建后是否启用。API 省略时为 false；Chat/CLI 入口会默认发送 true，除非用户要求禁用。"
+            "description": "创建后是否启用规则的自动触发器（定时、HTTP POST、On-call 故障、作战室）。默认 `false`。手动运行不受此影响。"
           },
           "cron_expr": {
             "type": "string",
-            "description": "运行周期。支持 4 段 `hour day month weekday`，会补 `minute=0`；也支持 5 段 `minute hour day month weekday`。分钟必须是固定整数，秒级 6 段不支持。同时设置日期和星期几的 cron 会被拒绝。创建 API 当前要求该字段，即使只启用 HTTP POST trigger，也要提供一个有效 cron 并把 `schedule_trigger_enabled` 设为 false。",
+            "description": "按 `timezone` 本地时间计算的调度表达式。支持 4 段（`hour day month weekday`，分钟默认为 0）或 5 段（`minute hour day month weekday`）。分钟必须是一个固定整数；不支持秒级 6 段；同时指定日期和星期几会被拒绝。即使规则只使用其他触发器也必填：请传一个合法表达式并将 `schedule_trigger_enabled` 设为 `false`。",
             "example": "15 9 * * *"
           },
           "timezone": {
             "type": "string",
-            "description": "`cron_expr` 计算所用的 IANA 时区，例如 `Asia/Shanghai`。必须是服务端可加载的合法时区名，非法值会被拒绝。省略时依次回退到调用者的成员时区、账户时区，最后是服务端默认时区（Asia/Shanghai）。"
+            "description": "计算 `cron_expr` 所用的 IANA 时区名，例如 `Asia/Shanghai`。`Local`、`CST`、`UTC+8`、`GMT+8` 等含糊名称会被拒绝。省略时依次使用调用者的成员时区、账户时区，最后为 `Asia/Shanghai`。"
           },
           "schedule_trigger_enabled": {
             "type": [
               "boolean",
               "null"
             ],
-            "description": "是否启用 schedule trigger。省略时为 true；HTTP-POST-only 规则应传 false。"
+            "description": "是否启用定时触发器。省略时为 `true`；只希望由其他触发器触发的规则请传 `false`。"
           },
           "prompt": {
             "type": "string",
             "minLength": 1,
-            "description": "每次运行发给 AI SRE Agent 的任务提示词。"
+            "description": "每次运行发给 AI SRE Agent 的任务指令。去除首尾空格后不能为空。"
           },
           "environment_kind": {
             "type": "string",
@@ -5595,15 +5766,15 @@
           },
           "environment_id": {
             "type": "string",
-            "description": "BYOC Runner ID。仅 `environment_kind=byoc` 时使用。"
+            "description": "BYOC 运行器 ID。`environment_kind=byoc` 时必填，其他类型下传入会被拒绝。个人规则只能使用账户级运行器；团队规则可使用账户级运行器或本团队的运行器。"
           },
           "http_post_trigger_enabled": {
             "type": "boolean",
-            "description": "是否创建并启用 HTTP POST trigger。启用时响应里会返回一次性 token。"
+            "description": "是否创建并启用 HTTP POST 触发器。为 `true` 时，响应会返回 `http_post_trigger_url` 和一次性的 `http_post_token`。"
           },
           "oncall_incident_trigger_enabled": {
             "type": "boolean",
-            "description": "是否启用 On-call 故障触发器。"
+            "description": "是否启用 On-call 故障触发器。创建该触发器时（本字段为 `true`，或传了协作空间 ID 或严重程度），`oncall_incident_channel_ids` 和 `oncall_incident_severities` 都必须非空。"
           },
           "oncall_incident_channel_ids": {
             "type": "array",
@@ -5612,7 +5783,7 @@
               "format": "int64",
               "minimum": 1
             },
-            "description": "监听的 On-call 集成 ID 列表；创建或启用该触发器时至少需要一个有效 ID。"
+            "description": "要监听的协作空间 ID；这些协作空间中的故障可以发起运行。每个 ID 必须为正数。"
           },
           "oncall_incident_severities": {
             "type": "array",
@@ -5624,7 +5795,39 @@
                 "Info"
               ]
             },
-            "description": "监听的故障严重程度，支持 Critical、Warning 和 Info；创建或启用该触发器时至少需要一个值。"
+            "description": "要监听的故障严重程度：`Critical`（最严重）、`Warning` 或 `Info`（最轻）——即 On-call 故障的严重程度。"
+          },
+          "oncall_incident_merge_similar": {
+            "type": [
+              "boolean",
+              "null"
+            ],
+            "description": "是否将相似故障合并分析。为 `true`（默认）时，与本规则正在分析的故障（运行中或 10 分钟内刚结束的运行）高度相似的新故障会加入该运行的会话，而不新开运行；其自身的运行记录为 `skipped`，并带有 `joined_session_id`。为 `false` 时，每个命中的故障都单独发起运行。"
+          },
+          "war_room_trigger_enabled": {
+            "type": "boolean",
+            "description": "是否启用作战室触发器。当 `war_room_channel_ids` 中某个协作空间的故障（严重程度在 `war_room_severities` 中）创建作战室（IM 群聊）时触发，Agent 会直接在该群聊中运行。创建该触发器时（本字段为 `true`，或传了 `war_room_channel_ids`），两个列表都必须非空。"
+          },
+          "war_room_channel_ids": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "int64",
+              "minimum": 1
+            },
+            "description": "创建作战室时会发起运行的协作空间 ID。每个 ID 必须为正数。"
+          },
+          "war_room_severities": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "enum": [
+                "Critical",
+                "Warning",
+                "Info"
+              ]
+            },
+            "description": "故障创建作战室时会发起运行的严重程度：`Critical`（最严重）、`Warning` 或 `Info`（最轻）——即 On-call 故障的严重程度。"
           }
         },
         "required": [
@@ -5651,30 +5854,30 @@
         "properties": {
           "rule_id": {
             "type": "string",
-            "description": "规则 ID。"
+            "description": "规则 ID（前缀 `arule_`）。获取、更新、删除、运行和查询运行记录时作为 `rule_id` 传入。"
           },
           "account_id": {
             "type": "integer",
             "format": "int64",
-            "description": "账户 ID。"
+            "description": "规则所属账户的 ID。"
           },
           "team_id": {
             "type": "integer",
             "format": "int64",
-            "description": "作用域团队 ID；0 表示个人规则。"
+            "description": "作用域团队 ID；`0` 表示个人规则。创建后不可修改。"
           },
           "owner_id": {
             "type": "integer",
             "format": "int64",
-            "description": "创建者 person ID。"
+            "description": "创建规则的成员 person ID。对个人规则而言，也是唯一可管理它的人。"
           },
           "name": {
             "type": "string",
-            "description": "规则名称。"
+            "description": "规则显示名称。"
           },
           "enabled": {
             "type": "boolean",
-            "description": "规则是否启用。"
+            "description": "规则的自动触发器是否启用。停用的规则仍可手动运行。个人规则的创建者离开账户后，规则会被自动停用。"
           },
           "run_scope": {
             "type": "string",
@@ -5686,7 +5889,7 @@
           },
           "cron_expr": {
             "type": "string",
-            "description": "规范化后的 5 段 cron 表达式。"
+            "description": "规范化后的 5 段 cron 表达式（`minute hour day month weekday`），按 `timezone` 计算。"
           },
           "timezone": {
             "type": "string",
@@ -5694,7 +5897,7 @@
           },
           "prompt": {
             "type": "string",
-            "description": "任务提示词。"
+            "description": "每次运行发给 AI SRE Agent 的任务指令。"
           },
           "environment_kind": {
             "type": "string",
@@ -5707,7 +5910,7 @@
           },
           "environment_id": {
             "type": "string",
-            "description": "BYOC Runner ID。"
+            "description": "`environment_kind=byoc` 时为 BYOC 运行器 ID；其他情况下为空字符串。"
           },
           "schedule_trigger_id": {
             "type": "string",
@@ -5715,7 +5918,7 @@
           },
           "schedule_trigger_enabled": {
             "type": "boolean",
-            "description": "Schedule trigger 是否启用。"
+            "description": "定时触发器是否启用。"
           },
           "http_post_trigger_id": {
             "type": "string",
@@ -5723,11 +5926,11 @@
           },
           "http_post_trigger_url": {
             "type": "string",
-            "description": "HTTP POST 触发器路径；规则没有 HTTP POST 触发器时省略。"
+            "description": "触发 HTTP POST 触发器的路径 `/safari/automation/triggers/{trigger_id}/fire`，相对于 API 基础地址。发送 `POST` 并带 `Authorization: Bearer <http_post_token>`。规则没有 HTTP POST 触发器时省略。"
           },
           "http_post_trigger_enabled": {
             "type": "boolean",
-            "description": "HTTP POST trigger 是否启用。"
+            "description": "HTTP POST 触发器是否启用。"
           },
           "oncall_incident_trigger_id": {
             "type": "string",
@@ -5735,7 +5938,7 @@
           },
           "oncall_incident_trigger_enabled": {
             "type": "boolean",
-            "description": "是否启用 On-call 故障触发器。"
+            "description": "On-call 故障触发器是否启用。"
           },
           "oncall_incident_channel_ids": {
             "type": "array",
@@ -5744,7 +5947,7 @@
               "format": "int64",
               "minimum": 1
             },
-            "description": "要监听的 On-call 渠道 ID。创建或启用该触发器至少需要一个有效 ID；未配置 On-call 故障触发器时省略。"
+            "description": "On-call 故障触发器监听的协作空间 ID。规则没有该触发器时省略。"
           },
           "oncall_incident_severities": {
             "type": "array",
@@ -5756,15 +5959,153 @@
                 "Info"
               ]
             },
-            "description": "要监听的事故级别。支持的值为 Critical、Warning、Info；创建或启用该触发器至少需要一个值；未配置 On-call 故障触发器时省略。"
+            "description": "On-call 故障触发器监听的严重程度：`Critical`（最严重）、`Warning` 或 `Info`（最轻）——即 On-call 故障的严重程度。规则没有该触发器时省略。"
+          },
+          "oncall_incident_merge_similar": {
+            "type": "boolean",
+            "description": "是否将相似故障合并分析（含义见创建接口）。规则没有 On-call 故障触发器时为 `true`。"
+          },
+          "war_room_trigger_id": {
+            "type": "string",
+            "description": "作战室触发器 ID。规则没有作战室触发器时省略。"
+          },
+          "war_room_trigger_enabled": {
+            "type": "boolean",
+            "description": "作战室触发器是否启用。"
+          },
+          "war_room_channel_ids": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "int64",
+              "minimum": 1
+            },
+            "description": "创建作战室时会发起运行的协作空间 ID。规则没有作战室触发器时省略。"
+          },
+          "war_room_severities": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "enum": [
+                "Critical",
+                "Warning",
+                "Info"
+              ]
+            },
+            "description": "创建作战室时会发起运行的严重程度：`Critical`（最严重）、`Warning` 或 `Info`（最轻）——即 On-call 故障的严重程度。规则没有作战室触发器时省略。"
+          },
+          "execution_place": {
+            "type": "string",
+            "enum": [
+              "web_console",
+              "im"
+            ],
+            "description": "定时、HTTP POST、On-call 故障和手动触发的运行在哪里执行：`web_console`（Web 控制台会话）或 `im`（创建规则时所在的 IM 群聊）。作战室触发的运行始终在作战室群聊中执行。创建后不可修改。"
+          },
+          "execution_location": {
+            "type": "object",
+            "description": "规则运行位置的只读描述。",
+            "properties": {
+              "place": {
+                "type": "string",
+                "enum": [
+                  "web_console",
+                  "im"
+                ],
+                "description": "与规则的 `execution_place` 相同：`web_console` 在 Web 控制台会话中运行，`im` 在绑定的 IM 群聊中运行。"
+              },
+              "run_scope": {
+                "type": "string",
+                "enum": [
+                  "person",
+                  "team"
+                ],
+                "description": "`person`：以创建者身份运行；`team`：归属 `team_id` 对应的团队运行。"
+              },
+              "team_id": {
+                "type": "integer",
+                "format": "int64",
+                "description": "运行所属团队；个人规则为 `0`。"
+              },
+              "platform": {
+                "type": "string",
+                "enum": [
+                  "feishu",
+                  "dingtalk",
+                  "wecom",
+                  "slack",
+                  "teams"
+                ],
+                "description": "绑定群聊所在的 IM 平台：`feishu`（飞书）、`dingtalk`（钉钉）、`wecom`（企业微信）、`slack`（Slack）、`teams`（Microsoft Teams）。仅 `place=im` 时返回。"
+              },
+              "conversation_mode": {
+                "type": "string",
+                "enum": [
+                  "direct",
+                  "group_chat",
+                  "group_thread",
+                  "war_room_chat"
+                ],
+                "description": "绑定会话的类型：`direct`（与机器人单聊）、`group_chat`（群聊）、`group_thread`（群聊中的话题）、`war_room_chat`（故障作战室）。仅 `place=im` 时返回。"
+              },
+              "chat_name": {
+                "type": "string",
+                "description": "绑定群聊的名称。仅 `place=im` 且名称已知时返回。"
+              },
+              "description": {
+                "type": "string",
+                "description": "可读的运行位置标签：Web 控制台规则为 `Web console`，否则为群聊名称，或平台加会话类型。"
+              }
+            },
+            "required": [
+              "place",
+              "run_scope",
+              "team_id",
+              "description"
+            ]
+          },
+          "last_run": {
+            "type": "object",
+            "description": "规则最近一次运行。仅列出自动化规则接口返回，且仅当规则至少运行过一次时返回。",
+            "properties": {
+              "run_id": {
+                "type": "string",
+                "description": "运行 ID，与列出自动化运行记录中的一致。"
+              },
+              "status": {
+                "type": "string",
+                "enum": [
+                  "queued",
+                  "running",
+                  "retrying",
+                  "succeeded",
+                  "partial",
+                  "failed",
+                  "skipped",
+                  "abandoned",
+                  "blocked"
+                ],
+                "description": "运行状态，含义与列出自动化运行记录中的 `status` 相同：`queued`、`running`、`retrying`（进行中）；`succeeded`、`partial`、`failed`、`skipped`（未执行或已合并到其他运行）、`abandoned`（未完成被终止）、`blocked`（因等待连接器授权而结束）。"
+              },
+              "started_at": {
+                "type": "integer",
+                "format": "int64",
+                "description": "开始时间，Unix 毫秒。"
+              }
+            },
+            "required": [
+              "run_id",
+              "status",
+              "started_at"
+            ]
           },
           "http_post_token": {
             "type": "string",
-            "description": "HTTP POST trigger token。只在创建或轮换 token 的响应中返回；请立即保存。"
+            "description": "HTTP POST 触发器 token。只在签发它的响应中返回：带 `http_post_trigger_enabled=true` 的创建、新建该触发器的更新，或带 `rotate_http_post_trigger_token=true` 的更新。请立即保存，之后无法再次读取。"
           },
           "can_edit": {
             "type": "boolean",
-            "description": "当调用者可管理该规则时为 true：个人规则仅限创建者；团队规则限账户管理员或规则所属团队成员。"
+            "description": "调用者可管理（获取、更新、删除、运行）该规则时为 `true`：个人规则的创建者，或团队规则所属团队的成员。账户所有者和管理员没有例外。"
           },
           "created_at": {
             "type": "integer",
@@ -5801,12 +6142,15 @@
           "created_at",
           "updated_at",
           "schedule_next_fire_at_ms",
-          "oncall_incident_trigger_enabled"
+          "oncall_incident_trigger_enabled",
+          "oncall_incident_merge_similar",
+          "war_room_trigger_enabled",
+          "execution_place"
         ]
       },
       "AutomationRuleListRequest": {
         "type": "object",
-        "description": "列出当前调用者可见的自动化规则。`all` 包含调用者自己的个人规则和可访问团队的团队规则；账户管理员在列表中不可见他人的个人规则。",
+        "description": "列出调用者可见的自动化规则：自己的个人规则，加上所属团队的团队规则。账户所有者和管理员同样受此限制。",
         "properties": {
           "p": {
             "type": "integer",
@@ -5826,7 +6170,7 @@
               "personal",
               "team"
             ],
-            "description": "作用域过滤：`all`（自己的个人规则 + 可访问团队规则）、`personal` 或 `team`；默认 `all`。"
+            "description": "作用域过滤：`all`（默认）自己的个人规则加所属团队的规则；`personal` 仅自己的个人规则；`team` 仅所属团队的规则。"
           },
           "team_ids": {
             "type": "array",
@@ -5841,7 +6185,7 @@
               "boolean",
               "null"
             ],
-            "description": "兼容字段；scope 为空且为 false 时等同于 team。"
+            "description": "旧版开关。仅在 `scope` 为空时生效：`false` 等同于 `scope=team`；其他情况忽略。"
           },
           "enabled": {
             "type": [
@@ -5853,7 +6197,7 @@
           "keyword": {
             "type": "string",
             "maxLength": 64,
-            "description": "按名称关键字过滤。"
+            "description": "返回名称包含该文本的规则。最多 64 个字符。"
           }
         }
       },
@@ -5863,7 +6207,7 @@
           "total": {
             "type": "integer",
             "format": "int64",
-            "description": "总数。"
+            "description": "符合过滤条件的规则总数（所有页）。"
           },
           "rules": {
             "type": "array",
@@ -5892,7 +6236,7 @@
               "null"
             ],
             "maxLength": 255,
-            "description": "新规则名称。"
+            "description": "新的显示名称，最多 255 个字符。去除空格后为空会被拒绝。"
           },
           "team_id": {
             "type": [
@@ -5901,21 +6245,21 @@
             ],
             "format": "int64",
             "minimum": 0,
-            "description": "改派规则作用域：0 表示转为个人规则（团队规则仅规则 owner 可转）；>0 表示转入调用者所属的团队。省略则保持不变。"
+            "description": "规则作用域不可修改。请省略本字段或传当前值；传其他值会返回 `400`。"
           },
           "enabled": {
             "type": [
               "boolean",
               "null"
             ],
-            "description": "是否启用规则。"
+            "description": "是否启用规则的自动触发器。省略则保持不变。"
           },
           "cron_expr": {
             "type": [
               "string",
               "null"
             ],
-            "description": "运行周期。支持 4 段 `hour day month weekday`，会补 `minute=0`；也支持 5 段 `minute hour day month weekday`。分钟必须是固定整数，秒级 6 段不支持。",
+            "description": "新的调度表达式，格式与创建时相同：4 段（`hour day month weekday`）或 5 段（`minute hour day month weekday`），分钟为固定整数，不支持秒，不能同时指定日期和星期几。省略则保持当前表达式。",
             "example": "15 9 * * *"
           },
           "timezone": {
@@ -5923,28 +6267,28 @@
               "string",
               "null"
             ],
-            "description": "更新 `cron_expr` 所用的 IANA 时区。省略或传 null 表示保持当前时区不变。"
+            "description": "`cron_expr` 使用的新 IANA 时区。传空字符串会存为 `UTC`。省略或传 `null` 保持当前时区。"
           },
           "schedule_trigger_enabled": {
             "type": [
               "boolean",
               "null"
             ],
-            "description": "是否启用 schedule trigger。"
+            "description": "是否启用定时触发器。省略则保持不变。"
           },
           "prompt": {
             "type": [
               "string",
               "null"
             ],
-            "description": "新的任务提示词。"
+            "description": "新的 Agent 任务指令。省略则保持不变。"
           },
           "environment_kind": {
             "type": [
               "string",
               "null"
             ],
-            "description": "运行环境类型。省略或空字符串表示自动选择。",
+            "description": "新的运行环境：`\"\"` 自动选择（优先使用在线的 BYOC 运行器，否则使用云端沙箱）、`cloud` 平台托管的云端沙箱、`byoc` 使用 `environment_id` 指定的运行器。只传本字段不传 `environment_id` 时会清空已存的 `environment_id`。",
             "enum": [
               "",
               "cloud",
@@ -5956,21 +6300,21 @@
               "string",
               "null"
             ],
-            "description": "BYOC Runner ID。"
+            "description": "BYOC 运行器 ID；最终 `environment_kind` 为 `byoc` 时必填，其他情况下会被拒绝。"
           },
           "http_post_trigger_enabled": {
             "type": [
               "boolean",
               "null"
             ],
-            "description": "是否启用 HTTP POST trigger。不存在时设为 true 会创建。"
+            "description": "启用或停用 HTTP POST 触发器。规则没有该触发器时传 `true` 会创建一个，并在本次响应中返回其 token。"
           },
           "oncall_incident_trigger_enabled": {
             "type": [
               "boolean",
               "null"
             ],
-            "description": "是否启用 On-call 故障触发器。"
+            "description": "启用或停用 On-call 故障触发器。规则还没有该触发器时，创建它还需同时提供 `oncall_incident_channel_ids` 和 `oncall_incident_severities`。"
           },
           "oncall_incident_channel_ids": {
             "type": "array",
@@ -5979,7 +6323,7 @@
               "format": "int64",
               "minimum": 1
             },
-            "description": "监听的 On-call 集成 ID 列表；创建或启用该触发器时至少需要一个有效 ID。"
+            "description": "非空时替换监听的协作空间 ID；空数组或省略则保留已存的 ID。"
           },
           "oncall_incident_severities": {
             "type": "array",
@@ -5991,11 +6335,46 @@
                 "Info"
               ]
             },
-            "description": "监听的故障严重程度，支持 Critical、Warning 和 Info；创建或启用该触发器时至少需要一个值。"
+            "description": "非空时替换监听的严重程度（`Critical`（最严重）、`Warning` 或 `Info`（最轻）——即 On-call 故障的严重程度）；空数组或省略则保留已存的值。"
+          },
+          "oncall_incident_merge_similar": {
+            "type": [
+              "boolean",
+              "null"
+            ],
+            "description": "是否将相似故障合并分析（含义见创建接口）。省略则保持不变。"
+          },
+          "war_room_trigger_enabled": {
+            "type": [
+              "boolean",
+              "null"
+            ],
+            "description": "启用或停用作战室触发器。规则还没有该触发器时，创建它还需同时提供 `war_room_channel_ids` 和 `war_room_severities`。省略则保持不变。"
+          },
+          "war_room_channel_ids": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "int64",
+              "minimum": 1
+            },
+            "description": "非空时替换会触发运行的作战室协作空间 ID；空数组或省略则保留已存的 ID。"
+          },
+          "war_room_severities": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "enum": [
+                "Critical",
+                "Warning",
+                "Info"
+              ]
+            },
+            "description": "非空时替换作战室触发的严重程度（`Critical`（最严重）、`Warning` 或 `Info`（最轻）——即 On-call 故障的严重程度）；空数组或省略则保留已存的值。"
           },
           "rotate_http_post_trigger_token": {
             "type": "boolean",
-            "description": "是否轮换 HTTP POST trigger token。新 token 只会在本次响应中返回。"
+            "description": "为 `true` 时签发新的 HTTP POST 触发器 token，旧 token 失效。该触发器必须存在且处于启用状态。新 token 只在本次响应中返回。"
           }
         },
         "required": [
@@ -6007,16 +6386,24 @@
         "properties": {
           "run_id": {
             "type": "string",
-            "description": "运行 ID。"
+            "description": "运行 ID（前缀 `trun_`）。"
           },
           "session_id": {
             "type": "string",
-            "description": "本次运行创建的会话 ID，从 `result_json` 中提取；运行尚未启动会话时省略。"
+            "description": "本次运行所在的 AI SRE 会话 ID。运行尚未启动会话、加入了其他运行（见 `joined_session_id`），或在 IM 群聊中执行时省略。"
           },
           "session_name": {
             "type": "string",
             "description": "运行会话的显示名称，批量查询填充；为空或查询失败时省略。"
           },
+          "joined_session_id": {
+            "type": "string",
+            "description": "对于合并到相似故障分析中的 On-call 故障运行（`status=skipped`）：其加入的会话 ID。其他情况省略。"
+          },
+          "joined_session_name": {
+            "type": "string",
+            "description": "`joined_session_id` 对应会话的显示名称。为空或名称查询失败时省略。"
+          },
           "kind": {
             "type": "string",
             "description": "运行类型；按规则查询时恒为 `automation_rule`。",
@@ -6027,11 +6414,11 @@
           "account_id": {
             "type": "integer",
             "format": "int64",
-            "description": "账户 ID。"
+            "description": "运行所属账户的 ID。"
           },
           "rule_id": {
             "type": "string",
-            "description": "规则 ID。"
+            "description": "本次运行所属规则的 ID。"
           },
           "trigger_kind": {
             "type": "string",
@@ -6040,13 +6427,22 @@
               "debug",
               "manual",
               "http_post",
-              "oncall_incident"
+              "oncall_incident",
+              "war_room_created"
+            ],
+            "description": "触发来源。可选值：\n| 值 | 含义 |\n| --- | --- |\n| `schedule` | 定时触发器按计划触发 |\n| `debug` | 调试运行（保留值；当前规则运行不会产生） |\n| `manual` | 通过运行自动化规则接口手动发起 |\n| `http_post` | 通过规则的 HTTP POST 触发器触发 |\n| `oncall_incident` | 由命中条件的 On-call 故障触发 |\n| `war_room_created` | 命中条件的故障创建作战室时触发，在该群聊中运行 |"
+          },
+          "execution_place": {
+            "type": "string",
+            "enum": [
+              "web_console",
+              "im"
             ],
-            "description": "触发来源。可选值：\n| 值 | 含义 |\n| --- | --- |\n| `schedule` | 定时触发器按调度计划触发 |\n| `debug` | 调试运行（保留值；当前版本的规则运行不产生该来源） |\n| `manual` | 用户手动触发一次运行 |\n| `http_post` | 通过规则的 HTTP POST webhook 触发 |\n| `oncall_incident` | 由值班故障（on-call incident）事件触发 |"
+            "description": "本次运行的执行位置：`web_console`（Web 控制台会话，`session_id` 指向该会话）或 `im`（IM 群聊，不返回会话信息）。`war_room_created` 运行始终为 `im`。"
           },
           "occurrence_key": {
             "type": "string",
-            "description": "幂等键。"
+            "description": "本次触发的幂等键：手动运行为 `manual:<run_id>`，定时运行为 `<trigger_id>:<计划触发时间 Unix 毫秒>`，On-call 故障运行为 `oncall_incident:<trigger_id>:<incident_id>`。"
           },
           "status": {
             "type": "string",
@@ -6061,11 +6457,11 @@
               "abandoned",
               "blocked"
             ],
-            "description": "运行状态。可选值（前三个为进行中，其余为终态）：\n| 值 | 含义 |\n| --- | --- |\n| `queued` | 已入队，等待工作器执行 |\n| `running` | 正在执行 |\n| `retrying` | 本次尝试失败，已安排重试 |\n| `succeeded` | 成功完成 |\n| `partial` | 部分成功（当前仅记忆整理类运行会产生；规则运行不会落到该状态） |\n| `failed` | 失败终态，不再重试 |\n| `skipped` | 未执行（如超过宽限期、触发器或规则失效），以运行记录形式留存原因 |\n| `abandoned` | 进行中超过陈旧阈值被后台清扫判为未完成（如工作器异常退出） |\n| `blocked` | 终态：有实际产出，但因连接器等待人工完成授权而结束（区别于 `failed`） |"
+            "description": "运行状态。可选值（前三个为进行中，其余为终态）：\n| 值 | 含义 |\n| --- | --- |\n| `queued` | 已入队，等待工作器执行 |\n| `running` | 正在执行 |\n| `retrying` | 本次尝试失败，已安排重试 |\n| `succeeded` | 成功完成 |\n| `partial` | 部分成功（当前仅记忆整理类运行会产生；规则运行不会落到该状态） |\n| `failed` | 失败终态，不再重试 |\n| `skipped` | 未执行（如超过宽限期、触发器或规则失效），以运行记录形式留存原因；合并到相似故障分析中的 On-call 故障运行也记为该状态（见 `joined_session_id`） |\n| `abandoned` | 进行中超过陈旧阈值被后台清扫判为未完成（如工作器异常退出） |\n| `blocked` | 终态：有实际产出，但因连接器等待人工完成授权而结束（区别于 `failed`） |"
           },
           "attempts": {
             "type": "integer",
-            "description": "尝试次数。"
+            "description": "本次运行已进行的执行尝试次数。"
           },
           "started_at": {
             "type": "integer",
@@ -6104,7 +6500,7 @@
               "null"
             ],
             "additionalProperties": true,
-            "description": "运行结果原始 JSON（运行启动后携带 `session_id`）；为空时为 null。"
+            "description": "运行结果原始 JSON（启动会话后携带 `session_id`）。为空或运行在 IM 群聊中执行时为 `null`。"
           },
           "created_at": {
             "type": "integer",
@@ -6123,6 +6519,7 @@
           "account_id",
           "rule_id",
           "trigger_kind",
+          "execution_place",
           "occurrence_key",
           "status",
           "attempts",
@@ -6152,7 +6549,7 @@
           "limit": {
             "type": "integer",
             "default": 20,
-            "description": "每页数量。"
+            "description": "每页数量。小于 1 时回退为 20。"
           },
           "status": {
             "type": "string",
@@ -6176,9 +6573,10 @@
               "debug",
               "manual",
               "http_post",
-              "oncall_incident"
+              "oncall_incident",
+              "war_room_created"
             ],
-            "description": "触发来源过滤：`schedule` 定时调度、`debug` 调试运行、`manual` 手动触发、`http_post` HTTP POST 触发、`oncall_incident` On-call 故障触发；省略则不过滤。"
+            "description": "触发来源过滤：`schedule` 定时触发、`debug` 调试运行、`manual` 手动运行、`http_post` HTTP POST 触发、`oncall_incident` On-call 故障触发、`war_room_created` 作战室触发；省略则不过滤。"
           },
           "started_after_ms": {
             "type": "integer",
@@ -6203,7 +6601,7 @@
           "total": {
             "type": "integer",
             "format": "int64",
-            "description": "总数。"
+            "description": "符合过滤条件的运行总数（所有页）。"
           },
           "runs": {
             "type": "array",
@@ -6228,7 +6626,7 @@
           },
           "session_id": {
             "type": "string",
-            "description": "本次运行对应的 AI SRE 会话 ID。由于调用只会在会话启动后才返回，因此在 200 响应中始终会有值。"
+            "description": "本次运行启动的 AI SRE 会话 ID。规则在 IM 群聊中执行（`execution_place=im`）时省略。"
           }
         },
         "required": [
@@ -6240,31 +6638,88 @@
         "properties": {
           "name": {
             "type": "string",
-            "description": "模板名称。"
+            "description": "本地化的模板名称；可用作规则的 `name`。"
+          },
+          "key": {
+            "type": "string",
+            "description": "与语言无关的稳定模板 ID（小写字母、数字、下划线）。仅控制台其他页面直接引用的模板才有；其他模板省略。"
           },
           "description": {
             "type": "string",
-            "description": "模板说明。"
+            "description": "本地化的模板说明，描述基于该模板创建的规则会做什么。"
           },
           "icon": {
             "type": "string",
-            "description": "图标标识。"
+            "description": "控制台为该模板展示的图标标识，例如 `siren`。"
+          },
+          "category": {
+            "type": "string",
+            "description": "控制台中模板所在分组的本地化名称（自由文本），例如 `Incident Response`。分组顺序按其第一个模板出现的顺序。"
           },
           "enabled": {
             "type": "boolean",
-            "description": "从该模板创建规则时默认是否启用（预填值）。"
+            "description": "创建请求中 `enabled` 的预填值。"
           },
           "prompt": {
             "type": "string",
-            "description": "模板提示词。"
+            "description": "创建请求中 `prompt` 的预填值。"
+          },
+          "schedule_trigger_enabled": {
+            "type": "boolean",
+            "description": "`schedule_trigger_enabled` 的预填值；当且仅当返回 `cron_expr` 时为 `true`。"
+          },
+          "cron_expr": {
+            "type": "string",
+            "description": "`cron_expr` 的预填值。模板不使用定时触发器时省略；创建请求仍需提供合法的 `cron_expr`。"
+          },
+          "http_post_trigger_enabled": {
+            "type": "boolean",
+            "description": "`http_post_trigger_enabled` 的预填值。"
+          },
+          "oncall_incident_trigger_enabled": {
+            "type": "boolean",
+            "description": "`oncall_incident_trigger_enabled` 的预填值；为 `true` 时，创建前需补充 `oncall_incident_channel_ids`。"
+          },
+          "oncall_incident_severities": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "enum": [
+                "Critical",
+                "Warning",
+                "Info"
+              ]
+            },
+            "description": "`oncall_incident_severities` 的预填值（`Critical`（最严重）、`Warning` 或 `Info`（最轻）——即 On-call 故障的严重程度）。模板不使用 On-call 故障触发器时省略。"
+          },
+          "war_room_trigger_enabled": {
+            "type": "boolean",
+            "description": "`war_room_trigger_enabled` 的预填值；为 `true` 时，创建前需补充 `war_room_channel_ids`。"
+          },
+          "war_room_severities": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "enum": [
+                "Critical",
+                "Warning",
+                "Info"
+              ]
+            },
+            "description": "`war_room_severities` 的预填值（`Critical`（最严重）、`Warning` 或 `Info`（最轻）——即 On-call 故障的严重程度）。模板不使用作战室触发器时省略。"
           }
         },
         "required": [
           "name",
           "description",
           "icon",
+          "category",
           "enabled",
-          "prompt"
+          "prompt",
+          "schedule_trigger_enabled",
+          "http_post_trigger_enabled",
+          "oncall_incident_trigger_enabled",
+          "war_room_trigger_enabled"
         ]
       },
       "AutomationTemplateListRequest": {
@@ -6273,7 +6728,7 @@
           "locale": {
             "type": "string",
             "maxLength": 16,
-            "description": "模板语言，例如 zh-CN 或 en-US。省略时按请求语言自动选择。"
+            "description": "模板语言。含 `zh` 返回中文，含 `en` 返回英文，其他非空值返回中文。省略时由查询参数 `locale`/`lang` 或请求头 `Accept-Language` 决定，默认中文。"
           }
         }
       },
@@ -6285,7 +6740,7 @@
             "items": {
               "$ref": "#/components/schemas/AutomationTemplateItem"
             },
-            "description": "内置自动化模板数组，展示文案按请求 `locale`（缺省取请求头语种）本地化。"
+            "description": "按解析出的语言返回的内置模板，按展示顺序排列。"
           }
         },
         "required": [
@@ -6294,7 +6749,7 @@
       },
       "ContextResolvedItem": {
         "type": "object",
-        "description": "该会话三层知识解析结果的快照。",
+        "description": "会话上下文解析到的知识版本。在 `POST /safari/session/get` 中只填充 `versions`（`resolved_at_ms` 为 0）；智能体尚未解析过知识时不返回该对象。",
         "properties": {
           "account_pack_id": {
             "type": "string",
@@ -6318,7 +6773,7 @@
             "additionalProperties": {
               "type": "integer"
             },
-            "description": "各份知识的解析版本映射。"
+            "description": "知识 ID 到智能体最近一次加载的版本号的映射。"
           }
         },
         "required": [
@@ -6334,7 +6789,7 @@
           },
           "message": {
             "type": "string",
-            "description": "用户可读的错误描述，语言会跟随调用方的 Accept-Language。可能包含字段名、ID 等请求上下文。",
+            "description": "按响应语言（query 参数 `locale` / `lang` 或请求头 `Accept-Language`）返回的错误描述，可能包含出错的字段名，请不要解析它。",
             "example": "The specified parameter template_id is not valid."
           }
         },
@@ -6345,7 +6800,7 @@
       },
       "EnvironmentBinding": {
         "type": "object",
-        "description": "会话绑定的 runner 或云沙箱。首条消息前为 null。",
+        "description": "会话绑定的 runner 或云沙箱。仅 `POST /safari/session/get` 返回；会话绑定前（首条消息之前）不返回。",
         "properties": {
           "kind": {
             "type": "string",
@@ -6363,11 +6818,17 @@
             "type": "string",
             "description": "可读的环境名称；cloud 绑定使用默认允许列表时为空。"
           },
+          "team_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "绑定环境所属团队；账户级环境为 0。"
+          },
           "status": {
             "type": "string",
-            "description": "绑定的实时健康状态，按类型分命名空间：BYOC 使用 online/pending/offline/deleted；cloud 使用 available/rebuilding/expired。",
+            "description": "绑定的实时健康状态。未知时不返回。\n\n`byoc`：\n- `online`：runner 已连接且就绪\n- `degraded`：runner 已连接但执行器不健康；仍可发送消息\n- `pending`：runner 从未连接过\n- `offline`：runner 心跳丢失，无法处理消息\n- `deleted`：环境已不存在，需另选环境\n\n`cloud`：\n- `available`：沙箱可处理下一条消息（暂停或启动中的沙箱会自动恢复）\n- `rebuilding`：沙箱正在恢复或重建\n- `expired`：沙箱已永久失败，无法自行恢复\n- `deleted`：所选的云环境模板已被删除",
             "enum": [
               "online",
+              "degraded",
               "pending",
               "offline",
               "deleted",
@@ -6384,7 +6845,7 @@
       },
       "ErrorCode": {
         "type": "string",
-        "description": "Flashduty 错误码枚举。每个失败响应的 `error.code` 都是下列稳定值之一，HTTP 状态码仅作参考。\n\n| 错误码 | HTTP | 含义 |\n|---|---|---|\n| `OK` | 200 | 保留值，正常错误响应不会返回。 |\n| `InvalidParameter` | 400 | 必填参数缺失或未通过校验。 |\n| `BadRequest` | 400 | 通用的 400 错误，通常是请求本身不合法。 |\n| `InvalidContentType` | 400 | 请求头 `Content-Type` 不是 `application/json`。 |\n| `ResourceNotFound` | 400 | 目标资源不存在。注意 HTTP 状态码是 400 而非 404（历史设计）。 |\n| `NoLicense` | 400 | 功能需要有效授权，但未找到可用的 license。 |\n| `ReferenceExist` | 400 | 该资源仍被其他实体引用，无法删除。 |\n| `Unauthorized` | 401 | `app_key` 缺失、无效或已过期。 |\n| `BalanceNotEnough` | 402 | 账户余额不足，无法执行需要计费的操作。 |\n| `AccessDenied` | 403 | 身份认证通过，但 RBAC 权限不足以执行该操作。 |\n| `RouteNotFound` | 404 | 请求的 URL 路径不是已知路由。 |\n| `MethodNotAllowed` | 405 | 当前路径不接受所使用的 HTTP 方法。 |\n| `UndonedOrderExist` | 409 | 账户存在未完成的订单，请稍后重试。 |\n| `RequestLocked` | 423 | 因连续失败被临时锁定。 |\n| `EntityTooLarge` | 413 | 请求体超过允许的最大长度。 |\n| `RequestTooFrequently` | 429 | 命中限流（全局、账户级或集成级）。 |\n| `RequestVerifyRequired` | 428 | 操作需要二次验证码，但未提供。 |\n| `DangerousOperation` | 428 | 危险操作，需要进行 MFA 验证。 |\n| `InternalError` | 500 | 服务端未预期错误。反馈问题请附上 `request_id`。 |\n| `ServiceUnavailable` | 503 | 后端依赖不可用，请稍后重试。 |",
+        "description": "错误码。所有失败响应都会把 `error.code` 设为下列稳定字符串之一，请以它而不是 HTTP 状态码做判断。\n\n| 错误码 | HTTP | 含义 |\n|---|---|---|\n| `OK` | 200 | 保留值，失败的请求不会返回。 |\n| `InvalidParameter` | 400 | 参数缺失、类型错误或未通过校验，`message` 通常会指出字段名。 |\n| `BadRequest` | 400 | 请求违反业务规则或与对象当前状态冲突，`message` 会说明原因。 |\n| `InvalidContentType` | 400 | 请求体没有以 `application/json` 发送。 |\n| `ResourceNotFound` | 400 | 引用的对象在本账户中不存在或已删除。注意 HTTP 状态码是 400 而不是 404。 |\n| `NoLicense` | 400 | 账户套餐不包含该功能、套餐配额已用完、套餐已过期或额度不足。 |\n| `ReferenceExist` | 400 | 对象仍被其他对象引用，无法删除。 |\n| `Unauthorized` | 401 | APP Key 缺失、无效或已删除。 |\n| `BalanceNotEnough` | 402 | 仅用于控制台计费流程，Open API 接口不会返回。 |\n| `AccessDenied` | 403 | APP Key 的权限范围或创建者角色不允许该操作或该对象。 |\n| `RouteNotFound` | 404 | 没有与该 HTTP 方法和路径匹配的接口。 |\n| `MethodNotAllowed` | 405 | 路径存在，但不支持该 HTTP 方法。 |\n| `UndonedOrderExist` | 409 | 仅用于控制台计费流程，Open API 接口不会返回。 |\n| `EntityTooLarge` | 413 | 请求体超出大小限制。 |\n| `RequestLocked` | 423 | 仅用于控制台登录保护，Open API 接口不会返回。 |\n| `RequestVerifyRequired` | 428 | 仅用于控制台验证码流程，Open API 接口不会返回。 |\n| `DangerousOperation` | 428 | 仅用于控制台高风险操作的 MFA 校验，Open API 接口不会返回。 |\n| `RequestTooFrequently` | 429 | 触发频率限制；请等待响应头 `Flashcat-Request-Rate-Limit-Delay` 给出的秒数后再重试。 |\n| `InternalError` | 500 | 服务端意外错误；请退避后重试，反馈问题时附上 `request_id`。 |\n| `ServiceUnavailable` | 503 | 后端依赖过载或不可用，请退避后重试。 |",
         "enum": [
           "OK",
           "InvalidParameter",
@@ -6399,35 +6860,35 @@
           "RouteNotFound",
           "MethodNotAllowed",
           "UndonedOrderExist",
-          "RequestLocked",
           "EntityTooLarge",
-          "RequestTooFrequently",
+          "RequestLocked",
           "RequestVerifyRequired",
           "DangerousOperation",
+          "RequestTooFrequently",
           "InternalError",
           "ServiceUnavailable"
         ],
         "x-enumDescriptions": {
-          "OK": "保留值，正常错误响应不会返回。",
-          "InvalidParameter": "必填参数缺失或未通过校验。",
-          "BadRequest": "通用的 400 错误，通常是请求本身不合法。",
-          "InvalidContentType": "请求头 `Content-Type` 不是 `application/json`。",
-          "ResourceNotFound": "目标资源不存在。注意 HTTP 状态码是 400 而非 404（历史设计）。",
-          "NoLicense": "功能需要有效授权，但未找到可用的 license。",
-          "ReferenceExist": "该资源仍被其他实体引用，无法删除。",
-          "Unauthorized": "`app_key` 缺失、无效或已过期。",
-          "BalanceNotEnough": "账户余额不足，无法执行需要计费的操作。",
-          "AccessDenied": "身份认证通过，但 RBAC 权限不足以执行该操作。",
-          "RouteNotFound": "请求的 URL 路径不是已知路由。",
-          "MethodNotAllowed": "当前路径不接受所使用的 HTTP 方法。",
-          "UndonedOrderExist": "账户存在未完成的订单，请稍后重试。",
-          "RequestLocked": "因连续失败被临时锁定。",
-          "EntityTooLarge": "请求体超过允许的最大长度。",
-          "RequestTooFrequently": "命中限流（全局、账户级或集成级）。",
-          "RequestVerifyRequired": "操作需要二次验证码，但未提供。",
-          "DangerousOperation": "危险操作，需要进行 MFA 验证。",
-          "InternalError": "服务端未预期错误。反馈问题请附上 `request_id`。",
-          "ServiceUnavailable": "后端依赖不可用，请稍后重试。"
+          "OK": "保留值，失败的请求不会返回。",
+          "InvalidParameter": "参数缺失、类型错误或未通过校验，`message` 通常会指出字段名。",
+          "BadRequest": "请求违反业务规则或与对象当前状态冲突，`message` 会说明原因。",
+          "InvalidContentType": "请求体没有以 `application/json` 发送。",
+          "ResourceNotFound": "引用的对象在本账户中不存在或已删除。注意 HTTP 状态码是 400 而不是 404。",
+          "NoLicense": "账户套餐不包含该功能、套餐配额已用完、套餐已过期或额度不足。",
+          "ReferenceExist": "对象仍被其他对象引用，无法删除。",
+          "Unauthorized": "APP Key 缺失、无效或已删除。",
+          "BalanceNotEnough": "仅用于控制台计费流程，Open API 接口不会返回。",
+          "AccessDenied": "APP Key 的权限范围或创建者角色不允许该操作或该对象。",
+          "RouteNotFound": "没有与该 HTTP 方法和路径匹配的接口。",
+          "MethodNotAllowed": "路径存在，但不支持该 HTTP 方法。",
+          "UndonedOrderExist": "仅用于控制台计费流程，Open API 接口不会返回。",
+          "EntityTooLarge": "请求体超出大小限制。",
+          "RequestLocked": "仅用于控制台登录保护，Open API 接口不会返回。",
+          "RequestVerifyRequired": "仅用于控制台验证码流程，Open API 接口不会返回。",
+          "DangerousOperation": "仅用于控制台高风险操作的 MFA 校验，Open API 接口不会返回。",
+          "RequestTooFrequently": "触发频率限制；请等待响应头 `Flashcat-Request-Rate-Limit-Delay` 给出的秒数后再重试。",
+          "InternalError": "服务端意外错误；请退避后重试，反馈问题时附上 `request_id`。",
+          "ServiceUnavailable": "后端依赖过载或不可用，请退避后重试。"
         },
         "example": "InvalidParameter"
       },
@@ -6463,12 +6924,32 @@
           },
           "invocation_id": {
             "type": "string",
-            "description": "标识一轮的 ADK 调用 ID。"
+            "description": "写入该事件的调用（一轮智能体执行）ID。为空时不返回。"
+          },
+          "root_invocation_id": {
+            "type": "string",
+            "description": "该事件所属顶层用户轮次的调用 ID，用于把嵌套子智能体调用写入的事件关联回该轮次。为空时不返回。"
+          },
+          "delivery_mode": {
+            "type": "string",
+            "enum": [
+              "reply_only"
+            ],
+            "description": "产生该事件的 IM 请求所协商的投递方式。`reply_only`：IM 端只展示显式回复，不展示智能体的最终文本。普通投递时不返回。"
+          },
+          "is_error": {
+            "type": "boolean",
+            "description": "该事件为记录运行时失败、且错误信息可直接展示给用户的助手事件时为 true。为 false 时不返回。"
           },
           "author": {
             "type": "string",
             "description": "事件作者（如 user 或智能体名称）。"
           },
+          "person_id": {
+            "type": "integer",
+            "format": "int64",
+            "description": "发送该用户消息的成员 ID。助手事件、工具事件以及未记录成员时（自动化运行、部分 IM 轮次）不返回。"
+          },
           "branch": {
             "type": "string",
             "description": "嵌套智能体的 ADK 分支路径。"
@@ -6532,7 +7013,7 @@
         "properties": {
           "server_name": {
             "type": "string",
-            "description": "MCP 服务器名称：必须以字母开头，仅含字母、数字、`-`、`_`（`@` 为保留字符）；在其作用域（账户范围或单个团队）内唯一，大小写不敏感。",
+            "description": "MCP 服务器名称：必须以字母开头，只能包含字母、数字、`-` 或 `_`（`@` 为保留字符）；在其作用域（账户级或单个团队）内唯一。",
             "minLength": 1,
             "maxLength": 255
           },
@@ -6567,7 +7048,7 @@
             "additionalProperties": {
               "type": "string"
             },
-            "description": "环境变量（stdio 传输）。"
+            "description": "环境变量（`stdio` 传输）。键名疑似凭据（包含 `KEY`、`SECRET`、`TOKEN`、`PASSWORD` 等）的值加密存储，响应中脱敏。"
           },
           "url": {
             "type": "string",
@@ -6578,19 +7059,25 @@
             "additionalProperties": {
               "type": "string"
             },
-            "description": "HTTP 头（sse / streamable-http）。"
+            "description": "HTTP 请求头（`sse` / `streamable-http` 传输）。键名疑似凭据（包含 `KEY`、`TOKEN`、`AUTHORIZATION` 等）的值加密存储，响应中脱敏。"
           },
           "connect_timeout": {
             "type": "integer",
-            "description": "连接超时，单位秒。0 表示默认（10 秒）。"
+            "description": "连接超时（秒）。省略或为 `0` 时存为 `0`，使用默认 10 秒。"
           },
           "call_timeout": {
             "type": "integer",
-            "description": "工具调用超时，单位秒。0 表示默认（60 秒）。"
+            "description": "工具调用超时（秒）。省略或为 `0` 时存为 `0`，使用默认 60 秒。"
           },
           "auth_mode": {
             "type": "string",
-            "description": "认证模式：shared（默认）、per_user_secret 或 per_user_oauth。"
+            "description": "凭据由谁提供：\n- `shared`（默认，空值等同）：使用保存在服务器上的一份凭据（`env` / `headers`），所有调用者共用。\n- `per_user_secret`：每位用户各自保存密钥，放在 `secret_schema.header_name` 指定的请求头中发送。\n- `per_user_oauth`：每位用户各自完成 OAuth 授权，首次使用时完成发现与客户端注册。\n\n`per_user_secret` 要求 `secret_schema` 带非空的 `header_name`；其他取值返回 `InvalidParameter`。",
+            "enum": [
+              "shared",
+              "per_user_secret",
+              "per_user_oauth"
+            ],
+            "default": "shared"
           },
           "secret_schema": {
             "type": "string",
@@ -6611,7 +7098,7 @@
           },
           "team_id": {
             "type": "integer",
-            "description": "团队范围：0 表示账户级；>0 表示团队。",
+            "description": "团队范围：`0` = 账户级（仅账户 owner 或管理员）；`>0` = 调用者所属的团队。传入 `source_template_name` 时忽略，市场安装一律为账户级。",
             "format": "int64"
           },
           "environments": {
@@ -6631,7 +7118,7 @@
           },
           "source_template_name": {
             "type": "string",
-            "description": "从连接器模板创建时的市场模板名称。"
+            "description": "要安装的市场模板名称。传入时模板必须存在，服务器建在账户级，且连接字段必须与模板一致，只能填写模板声明的参数值。创建后不可修改。"
           }
         },
         "required": [
@@ -6686,7 +7173,7 @@
           },
           "can_edit": {
             "type": "boolean",
-            "description": "调用者是否可编辑该服务器。"
+            "description": "调用者能否更新、启用、停用或删除该服务器：账户级服务器仅账户 owner 或管理员为 `true`，团队服务器仅该团队成员为 `true`。创建和更新接口的响应恒为 `true`。"
           },
           "environments": {
             "type": "array",
@@ -6697,7 +7184,7 @@
           },
           "server_name": {
             "type": "string",
-            "description": "MCP 服务器名称，在其作用域（账户范围或单个团队）内唯一，大小写不敏感。"
+            "description": "MCP 服务器名称，在其作用域（账户级或单个团队）内唯一。"
           },
           "description": {
             "type": "string",
@@ -6732,7 +7219,7 @@
             "additionalProperties": {
               "type": "string"
             },
-            "description": "环境变量（stdio 传输）；密钥值已脱敏。"
+            "description": "环境变量（`stdio` 传输）。键名疑似凭据或已加密存储的值会脱敏：超过 8 个字符时只显示首尾各 4 个字符、中间为 `****`，否则显示 `****`。为空时省略。"
           },
           "url": {
             "type": "string",
@@ -6743,15 +7230,15 @@
             "additionalProperties": {
               "type": "string"
             },
-            "description": "HTTP 头（sse / streamable-http）；密钥值已脱敏。"
+            "description": "HTTP 请求头（`sse` / `streamable-http` 传输），脱敏规则同 `env`。为空时省略。"
           },
           "proxy_url": {
             "type": "string",
-            "description": "访问服务器使用的出站代理 URL。"
+            "description": "访问服务器使用的出站代理 URL。公开 API 无法设置；为空时省略。"
           },
           "status": {
             "type": "string",
-            "description": "服务器状态。",
+            "description": "服务器的工具是否提供给 AI SRE 会话使用：\n- `enabled`：可用（创建时默认）。\n- `disabled`：保留配置但不提供使用；可通过 `POST /safari/mcp/server/enable` 重新启用。",
             "enum": [
               "enabled",
               "disabled"
@@ -6759,11 +7246,11 @@
           },
           "connect_timeout": {
             "type": "integer",
-            "description": "连接超时，单位秒（0 表示默认 10 秒）。"
+            "description": "存储的连接超时（秒）；`0` 表示使用默认 10 秒。"
           },
           "call_timeout": {
             "type": "integer",
-            "description": "工具调用超时，单位秒（0 表示默认 60 秒）。"
+            "description": "存储的工具调用超时（秒）；`0` 表示使用默认 60 秒。"
           },
           "allow_insecure_oauth_http": {
             "type": "boolean",
@@ -6775,7 +7262,7 @@
           },
           "auth_mode": {
             "type": "string",
-            "description": "认证模式。可选值：`shared`（共享凭据：配置资源时保存一份静态凭据，账户内所有调用方共用；缺省及空字符串等同于此值）、`per_user_secret`（按人密钥：每位使用者按 `secret_schema` 各自保存密钥，运行时按人注入）、`per_user_oauth`（按人 OAuth：每位使用者各自完成 OAuth 授权，首次调用时按需完成发现与注册）。",
+            "description": "凭据由谁提供；为空时省略，效果同 `shared`：\n- `shared`：使用保存在服务器上的一份凭据（`env` / `headers`），所有调用者共用。\n- `per_user_secret`：每位用户各自保存密钥，放在 `secret_schema.header_name` 指定的请求头中发送。\n- `per_user_oauth`：每位用户各自完成 OAuth 授权，首次使用时完成发现与客户端注册。",
             "enum": [
               "shared",
               "per_user_secret",
@@ -6792,7 +7279,16 @@
           },
           "source_template_name": {
             "type": "string",
-            "description": "该连接器安装来源的市场模板名称；自建为空。"
+            "description": "该服务器安装来源的市场模板名称；手动创建的服务器不返回此字段。"
+          },
+          "test_error": {
+            "type": "string",
+            "description": "最近一次连接测试的错误信息；最近一次测试成功或从未测试时不返回。"
+          },
+          "tested_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "最近一次连接测试的时间，Unix 毫秒时间戳；从未测试时不返回。"
           },
           "created_by": {
             "type": "integer",
@@ -6833,12 +7329,12 @@
         "properties": {
           "p": {
             "type": "integer",
-            "description": "页码，从 1 开始。",
+            "description": "页码，从 1 开始；小于 1 时按 1 处理。",
             "default": 1
           },
           "limit": {
             "type": "integer",
-            "description": "每页数量。",
+            "description": "每页条数；小于 1 时按 20 处理。服务端不设上限。",
             "default": 20
           },
           "scope": {
@@ -6848,7 +7344,8 @@
               "all",
               "account",
               "team"
-            ]
+            ],
+            "default": "all"
           },
           "query": {
             "type": "string",
@@ -6861,14 +7358,14 @@
               "type": "integer",
               "format": "int64"
             },
-            "description": "按团队 ID 过滤；为空则使用调用者可见范围。"
+            "description": "只返回这些团队的记录。调用者不属于的团队 ID 会被忽略；为空表示调用者所属的全部团队。"
           },
           "include_account": {
             "type": [
               "boolean",
               "null"
             ],
-            "description": "是否包含账户级（team_id=0）记录，默认 true。"
+            "description": "是否包含账户级（`team_id=0`）记录。默认 `true`；`scope` 为 `account` 时始终包含、为 `team` 时始终不包含，此时忽略该字段。"
           }
         }
       },
@@ -6938,7 +7435,7 @@
           },
           "command": {
             "type": "string",
-            "description": "可执行命令（stdio 传输）。"
+            "description": "新的可执行命令（`stdio` 传输），省略或为空表示不变。"
           },
           "args": {
             "type": "array",
@@ -6952,11 +7449,11 @@
             "additionalProperties": {
               "type": "string"
             },
-            "description": "环境变量（`stdio` 传输）；整体替换，但敏感键回传掩码值或空字符串时保留服务端存储的原值；省略则不修改。"
+            "description": "环境变量（`stdio` 传输）；整体替换，未传入的键会被删除。对受保护的键（规则见详情接口的脱敏说明），回传脱敏值或空字符串会保留已存储的值。省略表示不变。"
           },
           "url": {
             "type": "string",
-            "description": "服务器 URL（sse / streamable-http 传输）。"
+            "description": "新的服务器 URL（`sse` / `streamable-http` 传输），省略或为空表示不变。实际变更时，若未传新的 `oauth_metadata`，会将其清空。"
           },
           "headers": {
             "type": "object",
@@ -6967,30 +7464,35 @@
           },
           "connect_timeout": {
             "type": "integer",
-            "description": "连接超时，单位秒。0 表示默认（10 秒）。"
+            "description": "新的连接超时（秒），省略或为 `0` 表示不变（存储值为 `0` 时使用默认 10 秒）。"
           },
           "call_timeout": {
             "type": "integer",
-            "description": "工具调用超时，单位秒。0 表示默认（60 秒）。"
+            "description": "新的工具调用超时（秒），省略或为 `0` 表示不变（存储值为 `0` 时使用默认 60 秒）。"
           },
           "auth_mode": {
             "type": "string",
-            "description": "认证模式：shared（默认）、per_user_secret 或 per_user_oauth。"
+            "description": "新的认证模式，省略或为空表示不变。凭据由谁提供：\n- `shared`（默认，空值等同）：使用保存在服务器上的一份凭据（`env` / `headers`），所有调用者共用。\n- `per_user_secret`：每位用户各自保存密钥，放在 `secret_schema.header_name` 指定的请求头中发送。\n- `per_user_oauth`：每位用户各自完成 OAuth 授权，首次使用时完成发现与客户端注册。\n\n`per_user_secret` 要求 `secret_schema` 带非空的 `header_name`；其他取值返回 `InvalidParameter`。",
+            "enum": [
+              "shared",
+              "per_user_secret",
+              "per_user_oauth"
+            ]
           },
           "secret_schema": {
             "type": "string",
-            "description": "JSON 密钥 schema；auth_mode=per_user_secret 时必填。"
+            "description": "新的 JSON 密钥 schema，例如 `{\"header_name\":\"X-Api-Key\"}`。仅在同时传入非空 `auth_mode` 时生效，单独传入会被忽略。"
           },
           "oauth_metadata": {
             "type": "string",
-            "description": "JSON OAuth 元数据；为 per_user_oauth 预留。"
+            "description": "新的 JSON OAuth 元数据。非空值按原样保存。省略或为空时保留原值；若 `auth_mode` 或 `url` 发生变化，则清空。"
           },
           "team_id": {
             "type": [
               "integer",
               "null"
             ],
-            "description": "重新分配团队范围：0 表示账户级；>0 表示团队。省略则不变。",
+            "description": "重新分配团队范围：`0` = 账户级（仅账户 owner 或管理员）；`>0` = 调用者所属的团队。从市场安装的服务器只能改为 `0`。省略表示不变。",
             "format": "int64"
           },
           "environments": {
@@ -7096,7 +7598,7 @@
         "properties": {
           "ok": {
             "type": "boolean",
-            "description": "全部就绪检查是否通过。凡是能返回给调用者的响应中该值恒为 true——预检失败会直接返回 400/403 错误，而不是 ok=false 的响应体。"
+            "description": "所有就绪检查是否通过。200 响应中恒为 `true`；预检失败时直接返回错误。"
           },
           "checks": {
             "type": "array",
@@ -7132,7 +7634,7 @@
             "items": {
               "type": "string"
             },
-            "description": "预检过程中给出的非致命警告。没有警告时省略或为空数组。"
+            "description": "预检给出的非致命警告。当前不会填充，因此不返回该字段。"
           }
         },
         "required": [
@@ -7157,7 +7659,7 @@
             "$ref": "#/components/schemas/DutyError"
           },
           "data": {
-            "description": "端点专属数据负载，具体结构见各操作 200 响应中的 schema。"
+            "description": "接口返回的数据，格式见各接口的 200 响应。没有返回数据的接口会返回 `{}` 或完全不带 `data`。"
           }
         },
         "required": [
@@ -7243,7 +7745,7 @@
             "items": {
               "$ref": "#/components/schemas/EventItem"
             },
-            "description": "最近事件，按 (created_at, event_id) 升序排列。"
+            "description": "最新的一页事件（更早的页通过 `search_after_ctx` 获取），按 (`created_at`, `event_id`) 升序排列。不含内部控制事件。始终为数组。"
           },
           "has_more_older": {
             "type": "boolean",
@@ -7253,10 +7755,6 @@
             "type": "string",
             "description": "不透明游标；作为 search_after_ctx 回传以获取更早的一页。has_more_older 为 false 时省略。"
           },
-          "suggest_init": {
-            "type": "boolean",
-            "description": "账户级引导标志：当账户在任何范围内都没有知识时为 true；并非该会话独有的属性。"
-          },
           "pending_messages": {
             "type": "array",
             "items": {
@@ -7269,7 +7767,6 @@
           "session",
           "events",
           "has_more_older",
-          "suggest_init",
           "pending_messages"
         ]
       },
@@ -7295,22 +7792,25 @@
           },
           "entry_kind": {
             "type": "string",
-            "description": "创建该会话的入口来源。可选值：\n| 值 | 含义 |\n| --- | --- |\n| `web` | Web 控制台界面创建 |\n| `im` | IM 客户端（IM 机器人/IM 端 H5）创建 |\n| `api` | 通过公开 API 创建 |\n| `automation` | 由自动化规则触发创建（无人值守运行） |\n| `subagent` | 父会话经 agent_dispatch 派生的子会话（审计标签；运行时按 web 工具面执行） |",
+            "description": "创建该会话的入口：\n- `web`：Web 控制台（子智能体子会话以及早于该字段创建的会话也返回此值）\n- `im`：IM 机器人或 IM 端 H5\n- `api`：公开 API\n- `automation`：自动化规则（无人值守运行）",
             "enum": [
               "web",
               "im",
               "api",
-              "automation",
-              "subagent"
+              "automation"
             ]
           },
           "person_id": {
             "type": "string",
             "description": "创建者人员 ID。"
           },
+          "ref": {
+            "type": "string",
+            "description": "会话关联的业务对象，以带前缀的引用表示（例如故障引用）。未关联时不返回。"
+          },
           "creator_name": {
             "type": "string",
-            "description": "会话创建者的显示名，渲染响应时解析得到；成员查询失败时不返回该字段。"
+            "description": "会话创建者的显示名。仅 `POST /safari/session/list` 返回；名称查询失败时不返回。"
           },
           "team_id": {
             "type": "integer",
@@ -7321,13 +7821,49 @@
             "type": "string",
             "description": "解析出的团队名称；未绑定或团队已删除时为空。"
           },
+          "automation": {
+            "type": "object",
+            "description": "产生该会话的自动化规则。仅 `POST /safari/session/get` 返回，且只针对由自动化规则发起的会话。",
+            "properties": {
+              "rule_id": {
+                "type": "string",
+                "description": "自动化规则 ID。"
+              },
+              "rule_name": {
+                "type": "string",
+                "description": "规则名称；规则已删除时为空。"
+              },
+              "trigger_kind": {
+                "type": "string",
+                "enum": [
+                  "schedule",
+                  "manual",
+                  "http_post",
+                  "oncall_incident",
+                  "war_room_created",
+                  ""
+                ],
+                "description": "本次运行的触发方式：\n- `schedule`：规则的定时计划触发\n- `manual`：手动运行（控制台或 `POST /safari/automation/rule/run`）\n- `http_post`：调用了规则的 HTTP 触发地址\n- `oncall_incident`：On-call 故障事件匹配了该规则\n- `war_room_created`：创建了作战室\n- `\"\"`：运行记录已不存在"
+              },
+              "can_edit": {
+                "type": "boolean",
+                "description": "调用者可打开并管理该规则时为 true；规则已删除时为 false。"
+              }
+            },
+            "required": [
+              "rule_id",
+              "rule_name",
+              "trigger_kind",
+              "can_edit"
+            ]
+          },
           "is_mine": {
             "type": "boolean",
             "description": "当该会话由调用者创建时为 true。"
           },
           "can_view": {
             "type": "boolean",
-            "description": "调用者可查看此会话时为 true。"
+            "description": "调用者可读取该会话时为 true：创建者、团队成员以及团队会话所在账户的其他成员恒为 true；其他情况需通过有效分享链接。"
           },
           "can_continue": {
             "type": "boolean",
@@ -7335,7 +7871,7 @@
           },
           "can_manage": {
             "type": "boolean",
-            "description": "当调用者可重命名/归档/删除该会话时为 true；个人会话仅创建者可管理，团队会话允许创建者、账户管理员或团队成员管理。"
+            "description": "调用者可重命名、归档或删除该会话时为 true：个人会话仅创建者；团队会话为创建者或所属团队成员。账户所有者和管理员没有豁免。"
           },
           "can_fork": {
             "type": "boolean",
@@ -7343,7 +7879,7 @@
           },
           "access_source": {
             "type": "string",
-            "description": "调用者获得该会话访问权限的方式；未解析到访问来源时省略。可选值：\n| 值 | 含义 |\n| --- | --- |\n| `owner` | 调用者是会话创建者（完全权限） |\n| `team_member` | 调用者是会话绑定团队的成员（完全权限） |\n| `manager` | 管理者授权（保留值；当前版本不产生该来源） |\n| `share_link` | 通过有效分享链接获得（仅查看/复刻，不能继续或管理） |\n| `participant` | 同账户非成员通过可参与的团队会话获得（仅查看/继续/复刻） |",
+            "description": "调用者获得访问权限的方式；无访问权限时不返回。可选值：\n| 值 | 含义 |\n| --- | --- |\n| `owner` | 调用者创建了该会话（完全权限） |\n| `team_member` | 调用者属于会话所属团队（完全权限） |\n| `manager` | 保留值；当前版本不会返回 |\n| `share_link` | 通过有效分享链接获得（仅查看和复刻；子智能体子会话仅查看） |\n| `participant` | 同一账户的其他成员访问团队会话（可查看、继续、复刻，不可管理） |",
             "enum": [
               "owner",
               "team_member",
@@ -7373,10 +7909,9 @@
           },
           "status": {
             "type": "string",
-            "description": "生命周期状态。可选值：`enabled`（正常可用）、`deleted`（已删除，软删除，不可再访问）。",
+            "description": "生命周期状态。响应中恒为 `enabled`：已删除的会话不会被返回。",
             "enum": [
-              "enabled",
-              "deleted"
+              "enabled"
             ]
           },
           "incognito": {
@@ -7400,7 +7935,7 @@
           "state": {
             "type": "object",
             "additionalProperties": true,
-            "description": "原始会话状态包（会话级键）。为空时省略。"
+            "description": "原始会话状态键值表。仅 `POST /safari/session/get` 返回；为空时不返回。"
           },
           "bound_environment": {
             "$ref": "#/components/schemas/EnvironmentBinding"
@@ -7419,7 +7954,7 @@
           "context_window": {
             "type": "integer",
             "format": "int64",
-            "description": "所绑定模型的最大上下文 token 数。0 表示未知。"
+            "description": "会话所用模型的最大上下文长度（token）。仅 `POST /safari/session/get` 计算；列表响应中及查询失败时为 0。"
           },
           "archived_at": {
             "type": "integer",
@@ -7429,12 +7964,12 @@
           "pinned_at": {
             "type": "integer",
             "format": "int64",
-            "description": "调用者的个人置顶时间，Unix 毫秒时间戳；0 表示未置顶。"
+            "description": "调用者置顶该会话的时间，Unix 毫秒时间戳；未置顶为 0。置顶按用户区分。仅 `POST /safari/session/list` 填充；`POST /safari/session/get` 中恒为 0。"
           },
           "last_event_at": {
             "type": "integer",
             "format": "int64",
-            "description": "最近一条助手侧事件的时间，Unix 毫秒时间戳。"
+            "description": "最近一条助手侧事件的时间，Unix 毫秒时间戳；仅用户消息不会推进该值。为 0 时不返回。"
           },
           "is_running": {
             "type": "boolean",
@@ -7442,15 +7977,15 @@
           },
           "standing_tasks": {
             "type": "integer",
-            "description": "渲染响应时仍存活的进程型任务数（后台命令或 monitor）。"
+            "description": "生成响应时该会话仍存活的进程型任务数（后台命令或 monitor）；没有或无法读取时为 0。"
           },
           "has_unread": {
             "type": "boolean",
-            "description": "当存在调用者尚未查看的助手输出时为 true。"
+            "description": "存在调用者尚未查看的助手输出时为 true；`is_running` 为 true 时恒为 false。仅 `POST /safari/session/list` 计算；`POST /safari/session/get` 中恒为 false。"
           },
           "has_open_tasks": {
             "type": "boolean",
-            "description": "会话是否还有未结任务，用于区分「回合已交接」与「会话已完结」。尽力而为：读取失败时该字段不返回（`omitempty`），调用方应视为「未知」，不能据此判定会话空闲。"
+            "description": "会话仍有未结束的任务（如运行中的子智能体或后台进程）时为 true，用于区分「轮次已交接」与「会话已完结」。仅 `POST /safari/session/get` 返回；为 false 或查询失败时不返回，因此缺省应视为未知，而非空闲。"
           },
           "current_turn_started_at": {
             "type": "integer",
@@ -7477,6 +8012,7 @@
           "session_id",
           "session_name",
           "app_name",
+          "entry_kind",
           "person_id",
           "team_id",
           "is_mine",
@@ -7511,7 +8047,7 @@
         "properties": {
           "app_name": {
             "type": "string",
-            "description": "要查询其会话的智能体应用。可选值：\n| 值 | 含义 |\n| --- | --- |\n| `ask-ai` | Ask AI 问答助手 |\n| `support` | 客服支持智能体 |\n| `support-website` | 官网站点客服智能体（经 A2A 暴露，不内置于控制台） |\n| `support-flashcat` | Flashcat 站点客服智能体（经 A2A 暴露） |\n| `ai-sre` | AI SRE 主应用 |\n| `template-assistant` | 通知模板助手（模板编辑/校验场景） |\n| `swe` | 内部基准评测应用（不对外开放） |",
+            "description": "要查询其会话的智能体应用。可选值：\n| 值 | 含义 |\n| --- | --- |\n| `ask-ai` | Ask AI 问答助手 |\n| `support` | 客服支持智能体 |\n| `support-website` | 官网站点客服智能体（经 A2A 暴露，不内置于控制台） |\n| `support-flashcat` | Flashcat 站点客服智能体（经 A2A 暴露） |\n| `ai-sre` | AI SRE 主应用 |\n| `template-assistant` | 通知模板助手（模板编辑/校验场景） |\n| `query-assistant` | 监控查询语句编写助手 |\n| `swe` | 软件工程智能体应用（控制台不提供入口） |",
             "enum": [
               "ask-ai",
               "support",
@@ -7519,6 +8055,7 @@
               "support-flashcat",
               "ai-sre",
               "template-assistant",
+              "query-assistant",
               "swe"
             ]
           },
@@ -7549,16 +8086,16 @@
           },
           "include_subagent_sessions": {
             "type": "boolean",
-            "description": "是否在列表中包含子智能体派生的会话。"
+            "description": "为 true 时同时列出子智能体派发产生的子会话。默认 false（只返回顶层会话）。"
           },
           "keyword": {
             "type": "string",
-            "description": "按会话名称关键字过滤。",
+            "description": "只返回 `session_name` 包含该文本的会话；首尾空格会被忽略。",
             "maxLength": 64
           },
           "scope": {
             "type": "string",
-            "description": "可见范围：`all`（自己的个人会话 + 可访问团队会话）、`personal` 或 `team`；默认 `all`。",
+            "description": "可见范围：\n- `all`（默认）：调用者创建的会话，加上绑定到调用者所在团队的会话\n- `personal`：调用者自己创建且未绑定团队（`team_id` = 0）的会话\n- `team`：绑定到调用者所在团队的会话；调用者不属于任何团队时为空",
             "enum": [
               "all",
               "personal",
@@ -7592,11 +8129,11 @@
                 "automation"
               ]
             },
-            "description": "仅返回由这些入口产生的会话；为空则返回所有类型。"
+            "description": "仅返回由这些入口创建的会话：`web`（控制台）、`im`（IM 机器人或 IM 端 H5）、`api`（公开 API）、`automation`（自动化规则）。为空则返回所有入口。"
           },
           "status": {
             "type": "string",
-            "description": "归档分桶：active（默认）返回未归档，archived 返回已归档，all 返回全部。",
+            "description": "归档过滤：\n- `active`（默认）：未归档的会话\n- `archived`：仅已归档的会话\n- `all`：两者都返回",
             "enum": [
               "active",
               "archived",
@@ -7615,24 +8152,19 @@
           "total": {
             "type": "integer",
             "format": "int64",
-            "description": "匹配过滤条件的会话总数（忽略分页）。"
+            "description": "匹配过滤条件的会话数（忽略分页）。第 1 页额外插入的置顶会话不计入。"
           },
           "sessions": {
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/SessionItem"
             },
-            "description": "当前页的会话。"
-          },
-          "suggest_init": {
-            "type": "boolean",
-            "description": "账户级引导标志：当账户在任何范围内都没有知识时为 true；与本次调用的过滤条件无关。"
+            "description": "当前页的会话：第 1 页先是调用者置顶且匹配的会话（最近置顶在前），后跟最多 `limit` 条按请求顺序排列的其他会话。"
           }
         },
         "required": [
           "total",
-          "sessions",
-          "suggest_init"
+          "sessions"
         ]
       },
       "SessionTokenUsage": {
@@ -7756,9 +8288,13 @@
           "venues": {
             "type": "array",
             "items": {
-              "type": "string"
+              "type": "string",
+              "enum": [
+                "cloud",
+                "byoc"
+              ]
             },
-            "description": "限定技能可用的执行环境类型（EnvironmentKind 字符串，如 `byoc`）；为空时省略，表示所有环境均可用。"
+            "description": "技能限定可用的执行环境：`cloud`（托管沙箱）和/或 `byoc`（自建 runner）。为空时不返回，表示所有环境均可用。"
           },
           "s3_key": {
             "type": "string",
@@ -7770,7 +8306,7 @@
           },
           "status": {
             "type": "string",
-            "description": "技能状态。已删除的技能不会出现在任何 API 响应中，因此只会返回这两种状态。",
+            "description": "技能状态：`enabled`（智能体会加载）或 `disabled`（保留但不加载）。已删除的技能不会出现在响应中。",
             "enum": [
               "enabled",
               "disabled"
@@ -7793,7 +8329,7 @@
           },
           "can_edit": {
             "type": "boolean",
-            "description": "调用者是否可编辑该技能。"
+            "description": "调用者可修改该技能时为 true：账户级技能为账户所有者和管理员，团队技能为该团队成员。"
           },
           "source_template_name": {
             "type": "string",
@@ -7805,15 +8341,36 @@
           },
           "update_available": {
             "type": "boolean",
-            "description": "当市场存在更新版本时为 true。"
+            "description": "该技能的市场来源模板有更新版本时为 true。仅 `POST /safari/skill/list` 计算；其他响应中恒为 false。"
           },
           "is_modified": {
             "type": "boolean",
-            "description": "当市场来源技能被本地修改时为 true（自动更新将跳过）。"
+            "description": "市场安装的技能被本地修改（例如上传了新压缩包）时为 true；市场自动更新会跳过它。"
           },
           "created": {
             "type": "boolean",
-            "description": "仅在“从会话安装”响应中出现：true 表示新建，false 表示原地更新。"
+            "description": "这些接口不会返回该字段；仅「从会话安装」流程会设置。"
+          },
+          "examples": {
+            "type": "array",
+            "description": "SKILL.md frontmatter 中声明的示例问题（最多 10 条），作为推荐提问展示。没有时不返回。",
+            "items": {
+              "type": "object",
+              "properties": {
+                "zh": {
+                  "type": "string",
+                  "description": "中文问题文本。"
+                },
+                "en": {
+                  "type": "string",
+                  "description": "英文问题文本。"
+                }
+              },
+              "required": [
+                "zh",
+                "en"
+              ]
+            }
           }
         },
         "required": [
@@ -7837,17 +8394,17 @@
         "properties": {
           "p": {
             "type": "integer",
-            "description": "页码，从 1 开始。",
+            "description": "页码，从 1 开始；小于 1 时按 1 处理。",
             "default": 1
           },
           "limit": {
             "type": "integer",
-            "description": "每页数量。",
+            "description": "每页条数；小于 1 时按 20 处理。",
             "default": 20
           },
           "scope": {
             "type": "string",
-            "description": "将结果限制为 `all`（默认）、仅 `account`（team_id=0）、或仅 `team`（排除账户级记录）；设置后会覆盖 `include_account`。",
+            "description": "要返回的技能范围；设置后覆盖 `include_account`：\n- `all`（默认）：账户级技能（除非 `include_account` 为 false）加上调用者所在团队的技能\n- `account`：仅账户级技能（`team_id` = 0）\n- `team`：仅调用者所在团队的技能",
             "enum": [
               "all",
               "account",
@@ -7865,7 +8422,7 @@
               "type": "integer",
               "format": "int64"
             },
-            "description": "按团队 ID 过滤；为空则使用调用者可见范围。"
+            "description": "将团队级结果限定为这些团队 ID；调用者不属于的团队会被忽略。为空表示调用者所在的全部团队。"
           },
           "include_account": {
             "type": [
@@ -7952,20 +8509,20 @@
           "file": {
             "type": "string",
             "format": "binary",
-            "description": "技能压缩包（.skill / .zip / .tar.gz / .tgz），最大 100MB；超限文件会在读取正文前即被拒绝。"
+            "description": "技能压缩包（`.skill`、`.zip`、`.tar.gz` 或 `.tgz`），最大 100 MB，`SKILL.md` 位于根目录或唯一的顶层文件夹内。"
           },
           "team_id": {
             "type": "integer",
-            "description": "新建/upsert 技能的团队范围：0 表示账户级。通过 `skill_id` 定向替换时会忽略该字段。",
+            "description": "新建或按名称覆盖的技能所在作用域：0 表示账户级（默认），>0 表示该团队。同时设置 `replace=true` 和 `skill_id` 时忽略。",
             "format": "int64"
           },
           "replace": {
             "type": "boolean",
-            "description": "为 true 时覆盖已有技能而非在名称冲突时报错 —— 若提供 `skill_id` 则按其匹配，否则按技能名称匹配。"
+            "description": "为 true 时覆盖已有技能，而不是在名称冲突时报错：覆盖 `skill_id` 指定的技能，否则覆盖 `team_id` 中的同名技能。可取 `true`、`1`、`yes`、`on`（不区分大小写），其他值视为 false。"
           },
           "skill_id": {
             "type": "string",
-            "description": "定向替换指定技能时的技能 ID（需配合 `replace=true`）。"
+            "description": "要覆盖的技能 ID，来自 `POST /safari/skill/list`。仅与 `replace=true` 一起使用，否则忽略。"
           }
         },
         "required": [
@@ -7987,7 +8544,7 @@
           },
           "scope": {
             "type": "string",
-            "description": "知识范围；`channel` 为历史遗留范围，新建知识为 `account` 或 `team`。",
+            "description": "知识范围。\n- `account`：账户级知识，整个账户共享；`scope_id` 为账户 ID。\n- `team`：归属某个团队的知识；`scope_id` 为团队 ID。\n- `channel`：历史遗留范围。无法通过本 API 创建或移入，`POST /safari/knowledge/pack/list` 也不会返回；只有按 `pack_id` 直接访问此类知识时才会出现。",
             "enum": [
               "account",
               "team",
@@ -8005,24 +8562,24 @@
           },
           "file_count": {
             "type": "integer",
-            "description": "知识内文件数量。"
+            "description": "知识中当前的文件数量。"
           },
           "total_bytes": {
             "type": "integer",
-            "description": "知识内所有文件的总字节数。",
+            "description": "所有文件的总大小（字节），每份知识上限 5 MiB。",
             "format": "int64"
           },
           "version": {
             "type": "integer",
-            "description": "知识版本号，文件每次变更时递增。"
+            "description": "知识版本号。从 0 开始，每次写入或删除文件加 1；移动知识范围不会改变版本号。"
           },
           "duty_version": {
             "type": "integer",
-            "description": "最后一次撰写或确认 DUTY.md 时的知识版本。当 `version` 大于该值时，说明 DUTY.md 已不能反映知识的全部文件。"
+            "description": "最近一次写入 `DUTY.md` 时的 `version`。写入 `DUTY.md` 会把它设为新的 `version`；当 `version` 更大时，说明 `DUTY.md` 上次更新后又有文件被新增、修改或删除，`DUTY.md` 可能未覆盖全部文件。"
           },
           "created_by": {
             "type": "integer",
-            "description": "创建者成员 ID。",
+            "description": "触发创建该知识的成员 ID。账户知识会在第一个需要它的请求中自动创建，因此可能是账户内任意成员。",
             "format": "int64"
           },
           "created_at_ms": {
@@ -8037,7 +8594,7 @@
           },
           "can_edit": {
             "type": "boolean",
-            "description": "调用者是否有权限编辑该知识。"
+            "description": "调用者能否修改该知识及其文件：`account` 范围仅账户 Owner 和管理员为 `true`；`team` 范围仅当调用者是该团队成员时为 `true`（Owner 和管理员也不例外）。"
           }
         },
         "required": [
@@ -8069,11 +8626,11 @@
           },
           "rel_path": {
             "type": "string",
-            "description": "相对于知识根目录的路径，如 `runbooks/restart.md`。"
+            "description": "相对于知识根目录的路径，以 `/` 分隔，如 `runbooks/restart.md`。在同一份知识内唯一。"
           },
           "content_type": {
             "type": "string",
-            "description": "MIME 类型；上传时未指定则按扩展名推断。"
+            "description": "文件的 MIME 类型，取值不固定：写入时未传 `content_type` 则按 `rel_path` 的扩展名推断——`.md` → `text/markdown`，`.yaml`/`.yml` → `text/yaml`，`.json` → `application/json`，`.sh` → `text/x-sh`，其他 → `text/plain`；显式传入的值原样保存。"
           },
           "size_bytes": {
             "type": "integer",
@@ -8120,11 +8677,11 @@
           },
           "ref": {
             "type": "string",
-            "description": "与提示相关的单个引用。"
+            "description": "仅 `unresolved_reference` 时返回：知识中不存在的被引用路径。"
           },
           "refs": {
             "type": "array",
-            "description": "与提示相关的多个引用。",
+            "description": "仅 `still_referenced_by` 时返回：仍引用被删文件的其他文件的 `rel_path` 列表。",
             "items": {
               "type": "string"
             }
@@ -8145,15 +8702,15 @@
         "properties": {
           "p": {
             "type": "integer",
-            "description": "页码，从 1 开始；`p` 与 `limit` 均未设置时返回全部结果。"
+            "description": "页码，从 1 开始。`p` 与 `limit` 都不传（或 ≤ 0）时不分页，返回全部匹配结果；只传 `limit` 时 `p` 默认为 1。"
           },
           "limit": {
             "type": "integer",
-            "description": "每页条数。"
+            "description": "每页条数。传了 `p` 但未传 `limit` 时默认为 20；不限制上限。"
           },
           "scope": {
             "type": "string",
-            "description": "限定范围；`all`（默认）会覆盖 `include_account`。可选值：`all`（账户范围 + 可见团队范围）、`account`（仅账户级知识）、`team`（仅团队级知识，可配合 `team_ids` 过滤）。",
+            "description": "返回哪些范围：\n- `all`（默认）：账户知识（`include_account` 为 `false` 时除外）加上可见的团队知识。\n- `account`：仅账户知识，忽略 `include_account` 和 `team_ids`。\n- `team`：仅团队知识，可用 `team_ids` 进一步筛选；忽略 `include_account`。",
             "enum": [
               "all",
               "account",
@@ -8162,12 +8719,12 @@
           },
           "query": {
             "type": "string",
-            "description": "对知识 ID、范围、范围 ID/账户 ID 和团队名称做大小写不敏感的子串过滤。",
+            "description": "对知识 ID、范围、范围 ID、账户 ID 和团队名称做大小写不敏感的子串过滤；账户知识还可匹配 `账户`/`账号`，团队知识还可匹配 `团队`。首尾空格会被忽略。",
             "maxLength": 128
           },
           "team_ids": {
             "type": "array",
-            "description": "限定团队 ID；非管理员会与其所属团队取交集。",
+            "description": "将团队知识限定在这些团队 ID 内。调用者不属于的团队 ID 会被静默丢弃——对所有调用者都一样，包括 Owner 和管理员。",
             "items": {
               "type": "integer",
               "format": "int64"
@@ -8178,7 +8735,7 @@
               "boolean",
               "null"
             ],
-            "description": "是否包含账户范围的知识；默认为 true。"
+            "description": "`scope` 为 `all` 或未传时是否包含账户知识，默认 `true`。"
           }
         }
       },
@@ -8188,7 +8745,7 @@
         "properties": {
           "scope": {
             "type": "string",
-            "description": "知识范围。可选值：`account`（账户级知识，scope_id 固定为调用方账户 ID，仅账户管理员可创建；首次创建会播种默认 DUTY.md）、`team`（团队级知识，必须提供 `scope_id` 团队 ID，调用者需属于该团队）。",
+            "description": "要确保存在的知识范围。\n- `account`：账户知识。`scope_id` 会被替换为调用者的账户 ID；仅账户 Owner 和管理员可调用，即使知识已存在也一样。若该知识中没有 `DUTY.md`，会写入一份默认 `DUTY.md`。\n- `team`：`scope_id` 指定团队的知识。必须传 `scope_id`，且调用者须是该团队成员。",
             "enum": [
               "account",
               "team"
@@ -8196,7 +8753,7 @@
           },
           "scope_id": {
             "type": "integer",
-            "description": "团队 ID；团队范围必填，账户范围忽略。",
+            "description": "团队 ID。`team` 范围必填（非 0），否则返回 `InvalidParameter`；`account` 范围忽略。",
             "format": "int64"
           }
         },
@@ -8217,7 +8774,7 @@
               "string",
               "null"
             ],
-            "description": "目标范围；不传则为空操作，返回当前知识。",
+            "description": "目标范围。不传则不做修改，直接返回当前知识。\n- `account`：设为账户知识（仅账户 Owner 和管理员）。\n- `team`：移到 `scope_id` 指定的团队（调用者须是该团队成员）。\n其他取值返回 `InvalidParameter`。目标范围已有知识时返回 `ReferenceExist`。",
             "enum": [
               "account",
               "team"
@@ -8228,7 +8785,7 @@
               "integer",
               "null"
             ],
-            "description": "目标团队 ID；`scope` 为 `team` 时必填，为 `account` 时自动设置。",
+            "description": "目标团队 ID。`scope` 为 `team` 时必填（非 0）；`scope` 为 `account` 时忽略（使用账户 ID）。",
             "format": "int64"
           }
         },
@@ -8255,7 +8812,7 @@
         "properties": {
           "ok": {
             "type": "boolean",
-            "description": "知识删除成功时为 true。"
+            "description": "成功时恒为 `true`；删除失败会直接返回错误。"
           }
         },
         "required": [
@@ -8290,7 +8847,7 @@
           },
           "rel_path": {
             "type": "string",
-            "description": "文件相对于知识根目录的路径。"
+            "description": "文件相对于知识根目录的路径。该路径下没有文件时调用仍然成功，`file` 为 `null`，`content_b64` 为空。"
           }
         },
         "required": [
@@ -8307,15 +8864,21 @@
           },
           "rel_path": {
             "type": "string",
-            "description": "相对于知识根目录的目标路径；已存在的文件会被覆盖。"
+            "description": "目标路径，相对于知识根目录；该路径已有文件时会被覆盖。必须以 `/` 分隔、不能以 `/` 开头、必须是规范化形式，且任一路径段不能为空、`.`、`..` 或以 `.` 开头（不允许隐藏文件）。"
           },
           "content_b64": {
             "type": "string",
-            "description": "Base64 编码的文件内容；解码后必须是合法的 UTF-8 文本（拒绝二进制）。单文件上限 1 MiB。"
+            "description": "Base64（标准字母表）编码的文件内容。解码后必须是不含 NUL 字节的 UTF-8 文本，且不超过 1 MiB（`DUTY.md` 不超过 32 KiB）。不传或传空字符串则写入空文件。"
           },
           "content_type": {
             "type": "string",
-            "description": "MIME 类型；留空时按扩展名推断。"
+            "description": "与文件一起保存的 MIME 类型。可选：不传时按 `rel_path` 扩展名推断（`.md` → `text/markdown`，`.yaml`/`.yml` → `text/yaml`，`.json` → `application/json`，`.sh` → `text/x-sh`，其他 → `text/plain`）。传入的值原样保存。"
+          },
+          "expected_version": {
+            "type": "integer",
+            "minimum": 0,
+            "default": 0,
+            "description": "乐观并发校验。`0` 或不传：无条件写入。正数：仅当知识当前 `version` 等于该值时才写入；否则不写入，返回 HTTP 200，`status` 为 `conflict` 并带上当前 `version`。"
           }
         },
         "required": [
@@ -8366,7 +8929,7 @@
       },
       "KnowledgeFileListResponse": {
         "type": "object",
-        "description": "知识内的文件。",
+        "description": "知识中的全部文件及当前知识版本号。",
         "properties": {
           "files": {
             "type": "array",
@@ -8377,49 +8940,85 @@
           },
           "total": {
             "type": "integer",
-            "description": "知识内文件总数。",
+            "description": "`files` 中的文件数，即知识的全部文件数（该接口不分页）。",
             "format": "int64"
+          },
+          "version": {
+            "type": "integer",
+            "description": "知识当前的 `version`，可作为文件写入的 `expected_version`。"
           }
         },
         "required": [
           "files",
-          "total"
+          "total",
+          "version"
         ]
       },
       "KnowledgeFileGetResponse": {
         "type": "object",
-        "description": "文件元数据及其 Base64 编码的内容。",
+        "description": "文件元数据、Base64 编码的文件内容以及当前知识版本号。",
         "properties": {
           "file": {
-            "$ref": "#/components/schemas/KnowledgeFileItem"
+            "description": "文件元数据；`rel_path` 下没有文件时为 `null`。",
+            "oneOf": [
+              {
+                "$ref": "#/components/schemas/KnowledgeFileItem"
+              },
+              {
+                "type": "null"
+              }
+            ]
           },
           "content_b64": {
             "type": "string",
-            "description": "Base64 编码的文件内容；解码后为 UTF-8 文本。"
+            "description": "Base64 编码的文件内容。文件不存在（或内容为空）时为空字符串。"
+          },
+          "version": {
+            "type": "integer",
+            "description": "知识当前的 `version`。可作为 `expected_version` 传给 `POST /safari/knowledge/file/put` 或 `POST /safari/knowledge/file/delete`，若期间知识被他人修改则拒绝写入。"
           }
         },
         "required": [
           "file",
-          "content_b64"
+          "content_b64",
+          "version"
         ]
       },
       "KnowledgeFilePutResponse": {
         "type": "object",
-        "description": "写入的文件及非阻塞提示。",
+        "description": "写入结果。成功时包含写入的文件；版本冲突时只有 `status`、`version` 和 `message`。",
         "properties": {
+          "status": {
+            "type": "string",
+            "enum": [
+              "ok",
+              "conflict"
+            ],
+            "description": "写入结果。\n- `ok`：修改已提交。\n- `conflict`：`expected_version` 与知识当前版本不一致，未做任何修改；请重新读取文件后用返回的 `version` 重试。"
+          },
           "file": {
-            "$ref": "#/components/schemas/KnowledgeFileItem"
+            "$ref": "#/components/schemas/KnowledgeFileItem",
+            "description": "写入后保存的文件。`status` 为 `conflict` 时不返回。"
           },
           "warnings": {
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/KnowledgeWarning"
             },
-            "description": "写入成功后的非阻塞警告数组；`code=unresolved_reference` 表示文件内容中的 @ref 引用了知识内不存在的文件。无警告时该字段缺省（omitempty）。"
+            "description": "非阻塞警告；`unresolved_reference` 表示写入内容中的 @ref 指向知识中不存在的路径。没有警告时不返回。"
+          },
+          "version": {
+            "type": "integer",
+            "description": "`status` 为 `ok` 时是本次写入产生的知识 `version`；为 `conflict` 时是知识当前版本。可作为下一次写入的 `expected_version`。"
+          },
+          "message": {
+            "type": "string",
+            "description": "冲突说明（`this knowledge was updated by someone else`）。仅 `status` 为 `conflict` 时返回。"
           }
         },
         "required": [
-          "file"
+          "status",
+          "version"
         ]
       },
       "KnowledgeFileDeleteRequest": {
@@ -8432,11 +9031,17 @@
           },
           "rel_path": {
             "type": "string",
-            "description": "文件相对于知识根目录的路径。"
+            "description": "文件相对于知识根目录的路径，路径规则与 `POST /safari/knowledge/file/put` 相同。"
           },
           "force": {
             "type": "boolean",
             "description": "即使其他知识文件仍引用该文件也强制删除；此时引用方会以警告形式返回，而不再阻止删除。"
+          },
+          "expected_version": {
+            "type": "integer",
+            "minimum": 0,
+            "default": 0,
+            "description": "乐观并发校验。`0` 或不传：无条件删除。正数：仅当知识当前 `version` 等于该值时才删除；否则不删除，返回 HTTP 200，`status` 为 `conflict` 并带上当前 `version`。"
           }
         },
         "required": [
@@ -8445,16 +9050,36 @@
       },
       "KnowledgeFileDeleteResponse": {
         "type": "object",
-        "description": "删除结果；无警告时为空对象。",
+        "description": "删除结果。",
         "properties": {
+          "status": {
+            "type": "string",
+            "enum": [
+              "ok",
+              "conflict"
+            ],
+            "description": "删除结果。\n- `ok`：文件已删除，或本来就不存在。\n- `conflict`：`expected_version` 与知识当前版本不一致，未删除任何内容。"
+          },
           "warnings": {
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/KnowledgeWarning"
             },
-            "description": "删除后的非阻塞警告数组；`code=still_referenced_by` 表示被（强制）删除的文件仍被知识内其他文件 @ref 引用（`refs` 列出引用方）。无警告时该字段缺省（omitempty）。"
+            "description": "非阻塞警告；`still_referenced_by` 表示通过 `force` 删除了仍被其他文件引用的文件（`refs` 列出引用方）。没有警告时不返回。"
+          },
+          "version": {
+            "type": "integer",
+            "description": "删除后的知识 `version`（文件不存在时不变）。文件不存在且未传 `expected_version` 时为 `0`。`conflict` 时为知识当前版本。"
+          },
+          "message": {
+            "type": "string",
+            "description": "冲突说明。仅 `status` 为 `conflict` 时返回。"
           }
-        }
+        },
+        "required": [
+          "status",
+          "version"
+        ]
       },
       "ArtifactIdRequest": {
         "type": "object",
@@ -8489,7 +9114,7 @@
               "type": "integer",
               "format": "int64"
             },
-            "description": "只看指定团队的产物，与调用者可见范围取交集 —— 不属于调用者的团队不会有任何返回。"
+            "description": "只看这些团队拥有的产物，与 `scope` 条件取交集。小于等于 0 的 ID 会被忽略；调用者不属于的团队不会有返回，且设置该字段后不会返回个人产物。"
           },
           "query": {
             "type": "string",
@@ -8498,14 +9123,12 @@
           "page": {
             "type": "integer",
             "default": 1,
-            "minimum": 1,
-            "description": "页码，从 1 开始。"
+            "description": "页码，从 1 开始。小于 1 时按 1 处理。"
           },
           "limit": {
             "type": "integer",
             "default": 20,
-            "maximum": 100,
-            "description": "每页条数。默认 20，最大 100。"
+            "description": "每页条数。小于 1 时按 20 处理；大于 100 时按 100 处理（不会报错）。"
           },
           "orderby": {
             "type": "string",
@@ -8513,7 +9136,7 @@
               "created_at",
               "updated_at"
             ],
-            "description": "排序字段：`created_at` 或 `updated_at`。留空按 `updated_at` 倒序。"
+            "description": "排序字段：`created_at`（发布时间）或 `updated_at`（最近变更时间）。留空时按 `updated_at` 倒序。无论哪种排序，调用者置顶的产物都排在最前，相同值再按 `artifact_id` 排序。"
           },
           "asc": {
             "type": "boolean",
@@ -8530,14 +9153,18 @@
             "items": {
               "$ref": "#/components/schemas/PublishedArtifactItem"
             },
-            "description": "当前页的产物列表。"
+            "description": "本页产物；调用者置顶的产物排在最前。无匹配时为空数组。"
           },
           "total": {
             "type": "integer",
             "format": "int64",
             "description": "符合过滤条件的产物总数（跨所有页）。"
           }
-        }
+        },
+        "required": [
+          "items",
+          "total"
+        ]
       },
       "PublishedArtifactItem": {
         "type": "object",
@@ -8554,7 +9181,7 @@
           "team_id": {
             "type": "integer",
             "format": "int64",
-            "description": "归属团队 ID。`0` 表示个人产物（仅创建者可管理）；大于 0 表示团队产物。"
+            "description": "归属空间。`0` 表示个人产物：只出现在创建者的列表中，可由创建者或能管理来源会话的成员管理。大于 0 时为归属团队 ID：出现在该团队成员的列表中，团队任一成员都可管理。首次发布时取自来源会话，可通过 `/safari/artifact/gallery/update` 修改。"
           },
           "team_name": {
             "type": "string",
@@ -8563,7 +9190,7 @@
           "person_id": {
             "type": "integer",
             "format": "int64",
-            "description": "创建者的成员 ID。"
+            "description": "产物创建者的成员 ID，即首次发布时来源会话的所有者。重新发布或转移空间都不会改变它。"
           },
           "creator_name": {
             "type": "string",
@@ -8571,7 +9198,7 @@
           },
           "is_mine": {
             "type": "boolean",
-            "description": "调用者是否为创建者。"
+            "description": "调用者（`app_key` 调用时为 key 所属成员）是创建者时为 `true`，即 `person_id` 等于调用者的成员 ID。"
           },
           "can_edit": {
             "type": "boolean",
@@ -8591,7 +9218,7 @@
           },
           "name": {
             "type": "string",
-            "description": "底层文件名（含扩展名）。"
+            "description": "底层文件名（含扩展名）。底层文件记录缺失时为空字符串。"
           },
           "size": {
             "type": "integer",
@@ -8600,7 +9227,7 @@
           },
           "content_type": {
             "type": "string",
-            "description": "文件的 MIME 类型。"
+            "description": "MIME 类型，在文件产出时按文件扩展名推断：`text/html`（.html/.htm）、`text/markdown`（.md）、`text/plain`（.txt/.log）、`text/csv`、`text/yaml`（.yaml/.yml）、`text/x-python`、`text/x-go`、`text/x-sh`、`application/json`、`application/xml`、`application/pdf`、`image/png`、`image/jpeg`、`image/gif`、`image/svg+xml`、`image/webp`、`application/zip`、`application/gzip`（.tar/.gz/.tgz）；其他扩展名为 `application/octet-stream`。底层文件记录缺失时为空字符串。"
           },
           "created_at": {
             "type": "integer",
@@ -8610,7 +9237,12 @@
           "updated_at": {
             "type": "integer",
             "format": "int64",
-            "description": "产物最近一次更新（重命名、转移或重新发布）的 Unix 毫秒时间戳。"
+            "description": "产物记录最近一次变更（重命名、转移、重新发布或分享状态变化）的 Unix 毫秒时间戳。"
+          },
+          "pinned_at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "调用者在控制台产物库中置顶该产物的 Unix 毫秒时间戳。置顶按成员各自记录；调用者未置顶时不返回该字段。置顶的产物在 `/safari/artifact/gallery/list` 中排在最前。"
           },
           "share_enabled": {
             "type": "boolean",
@@ -8623,7 +9255,7 @@
           "shared_by": {
             "type": "integer",
             "format": "int64",
-            "description": "开启分享的成员 ID。仅在分享开启时返回。"
+            "description": "开启分享的成员 ID；之后同步快照不会改变它。仅在分享开启时返回。"
           },
           "shared_at": {
             "type": "integer",
@@ -8665,7 +9297,7 @@
               "string",
               "null"
             ],
-            "description": "新标题。会去除首尾空白，传入时不能为空。不传则不变。"
+            "description": "新标题。会去除首尾空白，为空时返回 `InvalidParameter`。不传或传 `null` 则保持不变。"
           },
           "team_id": {
             "type": [
@@ -8673,7 +9305,7 @@
               "null"
             ],
             "format": "int64",
-            "description": "转移目标空间。`0` 表示转为个人产物（仅创建者可管理）；大于 0 表示转移到调用者所属的团队。不传则不变。"
+            "description": "转移目标。`0` 表示转为个人产物，仅创建者本人可执行；大于 0 表示转移到该团队，调用者必须是该团队成员；负数返回 `InvalidParameter`。不传或传 `null` 则保持当前空间。创建者（`person_id`）不会改变。"
           }
         },
         "required": [
@@ -8732,7 +9364,7 @@
             },
             "maxItems": 50,
             "minItems": 1,
-            "description": "要查询的文件 ID（`pf_` 前缀）。单次最多 50 个；重复和空字符串会被忽略。"
+            "description": "要查询的文件 ID（`pf_` 前缀）。单次最多 50 个，按去重和去除空字符串之前的数量计算；超出时返回 `InvalidParameter`。"
           }
         },
         "required": [
@@ -8741,11 +9373,11 @@
       },
       "ArtifactFileStateItem": {
         "type": "object",
-        "description": "单个文件的发布状态。仅当文件存在已发布的产物时才会返回。",
+        "description": "单个文件的产物发布状态。按文件所属会话和工作区路径匹配，因此已被重新发布的文件的旧版本也会返回当前产物。",
         "properties": {
           "file_id": {
             "type": "string",
-            "description": "回显请求中的文件 ID。"
+            "description": "该条结果对应的请求文件 ID。"
           },
           "artifact_id": {
             "type": "string",
@@ -8776,7 +9408,7 @@
             "items": {
               "$ref": "#/components/schemas/ArtifactFileStateItem"
             },
-            "description": "每个存在已发布产物的请求文件对应一条记录；未发布的文件不会出现在列表中。"
+            "description": "每个其会话文件路径当前有已发布产物的请求文件对应一条；没有已发布产物的文件和不存在的 ID 不会出现。都不匹配时为空数组。"
           }
         },
         "required": [
@@ -8797,12 +9429,12 @@
           },
           "public_url": {
             "type": "string",
-            "description": "完全由 CDN 承载的匿名公开链接。任何拿到链接的人无需登录即可查看内容。"
+            "description": "匿名公开链接，形如 `<控制台域名>/share/artifact/<artifact_id>`。任何拿到链接的人无需登录即可查看内容。每次开启分享得到的都是同一个链接。"
           },
           "shared_by": {
             "type": "integer",
             "format": "int64",
-            "description": "开启分享的成员 ID。"
+            "description": "开启分享的成员 ID。同步快照时保持原值。"
           },
           "shared_at": {
             "type": "integer",
@@ -8849,7 +9481,7 @@
           },
           "expires_in": {
             "type": "integer",
-            "description": "两个链接的有效期，单位秒（300）。"
+            "description": "两个链接的有效期，单位秒。固定为 `300`。"
           },
           "name": {
             "type": "string",
@@ -8862,7 +9494,7 @@
           },
           "content_type": {
             "type": "string",
-            "description": "文件的 MIME 类型。"
+            "description": "MIME 类型，在文件产出时按文件扩展名推断：`text/html`（.html/.htm）、`text/markdown`（.md）、`text/plain`（.txt/.log）、`text/csv`、`text/yaml`（.yaml/.yml）、`text/x-python`、`text/x-go`、`text/x-sh`、`application/json`、`application/xml`、`application/pdf`、`image/png`、`image/jpeg`、`image/gif`、`image/svg+xml`、`image/webp`、`application/zip`、`application/gzip`（.tar/.gz/.tgz）；其他扩展名为 `application/octet-stream`。"
           }
         },
         "required": [
diff --git a/en/developer/go-sdk.mdx b/en/developer/go-sdk.mdx
index ec2d19cc3..e8543a72c 100644
--- a/en/developer/go-sdk.mdx
+++ b/en/developer/go-sdk.mdx
@@ -325,7 +325,7 @@ for page := 0; page < 100; page++ {
 
 An unsuccessful call returned by the Flashduty API — whether the envelope carries an error or the HTTP status is non-2xx — returns `*ErrorResponse`. It has `Code`, `Message`, an optional `Reason`, and `RequestID` fields; when troubleshooting, give `RequestID` to the support team to pinpoint the request. `Reason` carries the server-supplied optional cause (the envelope's `DutyError` has the same field, JSON `reason`,omitempty); when non-empty it is also appended to the end of the error string, as `, reason X`.
 
-When the API returns 429, the error is promoted to `*RateLimitError`: it embeds `*ErrorResponse` (so `errors.As` for `*ErrorResponse` still matches) and additionally carries a `RetryAfter` hint. `Code` values match the Open API [error code list](/en/openapi/introduction#error-code-list).
+When the API returns 429, the error is promoted to `*RateLimitError`: it embeds `*ErrorResponse` (so `errors.As` for `*ErrorResponse` still matches) and additionally carries a `RetryAfter` hint. `Code` values match the Open API [error code list](/en/openapi/rate-limits#error-codes).
 
 <Note>
 For **generated endpoints**, if you receive a non-2xx response with a non-JSON body, the SDK returns a plain `error`, not `*ErrorResponse`. This indicates that a gateway, load balancer, proxy, or other intermediary produced the response, usually because the request exceeded an intermediary timeout. Retry the request or split a long-running batch into smaller batches, and do not assume that `errors.As(err, &apiErr)` matches this error.
diff --git a/en/openapi/api-catalog.mdx b/en/openapi/api-catalog.mdx
index 05864e6c4..14490d318 100644
--- a/en/openapi/api-catalog.mdx
+++ b/en/openapi/api-catalog.mdx
@@ -3,7 +3,7 @@ title: "API catalog"
 description: "Complete list of Flashduty Open API endpoints, organized by product module with links to detailed documentation"
 ---
 
-Flashduty Open API provides **365** endpoints covering five major modules: On-call, Monitors, RUM, AI SRE, and Platform. All endpoints use unified authentication and request specifications. See [Quick Start](/en/openapi/introduction) for details.
+Flashduty Open API provides **370** endpoints covering five major modules: On-call, Monitors, RUM, AI SRE, and Platform. All endpoints use unified authentication and request specifications. See [Quick Start](/en/openapi/introduction) for details.
 
 <Note>
 All endpoint URLs use `https://api.flashcat.cloud` as the base, authenticated through APP Key through query string.
@@ -282,7 +282,7 @@ The `/integration/*` management APIs cover public (account-level) integrations,
 
 </Accordion>
 
-<Accordion title="Monitors (41 endpoints)">
+<Accordion title="Monitors (46 endpoints)">
 
 ### Alert rules
 
@@ -358,6 +358,11 @@ Alert rule import and export are available in the console only (the YAML rule bu
 | Method | Endpoint | Description |
 | :--- | :--- | :--- |
 | POST | [`/monit/folder/list`](/en/api-reference/monitors/rule-folders/monit-folder-read-list) | List monitor folders |
+| POST | [`/monit/folder/health`](/en/api-reference/monitors/rule-folders/monit-folder-read-health) | Get monitor folder health |
+| POST | [`/monit/folder/create`](/en/api-reference/monitors/rule-folders/monit-folder-write-create) | Create monitor folder |
+| POST | [`/monit/folder/update`](/en/api-reference/monitors/rule-folders/monit-folder-write-update) | Update monitor folder |
+| POST | [`/monit/folder/move`](/en/api-reference/monitors/rule-folders/monit-folder-write-move) | Move monitor folder |
+| POST | [`/monit/folder/delete`](/en/api-reference/monitors/rule-folders/monit-folder-write-delete) | Delete monitor folder |
 
 </Accordion>
 
diff --git a/en/openapi/introduction.mdx b/en/openapi/introduction.mdx
index 18768f9de..01ef4fe41 100644
--- a/en/openapi/introduction.mdx
+++ b/en/openapi/introduction.mdx
@@ -21,29 +21,35 @@ Open API lets you call Flashduty through HTTP endpoints to query and manage enti
 
 ### Request URL
 
-All APIs only accept access through **HTTPS** protocol and have a single Endpoint:
+All APIs are served over **HTTPS** from a single endpoint:
 
 ```
 https://api.flashcat.cloud
 ```
 
-### Headers
+### Method and headers
 
-Most requests use the POST method with JSON Payload parameters. Please ensure the correct Content-Type is set:
+Almost every operation is a `POST` with a JSON body, so set:
 
 ```
 Content-Type: application/json
 ```
 
+A few read operations use `GET` with query parameters (for example the status page reads and the Prometheus-compatible label query); each operation page shows its method. Send `{}` as the body of a `POST` that takes no parameters.
+
 ### Character encoding
 
-All APIs use **UTF-8** encoding.
+All requests and responses use **UTF-8**.
+
+### Response language
+
+Error messages are localized. The language is taken, in order, from the `locale` query parameter, the `lang` query parameter, then the `Accept-Language` header, for example `Accept-Language: en-US` or `zh-CN`. Field names, enum values, and error codes are never translated.
 
 ---
 
 ## Authentication
 
-All Open APIs use **APP Key** for authentication.
+All Open APIs authenticate with an **APP Key**.
 
 ### Obtaining an APP key
 
@@ -60,21 +66,32 @@ All Open APIs use **APP Key** for authentication.
 </Steps>
 
 <Warning>
-An APP Key's effective access is constrained by both its permission scope and the creator's current role permissions. Store the full key securely as soon as it is created; it cannot be viewed again after you leave the creation page.
+An APP Key's effective access is constrained by both its permission scope and the creator's current role permissions. Store the full key securely as soon as it is created; it cannot be viewed again after you leave the creation page. Do not hardcode it in client code; load it from an environment variable or a secret manager, and delete keys you no longer use.
 </Warning>
 
 You can edit an existing APP Key's name and permission scope from the APP Key list.
 
-### Usage example
+### Passing the APP key
 
-Pass the APP Key as a query string parameter:
+Pass the key as the `app_key` query parameter:
 
 ```bash
-curl -X POST 'https://api.flashcat.cloud/your/api/path?app_key=YOUR_APP_KEY' \
+curl -X POST 'https://api.flashcat.cloud/incident/list?app_key=YOUR_APP_KEY' \
   -H 'Content-Type: application/json' \
-  -d '{"param": "value"}'
+  -d '{"start_time": 1712000000, "end_time": 1712086400, "limit": 20}'
 ```
 
+Or send it in the `Fd-App-Key` request header, which keeps the key out of URLs and access logs:
+
+```bash
+curl -X POST 'https://api.flashcat.cloud/incident/list' \
+  -H 'Fd-App-Key: YOUR_APP_KEY' \
+  -H 'Content-Type: application/json' \
+  -d '{"start_time": 1712000000, "end_time": 1712086400, "limit": 20}'
+```
+
+When both are present, the query parameter wins. A missing or invalid key returns `401 Unauthorized`.
+
 <Note>
 Using Go? Use the official [Go SDK](/en/developer/go-sdk) to call Flashduty — you get typed request parameters, response structs, and error codes out of the box, with no hand-written HTTP.
 </Note>
@@ -83,13 +100,15 @@ Using Go? Use the official [Go SDK](/en/developer/go-sdk) to call Flashduty —
 
 ## Response structure
 
-All request responses are in JSON format and follow a unified structure:
+All responses are JSON with the same envelope:
 
-| Field | Type | Required | Description |
+| Field | Type | Always present | Description |
 | --- | --- | :---: | --- |
-| `request_id` | string | ✅ | Request ID for tracing |
-| `error` | object | | Error description, returned only when an error occurs |
-| `data` | any | | Data content, refer to each API definition for specific format |
+| `request_id` | string | ✅ | Request ID, also returned in the `Flashcat-Request-Id` response header. Include it when contacting support. |
+| `data` | any | | Operation-specific payload, documented on each operation page. Operations with no payload return `{}` or omit `data` entirely, so do not rely on its presence. Absent on errors. |
+| `error` | object | | Present only when the request failed. |
+
+Success returns HTTP `200`. Failures return the HTTP status listed in the [error code list](/en/openapi/rate-limits#error-codes), but branch on `error.code`, not on the status.
 
 ### Response examples
 
@@ -97,10 +116,10 @@ All request responses are in JSON format and follow a unified structure:
   <Tab title="Success Response">
 ```json
 {
-  "request_id": "abc123456",
+  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
   "data": {
-    "id": "user_001",
-    "name": "example"
+    "team_id": 1467226103121,
+    "team_name": "SRE"
   }
 }
 ```
@@ -108,10 +127,10 @@ All request responses are in JSON format and follow a unified structure:
   <Tab title="Error Response">
 ```json
 {
-  "request_id": "abc123456",
+  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
   "error": {
     "code": "InvalidParameter",
-    "message": "Parameter name cannot be empty"
+    "message": "The specified parameter team_name is not valid."
   }
 }
 ```
@@ -120,104 +139,23 @@ All request responses are in JSON format and follow a unified structure:
 
 ### Error object structure
 
-| Field | Type | Required | Description |
+| Field | Type | Always present | Description |
 | --- | --- | :---: | --- |
-| `code` | string | ✅ | Error code, see [Error Code List](#error-code-list) below |
-| `message` | string | | Error description |
+| `code` | string | ✅ | Stable error code, see the [error code list](/en/openapi/rate-limits#error-codes) |
+| `message` | string | ✅ | Human-readable description in the response language; may name the offending field. Do not parse it. |
 
 ---
 
-## Rate limits
-
-### Rate limits
-
-To ensure service stability, APIs have rate limits on request frequency. When requests are too frequent, a `429` status code with `RequestTooFrequently` error will be returned.
-
-<Warning>
-Please control your request frequency reasonably and avoid sending a large number of requests in a short period. It is recommended to implement a retry mechanism with exponential backoff when receiving a 429 error.
-</Warning>
-
-### Permission limits
-
-- An APP Key with **All permissions** has no additional API-scope restriction, but remains limited by the creator's current role permissions
-- **Custom permissions** requires at least one selected API permission; the APP Key can call only APIs in that selected scope
-- When an operation exceeds either the APP Key scope or the creator's role permissions, a `403` status code with `AccessDenied` error is returned
-- It is recommended to create separate APP Keys for different purposes, following the principle of least privilege
-
-### Error code list
-
-| Error Code | HTTP Status | Description |
-| --- | :---: | --- |
-| `InvalidParameter` | 400 | Parameter error, please check if request parameters are correct |
-| `InvalidContentType` | 400 | Content-Type not supported, please use `application/json` |
-| `MethodNotAllowed` | 400 | HTTP Method not supported |
-| `Unauthorized` | 401 | Authentication failed, please check if the APP Key is correct |
-| `AccessDenied` | 403 | Permission denied, current user does not have permission for this operation |
-| `RouteNotFound` | 404 | Request Method + Path not matched, please check the API address |
-| `RequestTooFrequently` | 429 | Request too frequent, please try again later |
-| `ResourceNotFound` | 400 | Account has not purchased resources, please go to the billing center to place an order |
-| `NoLicense` | 400 | Account does not have sufficient subscription License, please go to the billing center to upgrade or purchase a subscription |
-| `InternalError` | 500 | Internal or unknown error, please contact technical support |
-
----
+## Data conventions
 
-## Error handling recommendations
-
-<AccordionGroup>
-  <Accordion title="400 Parameter Error">
-    **Possible causes**:
-    - Missing required parameters
-    - Incorrect parameter format
-    - Content-Type not set to `application/json`
-    
-    **Solution**:
-    Check request parameters and Headers settings, refer to API documentation for parameter requirements.
-  </Accordion>
-
-  <Accordion title="401 Authentication Failed">
-    **Possible causes**:
-    - APP Key not provided
-    - APP Key is incorrect or has expired
-    
-    **Solution**:
-    1. Confirm that the request URL contains the `app_key` parameter
-    2. Go to the console to check if the APP Key is valid
-  </Accordion>
-
-  <Accordion title="403 Permission Denied">
-    **Possible causes**:
-    - Current user does not have permission to perform this operation
-    - The user corresponding to the APP Key has insufficient permissions
-    
-    **Solution**:
-    Contact the account administrator to elevate permissions, or use an APP Key with the appropriate permissions.
-  </Accordion>
-
-  <Accordion title="429 Too Many Requests">
-    **Possible causes**:
-    - Too many requests sent in a short period
-    
-    **Solution**:
-    1. Reduce request frequency
-    2. Implement exponential backoff retry mechanism
-    3. Combine multiple requests (for example, use batch APIs)
-  </Accordion>
-
-  <Accordion title="500 Internal Error">
-    **Possible causes**:
-    - Server-side internal exception
-    
-    **Solution**:
-    1. Retry later
-    2. If the issue persists, contact technical support and provide the `request_id`
-  </Accordion>
-</AccordionGroup>
+- **Timestamps** are Unix epoch integers. Most are in **seconds**; some (most AI SRE and RUM timestamps, incident feed entries, audit logs) are in **milliseconds**. Every time field states its unit in its description.
+- **Enums** are case-sensitive strings or integers; each field lists its allowed values and what they mean.
+- **IDs** are returned as integers or strings exactly as documented per field; send them back in the same type.
+- **Lists** are paginated; see [About pagination](/en/openapi/pagination).
+- **Updates**: each update operation states, per field, whether an omitted field keeps its current value or is cleared.
 
 ---
 
-## Best practices
+## Limits and errors
 
-- **Implement Retry Mechanism**: For network errors and 5xx errors, it is recommended to implement exponential backoff retry with an initial interval of 1 second and a maximum of 3 retries.
-- **Record request_id**: Save the `request_id` returned from each request to facilitate troubleshooting and technical support.
-- **Protect APP Key**: Do not hardcode APP Key in client code. It is recommended to manage it through environment variables or configuration centers.
-- **Rotate Keys Regularly**: Regularly replace APP Keys and promptly delete keys that are no longer in use to reduce the risk of leakage.
+Rate limits, permission checks, the full error code list, and retry advice are on [Rate limits and errors](/en/openapi/rate-limits). Each operation page also lists its own rate limits and required permission under **Restrictions**.
diff --git a/en/openapi/pagination.mdx b/en/openapi/pagination.mdx
index 1439a9047..e68d291a0 100644
--- a/en/openapi/pagination.mdx
+++ b/en/openapi/pagination.mdx
@@ -3,25 +3,23 @@ title: "About pagination"
 description: "Flashduty Open API pagination mechanism"
 ---
 
-In general, when we pull or retrieve certain data objects, data is returned in batches based on pagination, rather than returning all data in a single request.
+List operations return results in pages. Most use page-number pagination; operations over large or fast-changing collections also accept a cursor. The parameters an operation supports, and their limits and defaults, are documented on its page — the values below are the common defaults, not guarantees for every operation.
 
-## Traditional pagination
-
-We define pagination technology based on OFFSET and LIMIT queries as traditional pagination. In most Flashduty list query APIs, you can see the following parameter definitions:
+## Page-number pagination
 
 ### Request parameters
 
 | Parameter | Type | Description |
 | --- | --- | --- |
-| `p` | number | Page number, starting from 1 by default. offset = (p - 1) * limit |
-| `limit` | number | Number of items per page, maximum value not exceeding 100, default is 20 |
+| `p` | integer | Page number, starting at 1. Omitted or `0` means 1. offset = (p - 1) × limit |
+| `limit` | integer | Items per page. Typically at most 100, default 20; some operations use other bounds, shown on their page. |
 
-### Response parameters
+### Response fields
 
-| Parameter | Type | Description |
+| Field | Type | Description |
 | --- | --- | --- |
-| `total` | number | Total number of matched entries under current conditions |
-| `has_next_page` | boolean | Whether there is next page data under current conditions |
+| `total` | integer | Number of matching items (see [About total](#about-total)) |
+| `has_next_page` | boolean | Whether another page exists |
 
 ### Example
 
@@ -38,60 +36,42 @@ We define pagination technology based on OFFSET and LIMIT queries as traditional
 ```json
 {
   "total": 1000,
-  "has_next_page": true
+  "has_next_page": true,
+  "items": []
 }
 ```
   </Tab>
 </Tabs>
 
-### Potential issues
-
-Although querying based on traditional pagination technology is simple, you may encounter the following issues:
-
-<AccordionGroup>
-  <Accordion title="Performance Issues">
-    When using OFFSET and LIMIT for paginated queries, the database needs to skip a specified number of rows (OFFSET) and then return a specified number of rows (LIMIT). As the offset increases, query performance may decrease, especially when handling large amounts of data. Each query needs to scan and skip the previous rows, which causes queries to become slower and slower.
-  </Accordion>
-  <Accordion title="Data Instability">
-    When using PAGE and LIMIT for paginated queries, if data is deleted or inserted during the query, results may become unstable. For example, if previous rows are deleted during the query process, subsequent offsets may become invalid, leading to inaccurate or missing results.
-  </Accordion>
-</AccordionGroup>
-
-### Query limits
-
-To protect the system and ensure stable access for most users, we have imposed the following restrictions on API parameters based on traditional pagination technology:
+### Depth limit
 
 <Warning>
-PAGE × LIMIT must be ≤ 10000. If it exceeds 10000, the system will directly return a 400 error. In this case, please switch to cursor pagination or narrow your query conditions.
+On On-call list operations, `p × limit` must be at most 10,000. Deeper pages fail with `400 InvalidParameter`. To walk further, use cursor pagination where the operation supports it, or narrow the filters (for example, a shorter time range).
 </Warning>
 
+Page-number pagination can skip or repeat items when objects are created or deleted between two calls, because offsets shift. Use a cursor for complete, stable exports.
+
 ---
 
 ## Cursor pagination
 
-We define pagination technology based on SEARCH_AFTER_CTX as cursor pagination. Cursor pagination technology can better handle large datasets and high-performance requirements, providing a more stable and efficient paginated query experience.
-
-### Supported APIs
+Pass `search_after_ctx` from the previous response to get the next page. A cursor is opaque: do not build or modify it, and keep the other request parameters unchanged between pages. When `search_after_ctx` is set, `p` is ignored.
 
-We provide cursor pagination support in the following APIs:
-
-- [Incident List](/en/api-reference/on-call/incidents/incident-list)
-- [Alert List](/en/api-reference/on-call/alerts/alert-read-list)
+On List incidents and List alerts you can start with page-number pagination and switch at any time: every non-empty page also returns `search_after_ctx`, the cursor after its last item.
 
 ### Request parameters
 
 | Parameter | Type | Description |
 | --- | --- | --- |
-| `search_after_ctx` | string | Cursor index, starts from the first page when not set |
-| `limit` | number | Number of items per page, maximum value not exceeding 100, default is 20 |
+| `search_after_ctx` | string | Cursor from the previous response. Omit it for the first page. |
+| `limit` | integer | Items per page, bounds as documented on the operation page. |
 
-### Response parameters
+### Response fields
 
-| Parameter | Type | Description |
+| Field | Type | Description |
 | --- | --- | --- |
-| `total` | number | Total number of matched entries under current conditions |
-| `has_next_page` | boolean | Whether there is next page data under current conditions |
-| `search_after_ctx` | string | Next page cursor address, returned only when next page exists |
+| `has_next_page` | boolean | Whether another page exists |
+| `search_after_ctx` | string | Cursor for the next page. In cursor mode it is returned only when `has_next_page` is `true`. |
 
 ### Example
 
@@ -109,23 +89,45 @@ We provide cursor pagination support in the following APIs:
 {
   "total": 1000,
   "has_next_page": true,
-  "search_after_ctx": "658ba7f9566077d6090e8d51"
+  "search_after_ctx": "658ba7f9566077d6090e8d51",
+  "items": []
 }
 ```
   </Tab>
 </Tabs>
 
+### Operations that accept `search_after_ctx`
+
+- [List incidents](/en/api-reference/on-call/incidents/incident-list)
+- [List alerts](/en/api-reference/on-call/alerts/alert-read-list)
+- [List events for an alert](/en/api-reference/on-call/alerts/alert-read-event-list)
+- [List raw alert events](/en/api-reference/on-call/alerts/alert-event-read-list)
+- [List post-mortems](/en/api-reference/on-call/incidents/incident-post-mortem-list)
+- [List post-mortem templates](/en/api-reference/on-call/incidents/postmortem-read-list-templates)
+- [Get ServiceDeskPlus linked incidents](/en/api-reference/on-call/incidents/incident-service-desk-plus-request-read-list)
+- [List mapping data](/en/api-reference/on-call/alert-enrichment/mapping-data-read-list)
+- [List webhook delivery history](/en/api-reference/on-call/integrations/webhook-history-list)
+- [List session replay segments](/en/api-reference/rum/session-replay/rum-session-replay-read-segments)
+- [Search audit logs](/en/api-reference/platform/audit-logs/audit-read-search)
+- [Get session detail](/en/api-reference/ai-sre/sessions/session-read-info) (pages through session events)
+
+A few operations use other styles, documented on their pages: [List work items](/en/api-reference/on-call/incidents/incident-work-item-list) takes a `cursor`, and some AI SRE and monitors lists take an `offset`.
+
 ---
 
-## About TOTAL
+## About total
+
+`total` is not always exact. To keep large queries fast, operations over incidents, alerts, alert events, post-mortems, and mapping data stop counting at 1,000:
 
-Regardless of which pagination technology is used, Flashduty will return `total` and `has_next_page` parameters. However, please note that the `total` value is not always accurate. To ensure the system can respond quickly, we have added the following restrictions:
+<Warning>
+- When fewer than 1,000 items match, `total` is exact.
+- When 1,000 or more match, `total` is 1,000, meaning "1,000 or more".
+</Warning>
 
 <Warning>
-- When the total matching data is less than 1000, the `total` value is exact
-- When the total matching data is greater than or equal to 1000, the `total` value is always 1000, which only indicates that the system matched 1000+ data
+On [List incidents](/en/api-reference/on-call/incidents/incident-list) and [List alerts](/en/api-reference/on-call/alerts/alert-read-list) in page-number mode, `has_next_page` is derived from the capped `total`: once you have paged through 1,000 items it is `false` even if more items match. To read past 1,000 items, use cursor mode, where `has_next_page` is always accurate.
 </Warning>
 
 <Tip>
-Please use `has_next_page` to determine whether there is next page data, rather than `total`.
+Use `has_next_page`, not `total`, to decide whether to fetch another page, and use a cursor for anything that may exceed 1,000 items.
 </Tip>
diff --git a/en/openapi/rate-limits.mdx b/en/openapi/rate-limits.mdx
index ab3be488a..e33c80310 100644
--- a/en/openapi/rate-limits.mdx
+++ b/en/openapi/rate-limits.mdx
@@ -1,101 +1,69 @@
 ---
-title: "Rate limits"
-description: "Flashduty Open API rate limits and error codes"
+title: "Rate limits and errors"
+description: "Flashduty Open API rate limits, permission checks, error codes, and retry advice"
 ---
 
-## Request limits
+## Rate limits
 
-### Rate limits
+Every operation is rate limited. Limits are counted per account (all APP Keys and console sessions of the account share one budget), in a per-second and a per-minute window; each operation also has a platform-wide limit shared by all accounts. The exact numbers for an operation are on its page under **Restrictions**.
 
-To ensure service stability, APIs have rate limits on request frequency. When requests are too frequent, a `429` status code with `RequestTooFrequently` error will be returned.
+Default limits per account:
 
-<Warning>
-Please control your request frequency reasonably and avoid sending a large number of requests in a short period. It is recommended to implement a retry mechanism with exponential backoff when receiving a 429 error.
-</Warning>
+| Operation type | Per second | Per minute |
+| --- | :---: | :---: |
+| Read (list, get, query) | 50 | 1,000 |
+| Write (create, update, delete, enable, …) | 20 | 300 |
 
-### Permission limits
+Some operations have tighter limits, for example exports and heavy analytics queries; their **Restrictions** table shows the actual values.
 
-- An APP Key with **All permissions** has no additional API-scope restriction, but remains limited by the creator's current role permissions
-- **Custom permissions** requires at least one selected API permission; the APP Key can call only APIs in that selected scope
-- When an operation exceeds either the APP Key scope or the creator's role permissions, a `403` status code with `AccessDenied` error is returned
-- It is recommended to create separate APP Keys for different purposes, following the principle of least privilege
+### When you hit a limit
+
+The request fails with HTTP `429` and error code `RequestTooFrequently`. The response carries the header `Flashcat-Request-Rate-Limit-Delay`, the number of seconds until the current window resets. Wait at least that long before retrying; if the header is absent, back off exponentially (1 s, 2 s, 4 s, …).
+
+<Warning>
+Retrying immediately in a loop keeps the window saturated. Spread bulk jobs over time, and prefer list operations that accept multiple IDs over one call per object.
+</Warning>
 
 ---
 
-## Error code list
-
-| Error Code | HTTP Status | Description |
-| --- | :---: | --- |
-| `InvalidParameter` | 400 | Parameter error, please check if request parameters are correct |
-| `InvalidContentType` | 400 | Content-Type not supported, please use `application/json` |
-| `MethodNotAllowed` | 400 | HTTP Method not supported |
-| `Unauthorized` | 401 | Authentication failed, please check if the APP Key is correct |
-| `AccessDenied` | 403 | Permission denied, current user does not have permission for this operation |
-| `RouteNotFound` | 404 | Request Method + Path not matched, please check the API address |
-| `RequestTooFrequently` | 429 | Request too frequent, please try again later |
-| `ResourceNotFound` | 400 | Account has not purchased resources, please go to the billing center to place an order |
-| `NoLicense` | 400 | Account does not have sufficient subscription License, please go to the billing center to upgrade or purchase a subscription |
-| `InternalError` | 500 | Internal or unknown error, please contact technical support |
+## Permission checks
+
+- An APP Key with **All permissions** has no additional API-scope restriction, but remains limited by the creator's current role permissions.
+- An APP Key with **Custom permissions** can call only the APIs in its selected scope.
+- A call outside either the key's scope or the creator's role permissions fails with HTTP `403` and `AccessDenied`. The required permission of each operation is listed under **Restrictions** on its page.
+- Some operations additionally check object-level access (for example, only members of a channel's team can change it); those rules are described in each operation's **Usage** section.
+- Create separate APP Keys for different purposes, each with the smallest scope it needs.
 
 ---
 
-## Error handling recommendations
-
-<AccordionGroup>
-  <Accordion title="400 Parameter Error">
-    **Possible causes**:
-    - Missing required parameters
-    - Incorrect parameter format
-    - Content-Type not set to `application/json`
-    
-    **Solution**:
-    Check request parameters and Headers settings, refer to API documentation for parameter requirements.
-  </Accordion>
-
-  <Accordion title="401 Authentication Failed">
-    **Possible causes**:
-    - APP Key not provided
-    - APP Key is incorrect or has expired
-    
-    **Solution**:
-    1. Confirm that the request URL contains the `app_key` parameter
-    2. Go to the console to check if the APP Key is valid
-  </Accordion>
-
-  <Accordion title="403 Permission Denied">
-    **Possible causes**:
-    - Current user does not have permission to perform this operation
-    - The user corresponding to the APP Key has insufficient permissions
-    
-    **Solution**:
-    Contact the account administrator to elevate permissions, or use an APP Key with the appropriate permissions.
-  </Accordion>
-
-  <Accordion title="429 Too Many Requests">
-    **Possible causes**:
-    - Too many requests sent in a short period
-    
-    **Solution**:
-    1. Reduce request frequency
-    2. Implement exponential backoff retry mechanism
-    3. Combine multiple requests (for example, use batch APIs)
-  </Accordion>
-
-  <Accordion title="500 Internal Error">
-    **Possible causes**:
-    - Server-side internal exception
-    
-    **Solution**:
-    1. Retry later
-    2. If the issue persists, contact technical support and provide the `request_id`
-  </Accordion>
-</AccordionGroup>
+## Error codes
+
+Every failure returns the envelope `{ "request_id": "…", "error": { "code": "…", "message": "…" } }`. Branch on `error.code`; it is stable. `message` is localized and may change.
+
+| Error code | HTTP status | Meaning | What to do |
+| --- | :---: | --- | --- |
+| `InvalidParameter` | 400 | A parameter is missing, has the wrong type, or failed validation. `message` usually names the field. | Fix the request; do not retry unchanged. |
+| `BadRequest` | 400 | The request breaks a business rule or conflicts with the current state of an object; `message` says which. | Read `message`, then fix the request or the object state. |
+| `InvalidContentType` | 400 | The body is not sent as `application/json`. | Set `Content-Type: application/json`. |
+| `ResourceNotFound` | 400 | The referenced object does not exist in this account or was deleted. Returned as 400, not 404. | Check the ID. |
+| `ReferenceExist` | 400 | The object is still referenced by other objects, so it cannot be deleted. | Remove the references first. |
+| `NoLicense` | 400 | The account's plan does not include the feature, a plan quota is used up, the plan has expired, or credits are insufficient. | Upgrade the plan, buy licenses, or add credits in the billing center. |
+| `Unauthorized` | 401 | The APP Key is missing, invalid, or deleted. | Check the `app_key` parameter or `Fd-App-Key` header. |
+| `AccessDenied` | 403 | The key's scope or the creator's role does not allow this operation or object. | Grant the permission or use another key. |
+| `RouteNotFound` | 404 | No operation matches the method and path. | Check the path and HTTP method on the operation page. |
+| `MethodNotAllowed` | 405 | The path exists but not for this HTTP method. | Use the method shown on the operation page. |
+| `EntityTooLarge` | 413 | The request body exceeds the size limit. | Send less data per request. |
+| `RequestTooFrequently` | 429 | A rate limit was hit. | Wait for `Flashcat-Request-Rate-Limit-Delay` seconds, then retry. |
+| `InternalError` | 500 | Unexpected server error. | Retry with backoff; if it persists, contact support with the `request_id`. |
+| `ServiceUnavailable` | 503 | A backend dependency is overloaded or unavailable. | Retry with backoff. |
+
+Other values of the `ErrorCode` enum in the API reference (`RequestVerifyRequired`, `DangerousOperation`, `RequestLocked`, `BalanceNotEnough`, `UndonedOrderExist`) belong to console-only flows such as MFA and billing and are not returned by Open API operations.
 
 ---
 
-## Best practices
+## Retry advice
 
-- **Implement Retry Mechanism**: For network errors and 5xx errors, it is recommended to implement exponential backoff retry with an initial interval of 1 second and a maximum of 3 retries.
-- **Record request_id**: Save the `request_id` returned from each request to facilitate troubleshooting and technical support.
-- **Protect APP Key**: Do not hardcode APP Key in client code. It is recommended to manage it through environment variables or configuration centers.
-- **Rotate Keys Regularly**: Regularly replace APP Keys and promptly delete keys that are no longer in use to reduce the risk of leakage.
+- **Retry** only `429`, `500`, `503`, and network errors, with exponential backoff (start at 1 second, at most 3 retries). For `429`, honor `Flashcat-Request-Rate-Limit-Delay`.
+- **Do not retry** other `4xx` errors unchanged; they will fail the same way.
+- **Treat creates as not idempotent.** Before retrying a create that timed out, list or query to check whether the first attempt succeeded.
+- **Log the `request_id`** of every failed call; support needs it to locate the request.
diff --git a/scripts/lint_openapi.py b/scripts/lint_openapi.py
index d45c25b81..9888e5226 100644
--- a/scripts/lint_openapi.py
+++ b/scripts/lint_openapi.py
@@ -15,6 +15,17 @@
                        learn what each value means
   missing-example      every operation needs a request example (when it has a
                        request body) and a 200 response example
+  int-enum-undocumented  every value of an integer enum must be mentioned in the
+                       property description
+  required-undeclared  a schema's `required` may only name its own properties
+                       (schemas composed with allOf are exempt)
+  missing-403          every operation documents the 403 response (APP Key
+                       scopes can deny any operation)
+  example-mismatch     request and 200 response examples must match their schema:
+                       types, enum members, no undeclared keys, and required keys
+                       present in responses
+  description-too-long the operation description is the one-line subtitle;
+                       longer prose belongs in x-mint.content
 
 Usage:
   python3 scripts/lint_openapi.py            # lint all spec files, exit 1 on violations
@@ -44,6 +55,9 @@
     {"success", "failed"},
 ]
 
+# the operation `description` renders as the page subtitle
+MAX_OP_DESCRIPTION = 220
+
 # field-name exemptions: order-by enums list sortable field names, whose
 # meaning lives on the referenced fields themselves
 ENUM_EXEMPT_NAMES = re.compile(r"^(orderby|order_by)$")
@@ -87,6 +101,11 @@ def walk_properties(node, where, file, rep, seen):
         if isinstance(member, dict) and "$ref" not in member:
             walk_properties(member, where, file, rep, seen)
 
+    if "allOf" not in node:
+        undeclared = [r for r in node.get("required", []) if r not in node.get("properties", {})]
+        if undeclared:
+            rep.add(file, "required-undeclared", where, f"required names undeclared properties: {undeclared}")
+
     for name, prop in node.get("properties", {}).items():
         if not isinstance(prop, dict):
             continue
@@ -111,6 +130,11 @@ def walk_properties(node, where, file, rep, seen):
             if missing:
                 rep.add(file, "enum-undocumented", pwhere,
                         f"enum values not explained in description: {missing}")
+        if enum and prop.get("type") == "integer":
+            missing = [v for v in enum if str(v) not in desc]
+            if missing:
+                rep.add(file, "int-enum-undocumented", pwhere,
+                        f"integer enum values not explained in description: {missing}")
         # recurse
         if prop.get("type") == "object" or "properties" in prop:
             walk_properties(prop, pwhere, file, rep, seen)
@@ -119,6 +143,72 @@ def walk_properties(node, where, file, rep, seen):
             walk_properties(items, pwhere + "[]", file, rep, seen)
 
 
+def resolve(spec, node, depth=0):
+    while isinstance(node, dict) and "$ref" in node and depth < 20:
+        node = spec["components"]["schemas"].get(node["$ref"].split("/")[-1], {})
+        depth += 1
+    return node
+
+
+def flatten(spec, schema):
+    """Merge allOf members into one object schema (properties + required)."""
+    s = resolve(spec, schema)
+    if not isinstance(s, dict) or "allOf" not in s:
+        return s
+    merged = {"type": "object", "properties": {}, "required": []}
+    for m in s["allOf"] + [{k: v for k, v in s.items() if k != "allOf"}]:
+        m = flatten(spec, m)
+        merged["properties"].update(m.get("properties", {}))
+        merged["required"] += m.get("required", [])
+        if m.get("additionalProperties"):
+            merged["additionalProperties"] = m["additionalProperties"]
+    return merged
+
+
+def check_example(spec, schema, ex, file, where, rep, path="$", response=False, depth=0):
+    s = flatten(spec, schema)
+    if depth > 20 or not isinstance(s, dict) or "oneOf" in s or "anyOf" in s:
+        return
+    types = s.get("type")
+    types = types if isinstance(types, list) else [types] if types else []
+    if ex is None:
+        if types and "null" not in types:
+            rep.add(file, "example-mismatch", where, f"{path} is null but the schema is not nullable")
+        return
+    if "enum" in s and ex not in s["enum"]:
+        rep.add(file, "example-mismatch", where, f"{path}={ex!r} is not an enum member")
+    kind = next((t for t in types if t != "null"), "object" if "properties" in s else None)
+    if kind == "object":
+        if not isinstance(ex, dict):
+            rep.add(file, "example-mismatch", where, f"{path} should be an object")
+            return
+        props, extra = s.get("properties", {}), s.get("additionalProperties")
+        for k, v in ex.items():
+            if k in props:
+                check_example(spec, props[k], v, file, where, rep, f"{path}.{k}", response, depth + 1)
+            elif isinstance(extra, dict):
+                check_example(spec, extra, v, file, where, rep, f"{path}.{k}", response, depth + 1)
+            elif props and not extra:
+                rep.add(file, "example-mismatch", where, f"{path}.{k} is not declared in the schema")
+        if response:
+            for r in s.get("required", []):
+                if r not in ex:
+                    rep.add(file, "example-mismatch", where, f"{path}.{r} is required but missing")
+    elif kind == "array":
+        if not isinstance(ex, list):
+            rep.add(file, "example-mismatch", where, f"{path} should be an array")
+            return
+        for i, v in enumerate(ex):
+            check_example(spec, s.get("items", {}), v, file, where, rep, f"{path}[{i}]", response, depth + 1)
+    elif kind in ("integer", "number", "string", "boolean"):
+        ok = {"integer": lambda v: isinstance(v, int) and not isinstance(v, bool),
+              "number": lambda v: isinstance(v, (int, float)) and not isinstance(v, bool),
+              "string": lambda v: isinstance(v, str),
+              "boolean": lambda v: isinstance(v, bool)}[kind](ex)
+        if not ok:
+            rep.add(file, "example-mismatch", where, f"{path}={ex!r} is not a {kind}")
+
+
 def lint_operations(spec, file, rep):
     for path, pi in spec.get("paths", {}).items():
         if not isinstance(pi, dict):
@@ -130,6 +220,13 @@ def lint_operations(spec, file, rep):
             body = op.get("requestBody", {}).get("content", {}).get("application/json", {})
             if body and "example" not in body and "examples" not in body:
                 rep.add(file, "missing-example", where, "request body has no example")
+            if body.get("schema") and "example" in body:
+                check_example(spec, body["schema"], body["example"], file, where + " request", rep)
+            if "403" not in op.get("responses", {}):
+                rep.add(file, "missing-403", where, "no 403 response")
+            if len(op.get("description", "")) > MAX_OP_DESCRIPTION:
+                rep.add(file, "description-too-long", where,
+                        f"{len(op['description'])} chars; move detail into x-mint.content")
             ok = op.get("responses", {}).get("200", {})
             if "$ref" not in ok:
                 content = ok.get("content", {}).get("application/json", {})
@@ -137,6 +234,9 @@ def lint_operations(spec, file, rep):
                 # downloads and empty 200s are exempt
                 if content and "example" not in content and "examples" not in content:
                     rep.add(file, "missing-example", where, "200 response has no example")
+                if content.get("schema") and "example" in content:
+                    check_example(spec, content["schema"], content["example"], file,
+                                  where + " response", rep, response=True)
 
 
 def lint_file(path, rep):
diff --git a/zh/developer/go-sdk.mdx b/zh/developer/go-sdk.mdx
index 660a0539b..9fdeb3c32 100644
--- a/zh/developer/go-sdk.mdx
+++ b/zh/developer/go-sdk.mdx
@@ -325,7 +325,7 @@ for page := 0; page < 100; page++ {
 
 Flashduty API 返回的未成功调用——无论是信封中携带了错误，还是 HTTP 状态非 2xx——都会返回 `*ErrorResponse`。它带有 `Code`、`Message`、可选的 `Reason` 与 `RequestID` 字段，排障时把 `RequestID` 提供给支持团队即可定位。`Reason` 携带服务端给出的可选原因（信封内的 `DutyError` 同样带有该字段，JSON 字段为 `reason`,omitempty）；非空时它也会被追加到错误字符串末尾，形如 `, reason X`。
 
-当 API 返回 429 时，错误被提升为 `*RateLimitError`：它内嵌 `*ErrorResponse`（所以 `errors.As` 取 `*ErrorResponse` 仍然成立），并额外带上 `RetryAfter` 提示。`Code` 与 Open API 的[错误码列表](/zh/openapi/introduction#错误码列表)一一对应。
+当 API 返回 429 时，错误被提升为 `*RateLimitError`：它内嵌 `*ErrorResponse`（所以 `errors.As` 取 `*ErrorResponse` 仍然成立），并额外带上 `RetryAfter` 提示。`Code` 与 Open API 的[错误码列表](/zh/openapi/rate-limits#错误码)一一对应。
 
 <Note>
 对于**生成接口**，如果您收到的是带非 JSON 响应体的非 2xx 响应，SDK 会返回普通 `error`，而不是 `*ErrorResponse`。这表示响应来自网关、负载均衡器或代理等中间层，通常是请求超过了中间层超时。您可以重试请求，或将耗时较长的批量请求拆分为更小的批次；不要假定 `errors.As(err, &apiErr)` 能匹配此类错误。
diff --git a/zh/openapi/api-catalog.mdx b/zh/openapi/api-catalog.mdx
index d1f9ea293..0bbd81e9b 100644
--- a/zh/openapi/api-catalog.mdx
+++ b/zh/openapi/api-catalog.mdx
@@ -3,7 +3,7 @@ title: "API 目录"
 description: "Flashduty Open API 接口完整列表，按产品模块组织并链接到详细文档"
 ---
 
-Flashduty Open API 提供 **365** 个接口，覆盖 On-call、Monitors、RUM、AI SRE 和平台五个主要模块。所有接口使用统一认证方式和请求规范。详情参见[快速开始](/zh/openapi/introduction)。
+Flashduty Open API 提供 **370** 个接口，覆盖 On-call、Monitors、RUM、AI SRE 和平台五个主要模块。所有接口使用统一认证方式和请求规范。详情参见[快速开始](/zh/openapi/introduction)。
 
 <Note>
 所有接口 URL 均以 `https://api.flashcat.cloud` 为 base，通过 query string 中的 APP Key 认证。
@@ -282,7 +282,7 @@ Flashduty Open API 提供 **365** 个接口，覆盖 On-call、Monitors、RUM、
 
 </Accordion>
 
-<Accordion title="Monitors（41 个接口）">
+<Accordion title="Monitors（46 个接口）">
 
 ### 告警规则
 
@@ -357,7 +357,12 @@ Flashduty Open API 提供 **365** 个接口，覆盖 On-call、Monitors、RUM、
 
 | 方法 | 接口 | 描述 |
 | :--- | :--- | :--- |
-| POST | [`/monit/folder/list`](/zh/api-reference/monitors/rule-folders/monit-folder-read-list) | 查询监控节点列表 |
+| POST | [`/monit/folder/list`](/zh/api-reference/monitors/rule-folders/monit-folder-read-list) | 查询监控目录列表 |
+| POST | [`/monit/folder/health`](/zh/api-reference/monitors/rule-folders/monit-folder-read-health) | 获取监控目录健康摘要 |
+| POST | [`/monit/folder/create`](/zh/api-reference/monitors/rule-folders/monit-folder-write-create) | 创建监控目录 |
+| POST | [`/monit/folder/update`](/zh/api-reference/monitors/rule-folders/monit-folder-write-update) | 更新监控目录 |
+| POST | [`/monit/folder/move`](/zh/api-reference/monitors/rule-folders/monit-folder-write-move) | 移动监控目录 |
+| POST | [`/monit/folder/delete`](/zh/api-reference/monitors/rule-folders/monit-folder-write-delete) | 删除监控目录 |
 
 </Accordion>
 
diff --git a/zh/openapi/introduction.mdx b/zh/openapi/introduction.mdx
index 9998035fe..512d0683a 100644
--- a/zh/openapi/introduction.mdx
+++ b/zh/openapi/introduction.mdx
@@ -22,23 +22,29 @@ Open API 用于通过 HTTP 接口主动调用 Flashduty，查询和管理故障
 
 ### 请求地址
 
-所有 API 只接受 **HTTPS** 协议进行访问，且只有一个 Endpoint：
+所有 API 只接受 **HTTPS** 访问，且只有一个 Endpoint：
 
 ```
 https://api.flashcat.cloud
 ```
 
-### Headers
+### 请求方法与 Headers
 
-大部分请求使用 POST 方法，并使用 JSON Payload 传参。请确保设置正确的 Content-Type：
+绝大多数接口使用 `POST` 方法、JSON 请求体，请设置：
 
 ```
 Content-Type: application/json
 ```
 
+少数读接口使用 `GET` 方法和 query 参数（例如状态页的查询接口、Prometheus 兼容的标签查询），以各接口页面标注的方法为准。不需要参数的 `POST` 接口请传 `{}`。
+
 ### 字符编码
 
-所有 API 均使用 **UTF-8** 编码。
+请求与响应均使用 **UTF-8** 编码。
+
+### 响应语言
+
+错误信息会按语言返回。语言依次取自 query 参数 `locale`、query 参数 `lang`、请求头 `Accept-Language`，例如 `Accept-Language: zh-CN` 或 `en-US`。字段名、枚举值和错误码不会被翻译。
 
 ---
 
@@ -61,21 +67,32 @@ Content-Type: application/json
 </Steps>
 
 <Warning>
-APP Key 的实际可访问范围同时受其权限范围和创建者当前角色权限限制。创建成功后请立即妥善保存完整密钥；离开创建页面后无法再次查看。
+APP Key 的实际可访问范围同时受其权限范围和创建者当前角色权限限制。创建成功后请立即妥善保存完整密钥；离开创建页面后无法再次查看。不要把 APP Key 硬编码在客户端代码里，请通过环境变量或密钥管理服务注入，并及时删除不再使用的密钥。
 </Warning>
 
 您可以在 APP Key 列表中编辑已有密钥的名称和权限范围。
 
-### 使用示例
+### 传递 APP Key
 
-将 APP Key 作为 query string 参数传入：
+通过 query 参数 `app_key` 传入：
 
 ```bash
-curl -X POST 'https://api.flashcat.cloud/your/api/path?app_key=YOUR_APP_KEY' \
+curl -X POST 'https://api.flashcat.cloud/incident/list?app_key=YOUR_APP_KEY' \
   -H 'Content-Type: application/json' \
-  -d '{"param": "value"}'
+  -d '{"start_time": 1712000000, "end_time": 1712086400, "limit": 20}'
 ```
 
+也可以放在请求头 `Fd-App-Key` 中，避免密钥出现在 URL 和访问日志里：
+
+```bash
+curl -X POST 'https://api.flashcat.cloud/incident/list' \
+  -H 'Fd-App-Key: YOUR_APP_KEY' \
+  -H 'Content-Type: application/json' \
+  -d '{"start_time": 1712000000, "end_time": 1712086400, "limit": 20}'
+```
+
+两者同时存在时以 query 参数为准。缺少或无效的 APP Key 返回 `401 Unauthorized`。
+
 <Note>
 使用 Go？推荐用官方 [Go SDK](/zh/developer/go-sdk) 调用 Flashduty，直接获得类型化的请求参数、响应结构和错误码，无需手写 HTTP 请求。
 </Note>
@@ -84,13 +101,15 @@ curl -X POST 'https://api.flashcat.cloud/your/api/path?app_key=YOUR_APP_KEY' \
 
 ## 响应结构
 
-所有请求响应均为 JSON 格式，遵循统一结构：
+所有响应均为 JSON，遵循统一结构：
 
-| 字段 | 类型 | 必选 | 描述 |
+| 字段 | 类型 | 必定返回 | 描述 |
 | --- | --- | :---: | --- |
-| `request_id` | string | ✅ | 请求 ID，用于链路追踪 |
-| `error` | object | | 错误描述，仅当出现错误时返回 |
-| `data` | any | | 数据内容，具体格式参考各 API 定义 |
+| `request_id` | string | ✅ | 请求 ID，同时通过响应头 `Flashcat-Request-Id` 返回。联系技术支持时请提供。 |
+| `data` | any | | 接口返回的数据，格式见各接口页面。没有返回数据的接口会返回 `{}` 或完全不带 `data`，请不要依赖该字段一定存在。出错时不返回。 |
+| `error` | object | | 仅在请求失败时返回。 |
+
+成功时 HTTP 状态码为 `200`。失败时返回[错误码列表](/zh/openapi/rate-limits#错误码)中对应的 HTTP 状态码，但请以 `error.code` 而不是状态码做判断。
 
 ### 响应示例
 
@@ -98,10 +117,10 @@ curl -X POST 'https://api.flashcat.cloud/your/api/path?app_key=YOUR_APP_KEY' \
   <Tab title="成功响应">
 ```json
 {
-  "request_id": "abc123456",
+  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
   "data": {
-    "id": "user_001",
-    "name": "example"
+    "team_id": 1467226103121,
+    "team_name": "SRE"
   }
 }
 ```
@@ -109,10 +128,10 @@ curl -X POST 'https://api.flashcat.cloud/your/api/path?app_key=YOUR_APP_KEY' \
   <Tab title="错误响应">
 ```json
 {
-  "request_id": "abc123456",
+  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
   "error": {
     "code": "InvalidParameter",
-    "message": "参数 name 不能为空"
+    "message": "The specified parameter team_name is not valid."
   }
 }
 ```
@@ -121,104 +140,23 @@ curl -X POST 'https://api.flashcat.cloud/your/api/path?app_key=YOUR_APP_KEY' \
 
 ### Error 对象结构
 
-| 字段 | 类型 | 必选 | 描述 |
+| 字段 | 类型 | 必定返回 | 描述 |
 | --- | --- | :---: | --- |
-| `code` | string | ✅ | 错误码，详见下方[错误码列表](#错误码列表) |
-| `message` | string | | 错误描述 |
+| `code` | string | ✅ | 稳定的错误码，见[错误码列表](/zh/openapi/rate-limits#错误码) |
+| `message` | string | ✅ | 按响应语言返回的错误描述，可能包含出错的字段名。请不要解析它。 |
 
 ---
 
-## 使用限制
-
-### 频率限制
-
-为保证服务稳定性，API 对请求频率有一定限制。当请求过于频繁时，将返回 `429` 状态码和 `RequestTooFrequently` 错误。
-
-<Warning>
-请合理控制请求频率，避免在短时间内发送大量请求。建议实现重试机制，在收到 429 错误时进行指数退避重试。
-</Warning>
-
-### 权限限制
-
-- 选择 **全部权限** 的 APP Key 不额外限制接口范围，但仍受创建者当前角色权限约束
-- 选择 **自定义权限** 时，必须至少选择一个 API 权限点，APP Key 只能调用选中的接口范围
-- 操作超出 APP Key 权限范围或创建者角色权限时，将返回 `403` 状态码和 `AccessDenied` 错误
-- 建议为不同用途创建独立的 APP Key，遵循最小权限原则
-
-### 错误码列表
-
-| 错误码 | HTTP Status | 描述 |
-| --- | :---: | --- |
-| `InvalidParameter` | 400 | 参数错误，请检查请求参数是否正确 |
-| `InvalidContentType` | 400 | Content-Type 不支持，请使用 `application/json` |
-| `MethodNotAllowed` | 400 | HTTP Method 不支持 |
-| `Unauthorized` | 401 | 登录认证未通过，请检查 APP Key 是否正确 |
-| `AccessDenied` | 403 | 权限认证未通过，当前用户无此操作权限 |
-| `RouteNotFound` | 404 | 请求 Method + Path 未匹配，请检查 API 地址 |
-| `RequestTooFrequently` | 429 | 请求过于频繁，请稍后重试 |
-| `ResourceNotFound` | 400 | 账户未购买资源，请前往费用中心下单 |
-| `NoLicense` | 400 | 账户无充足订阅 License，请前往费用中心升级或购买订阅 |
-| `InternalError` | 500 | 内部或未知错误，请联系技术支持 |
-
----
+## 数据约定
 
-## 错误处理建议
-
-<AccordionGroup>
-  <Accordion title="400 参数错误">
-    **可能原因**：
-    - 缺少必填参数
-    - 参数格式不正确
-    - Content-Type 未设置为 `application/json`
-    
-    **解决方案**：
-    检查请求参数和 Headers 设置，参考 API 文档确认参数要求。
-  </Accordion>
-
-  <Accordion title="401 认证失败">
-    **可能原因**：
-    - APP Key 未提供
-    - APP Key 不正确或已失效
-    
-    **解决方案**：
-    1. 确认请求 URL 中包含 `app_key` 参数
-    2. 前往控制台检查 APP Key 是否有效
-  </Accordion>
-
-  <Accordion title="403 权限不足">
-    **可能原因**：
-    - 当前用户无权执行此操作
-    - APP Key 对应用户权限不足
-    
-    **解决方案**：
-    联系账户管理员提升权限，或使用具有相应权限的 APP Key。
-  </Accordion>
-
-  <Accordion title="429 请求过频">
-    **可能原因**：
-    - 短时间内发送了过多请求
-    
-    **解决方案**：
-    1. 降低请求频率
-    2. 实现指数退避重试机制
-    3. 合并多个请求（如使用批量接口）
-  </Accordion>
-
-  <Accordion title="500 内部错误">
-    **可能原因**：
-    - 服务端内部异常
-    
-    **解决方案**：
-    1. 稍后重试
-    2. 如持续出现，请联系技术支持并提供 `request_id`
-  </Accordion>
-</AccordionGroup>
+- **时间戳**均为 Unix 时间戳整数。大多数以**秒**为单位；部分（AI SRE 和 RUM 的大多数时间字段、故障动态、审计日志）以**毫秒**为单位。每个时间字段的描述都会写明单位。
+- **枚举**区分大小写，可能是字符串或整数；每个字段都会列出可选值及含义。
+- **ID** 按各字段标注的类型（整数或字符串）返回，回传时请保持相同类型。
+- **列表**均分页返回，见[关于分页](/zh/openapi/pagination)。
+- **更新接口**会逐字段说明：不传某字段时是保留原值还是清空。
 
 ---
 
-## 最佳实践
+## 限制与错误
 
-- **实现重试机制**：对于网络错误和 5xx 错误，建议实现指数退避重试，初始间隔 1 秒，最大重试 3 次。
-- **记录 request_id**：保存每次请求返回的 `request_id`，便于问题排查和技术支持。
-- **保护 APP Key**：不要在客户端代码中硬编码 APP Key，建议通过环境变量或配置中心管理。
-- **定期轮换密钥**：定期更换 APP Key，及时删除不再使用的密钥，降低泄露风险。
+频率限制、权限校验、完整错误码列表和重试建议见[使用限制与错误码](/zh/openapi/rate-limits)。每个接口页面的 **限制说明** 部分也列出了该接口自己的频率限制和所需权限。
diff --git a/zh/openapi/pagination.mdx b/zh/openapi/pagination.mdx
index 48eb839fb..80c3e3240 100644
--- a/zh/openapi/pagination.mdx
+++ b/zh/openapi/pagination.mdx
@@ -4,25 +4,23 @@ description: "Flashduty Open API 分页机制说明"
 keywords: ["API分页", "游标分页", "传统分页", "OFFSET", "LIMIT", "SEARCH_AFTER_CTX"]
 ---
 
-一般情况下，当我们拉取或检索某种数据对象时，都会基于分页将数据分批次返回，而不是在一个请求中返回所有数据。
+列表接口分页返回结果。大多数接口使用页码分页；数据量大或变化快的集合还支持游标分页。每个接口支持哪些分页参数、上限和默认值是多少，以该接口页面为准——下文给出的是常见默认值，并非对所有接口都成立。
 
-## 传统分页
-
-我们把基于 OFFSET 和 LIMIT 查询的分页技术定义为传统分页。在大多数 Flashduty 列表查询 API 中，您可以看到以下参数定义：
+## 页码分页
 
 ### 请求参数
 
 | 参数 | 类型 | 描述 |
 | --- | --- | --- |
-| `p` | number | 分页页码，默认从 1 开始。offset = (p - 1) * limit |
-| `limit` | number | 页内数目，最大值不超过 100，默认为 20 |
+| `p` | integer | 页码，从 1 开始。不传或传 `0` 视为 1。offset = (p - 1) × limit |
+| `limit` | integer | 每页条数。通常最大 100、默认 20；部分接口的范围不同，见接口页面。 |
 
-### 响应参数
+### 响应字段
 
-| 参数 | 类型 | 描述 |
+| 字段 | 类型 | 描述 |
 | --- | --- | --- |
-| `total` | number | 当前条件下匹配到总条目数量 |
-| `has_next_page` | boolean | 当前条件下是否有下一页数据 |
+| `total` | integer | 匹配条数（见[关于 total](#关于-total)） |
+| `has_next_page` | boolean | 是否还有下一页 |
 
 ### 示例
 
@@ -39,60 +37,42 @@ keywords: ["API分页", "游标分页", "传统分页", "OFFSET", "LIMIT", "SEAR
 ```json
 {
   "total": 1000,
-  "has_next_page": true
+  "has_next_page": true,
+  "items": []
 }
 ```
   </Tab>
 </Tabs>
 
-### 潜在问题
-
-基于传统分页技术进行查询虽然简单，但可能会遇到以下一些问题：
-
-<AccordionGroup>
-  <Accordion title="性能问题">
-    使用 OFFSET 和 LIMIT 进行分页查询时，数据库需要跳过指定数量的行（OFFSET），然后返回指定数量的行（LIMIT）。随着偏移量的增加，查询的性能可能会下降，特别是在处理大量数据时。每次查询都需要扫描和跳过前面的行，这会导致查询变得越来越慢。
-  </Accordion>
-  <Accordion title="数据不稳定性">
-    当使用 PAGE 和 LIMIT 进行分页查询时，如果在查询期间删除或插入了数据，可能会导致结果不稳定。例如，如果在查询过程中删除了前面的行，那么后续的偏移量可能会失效，导致结果不准确或缺失。
-  </Accordion>
-</AccordionGroup>
-
-### 查询限制
-
-为了保护系统，确保大多数用户可以稳定访问，我们针对基于传统分页技术查询的 API 参数做了以下限制：
+### 深度限制
 
 <Warning>
-要求 PAGE × LIMIT ≤ 10000，如果超过 10000，系统将直接返回 400 错误信息。这种情况下，请您转为使用游标分页，或缩小查询条件。
+On-call 的列表接口要求 `p × limit` 不超过 10,000，更深的页返回 `400 InvalidParameter`。如需继续往后取，请在接口支持时改用游标分页，或收窄筛选条件（例如缩短时间范围）。
 </Warning>
 
+两次调用之间如有数据新增或删除，偏移量会随之移动，页码分页可能漏掉或重复部分数据。需要完整、稳定地导出时请使用游标分页。
+
 ---
 
 ## 游标分页
 
-我们把基于 SEARCH_AFTER_CTX 分页的技术定义为游标分页。游标分页技术可以更好地处理大数据集和高性能要求，并提供更稳定和高效的分页查询体验。
-
-### 支持的 API
+把上一次响应中的 `search_after_ctx` 传回即可获取下一页。游标是不透明的：不要自行构造或修改，翻页过程中其他请求参数保持不变。传了 `search_after_ctx` 时 `p` 会被忽略。
 
-我们在以下 API 中提供了游标分页支持：
-
-- [故障列表](/zh/api-reference/on-call/incidents/incident-list)
-- [告警列表](/zh/api-reference/on-call/alerts/alert-read-list)
+在查询故障列表和查询告警列表上，可以先用页码分页、随时切换为游标分页：每个非空页都会同时返回 `search_after_ctx`，即该页最后一条之后的游标。
 
 ### 请求参数
 
 | 参数 | 类型 | 描述 |
 | --- | --- | --- |
-| `search_after_ctx` | string | 游标索引，不设置时从第一页开始 |
-| `limit` | number | 页内数目，最大值不超过 100，默认为 20 |
+| `search_after_ctx` | string | 上一次响应返回的游标，首页不传。 |
+| `limit` | integer | 每页条数，范围见接口页面。 |
 
-### 响应参数
+### 响应字段
 
-| 参数 | 类型 | 描述 |
+| 字段 | 类型 | 描述 |
 | --- | --- | --- |
-| `total` | number | 当前条件下匹配到总条目数量 |
-| `has_next_page` | boolean | 当前条件下是否有下一页数据 |
-| `search_after_ctx` | string | 下一页游标地址，仅当存在下页时返回 |
+| `has_next_page` | boolean | 是否还有下一页 |
+| `search_after_ctx` | string | 下一页的游标。游标模式下仅当 `has_next_page` 为 `true` 时返回。 |
 
 ### 示例
 
@@ -110,23 +90,45 @@ keywords: ["API分页", "游标分页", "传统分页", "OFFSET", "LIMIT", "SEAR
 {
   "total": 1000,
   "has_next_page": true,
-  "search_after_ctx": "658ba7f9566077d6090e8d51"
+  "search_after_ctx": "658ba7f9566077d6090e8d51",
+  "items": []
 }
 ```
   </Tab>
 </Tabs>
 
+### 支持 `search_after_ctx` 的接口
+
+- [查询故障列表](/zh/api-reference/on-call/incidents/incident-list)
+- [查询告警列表](/zh/api-reference/on-call/alerts/alert-read-list)
+- [查询告警事件列表](/zh/api-reference/on-call/alerts/alert-read-event-list)
+- [查询原始告警事件列表](/zh/api-reference/on-call/alerts/alert-event-read-list)
+- [查询复盘报告列表](/zh/api-reference/on-call/incidents/incident-post-mortem-list)
+- [查询故障复盘模板列表](/zh/api-reference/on-call/incidents/postmortem-read-list-templates)
+- [获取 ServiceDeskPlus 关联故障](/zh/api-reference/on-call/incidents/incident-service-desk-plus-request-read-list)
+- [查询映射数据列表](/zh/api-reference/on-call/alert-enrichment/mapping-data-read-list)
+- [查询 Webhook 推送历史](/zh/api-reference/on-call/integrations/webhook-history-list)
+- [查询会话回放分段](/zh/api-reference/rum/session-replay/rum-session-replay-read-segments)
+- [检索审计日志](/zh/api-reference/platform/audit-logs/audit-read-search)
+- [查看会话详情](/zh/api-reference/ai-sre/sessions/session-read-info)（分页读取会话事件）
+
+少数接口使用其他分页方式，详见其页面：[查询跟进事项列表](/zh/api-reference/on-call/incidents/incident-work-item-list)使用 `cursor`，部分 AI SRE 和监控接口使用 `offset`。
+
 ---
 
-## 关于 TOTAL
+## 关于 total
+
+`total` 不总是精确值。为保证大查询的响应速度，故障、告警、告警事件、复盘报告和映射数据相关的列表最多计数到 1,000：
 
-无论使用哪种分页技术，Flashduty 都会给您返回 `total` 和 `has_next_page` 参数。但是，请注意，`total` 值并不始终准确，为了保证系统可以快速响应，我们增加了以下限制：
+<Warning>
+- 匹配数据少于 1,000 条时，`total` 是精确值。
+- 匹配数据达到或超过 1,000 条时，`total` 固定为 1,000，表示"1,000 条及以上"。
+</Warning>
 
 <Warning>
-- 当匹配数据总量小于 1000 时，`total` 值为精确值
-- 当匹配数据总量大于等于 1000 时，`total` 值恒为 1000，此时仅代表系统匹配到 1000+ 数据
+[查询故障列表](/zh/api-reference/on-call/incidents/incident-list)和[查询告警列表](/zh/api-reference/on-call/alerts/alert-read-list)在页码模式下，`has_next_page` 是根据封顶后的 `total` 计算的：翻过 1,000 条之后，即使还有匹配数据，它也会返回 `false`。需要读取 1,000 条以上时请使用游标模式，游标模式下的 `has_next_page` 始终准确。
 </Warning>
 
 <Tip>
-请您通过 `has_next_page` 来判断是否存在下一页数据，而不是 `total`。
+请用 `has_next_page` 而不是 `total` 判断是否还有下一页；可能超过 1,000 条的数据请使用游标分页。
 </Tip>
diff --git a/zh/openapi/rate-limits.mdx b/zh/openapi/rate-limits.mdx
index 78c0bbd25..5ea46ddd0 100644
--- a/zh/openapi/rate-limits.mdx
+++ b/zh/openapi/rate-limits.mdx
@@ -1,102 +1,70 @@
 ---
-title: "使用限制"
-description: "Flashduty Open API 使用限制与错误码说明"
-keywords: ["API限流", "错误码", "频率限制", "权限限制", "最佳实践"]
+title: "使用限制与错误码"
+description: "Flashduty Open API 频率限制、权限校验、错误码与重试建议"
+keywords: ["API限流", "错误码", "频率限制", "权限限制", "重试"]
 ---
 
-## 请求限制
+## 频率限制
 
-### 频率限制
+每个接口都有频率限制。限制按账户计算（同一账户下的所有 APP Key 和控制台会话共用一份额度），分每秒和每分钟两个窗口；此外每个接口还有一个所有账户共享的平台级上限。某个接口的具体数值见其页面的 **限制说明**。
 
-为保证服务稳定性，API 对请求频率有一定限制。当请求过于频繁时，将返回 `429` 状态码和 `RequestTooFrequently` 错误。
+每个账户的默认限制：
 
-<Warning>
-请合理控制请求频率，避免在短时间内发送大量请求。建议实现重试机制，在收到 429 错误时进行指数退避重试。
-</Warning>
+| 接口类型 | 每秒 | 每分钟 |
+| --- | :---: | :---: |
+| 读（列表、详情、查询） | 50 | 1,000 |
+| 写（创建、更新、删除、启用等） | 20 | 300 |
 
-### 权限限制
+部分接口的限制更严，例如导出和较重的统计分析查询，以其 **限制说明** 中的数值为准。
 
-- 选择 **全部权限** 的 APP Key 不额外限制接口范围，但仍受创建者当前角色权限约束
-- 选择 **自定义权限** 时，必须至少选择一个 API 权限点，APP Key 只能调用选中的接口范围
-- 操作超出 APP Key 权限范围或创建者角色权限时，将返回 `403` 状态码和 `AccessDenied` 错误
-- 建议为不同用途创建独立的 APP Key，遵循最小权限原则
+### 触发限制时
+
+请求返回 HTTP `429` 和错误码 `RequestTooFrequently`，响应头 `Flashcat-Request-Rate-Limit-Delay` 给出距当前窗口重置还有多少秒。请至少等待这么久再重试；没有该响应头时按指数退避（1 秒、2 秒、4 秒……）。
+
+<Warning>
+在循环里立即重试只会让窗口一直处于打满状态。批量任务请分散执行，并优先使用一次可传多个 ID 的接口，而不是逐个对象调用。
+</Warning>
 
 ---
 
-## 错误码列表
-
-| 错误码 | HTTP Status | 描述 |
-| --- | :---: | --- |
-| `InvalidParameter` | 400 | 参数错误，请检查请求参数是否正确 |
-| `InvalidContentType` | 400 | Content-Type 不支持，请使用 `application/json` |
-| `MethodNotAllowed` | 400 | HTTP Method 不支持 |
-| `Unauthorized` | 401 | 登录认证未通过，请检查 APP Key 是否正确 |
-| `AccessDenied` | 403 | 权限认证未通过，当前用户无此操作权限 |
-| `RouteNotFound` | 404 | 请求 Method + Path 未匹配，请检查 API 地址 |
-| `RequestTooFrequently` | 429 | 请求过于频繁，请稍后重试 |
-| `ResourceNotFound` | 400 | 账户未购买资源，请前往费用中心下单 |
-| `NoLicense` | 400 | 账户无充足订阅 License，请前往费用中心升级或购买订阅 |
-| `InternalError` | 500 | 内部或未知错误，请联系技术支持 |
+## 权限校验
+
+- **全部权限**的 APP Key 不额外限制接口范围，但仍受创建者当前角色权限约束。
+- **自定义权限**的 APP Key 只能调用选中的接口范围。
+- 超出 APP Key 权限范围或创建者角色权限的调用返回 HTTP `403` 和 `AccessDenied`。每个接口所需权限见其页面的 **限制说明**。
+- 部分接口还会校验对象级权限（例如只有协作空间所属团队的成员才能修改它），具体规则写在接口页面的 **使用说明** 中。
+- 建议按用途分别创建 APP Key，每个只授予所需的最小范围。
 
 ---
 
-## 错误处理建议
-
-<AccordionGroup>
-  <Accordion title="400 参数错误">
-    **可能原因**：
-    - 缺少必填参数
-    - 参数格式不正确
-    - Content-Type 未设置为 `application/json`
-    
-    **解决方案**：
-    检查请求参数和 Headers 设置，参考 API 文档确认参数要求。
-  </Accordion>
-
-  <Accordion title="401 认证失败">
-    **可能原因**：
-    - APP Key 未提供
-    - APP Key 不正确或已失效
-    
-    **解决方案**：
-    1. 确认请求 URL 中包含 `app_key` 参数
-    2. 前往控制台检查 APP Key 是否有效
-  </Accordion>
-
-  <Accordion title="403 权限不足">
-    **可能原因**：
-    - 当前用户无权执行此操作
-    - APP Key 对应用户权限不足
-    
-    **解决方案**：
-    联系账户管理员提升权限，或使用具有相应权限的 APP Key。
-  </Accordion>
-
-  <Accordion title="429 请求过频">
-    **可能原因**：
-    - 短时间内发送了过多请求
-    
-    **解决方案**：
-    1. 降低请求频率
-    2. 实现指数退避重试机制
-    3. 合并多个请求（如使用批量接口）
-  </Accordion>
-
-  <Accordion title="500 内部错误">
-    **可能原因**：
-    - 服务端内部异常
-    
-    **解决方案**：
-    1. 稍后重试
-    2. 如持续出现，请联系技术支持并提供 `request_id`
-  </Accordion>
-</AccordionGroup>
+## 错误码
+
+所有失败响应都使用 `{ "request_id": "…", "error": { "code": "…", "message": "…" } }` 结构。请以稳定的 `error.code` 做判断；`message` 会按语言变化，也可能调整措辞。
+
+| 错误码 | HTTP 状态码 | 含义 | 处理方式 |
+| --- | :---: | --- | --- |
+| `InvalidParameter` | 400 | 参数缺失、类型错误或未通过校验，`message` 通常会指出字段名。 | 修正请求，不要原样重试。 |
+| `BadRequest` | 400 | 请求违反业务规则，或与对象当前状态冲突，`message` 会说明原因。 | 根据 `message` 修正请求或对象状态。 |
+| `InvalidContentType` | 400 | 请求体没有以 `application/json` 发送。 | 设置 `Content-Type: application/json`。 |
+| `ResourceNotFound` | 400 | 引用的对象在本账户中不存在或已删除。注意返回 400 而不是 404。 | 检查 ID。 |
+| `ReferenceExist` | 400 | 对象仍被其他对象引用，无法删除。 | 先解除引用。 |
+| `NoLicense` | 400 | 账户套餐不包含该功能、套餐配额已用完、套餐已过期或额度不足。 | 在费用中心升级套餐、购买 License 或充值额度。 |
+| `Unauthorized` | 401 | APP Key 缺失、无效或已删除。 | 检查 `app_key` 参数或 `Fd-App-Key` 请求头。 |
+| `AccessDenied` | 403 | APP Key 的权限范围或创建者角色不允许该操作或该对象。 | 授予权限或换用其他 APP Key。 |
+| `RouteNotFound` | 404 | 没有与该方法和路径匹配的接口。 | 对照接口页面检查路径和 HTTP 方法。 |
+| `MethodNotAllowed` | 405 | 路径存在，但不支持该 HTTP 方法。 | 使用接口页面标注的方法。 |
+| `EntityTooLarge` | 413 | 请求体超出大小限制。 | 减少单次请求的数据量。 |
+| `RequestTooFrequently` | 429 | 触发频率限制。 | 等待 `Flashcat-Request-Rate-Limit-Delay` 秒后重试。 |
+| `InternalError` | 500 | 服务端意外错误。 | 退避后重试；持续出现请携带 `request_id` 联系技术支持。 |
+| `ServiceUnavailable` | 503 | 后端依赖过载或不可用。 | 退避后重试。 |
+
+API 参考中 `ErrorCode` 枚举的其他取值（`RequestVerifyRequired`、`DangerousOperation`、`RequestLocked`、`BalanceNotEnough`、`UndonedOrderExist`）只用于 MFA、计费等控制台流程，Open API 接口不会返回。
 
 ---
 
-## 最佳实践
+## 重试建议
 
-- **实现重试机制**：对于网络错误和 5xx 错误，建议实现指数退避重试，初始间隔 1 秒，最大重试 3 次。
-- **记录 request_id**：保存每次请求返回的 `request_id`，便于问题排查和技术支持。
-- **保护 APP Key**：不要在客户端代码中硬编码 APP Key，建议通过环境变量或配置中心管理。
-- **定期轮换密钥**：定期更换 APP Key，及时删除不再使用的密钥，降低泄露风险。
+- **只重试** `429`、`500`、`503` 和网络错误，使用指数退避（从 1 秒开始，最多重试 3 次）。`429` 请遵循 `Flashcat-Request-Rate-Limit-Delay`。
+- **不要原样重试**其他 `4xx` 错误，结果不会改变。
+- **创建类接口按非幂等处理。**创建请求超时后重试前，先通过列表或查询接口确认上一次是否已经成功。
+- **记录失败调用的 `request_id`**，技术支持需要它来定位请求。